من النية إلى البنية التحتية: نقل البيانات المستند إلى الوكيل إلى GKE

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام وكيل ذكاء اصطناعي لإجراء عملية نقل معقّدة للبنية الأساسية تلقائيًا. بدلاً من كتابة بيانات Kubernetes يدويًا أو تنفيذ نصوص برمجية مبرمَجة، يمكنك التعبير عن نيّتك باللغة الطبيعية، وسيستخدم الوكيل بروتوكول Model Context (MCP) وخادم Gemini Cloud Assist لإنشاء الإعداد وتطبيقه نيابةً عنك.

إمكانات خادم MCP في GCA

يوفّر خادم MCP التابع لـ GCA للوكيل عدة أدوات متخصصة:

  • ask_cloud_assist: هذه هي الواجهة الأساسية للحصول على المساعدة في Google Cloud Platform وللوصول إلى وكيل Gemini Cloud Assist. يمكن الوصول إلى جميع وظائف Gemini Cloud Assist من خلال هذه الأداة، وهي تشمل وظائف أدوات MCP الأخرى.
  • design_infra: تتيح هذه الأداة سير العمل اللازم لتصميم البنية الأساسية ووضع هيكلها على Google Cloud Platform.
  • investigate_issue: تتيح هذه الأداة سير عمل لتحديد المشاكل وحلّها في Google Cloud. يمكنه إجراء تحديد سريع للمشاكل أو تحديد أكثر تفصيلاً للمشاكل من خلال مرجع "التحقيق".
  • invoke_operation: تتيح هذه الأداة سير العمل لإنشاء الموارد وتعديلها وحذفها في Google Cloud. لا تعمل هذه الأداة إلا عندما تكون "إجراءات الوكيل" مفعَّلة. لا يمكن تنفيذ عمليات الكتابة في Gemini Cloud Assist إلا من خلال استدعاء هذه الأداة.
  • optimize_costs: تتيح هذه الأداة سير العمل اللازم لتحليل تكاليف Google Cloud وتتبُّعها وتحسينها. وتوفّر هذه الأداة تفصيلاً دقيقًا للإنفاق وتحدّد فرصًا لتحقيق فعالية التكلفة من خلال العثور على الموارد غير المستخدَمة أو غير المستغلّة بشكل كافٍ.

ستبدأ ببيئة معدّة مسبقًا تتضمّن مجموعة GKE ونموذجًا تم تنزيله. بعد ذلك، ستستخدم gemini-cli لتوجيه العامل لنقل عبء عمل من Cloud Run إلى GKE وبدء تشغيل مثيل استنتاج Gemma باستخدام vLLM باستخدام النموذج الذي تم إعداده في حزمة التخزين.

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

  • إعداد مجموعة GKE وتنزيل نموذج Gemma باستخدام Terraform
  • إعداد gemini-cli باستخدام قواعد الوكيل وخادم MCP
  • استخدِم طلبًا بلغة طبيعية محدّدة لتوجيه الوكيل بتنفيذ عملية نقل البيانات ونشرها بالكامل.
  • تحقَّق من عملية النشر التي نفّذها الوكيل.

المتطلبات

  • متصفّح ويب، مثل Chrome
  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • رمز مميّز من Hugging Face (مطلوب لتنزيل نموذج Gemma خلال مرحلة الإعداد)

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين من جميع المستويات، بما في ذلك المبتدئين.

المدة المقدَّرة: من 45 إلى 60 دقيقة.

2. قبل البدء

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

  1. في Google Cloud Console، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية.

بدء Cloud Shell

  1. انقر على تفعيل Cloud Shell في أعلى "وحدة تحكّم Google Cloud".
  2. إثبات صحة المصادقة:
gcloud auth list
  1. أكِّد مشروعك:
gcloud config get project
  1. اضبطه إذا لزم الأمر:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

تفعيل واجهات برمجة التطبيقات

نفِّذ الأمر التالي لتفعيل جميع واجهات برمجة التطبيقات المطلوبة:

gcloud services enable \
  run.googleapis.com \
  container.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

فعِّل أيضًا خدمة MCP في Gemini Cloud Assist:

gcloud beta services mcp enable geminicloudassist.googleapis.com

3- إعداد البيئة

