جعبه ابزار هوش مصنوعی مهندسی ابری: مهندسی پلتفرم در GKE با استفاده از Gemini

۱. مقدمه

عیب‌یابی استقرارهای ناقص Kubernetes بخشی رایج و اغلب ناامیدکننده از زندگی روزمره یک مهندس پلتفرم است. این کار معمولاً شامل بررسی‌های دستی زیادی است: بررسی لاگ‌ها، اجرای دستورات kubectl describe و ارجاع متقابل به فایل‌های YAML برای یافتن یک عدم تطابق یا پیکربندی اشتباه.

در حالی که چت‌بات‌های هوش مصنوعی همه منظوره می‌توانند به توضیح مفاهیم یا نوشتن کدهای اولیه کمک کنند، اما در خلأ عمل می‌کنند. آن‌ها چیزی در مورد کدبیس خاص شما یا وضعیت فعلی کلاستر شما نمی‌دانند، که منجر به کپی-پیست دستی و تغییر زمینه زیادی می‌شود.

در این آزمایشگاه، شما تجربه خواهید کرد که چگونه با استفاده از ابزارهای هوش مصنوعی با سطوح فزاینده‌ای از زمینه، این شکاف را پر کنید. شما از رابط خط فرمان Gemini و پروتکل زمینه مدل (MCP) برای عیب‌یابی یک برنامه خراب در GKE استفاده خواهید کرد. در پایان این آزمایشگاه، شما خواهید فهمید که چگونه از هوش مصنوعی که از فایل‌ها و زیرساخت‌های شما آگاه است برای حل سریع‌تر مسائل پیچیده استفاده کنید و چگونه این گردش‌های کاری را به «مهارت‌های» قابل استفاده مجدد برای تیم خود کدگذاری کنید.

مفاهیم اصلی

• مهندسی پلتفرم : مهندسی پلتفرم، عملی برای ساخت و نگهداری ابزارها و گردش‌های کاری داخلی است که توسعه‌دهندگان نرم‌افزار را قادر می‌سازد تا زیرساخت خود را بدون نیاز به تخصص در هر سرویس ابری زیربنایی، مدیریت کنند. هدف، کاهش اصطکاک فنی در عین حفظ ثبات و امنیت است. با ایجاد یک مسیر طلایی استاندارد، تیم‌های پلتفرم اطمینان حاصل می‌کنند که توسعه‌دهندگان برنامه‌های کاربردی می‌توانند با خیال راحت و به سرعت مستقر شوند، در حالی که تیم پلتفرم کنترل بر مدیریت و هزینه را حفظ می‌کند.
• رابط خط فرمان Gemini : رابط خط فرمان Gemini یک رابط خط فرمان است که به شما امکان می‌دهد مستقیماً از طریق ترمینال خود با مدل‌های Gemini تعامل داشته باشید. برخلاف یک چت‌بات استاندارد مبتنی بر وب، این رابط خط فرمان به گونه‌ای طراحی شده است که در محیط توسعه شما وجود داشته باشد و ادغام هوش مصنوعی را در گردش‌های کاری مبتنی بر پوسته موجود آسان‌تر می‌کند. این رابط به شما امکان می‌دهد خروجی سایر دستورات را مستقیماً به مدل منتقل کنید و بدون ترک ترمینال خود، دستورالعمل‌ها را اجرا کنید.
• پروتکل زمینه مدل (MCP) : MCP یک استاندارد باز است که به یک مدل هوش مصنوعی امکان اتصال به ابزارها یا منابع داده خاص را می‌دهد. بدون MCP، یک مدل هوش مصنوعی فقط می‌داند که بر اساس چه چیزی آموزش دیده است و نمی‌تواند منابع خاص شما را ببیند. با سرور GKE MCP ، رابط خط فرمان Gemini می‌تواند به طور فعال از API پروژه Google Cloud شما پرس و جو کند، وضعیت خوشه‌های شما را بررسی کند و دستورات را از طرف شما اجرا کند. این رابط به عنوان پلی بین موتور استدلال مدل و API واقعی GKE عمل می‌کند.
• مهارت‌های عامل : مهارت‌ها بسته‌هایی از دستورالعمل‌ها، اسکریپت‌ها و منابع هستند که قابلیت‌های یک عامل هوش مصنوعی را برای وظایف تخصصی گسترش می‌دهند. آن‌ها به شما امکان می‌دهند استانداردهای سازمانی را تدوین کرده و گردش‌های کاری پیچیده را خودکار کنید.

اهداف آزمایشگاه

در این آزمایشگاه، شما:

1. پیشرفت زمینه‌ای را تجربه کنید: ببینید که چگونه افزایش زمینه، حل مسئله هوش مصنوعی را بهبود می‌بخشد.
2. عیب‌یابی دستی در مقابل عیب‌یابی هوش مصنوعی: سختی اشکال‌زدایی دستی را با گردش‌های کاری مبتنی بر هوش مصنوعی مقایسه کنید.
3. اشکال‌زدایی کامل متن: از رابط خط فرمان Gemini به همراه سرور GKE MCP برای اشکال‌زدایی برنامه‌ها با آگاهی کامل از زیرساخت استفاده کنید.
4. گسترش قابلیت‌ها: یاد بگیرید که مهارت‌های سفارشی برای خودکارسازی گردش‌های کاری بنویسید.

