استخدام ميزة "الإعداد عن بُعد" من جهة الخادم مع "وظائف السحابة الإلكترونية" و"منصّة الوكيل"

يوضّح هذا الدليل كيفية بدء استخدام الجيل الثاني من Cloud Functions مع جهة الخادم في Remote Config لإجراء طلبات من جهة الخادم إلى Agent Platform Gemini API (formerly Vertex AI).

في هذا البرنامج التعليمي، ستضيف Remote Config إلى دالة تشبه روبوت الدردشة تستخدم نموذج Gemini للإجابة عن أسئلة المستخدمين. سيدير "Remote Config" إدخالات "Gemini API" (بما في ذلك طلب سيتم إلحاقه بطلبات المستخدمين الواردة)، ويمكنك تعديل هذه الإدخالات عند الطلب من وحدة تحكّم "Firebase". ستستخدم أيضًا Firebase Local Emulator Suite لاختبار الدالة وتصحيح أخطائها، وبعد التأكّد من أنّها تعمل، ستنشرها وتختبرها على Google Cloud.

المتطلبات الأساسية

يفترض هذا الدليل أنّك على دراية باستخدام JavaScript لتطوير التطبيقات.

إعداد مشروع Firebase

إذا لم يكن لديك مشروع على Firebase:

  1. سجِّل الدخول إلى وحدة تحكّم Firebase.

  2. انقر على إنشاء مشروع، ثم استخدِم أيًا من الخيارَين التاليَين:

    • الخيار 1: أنشئ مشروعًا جديدًا على Firebase (ومشروع Google Cloud الأساسي تلقائيًا) عن طريق إدخال اسم مشروع جديد في الخطوة الأولى من سير عمل "إنشاء مشروع".
    • الخيار 2: "إضافة Firebase" إلى مشروع Google Cloud حالي من خلال اختيار اسم مشروع Google Cloud من القائمة المنسدلة في الخطوة الأولى من سير عمل "إنشاء مشروع".

  3. عندما يُطلب منك ذلك، لا تحتاج إلى إعداد Google Analytics لاستخدام هذا الحلّ.

  4. اتّبِع التعليمات الظاهرة على الشاشة لإنشاء مشروعك.

إذا كان لديك مشروع على Firebase:

انتقِل إلى ضبط بيئة التطوير.

ضبط بيئة التطوير

ستحتاج إلى بيئة Node.js لكتابة الدوال، وستحتاج إلى واجهة سطر الأوامر (CLI) في Firebase لنشر الدوال في بيئة التشغيل Cloud Functions.

  1. ثبِّت Node.js وnpm.

    لتثبيت Node.js وnpm، ننصحك باستخدام مدير إصدارات Node.

  2. ثبِّت واجهة سطر الأوامر (CLI) في Firebase باستخدام طريقتك المفضّلة. على سبيل المثال، لتثبيت واجهة سطر الأوامر باستخدام npm، شغِّل هذا الأمر:

    npm install -g firebase-tools@latest

    يثبّت هذا الأمر الأمر firebase المتاح عالميًا. إذا تعذّر تنفيذ هذا الأمر، قد تحتاج إلى تغيير أذونات npm.

    للتحديث إلى أحدث إصدار من "firebase-tools"، أعِد تشغيل الأمر نفسه.

  3. ثبِّت firebase-functions وfirebase-admin واستخدِم --save لحفظهما في package.json:

    npm install firebase-functions@latest firebase-admin@latest --save

أنت الآن جاهز للانتقال إلى تنفيذ هذا الحلّ.

التنفيذ

