استخدام ميزة "الإعداد عن بُعد" من جهة الخادم مع 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 الأساسي تلقائيًا) من خلال إدخال اسم مشروع جديد في الخطوة الأولى من سير عمل "إنشاء مشروع".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.

  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 Console.
  2. ابدأ مشروعك وثبِّت تبعيات Node.
  3. اضبط أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة Admin SDK و احفظ مفتاحك.
  4. أنشِئ الدالة.
  5. أنشِئ نموذجًا خاصًا بالخادم Remote Config.
  6. انشر دالتك واختبِرها في Firebase Local Emulator Suite.
  7. انشر دالتك على Google Cloud.

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

  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 وحفظ مفتاحك

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

  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 Console، افتح صفحة بيانات الاعتماد.
  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. احذف المحتوى الحالي ثم أضِف Admin SDK Remote Config وVertex AI SDK وابدأ التطبيق عن طريق لصق الرمز البرمجي التالي في الملف:

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

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

    يمكنك أيضًا ضبط مَعلمة للتحكّم في ما إذا كنت ستصل إلى 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
};

  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. اضبط 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');
  }
});

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

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

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

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

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

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

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

    اسم المَعلمة الوصف النوع القيمة التلقائية
    model_name اسم النموذج
    للاطّلاع على أحدث قوائم أسماء النماذج التي يمكنك استخدامها في الرمز البرمجي، يُرجى الاطّلاع على Model versions and lifecycles أو Available model names.     		سلسلة 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: ضبط أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة 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 CLI:

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 Console، فعِّل IAM Service Account Credentials API.
  2. امنح حساب المستخدم دور منشئ الرموز المميّزة لحساب الخدمة: من Google Cloud Console، افتح إدارة الهوية وإمكانية الوصول والمشرف > إدارة الهوية وإمكانية الوصول، واختَر حساب المستخدم ، ثم انقر على تعديل الأساسي > إضافة دور آخر.

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

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

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

  5. انقر على المشغِّل > تعديل ، ثم وسِّع إعدادات وقت التشغيل والإصدار والاتصالات والأمان.

  6. من علامة التبويب وقت التشغيل ، غيِّر حساب خدمة وقت التشغيل إلى حساب Admin 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 ونشر هذه التغييرات واختبار خيارات مختلفة.

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