یادداشتی در مورد خروجی‌های LLM

با توجه به ماهیت این آزمایشگاه و نحوه عملکرد LLMها، خروجی‌هایی که دریافت می‌کنید احتمالاً با خروجی‌های مثال نشان داده شده متفاوت خواهد بود. این رفتار مورد انتظار برای هوش مصنوعی مولد است. به جای تلاش برای تکرار متن یا قالب‌بندی دقیق در مثال‌ها، بر درک مراحل و استدلال ارائه شده توسط مدل تمرکز کنید.

۲. راه‌اندازی پروژه

قبل از شروع آزمایشگاه، محیط خود را آماده کنید. Cloud Shell را باز کنید، پروژه خود را انتخاب کنید و اسکریپت‌های راه‌اندازی را اجرا کنید. بیایید شروع کنیم!

پوسته ابری را باز کنید

برای این آزمایش، از Cloud Shell ، یک محیط ترمینال مبتنی بر مرورگر که توسط Google Cloud ارائه شده است، استفاده کنید. این محیط به صورت از پیش پیکربندی شده با تمام ابزارهای مورد نیاز شما - از جمله رابط خط فرمان Google Cloud ( gcloud ) ، kubectl و Gemini CLI - ارائه می‌شود و در زمان نصب این ابزارها روی دستگاه محلی شما صرفه‌جویی می‌کند.

1. به کنسول ابری گوگل بروید.
2. به بالای سمت راست کنسول نگاه کنید و روی دکمه‌ی «فعال کردن پوسته‌ی ابری» کلیک کنید (شبیه به یک اعلان ترمینال >_ ).
3. یک جلسه ترمینال در پایین پنجره مرورگر شما باز می‌شود. در صورت درخواست، روی ادامه کلیک کنید.

انتخاب یک پروژه

در ترمینال Cloud Shell، مطمئن شوید که در پروژه صحیح کار می‌کنید.

1. یک پروژه موجود را انتخاب کنید یا یک پروژه جدید مخصوص این آزمایشگاه در کنسول ایجاد کنید.
2. شناسه پروژه خود را یادداشت کنید. با اجرای دستور زیر، پروژه را در پوسته فعلی خود تنظیم کنید: gcloud config set project [YOUR_PROJECT_ID]

راه اندازی آزمایشگاه

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

1. مخزن را کلون کنید:
   👉💻 دستورات زیر را اجرا کنید تا فقط دایرکتوری lab را کلون کنید:

   git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos ~/devrel-demos
   cd ~/devrel-demos
   git sparse-checkout set codelabs/ai-toolkit-lab-1
   

2. به دایرکتوری آزمایشگاه بروید:
   👉💻 دویدن:

   cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/
   

3. تنظیم متغیرهای محیطی:
   👉💻 دستورات زیر را برای تنظیم پروژه و منطقه خود اجرا کنید:

   export PROJECT_ID=$(gcloud config get-value project)
   export REGION=us-central1
   

4. اسکریپت راه‌اندازی را اجرا کنید:
   این اسکریپت APIهای فهرست‌شده در زیر را فعال می‌کند، یک کلاستر GKE Autopilot ایجاد می‌کند و نصب ابزارهای مورد نیاز را تضمین می‌کند.
   👉💻 اسکریپت را از دایرکتوری ریشه اجرا کنید:

   ./setup.sh
   

   توجه: ایجاد خوشه ممکن است ۵ تا ۱۰ دقیقه طول بکشد.
5. مقداردهی اولیه وضعیت شکسته:
   برای شبیه‌سازی سناریویی که همکارانتان شما را با یک محیط خراب ترک کرده‌اند، اسکریپت break.sh را اجرا کنید. این اسکریپت مانیفست‌های خراب را در دایرکتوری فعال کدبیس کپی می‌کند.
   👉💻 اسکریپت را اجرا کنید:

   ./break.sh
   

6. برای تمرین‌های آزمایشگاهی آماده شوید:
   برای جلوگیری از تقلب هوش مصنوعی (دیدن راه‌حل‌ها)، در ادامه‌ی آزمایش به دایرکتوری cymbal-bank بروید.
   👉💻 دویدن:

   cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/cymbal-bank
   

API های فعال شده

اسکریپت راه‌اندازی چندین API گوگل کلود را فعال می‌کند. نحوه‌ی عملکرد آنها به شرح زیر است:

• container.googleapis.com: رابط برنامه‌نویسی کاربردی موتور کوبرنتیز گوگل. این رابط برای هرگونه عملیات در سطح کلاستر مورد نیاز است.
• generativelanguage.googleapis.com: رابط برنامه‌نویسی کاربردی (API) که به رابط خط فرمان Gemini اجازه می‌دهد با مدل‌های Gemini ارتباط برقرار کند.
• cloudresourcemanager.googleapis.com: برای بررسی فراداده‌های سطح پروژه و مدیریت مجوزها مورد نیاز است.
• logging.googleapis.com: برای عیب‌یابی ضروری است، زیرا امکان دریافت و تجزیه و تحلیل گزارش‌ها از کانتینرهای شما را فراهم می‌کند.

