قصد زیرساخت: مهاجرت عامل‌محور به GKE

۱. مقدمه

در این آزمایشگاه کد، یاد خواهید گرفت که چگونه از یک عامل هوش مصنوعی برای انجام خودکار یک مهاجرت پیچیده زیرساخت استفاده کنید. به جای نوشتن دستی مانیفست‌های Kubernetes یا اجرای اسکریپت‌های اتوماسیون، شما قصد خود را به زبان طبیعی بیان خواهید کرد و عامل از پروتکل Model Context (MCP) و سرور Gemini Cloud Assist برای تولید و اعمال پیکربندی برای شما استفاده خواهد کرد.

مهم: این codelab به بررسی سرور Gemini Cloud Assist (GCA) MCP می‌پردازد که در حال حاضر در پیش‌نمایش خصوصی است. حتی اگر به مجموعه کامل ویژگی‌ها دسترسی نداشته باشید، همچنان می‌توانید codelab را ادامه دهید. با این حال، اگر به ویژگی‌های mutation (به‌ویژه ابزار invoke_operation ) دسترسی نداشته باشید، agent قادر به اعمال خودکار تغییرات نخواهد بود. در این صورت، باید مانیفست‌های تولید شده Kubernetes را به‌صورت دستی اعمال کنید. برای اطلاعات بیشتر با تیم حساب خود تماس بگیرید.

قابلیت‌های سرور GCA MCP

سرور GCA MCP چندین ابزار تخصصی را در اختیار عامل قرار می‌دهد:

• ask_cloud_assist : این رابط اصلی برای دستیاری پلتفرم ابری گوگل و برای عامل Gemini Cloud Assist است. تمام قابلیت‌های Gemini Cloud Assist از طریق این ابزار قابل دسترسی است و شامل عملکرد سایر ابزارهای MCP نیز می‌شود.
• design_infra : این از گردش‌های کاری برای طراحی و معماری زیرساخت در پلتفرم ابری گوگل پشتیبانی می‌کند.
• investigate_issue : این از گردش‌های کاری برای عیب‌یابی در Google Cloud پشتیبانی می‌کند. می‌تواند عیب‌یابی سریع یا عیب‌یابی عمیق‌تر را از طریق یک منبع Investigation انجام دهد.
• invoke_operation : این ابزار از گردش‌های کاری برای ایجاد، به‌روزرسانی و حذف منابع در Google Cloud پشتیبانی می‌کند. این ابزار فقط زمانی کاربردی است که Agent Actions فعال باشد. عملیات نوشتن در Gemini Cloud Assist فقط از طریق فراخوانی این ابزار قابل اجرا هستند.
• optimize_costs : این از گردش‌های کاری برای تجزیه و تحلیل، ردیابی و بهینه‌سازی هزینه‌های Google Cloud پشتیبانی می‌کند. این ابزار جزئیات دقیقی از هزینه‌ها ارائه می‌دهد و با یافتن منابع بیکار یا کم استفاده، فرصت‌های بهره‌وری هزینه را شناسایی می‌کند.

شما با یک محیط از پیش آماده‌سازی شده با یک کلاستر GKE و یک مدل دانلود شده شروع خواهید کرد. سپس از gemini-cli برای وادار کردن عامل به انتقال یک بار کاری از Cloud Run به GKE و راه‌اندازی یک نمونه استنتاج Gemma با vLLM با استفاده از مدل آماده‌سازی شده در مخزن ذخیره‌سازی خود استفاده خواهید کرد.

کاری که انجام خواهید داد

• یک خوشه GKE را مرحله‌بندی کنید و یک مدل Gemma را با استفاده از Terraform دانلود کنید.
• پیکربندی gemini-cli با قوانین عامل و یک سرور MCP.
• از یک زبان طبیعی خاص برای دستور دادن به عامل جهت انجام کامل مهاجرت و استقرار استفاده کنید.
• استقرار انجام شده توسط عامل را تأیید کنید.

آنچه نیاز دارید

• یک مرورگر وب مانند کروم .
• یک پروژه گوگل کلود با قابلیت پرداخت.
• یک توکن چهره در آغوش گرفته (برای دانلود مدل Gemma در مرحله آماده‌سازی لازم است).

این آزمایشگاه کد برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، مناسب است.