اتّبِع الخطوات التالية لإنشاء واختبار ونشر الجيل الثاني من Cloud Functions باستخدام Remote Config وAgent Platform:

  1. فعِّل واجهات برمجة التطبيقات المقترَحة في Agent Platform في وحدة تحكّم Google Cloud.
  2. إعداد مشروعك وتثبيت تبعيات Node
  3. اضبط أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة "Admin SDK" واحفظ مفتاحك.
  4. أنشئ الدالة.
  5. أنشئ نموذج Remote Config خاصًا بالخادم.
  6. انشر الدالة واختبِرها في Firebase Local Emulator Suite.
  7. انشر الدالة في Google Cloud.

الخطوة 1: تفعيل واجهات برمجة التطبيقات المقترَحة من Agent Platform في وحدة تحكّم Google Cloud

  1. افتح وحدة تحكّم Google Cloud، واختَر مشروعك عندما يُطلب منك ذلك.
  2. في حقل البحث في أعلى وحدة التحكّم، أدخِل Agent Platform وانتظِر حتى يظهر Agent Platform كنتيجة.
  3. انقر على Agent Platform. ستظهر لوحة بيانات "Agent Platform".

  4. انقر على تفعيل جميع واجهات برمجة التطبيقات المقترَحة.

    قد يستغرق إكمال تفعيل واجهة برمجة التطبيقات بضع لحظات. يُرجى إبقاء الصفحة نشطة ومفتوحة إلى أن تكتمل عملية التفعيل.

  5. إذا لم تكن الفوترة مفعَّلة، سيُطلب منك إضافة حساب على "Cloud Billing" أو ربطه. بعد تفعيل حساب فوترة، ارجع إلى لوحة بيانات Agent Platform وتأكَّد من تفعيل جميع واجهات برمجة التطبيقات المقترَحة.

الخطوة 2: إعداد مشروعك وتثبيت تبعيات Node

  1. افتح وحدة طرفية على جهاز الكمبيوتر وانتقِل إلى الدليل الذي تخطط لإنشاء الدالة فيه.

  2. سجِّل الدخول إلى Firebase:

    firebase login

  3. شغِّل الأمر التالي لإعداد Cloud Functions for Firebase:

    firebase init functions

  4. اختَر استخدام مشروع حالي وحدِّد رقم تعريف مشروعك.

  5. عندما يُطلب منك اختيار اللغة التي تريد استخدامها، اختَر Javascript واضغط على مفتاح Enter.

  6. بالنسبة إلى جميع الخيارات الأخرى، حدِّد الإعدادات التلقائية.

    يتم إنشاء دليل functions في الدليل الحالي. ستجد في الداخل ملف index.js الذي ستستخدمه لإنشاء الدالة، ودليل node_modules الذي يحتوي على تبعيات الدالة، وملف package.json الذي يحتوي على تبعيات الحزمة.

  7. أضِف الحزمتَين Admin SDK وAgent Platform من خلال تشغيل الأوامر التالية، باستخدام --save لضمان حفظهما في ملف package.json:

    cd functions
npm install firebase-admin@latest @google-cloud/vertexai --save

يُفترض أن يظهر ملف functions/package.json الآن على النحو التالي، مع تحديد أحدث الإصدارات:

  {
    "name": "functions",
    "description": "Cloud Functions for Firebase",
    "scripts": {
      "serve": "firebase emulators:start --only functions",
      "shell": "firebase functions:shell",
      "start": "npm run shell",
      "deploy": "firebase deploy --only functions",
      "logs": "firebase functions:log"
    },
    "engines": {
      "node": "20"
    },
    "main": "index.js",
    "dependencies": {
      "@google-cloud/vertexai": "^1.1.0",
      "firebase-admin": "^12.1.0",
      "firebase-functions": "^5.0.0"
    },
    "devDependencies": {
      "firebase-functions-test": "^3.1.0"
    },
    "private": true
  }