۳. مرحله ۰: عیب‌یابی دستی (بدون هوش مصنوعی)

حالا که در دایرکتوری cymbal-bank هستید، بیایید سعی کنیم خطاها را به صورت دستی پیدا کنیم. این «راه سخت» است. قبل از اینکه اجازه دهید هوش مصنوعی کارهای سنگین را انجام دهد، ابتدا خط پایه را تجربه کنید. عیب‌یابی دستی به معنای استفاده از ابزارهای استاندارد مانند kubectl برای بررسی وضعیت خوشه، دریافت گزارش‌ها و خواندن فایل‌های YAML برای تشخیص ناسازگاری‌ها است. این کار اغلب کند و خسته‌کننده است و برای اتصال نقاط به یکدیگر به تخصص نیاز دارد. این به عنوان یک نقطه مرجع عالی برای ابزارهای هوش مصنوعی که بعداً استفاده می‌کنید، عمل می‌کند.

1. سعی کنید مستقر شوید: بیایید ببینیم Kubernetes در مورد این مانیفست‌ها چه فکر می‌کند.
   👉💻 برای اعمال مانیفست‌ها، دستور زیر را اجرا کنید:

   kubectl apply -f kubernetes-manifests/
   

   ممکن است چند ثانیه طول بکشد تا پادها بچرخند. می‌توانید با استفاده از دستور 'watch kubectl get pods' از فعال شدن آنها مطلع شوید. پس از فعال شدن، از کلیدهای ctrl+c برای خروج از watch استفاده کنید. متوجه دو پاد ناموفق در لیست خواهید شد:
   • غلاف frontend خطای "CreateContainerConfigError" را نشان می‌دهد. این نوع خطا عموماً نشان می‌دهد که کانتینر در بارگیری پیکربندی مورد نیاز خود با مشکل مواجه است. به این فکر کنید که یک کانتینر برای راه‌اندازی به چه منابع خارجی نیاز دارد - آیا متغیرهای محیطی، اسرار یا ConfigMaps وجود دارد که ممکن است به اشتباه پیکربندی شده باشند یا وجود نداشته باشند؟ شما باید پیکربندی غلاف را بررسی کنید تا مقصر خاص را پیدا کنید.
   • سرویس کاربر در حالت "ImagePullBackOff" قرار دارد. وقتی این را می‌بینید، معمولاً به این معنی است که کلاستر قادر به بازیابی تصویر کانتینری که به آن گفته شده بود استفاده کند، نیست. جزئیات درخواست تصویر را در نظر بگیرید: آیا نام و برچسب تصویر دقیقاً صحیح است؟ آیا مشکلات احتمالی مجوز در رجیستری وجود دارد؟ به جایی که تصویر از آن استخراج می‌شود نگاهی بیندازید تا ببینید آیا می‌توانید دلیل عدم موفقیت درخواست را تشخیص دهید.
2. آسیب را بررسی کنید: از دستورات استاندارد Kubernetes برای دیدن علت خرابی استفاده کنید.
   • 👉💻 وضعیت پادها و همچنین نام آنها را بررسی کنید:

     kubectl get pods
     

     • مشاهده: شما پادها را در ImagePullBackOff ، CrashLoopBackOff ، Pending یا CreateContainerConfigError مشاهده می‌کنید.
     • توجه: یک پاد در حالت Running لزوماً به معنای عملکرد صحیح آن نیست. به عنوان مثال، ممکن است فاقد بررسی‌های سلامت کافی (زنده بودن/آمادگی) باشد و باعث شود حتی اگر برنامه داخل آن با مشکل مواجه شود، به عنوان در حال اجرا علامت‌گذاری شود. گزارش‌ها می‌توانند خطاها را نشان دهند، علیرغم اینکه یک پاد به ظاهر در حال اجرا است. در مجموع 11 خطای مختلف برای رفع وجود دارد.
   • 👉💻 یک پادِ از کار افتاده را برای دیدن رویدادها توصیف کنید ( [POD_NAME] را با نام واقعی یک پاد جایگزین کنید):

     kubectl describe pod [POD_NAME]
     

   • 👉💻 برای مشاهده خطاهای برنامه، لاگ‌های یک پاد (pod) خراب را بررسی کنید:

     kubectl logs [POD_NAME]
     

3. کار کارآگاهی: فایل manifests را در kubernetes-manifests/ با استفاده از Cloud Shell Editor یا cat در ترمینال باز کنید. سعی کنید خطاهایی را که در لاگ‌ها و رویدادها می‌بینید با پیکربندی موجود در فایل‌های YAML مرتبط کنید. چالش: سعی کنید فقط یک خطا را به صورت دستی برطرف کنید. توجه کنید که چگونه باید بین فایل‌ها جابجا شوید تا بقیه زنجیره خرابی‌ها را بفهمید.

۴. مرحله ۱: پرسیدن از وب (رابط کاربری وب Gemini)

