استدعاء عمليات 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 console، أو اختر مشروعًا حاليًا.

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

لنشر سير عمل مثل هذا، عليك تضمينه في 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 Console، فعِّل 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 للتحكّم في المصادر التي يمكنها الوصول إلى دالتك.

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

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