從意圖到基礎架構：以代理程式驅動遷移至 GKE 的作業

1. 簡介

在本程式碼研究室中，您將瞭解如何使用 AI 代理自動執行複雜的基礎架構遷移作業。您不需要手動編寫 Kubernetes 資訊清單或執行自動化指令碼，只要以自然語言表達意圖，代理程式就會使用 Model Context Protocol (MCP) 和 Gemini Cloud Assist 伺服器，為您產生及套用設定。

重要事項：本程式碼研究室著重介紹 Gemini Cloud Assist (GCA) MCP 伺服器，這項服務目前為不公開預先發布版。即使無法存取完整功能集，您仍可繼續進行程式碼實驗室。不過，如果系統未授予您變更功能 (具體來說是 invoke_operation 工具) 的存取權，代理程式就無法自動套用變更。在這種情況下，您需要手動套用產生的 Kubernetes 資訊清單。詳情請洽詢您的帳戶團隊。

GCA MCP 伺服器功能

GCA MCP 伺服器為代理提供多種專用工具：

• 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，並使用儲存空間儲存桶中的暫存模型，透過 vLLM 啟動 Gemma 推論執行個體。

學習內容

• 使用 Terraform 準備 GKE 叢集，並下載 Gemma 模型。
• 使用代理規則和 MCP 伺服器設定 gemini-cli。
• 使用特定的自然語言提示，指示代理程式執行完整的遷移和部署作業。
• 驗證代理程式執行的部署作業。

軟硬體需求

• 網路瀏覽器，例如 Chrome。
• 已啟用計費功能的 Google Cloud 專案。
• Hugging Face 權杖 (在暫存階段下載 Gemma 模型時需要)。

本程式碼研究室適合各種程度的開發人員，包括初學者。

預計時長：45 到 60 分鐘。

2. 事前準備

建立或選取 Google Cloud 專案

1. 在 Google Cloud 控制台中，選取或建立 Google Cloud 專案。
2. 確認 Cloud 專案已啟用計費功能。

啟動 Cloud Shell

1. 點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」。
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

3. 準備環境

在本步驟中，您將建構自訂聊天機器人映像檔、建立 GKE 叢集，並將 Gemma 模型下載至 Cloud Storage bucket，藉此準備環境。

許多機構一開始會使用 Gemini API，但後來為了加強控管、自訂或使用專為自家業務微調的版本，決定遷移至自行代管的模型。在本程式碼研究室中，我們以 Gemma 為例，說明如何自行在 GKE 上代管強大的開放式模型。將檔案暫存在 Cloud Storage bucket 中，叢集就能使用。

下載示範素材資源

從 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. 在 asia-southeast1 中建立名為 chatbot-repo 的 Artifact Registry 存放區：

   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 時收到「權限遭拒」錯誤，您可能需要執行 chmod +x deploy.sh，讓 deploy.sh 成為可執行檔。

這個指令碼會使用 Terraform 佈建基礎架構。這項指令會建立 VPC、GKE 叢集和服務帳戶，並使用您剛建構的 Chatbot 映像檔部署初始 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。按一下網址，在瀏覽器中開啟聊天機器人。你現在可以與聊天機器人互動，目前聊天機器人是根據 Gemini 2.5 Flash 運作。

下載模型

在這個步驟中，我們會將 Gemma 模型暫存在 Cloud Storage bucket 中。我們一開始會使用受管理的 Gemini API，但您也可以選擇執行自訂微調模型或其他自訂開放模型。或者，您可能只是基於安全或法規遵循考量，希望在自己的叢集中管理模型執行作業。在此暫存模型，可為從受管理的 Gemini API 遷移至 GKE 上的自行代管模型做好準備。

執行步驟 2，將 Gemma 模型下載至 GCS bucket。您需要 Hugging Face 權杖。這項程序會在 GKE 叢集上執行，從 Hugging Face 下載模型並上傳至 Bucket 供日後使用，大約需要 15 分鐘 (或更久，視流量而定)。

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

這個 Terraform 指令會在 GKE 叢集上建立 Kubernetes Job，以處理下載作業。只要工作仍在執行，Terraform 指令碼就會保持啟用狀態。

如要從其他殼層工作階段監控進度，或在執行後確認是否完成，可以執行下列指令：

kubectl get jobs

4. 設定代理程式和 MCP

現在我們要設定執行遷移作業的代理程式。我們會使用 gemini-cli，並為其設定規則，以便與環境互動。