از آنجایی که عیب‌یابی دستی کند است، بیایید از یک دستیار هوش مصنوعی استفاده کنیم. برنامه وب Gemini یک رابط چت قدرتمند همه منظوره است. در توضیح مفاهیم و تولید قطعه کد عالی عمل می‌کند. با این حال، بدون هیچ زمینه‌ای از محیط خاص شما کار می‌کند. نمی‌تواند فایل‌های شما را ببیند، خوشه شما را بررسی کند یا دستوراتی را اجرا کند. شما باید پیام‌های خطا و محتوای فایل را به صورت دستی کپی و جای‌گذاری کنید.

1. به Gemini بروید: gemini.google.com را در یک برگه جدید باز کنید. باید با حساب Google خود وارد شوید.
2. درخواست کمک برای یک خطای خاص: فرض کنید خطای ImagePullBackOff را در Pod userservice مشاهده می‌کنید.
   👉💬 این دستور را در رابط کاربری وب Gemini وارد کنید:
   My Kubernetes deployment for 'userservice' is failing with ImagePullBackOff. Here is the image name: us-central1-docker.pkg.dev/bank-of-anthos-ci/bank-of-anthos/user-service:v0.6.9. What is wrong?
3. پاسخ هوش مصنوعی: Gemini لیستی از علل رایج را به شما ارائه می‌دهد:
   • تصویر وجود ندارد.
   • شما مجوز کشیدن آن را ندارید.
   • یه غلط املایی داره.
   پیشنهاد می‌دهد که مجوزهای رجیستری یا IAM خود را بررسی کنید. اما نمی‌تواند تشخیص دهد که نام واقعی تصویر userservice (بدون خط تیره) است، مگر اینکه پروژه شما را ببیند.

نکته اصلی اختلاف اینجاست که Gemini هیچ دیدی نسبت به محیط محلی شما ندارد. برای دریافت زمینه مورد نیاز، باید آن را به صورت دستی (با درخواست و کپی کردن متن) ارائه دهید، که زمان‌بر و مستعد خطا است.

۵. فاز ۲: توان ترمینال (Gemini CLI)

حالا با استفاده از Gemini CLI به ترمینال بروید. Gemini CLI قدرت مدل‌های Gemini را مستقیماً به ترمینال شما می‌آورد. این CLI در جایی که شما کار می‌کنید، قرار دارد. فایل‌های محلی را می‌خواند، ورودی‌های piped را می‌پذیرد و حتی دستورات shell را از طرف شما (با تأیید شما) اجرا می‌کند. این ویژگی، آن را برای ادغام هوش مصنوعی در گردش‌های کاری شما بدون تغییر زمینه، فوق‌العاده مفید می‌کند. برای اطلاعات دقیق‌تر و استفاده پیشرفته، به مستندات رسمی Gemini CLI مراجعه کنید.

توجه: در حال حاضر، Antigravity CLI رسماً منتشر شده و جانشین Gemini CLI است. این آزمایشگاه همچنان از Gemini CLI استفاده می‌کند. برای جزئیات بیشتر در مورد Antigravity CLI، به مستندات رسمی Antigravity CLI مراجعه کنید.

زمینه و قابلیت مشاهده

قبل از شروع دستورالعمل‌ها، توجه داشته باشید که میزان دسترسی Gemini CLI به پروژه شما بستگی به محل اجرای آن دارد. مدل می‌تواند فایل‌ها و پوشه‌ها را نسبت به دایرکتوری کاری فعلی شما ببیند. اگر آن را از ریشه پروژه خود اجرا کنید، به تمام فایل‌های موجود در آن پروژه دسترسی دارد. اگر آن را از یک زیرشاخه اجرا کنید، دید آن به آن زیرشاخه و فرزندانش محدود می‌شود. همیشه قبل از درخواست از مدل برای تجزیه و تحلیل یا تغییر فایل‌ها، مطمئن شوید که در دایرکتوری صحیح هستید!

شروع رابط خط فرمان Gemini

Cloud Shell به طور پیش‌فرض شامل رابط خط فرمان Gemini است. برای شروع استفاده از آن با فایل‌های محلی خود، کافیست آن را اجرا کنید.

1. به دایرکتوری Cymbal Bank بروید:
   👉💻 دستور زیر را اجرا کنید تا مطمئن شوید در دایرکتوری صحیح هستید:

   cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/cymbal-bank
   

2. اجرای رابط خط فرمان Gemini:
   👉💻 دستور زیر را برای شروع Gemini CLI اجرا کنید:

   gemini
   

استفاده از رابط خط فرمان Gemini

تنها چیزی که واقعاً در مورد این برنامه می‌دانید این است که کد را کجا پیدا کنید و اینکه مشکل از کجاست. بیایید بیشتر یاد بگیریم و ببینیم Gemini چگونه می‌تواند به شما در رفع مشکل برنامه کمک کند. ابتدا، با پرسیدن سوالی در مورد فایل‌های برنامه که باید بتواند ببیند، توانایی آن را در بررسی زمینه آزمایش کنید.

1. بررسی کدبیس: از Gemini بخواهید توضیح دهد که این برنامه چیست و چه کاری انجام می‌دهد.
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   What is this application and what does it do?
   رابط خط فرمان Gemini فایل‌های موجود در دایرکتوری فعلی را می‌خواند و یک نمای کلی از پروژه ارائه می‌دهد.
