استدعاء عمليات Genkit من تطبيقك

تتضمّن "وظائف Firebase السحابية" طريقة onCallGenkit تتيح لك إنشاء دالة قابلة للاستدعاء باستخدام إجراء Genkit (وهو تدفق). يمكن استدعاء هذه الدوال باستخدام genkit/beta/client أو حِزم SDK للعميل في "وظائف السحابة الإلكترونية"، التي تضيف تلقائيًا معلومات المصادقة.

قبل البدء

• يجب أن تكون على دراية بمفهوم التدفقاتفي Genkit وكيفية كتابتها. تفترض التعليمات الواردة في هذه الصفحة أنّك سبق لك تحديد بعض التدفقات التي تريد نشرها.
• من المفيد، ولكن ليس مطلوبًا، أن تكون قد استخدمت "وظائف Firebase السحابية" من قبل.

إعداد مشروع Firebase

1. أنشِئ مشروعًا جديدًا على Firebase باستخدام وحدة تحكّم Firebase أو اختَر مشروعًا حاليًا.

2. رقِّي المشروع إلى خطة Blaze، وهي مطلوبة لنشر "وظائف السحابة الإلكترونية" في مرحلة الإنتاج.

3. ثبِّت Firebase CLI.

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

4. سجِّل الدخول باستخدام Firebase CLI:

   firebase login
   firebase login --reauth # alternative, if necessary
   firebase login --no-localhost # if running in a remote shell

5. أنشِئ دليل مشروع جديدًا:

   export PROJECT_ROOT=~/tmp/genkit-firebase-project1
   mkdir -p $PROJECT_ROOT

6. إعداد مشروع Firebase في الدليل:

   cd $PROJECT_ROOT
   firebase init functions

يفترض الجزء المتبقي من هذه الصفحة أنّك اخترت كتابة الدوال بلغة JavaScript.

تضمين التدفق في onCallGenkit

بعد إعداد مشروع Firebase باستخدام "وظائف السحابة الإلكترونية"، يمكنك نسخ تعريفات التدفقات أو كتابتها في دليل functions الخاص بالمشروع. في ما يلي مثال على تدفق لتوضيح ذلك:

const ai = genkit({
  plugins: [googleAI()],
  model: gemini15Flash,
});

const jokeTeller = ai.defineFlow({
  name: "jokeTeller",
  inputSchema: z.string().nullable(),
  outputSchema: z.string(),
  streamSchema: z.string(),
}, async (jokeType = "knock-knock", {sendChunk}) => {
  const prompt = `Tell me a ${jokeType} joke.`;

  // Call the `generateStream()` method to
  // receive the `stream` async iterable.
  const {stream, response: aiResponse} = ai.generateStream(prompt);

  // Send new words of the generative AI response
  // to the client as they are generated.
  for await (const chunk of stream) {
    sendChunk(chunk.text);
  }

  // Return the full generative AI response
  // to clients that may not support streaming.
  return (await aiResponse).text;
},
);
index.js

لتفعيل تدفّق مثل هذا، عليك تضمينه باستخدام onCallGenkit، المتاح في firebase-functions/https. تتضمّن هذه الطريقة المساعدة جميع ميزات الدوال القابلة للاستدعاء، وتتيح تلقائيًا الردود المستندة إلى البث وJSON.

const {onCallGenkit} = require("firebase-functions/https");

exports.tellJoke = onCallGenkit({
  // Bind the Gemini API key secret parameter to the function.
  secrets: [apiKey],
},
// Pass in the genkit flow.
jokeTeller,
);
index.js

إتاحة بيانات اعتماد واجهة برمجة التطبيقات للتدفقات المنشورة

بعد نشر التدفقات، تحتاج إلى طريقة للمصادقة على أي خدمات بعيدة تعتمد عليها. تحتاج معظم التدفقات على الأقل إلى بيانات اعتماد للوصول إلى خدمة واجهة برمجة التطبيقات الخاصة بالنموذج الذي تستخدمه.

بالنسبة إلى هذا المثال، نفِّذ أحد الإجراءَين التاليَين، حسب موفّر النموذج الذي اخترته:

‫Gemini (Google AI)

1. تأكَّد من توفّر Google AI في منطقتك.

2. أنشِئ مفتاح واجهة برمجة تطبيقات لـ Gemini API باستخدام Google AI Studio.

3. خزِّن مفتاح واجهة برمجة التطبيقات في Cloud Secret Manager:

   firebase functions:secrets:set GOOGLE_GENAI_API_KEY

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

   لمزيد من المعلومات حول إدارة الأسرار، يُرجى الاطّلاع على مقالة تخزين معلومات الضبط الحسّاسة والوصول إليها.

