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

1. مقدمة

نظرة عامة

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

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

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

رسم توضيحي لشخص يعمل في حديقة حيوانات

ستنشر تطبيق 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
    من المفترض أن يظهر لك ناتج مشابه لما يلي:
    استبدِل [PROJECT_ID] برقم تعريف المشروع الذي اخترته أو أنشأته.👉💻 إذا ظهرت لك قيمة أخرى، شغِّل الأمر التالي لضبط رقم تعريف مشروعك كمعرّف مشروع تلقائي لأوامر gcloud CLI:
    Your active configuration is: [cloudshell-19597]
[PROJECT_ID]

    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 لمزيد من التفاصيل).

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

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