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


تتيح Firebase Remote Config إمكانية الإعداد من جهة الخادم باستخدام الإصدار 12.1.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) Node.js الخاصة بـ Firebase Admin. تتيح لك هذه الإمكانية إدارة السلوك والإعدادات لتطبيقات من جهة الخادم بشكل ديناميكي باستخدام Remote Config. ويشمل ذلك عمليات التنفيذ بدون خادم، مثل Cloud Functions.

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

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

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

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

قبل البدء

اتّبِع التعليمات الواردة في إضافة حزمة تطوير البرامج (SDK) الخاصة بمسؤول Firebase إلى الخادم لإنشاء مشروع على Firebase وإعداد حساب خدمة وإضافة حزمة تطوير البرامج (SDK) الخاصة بمسؤول Firebase في Node.js إلى الخادم.

الخطوة 1: إعداد حزمة Firebase Admin Node.js SDK وتفويض طلبات واجهة برمجة التطبيقات

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

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

// Initialize Firebase
const firebaseApp = initializeApp();

الخطوة 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 الخاص بالخادم واستخدام قيمه. توضِّح الخطوات التالية كيفية ضبط إعدادات تطبيق Node.js.

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

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

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

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

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

  2. لضمان تشغيل تطبيقك بنجاح حتى إذا انقطع اتصاله بخادم الخلفية Remote Config، أضِف قيمًا تلقائية لكل مَعلمة في تطبيقك. ولإجراء ذلك، أضِف 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()

  3. بعد تحميل النموذج، استخدِم template.evaluate() لاستيراد المَعلمات والقيم من النموذج:

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

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

    • في حال استخدام شروط النسبة المئوية، أضِف randomizationId الذي تريد استخدامه لتقييم شروطك ضمن الدالة template.evaluate().
    • في حال استخدام الإشارات المخصّصة، حدِّد السمات وقيمها. تتوفّر الإشارات المخصّصة مع الإصدار 12.5.0 من حزمة تطوير البرامج (SDK) الخاصة بـ Firebase Admin Node.js والإصدارات الأحدث.

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

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

    // 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"
});

  5. بعد ذلك، استخرِج قيم المَعلمات التي تحتاج إليها من الثابت config. استخدِم getters لتحويل القيم من Remote Config إلى التنسيق المتوقّع. تتوفّر الأنواع التالية:

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

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

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

const is_ai_enabled = config.getBool('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}`;

  6. إذا كان الخادم يعمل لفترة طويلة، على عكس بيئة بلا خادم، استخدِم setInterval لإعادة تحميل النموذج بشكل دوري للتأكّد من أنّك تستردّ أحدث نموذج من خادم Remote Config.

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

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

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

  1. في وحدة تحكّم Firebase، انتقِل إلى صفحة عمليات التطوير والتشغيل والتفاعل > Remote Config > المَعلمات.

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

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

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

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

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

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

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

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

بخلاف ذلك، يمكنك استخدام Cloud Run. لنشر تطبيق الخادم باستخدام Cloud Run، اتّبِع الدليل في البدء السريع: نشر خدمة Node.js على Cloud Run.

لمزيد من المعلومات حول أفضل حالات استخدام Cloud Run وCloud Functions، يُرجى الرجوع إلى Cloud Functions مقارنةً بـ Cloud Run: متى يجب استخدام أحدهما بدلاً من الآخر.