استخدام ميزة "الإعداد عن بُعد" من جهة الخادم مع 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 CLI لنشر الدوال إلى وقت تشغيل 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 وكنت تستخدم الإصدار 20 من Node.js، عدِّل الملف لاستخدام الإصدار 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 Invoker.
  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 في محرِّر نصوص أو بيئة تطوير متكاملة.

  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-1.5-flash-002
    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 إعدادات safety لحساب 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: ضبط أذونات إدارة الهوية وإمكانية الوصول لحساب الخدمة 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 من خلال 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. اختَر Service Account Token Creator (صانع رمز مميّز لحساب الخدمة)، ثم انقر على Save (حفظ).

    للحصول على معلومات أكثر تفصيلاً عن انتحال هوية حساب الخدمة، يُرجى الرجوع إلى مقالة انتحال هوية حساب الخدمة في مستندات 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 ونشر هذه التغييرات واختبار خيارات مختلفة.

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