نماذج الإصدارات باستخدام ميزة "الإعداد عن بُعد"


عند استخدام نماذج طلبات الخادم، يمكنك تعديل القيم ضمن نموذج معيّن بدون طرح إصدار جديد من تطبيقك. ومع ذلك، بما أنّ أي تغييرات في النموذج ستُستخدَم على الفور تقريبًا في الطلبات الواردة من تطبيقك، عليك توخي الحذر بشأن إجراء تغييرات قد تؤدي إلى تعطُّل تطبيقك أو إحداث تغييرات غير متوقّعة في سلوكه.

لذلك، إذا أردت إجراء تغييرات أكثر أهمية أو طرح التغييرات تدريجيًا، لن تحتاج إلى تغيير النموذج المستخدَم في رمز الإنتاج.

ننصحك بدلاً من ذلك باستخدام Firebase Remote Config من أجل التحكّم في قيمة رقم تعريف النموذج المستخدَم في الطلب المقدَّم إلى النموذج.

Firebase Remote Config يتيح لك تعديل قيم المَعلمات في تطبيقك (مثل رقم تعريف النموذج) ديناميكيًا وعن بُعد من Firebase وحدة تحكُّم، بدون الحاجة إلى طرح إصدار جديد من تطبيقك. ويتضمّن أيضًا إمكانات وعمليات دمج مبسطة لطرح التغييرات وإجراء اختبارات A/B.

يوضّح هذا الدليل كيفية دمج Remote Config في تطبيقك، وتحديدًا التحكّم في رقم تعريف النموذج المستخدَم في تطبيقك.

الخطوة 1: ضبط قيمة المَعلمة في Firebase وحدة التحكُّم

أنشئ نموذجًا لعميل Remote Config واضبط مَعلمة template_id وقيمتها لاسترجاعها واستخدامها في التطبيق.

  1. افتح مشروع Firebase في وحدة التحكُّم Firebase. بعد ذلك، من قائمة التنقّل، وسِّع تشغيل وانقر على Remote Config.

  2. تأكَّد من اختيار العميل من أداة اختيار العميل/الخادم في أعلى الصفحة.

  3. ابدأ نموذج عميل بالنقر على إنشاء إعداد (أو إضافة مَعلمة إذا كنت قد استخدمت نماذج العملاء من قبل).

  4. حدِّد المَعلمة template_id:

    اسم المَعلمة الوصف النوع القيمة التلقائية
    template_id رقم تعريف النموذج سلسلة my-first-template-v1-0-0
  5. بعد إضافة هذه المَعلمة، انقر على نشر التغييرات. إذا لم يكن هذا نموذجًا جديدًا لـ Remote Config، راجِع التغييرات وانقر على نشر التغييرات مرة أخرى.

الخطوة 2: إضافة Remote Config وتهيئته في تطبيقك

أضِف مكتبة Remote Config واضبط Remote Config داخل تطبيقك.

Swift

كجزء من Firebase AI Logic الإعداد، سبق لك إضافة حزمة تطوير البرامج (SDK) لمنصة Firebase إلى تطبيقك، ولكن ستحتاج أيضًا إلى إضافة Remote Config.

  1. في Xcode، افتح المشروع وانتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة.

  2. اختَر firebase-ios-sdk ، ثم انقر على إضافة حزمة.

  3. من "أداة التنقّل في المشروع"، اختَر تطبيقك > الأهداف > تطبيقك.

  4. من علامة التبويب الإعدادات العامة ، انتقِل إلى الأطر والمكتبات والمحتوى المضمّن.

  5. انقر على + واختَر FirebaseRemoteConfig، ثم انقر على إضافة.

  6. أضِف عملية استيراد FirebaseRemoteConfig إلى الرمز البرمجي:

    import FirebaseRemoteConfig
    
  7. داخل الفئة المناسبة لتطبيقك، ابدأ Firebase وأضِف Remote Config إلى منطق التطبيق الرئيسي.

    هنا، ستضمّن Remote Config و Remote Config متتبِّع الوقت الفعلي كعمليات استيراد لكي يتمكّن التطبيق من استرجاع القيم الجديدة في الوقت الفعلي، وأضِف أقل فترة زمنية للاسترجاع:

    let remoteConfig = RemoteConfig.remoteConfig()
    let settings = RemoteConfigSettings()
    settings.minimumFetchInterval = 3600
    remoteConfig.configSettings = settings
    

