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

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

قبل البدء

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

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

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

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

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

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

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

4. أنشئ دليل مشروع جديدًا:

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

5. اضبط مشروع Firebase في الدليل:

   cd $PROJECT_ROOT
   firebase init genkit

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

2- تعديل تعريفات خطوات التحديث

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

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

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

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

توضّح الأقسام التالية التغييرات التي يجب إجراؤها قبل التمكّن من نشرها.

تحديد عمليات التدفق باستخدام onFlow

بدلاً من تحديد مسار الإحالة الناجحة باستخدام Genkit.defineFlow()، استخدِم الدالة onFlow() في الإضافة Firebase. يؤدي استخدام هذه الدالة إلى لفّ منطق المسار في معالج طلبات Cloud Functions، على غرار onCall.

import { onFlow } from "@genkit-ai/firebase/functions";

export const generatePoem = onFlow(
  ai,
  {
    // ...
  },
  async (subject: string) => {
    // ...
  }
);

يُرجى العِلم أنّ onFlow ليست طريقة في Genkit، بل هي دالة تأخذ مثيل Genkit كمَعلمتها الأولى. بخلاف ذلك، تكون الصيغة مشابهة لصيغة defineFlow.

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

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

import { firebaseAuth } from "@genkit-ai/firebase/auth";

export const generatePoem = onFlow(
  ai,
  {
    name: "generatePoem",
    // ...
    authPolicy: firebaseAuth((user, input) => {
      if (!user.email_verified) {
        throw new Error("Verified email required to run flow");
      }
    }),
  },
  async (subject: string) => {
    // ...
  }
);

تستخدِم هذه السياسة المساعدة firebaseAuth() للسماح بالوصول فقط إلى مستخدمي تطبيقك المسجّلين الذين لديهم عناوين بريد إلكتروني تم إثبات ملكيتها. على جانب العميل، عليك ضبط عنوان Authorization: Bearer على رمز تعريف Firebase الذي يستوفي سياستك. توفّر حِزم تطوير البرامج (SDK) لعملاء Cloud Functions طُرقًا للدوالّ القابلة للاستدعاء تُجري ذلك تلقائيًا. اطّلِع على القسم تجربة العملية المنشورة للحصول على مثال.

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

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

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

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

ضبط سياسة مشاركة الموارد المتعدّدة المصادر (CORS)

إذا كنت ستتمكّن من الوصول إلى العملية من تطبيق ويب (ويمكنك إجراء ذلك في قسم تجربة العملية المنشورة)، عليك ضبط سياسة CORS في المَعلمة httpsOptions:

export const generatePoem = onFlow(
  ai,
  {
    name: "generatePoem",
    // ...
    httpsOptions: {
      cors: '*',
    },
  },
  async (subject: string) => {
    // ...
  }
);

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

مثال كامل

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

const googleAIapiKey = defineSecret("GOOGLE_GENAI_API_KEY");

export const generatePoem = onFlow(
  ai,
  {
    name: "generatePoem",
    inputSchema: z.string(),
    outputSchema: z.string(),
    authPolicy: firebaseAuth((user, input) => {
      if (!user.email_verified) {
        throw new Error("Verified email required to run flow");
      }
    }),
    httpsOptions: {
      secrets: [googleAIapiKey],
      cors: '*',
    },
  },
  async (subject: string) => {
    const { text } = await ai.generate(`Compose a poem about ${subject}.`);
    return text;
  }
);

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

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

cd $PROJECT_ROOT
firebase deploy --only functions

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

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

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

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

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

3. في دليل مشروعك، اضبط إعدادات Firebase Hosting، حيث سيتم نشر نموذج التطبيق:

   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، وبعد ذلك يمكنك بدء طلبات نقاط النهاية.

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

يمكنك تشغيل مسارات الإحالات الناجحة المحدّدة باستخدام onFlow في واجهة مستخدِم المطوّر بالطريقة نفسها تمامًا التي تستخدمها لتشغيل مسارات الإحالات الناجحة المحدّدة باستخدام 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.