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

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

قبل البدء

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

إعداد مشروع على Firebase

أنشئ مشروعًا جديدًا على Firebase باستخدام وحدة تحكّم Firebase، أو اختَر مشروعًا حاليًا.
عليك ترقية المشروع إلى خطة Blaze، وهي مطلوبة لنشر Cloud Functions في مرحلة الإنتاج.
ثبِّت Firebase CLI.

سجِّل الدخول باستخدام واجهة Firebase CLI:

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

أنشئ دليل مشروع جديد:

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

ابدأ مشروع 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)

تأكَّد من أنّ تكنولوجيات الذكاء الاصطناعي من Google متوفّرة في منطقتك.
أنشئ مفتاح واجهة برمجة تطبيقات لواجهة برمجة التطبيقات Gemini API باستخدام Google AI Studio.
تخزين مفتاح واجهة برمجة التطبيقات في Cloud Secret Manager:
```
firebase functions:secrets:set GOOGLE_GENAI_API_KEY
```
هذه الخطوة مهمة لمنع تسرُّب مفتاح واجهة برمجة التطبيقات عن طريق الخطأ، والذي يمنح إذن الوصول إلى خدمة قد تكون خاضعة لتعريفات قياسية.

اطّلِع على تخزين معلومات الضبط الحسّاسة والوصول إليها لمزيد من المعلومات عن إدارة الأسرار.
عدِّل 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)

في وحدة تحكّم Cloud، فعِّل واجهة برمجة التطبيقات Vertex AI لمشروعك على Firebase.
في صفحة إدارة الهوية وإمكانية الوصول (IAM)، احرص على منح حساب خدمة 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/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