Kotlin

  1. أضِف اعتمادية Remote Config إلى ملف Gradle للوحدة (على مستوى التطبيق)، وعادةً يكون app/build.gradle.kts أو app/build.gradle:

    dependencies {
        implementation(platform("com.google.firebase:firebase-bom:34.13.0"))
        implementation("com.google.firebase:firebase-ai")
        implementation("com.google.firebase:firebase-config")
        // ... other dependencies
    }
    
  2. أضِف Remote Config إلى منطق التطبيق الرئيسي. هنا، ستبدأ تهيئة Remote Config وأضِف أقل فترة زمنية للاسترجاع:

    val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
    val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
    }
    remoteConfig.setConfigSettingsAsync(configSettings)
    

Java

  1. أضِف اعتمادية Remote Config إلى ملف Gradle للوحدة (على مستوى التطبيق)، وعادةً يكون app/build.gradle.kts أو app/build.gradle:

    dependencies {
        implementation(platform("com.google.firebase:firebase-bom:34.13.0"))
        implementation("com.google.firebase:firebase-ai")
        implementation("com.google.firebase:firebase-config")
        // ... other dependencies
    }
    
  2. أضِف Remote Config إلى منطق التطبيق الرئيسي. هنا، ستبدأ تهيئة Remote Config وأضِف أقل فترة زمنية للاسترجاع:

    FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
    FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
    mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
    

Web

  1. افتح الرمز البرمجي في محرِّر نصوص واستورِد Remote Config

    import { getRemoteConfig } from 'firebase/remote-config';
    
  2. داخل وظيفتك الأساسية وبعد بدء تشغيل تطبيق Firebase لـ Firebase AI Logic SDK، ابدأ Remote Config

      // Initialize Remote Config and get a reference to the service
      const remoteConfig = getRemoteConfig(app);
    
  3. اضبط أقل فترة زمنية للاسترجاع:

    remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
    

Dart

  1. من دليل مشروع Flutter، ثبِّت Remote Config باستخدام الأمر التالي:

    flutter pub add firebase_remote_config
    
  2. افتح ./lib/main.dart وأضِف عملية الاستيراد بعد عمليات الاستيراد الأخرى التي أضفتها لدعم Firebase AI Logic

    import 'package:firebase_vertexai/firebase_ai.dart';
    import 'package:firebase_core/firebase_core.dart';
    import 'package:firebase_remote_config/firebase_remote_config.dart';
    
  3. أضِف المتغيّر _modelName إلى تطبيقك لكي تتمكّن من استخدامه لاحقًا:

    late final String _modelName;
    late final String _systemInstructions;
    late final String _prompt;
    
  4. احصل على النسخة الافتراضية لعنصر Remote Config وحدِّد أقل فترة زمنية للاسترجاع من أجل السماح بإعادة التحميل بشكل متكرّر. احرص على إضافة ذلك بعد بدء Firebase.

      final remoteConfig = FirebaseRemoteConfig.instance;
      await remoteConfig.setConfigSettings(RemoteConfigSettings(
        fetchTimeout: const Duration(seconds: 3600),
        minimumFetchInterval: const Duration(seconds: 3600),
      ));
    

Unity

  1. أضِف Remote Config إلى مشروع Unity باتّباع هذه التعليمات.

  2. احصل على النسخة الافتراضية لعنصر Remote Config وحدِّد أقل فترة زمنية للاسترجاع من أجل السماح بإعادة التحميل بشكل متكرّر. احرص على إضافة ذلك بعد بدء Firebase.

    var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
    const int MillisecondsPerSecond = 1000;
    await remoteConfig.SetConfigSettingsAsync(new ConfigSettings() {
      FetchTimeoutInMilliseconds = 3600 * MillisecondsPerSecond,
      MinimumFetchIntervalInMilliseconds = 3600 * MillisecondsPerSecond
    });
    

الخطوة 3: ضبط قيمة المَعلمة داخل التطبيق

