استخدام ميزة "الإعداد عن بُعد" في بيئات الخادم

تتيح منصة "Firebase Remote Config" ضبط الإعدادات من جهة الخادم باستخدام حِزم SDK الخاصة بمدير Firebase لكل من Node.js (الإصدار 12.1.0 أو أحدث) وPython (الإصدار 6.7.0 أو أحدث) وJava (الإصدار 9.7.0 أو أحدث) وGo (الإصدار 4.17.0 أو أحدث).

تتيح لك هذه الميزة إدارة سلوك وإعدادات التطبيقات من جهة الخادم بشكل ديناميكي باستخدام Remote Config. ويشمل ذلك عمليات التنفيذ بدون خادم، مثل Cloud Functions for Firebase والخدمات المستندة إلى حاويات على Cloud Run.

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

باستخدام Remote Config من جهة الخادم، يمكنك إجراء ما يلي:

  • حدِّد مَعلمات الإعداد عن بُعد للتطبيقات التي تعمل على خادمك أو التي يتم الوصول إليها من خلاله، ما يتيح حالات استخدام مثل ضبط مَعلمات نماذج الذكاء الاصطناعي والطلبات وعمليات الدمج الأخرى عن بُعد، لضمان بقاء مفاتيح واجهة برمجة التطبيقات آمنة.
  • ضبط المَعلمات ديناميكيًا استجابةً للتغييرات في بيئتك أو تغييرات التطبيقات الأخرى، مثل تعديل مَعلمات النماذج اللغوية الكبيرة ونقاط نهاية النماذج
  • يمكنك التحكّم في التكاليف من خلال تعديل واجهات برمجة التطبيقات التي يطلبها خادمك عن بُعد.
  • يمكنك إنشاء إعدادات مخصّصة بشكل فوري للعملاء الذين يصلون إلى خادمك.
  • تسجيل العملاء الذين تلقّوا قيمة مَعلمة واستخدامها في Cloud Functions for Firebase كجزء من نظام التحقّق من الأذونات

يمكنك نشر Remote Config من جهة الخادم على Cloud Run أو Cloud Functions for Firebase أو بيئات الخوادم المستضافة ذاتيًا.

قبل البدء

اتّبِع التعليمات الواردة في مقالة إضافة حزمة تطوير البرامج (SDK) لمشرف Firebase إلى خادمك لإنشاء مشروع على Firebase وإعداد حساب خدمة وإضافة حزمة تطوير البرامج (SDK) لمشرف Firebase إلى خادمك. تأكَّد من استخدام إصدار متوافق من Admin SDK لمنصتك:

  • ‫Node.js: الإصدار 12.1.0 أو إصدار أحدث من حزمة Firebase Admin Node.js SDK
  • ‫Python: الإصدار 6.7.0 من حزمة تطوير البرامج (SDK) لمشرف Firebase بلغة Python أو إصدار أحدث
  • ‫Java: الإصدار 9.7.0 من حزمة تطوير البرامج (SDK) لمشرف Firebase على Java أو إصدار أحدث
  • ‫Go: الإصدار 4.17.0 من حزمة Firebase Admin Go SDK أو إصدار أحدث

الخطوة 1: إعداد "مدير SDK في Firebase" وتفويض طلبات البيانات من واجهة برمجة التطبيقات

عند إعداد حزمة SDK للمشرف بدون مَعلمات، تستخدم حزمة SDK بيانات الاعتماد التلقائية لتطبيق Google وتقرأ الخيارات من متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS. ابدأ حزمة تطوير البرامج (SDK) واضبط Remote Config لمنصتك:

Node.js

استورِد initializeApp وgetRemoteConfig، ثم ابدأ مثيل تطبيق Firebase:

import { initializeApp } from "firebase-admin/app";
import { getRemoteConfig } from "firebase-admin/remote-config";

// Initialize Firebase
const firebaseApp = initializeApp();

Python

استورِد firebase_admin (مع asyncio وjson لتحميل النماذج غير المتزامن وتحليل JSON)، ثم ابدأ التطبيق:

import firebase_admin
import asyncio
import json

firebase_admin.initialize_app()

Java

ابدأ إعداد حزمة تطوير البرامج (SDK) لمشرف Firebase باستخدام FirebaseOptions وبيانات اعتماد حساب الخدمة:

// Initialize the Firebase Admin SDK
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
    .build();
FirebaseApp.initializeApp(options);

متابعة

ابدأ تطبيق Firebase وأنشئ مثيل عميل RemoteConfig:

ctx := context.Background()

// Initialize Firebase
app, err := firebase.NewApp(ctx, nil)
if err != nil {
    log.Fatalln("Error initializing app:", err)
}

remoteConfig, err := app.RemoteConfig(ctx)
if err != nil {
    log.Fatalln("Error initializing remote config client:", err)
}

الخطوة 2: تحديد قيم المَعلمات التلقائية لتطبيق الخادم

حدِّد المتغيّرات في تطبيقك التي تريد تعديلها ديناميكيًا باستخدام Remote Config. بعد ذلك، فكِّر في المتغيّرات التي يجب ضبطها تلقائيًا في تطبيقك وما يجب أن تكون قيمها التلقائية. يضمن ذلك تشغيل تطبيقك بنجاح حتى في حال انقطاع اتصاله بخادم الخلفية في Remote Config.

على سبيل المثال، إذا كنت تكتب تطبيق خادم يدير دالة ذكاء اصطناعي توليدي، يمكنك ضبط اسم نموذج تلقائي ومقدمة طلب وإعدادات ذكاء اصطناعي توليدي، مثل ما يلي:

اسم المَعلمة الوصف النوع القيمة التلقائية
model_name اسم واجهة برمجة التطبيقات للنموذج سلسلة gemini-2.0-flash
preamble_prompt الطلب الذي يجب إضافته إلى بداية طلب بحث المستخدم سلسلة I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
generation_config المَعلمات المطلوب إرسالها إلى النموذج JSON {"stopSequences": ["I hope this helps"], "temperature": 0.7, "maxOutputTokens": 512, "topP": 0.1, "topK": 20}

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

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

  1. الوصول إلى نموذج خادم Remote Config وتحميله

    Node.js

    ابدأ بإعداد نموذج الخادم باستخدام initServerTemplate() واستدعِ load() لجلب النموذج من الخلفية:

    // Initialize server-side Remote Config
const rc = getRemoteConfig(firebaseApp);
const template = rc.initServerTemplate();

// Load Remote Config
await template.load();

    إذا كنت تستخدم Node.js ضمن Cloud Functions for Firebase، يمكنك استخدام دالة getServerTemplate() غير المتزامنة لإعداد النموذج وتحميله في خطوة واحدة:

    // Initialize server-side Remote Config
const rc = getRemoteConfig(firebaseApp);
const template = await rc.getServerTemplate();

    Python

    ابدأ بإعداد نموذج الخادم باستخدام init_server_template() واستدعِ load() لجلب النموذج من الخلفية:

    from firebase_admin import remote_config

# Initialize server-side Remote Config
template = remote_config.init_server_template()

# Load the template from the backend
asyncio.run(template.load())

    بدلاً من ذلك، إذا كنت تستخدم Python مع Cloud Functions for Firebase، يمكنك استخدام دالة get_server_template() غير المتزامنة لإعداد النموذج وتحميله في خطوة واحدة:

    # Initialize server-side Remote Config
template = await remote_config.get_server_template()

    Java

    ابدأ عملية إعداد عميل Remote Config من جهة الخادم باستخدام FirebaseRemoteConfig.getInstance():

    // Initialize server-side Remote Config client
FirebaseRemoteConfig rc = FirebaseRemoteConfig.getInstance();

    بدلاً من ذلك، إذا كنت تستخدم Java مع Cloud Functions for Firebase، يمكنك استخدام getServerTemplate() لإعداد النموذج وتحميله في خطوة واحدة:

    ServerTemplate template = rc.getServerTemplate();

    متابعة

    ابدأ بإعداد نموذج الخادم باستخدام InitServerTemplate() واستدعِ Load() لجلب النموذج من الخلفية:

    // Initialize server-side Remote Config
defaultConfig := make(map[string]any)
templateDataJSON := ""
template, err := remoteConfig.InitServerTemplate(defaultConfig, templateDataJSON)
if err != nil {
    log.Fatalln("Error initializing server template:", err)
}