مدت زمان تخمینی: ۴۵-۶۰ دقیقه.

۲. قبل از شروع

یک پروژه Google Cloud ایجاد یا انتخاب کنید

1. در کنسول گوگل کلود ، یک پروژه گوگل کلود انتخاب یا ایجاد کنید .
2. مطمئن شوید که پرداخت برای پروژه ابری شما فعال است.

شروع پوسته ابری

1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
2. تأیید اعتبار:

gcloud auth list

3. پروژه خود را تایید کنید:

gcloud config get project

4. در صورت نیاز آن را تنظیم کنید:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

فعال کردن APIها

برای فعال کردن تمام API های مورد نیاز، این دستور را اجرا کنید:

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

همچنین، سرویس Gemini Cloud Assist MCP را فعال کنید:

gcloud beta services mcp enable geminicloudassist.googleapis.com

۳. محیط را مرحله‌بندی کنید

در این مرحله، با ساخت یک تصویر چت‌بات سفارشی، ایجاد خوشه GKE و دانلود مدل Gemma در یک فضای ذخیره‌سازی ابری، محیط را آماده خواهید کرد.

اغلب، سازمان‌ها با رابط برنامه‌نویسی Gemini شروع می‌کنند، اما بعداً تصمیم می‌گیرند برای کنترل بیشتر، سفارشی‌سازی یا استفاده از یک نسخه تنظیم‌شده خاص برای کسب‌وکارشان، به یک مدل خود-میزبانی مهاجرت کنند. در این آزمایشگاه کد، ما از Gemma به عنوان نمونه‌ای از یک مدل باز قدرتمند استفاده می‌کنیم که می‌توانید خودتان آن را روی GKE میزبانی کنید. قرار دادن آن در یک مخزن ذخیره‌سازی ابری، آن را برای استفاده در کلاستر ما در دسترس قرار می‌دهد.

دانلود فایل‌های نمایشی

پوشه‌ی مورد نظر را از مخزن گیت‌هاب کپی کنید.

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

نکته: اگر هنگام اجرای deploy.sh با خطای "Permission denied" مواجه شدید، ممکن است لازم باشد با اجرای chmod +x deploy.sh آن را قابل اجرا کنید.

این اسکریپت از 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 دقیقه طول بکشد.

پس از اتمام استقرار، در خروجی‌های Terraform که در ترمینال چاپ می‌شوند، به دنبال cloud_run_url بگردید. برای باز کردن چت‌بات در مرورگر خود، روی URL کلیک کنید. اکنون می‌توانید با چت‌بات که در حال حاضر روی Gemini 2.5 Flash اجرا می‌شود، تعامل داشته باشید.

مدل را دانلود کنید

در این مرحله، مدل Gemma را در یک مخزن ذخیره‌سازی ابری (Cloud Storage Bucket) اجرا خواهیم کرد. در حالی که ما با API مدیریت‌شده Gemini شروع می‌کنیم، شما می‌توانید یک مدل سفارشی تنظیم‌شده یا یک مدل باز سفارشی دیگر را اجرا کنید. از طرف دیگر، ممکن است بخواهید به دلایل امنیتی یا انطباق، اجرای مدل را در خوشه خود مدیریت‌شده نگه دارید. اجرا مدل در اینجا، ما را برای مهاجرت از API مدیریت‌شده Gemini به یک مدل خود-میزبان در GKE آماده می‌کند.

مرحله ۲ را اجرا کنید تا مدل Gemma را در سطل GCS خود دانلود کنید. به توکن Hugging Face خود نیاز خواهید داشت. این فرآیند روی خوشه GKE شما اجرا می‌شود و حدود ۱۵ دقیقه (یا بسته به ترافیک بیشتر) طول می‌کشد تا مدل از Hugging Face دانلود شود و برای استفاده بعدی در سطل شما آپلود شود.

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

این دستور Terraform یک Kubernetes Job در کلاستر GKE شما ایجاد می‌کند تا دانلود را مدیریت کند. اسکریپت Terraform تا زمانی که این Job در حال اجرا باشد، فعال خواهد ماند.

اگر می‌خواهید پیشرفت را از یک جلسه پوسته دیگر نظارت کنید، یا تأیید کنید که پس از اجرا تکمیل شده است، می‌توانید دستور زیر را اجرا کنید:

kubectl get jobs