عليك ضبط قيم المَعلمات التلقائية داخل التطبيق في عنصر Remote Config. يضمن ذلك أن يعمل تطبيقك على النحو المتوقّع حتى إذا لم يتمكّن من استرجاع القيم من خدمة Remote Config

Swift

  1. في وحدة تحكُّم Firebase، افتح Remote Config.

  2. في علامة التبويب المَعلمات، افتح القائمة، وانقر على تنزيل القيم التلقائية.

  3. عندما يُطلب منك ذلك، فعِّل ملف ‎.plist لنظام التشغيل iOS، ثم انقر على تنزيل الملف.

  4. احفظ الملف في دليل تطبيقك.

  5. في Xcode، انقر بزر الماوس الأيمن على تطبيقك واختَر إضافة ملفات

  6. اختَر remote_config_defaults.plist، ثم انقر على إضافة.

  7. عدِّل رمز تطبيقك للإشارة إلى الملف التلقائي:

    // Set default values for Remote Config parameters.
    remoteConfig.setDefaults(fromPlist: "remote_config_defaults")
    

Kotlin

  1. من وحدة التحكّم Firebase، افتح Remote Config.

  2. في علامة التبويب المَعلمات ، افتح القائمة، وانقر على تنزيل القيم التلقائية.

  3. عندما يُطلب منك ذلك، فعِّل ملف ‎.xml لنظام التشغيل Android، ثم انقر على تنزيل الملف.

  4. احفظ الملف في دليل موارد XML لتطبيقك.

  5. عدِّل ملف النشاط الرئيسي لإضافة الإعدادات التلقائية بعد configSettings التي أضفتها سابقًا:

    // Set default values for Remote Config parameters.
    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)
    

Java

  1. في وحدة تحكُّم Firebase، افتح Remote Config.

  2. في علامة التبويب المَعلمات ، افتح القائمة، وانقر على تنزيل القيم التلقائية.

  3. عندما يُطلب منك ذلك، فعِّل ملف ‎.xml لنظام التشغيل Android، ثم انقر على تنزيل الملف.

  4. احفظ الملف في دليل موارد XML لتطبيقك.

  5. عدِّل ملف النشاط الرئيسي لإضافة الإعدادات التلقائية بعد configSettings التي أضفتها سابقًا:

    // Set default values for Remote Config parameters.
    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);
    

Web

يمكنك ضبط القيمة التلقائية لاسم النموذج مباشرةً في الرمز البرمجي:

// Set default values for Remote Config parameters.
remoteConfig.defaultConfig = {
  template_id: 'my-first-template-v1-0-0',
};

Dart

يمكنك ضبط القيمة التلقائية لاسم النموذج مباشرةً في الرمز البرمجي:

// Set default values for Remote Config parameters.
remoteConfig.setDefaults(const {
  "template_id": "my-first-template-v1-0-0"
});

Unity

يمكنك ضبط القيمة التلقائية لاسم النموذج مباشرةً في الرمز البرمجي:

// Set default values for Remote Config parameters.
await remoteConfig.SetDefaultsAsync(
  new System.Collections.Generic.Dictionary<string, object>() {
    { "template_id", "my-first-template-v1-0-0" }
  }
);

الخطوة 4: استرجاع القيمة وتفعيلها

بعد ضبط القيمة التلقائية لاسم النموذج، أضِف ما يلي لاسترجاع القيم وتفعيلها.

Swift

// Fetch and activate Remote Config values
remoteConfig.fetchAndActivate { status, error in
  if let error = error {
    print("Error fetching Remote Config: \(error.localizedDescription)")
  }
}

يجب أن يؤدي ذلك إلى تعديل عنصر Remote Config كلما تم نشر نموذج جديد لـ Remote Config.

Kotlin

// Fetch and activate Remote Config values
remoteConfig.fetchAndActivate()
      .addOnCompleteListener(this) { task ->
          if (task.isSuccessful) {
              val updated = task.result
              Log.d(TAG, "Remote Config values fetched and activated: $updated")
          } else {
              Log.e(TAG, "Error fetching Remote Config", task.exception)
          }
      }

