从意图到基础架构：通过代理将应用迁移到 GKE

1. 简介

在此 Codelab 中，您将学习如何使用 AI 智能体自动执行复杂的基础架构迁移。您无需手动编写 Kubernetes 清单或运行自动化脚本，只需使用自然语言表达您的 意图 ，智能体就会使用 Model Context Protocol (MCP) 和 Gemini Cloud Assist 服务器为您生成并应用配置。

重要提示： 此 Codelab 重点介绍了 Gemini Cloud Assist (GCA) MCP 服务器，该服务器目前处于非公开预览版阶段。即使您无法访问完整的功能集，仍可以继续学习此 Codelab。但是，如果您未获准访问突变功能（特别是 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 模型时需要）。

此 Codelab 适用于各种水平的开发者，包括新手。

预计时长： 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 存储分区来准备环境。

组织通常从 Gemini API 开始，但后来决定迁移到自行托管的模型，以便更好地控制、自定义或使用针对其业务进行微调的版本。在此 Codelab 中，我们以 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. 在 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 时收到“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。点击该网址，在浏览器中打开聊天机器人。现在，您可以与聊天机器人互动，该聊天机器人目前针对 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 命令会在您的 GKE 集群上创建一个 Kubernetes 作业来处理下载。只要作业正在运行，Terraform 脚本就会保持活动状态。

如果您想从其他 shell 会话监控进度，或者在运行后验证其是否已完成，可以运行：

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 界面中启用突变功能。

1. 点击 Google Cloud 控制台窗口右上角的 Gemini 徽标，打开 Gemini Assist 边栏。
   
   
2. 启用边栏中列出的任何必要 API。
   
   
3. 导航到边栏中的设置，然后选中 “启用 Cloud Assist 以执行操作”。
   
   
   

配置智能体规则

项目目录的根目录 (intent-to-infrastructure) 中包含自定义 gemini.md 文件。此文件包含指导智能体使用正确工具的规则。

验证此文件是否存在于您的目录中。您应从此目录运行 gemini，以便其能够访问 Terraform 文件、应用代码和 gemini.md 规则文件。

5. 第 1 步：将聊天机器人迁移到 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 部署 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 分钟的时间才能从存储分区中完全加载模型权重并开始提供服务，这是因为模型很大。您可以通过检查日志来监控加载进度：

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

2. vLLM 准备就绪后，根据需要再次转发聊天机器人服务并对其进行测试。它现在应由自行托管的 Gemma 模型提供支持！

7. 清理

为避免系统向您的 Google Cloud 账号持续收取费用，请删除在此 Codelab 期间创建的资源。

运行基础基础架构的销毁命令：

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 的迁移。