4. عدِّل الملف src/index.js وأضِف ما يلي بعد عمليات الاستيراد الحالية:

   const {defineSecret} = require("firebase-functions/params");

   // Store the Gemini API key in Cloud Secret Manager.
   const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");
   index.js

   بعد ذلك، في تعريف الدالة القابلة للاستدعاء، أعلِن أنّ الدالة تحتاج إلى الوصول إلى قيمة هذا السر:

   // Bind the Gemini API key secret parameter to the function.
   secrets: [apiKey],
   index.js

الآن، عند نشر هذه الدالة، سيتم تخزين مفتاح واجهة برمجة التطبيقات في Cloud Secret Manager، وسيكون متاحًا من بيئة "وظائف السحابة الإلكترونية".

‫Gemini (Vertex AI)

1. في Cloud Console، فعِّل Vertex AI API لمشروع Firebase.

2. في صفحة إدارة الهوية وإمكانية الوصول ، تأكَّد من منح حساب خدمة Compute التلقائي دور مستخدم Vertex AI.

السر الوحيد الذي عليك إعداده لهذا البرنامج التعليمي هو موفّر النموذج، ولكن بشكل عام، عليك إجراء عملية مماثلة لكل خدمة يستخدمها التدفق.

(اختياري) إضافة فرض فحص التطبيقات

تستخدم ميزة "فحص التطبيقات" في Firebase عملية إثبات الملكية الأصلية للتحقّق من أنّ واجهة برمجة التطبيقات لا يتم استدعاؤها إلا من خلال تطبيقك. تتيح طريقة onCallGenkit فرض ميزة "فحص التطبيقات" بشكل إعلاني.

export const generatePoem = onCallGenkit({
  enforceAppCheck: true,
  // Optional. Makes App Check tokens only usable once. This adds extra security
  // at the expense of slowing down your app to generate a token for every API
  // call
  consumeAppCheckToken: true,
}, generatePoemFlow);

ضبط مشاركة المراجع مع نطاقات خارجية (CORS)

استخدِم الخيار cors للتحكّم في المصادر التي يمكنها الوصول إلى دالتك.

بشكل تلقائي، يتم ضبط مشاركة الموارد المتعدّدة المصادر (CORS) للدوال القابلة للاستدعاء للسماح بالطلبات من جميع المصادر. للسماح ببعض الطلبات المتعدّدة المصادر، وليس كلها، مرِّر قائمة بنطاقات أو تعبيرات عادية محدّدة يجب السماح بها. على سبيل المثال:

export const tellJoke = onCallGenkit({
  cors: 'mydomain.com',
}, jokeTeller);

مثال مُكتمل

بعد إجراء جميع التغييرات الموضّحة أعلاه، سيبدو التدفق القابل للنشر مشابهًا للمثال التالي:

const {onCallGenkit} = require("firebase-functions/https");
const {defineSecret} = require("firebase-functions/params");

// Dependencies for Genkit.
const {gemini15Flash, googleAI} = require("@genkit-ai/googleai");
const {genkit, z} = require("genkit");

// Store the Gemini API key in Cloud Secret Manager.
const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");

const ai = genkit({
  plugins: [googleAI()],
  model: gemini15Flash,
});

const jokeTeller = ai.defineFlow({
  name: "jokeTeller",
  inputSchema: z.string().nullable(),
  outputSchema: z.string(),
  streamSchema: z.string(),
}, async (jokeType = "knock-knock", {sendChunk}) => {
  const prompt = `Tell me a ${jokeType} joke.`;

  // Call the `generateStream()` method to
  // receive the `stream` async iterable.
  const {stream, response: aiResponse} = ai.generateStream(prompt);

  // Send new words of the generative AI response
  // to the client as they are generated.
  for await (const chunk of stream) {
    sendChunk(chunk.text);
  }

  // Return the full generative AI response
  // to clients that may not support streaming.
  return (await aiResponse).text;
},
);

exports.tellJoke = onCallGenkit({
  // Bind the Gemini API key secret parameter to the function.
  secrets: [apiKey],
},
// Pass in the genkit flow.
jokeTeller,
);
index.js

نشر التدفقات على Firebase

بعد تحديد التدفقات باستخدام onCallGenkit، يمكنك نشرها كما تنشر الدوال الأخرى:

cd $PROJECT_ROOT
firebase deploy --only functions