استدعاء غير متزامن لتطبيق الذكاء الاصطناعي المستند إلى الوكلاء باستخدام الأحداث

1- مقدمة

نظرة عامة

توضّح هذه التجربة العملية كيفية تنفيذ استدعاء مستند إلى الأحداث لوكيل ADK تم نشره على Cloud Run بشكل آمن باستخدام خدمتَي Eventarc وPub/Sub. في معظم الأحيان، يتم استدعاء الوكيل من قِبل مستخدم أو وكيل آخر مباشرةً. ومع ذلك، عند دمج وكيل في مهام سير العمل الحالية المستندة إلى الأحداث، يتطلّب إجراء مكالمة مباشرة إجراء تغييرات على البرامج الحالية. يتيح تشغيل استدعاء وكيل استنادًا إلى حدث دمج وكيل في سير العمل الحالي بدون إجراء تغييرات على سير العمل.

الإجراءات التي ستنفذّها

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

صورة توضيحية لـ Zoo-Keeper

ستنشر تطبيق ZooKeeper كخدمة على Cloud Run، وهو نظام أساسي مُدار بالكامل بدون خادم لتشغيل الحاويات التي لا تتضمّن حالة على بنية Google الأساسية. بعد ذلك، ستُعدّ إعداد مشغّل Eventarc الذي سيستدعي نقطة نهاية الخدمة للتعامل بشكل غير متزامن مع الرسائل المنشورة في موضوع Pub/Sub. عليك التأكّد من أنّ عملية النشر تتّبع أفضل الممارسات، بما في ذلك استخدام حسابات خدمة IAM المخصّصة ومنح الحد الأدنى من امتيازات الوصول وتقليل مساحة سطح الهجوم المحتملة من خلال إتاحة نقطة نهاية تطبيق ZooKeeper لخدمة Eventarc فقط. يمكنك إجراء ذلك بمساعدة Cloud Shell وCloud Console. ستستخدم مكتبات ADK وCloud SDK للغة Python. للتحقّق من السلوك، ستستخدم "واجهة سطر الأوامر في Google Cloud".

أهداف الدورة التعليمية

  • انشر وكيل ADK على Google Cloud Run.
  • دمج مشغّل Eventarc مع وكيل ADK الذي يعمل على Google Cloud Run
  • يمكنك تأمين عملية النشر والتكامل مع Eventarc باستخدام مبدأ الحدّ الأدنى من أذونات الوصول بمساعدة خدمة "إدارة الهوية وإمكانية الوصول" (IAM) من Google Cloud.
  • نشر الرسائل وسحبها من وإلى Pub/Sub
  • تقليل إمكانية وصول الجميع إلى تطبيقك الذي تم نشره على Google Cloud Run

المتطلبات

يُرجى العِلم أنّه يجب أن يكون لحسابك إذن وصول إلى "إدارة الهوية وإمكانية الوصول" في المشروع الذي يتيح لك توفير الموارد وإعداد إذن الوصول إلى "إدارة الهوية وإمكانية الوصول" لهذه الموارد.

† قد تختلف تجربة المستخدم عند استخدام متصفّحات أخرى عن التجربة الموضّحة في المختبر.

‡ قد تكون بعض العمليات الموضّحة في المختبر محدودة عند استخدام حساب تابع لشركة أو مؤسسة تعليمية.

2. إعداد بيئة الاختبار

لضمان توفّر بيئة تطوير تعمل بكامل طاقتها في الدرس التطبيقي، ستستخدم Google Cloud Shell التي تم تثبيت جميع الأدوات اللازمة عليها مسبقًا. اتّبِع التعليمات لإعداد البيئة.

إذا لم يكن لديك حساب على Google، أنشئ حسابًا على Google.

تعليمات الإعداد

  1. استخدِم حسابك على Google لتسجيل الدخول إلى Google Cloud Console.
  2. 👉 افتح أداة اختيار المشاريع في شريط التنقّل العلوي (قد يظهر "اختيار مشروع" أو اسم مشروع حالي) أو انقر على اختصار لوحة المفاتيح Ctrl+O واختَر مشروعًا حاليًا أو أنشئ مشروعًا جديدًا.سيستغرق إنشاء مشروع جديد بضع ثوانٍ. انتظِر إلى أن يصبح جاهزًا، ثم اختَره باستخدام أداة اختيار المشاريع.
  1. 👉 انقر على رمز Cloud Shell في أعلى "وحدة تحكّم Google Cloud". (المحدّد بالمستطيل الأحمر):زر Cloud Shell
    إذا طُلب منك ذلك، انقر على **تفويض** في مربّع الحوار المنبثق للموافقة على استخدام Cloud Shell لبيانات اعتماد حسابك.
    مربّع حوار التفويض
  2. 👉💻 تأكَّد من ضبط gcloud CLI لاستخدام المشروع الذي اخترته (أو أنشأته). نفِّذ الأمر التالي للتحقّق من رقم تعريف المشروع الذي تم ضبطه:
    gcloud config get-value project
    من المفترض أن يظهر لك ناتج مشابه لما يلي:
    Your active configuration is: [cloudshell-19597]