2. سعی کنید مشکلی را در کدبیس پیدا کنید: از آنجایی که Gemini CLI فایل‌های شما را می‌بیند، از آن بخواهید که یک عدم تطابق پیدا کند.
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   The contacts service pod is running, but I can't reach the service. Review kubernetes-manifests/contacts.yaml and check for common issues
   رابط خط فرمان Gemini فایل‌ها را می‌خواند و عدم تطابق بین app: contacts-backend و app: contacts تشخیص می‌دهد. این یک پیروزی بزرگ نسبت به مراحل قبلی است.
3. ازش بخواه که درستش کنه:
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   Fix the label mismatch in contacts.yaml so the service matches the deployment.
   رابط خط فرمان Gemini، YAML اصلاح‌شده را به شما نشان می‌دهد یا حتی در صورت تأیید دستور، تغییر را اعمال می‌کند.
4. محدودیت: در حالی که فایل‌ها را می‌بیند، هنوز نمی‌داند چه چیزی واقعاً در کلاستر شما در حال اجرا است. اگر یک پاد به دلیل خطای زمان اجرا که در YAML استاتیک مشخص نیست، از کار بیفتد، بدون گزارش‌ها یا وضعیت کلاستر نمی‌تواند کمکی کند.

توجه: Gemini CLI هنگام اجرای دستورات یا ایجاد تغییرات در فایل‌ها، از شما اجازه می‌خواهد. این امر تضمین می‌کند که شما کنترل خود را بر محیط خود حفظ می‌کنید. وقتی اعلانی مانند تصویر زیر را مشاهده کردید، می‌توانید برای پاسخ دادن به هر درخواست اقدام، "1. Allow once" را با "enter" بزنید. همچنین می‌توانید کلید فلش رو به پایین را فشار داده و Enter را بزنید تا "2. Allow for this session" را انتخاب کنید، که باعث می‌شود Gemini CLI همیشه آن اقدام را به طور مستقل و بدون درخواست اجازه شما، در طول این مکالمه انجام دهد. با این حال، اگر Gemini CLI را ببندید و دوباره آن را باز کنید، دیگر آن اجازه را نخواهد داشت و قبل از انجام هر اقدامی، بار دیگر از شما اجازه خواهد گرفت.

توجه: اگر در اجرای دستورات به مشکل برخوردید، یا خواستید دوباره از ابتدا امتحان کنید، می‌توانید با اجرای دستور ../break.sh از دایرکتوری cymbal-bank ، مانیفست‌های Kubernetes را در هر زمانی به حالت اولیه‌ی خراب خود برگردانید.

توجه: اگر به محدودیت استفاده رسیدید، گزینه «توقف» را انتخاب کنید و سپس /model را اجرا کنید تا ببینید کدام مدل‌ها به محدودیت خود رسیده‌اند و به مدل دیگری مانند gemini-2.5-flash-lite تغییر دهید. سپس با استفاده از «ادامه» از مدل بخواهید که با استفاده از مدل جدید به کار خود در آزمایشگاه ادامه دهد.

۶. فاز ۳: اشکال‌زدایی کامل متن (Gemini CLI + GKE MCP)

اگرچه فاز ۲ نشان داد که هوش مصنوعی وقتی می‌تواند فایل‌های شما را ببیند چقدر می‌تواند قدرتمند باشد، اما پر سر و صدا نیز بود. شما مجبور بودید هر فایل خوانده شده و عملکرد ابزار را به صورت دستی تأیید کنید، که این امر در طول یک جلسه اشکال‌زدایی پیچیده، اصطکاک قابل توجهی ایجاد می‌کند. فاز ۳ سرور GKE MCP را برای کمک به رفع این مشکل معرفی می‌کند و "آگاهی زیرساختی" مستقیمی را برای هوش مصنوعی فراهم می‌کند. این امر به Gemini اجازه می‌دهد تا لاگ‌ها، رویدادها و فراداده‌ها را با وقفه‌های دستی کمتری عیب‌یابی کند و یک جریان عیب‌یابی خودکارتر و منسجم‌تر ایجاد کند.

ام سی پی چیست؟

برای درک MCP، ابتدا درک مفهوم ابزارها در دنیای هوش مصنوعی مفید است. یک ابزار اساساً یک تابع یا برنامه خارجی است که یک LLM می‌تواند از آن برای انجام اقدامات یا دریافت داده‌هایی که در غیر این صورت قادر به دسترسی به آنها نیست - مانند بررسی آب و هوا، اجرای یک اسکریپت خاص یا پرس و جو از یک پایگاه داده - استفاده کند. در حالی که ابزارهای منفرد قدرتمند هستند، اشتراک‌گذاری ایمن و مداوم آنها بین عوامل و محیط‌های مختلف هوش مصنوعی همیشه یک چالش بوده است. MCP این مشکل را با عمل به عنوان یک پلتفرم استاندارد که می‌تواند میزبان این ابزارها باشد و آنها را در اختیار هر کلاینت هوش مصنوعی سازگار قرار دهد، حل می‌کند.

