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


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

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

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

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

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

قبل البدء

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

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

عندما تبدأ حزمة تطوير البرامج (SDK) للمشرف بدون مَعلمات، تستخدم الحزمة بيانات الاعتماد التلقائية لتطبيق Google وتقرأ الخيارات من متغيّر بيئة GOOGLE_APPLICATION_CREDENTIALS. لإعداد حزمة تطوير البرامج وإضافة 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 لنظام التشغيل 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. بعد ذلك، استخرِج قيم المَعلمات التي تحتاج إليها من الثابت الخاص بالإعداد. استخدِم getters لتحويل القيم من Remote Config إلى التنسيق المتوقّع. تتوفّر الأنواع التالية:

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

    على سبيل المثال، إذا كنت تنفّذ Vertex AI على الخادم وتريد تغيير النموذج ومَعلمات النموذج، قد تحتاج إلى ضبط المَعلمات الخاصة بـ 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. افتح صفحة مَعلمات Remote Config في "وحدة تحكّم Firebase"، ثم اختَر الخادم من أداة اختيار العميل/الخادم.
  2. حدِّد مَعلمات Remote Config بالأسماء وأنواع البيانات نفسها التي حدّدتها في تطبيقك، وقدِّم القيم. ستتجاهل هذه القيم defaultConfig الذي ضبطته في إعداد تطبيق الخادم عند استرداد النموذج وتقييمه وتعيين هذه القيم لمتغيّراتك.
  3. يمكنك اختياريًا ضبط شروط لتطبيق القيم بشكل دائم على عيّنة عشوائية من المثيلات أو الإشارات المخصّصة التي تحدّدها. لمزيد من المعلومات حول الشروط، يُرجى الاطّلاع على أنواع قواعد الشروط.
  4. عند الانتهاء من إضافة المَعلمات، انقر على نشر التغييرات.
  5. راجِع التغييرات وانقر على نشر التغييرات مرة أخرى.

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

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

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

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

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