Gemini Cloud Assist (GCA) MCP 伺服器是這個流程的重要元件。這項服務可做為用戶端代理程式與 Google Cloud 之間的橋樑，讓代理程式執行調查、產生計畫 (例如 gcloud 和 kubectl 指令)，並直接對雲端專案中的資源套用變更。

確認您已獲派可呼叫 MCP 工具的角色，例如 roles/geminicloudassist.user。如果之後遇到權限問題，請參閱說明文件，瞭解如何為 Cloud Assist 設定 IAM 角色。

如需將 Gemini Cloud Assist 與第三方工具整合的詳細操作說明，請參閱「使用 MCP 將 Gemini Cloud Assist 與第三方工具整合」說明文件。

安裝 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 CLI 瞭解使用 Cloud Assist 工具的適當脈絡。

3. 確認技能已順利安裝：啟動 gemini 並執行下列指令，列出有效技能：

/skills list

確認清單中顯示與 Gemini Cloud Assist 相關的技能。輸入 exit，返回 Cloud Shell 提示。

在 Gemini Cloud Assist 中啟用突變

如要允許代理程式對基礎架構套用變更，您必須在 Gemini Cloud Assist UI 中啟用突變功能。

1. 按一下 Google Cloud 控制台視窗右上角的 Gemini 標誌，開啟 Gemini Assist 側邊欄。
   
   
2. 啟用側欄中列出的所有必要 API。
   
   
3. 前往側邊欄中的設定，然後勾選「啟用 Cloud Assist 來執行動作」。
   
   
   

設定代理程式規則

專案目錄的資料夾根目錄 (intent-to-infrastructure) 中包含自訂 gemini.md 檔案。這個檔案包含的規則會引導代理程式使用正確的工具。

確認這個檔案位於您的目錄中。您應從這個目錄執行 gemini，以便存取 Terraform 檔案、應用程式程式碼和 gemini.md 規則檔案。

5. 步驟 1：將 Chatbot 遷移至 GKE

現在我們要使用代理程式執行遷移作業的第一部分：將聊天機器人應用程式從 Cloud Run 遷移至 GKE。

1. 從 intent-to-infrastructure 目錄的根目錄啟動 gemini (確保有權存取 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 伺服器提供工具的權限。請選取「允許」，讓代理程式繼續執行。

5. 輸入 yes 即可套用變更。代理程式會使用 invoke_operation 將資源部署到 GKE 叢集。

驗證步驟 1

1. 取得服務清單：

kubectl get services

您應該會看到聊天機器人應用程式正在執行的服務。

2. 轉送服務通訊埠，存取聊天機器人：

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

(注意：請將

chatbot-service

(如果不同，請改為代理程式產生的實際服務名稱)。

測試聊天機器人。這時應該仍會使用 Gemini API 回應 (如 Cloud Run 中設定)。

6. 步驟 2：透過 vLLM 和 Reconnect 部署 Gemma

在這個步驟中，我們將使用代理在 GKE 上部署自行代管的 Gemma 模型，並重新連結應用程式。

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 為 vLLM 部署作業和服務產生 YAML。
   • 更新聊天機器人部署 YAML，將環境變數 (或設定) 指向新的 vLLM 服務，而非 Gemini API。
   • 要求確認是否要套用變更。
3. 輸入 yes 即可套用變更。

驗證步驟 2

1. 再次取得 Pod 清單：

kubectl get pods

現在應該會看到聊天機器人和 vLLM 的 Pod。

注意：即使 vLLM Pod 處於 Running 狀態，伺服器也可能需要最多 10 分鐘，才能從儲存空間 bucket 完全載入模型權重並開始提供服務，這是因為模型大小較大。您可以查看記錄檔，監控載入進度：

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

2. vLLM 準備就緒後，請視需要再次轉送聊天機器人服務的連接埠，然後進行測試。現在應該會由您自行代管的 Gemma 模型提供支援！

7. 清除

如要避免系統持續向您的 Google Cloud 帳戶收費，請刪除本程式碼研究室建立的資源。

執行基礎架構的 destroy 指令：

cd terraform
./deploy.sh demo step1 destroy

此外，如要清理本機環境，可以解除安裝或停用 Gemini Cloud Assist 擴充功能。使用 gemini extensions uninstall 或 gemini extensions disable，然後輸入擴充功能名稱。

8. 後續步驟

如要進一步瞭解 Gemini Cloud Assist 和進階功能，請參閱下列資源：

• 排解 Cloud Assist 調查功能的問題
• 設定主動模式

9. 恭喜

恭喜！您已成功使用自然語言和 MCP，透過代理程式將工作負載遷移至 GKE。