يُرجى العِلم أنّه في حال استخدام ESLint، ستظهر لك فقرة تتضمّنه. بالإضافة إلى ذلك، تأكَّد من أنّ إصدار محرّك العقدة يتطابق مع الإصدار المثبَّت من Node.js والإصدار الذي يتم تشغيله في النهاية على Google Cloud. على سبيل المثال، إذا تم ضبط المقطع engines في ملف package.json على الإصدار 18 من Node وكنت تستخدم الإصدار 20 من Node.js، عدِّل الملف لاستخدام الإصدار 20:

  "engines": {
    "node": "20"
  },

الخطوة 3: ضبط أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة "Admin SDK" وحفظ مفتاحك

في هذا الحلّ، ستستخدم حساب خدمة Firebase Admin SDK لتشغيل الدالة.

  1. في وحدة تحكّم Google Cloud، افتح صفحة "إدارة الهوية وإمكانية الوصول والمشرف"، وابحث عن حساب خدمة Admin SDK (الذي يحمل الاسم firebase-adminsdk).
  2. اختَر الحساب وانقر على تعديل المدير. ستظهر صفحة "تعديل إذن الوصول".
  3. انقر على إضافة دور آخر، ثم اختَر Remote Config Viewer.
  4. انقر على إضافة دور آخر (Add another role)، واختَر مطوّر منصة الذكاء الاصطناعي (AI platform developer).
  5. انقر على إضافة دور آخر، ثم اختَر مستخدم Agent Platform.
  6. انقر على إضافة دور آخر، ثم اختَر مُشغِّل Cloud Run.
  7. انقر على حفظ.

بعد ذلك، عليك تصدير بيانات اعتماد حساب الخدمة "Admin SDK" وحفظها في متغيّر البيئة "GOOGLE_APPLICATION_CREDENTIALS".

  1. في وحدة تحكّم Google Cloud، افتح صفحة بيانات الاعتماد.
  2. انقر على حساب الخدمة Admin SDK لفتح صفحة التفاصيل.
  3. انقر على المفاتيح.
  4. انقر على إضافة مفتاح > إنشاء مفتاح جديد.
  5. تأكَّد من اختيار JSON كـ نوع المفتاح، ثم انقر على إنشاء.
  6. نزِّل المفتاح في مكان آمن على الكمبيوتر.

  7. من الوحدة الطرفية، يمكنك تصدير المفتاح كمتغيّر بيئة:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

الخطوة 4: إنشاء الدالة

في هذه الخطوة، ستنشئ دالة تعالج إدخالات المستخدم وتُنشئ ردودًا مستندة إلى الذكاء الاصطناعي. ستجمع مقتطفات متعددة من الرموز البرمجية لإنشاء دالة شاملة تبدأ Admin SDK وAgent Platform Gemini API (formerly Vertex AI)، وتضبط المَعلمات التلقائية باستخدام Remote Config، وتجلب أحدث مَعلمات Remote Config، وتعالج إدخالات المستخدم، وتعرض ردًا للمستخدم.

  1. في قاعدة الرموز البرمجية، افتح functions/index.js في محرِّر نصوص أو بيئة تطوير متكاملة (IDE).

  2. احذف المحتوى الحالي ثم أضِف حزمة تطوير البرامج (SDK) لكل من Admin SDK وRemote Config وAgent Platform وابدأ التطبيق من خلال لصق الرمز التالي في الملف:

    const { onRequest } = require("firebase-functions/https");
const { requiresRole, requiresAPI } = require("firebase-functions");
const logger = require("firebase-functions/logger");

const { initializeApp } = require("firebase-admin/app");
const { VertexAI } = require('@google-cloud/vertexai');
const { getRemoteConfig } = require("firebase-admin/remote-config");

requiresRole("roles/aiplatform.user");
requiresRole("roles/cloudconfig.viewer");
requiresAPI("aiplatform.googleapis.com", "Needed to query Vertex AI Gemini models");
requiresAPI("firebaseremoteconfig.googleapis.com", "Needed to fetch server-side Remote Config templates");

// Set and check environment variables.
const project = process.env.GCLOUD_PROJECT;