۴. عامل راه‌اندازی و MCP

حالا ما عاملی را که مهاجرت را انجام می‌دهد پیکربندی خواهیم کرد. ما gemini-cli استفاده خواهیم کرد و آن را به قوانینی برای تعامل با محیط مجهز خواهیم کرد.

سرور Gemini Cloud Assist (GCA) MCP یک جزء حیاتی از این جریان است. این سرور به عنوان پلی بین عامل سمت کلاینت شما و Google Cloud عمل می‌کند و آن را قادر می‌سازد تا تحقیقات را انجام دهد، طرح‌هایی (مانند دستورات gcloud و kubectl ) تولید کند و تغییرات را مستقیماً در منابع پروژه ابری شما اعمال کند.

مطمئن شوید که نقشی به شما اعطا شده است که امکان فراخوانی ابزارهای MCP، مانند roles/geminicloudassist.user را فراهم می‌کند. اگر بعداً با مشکلات مجوز مواجه شدید، به مستندات مربوط به پیکربندی نقش‌های IAM برای Cloud Assist مراجعه کنید.

برای دستورالعمل‌های دقیق‌تر در مورد ادغام Gemini Cloud Assist با ابزارهای شخص ثالث، به بخش « ادغام Gemini Cloud Assist با ابزارهای شخص ثالث با استفاده از مستندات MCP» مراجعه کنید.

افزونه‌ی Gemini Cloud Assist را نصب کنید

1. با اجرای دستور زیر، از طریق اعتبارنامه‌های پیش‌فرض برنامه (ADC) احراز هویت کنید:

gcloud auth application-default login

2. سرور MCP را به عنوان یک افزونه Gemini CLI نصب کنید:

gemini extensions install https://github.com/GoogleCloudPlatform/gemini-cloud-assist-mcp

توجه: این دستور هم سرور MCP و هم یک مهارت تخصصی را نصب می‌کند. این مهارت به رابط خط فرمان Gemini کمک می‌کند تا زمینه‌های مناسب برای استفاده از ابزارهای Cloud Assist را درک کند.

3. تأیید کنید که مهارت با موفقیت نصب شده است: gemini را شروع کنید و دستور زیر را برای لیست کردن مهارت‌های فعال اجرا کنید:

/skills list

تأیید کنید که مهارت مربوط به Gemini Cloud Assist را در لیست می‌بینید. برای بازگشت به اعلان Cloud Shell خود، exit را تایپ کنید.

فعال کردن جهش‌ها در Gemini Cloud Assist

برای اینکه به عامل اجازه دهید تغییرات را در زیرساخت شما اعمال کند، باید ویژگی‌های جهش را در رابط کاربری Gemini Cloud Assist فعال کنید.

1. با کلیک روی لوگوی Gemini در سمت راست بالای پنجره Google Cloud Console، نوار کناری Gemini Assist را باز کنید.
   
   
2. هر API لازم که در نوار کناری فهرست شده است را فعال کنید.
   
   
3. به تنظیمات در نوار کناری بروید و گزینه «فعال کردن دستیار ابری برای اجرای اقدامات» را علامت بزنید.
   
   
   

پیکربندی قوانین عامل

دایرکتوری پروژه شامل یک فایل سفارشی gemini.md در ریشه پوشه ( intent-to-infrastructure ) است. این فایل حاوی قوانینی است که عامل را برای استفاده از ابزارهای صحیح راهنمایی می‌کند.

تأیید کنید که این فایل در دایرکتوری شما وجود دارد. شما باید gemini از این دایرکتوری اجرا کنید تا به فایل‌های Terraform، کد برنامه و فایل قوانین gemini.md دسترسی داشته باشد.

۵. مرحله ۱: انتقال چت‌بات به GKE

اکنون از عامل برای انجام بخش اول مهاجرت استفاده خواهیم کرد: انتقال برنامه چت‌بات از Cloud Run به GKE.

1. gemini از ریشه دایرکتوری intent-to-infrastructure اجرا کنید (و مطمئن شوید که به gemini.md دسترسی دارد).
2. ابتدا، از عامل می‌خواهیم که پروژه را بررسی کند تا برنامه و زیرساخت را درک کند. دستور زیر را وارد کنید:

Tell me about the app and infrastructure in this project

