نشر عمليات المعالجة باستخدام "وظائف السحابة الإلكترونية" لبرنامج Firebase

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

قبل البدء

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

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

إذا لم يكن لديك مشروع على Firebase تم إعداده باستخدام TypeScript Cloud Functions، اتّبِع الخطوات التالية:

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

2. عليك ترقية المشروع إلى خطة Blaze، وهي مطلوبة لنشر وظائف Cloud.

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 genkit

   تفترض بقية هذه الصفحة أنّك قرّرت كتابة دوالّك باستخدام TypeScript، ولكن يمكنك أيضًا نشر مسارات Genkit إذا كنت تستخدم JavaScript.

2- لفّ عملية التدفق في onCallGenkit

بعد إعداد مشروع على Firebase باستخدام وظائف Cloud، يمكنك نسخ تعريفات مسارات الإحالات الناجحة أو كتابتها في دليل functions/src للمشروع، وتصديرها في index.ts.

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

لنفترض أنّ لديك المسار التالي:

const generatePoemFlow = ai.defineFlow(
  {
    name: "generatePoem",
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (subject: string) => {
    const { text } = await ai.generate(`Compose a poem about ${subject}.`);
    return text;
  }
);

يمكنك عرض هذا المسار كدالّة قابلة للاستدعاء باستخدام onCallGenkit:

import { onCallGenkit } from 'firebase-functions/https';

export generatePoem = onCallGenkit(generatePoemFlow);

تحديد سياسة تفويض

يجب أن تتضمّن جميع عمليات التنفيذ التي تم نشرها، سواء تم نشرها على Firebase أم لا، سياسة تفويض. وفي حال عدم توفّر سياسة تفويض، يمكن لأي مستخدم استدعاء عمليات تنفيذ الذكاء الاصطناعي التوليدي التي قد تكون باهظة التكلفة. لتحديد سياسة تفويض، استخدِم المَعلمة authPolicy في onCallGenkit:

export const generatePoem = onCallGenkit({
  authPolicy: (auth) => auth?.token?.email_verified,
}, generatePoemFlow);

يستخدم هذا العيّنة دالة يدوية كسياسة مصادقة. بالإضافة إلى ذلك، تُصدِّر مكتبة https مساعِدَي signedIn() وhasClaim(). في ما يلي الرمز نفسه باستخدام أحد هذه الأدوات المساعدة:

import { hasClaim } from 'firebase-functions/https';

export const generatePoem = onCallGenkit({
  authPolicy: hasClaim('email_verified'),
}, generatePoemFlow);

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

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

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

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

إضافة ميزة فرض فحص التطبيق

تستخدِم ميزة فحص التطبيقات من 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. في حال استخدام المصادقة المناسبة (خاصةً App Check)، غالبًا ما تكون سياسة مشاركة الموارد المتعددة المصادر (CORS) غير ضرورية.

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

مثال كامل

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

import { genkit } from 'genkit';
import { onCallGenkit, hasClaim } from 'firebase-functions/https';
import { defineSecret } from 'firebase-functions/params';

const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");

const generatePoemFlow = ai.defineFlow({
  name: "generatePoem",
  inputSchema: z.string(),
  outputSchema: z.string(),
}, async (subject: string) => {
  const { text } = await ai.generate(`Compose a poem about ${subject}.`);
  return text;
});

export const generateFlow = onCallGenkit({
  secrets: [apiKey],
  authPolicy: hasClaim("email_verified"),
  enforceAppCheck: true,
}, generatePoemFlow);

3- نشر عمليات الإعداد إلى Firebase

بعد تحديد مسارات الإحالات الناجحة باستخدام onCallGenkit، يمكنك نشرها بالطريقة نفسها التي ستننشر بها وظائف Cloud Functions الأخرى:

cd $PROJECT_ROOT
firebase deploy --only functions

لقد تم الآن نشر العملية كإحدى وظائف Cloud. ولكن لا يمكنك الوصول إلى نقطة النهاية المنشورة باستخدام curl أو ما شابه، بسبب سياسة تفويض عملية التنقّل. يوضّح القسم التالي كيفية الوصول بأمان إلى المسار.

اختياري: تجربة العملية المنشورة

لتجربة نقطة نهاية المسار، يمكنك نشر المثال التالي على الويب التطبيق البسيط:

1. في قسم إعدادات المشروع ضمن "وحدة تحكّم Firebase"، أضِف تطبيق ويب جديدًا، مع تحديد خيار إعداد ميزة "الاستضافة" أيضًا.

2. في قسم المصادقة ضمن "وحدة تحكّم Firebase"، فعِّل مقدّم الخدمة Google المستخدَم في هذا المثال.

3. في دليل مشروعك، يمكنك إعداد ميزة "استضافة Firebase" التي ستنشر عليها نموذج التطبيق:

   cd $PROJECT_ROOT
   firebase init hosting

   قبول الإعدادات التلقائية لجميع الطلبات

4. استبدِل public/index.html بما يلي:

   <!DOCTYPE html>
   <html>
     <head>
       <title>Genkit demo</title>
     </head>
     <body>
       <div id="signin" hidden>
         <button id="signinBtn">Sign in with Google</button>
       </div>
       <div id="callGenkit" hidden>
         Subject: <input type="text" id="subject" />
         <button id="generatePoem">Compose a poem on this subject</button>
         <p id="generatedPoem"></p>
       </div>
       <script type="module">
         import { initializeApp } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-app.js";
         import {
           getAuth,
           onAuthStateChanged,
           GoogleAuthProvider,
           signInWithPopup,
         } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-auth.js";
         import {
           getFunctions,
           httpsCallable,
         } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-functions.js";
   
         const firebaseConfig = await fetch("/__/firebase/init.json");
         initializeApp(await firebaseConfig.json());
   
         async function generatePoem() {
           const poemFlow = httpsCallable(getFunctions(), "generatePoem");
           const subject = document.querySelector("#subject").value;
           const response = await poemFlow(subject);
           document.querySelector("#generatedPoem").innerText = response.data;
         }
   
         function signIn() {
           signInWithPopup(getAuth(), new GoogleAuthProvider());
         }
   
         document.querySelector("#signinBtn").addEventListener("click", signIn);
         document
           .querySelector("#generatePoem")
           .addEventListener("click", generatePoem);
   
         const signinEl = document.querySelector("#signin");
         const genkitEl = document.querySelector("#callGenkit");
   
         onAuthStateChanged(getAuth(), (user) => {
           if (!user) {
             signinEl.hidden = false;
             genkitEl.hidden = true;
           } else {
             signinEl.hidden = true;
             genkitEl.hidden = false;
           }
         });
       </script>
     </body>
   </html>
   

5. يمكنك نشر تطبيق الويب وCloud Function باتّباع الخطوات التالية:

   cd $PROJECT_ROOT
   firebase deploy

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

اختياري: تشغيل مسارات الإحالات الناجحة في واجهة مستخدم المطوّر

يمكنك تشغيل مسارات الإحالات الناجحة المحدّدة باستخدام onCallGenkit في واجهة مستخدِم المطوّر بالطريقة نفسها التي تُنفِّذ بها مسارات الإحالات الناجحة المحدّدة باستخدام defineFlow، لذا ليس عليك التبديل بينهما بين النشر والتطوير.

cd $PROJECT_ROOT/functions
npx genkit start -- npx tsx --watch src/index.ts

أو

cd $PROJECT_ROOT/functions
npm run genkit:start

يمكنك الآن الانتقال إلى عنوان URL الذي يطبعه الأمر genkit start للوصول إليه.

اختياري: التطوير باستخدام مجموعة أدوات المحاكاة المحلية لمنصة Firebase

يوفّر Firebase مجموعة من المحاكيات لتطوير التطبيقات على الجهاز، ويمكنك استخدامها مع Genkit.

لاستخدام واجهة مستخدم المطوّر في Genkit مع مجموعة محاكيات Firebase، ابدأ محاكيات Firebase على النحو التالي:

npx genkit start -- firebase emulators:start --inspect-functions

يُشغِّل هذا الأمر الرمز البرمجي في المحاكي، ويُشغِّل إطار عمل Genkit في وضع التطوير. يؤدي ذلك إلى تشغيل واجهة برمجة التطبيقات Genkit reflection API وعرضها (وليس واجهة مستخدم المطوّر).

للاطّلاع على عمليات التتبّع من Firestore في واجهة مستخدم المطوّر، يمكنك الانتقال إلى علامة التبويب فحص وتفعيل مفتاح التبديل مطوّر/إصدار علني. عند التبديل إلى prod، يتم تحميل التتبّعات من firestore.