استخدام ميزة "الإعداد عن بُعد" من جهة الخادم مع Cloud Functions وVertex AI

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

في هذا البرنامج التعليمي، ستضيف 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 لكتابة الدوال، كما ستحتاج إلى واجهة سطر الأوامر Firebase لنشر الدوال في وقت التشغيل Cloud Functions.

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

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

  2. ثبِّت Firebase CLI باستخدام الطريقة المفضّلة لديك. على سبيل المثال، لتثبيت واجهة سطر الأوامر باستخدام 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 وVertex AI:

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

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

  1. افتح Google Cloud وحدة التحكّم، واختر مشروعك عند مطالبتك بذلك.
  2. في حقل البحث أعلى وحدة التحكّم، أدخِل Vertex AI وانتظِر إلى أن تظهر Vertex AI كنتيجة.
  3. انقر على Vertex AI. تظهر لوحة بيانات Vertex AI.

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

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

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

الخطوة 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 وVertex AI من خلال تنفيذ الأوامر التالية، واستخدِم --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 يتطابق مع إصدار Node.js المثبَّت والإصدار الذي ستشغّله في النهاية على Google Cloud. على سبيل المثال، إذا تم ضبط المقطع engines في package.json على الإصدار 18 من Node وكنت تستخدم Node.js 20، عدِّل الملف لاستخدام الإصدار 20:

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

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

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

  1. في وحدة تحكّم Google Cloud، افتح صفحة إدارة الهوية وإمكانية الوصول، وابحث عن حساب خدمة Admin SDK (المسمّى firebase-adminsdk).
  2. اختَر الحساب وانقر على تعديل الجهة الرئيسية. تظهر صفحة "الإذن بالتعديل".
  3. انقر على إضافة دور آخر، ثم اختَر Remote Config المشاهد.
  4. انقر على إضافة دور آخر، ثم اختَر مطوّر منصة الذكاء الاصطناعي.
  5. انقر على إضافة دور آخر، ثم اختَر مستخدم Vertex AI.
  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 وVertex AI Gemini API، وإعداد المَعلمات التلقائية باستخدام Remote Config، واسترداد أحدث مَعلمات Remote Config، ومعالجة إدخال المستخدم، وبث استجابة إلى المستخدم.

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

  2. احذف المحتوى الحالي، ثم أضِف حِزم SDK الخاصة بـ Admin SDK وRemote Config وVertex AI، وأعِد ضبط التطبيق من خلال لصق الرمز التالي في الملف:

    const { onRequest } = require("firebase-functions/v2/https");
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");

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

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

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

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

    // 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
};
    index.js

  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;
    index.js

  5. اضبط Vertex AI وأضِف منطق المحادثة والردود:

      // 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');
  }
});
    index.js

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

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

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

  1. افتح وحدة تحكّم Firebase، ثم وسِّع تشغيل من قائمة التنقّل واختَر Remote Config.

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

    • إذا كانت هذه هي المرّة الأولى التي تستخدِم فيها 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 إعدادات الأمان في Vertex AI JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location الموقع الجغرافي لتشغيل خدمة Vertex AI ونموذجها سلسلة us-central1
    is_vertex_enabled مَعلمة اختيارية تتحكّم في ما إذا كان يتم إرسال طلبات البحث إلى Vertex AI. قيمة منطقية true

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

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

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

  1. تأكَّد من ضبط GOOGLE_APPLICATION_CREDENTIALS كمتغيّر بيئة كما هو موضّح في الخطوة 3: ضبط أذونات إدارة الهوية وإمكانية الوصول (IAM) لحساب الخدمة 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 Emulator أو وحدة التحكّم وابحث عن أي أخطاء أو تحذيرات.

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

    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 واختبار الوظيفة المباشرة.

نشر الدالة

نفِّذ الدالة باستخدام واجهة سطر الأوامر Firebase:

firebase deploy --only functions

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

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

لحظر الوصول غير المصادق عليه إلى الدالة، اتّبِع الخطوات التالية:

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

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

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

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

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

توضِّح الخطوات التالية كيفية ضبط حساب المستخدم والوظيفة التي سيتم تنفيذها باستخدام امتيازات حساب الخدمة Admin SDK.

  1. في وحدة تحكّم Google Cloud، فعِّل IAM Service Account Credentials API.
  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 ونشر هذه التغييرات واختبار خيارات مختلفة.

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