// Initialize Firebase.
const app = initializeApp();

  3. اضبط القيم التلقائية التي ستستخدمها الدالة إذا تعذّر الاتصال بخادم Remote Config. يضبط هذا الحلّ textModel وgenerationConfig وsafetySettings وtextPrompt وlocation كمَعلمات Remote Config تتوافق مع مَعلمات Remote Config التي ستضبطها لاحقًا في هذا الدليل. لمزيد من المعلومات حول هذه المَعلمات، يُرجى الاطّلاع على عميل Vertex AI Node.js.

    يمكنك أيضًا ضبط مَعلمة للتحكّم في ما إذا كنت تريد الوصول إلى Agent Platform Gemini API (formerly Vertex AI) (في هذا المثال، مَعلمة باسم vertex_enabled). يمكن أن يكون هذا الإعداد مفيدًا عند اختبار الدالة. في مقتطفات الرموز التالية، يتم ضبط هذه القيمة على false، ما سيؤدي إلى تخطّي استخدام Agent Platform أثناء اختبار نشر الدوال الأساسية. سيؤدي ضبطه على true إلى استدعاء Agent Platform Gemini API (formerly Vertex AI).

    // Define default (fallback) parameter values for Remote Config.
const defaultConfig = {

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-002",
  generation_config: [{
    "stopSequences": [], "temperature": 0.7,
    "maxOutputTokens": 64, "topP": 0.1, "topK": 20
  }],
  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!",
  safety_settings: [{
    "category":
      "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT",
    "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE"
  }],
  location: 'us-central1',

  // Disable Vertex AI Gemini API access for testing.
  vertex_enabled: false
};

  4. أنشئ الدالة وأعِدّ Remote Config من جهة الخادم:

    // Export the function.
exports.generateWithVertex = onRequest(async (request, response) => {

  try {

    // Set up Remote Config.
    const rc = getRemoteConfig(app);

    // Get the Remote Config template and assign default values.
    const template = await rc.getServerTemplate({
      defaultConfig: defaultConfig
    });

    // Add the template evaluation to a constant.
    const config = template.evaluate();

    // Obtain values from Remote Config.
    const textModel = config.getString("model_name") ||
        defaultConfig.model_name;
    const textPrompt = config.getString("prompt") || defaultConfig.prompt;
    const generationConfig = config.getString("generation_config") ||
        defaultConfig.generation_config;
    const safetySettings = config.getString("safety_settings") ||
        defaultConfig.safety_settings;
    const location = config.getString("location") ||
        defaultConfig.location;
    const vertexEnabled = config.getBoolean("is_vertex_enabled") ||
        defaultConfig.vertex_enabled;

  5. إعداد Agent Platform وإضافة منطق المحادثة والردّ:

      // Allow user input.
  const userInput = request.query.prompt || '';

  // Instantiate Vertex AI.
    const vertex_ai = new VertexAI({ project: project, location: location });
    const generativeModel = vertex_ai.getGenerativeModel({
      model: textModel,
      safety_settings: safetySettings,
      generation_config: generationConfig,
    });

    // Combine prompt from Remote Config with optional user input.
    const chatInput = textPrompt + " " + userInput;

    if (!chatInput) {
      return res.status(400).send('Missing text prompt');
    }
    // If vertexEnabled isn't true, do not send queries to Vertex AI.
    if (vertexEnabled !== true) {
      response.status(200).send({
        message: "Vertex AI call skipped. Vertex is not enabled."
      });
      return;
    }

    logger.log("\nRunning with model ", textModel, ", prompt: ", textPrompt,
      ", generationConfig: ", generationConfig, ", safetySettings: ",
      safetySettings, " in ", location, "\n");

    const result = await generativeModel.generateContentStream(chatInput); 
    response.writeHead(200, { 'Content-Type': 'text/plain' });

    for await (const item of result.stream) {
      const chunk = item.candidates[0].content.parts[0].text;
      logger.log("Received chunk:", chunk);
      response.write(chunk);
    }

    response.end();

  } catch (error) {
    logger.error(error);
    response.status(500).send('Internal server error');
  }
});

  6. احفظ الملف ثم أغلقه.