پروتکل زمینه مدل (MCP) یک پروتکل متن‌باز است که به مدل‌های هوش مصنوعی امکان دسترسی ایمن به منابع داده و ابزارهای خارجی را می‌دهد. MCP به جای یکپارچه‌سازی‌های کدنویسی‌شده برای هر ابزار یا پایگاه داده خاص، روشی استاندارد برای تعامل مدل‌ها با محیط خود فراهم می‌کند.

شما می‌توانید ابزارهای موجود در Gemini CLI را با اجرای /mcp در داخل Gemini CLI مشاهده کنید.

در این آزمایشگاه، سرور GKE MCP به Gemini CLI اجازه می‌دهد تا مستقیماً با کلاستر GKE شما تعامل داشته باشد و آن را قادر می‌سازد تا منابع را بررسی کند، گزارش‌ها را بخواند و با آگاهی کامل از وضعیت فعال کلاستر، به شما در اشکال‌زدایی مشکلات کمک کند. این امر هوش مصنوعی را از یک تحلیلگر کد استاتیک به یک دستیار عیب‌یابی فعال تبدیل می‌کند که وضعیت فعال زیرساخت شما را درک می‌کند.

پیکربندی افزونه GKE MCP

به طور پیش‌فرض، Gemini CLI یک ابزار عمومی است. سرور GKE MCP را با ایجاد یک فایل پیکربندی پیکربندی کنید.

1. 👉💻 ابتدا، اگر هنوز در محیط خط فرمان Gemini هستید، با تایپ کردن /quit ‎ از آن خارج شوید.
2. 👉💻 دستور زیر را برای ایجاد دایرکتوری افزونه اجرا کنید:

   mkdir -p ~/.gemini/extensions/gke
   

3. 👉💻 دستور زیر را برای ایجاد فایل پیکربندی اجرا کنید. این دستور به طور خودکار PROJECT_ID شما را به فایل تزریق می‌کند:

   cat << EOF > ~/.gemini/extensions/gke/gemini-extension.json
   {
     "name": "gke",
     "version": "1.0.0",
     "mcpServers": {
       "container": {
         "httpUrl": "https://container.googleapis.com/mcp",
         "authProviderType": "google_credentials",
         "oauth": {
           "scopes": ["https://www.googleapis.com/auth/container"]
         },
         "timeout": 30000,
         "headers": {
           "x-goog-user-project": "$PROJECT_ID"
         }
       }
     }
   }
   EOF
   

4. 👉💻 رابط خط فرمان Gemini را اجرا کنید:

   gemini
   

5. با تایپ کردن /mcp ‎ در رابط خط فرمان Gemini، تأیید کنید که سرور MCP فعال شده است.

از Gemini بخواهید با استفاده از حالت خوشه اشکال‌زدایی کند

1. اشکال‌زدایی از استقرار ناموفق: اکنون، از Gemini بخواهید که خوشه را بررسی کرده و بر اساس یافته‌های خود، مانیفست‌ها را اصلاح کند.
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   The frontend deployment is failing. Can you use your tools to check the logs and events of the pods, and then fix it?
   Gemini از ابزارهای MCP برای فراخوانی دستورات kubectl در پشت صحنه استفاده می‌کند. این ابزار خطای ImagePullBackOff را می‌بیند، علت را توضیح می‌دهد و راه حل صحیح را پیشنهاد می‌دهد.
2. رفع مشکلات پیچیده: از آن بخواهید که گزارش‌های مربوط به خطاهای سطح برنامه را بررسی کند.
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   Check the logs for the 'contacts' pod. Why is it failing to connect to the database?
   خطای عدم پذیرش اتصال را می‌بیند و آن را به عدم تطابق پورت یا عدم تطابق نام سرویس در config.yaml ردیابی می‌کند!
3. تکرار: از Gemini بخواهید سایر مشکلاتی را که در مرحله 0 پیدا کرده‌اید، برطرف کند.
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   Check if the service 'contacts' is correctly routing traffic to its pods
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   Are there any pods failing due to resource limits?

توجه: اگر در اجرای دستورات به مشکل برخوردید، یا خواستید دوباره از ابتدا امتحان کنید، می‌توانید با اجرای دستور ../break.sh از دایرکتوری cymbal-bank ، مانیفست‌های Kubernetes را در هر زمانی به حالت اولیه‌ی خراب خود برگردانید.

۷. مرحله ۴: توانمندسازی تیم (مهارت‌های نماینده)

در نهایت، با ایجاد مهارت‌های سفارشی برای عامل‌ها، قابلیت‌های هوش مصنوعی را برای نیازهای خاص خود گسترش دهید.

مهارت‌های عامل چیست؟

مهارت‌های عامل، بسته‌هایی از دستورالعمل‌ها، اسکریپت‌ها و منابع هستند که یک عامل هوش مصنوعی را برای وظایف تخصصی گسترش می‌دهند. آن‌ها به شما امکان می‌دهند استانداردهای سازمانی را کدگذاری کرده و گردش‌های کاری پیچیده را خودکار کنید. یک مهارت در یک دایرکتوری خاص قرار دارد و حاوی یک فایل SKILL.md است که رفتار آن را تعریف می‌کند. با ایجاد مهارت‌ها، اطمینان حاصل می‌کنید که هوش مصنوعی به جای بداهه‌پردازی، از یک فرآیند ثابت و تکرارپذیر پیروی می‌کند.

