نشر عمليات المعالجة باستخدام Cloud Run

يمكنك نشر مسارات Genkit كمحطات نهاية HTTPS باستخدام Cloud Run. تتوفّر في Cloud Run عدة خيارات للنشر، بما في ذلك النشر المستنِد إلى الحاوية. ستوضّح هذه الصفحة كيفية نشر مسارات الإحالات الناجحة مباشرةً من الرمز البرمجي.

قبل البدء

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

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

إذا لم يسبق لك إعداد مشروع على Google Cloud، اتّبِع الخطوات التالية:

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

2. ربط المشروع بحساب فوترة، وهو مطلوب لخدمة Cloud Run

3. اضبط Google Cloud CLI لاستخدام مشروعك:

   gcloud init

2- تحضير مشروع Node للنشر

لكي تتمكّن من نشر مسارات الإحالات الناجحة، عليك إجراء بعض التغييرات البسيطة على رمز مشروعك:

إضافة نصوص التشغيل والإنشاء إلى package.json

عند نشر مشروع Node.js على Cloud Run، تتوقّع أدوات النشر أن يحتوي مشروعك على نص start ونص build اختياريًا. بالنسبة إلى مشروع TypeScript نموذجي، تكون النصوص البرمجية التالية عادةً كافية:

"scripts": {
  "start": "node lib/index.js",
  "build": "tsc"
},

إضافة رمز لضبط خادم التدفق وبدء تشغيله

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

عند إجراء المكالمة، حدِّد مسارات الإحالات الناجحة التي تريد عرضها:

ai.startFlowServer({
  flows: [menuSuggestionFlow],
});

هناك أيضًا بعض المَعلمات الاختيارية التي يمكنك تحديدها:

• ‫port: منفذ الشبكة الذي سيتم الاستماع إليه في حال عدم تحديده، يستمع الخادم إلى المنفذ المحدّد في متغيّر البيئة PORT، وإذا لم يتم ضبط PORT، يكون الإعداد التلقائي هو 3400.
• cors: سياسة مشاركة الموارد المتعددة المصادر (CORS) لخادم سير العمل إذا كنت ستستخدم هذه نقاط النهاية من تطبيق ويب، من المرجّح أن تحتاج إلى تحديد ذلك.
• pathPrefix: بادئة مسار اختيارية لإضافتها قبل نقاط نهاية المسار
• jsonParserOptions: خيارات يتم تمريرها إلى أداة تحليل محتوى JSON في Express

اختياري: تحديد سياسة تفويض

يجب أن تتطلّب جميع عمليات التنفيذ نوعًا من التفويض، وإلا يمكن لأي شخص تنفيذ عمليات الذكاء الاصطناعي التوليدي التي قد تكون باهظة التكلفة.

عند نشر عملياتك باستخدام Cloud Run، يتوفّر لك خياران لمنح الإذن:

• التفويض المستنِد إلى إدارة الهوية والوصول في Cloud: استخدِم ميزات إدارة الوصول المضمّنة في Google Cloud لفرض قيود على الوصول إلى نقاط النهاية. اطّلِع على المصادقة في مستندات Cloud Run للحصول على معلومات عن تقديم بيانات الاعتماد هذه.

• سياسة التفويض المحدّدة في الرمز البرمجي: استخدِم ميزة سياسة التفويض في تدفّقات Genkit للتحقّق من معلومات التفويض باستخدام رمز مخصّص. وغالبًا ما يكون هذا التفويض مستندًا إلى رمز مميّز، ولكن ليس بالضرورة.

إذا كنت تريد تحديد سياسة تفويض في الرمز، استخدِم المَعلمة authPolicy في تعريف العملية:

const myFlow = ai.defineFlow(
  {
    name: "myFlow",
    authPolicy: (auth, input) => {
      if (!auth) {
        throw new Error("Authorization required.");
      }
      // Custom checks go here...
    },
  },
  async () => {
    // ...
  }
);

تأتي المَعلمة auth لسياسة التفويض من السمة auth لكائن الطلب. يتم عادةً ضبط هذه السمة باستخدام الوسيط Express. اطّلِع على التفويض والنزاهة.

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

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

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

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

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

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

3. إتاحة مفتاح واجهة برمجة التطبيقات في بيئة Cloud Run:

   1. في Cloud Console، فعِّل Secret Manager API.
   2. في صفحة مدير الأسرار ، أنشئ سرًا جديدًا يحتوي على مفتاح واجهة برمجة التطبيقات.
   3. بعد إنشاء المفتاح السري، في الصفحة نفسها، امنح حساب الخدمة التلقائي لحساب الحوسبة إذن الوصول إلى المفتاح السري باستخدام دور مُستخدِم مفتاح سري مدير. (يمكنك البحث عن اسم حساب الخدمة التلقائي لخدمات الحوسبة في صفحة "إدارة الهوية وإمكانية الوصول").

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

Gemini (Vertex AI)

1. في Cloud Console، فعِّل واجهة برمجة التطبيقات Vertex AI API لمشروعك.

2. في صفحة إدارة الهوية وإمكانية الوصول (IAM)، احرص على منح حساب خدمة Compute التلقائي دور مستخدم Vertex AI.

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

3- نشر عمليات التنفيذ إلى Cloud Run

بعد إعداد مشروعك للنشر، يمكنك نشره باستخدام أداة gcloud.

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

gcloud run deploy --update-secrets=GOOGLE_GENAI_API_KEY=<your-secret-name>:latest

Gemini (Vertex AI)

gcloud run deploy

ستطلب منك أداة النشر أي معلومات مطلوبة.

عندما يُطلب منك السماح بطلبات التفعيل غير المعتمَدة:

• حدِّد الإجابة Y إذا كنت لا تستخدم "إدارة الهوية وإمكانية الوصول" وكنت قد حدّدت بدلاً من ذلك سياسة تفويض في الرمز البرمجي.
• أدخِل N لضبط خدمتك على طلب بيانات اعتماد إدارة الهوية وإمكانية الوصول.

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

بعد انتهاء عملية النشر، ستطبع الأداة عنوان URL للخدمة. يمكنك اختباره باستخدام curl:

curl -X POST https://<service-url>/menuSuggestionFlow \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" -d '{"data": "banana"}'