// Load Remote Config
err = template.Load(ctx)
if err != nil {
    log.Fatalln("Error fetching server template:", err)
}

    هناك طريقة أخرى يمكنك من خلالها إعداد النموذج، وهي استخدام الدالة GetServerTemplate لاسترداد نموذج الخادم المطلوب. يمكنك تحويل هذا النموذج إلى تنسيق JSON يمكن تخزينه محليًا، ثم بدء نموذج JSON هذا باستخدام الدالة InitServerTemplate.

  2. لضمان تشغيل تطبيقك بنجاح حتى في حال انقطاع اتصاله بخادم الخلفية في Remote Config، أضِف قيمًا تلقائية لكل مَعلمة في تطبيقك.

    Node.js

    أضِف عنصر defaultConfig داخل دالة النموذج initServerTemplate أو getServerTemplate:

    const template = rc.initServerTemplate({
  defaultConfig: {
    model_name: "gemini-pro",
    generation_config: '{"stopSequences": [], "temperature": 0.7, "maxOutputTokens": 512, "topP": 0.1, "topK": 20}',
    preamble_prompt: "I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!"
  },
});

// Load Remote Config
await template.load();

    Python

    أضِف قاموس default_config داخل دالة النموذج init_server_template أو get_server_template:

    template = remote_config.init_server_template({
  'default_config': {
    'model_name': "gemini-pro",
    'generation_config': '{"stopSequences": [], "temperature": 0.7, "maxOutputTokens": 512, "topP": 0.1, "topK": 20}',
    'preamble_prompt': "I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!"
  },
})

# Load Remote Config
asyncio.run(template.load())

    هناك طريقة أخرى يمكنك من خلالها إعداد نموذج، وهي استخدام الدالة get_server_template لاسترداد نموذج الخادم المطلوب. يمكنك تحويل هذا النموذج إلى تنسيق JSON باستخدام الدالة template.to_json. يمكن تخزين نموذج JSON هذا محليًا، ويمكنك بعد ذلك إعداد نموذج JSON هذا باستخدام دالة init_server_template.

    Java

    أضِف عنصر defaultConfig باستخدام KeysAndValues داخل دالة getServerTemplate:

    // Initialize default config using KeysAndValues
KeysAndValues defaultConfig = new KeysAndValues.Builder()
                                  .put("rc_param_1", "default value 1")
                                  .put("rc_param_2", "default value 2")
                                  .build();
ServerTemplate template = rc.getServerTemplate(defaultConfig);

    يمكنك بدلاً من ذلك تمرير نموذج مخزَّن مؤقتًا تلقائيًا أثناء إعداد Remote Config، والذي يمكن استخدامه حتى في حال انقطاع الاتصال بخادم Remote Config:

    String templateDataJSON = "{}"; // add your default template as JSON
ServerTemplate template = rc.serverTemplateBuilder()
                    .defaultConfig(defaultConfig)
                    .cachedTemplate(templateDataJSON)
                    .build();

    متابعة

    أضِف خريطة defaultConfig داخل دالة النموذج InitServerTemplate أو GetServerTemplate:

    // Initialize server-side Remote Config
defaultConfig := make(map[string]any)
defaultConfig["model_name"] = "gemini-2.0-flash"

// Assume the type generationConfig has been defined
defaultConfig["generation_config"] = &generationConfig{
    StopSequences:   []string{"I hope this helps"},
    Temperature:     0.7,
    MaxOutputTokens: 512,
    TopP:            0.9,
    TopK:            30,
}

defaultConfig["preamble_prompt"] = "I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!"

templateDataJSON := ""
template, err := remoteConfig.InitServerTemplate(defaultConfig, templateDataJSON)
if err != nil {
    log.Fatalln("Error initializing server template:", err)
}

// Load Remote Config
err = template.Load(ctx)
if err != nil {
    log.Fatalln("Error fetching server template:", err)
}

  3. بعد تحميل النموذج، قيِّم النموذج لاستيراد المَعلمات والقيم منه:

    Node.js

    استخدام template.evaluate():

    // Add template parameters to config
const config = template.evaluate();

    Python

    استخدام template.evaluate():

    # Add template parameters to config
config = template.evaluate()

    Java

    استخدام template.evaluate():

    // Add template parameters to config
ServerConfig config = template.evaluate();

    متابعة

    استخدِم template.Evaluate() مع سياق تقييم فارغ في حال عدم تطبيق أي شروط:

    // An empty evaluation context means no conditions are applied.
