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

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

قبل البدء

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

إعداد مشروع Firebase

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

2. رقِّي المشروع إلى خطة Blaze، وهي مطلوبة لنشر Cloud Functions في مرحلة الإنتاج.

3. ثبِّت Firebase CLI.

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 باستخدام Cloud Functions، يمكنك نسخ تعريفات سير العمل أو كتابتها في الدليل 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/v2/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)

1. تأكَّد من أنّ تكنولوجيات الذكاء الاصطناعي من Google متوفرة في منطقتك.

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، وسيكون متاحًا من بيئة Cloud Functions.

Gemini (Vertex AI)

1. في Cloud Console، فعِّل واجهة برمجة التطبيقات Vertex AI API لمشروعك على Firebase.

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

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

(اختياري) إضافة تنفيذ App Check

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

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/v2/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