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

يشرح هذا الدليل كيفية بدء استخدام الجيل الثاني. وظائف السحابة الإلكترونية مع الإعداد عن بُعد من جهة الخادم لجعل الخادم المكالمات الواردة إلى Vertex AI Gemini API

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

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

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

إعداد مشروع Firebase

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

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

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

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

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

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

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

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

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

ستحتاج إلى بيئة Node.js لكتابة الدوال. ستحتاج إلى واجهة سطر الأوامر في Firebase لنشر الوظائف في دوال السحابة وقت التشغيل.

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

    لتثبيت Node.js وnpm، نوصي باستخدام مدير إصدارات العُقد:

  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

يمكنك الآن مواصلة تنفيذ هذا الحل.

التنفيذ

اتّبِع الخطوات التالية لإنشاء الجيل الثاني واختباره ونشره. وظائف السحابة الإلكترونية مع ميزة "الإعداد عن بُعد" وVertex AI:

  1. تفعيل واجهات برمجة التطبيقات المقترَحة من Vertex AI في Google Cloud Console
  2. إعداد مشروعك وتثبيت تبعيات العُقد
  3. ضبط أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة "SDK للمشرف" لحفظ مفتاحك.
  4. أنشئ الدالة.
  5. إنشاء نموذج "الإعداد عن بُعد" الخاص بالخادم
  6. انشر الدالة واختبِرها في حزمة أدوات المحاكاة المحلية في Firebase
  7. نشر الدالة في Google Cloud.

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

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

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

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

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

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

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

  2. تسجيل الدخول إلى Firebase:

    firebase login

  3. شغِّل الأمر التالي لإعداد دوال السحابة الإلكترونية لبرنامج Firebase:

    firebase init functions

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

  5. عندما يُطلب منك تحديد اللغة المراد استخدامها، اختَر JavaScript ثم اضغط على أدخِل.

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

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

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

في هذا الحل، عليك استخدام حساب خدمة حزمة تطوير البرامج (SDK) لمشرف Firebase الدالة.

  1. في وحدة تحكُّم Google Cloud، افتح إدارة الهوية وإمكانية الوصول (IAM) المشرف، وحدد موقع حساب خدمة SDK للمشرف (المسمى firebase-adminsdk).
  2. اختَر الحساب وانقر على تعديل الحساب الرئيسي. صفحة "تعديل الوصول" تظهر.
  3. انقر على إضافة دور آخر، ثم على عارِض الإعدادات عن بُعد.
  4. انقر على إضافة دور آخر، ثم على مطوِّر منصة الذكاء الاصطناعي.
  5. انقر على إضافة دور آخر، ثم اختَر مستخدم Vertex AI.
  6. انقر على إضافة دور آخر، ثم على مرسل تشغيل السحابة الإلكترونية.
  7. انقر على حفظ.

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

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

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

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

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

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

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

  2. احذف المحتوى الحالي ثم أضِف حزمة تطوير البرامج (SDK) للمشرف عن بُعد وحزمة تطوير برامج 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. تهيئة القيم الافتراضية التي ستستخدمها وظيفتك إذا تعذر الاتصال بها خادم التهيئة عن بُعد. يقوم هذا الحل بتهيئة textModel، generationConfig وsafetySettings وtextPrompt وlocation باسم مَعلمات "الإعداد عن بُعد" التي تتوافق مع ميزة "الإعداد عن بُعد" ستدقق في تفاصيل هذا الدليل. لمزيد من المعلومات، المعلومات عن هذه المعلمات، يُرجى مراجعة عميل Vertex AI Node.js:

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

    // 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. إنشاء الدالة وإعداد الإعداد عن بُعد من جهة الخادم:

    // 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: إنشاء نموذج "الإعداد عن بُعد" الخاص بالخادم

الخطوة التالية، إنشاء نموذج "الإعداد عن بُعد من جهة الخادم" وضبط المَعلمات والقيم المراد استخدامها في الدالة. لإنشاء خادم خاص بالخادم نموذج "الإعداد عن بُعد":

  1. افتح وحدة تحكُّم Firebase، ومن قائمة التنقل، وسِّع تشغيل واختيار الإعداد عن بُعد:

  2. حدد الخادم من محدد العميل/الخادم أعلى صفحة "الإعداد عن بُعد".

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

  3. حدِّد مَعلمات "الإعداد عن بُعد" التالية:

    اسم المَعلمة الوصف النوع القيمة التلقائية
    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"

أنت الآن جاهز لنشر الدالة واختبارها محليًا باستخدام مجموعة أدوات المحاكاة المحلية في Firebase

  1. تأكَّد من ضبط GOOGLE_APPLICATION_CREDENTIALS كبيئة. على النحو الموضّح في الخطوة 3: ضبط أذونات "إدارة الهوية وإمكانية الوصول" حساب خدمة 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 المهيأ في نموذج خادم "الإعداد عن بُعد"، فمن المفترض أن يصل هذا إلى Gemini من خلال Vertex AI Gemini API، وبالتالي تحمل رسوم:

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

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

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

بعد اختبار الدالة والتحقق منها، تكون جاهزًا للنشر إلى Google Cloud واختبار الدالة المباشرة.

نشر الدالة

انشر الدالة باستخدام واجهة سطر الأوامر لمنصّة Firebase:

firebase deploy --only functions

حظر الوصول الذي لم تتم مصادقته إلى الدالة

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

لحظر الوصول الذي لم تتم مصادقته إلى الدالة:

  1. في وحدة تحكُّم Google Cloud، افتح تشغيل السحابة الإلكترونية

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

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

اضبط حساب المستخدم لاستخدام بيانات اعتماد حساب خدمة "SDK للمشرف".

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

توضّح الخطوات التالية كيفية ضبط حساب المستخدِم والوظيفة للتشغيل مع امتيازات حساب خدمة SDK للمشرف.

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

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

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

  4. فتح صفحة "وظائف السحابة الإلكترونية في Google Cloud" وانقر على الدالة 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"

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

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