evaluationContext := make(map[string]any)
config, err := template.Evaluate(evaluationContext)
if err != nil {
    log.Fatalln("Error evaluating template:", err)
}

  4. يمكنك اختياريًا تحديد قيم السياق التي تريدها إذا ضبطت الشروط في نموذج Remote Config:

    • في حال استخدام شروط النسبة المئوية، أضِف معرّف التوزيع العشوائي (randomizationId أو randomization_id أو randomizationID) الذي تريد استخدامه لتقييم شروطك ضمن دالة تقييم النموذج.
    • في حال استخدام الإشارات المخصّصة، حدِّد السمات وقيمها. تتوفّر الإشارات المخصّصة في الإصدار 12.5.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لـ Node.js في "مدير Firebase"، والإصدار 6.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لـ Python، والإصدار 9.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لـ Java، والإصدار 4.17.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لـ Go.

    على سبيل المثال، يمكنك ضبط رقم تعريف تثبيت Firebase أو رقم تعريف المستخدم كرقم تعريف عشوائي لضمان إضافة كل مستخدم يتصل بخادمك إلى المجموعة العشوائية المناسبة، وversion كإشارة مخصّصة لاستهداف إصدارات برامج عملاء معيّنة، وplatform كإشارة مخصّصة لاستهداف الأنظمة الأساسية لبرامج العملاء.

    لمزيد من المعلومات حول الشروط، يُرجى الاطّلاع على أنواع قواعد الشروط.

    Node.js

    يجب تمرير عنصر سياق تقييم يحتوي على randomizationId وأي إشارات مخصّصة إلى template.evaluate():

    // Add template parameters to `config`. Evaluates the
// template and returns the parameter value assigned to
// the group assigned to the {randomizationId} and version.
const config = template.evaluate({
  randomizationId: "2ac93c28-c459-4760-963d-a3974ec26c04",
  version: "1.0",
  platform: "Android"
});

    Python

    مرِّر قاموسًا يحتوي على randomization_id وأي إشارات مخصّصة إلى template.evaluate():

    # Add template parameters to `config`. Evaluates the
# template and returns the parameter value assigned to
# the group assigned to the {randomization_id} and version.
config = template.evaluate({
  'randomization_id': "2ac93c28-c459-4760-963d-a3974ec26c04",
  'version': "1.0",
  'platform': "Android"
})

    Java

    أنشئ سياق KeysAndValues يحتوي على randomizationId وأي إشارات مخصّصة، ثم مرِّره إلى template.evaluate():

    // Add custom signals and randomizationId
KeysAndValues context = new KeysAndValues.Builder()
                                .put("custom_signal_key", "99")
                                .put("randomizationId", "2ac93c28")
                                .build();

// Evaluate the template with signals
ServerConfig config = template.evaluate(context);

    متابعة

    يجب تمرير خريطة سياق تقييم تحتوي على randomizationID وأي إشارات مخصّصة إلى template.Evaluate():

    // Add template parameters to `config`. Evaluates the
// template and returns the parameter value assigned to
// the group assigned to the {randomizationID}, version, and platform.
evaluationContext := make(map[string]any)
evaluationContext["randomizationID"] = "2ac93c28-c459-4760-963d-a3974ec26c04"
evaluationContext["version"] = "1.0"
evaluationContext["platform"] = "Android"

config, err := template.Evaluate(evaluationContext)
if err != nil {
    log.Fatalln("Error evaluating template:", err)
}

  5. بعد ذلك، استخرِج قيم المَعلمات التي تحتاج إليها من عنصر الإعدادات الذي تم تقييمه. استخدِم طرق getter لتحويل القيم من Remote Config إلى التنسيق المتوقّع.

    على سبيل المثال، إذا كنت تنفّذ Agent Platform على خادمك وتريد تغيير النموذج ومَعلماته، يمكنك ضبط مَعلمات model_name وgeneration_config. في ما يلي طرق الحصول على البيانات المتاحة ومثال على كيفية الوصول إلى قيم Remote Config لكل نظام أساسي:

    Node.js

    طرق الحصول على البيانات المتوافقة:

    • قيمة منطقية: getBoolean
    • الكائن: getValue
    • الرقم: getNumber
    • السلسلة: getString

    // Replace defaults with values from Remote Config.
const generationConfig =
  JSON.parse(
    config.getString('generation_config'));

const is_ai_enabled = config.getBoolean('is_ai_enabled');

const model = config.getString('model_name');

// Generates a prompt comprised of the Remote Config
// parameter and prepends it to the user prompt
const prompt = `${config.getString('preamble_prompt')} ${req.query.prompt}`;

    Python

    طرق الحصول على البيانات المتوافقة:

    • قيمة منطقية: get_bool
    • عدد صحيح: get_int
    • التعويم: get_float
    • السلسلة: get_string
    • مصدر القيمة: get_value_source

    # Replace defaults with values from Remote Config.
generation_config = json.loads(config.get_string('generation_config'))
is_ai_enabled = config.get_bool('is_ai_enabled')
model = config.get_string('model_name')