Java

  // Fetch and activate Remote Config values
  mFirebaseRemoteConfig.fetchAndActivate()
    .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
        @Override
        public void onComplete(@NonNull Task<Boolean> task) {
            if (task.isSuccessful()) {
                boolean updated = task.getResult();
                Log.d(TAG, "Config params updated: " + updated);
            } else {
                Log.e(TAG, "Error fetching Remote Config", task.exception)
            }
          }
    });

Web

  1. أضِف getValue وfetchAndActivate إلى عمليات الاستيراد:

    import { getValue, fetchAndActivate } from 'firebase/remote-config';
    
  2. حدِّد موقع الرمز البرمجي الذي تحدِّد فيه القيمة التلقائية لاسم النموذج. بعد مجموعة الرموز البرمجية مباشرةً، أضِف الرمز البرمجي التالي لاسترجاع الإعداد وتفعيله وتعيين القيمة المسترجَعة للثابت templateID.

    // Fetch and activate Remote Config.
    try {
      await fetchAndActivate(remoteConfig);
    } catch(err) {
      console.error('Remote Config fetch failed', err);
    }
    
    console.log('Remote Config fetched.');
    
    // Assign Remote Config values.
    const templateID = getValue(remoteConfig, 'template_id').asString();
    

Dart

// Fetch and activate Remote Config.
remoteConfig.fetchAndActivate();

// Assign Remote Config values.
String? _templateID = remoteConfig.getString("template_id");

Unity

// Fetch and activate Remote Config values.
await remoteConfig.FetchAndActivateAsync();

الخطوة 5: إضافة مستمع في الوقت الفعلي لـ Remote Config

أضِف مستمعًا في الوقت الفعلي Remote Config إلى تطبيقك لضمان نشر التغييرات التي تجريها على النموذج Remote Config إلى العميل فور تعديلها.

يعدِّل الرمز البرمجي التالي عنصر Remote Config كلما تغيّرت قيمة مَعلمة.

Swift

// Add real-time Remote Config
remoteConfig.addOnConfigUpdateListener { configUpdate, error in
  guard let configUpdate = configUpdate, error == nil else {
    print("Error listening for config updates: \(error?.localizedDescription ?? "No error available")")
    return
  }

  print("Updated keys: \(configUpdate.updatedKeys)")
  remoteConfig.activate { changed, error in
    guard error == nil else {
      print("Error activating config: \(error?.localizedDescription ?? "No error available")")
      return
    }
    print("Activated config successfully")
  }
}

Kotlin

يمكنك أيضًا اختياريًا ضبط إجراء داخل عملية تفعيل addOnCompleteListener:

      // Add a real-time Remote Config listener
      remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener {
          override fun onUpdate(configUpdate : ConfigUpdate) {
              Log.d(ContentValues.TAG, "Updated keys: " + configUpdate.updatedKeys);
              remoteConfig.activate().addOnCompleteListener {
                  // Optionally, add an action to perform on update here.
              }
          }

          override fun onError(error : FirebaseRemoteConfigException) {
              Log.w(ContentValues.TAG, "Config update error with code: " + error.code, error)
          }
      }

Java

يمكنك أيضًا اختياريًا ضبط إجراء داخل عملية تفعيل addOnCompleteListener:

  // Add a real-time Remote Config listener
  remoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() {
      @Override
      public void onUpdate(ConfigUpdate configUpdate) {
          Log.d(ContentValues.TAG, "Updated keys: " + configUpdate.getUpdatedKeys());
                remoteConfig.activate().addOnCompleteListener(new OnCompleteListener<Boolean>() {
                  @Override
                  public void onComplete(@NonNull Task<Boolean> task) {
                      // Optionally, add an action to perform on update here.
                  }
              });
          }

      @Override
      public void onError(FirebaseRemoteConfigException error) {
          Log.w(ContentValues.TAG, "Config update error with code: " + error.getCode(), error);
      }
  });

Web

 // Add a real-time Remote Config listener
 onConfigUpdate(remoteConfig, {
   next: (configUpdate) => {
      console.log("Updated keys:", configUpdate.getUpdatedKeys());
      if (configUpdate.getUpdatedKeys().has("welcome_message")) {
         activate(remoteConfig).then(() => {
         showWelcomeMessage();
         });
      }
   },
   error: (error) => {
      console.log("Config update error:", error);
   },
   complete: () => {
      console.log("Listening stopped.");
   }
});