في هذه الخطوة، ستجهّز البيئة من خلال إنشاء صورة مخصّصة لبرنامج الدردشة الآلي، وإنشاء مجموعة GKE، وتنزيل نموذج Gemma إلى حزمة Cloud Storage.

في كثير من الأحيان، تبدأ المؤسسات باستخدام Gemini API، ولكنها تقرّر لاحقًا الانتقال إلى نموذج مستضاف ذاتيًا للحصول على المزيد من التحكّم أو التخصيص أو لاستخدام إصدار معدَّل بدقة ومناسب لنشاطها التجاري. في هذا الدرس التطبيقي حول الترميز، نستخدم Gemma كمثال على نموذج مفتوح المصدر قوي يمكنك استضافته بنفسك على GKE. ويؤدي تخزينها في حزمة Cloud Storage إلى إتاحتها لمجموعتنا.

تنزيل مواد العرض التجريبية

استنسِخ المجلد المحدّد من مستودع GitHub.

git clone --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
cd next-26-keynotes
git sparse-checkout set devkey/intent-to-infrastructure
cd devkey/intent-to-infrastructure

إنشاء صورة لروبوت الدردشة

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

  1. أنشئ مستودع Artifact Registry باسم chatbot-repo في asia-southeast1:
    gcloud artifacts repositories create chatbot-repo \
    --repository-format=docker \
    --location=asia-southeast1 \
    --description="Chatbot Docker repository"
  2. انتقِل إلى دليل src:
    cd src
  3. أنشئ الصورة وادفعها باستخدام Cloud Build:
    gcloud builds submit --config cloudbuild.yaml \
    --substitutions=_LOCATION="asia-southeast1",_REPOSITORY_ID="chatbot-repo",_IMAGE_NAME="chatbot",_IMAGE_TAG="latest"
  4. ارجع إلى جذر المشروع:
    cd ..

توفير البنية الأساسية

انتقِل إلى الدليل terraform ونفِّذ الخطوة 1 لإنشاء مجموعة GKE.

cd terraform
./deploy.sh demo step1 apply

يستخدم هذا النص البرمجي Terraform لتوفير البنية الأساسية. تنشئ هذه العملية شبكة VPC ومجموعة GKE وحسابات الخدمة، وتنفّذ خدمة Cloud Run الأولية باستخدام صورة برنامج الدردشة الآلي التي أنشأتها للتو.

أثناء العملية، ستعرض Terraform الخطة وتطلب تأكيدها. يجب كتابة yes للموافقة والمتابعة:

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

قد تستغرق العملية بأكملها من 15 إلى 20 دقيقة.

بعد اكتمال عملية النشر، ابحث عن cloud_run_url في نواتج Terraform المطبوعة في الجهاز. انقر على عنوان URL لفتح روبوت المحادثة في المتصفّح. يمكنك الآن التفاعل مع روبوت الدردشة الذي يستند حاليًا إلى Gemini 2.5 Flash.

تنزيل النموذج

في هذه الخطوة، سننقل نموذج Gemma إلى حزمة Cloud Storage. مع أنّنا سنبدأ باستخدام واجهة Gemini API المُدارة، يمكنك اختيار تشغيل نموذج مخصّص تم ضبطه بدقة أو نموذج مخصّص آخر مفتوح المصدر. بدلاً من ذلك، قد تريد ببساطة إبقاء تنفيذ النموذج مُدارًا داخل مجموعتك الخاصة لأسباب تتعلّق بالأمان أو الامتثال. يساعدنا إعداد النموذج هنا في الاستعداد لعملية نقل البيانات من Gemini API المُدار إلى نموذج مستضاف ذاتيًا على GKE.

نفِّذ الخطوة 2 لتنزيل نموذج Gemma إلى حزمة GCS. ستحتاج إلى الرمز المميّز الخاص بمنصة Hugging Face. يتم تنفيذ هذه العملية على مجموعة GKE، وستستغرق حوالي 15 دقيقة (أو أكثر حسب عدد الزيارات) لتنزيل النموذج من Hugging Face وتحميله إلى الحزمة لاستخدامه لاحقًا.

./deploy.sh demo step2 apply -var="hf_token=<YOUR_HF_TOKEN>"

