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

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

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

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

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

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

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

   ترقية المشروع إلى خطة Blaze، وهي مطلوبة لنشر السحابة الإلكترونية الدوال.

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 بعض نماذج الملفات المصدر لتبدأ في تطوير مسارات الذكاء الاصطناعي (AI) الخاصة بك. ومع ذلك، في بقية هذا البرنامج التعليمي، ستنشر فقط تدفق العينة.

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

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

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

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

   3. تخزين مفتاح واجهة برمجة التطبيقات في Cloud Secret Manager:

      firebase functions:secrets:set GOOGLE_GENAI_API_KEY
      

      تُعد هذه الخطوة مهمة لمنع تسريب مفتاح واجهة برمجة التطبيقات عن طريق الخطأ، التي تمنح إمكانية الوصول إلى خدمة يُحتمَل أن تكون تفرض تكلفة استخدام

      يُرجى الاطّلاع على تخزين معلومات الإعداد الحساسة والوصول إليها لمزيد من المعلومات حول إدارة الأسرار.

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

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

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

      export const menuSuggestionFlow = onFlow(
        {
          name: "menuSuggestionFlow",
          // ...
          httpsOptions: {
            secrets: [googleAIapiKey],  // Add this line.
          },
        },
        async (subject) => {
          // ...
        }
      );
      

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

   Gemini (Vertex AI)

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

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

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

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

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

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

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

   1. إتاحة بيانات اعتماد واجهة برمجة التطبيقات على الجهاز نفِّذ أيًّا ممّا يلي: بناءً على مزود النموذج الذي اخترته:

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

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

      export GOOGLE_GENAI_API_KEY=<your API key>
      

      Gemini (Vertex AI)

      يمكنك تعيين بعض متغيرات البيئة الإضافية واستخدام gcloud لإعداد الجهاز بيانات الاعتماد التلقائية للتطبيق على الجهاز:

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

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

      cd $PROJECT_ROOT/functions
      genkit start
      

   3. في واجهة مستخدم مطور البرامج (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 (استضافة 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="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، يمكنك الانتقال إلى علامة التبويب "فحص" والتبديل بين "مطوّري البرامج/المنتجات". المبدل (Switch). عند التبديل إلى "إنتاج" سيتمّ تحميل آثار الأنشطة من Firestore.