Genkit مع وظائف السحابة الإلكترونية في Firebase

يشتمل Firebase Genkit على مكوّن إضافي يساعدك في تفعيل مساراتك إلى دوال السحابة في Firebase. ترشدك هذه الصفحة، كمثال، خلال عملية نشر تدفق النموذج الافتراضي في Firebase.

نشر التدفق كدالة Cloud

1. تثبيت الأدوات المطلوبة:

   1. تأكّد من استخدام الإصدار 20 من Node.js أو إصدار أحدث (شغِّل node --version للتحقّق).

   2. ثبِّت واجهة سطر الأوامر في Firebase.

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

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

3. تسجيل الدخول باستخدام واجهة سطر الأوامر في Firebase:

   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 باستخدام Genkit في المجلد:

   cd $PROJECT_ROOT
   firebase init genkit
   

   • اختَر المشروع الذي أنشأته سابقًا.
   • اختَر موفِّر الطراز الذي تريد استخدامه.

   اقبل الإعدادات التلقائية للطلبات المتبقية. ستنشئ أداة "genkit" بعض نماذج ملفات المصدر لتبدأ في تطوير مسارات الذكاء الاصطناعي الخاصة بك. ومع ذلك، في بقية هذا البرنامج التعليمي، ستنشر فقط تدفق العينة.

6. إتاحة بيانات اعتماد واجهة برمجة التطبيقات لوظيفة السحابة الإلكترونية نفِّذ أحد الإجراءات التالية، حسب موفِّر النموذج الذي اخترته:

   Gemini (تكنولوجيات الذكاء الاصطناعي من Google)

   1. تأكَّد من أنّ تكنولوجيات الذكاء الاصطناعي من Google متاحة في منطقتك.

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

   3. اضبط متغيّر البيئة GOOGLE_GENAI_API_KEY على المفتاح:

      export GOOGLE_GENAI_API_KEY=<your API key>
      

   4. تعديل src/index.ts وإضافة ما يلي بعد عمليات الاستيراد الحالية:

   import {defineSecret} from "firebase-functions/params";
   defineSecret("GOOGLE_GENAI_API_KEY");
   

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

   Gemini (Vertex AI)

   1. في Cloud Console، عليك تفعيل Vertex AI API لمشروعك على Firebase.

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

   3. اختياري: إذا كنت تريد تنفيذ التدفق محليًا، كما في الخطوة التالية، عليك ضبط بعض متغيرات البيئة الإضافية واستخدام أداة gcloud لإعداد بيانات الاعتماد التلقائية للتطبيق:

      export GCLOUD_PROJECT=<your project ID>
      export GCLOUD_LOCATION=us-central1
      gcloud auth application-default login
      

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

7. إذا كنت ستصل إلى التدفق من تطبيق ويب (وهو ما ستفعله في القسم التالي)، في معلَمة httpsOptions، اضبط سياسة CORS:

   export const menuSuggestionFlow = onFlow(
     {
       name: "menuSuggestionFlow",
       // ...
       httpsOptions: {cors: true}, // Add this line.
     },
     async (subject) => {
       // ...
     }
   );
   

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

8. اختياري: يمكنك تجربة المسار في واجهة مستخدم المطوّر:

   1. بدء واجهة المستخدم:

      cd $PROJECT_ROOT/functions
      genkit start
      

   2. في واجهة مستخدم مطور البرامج (http://localhost:4000/)، شغّل التدفق:

      1. انقر على mesuggestionFlow.

      2. في علامة التبويب Input JSON، قدِّم موضوعًا للنموذج:

         "AI app developers"
         

      3. في علامة التبويب Auth JSON، قدِّم كائن مصادقة تمت محاكاته:

         {
           "uid": 0,
           "email_verified": true
         }
         

      4. انقر على تشغيل.

9. إذا كان كل شيء يسير على ما يرام حتى الآن، يمكنك نشر التدفق:

   cd $PROJECT_ROOT
   firebase deploy --only functions
   

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

تجربة التدفق المنشور

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

يخضع مسار النموذج التلقائي لسياسة تفويض مثل ما يلي:

firebaseAuth((user) => {
  if (!user.email_verified) {
    throw new Error('Verified email required to run flow');
  }
});

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

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

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="suggestMenuItem">Suggest a menu theme</button>
         <p id="menuItem"></p>
       </div>
       <script type="module">
         import { initializeApp } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-app.js';
         import {
           getAuth,
           onAuthStateChanged,
           GoogleAuthProvider,
           signInWithPopup,
         } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-auth.js';
         import {
           getFunctions,
           httpsCallable,
         } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-functions.js';
   
         const firebaseConfig = await fetch('/__/firebase/init.json');
         initializeApp(await firebaseConfig.json());
   
         async function generateMenuItem() {
           const menuSuggestionFlow = httpsCallable(
             getFunctions(),
             'menuSuggestionFlow'
           );
           const subject = document.querySelector('#subject').value;
           const response = await menuSuggestionFlow(subject);
           document.querySelector('#menuItem').innerText = response.data;
         }
   
         function signIn() {
           signInWithPopup(getAuth(), new GoogleAuthProvider());
         }
   
         document
           .querySelector('#signinBtn')
           .addEventListener('click', signIn);
         document
           .querySelector('#suggestMenuItem')
           .addEventListener('click', generateMenuItem);
   
         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، ويمكنك بعد ذلك تقديم طلبات نقاط النهاية.

التطوير باستخدام "حزمة أدوات المحاكاة المحلية من Firebase"

يوفّر Firebase حزمة من أدوات المحاكاة للتطوير المحلي التي يمكنك استخدامها مع Genkit.

لاستخدام Genkit مع Firebase Emulator Suite، ابدأ محاكيات Firebase على النحو التالي:

GENKIT_ENV=dev firebase emulators:start --inspect-functions

سيؤدي ذلك إلى تشغيل الرمز الخاص بك في المحاكي وتشغيل إطار عمل Genkit في وضع التطوير، الذي يطلق ويكشف واجهة برمجة تطبيقات الانعكاس Genkit (وليس واجهة مستخدم Dev).

بعد ذلك، يمكنك تشغيل واجهة مستخدم Genkit Dev مع الخيار --attach لربطها بالرمز البرمجي الذي يتم تشغيله داخل "محاكي Firebase":

genkit start --attach http://localhost:3100 --port 4001

للاطّلاع على آثار الأنشطة من Firestore في واجهة مستخدم Dev، يمكنك الانتقال إلى علامة التبويب "فحص" وتبديل مفتاح "مطوّر البرامج/الإنتاج" إلى علامة التبويب "فحص". عند التبديل إلى "إنتاج"، سيتم تحميل بيانات آثار الأنشطة من Firestore.