[PROJECT_ID]
    حيث [PROJECT_ID] هو رقم تعريف المشروع الذي اخترته أو أنشأته.👉💻 إذا ظهرت لك قيمة أخرى، شغِّل الأمر التالي لضبط رقم تعريف مشروعك كمعرّف مشروع تلقائي لأوامر gcloud CLI:
    gcloud config set project [YOUR_PROJECT_ID]
    على سبيل المثال، إذا كان معرّف مشروعك هو lab-project-id-example-123، يجب أن يكون الأمر كما يلي:
    gcloud config set project lab-project-id-example-123
    🤔💻 إذا لم تتذكّر رقم تعريف مشروعك، استخدِم الأمر التالي لإدراج جميع أرقام تعريف المشاريع التي يمكنك الوصول إليها بدءًا من الأحدث:
    gcloud projects list \
    --format='value(projectId)' \
    --sort-by='~createTime'
  1. 👉💻 اضبط الموقع الجغرافي لتوفير الموارد ورقم تعريف مشروعك ورقمه في متغيّرات البيئة:
    export LOCATION="us-central1"
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
  2. 👉💻 فعِّل واجهات Google APIs المطلوبة لهذا المختبر.
    gcloud services enable \
    aiplatform.googleapis.com \
    eventarc.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    pubsub.googleapis.com
    يُرجى الانتظار قليلاً لأنّ هذا الأمر قد يستغرق بضع دقائق. عند تنفيذ الأمر بنجاح، من المفترض أن تظهر لك رسالة مشابهة لما يلي:
    Operation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.

3- نشر تطبيق ZooKeeper التجريبي

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

إعداد موارد Pub/Sub

ستنشئ موضوعَين على Pub/Sub. سيتم استخدام أحدهما من قِبل خدمة تابعة لجهة خارجية لإرسال الأحداث إلى تطبيق الذكاء الاصطناعي المستند إلى الوكلاء. وآخر لنشر نتائج معالجة الحدث.

  1. 👉💻 أنشئ موضوعًا على Pub/Sub يُستخدَم لتشغيل تطبيق الذكاء الاصطناعي المستند إلى الوكلاء:
    gcloud pubsub topics create invoke_agent
export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)")
  2. 👉💻 أنشئ موضوعًا على Pub/Sub يمكن للتطبيق نشر ردوده فيه:
    gcloud pubsub topics create agent_responses
export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)")
gcloud pubsub subscriptions create agent_responses \
    --topic=agent_responses
    تنشئ هذه الأوامر أيضًا اشتراكًا في موضوع Pub/Sub الذي تم إنشاؤه. سيتم استخدام الاشتراك عند تشغيل العرض التوضيحي كطريقة لعرض النتائج.

إعداد حسابات الخدمة وسياسات إدارة الهوية وإمكانية الوصول على مستوى المشروع

ستنشئ حسابَي خدمة للحدّ من نطاق الوصول إلى خدمة Cloud Run ومشغّل Eventarc إلى الحدّ الأدنى وفقًا لمبدأ الحدّ الأدنى من الأذونات. تتطلّب خدمة Cloud Run أذونات لكتابة السجلات وعمليات التتبُّع، ولطلب نموذج اللغة الكبير Gemini على Google Vertex AI، ولنشر النتائج في موضوع Pub/Sub. يتطلّب الحدّ الأدنى من أذونات الوصول إلى مشغّل Eventarc أذونات لاستدعاء خدمة Cloud Run ZooKeeper والوصول إلى Pub/Sub لقراءة الأحداث المنشورة. ترشدك هذه التعليمات إلى كيفية منح حساب خدمة المشغّل الأذونات اللازمة لانتحال هوية خدمة نظام Pub/Sub. بعد إنشاء مورد مشغّل Eventarc، ستنفّذ الأمر الذي يمنح الدور roles/run.invoker لتفعيل حساب خدمة المشغّل من أجل استدعاء خدمة Cloud Run.

  1. 👉💻 أنشئ حساب خدمة لخدمة Cloud Run:
    gcloud iam service-accounts create zookeeper-cloudrun-sa