نماینده باید فایل‌های موجود در دایرکتوری را بخواند و یک نمای کلی از برنامه چت‌بات و پیکربندی Terraform به شما ارائه دهد.

3. اکنون، از دستور زیر برای دستور دادن به عامل جهت انجام مهاجرت استفاده کنید.

Convert my Cloud Run service to the equivalent on GKE.

4. نماینده باید:
   • برای درک زمینه از ابزار ask_cloud_assist استفاده کنید.
   • از ابزار design_infra برای تولید Kubernetes YAML برای برنامه چت‌بات استفاده کنید.
   • بپرسید: «آیا مایلید این پیکربندی را اعمال کنید؟»

توجه: وقتی gemini برای اولین بار سعی در استفاده از ابزاری دارد، از شما اجازه دسترسی به ابزارهای ارائه شده توسط سرور MCP را می‌خواهد. برای فعال کردن عامل، باید گزینه Allow را انتخاب کنید.

5. برای اعمال تغییرات، با yes پاسخ دهید. عامل invoke_operation برای استقرار منابع در خوشه GKE شما استفاده خواهد کرد.

مرحله ۱ را تأیید کنید

1. دریافت لیست خدمات:

kubectl get services

شما باید سرویسی را برای برنامه‌ی چت‌بات در حال اجرا ببینید.

2. برای دسترسی به ربات چت، سرویس را پورت فوروارد کنید:

kubectl port-forward svc/chatbot-service 8080:80

(توجه: جایگزین کنید)

chatbot-service

(در صورت متفاوت بودن، نام واقعی سرویس تولید شده توسط عامل نیز ذکر می‌شود.)

چت‌بات را آزمایش کنید. هنوز باید با استفاده از API Gemini پاسخ دهد (همانطور که در Cloud Run پیکربندی شده بود).

۶. مرحله ۲: استقرار 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.

2. نماینده باید:
   • design_infra برای تولید YAML برای استقرار و سرویس vLLM استفاده کنید.
   • YAML مربوط به استقرار چت‌بات را به‌روزرسانی کنید تا متغیرهای محیطی (یا پیکربندی) به جای رابط برنامه‌نویسی Gemini به سرویس vLLM جدید اشاره کنند.
   • برای اعمال تغییرات، درخواست تأیید کنید.
3. برای اعمال تغییرات، با yes پاسخ دهید.

مرحله ۲ را تأیید کنید

1. دوباره لیست پادها را دریافت کنید:

kubectl get pods

اکنون باید پادهای مربوط به چت‌بات و vLLM را ببینید.

توجه: حتی پس از اینکه vLLM Pod در حالت Running قرار گرفت، به دلیل حجم بالای مدل، ممکن است تا 10 دقیقه طول بکشد تا سرور وزن‌های مدل را از مخزن ذخیره‌سازی به طور کامل بارگذاری کرده و شروع به سرویس‌دهی کند. می‌توانید با بررسی لاگ‌ها، روند بارگذاری را زیر نظر داشته باشید:

kubectl logs -f deployment/gemma-vllm -c vllm-server

2. پس از آماده شدن vLLM، در صورت نیاز دوباره سرویس چت‌بات را پورت‌فوروارد کنید و آن را آزمایش کنید. اکنون باید توسط مدل Gemma خود-میزبانی شده شما پشتیبانی شود!

۷. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این codelab را حذف کنید.

دستور destroy را برای زیرساخت پایه اجرا کنید:

cd terraform
./deploy.sh demo step1 destroy

علاوه بر این، اگر می‌خواهید محیط محلی خود را پاکسازی کنید، می‌توانید افزونه‌ی Gemini Cloud Assist را حذف یا غیرفعال کنید. gemini extensions uninstall یا gemini extensions disable و به دنبال آن نام افزونه استفاده کنید.

۸. قدم بعدی چیست؟

برای کسب اطلاعات بیشتر در مورد Gemini Cloud Assist و ویژگی‌های پیشرفته، به این منابع مراجعه کنید:

• عیب‌یابی مشکلات مربوط به بررسی‌های Cloud Assist
• حالت پیشگیرانه را تنظیم کنید

۹. تبریک

تبریک! شما با موفقیت یک مهاجرت مبتنی بر عامل از یک حجم کاری به GKE را با استفاده از زبان طبیعی و MCP انجام دادید.