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

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

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

    لمزيد من المعلومات التفصيلية حول انتحال هوية حساب الخدمة، يمكنك الاطّلاع على حساب الخدمة انتحال هوية في وثائق Google Cloud.

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

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

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

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

إعداد واجهة سطر أوامر gcloud

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

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

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

  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" ونشر المحتوى هذه التغييرات، واختبار خيارات مختلفة.

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