استخدام ميزة "الإعداد عن بُعد" من جهة الخادم مع 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 من العقدة وكنت تستخدم الإصدار 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 في محرِّر نصوص أو بيئة تطوير متكاملة (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();
    
  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
    };
    
  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 اسم النموذج
    للحصول على قوائم محدّثة بأسماء النماذج لاستخدامها في الرمز البرمجي، اطّلِع على نُسخ نماذج ومراحل حياتها أو أسماء نماذج المتاحة.
    سلسلة 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 إذا لم يكن مثبّتًا على جهاز الكمبيوتر، كما هو موضَّح في Install the 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 ونشر هذه التغييرات واختبار خيارات مختلفة.

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