یک فهرست مهارت معمولی به این شکل است:

my-skill/
├── SKILL.md          # Main instruction file (Required)
├── scripts/           # Helper scripts (Optional)
└── resources/         # Templates or data files (Optional)

ایجاد مهارت عیب‌یابی در Kubernetes

به جای ایجاد دستی این فایل‌ها، Gemini CLI روشی قدرتمند برای ایجاد مهارت‌ها با استفاده از زبان طبیعی ارائه می‌دهد.

تصور کنید می‌خواهید یک مهارت به نام k8s-troubleshooter ایجاد کنید تا مراحلی را که انجام داده‌اید، خودکارسازی کند.

1. ایجاد مهارت از طریق ایجاد انگیزه: می‌توانید از Gemini CLI بخواهید که بر اساس آنچه امروز آموخته‌اید، مهارت را برای شما ایجاد کند.
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   Create a new skill called 'k8s-troubleshooter' that helps diagnose issues with Kubernetes manifests and cluster state. It should be able to analyze pod logs, events, and resource descriptions to identify common deployment problems and configuration errors.
   مشابه زمانی که ابزاری را فراخوانی می‌کند یا عملی را انجام می‌دهد، رابط خط فرمان Gemini باید به شما بگوید که اعلان شما مهارت "skill-creator" خود را فعال کرده است. این یک مهارت از پیش پیکربندی شده در رابط خط فرمان Gemini است که به Gemini امکان ایجاد مهارت‌های عامل (Agent Skills) را می‌دهد.
   جمینی باید از شما اجازه ایجاد فهرست مهارت‌ها را بخواهد. با انتخاب « 1. اجازه یک بار » تأیید کنید.
   جمینی به طور خودکار:
   • یک دایرکتوری در ~/.gemini/skills/k8s-troubleshooter/ ایجاد می‌کند.
   • یک فایل SKILL.md با دستورالعمل‌هایی بر اساس درخواست شما تولید می‌کند.
   • دایرکتوری‌های منابع استاندارد ایجاد می‌کند.
2. خط فرمان Gemini را مجدداً راه‌اندازی کنید:
   👉💻 رابط خط فرمان Gemini را با /quit ‎ ببندید و سپس آن را مجدداً راه‌اندازی کنید:

   gemini
   

3. تأیید کنید که مهارت بارگذاری شده است:
   👉💻 با تایپ کردن /skills در خط فرمان Gemini، از فعال بودن مهارت اطمینان حاصل کنید. باید k8s-troubleshooter در لیست ببینید.
4. نحوه عملکرد آن در عمل: حالا، مهارت را فراخوانی کنید:
   👉💬 این دستور را در رابط خط فرمان Gemini وارد کنید:
   Use the k8s-troubleshooter skill to find out why the contacts service is failing.
   هوش مصنوعی به جای بداهه‌پردازی، از طرح ساختاریافته‌ی SKILL.md پیروی می‌کند و منجر به نتایج منسجم‌تری می‌شود.

تمرین: مهارت‌های خودتان را تصور کنید

به گردش کار روزانه خود فکر کنید. چه کار تکراری را می‌توانید با یک مهارت خودکار کنید؟

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

۸. نتیجه‌گیری

این آزمایشگاه با پیشرفت در سطوح مختلف زمینه هوش مصنوعی، روش جدیدی برای تعامل با زیرساخت ابری را نشان می‌دهد. با حرکت از زمینه صفر به زمینه کامل زیرساخت (Gemini CLI + GKE MCP)، خواهید دید که یک دستیار هوش مصنوعی هنگام مشاهده فایل‌ها و وضعیت خوشه شما چقدر مؤثرتر می‌شود.

خلاصه آزمایشگاه

• اهمیت زمینه: می‌بینید که ابزارهای هوش مصنوعی بدون زمینه نمی‌توانند به مشکلات خاص کدبیس کمک کنند.
• زمینه ترمینال: شما از رابط خط فرمان Gemini برای تجزیه و تحلیل فایل‌های محلی و شناسایی خطاهای پیکربندی مستقیماً از فضای کاری خود استفاده می‌کنید.
• اشکال‌زدایی کامل متن: شما از رابط خط فرمان Gemini به همراه MCP استفاده می‌کنید تا به هوش مصنوعی اجازه دهید با مرتبط کردن فایل‌های کدبیس با وضعیت زنده خوشه، مشکلات پیچیده را تشخیص داده و برطرف کند.
• توسعه‌پذیری: شما در مورد مهارت‌ها و نحوه استفاده از آنها برای کدگذاری دانش سازمانی یاد می‌گیرید.

پاکسازی

برای جلوگیری از هزینه‌های جاری، اسکریپت teardown را اجرا کنید. توجه داشته باشید که اگر آزمایشگاه را روی Qwiklabs اجرا می‌کنید، این مرحله ضروری نیست.

👉💻 دستور زیر را از دایرکتوری کارگاه اجرا کنید:

cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/
./teardown.sh

مراحل بعدی

در اینجا چند توصیه برای مطالعه بیشتر ارائه شده است:

• مستندات رابط خط فرمان Gemini : مستندات رسمی رابط خط فرمان Gemini.
• مستندات GKE : صفحه اصلی برای همه مستندات GKE.
• مهندسی پلتفرم در گوگل کلود : راهنمایی در مورد چگونگی رویکرد به مهندسی پلتفرم در گوگل کلود.
• هوش مصنوعی و یادگیری ماشینی در GKE : مستنداتی در مورد اجرای بارهای کاری هوش مصنوعی/یادگیری ماشینی در GKE.
• مرکز معماری ابری گوگل : راهنمایی و بهترین شیوه‌ها برای ایجاد بارهای کاری در فضای ابری گوگل

۹. پیوست: راهکاری برای آشکار کردن شکستگی‌ها

اگر در اجرای دستورات با مشکل مواجه شدید یا خواستید خطاها را بررسی کنید، در اینجا لیستی از خطاهای ایجاد شده در دایرکتوری manifests-broken/ و نحوه رفع آنها آمده است:

1. URL های ناقص در config.yaml :
   • خطا: TRANSACTIONS_API_ADDR: "ledgerwriter::8080" (دو نقطه).
   • دلیل: برنامه نمی‌تواند آدرس را تجزیه و تحلیل کند و منجر به خطاهای اتصال می‌شود.
   • راه حل: آن را دوباره به "ledgerwriter:8080" تغییر دهید.
2. برچسب‌های نامتناسب در contacts.yaml :
   • خطا: انتخابگر سرویس به جای contacts روی app: contacts-backend تنظیم شده است.
   • چرا: سرویس نمی‌تواند پادها (که هنوز app: contacts دارند) را پیدا کند، بنابراین ترافیک مسیریابی نخواهد شد.
   • راه حل: انتخابگر را به app: contacts تغییر دهید.
3. عدم تطابق پورت در userservice.yaml :
   • خطا: targetPort سرویس به جای 8080 روی 8081 تنظیم شده است.
   • دلیل: ترافیک ارسالی به سرویس به پورت کانتینر اشتباه هدایت می‌شود و باعث عدم برقراری ارتباط می‌گردد.
   • راه حل: targetPort دوباره به 8080 تغییر دهید.
4. نام‌های سرویس نامتناسب در config.yaml :
   • خطا: BALANCES_API_ADDR: "balance-reader:8080" (به جای balancereader ).
   • دلیل: نام میزبان در DNS مشخص نمی‌شود زیرا نام سرویس balancereader است.
   • رفع مشکل: آن را دوباره به "balancereader:8080" تغییر دهید.
5. سیاست‌های دریافت تصویر در contacts.yaml :
   • خطا: imagePullPolicy: Never .
   • چرا: K8ها با فرض اینکه تصویر محلی است، آن را از رجیستری استخراج نمی‌کنند. این کار با ErrImagePull با شکست مواجه خواهد شد.
   • راه حل: خط را حذف کنید یا آن را روی IfNotPresent تنظیم کنید.
6. بررسی خرابی‌های مربوط به آمادگی در userservice.yaml :
   • خطا: مسیر به جای /ready به /healthz تغییر یافت.
   • دلیل: کانتینر /healthz را سرویس نمی‌دهد، بنابراین پروب از کار می‌افتد و پاد هرگز آماده علامت‌گذاری نمی‌شود.
   • رفع مشکل: مسیر را به /ready تغییر دهید.
7. محدودیت‌های منابع در contacts.yaml :
   • خطا: محدودیت حافظه به جای 128Mi میلی‌آمپر روی 10Mi تنظیم شده است.
   • دلیل: برنامه برای شروع به حافظه بیشتری نیاز دارد و باعث می‌شود که OOMKilled شود.
   • راه حل: محدودیت حافظه را بازیابی کنید.
8. متغیرهای محیطی در frontend.yaml وجود ندارند :
   • خطا: REGISTERED_OAUTH_CLIENT_ID env حذف شد.
   • چرا: اگر متغیرهای محیطی مورد انتظار وجود نداشته باشند، ممکن است برنامه از کار بیفتد یا ویژگی‌های آن غیرفعال شوند.
   • رفع مشکل: تعریف متغیر محیطی را بازیابی کنید.
9. عدم تطابق کلید ConfigMap در frontend.yaml :
   • خطا: key: DEMO_USER به جای DEMO_LOGIN_USERNAME .
   • دلیل: K8ها نمی‌توانند کلید را در ConfigMap پیدا کنند و باعث می‌شوند کانتینر شروع به کار نکند.
   • راه حل: کلید را دوباره به DEMO_LOGIN_USERNAME تغییر دهید.
10. اشتباه تایپی در نام تصویر در userservice.yaml :
    • خطا: به جای userservice از user-service .
    • دلیل: تصویر در رجیستری وجود ندارد و باعث ImagePullBackOff می‌شود.
    • اصلاح: نام تصویر را اصلاح کنید.
11. مشکلات حساب سرویس در contacts.yaml :
    • خطا: bank-of-anthos-sa به جای bank-of-anthos .
    • دلیل: حساب کاربری ServiceAccount وجود ندارد یا فاقد مجوز است.
    • راه حل: از نام صحیح ServiceAccount استفاده کنید.