# Generates a prompt comprised of the Remote Config
# parameter and prepends it to the user prompt.
prompt = f"{config.get_string('preamble_prompt')}{req.args.get('prompt')}"

    Java

    طرق الحصول على البيانات المتوافقة:

    • قيمة منطقية: getBoolean
    • السلسلة: getString
    • غرفة مزدوجة: getDouble
    • تنسيق التاريخ الطويل: getLong
    • مصدر القيمة: getValueSource

    // Get the model name
String modelName = config.getString("model_name");
// Get the origin of value assigned to param
ValueSource modelNameSource = config.getValueSource("model_name");

    تعرض الطريقة getValueSource قيمة ValueSource تشير إلى ما إذا كان مصدر قيمة المَعلمة هو STATIC أو REMOTE أو DEFAULT.

    متابعة

    طرق الحصول على البيانات المتوافقة:

    • قيمة منطقية: GetBoolean
    • عدد صحيح: GetInt
    • التعويم: GetFloat
    • السلسلة: GetString
    • مصدر القيمة: GetValueSource

    // Replace defaults with values from Remote Config.

// Assume the type generationConfig has been defined
var genConfig generationConfig
err = json.Unmarshal([]byte(config.GetString("generation_config")), &genConfig)
if err != nil {
    log.Fatalln("Error unmarshaling generation config:", err)
}
model := config.GetString("model_name")

// Parameter created on the console
isAIEnabled := config.GetBoolean("is_ai_enabled")

// Generates a prompt comprised of the Remote Config
// parameter and prepends it to the user prompt (assume it is extracted from the request body)
userPrompt := "What is Remote Config?"
prompt := fmt.Sprintf("%s %s", config.GetString("preamble_prompt"), userPrompt)

  6. إذا كان الخادم يعمل لفترة طويلة، على عكس بيئة الحوسبة بدون خادم، يجب إعادة تحميل النموذج بشكل دوري (على سبيل المثال، باستخدام setInterval في Node.js أو java.util.Timer في Java) للتأكّد من أنّك تحصل على أحدث نموذج من خادم Remote Config.

الخطوة 4: ضبط قيم المَعلمات الخاصة بالخادم في Remote Config

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

في ما يلي كيفية إنشاء نموذج Remote Config خاص بالخادم:

  1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

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

  3. حدِّد مَعلمات Remote Config بالأسماء وأنواع البيانات نفسها التي حدّدتها في تطبيقك، وقدِّم القيم. ستلغي هذه القيم الإعدادات التلقائية (defaultConfig أو default_config) التي ضبطتها في ضبط تطبيق الخادم عند جلب النموذج وتقييمه وتعيين هذه القيم لمتغيّراتك.

  4. يمكنك اختياريًا ضبط شروط لتطبيق القيم بشكل مستمر على عينة عشوائية من المثيلات أو الإشارات المخصصة التي تحددها. لمزيد من المعلومات حول الشروط، يُرجى الاطّلاع على أنواع قواعد الشروط.

  5. عند الانتهاء من إضافة المَعلمات، انقر على نشر التغييرات.

  6. راجِع التغييرات وانقر على نشر التغييرات مرّة أخرى.

الخطوة 5: النشر باستخدام Cloud Functions for Firebase أو Cloud Run

إذا كان تطبيق الخادم خفيفًا ويعتمد على الأحداث، ننصحك بنشر الرمز باستخدام Cloud Functions for Firebase. على سبيل المثال، لنفترض أنّ لديك تطبيقًا يتضمّن حوارًا بين الشخصيات مستندًا إلى واجهة برمجة تطبيقات للذكاء الاصطناعي التوليدي (مثل Google AI أو Agent Platform). في هذه الحالة، يمكنك استضافة منطق عرض نموذج لغوي كبير في دالة يستدعيها تطبيقك عند الطلب.

إذا كنت بصدد إنشاء تطبيق ويب يعرضه الخادم، توفّر App Hosting الدعم لأُطر عمل الويب الشائعة.

وإلا، يمكنك استخدام Cloud Run. لنشر تطبيق الخادم باستخدام Cloud Run، اتّبِع دليل البدء السريع للغتك:

لمزيد من المعلومات حول أفضل حالات استخدام Cloud Run وCloud Functions for Firebase، يُرجى الاطّلاع على المقالة المقارنة بين Cloud Functions for Firebase وCloud Run: حالات استخدام كل منهما.

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