الخطوة 5: إنشاء نموذج Remote Config خاص بالخادم

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

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

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

    • إذا كانت هذه هي المرة الأولى التي تستخدم فيها Remote Config أو نماذج الخادم، انقر على إنشاء إعدادات. تظهر لوحة إنشاء أول مَعلمة من جهة الخادم.
    • إذا لم تكن هذه هي المرة الأولى التي تستخدم فيها نماذج خادم Remote Config، انقر على إضافة مَعلمة.

  3. حدِّد مَعلمات Remote Config التالية:

    اسم المَعلمة الوصف النوع القيمة التلقائية
    model_name اسم النموذج
    للاطّلاع على قوائم محدّثة بأسماء النماذج التي يمكنك استخدامها في الرمز البرمجي، يُرجى مراجعة إصدارات النماذج ودورات حياتها أو أسماء النماذج المتاحة.     		سلسلة gemini-2.0-flash
    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}]
    safety_settings إعدادات الأمان لـ "Agent Platform" JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location الموقع الجغرافي لتشغيل خدمة Agent Platform والنموذج سلسلة global
    is_vertex_enabled مَعلمة اختيارية تتحكّم في ما إذا كان يتم إرسال طلبات البحث إلى Agent Platform. قيمة منطقية true

  4. عند الانتهاء من إضافة المَعلمات، تحقَّق من المَعلمات ومن أنّ أنواع بياناتها صحيحة، ثم انقر على نشر التغييرات.

الخطوة 6: نشر الدالة واختبارها في Firebase Local Emulator Suite

أنت الآن جاهز لنشر الدالة واختبارها محليًا باستخدام Firebase Local Emulator Suite.

  1. تأكَّد من ضبط GOOGLE_APPLICATION_CREDENTIALS كمتغيّر بيئة كما هو موضّح في الخطوة 3: ضبط أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة Admin SDK وحفظ مفتاحك. بعد ذلك، من الدليل الرئيسي لدليل functions، انشر الدالة في محاكي Firebase:

    firebase emulators:start --project PROJECT_ID --only functions

  2. افتح صفحة سجلّات المحاكي. من المفترض أن يشير ذلك إلى أنّه تم تحميل الدالة.

  3. يمكنك الوصول إلى الدالة من خلال تنفيذ الأمر التالي، حيث PROJECT_ID هو رقم تعريف المشروع وLOCATION هي المنطقة التي نشرت الدالة فيها (على سبيل المثال، us-central1):

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. انتظِر الردّ، ثم ارجع إلى صفحة سجلّات "محاكي Firebase" أو وحدة التحكّم وتحقَّق من وجود أي أخطاء أو تحذيرات.

  5. جرِّب إرسال بعض البيانات التي أدخلها المستخدم، مع العِلم أنّه تم ضبط is_vertex_enabled في نموذج خادم Remote Config، لذا من المفترض أن يتم الوصول إلى نموذج Gemini من خلال Agent Platform Gemini API (formerly Vertex AI)، وقد يؤدي ذلك إلى فرض رسوم:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. يُرجى إجراء تغييرات على نموذج خادم "Remote Config" في وحدة تحكّم "Firebase"، ثم إعادة الوصول إلى الدالة لملاحظة التغييرات.

الخطوة 7: نشر الدالة في Google Cloud

بعد اختبار الدالة والتحقّق منها، تصبح جاهزًا لنشرها في Google Cloud واختبارها مباشرةً.

نشر الدالة

انشر الدالة باستخدام واجهة سطر الأوامر (CLI) في Firebase:

firebase deploy --only functions

حظر الوصول غير المصادَق عليه إلى الدالة