export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com"
  2. 👉💻 امنح حساب الخدمة أذونات لكتابة السجلات وعمليات التتبُّع واستخدام نماذج Gemini على Vertex AI:
    gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member="serviceAccount:${ZOOKEEPER_SA}" \
     --role="roles/logging.logWriter" \
     --condition=None
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:${ZOOKEEPER_SA}" \
    --role="roles/cloudtrace.agent" \
    --condition=None
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:${ZOOKEEPER_SA}" \
    --role="roles/aiplatform.user" \
    --condition=None
  3. 👉💻 امنح حساب الخدمة أذونات لنشر الرسائل في الموضوع "agent_responses":
    gcloud pubsub topics add-iam-policy-binding agent_responses \
    --member="serviceAccount:${ZOOKEEPER_SA}" \
    --role="roles/pubsub.publisher"
  4. 👉💻 أنشئ حساب خدمة للمشغّل في Eventarc:
    gcloud iam service-accounts create zookeeper-trigger-sa
export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com"
  5. 👉💻 امنح أذونات حساب خدمة نظام Pub/Sub لإجراء طلبات إرسال مصادَق عليها:
    gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"
    هذا الأمر اختياري إذا تم إنشاء مشروع بعد 8 أبريل 2021.

نشر تطبيق ZooKeeper على Cloud Run

عليك تنزيل رمز التطبيق التجريبي من GitHub. ونشر الرمز في Cloud Run

  1. 👉💻 نزِّل تطبيق الذكاء الاصطناعي الوكيل:
    mkdir zoo-keeper-lab && cd zoo-keeper-lab
git init
git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos
git config set core.sparseCheckout true
echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout
git pull origin main --depth 1
cd ai-ml/agent-labs/adk_invoke_with_pubsub/
    تستخدم هذه الأوامر ميزة "استخراج الملفات المتفرقة" في Git للمجلد الذي يحتوي على التطبيق التجريبي لتقليل وقت التنزيل.
  2. 👉💻 نشر تطبيق الذكاء الاصطناعي الوكيل على Cloud Run:
    gcloud run deploy zookeeper-agent \
    --region="${LOCATION}" \
    --source="." \
    --no-allow-unauthenticated \
    --quiet \
    --service-account="${ZOOKEEPER_SA}" \
    --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"

ضبط مشغّل Eventarc

بعد إعداد جميع الموارد (مواضيع Pub/Sub وحسابات الخدمة في "إدارة الهوية وإمكانية الوصول" وخدمة Cloud Run)، حان الوقت لإعداد مورد مشغّل Eventarc. ستنشئ مورد مشغّل Eventarc وتمنح الأذونات اللازمة لاستدعاء خدمة Cloud Run إلى حساب خدمة المشغّل.

  1. 👉💻 إنشاء مشغّل Eventarc:
    gcloud eventarc triggers create invoke-agent \
    --location="${LOCATION}" \
    --destination-run-service="zookeeper-agent" \
    --destination-run-path="/zookeeper" \
    --destination-run-region="${LOCATION}" \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic="${INVOKE_TOPIC_ID}" \
    --service-account="${TRIGGER_SA}"
  2. 👉💻 امنح أذونات لحساب خدمة المشغّل لاستدعاء خدمة Cloud Run:
    gcloud run services add-iam-policy-binding zookeeper-agent \
    --region="${LOCATION}" \
    --member="serviceAccount:${TRIGGER_SA}" \
    --role="roles/run.invoker"

4. مراجعة طريقة عمل الحلّ

الآن، راجِع ما تم نشره للتو. يعكس المخطّط التالي جميع المراجع وكيفية تفاعلها مع بعضها البعض. ستستخدم gcloud CLI لنشر رسالة في الموضوع invoke_agent. سيؤدي ذلك إلى محاكاة حدث تسجّله خدمة خارجية في خدمة المراسلة لاستدعاء تطبيق الذكاء الاصطناعي المستند إلى الوكلاء.

مخطط الحلّ