Dart

// Add a real-time Remote Config listener
remoteConfig.onConfigUpdated.listen((event) async {
  await remoteConfig.activate();
});

Unity

// Add a real-time Remote Config listener to automatically update whenever
// a new template is published.
// Note: the parameters can be anonymous as they are unused.

remoteConfig.OnConfigUpdateListener += (_, _) => {
  remoteConfig.ActivateAsync();
};

الخطوة 6: تعديل طلبات Gemini API لاستخدام قيمة Remote Config

انقر على موفّر Gemini API لعرض المحتوى والرمز البرمجي الخاصَّين بالموفّر على هذه الصفحة.

بعد ضبط Remote Config بالكامل، عدِّل الرمز البرمجي لاستبدال القيم المرمّزة بقيم مصدرها Remote Config.

Swift

import FirebaseAI

let templateID = remoteConfig.configValue(forKey: "template_id").stringValue
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()
let customerName = "Jane"

// When making the `generateContent` call, source the template ID value from Remote Config
let response = try await model.generateContent(
  templateID: templateID,
  // Provide the values for any input variables required by your template.
  inputs: [
    "customerName": customerName
  ]
)

// ...

Kotlin

// ...

val model = Firebase.ai(backend = GenerativeBackend.googleAI()).templateGenerativeModel()
val customerName = "Jane"

// When making the `generateContent` call, source the template ID value from Remote Config
val response = model.generateContent(
  remoteConfig.getString("template_id"),
  // Provide the values for any input variables required by your template.
  mapOf(
    "customerName" to customerName
  )
)

val text = response.text
println(text)

Java

// ...

TemplateGenerativeModel ai = FirebaseAI.getInstance()
    .templateGenerativeModel(null /* Request Options */);

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(ai);
String customerName = "Jane";

// When making the `generateContent` call, source the template ID value from Remote Config
Future<GenerateContentResponse> response = model.generateContent(
    remoteConfig.getString("template_id"),
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)

);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

// ...

Web

// ...

const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

const model = getTemplateGenerativeModel(ai);
const templateID = getValue(remoteConfig, 'template_id').asString();
const customerName = 'Jane';

// When making the `generateContent` call, source the template ID value from Remote Config
const result = await model.generateContent(
  templateID,
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

// ...

Dart

// ...

final model = FirebaseAI.googleAI().templateGenerativeModel();

final templateID = remoteConfig.getString("template_id");
final customerName = 'Jane';

// When making the `generateContent` call, source the template ID value from Remote Config
var response = await model.generateContent(
  templateID,
  // Provide the values for any input variables required by your template
  inputs: {
    'customerName': customerName,
  },
);

// ...

Unity

// ...

var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

var templateID = remoteConfig.GetValue("template_id").StringValue;
var model = ai.GetTemplateGenerativeModel();
var customerName = "Jane";

try
{
    // When making the `generateContent` call, source the template ID value from Remote Config
    var response = await model.GenerateContentAsync(
        templateID,
        // Provide the values for any input variables required by your template
        new Dictionary<string, object>
        {
            { "customerName", customerName },
        }
    );
    Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e)
{
    Debug.LogError($"An error occurred: {e.Message}");
}

// ...

الخطوة 7: تشغيل التطبيق

أنشئ التطبيق وشغِّله وتأكَّد من أنّه يعمل. أجرِ تغييرات على إعداداتك من صفحة "Remote Config" في "Firebase"، وانشر التغييرات، وتأكَّد من النتيجة.

الخطوات التالية

  • مزيد من المعلومات عن تنفيذ حالات استخدام أخرى لـ و Remote ConfigFirebase AI Logic.

  • بالنسبة إلى التطبيقات والألعاب على الأجهزة الجوّالة:

    • اختبِر تغييرات النموذج باستخدام Remote Config و A/B Testing.

    • اطرح التغييرات تدريجيًا باستخدام Remote Config عمليات طرح (على نظامَي التشغيل iOS+ وAndroid فقط).

    • استخدِم Remote Config ميزة التخصيص لاستخدام تعلُّم الآلة من أجل تحديد أفضل الإعدادات للمستخدمين الأفراد (على نظام التشغيل iOS+ وAndroid وUnity فقط).