عند نشر الدوال باستخدام Firebase، يتم السماح بالاستدعاءات غير المصادق عليها تلقائيًا إذا لم تكن سياسة مؤسستك تفرض قيودًا على ذلك. أثناء الاختبار وقبل تأمين الوصول باستخدام App Check، ننصح بحظر الوصول غير المصادَق عليه.

لحظر الوصول غير المصادَق عليه إلى الدالة:

  1. في وحدة تحكّم Google Cloud، افتح Cloud Run.

  2. انقر على generateWithVertex، ثم انقر على علامة التبويب الأمان.

  3. فعِّل طلب المصادقة، ثم انقر على حفظ.

ضبط حساب المستخدم لاستخدام بيانات اعتماد حساب خدمة Admin SDK

بما أنّ حساب خدمة Admin SDK لديه جميع الأدوار والأذونات اللازمة لتشغيل الدالة والتفاعل مع Remote Config وAgent Platform Gemini API (formerly Vertex AI)، ننصحك باستخدامه لتشغيل الدالة. لإجراء ذلك، يجب أن يكون بإمكانك إنشاء رموز مميّزة للحساب من حساب المستخدم الخاص بك.

توضّح الخطوات التالية كيفية ضبط حساب المستخدم والدالة ليتم تشغيلهما باستخدام امتيازات حساب خدمة Admin SDK.

  1. في وحدة تحكّم Google Cloud، فعِّل واجهة برمجة التطبيقات لبيانات اعتماد حساب خدمة إدارة الهوية وإمكانية الوصول.
  2. امنح حساب المستخدم دور منشئ الرمز المميّز لحساب الخدمة: من وحدة تحكّم Google Cloud، افتح إدارة الهوية وإمكانية الوصول والمشرف > إدارة الهوية وإمكانية الوصول، واختَر حساب المستخدم، ثم انقر على تعديل المدير > إضافة دور آخر.

  3. اختَر منشئ الرمز المميّز لحساب الخدمة، ثم انقر على حفظ.

    لمزيد من المعلومات التفصيلية حول انتحال هوية حساب الخدمة، يُرجى الرجوع إلى انتحال هوية حساب الخدمة في مستندات Google Cloud.

  4. افتح صفحة وحدة تحكّم Google Cloud Cloud Functions وانقر على دالة generateWithVertex في قائمة الدوال.

  5. اختَر المشغّل > تعديل ووسِّع إعدادات وقت التشغيل والإنشاء والاتصالات والأمان.

  6. من علامة التبويب وقت التشغيل، غيِّر حساب خدمة وقت التشغيل إلى حساب مدير SDK.

  7. انقر على التالي، ثم على نشر.

إعداد gcloud CLI

لتشغيل الدالة واختبارها بأمان من سطر الأوامر، عليك المصادقة باستخدام خدمة "Cloud Functions" والحصول على رمز مصادقة صالح.

لتفعيل إنشاء الرموز المميّزة، ثبِّت gcloud CLI واضبط إعداداته:

  1. إذا لم تكن قد ثبّتّ gcloud CLI على جهاز الكمبيوتر، ثبّتها كما هو موضّح في مقالة تثبيت gcloud CLI.

  2. احصل على بيانات اعتماد الوصول إلى حسابك على Google Cloud:

    gcloud auth login

  3. اضبط رقم تعريف مشروعك في gcloud:

    gcloud config set project PROJECT_ID

اختبار الدالة

أنت الآن جاهز لاختبار الدالة في Google Cloud. لاختبار الدالة، شغِّل الأمر التالي:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

أعِد المحاولة باستخدام البيانات التي يقدّمها المستخدم:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
 -H "Authorization: bearer $(gcloud auth print-identity-token)" \
 -H "Content-Type: application/json"

يمكنك الآن إجراء تغييرات على نموذج خادم Remote Config ونشر هذه التغييرات واختبار خيارات مختلفة.

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