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

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

قبل البدء

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

إعداد مشروع Firebase

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

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

  3. ثبِّت Firebase CLI.

  4. سجِّل الدخول إلى واجهة سطر الأوامر (CLI) في Firebase:

    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;
},
);

لتفعيل تدفّق مشابه لهذا التدفّق، عليك تضمينه في 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,
);

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

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

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

‫Gemini (الذكاء الاصطناعي من Google)

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

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

    firebase functions:secrets:set GOOGLE_GENAI_API_KEY

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

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

  3. عدِّل 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");

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

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

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

‫Gemini (Vertex AI)

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

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

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

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

تستخدم خدمة Firebase App Check ميزة "التصديق الأصلي" للتأكّد من أنّ تطبيقك هو وحده الذي يطلب بيانات من واجهة برمجة التطبيقات. تتيح الطريقة 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/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,
);

نشر سير العمل على Firebase

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

cd $PROJECT_ROOT
firebase deploy --only functions