يتم تأمين عملية النشر باتّباع مبدأ الحدّ الأدنى من أذونات الوصول. تفرض خدمة Cloud Run المصادقة (راجِع الوسيطة --no-allow-unauthenticated في الخطوة رقم 9 في القسم السابق). يمكن فقط للهويات التي لديها أدوار/run.invoker أو أذونات مشابهة استدعاء الخدمة. ويتم منح هذا الدور فقط لحساب الخدمة الخاص بمشغّل Eventarc. وبالمثل، يتم تقليل إذن الوصول إلى موضوع invoke_agent لمنع نشر الأحداث بدون إذن. سيظلّ بإمكانك استدعاء وكيل ZooKeeper مباشرةً بدون نشر الرسالة في موضوع Pub/Sub. راجِع القسم 6 لمعرفة كيفية إخفاء نقطة نهاية التطبيق عن الوصول العام.

تشغيل سير العمل

ستحاكي حدثًا خارجيًا من خلال نشر سؤال باللغة الطبيعية على ZooKeeper.

👉💻 استخدِم الأمر التالي لنشر رسالة في موضوع Pub/Sub:

gcloud pubsub topics publish invoke_agent \
    --message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'

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

يمكنك التأكّد من أنّ الوكيل قد تلقّى الحدث، وعالج الطلب، ونشر الردّ في موضوع agent_responses. لقراءة الردّ، ستستخدم اشتراك agent_responses (يستخدم برنامج codelab المعرّف نفسه لكلّ من الموضوع والاشتراك في الردود).

👉💻 استخدِم الأمر التالي لقراءة ردّ الوكيل من اشتراك Pub/Sub:

gcloud pubsub subscriptions pull agent_responses --auto-ack

سيعرض الناتج جدولاً يتضمّن البيانات الوصفية للرسالة والحمولة التي تحتوي على الإجابة التي تفيد بأنّ هناك 33 نوعًا من الحيوانات في حديقة الحيوانات. تعترف العلامة --auto-ack تلقائيًا بالرسالة بعد سحبها، لذلك لن يتم تسليمها مرة أخرى.

آلية العمل

يمكنك الاطّلاع على رمز المصدر لتطبيق الذكاء الاصطناعي المستند إلى الوكلاء من خلال فتح محرّر Cloud Shell وعرض الملفات ضمن المجلد ~/zoo-keeper-lab. يمكنك أيضًا الاطّلاع على رمز المصدر على GitHub.

  • ينفّذ الملف main.py تطبيق ويب أساسيًا باستخدام FastAPI مع معالج واحد يعالج أحداث Eventarc.
  • يحلّل الملف processor.py رسالة الحدث لاسترداد رقم تعريف المستخدم والطلب. بعد ذلك، يتم إنشاء جلسة جديدة في برنامج تشغيل ADK ويتم استدعاء وكيل Zookeeper لمعالجة الطلب. يتم نشر الردّ من الوكيل في موضوع Pub/Sub الذي يحمل الاسم agent_responses.
  • يستضيف المجلد الفرعي zookeeper_agent رمز المصدر لوكيل ADK. يمكنك تنفيذ الأمر adk run zookeeper_agent من المجلد الجذر للتطبيق للتفاعل مع البرنامج باستخدام adk CLI.

كيفية تحديد المشاكل وحلّها

في حال تعذُّر تنفيذ أي من الأوامر السابقة، اقرأ رسالة الخطأ بعناية. إذا تعذّر نشر التطبيق على Cloud Run، ستكون الخطوة الأولى هي تحديد مرحلة العملية التي حدث فيها الخطأ.

  • إذا أظهرت نتائج تنفيذ الأمر "gcloud run deploy..." تعذُّر إنشاء الإصدار، اطّلِع على عنوان URL لسجلات الإنشاء في النتائج وافتحه في نافذة منفصلة.
  • إذا كانت النتيجة تعرض رسالة مثل "تعذّر بدء الخدمة" أو رسالة مشابهة، يعني ذلك أنّ الخدمة يتم نشرها ولكنّ التنفيذ يتعذّر في عملية التحقّق من الصحة. في هذه الحالة، افتح "مستكشف السجلات" أو اطّلِع على الفقرة التالية لمعرفة أمر gcloud CLI. قراءة السجلات للعثور على السبب الجذري للخطأ

ماذا يحدث إذا نشرت رسالة على Pub/Sub ولكن لم يستجب الوكيل أو بدا الرد غريبًا؟

👉💻 استخدِم الأمر التالي لقراءة سجلّات التطبيق المنشورة من التنفيذ الأخير:

gcloud logging read \
    'resource.type = "cloud_run_revision" AND \
     resource.labels.service_name = "zookeeper-agent" AND \
     resource.labels.location = "us-central1"'

تتتبّع السجلات عملية التنفيذ وتُبلغ عن أخطاء مثل حمولة الرسالة غير الصحيحة أو التي لا يمكن تحليلها، والاستجابة غير الصالحة من نموذج Gemini، وإعدادات البيئة غير الصالحة، والمشاكل المحتملة الأخرى.

5- تعزيز أمان عملية النشر

تعرض خدمة Cloud Run التي نشرتها نقطة نهاية عامة يمكن لأي مستخدم على الإنترنت استدعاؤها. على الرغم من أنّ نقطة النهاية محمية من الاستدعاء غير المصرّح به وتتحقّق بدقة من بنية الطلب، إلا أنّها لا تزال تتيح هذا النوع من الهجمات التي تسمح بهجمات حجب الخدمة وحجب المحفظة. بما أنّ مسار الاستدعاء الوحيد للخدمة في التصميم الحالي هو من خلال مشغّل Eventarc، لا تحتاج الخدمة إلى عرض نقطة النهاية الخاصة بها على الإنترنت.

👉💻 يمكنك إغلاق متجه الهجوم هذا من خلال حصر المكالمات التي يتم إجراؤها إلى الخدمة على مجموعة محدودة من المصادر، بما في ذلك مشغّلات Eventarc:

gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal

الآن، إذا حاولت طلب عنوان URL الخاص بالخدمة من جهازك المحلي، ستظهر لك رسالة الخطأ "404: لم يتم العثور على الصفحة".

👉💻 استخدِم curl لإرسال طلب إلى نقطة نهاية الخدمة:

URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"

ستظهر لك نتيجة مماثلة لما يلي:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>404 Page not found</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Page not found</h1>
<h2>The requested URL was not found on this server.</h2>
<h2></h2>
</body></html>

بعد هذا التغيير، لن يكون من الممكن استدعاء ZooKeeper مباشرةً من خلال طلب نقطة نهاية خدمة Cloud Run، إلا إذا أجريت الطلب من شبكة VPC في المشروع نفسه أو شبكة VPC المشتركة التي تم ضبط المراجعة لإرسال الزيارات إليها أو مضيف يشكّل جزءًا من حيّز عناصر التحكّم في خدمة VPC.

6. ملخّص

تهانينا! لقد أعددت بنجاح بيئة لتشغيل تطبيق الذكاء الاصطناعي المستند إلى الوكلاء بشكل غير متزامن عند تفعيله بواسطة الأحداث الواردة.

تَنظيم

يُرجى العِلم أنّ الاحتفاظ بالموارد التي تم توفيرها قد يؤدي إلى فرض رسوم على حساب الفوترة. إذا كنت لا تخطّط لاستخدام هذه البيئة لإجراء المزيد من التجارب ولتجنُّب الرسوم القادمة، ننصحك بحذف الموارد التي تم إنشاؤها أثناء هذا الدرس التطبيقي.

هناك طريقتان لإجراء ذلك:

الطريقة 1: إيقاف المشروع

يؤدي إيقاف المشروع (حذفه) إلى تحرير جميع موارد المشروع وبياناته وإلغاء ربط حساب الفوترة. يمنع استخدام هذه الطريقة فرض رسوم إضافية على أي موارد أو بيانات مستخدَمة في هذا الدرس العملي. استخدِم الأمر التالي لإيقاف المشروع:

gcloud projects delete $(gcloud config get-value project) --quiet

الطريقة 2: حذف الموارد في المشروع

يؤدي حذف خدمة Cloud Run إلى الحماية من فرض رسوم إضافية مقابل استخدام المنصة بدون خادم. يُرجى العِلم أنّ هذه الطريقة لا تزيل بشكل كامل جميع البيانات التي تم إنشاؤها أثناء تجربة الدرس العملي، مثل سجلات Cloud Build والتطبيقات وصور الحاويات وما إلى ذلك. نفِّذ الأمر التالي لحذف الخدمة:

gcloud run services delete zookeeper-agent --region=${LOCATION}

لا يفرض تعريف مشغّل Eventarc ومواضيع Pub/Sub تكاليف إدارة (راجِع أسعار Eventarc وأسعار Pub/Sub لمزيد من التفاصيل).

مزيد من المعلومات حول إيقاف المشروع

الخطوات التالية