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

تتيح Firebase Remote Config إعدادات من جهة الخادم باستخدام حِزم Firebase Admin SDK لنظام التشغيل 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 إلى الخادم. تأكَّد من استخدام إصدار متوافق من مدير SDK للنظام الأساسي الذي تستخدمه:

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

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

عند تهيئة حزمة مدير 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 هذا على الجهاز، ويمكنك بعد ذلك إعداده باستخدام الدالة 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 Admin، والإصدار 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. في ما يلي طرق getter المتوافقة ومثال على كيفية الوصول إلى قيم 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
    • النوع Float: 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
    • Double: 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
    • النوع Float: 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، انتقِل إلى صفحة عمليات التطوير والتشغيل والتفاعل > Remote Config > المَعلمات.

  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: متى يجب استخدام أحدهما بدلاً من الآخر.

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