ينشئ أمر Terraform هذا مهمة Kubernetes على مجموعة GKE للتعامل مع عملية التنزيل. سيبقى نص Terraform البرمجي نشطًا طالما أنّ المهمة قيد التشغيل.

إذا أردت تتبُّع مستوى التقدّم من جلسة shell مختلفة أو التأكّد من اكتمالها بعد التشغيل، يمكنك تنفيذ ما يلي:

kubectl get jobs

4. إعداد "الوكيل" وMCP

سنضبط الآن الوكيل الذي سينفّذ عملية النقل. سنستخدم gemini-cli ونزوّده بقواعد للتفاعل مع البيئة.

خادم MCP الخاص بـ "مساعد Gemini السحابي" (GCA) هو عنصر أساسي في هذا التدفق. تعمل هذه الأداة كجسر بين الوكيل من جهة العميل وGoogle Cloud، ما يتيح لها إجراء التحقيقات وإنشاء الخطط (مثل الأوامر gcloud وkubectl) وتطبيق التغييرات مباشرةً على الموارد في مشروعك على السحابة الإلكترونية.

تأكَّد من منحك دورًا يسمح باستدعاء أدوات MCP، مثل roles/geminicloudassist.user. إذا واجهت مشاكل في الأذونات لاحقًا، يمكنك الرجوع إلى المستندات حول إعداد أدوار "إدارة الهوية وإمكانية الوصول" في Cloud Assist.

للحصول على تعليمات أكثر تفصيلاً حول دمج Gemini Cloud Assist مع أدوات تابعة لجهات خارجية، يُرجى الاطّلاع على مستند دمج Gemini Cloud Assist مع أدوات تابعة لجهات خارجية باستخدام MCP.

تثبيت إضافة Gemini Cloud Assist

  1. يمكنك المصادقة من خلال "بيانات الاعتماد التلقائية للتطبيق" (ADC) عن طريق تنفيذ ما يلي:
gcloud auth application-default login
  1. ثبِّت خادم MCP كإضافة في Gemini CLI:
gemini extensions install https://github.com/GoogleCloudPlatform/gemini-cloud-assist-mcp
  1. تأكَّد من تثبيت المهارة بنجاح: ابدأ gemini ونفِّذ الأمر التالي لإدراج المهارات النشطة:
/skills list

تأكَّد من ظهور المهارة ذات الصلة بـ "Gemini Cloud Assist" في القائمة. اكتب exit للرجوع إلى طلب Cloud Shell.

تفعيل عمليات التعديل في Gemini Cloud Assist

للسماح للوكيل بتطبيق تغييرات على البنية الأساسية، يجب تفعيل ميزات التعديل في واجهة مستخدم Gemini Cloud Assist.

  1. افتح الشريط الجانبي لـ "مساعد Gemini" من خلال النقر على شعار Gemini في أعلى يسار نافذة Google Cloud Console.
    الشريط الجانبي في Gemini Assist
  2. فعِّل أي واجهات برمجة تطبيقات ضرورية مُدرَجة في الشريط الجانبي.
    تفعيل واجهات برمجة التطبيقات
  3. انتقِل إلى الإعدادات في الشريط الجانبي وضع علامة في المربّع بجانب "السماح لميزة Cloud Assist بتنفيذ الإجراءات".
    الانتقال إلى &quot;الإعدادات&quot;
    تفعيل التنفيذ

ضبط قواعد الوكيل

يتضمّن دليل المشروع ملف gemini.md مخصّصًا في جذر المجلد (intent-to-infrastructure). يحتوي هذا الملف على قواعد توجّه الوكيل لاستخدام الأدوات الصحيحة.

تأكَّد من أنّ هذا الملف متوفّر في الدليل. يجب تشغيل gemini من هذا الدليل حتى يتمكّن من الوصول إلى ملفات Terraform والرمز البرمجي للتطبيق وملف قواعد gemini.md.

5- الخطوة 1: نقل Chatbot إلى GKE

سنستخدم الآن الوكيل لتنفيذ الجزء الأول من عملية النقل، وهو نقل تطبيق روبوت الدردشة من Cloud Run إلى GKE.

  1. ابدأ gemini من جذر الدليل intent-to-infrastructure (مع التأكّد من إمكانية الوصول إلى gemini.md).
  2. أولاً، لنطلب من الوكيل استكشاف المشروع لفهم التطبيق والبنية الأساسية. أدخِل الطلب التالي:
Tell me about the app and infrastructure in this project

يجب أن يقرأ الوكيل الملفات في الدليل ويقدّم لك نظرة عامة على تطبيق روبوت الدردشة وإعدادات Terraform.

  1. الآن، استخدِم الطلب التالي لتوجيه الوكيل بتنفيذ عملية نقل البيانات.
Convert my Cloud Run service to the equivalent on GKE.
  1. على موظّف الدعم إجراء ما يلي:
    • استخدِم أداة ask_cloud_assist لفهم السياق.
    • استخدِم الأداة design_infra لإنشاء ملف YAML الخاص بتطبيق روبوت الدردشة في Kubernetes.
    • اطرح السؤال التالي: "هل تريد المتابعة لتطبيق هذا الإعداد؟"
  1. أدخِل yes لتطبيق التغييرات. سيستخدم الوكيل invoke_operation لنشر الموارد في مجموعة GKE.

الخطوة 1 من عملية تأكيد الحساب

  1. الحصول على قائمة الخدمات:
kubectl get services

من المفترض أن تظهر لك خدمة لتشغيل تطبيق chatbot.

  1. أعِد توجيه المنفذ للخدمة للوصول إلى برنامج الدردشة الآلي:
kubectl port-forward svc/chatbot-service 8080:80

(ملاحظة: استبدِل

chatbot-service

مع الاسم الفعلي للخدمة التي أنشأها الوكيل إذا كان مختلفًا).

اختبِر روبوت الدردشة. سيظلّ بإمكانك الحصول على ردود باستخدام Gemini API (كما تم إعداده في Cloud Run).

6. الخطوة 2: نشر Gemma من خلال vLLM وإعادة الاتصال

في هذه الخطوة، سنستخدم الوكيل لنشر نموذج Gemma مستضاف ذاتيًا على GKE وإعادة ربط تطبيقنا به.

  1. في جلسة gemini نفسها، أدخِل الطلب التالي:
Now that the chatbot is on GKE, add a vLLM service running the Gemma model from my storage bucket in the same cluster. Make sure to give the vLLM service at least 10 minutes to start up to account for loading the large model. Then, update the chatbot service to reference this vLLM service instead of the Gemini API.
  1. على موظّف الدعم إجراء ما يلي:
    • استخدِم design_infra لإنشاء YAML لعملية نشر vLLM والخدمة.
    • عدِّل ملف YAML الخاص بنشر روبوت المحادثة لتغيير متغيرات البيئة (أو الإعداد) للإشارة إلى خدمة vLLM الجديدة بدلاً من Gemini API.
    • طلب تأكيد لتطبيق التغييرات
  2. أدخِل yes لتطبيق التغييرات.

الخطوة 2 من عملية إثبات الملكية

  1. الحصول على قائمة الحاويات مرة أخرى:
kubectl get pods

من المفترض أن تظهر الآن وحدات لكلّ من روبوت الدردشة وvLLM.

  1. بعد أن يصبح vLLM جاهزًا، أعِد توجيه خدمة chatbot إلى منفذ آخر إذا لزم الأمر واختبِرها. من المفترض أن يكون النموذج الآن مستنِدًا إلى نموذج Gemma المستضاف ذاتيًا.

7. تنظيف

لتجنُّب الرسوم المستمرة على حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس العملي.

نفِّذ أمر الإزالة للبنية الأساسية:

cd terraform
./deploy.sh demo step1 destroy

بالإضافة إلى ذلك، يمكنك إلغاء تثبيت إضافة Gemini Cloud Assist أو إيقافها إذا أردت تنظيف بيئتك المحلية. استخدِم gemini extensions uninstall أو gemini extensions disable متبوعًا باسم الإضافة.

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

لمزيد من المعلومات حول Gemini Cloud Assist والميزات المتقدّمة، يُرجى الاطّلاع على المراجع التالية:

9- تهانينا

تهانينا! لقد نفّذت بنجاح عملية نقل مستندة إلى الوكيل لعبء عمل إلى GKE باستخدام اللغة الطبيعية وMCP.