可易

使用 ADK 和 Vertex AI 在 GKE 上部署智能体应用

可易团队阅读约 12 分钟

本指南说明如何用 GKE、ADK 与 Vertex AI，把基于 FastAPI、由 Gemini 2.5 Flash 驱动的智能体做成容器，部署到集群并完成接口测试与资源清理。

目录

使用 Agent Development Kit（ADK）和 Vertex AI 在 GKE 上部署智能体应用

本指南演示如何使用谷歌 Kubernetes 引擎（Google Kubernetes Engine，GKE）部署并管理容器化的智能体人工智能／机器学习应用。把谷歌智能体开发套件（Agent Development Kit，ADK）与作为大语言模型（large language model，LLM）提供方的 Vertex AI 结合起来，你可以高效、规模化地把人工智能智能体投入运行。本指南带你走完端到端过程：把一个由 Gemini 2.5 Flash 驱动、基于 FastAPI 的智能体，从开发推进到在 GKE 上的生产部署。

本指南面向希望使用 Kubernetes 容器编排能力来提供智能体人工智能／机器学习应用的机器学习（Machine learning，ML）工程师、开发者和云架构师。要进一步了解 Google Cloud 内容中的常见角色和示例任务，请参阅常见的 GKE 用户角色与任务。

开始之前，请确保你熟悉以下内容：

背景

本指南把若干 Google 技术组合起来，搭建一个可扩展的智能体人工智能平台。GKE 为用 ADK 构建的智能体提供容器编排。通过 Vertex AI API 做大语言模型推理，GKE 集群不需要专门的 GPU 硬件，因为推理由 Google 的托管基础设施处理。

谷歌智能体开发套件（Google Agent Development Kit，ADK）

智能体开发套件（Agent Development Kit，ADK）是用于开发和部署人工智能智能体的灵活、模块化框架。它针对 Gemini 和 Google 生态系统做了优化，但 ADK 与模型无关、与部署方式无关，并且为与其他框架兼容而构建。

更多信息见 ADK 文档。

GKE 托管的 Kubernetes 服务

GKE 是用于部署、扩展和管理容器化应用的托管 Kubernetes 服务。GKE 提供所需基础设施，包括可扩展资源、分布式计算和高效网络，以应对大语言模型的计算需求。

关于关键 Kubernetes 概念的更多信息，见开始学习 Kubernetes。关于 GKE 以及它如何帮助你扩展、自动化并管理 Kubernetes 的更多信息，见 GKE 概述。

Vertex AI

Vertex AI 是 Google Cloud 统一的机器学习平台，让开发者能够构建、部署并扩展人工智能／机器学习模型。对于 GKE 上的智能体人工智能应用，Vertex AI 提供必要的工具和服务，包括对 Gemini 2.5 Flash 等大语言模型的访问、用于训练和推理的托管基础设施，以及用于高效生命周期管理的 MLOps 能力。

通过 Vertex AI API 使用大语言模型时，模型推理发生在 Google 的托管基础设施上，从而降低你的 GKE 集群对特定 GPU 或 TPU 配额的需求。

关于面向智能体人工智能应用的 Vertex AI 的更多信息，见 Vertex AI 文档。

Gemini 2.5 Flash

Gemini 2.5 Flash 提供面向智能体工作负载设计的下一代特性和更强能力，包括更高速度、内置工具使用、多模态生成，以及 100 万 token 的上下文窗口。Gemini 2.5 Flash 改进了上一代 Flash 模型，并在相近速度下提供更高质量。

关于 Gemini 2.5 Flash 的技术信息（例如性能基准、训练数据集信息、可持续性方面的工作、预期用途与限制，以及伦理与安全方面的做法），见 Gemini 2.5 Flash 模型卡。

目标

本指南说明如何完成以下事项：

  • 设置你的 Google Cloud 环境。
  • 为你的智能体构建容器镜像。
  • 把智能体部署到 GKE 集群。
  • 测试已部署的智能体。

费用

本指南使用 Google Cloud 的以下计费组件：

请查看各项服务的价格，以了解可能产生的费用。

开始之前

登录你的 Google Cloud 账号。如果你是 Google Cloud 的新用户，请创建账号，以便评估我们的产品在真实场景中的表现。新客户还会获得 300 美元免费赠金，用于运行、测试和部署工作负载。

在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。

选择或创建项目所需的角色

  • 选择项目：选择项目不需要特定的 IAM 角色——你可以选择任何已向你授予角色的项目。
  • 创建项目：要创建项目，你需要 Project Creator 角色（roles/resourcemanager.projectCreator），其中包含 resourcemanager.projects.create 权限。了解如何授予角色。

转到项目选择器

验证你的 Google Cloud 项目已启用结算。

启用所需的 API（如果尚未启用）。

启用 API 所需的角色

要启用 API，你需要 serviceusage.services.enable 权限。如果你创建了该项目，则很可能已经通过 Owner 角色（roles/owner）拥有此权限。否则，你可以通过 Service Usage Admin 角色（roles/serviceusage.serviceUsageAdmin）获得此权限。了解如何授予角色。

启用这些 API

确认你在该项目上拥有以下一个或多个角色：

roles/container.admin, roles/iam.serviceAccountAdmin, roles/artifactregistry.admin, roles/cloudbuild.builds.editor, roles/resourcemanager.projectIamAdmin

检查角色

  1. 在 Google Cloud 控制台中，转到 IAM 页面。

转到 IAM

  1. 选择项目。
  2. 在主账号（Principal）列中，找出标识你本人或你所在群组的所有行。要了解你属于哪些群组，请联系管理员。
  3. 对于指定或包含你的所有行，查看角色（Role）列，确认角色列表是否包含所需角色。

授予角色

  1. 在 Google Cloud 控制台中，转到 IAM 页面。

转到 IAM

  1. 选择项目。
  2. 点击授予访问权限（Grant access）。
  3. 在新的主账号（New principals）字段中，输入你的用户标识。

这通常是 Google 账号的电子邮件地址。

  1. 点击选择角色（Select a role），然后搜索该角色。
  2. 要授予其他角色，点击添加其他角色（Add another role），并添加每一个额外角色。
  3. 点击保存（Save）。

准备环境

本教程使用 Cloud Shell 管理托管在 Google Cloud 上的资源。Cloud Shell 预装了本教程所需的软件，包括 kubectl、terraform 和 Google Cloud CLI。

要使用 Cloud Shell 设置环境，请按以下步骤操作：

  1. 在 Google Cloud 控制台中启动 Cloud Shell 会话，并点击激活 Cloud Shell（Activate Cloud Shell）。此操作会在 Google Cloud 控制台底部窗格中启动一个会话。
  2. 设置默认环境变量：
gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_LOCATION=REGION
export PROJECT_ID=PROJECT_ID
export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
export WORKLOAD_POOL=$PROJECT_ID.svc.id.goog
export PROJECT_NUMBER=$(gcloud projects describe --format json $PROJECT_ID | jq -r ".projectNumber")

替换以下值：

  • PROJECT_ID：你的 Google Cloud 项目 ID。
  • REGION：用于预配 GKE 集群、Artifact Registry 和其他区域级资源的 Google Cloud 区域（例如 us-central1）。

克隆示例项目

  1. 在 Cloud Shell 终端中，克隆本教程的示例代码仓库：
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
  1. 进入教程目录：
cd kubernetes-engine-samples/ai-ml/adk-vertex

创建并配置 Google Cloud 资源

要把智能体部署到 GKE，请预配必要的 Google Cloud 资源。你可以使用 gcloud CLI 直接在命令行执行，也可以使用 Terraform 做基础设施即代码。

#### 使用 gcloud CLI

本节提供 gcloud CLI 命令，用于设置 GKE 集群、Artifact Registry，以及用于与 Vertex AI 无缝集成的 GKE 工作负载身份联合（Workload Identity Federation for GKE）。请确保你已按准备环境中的说明设置了环境变量。

  1. 创建 GKE 集群：你可以在 GKE Autopilot 或 Standard 集群中部署容器化智能体应用。使用 Autopilot 集群可获得完全托管的 Kubernetes 体验。要选择最适合你工作负载的 GKE 运行模式，见选择 GKE 运行模式。

Autopilot

在 Cloud Shell 中运行以下命令：

gcloud container clusters create-auto CLUSTER_NAME \
           --location=$GOOGLE_CLOUD_LOCATION \
           --project=$PROJECT_ID

把 CLUSTER_NAME 替换为你的 GKE Autopilot 集群名称。

Standard

在 Cloud Shell 中运行以下命令：

gcloud container clusters create CLUSTER_NAME \
       --location=$GOOGLE_CLOUD_LOCATION \
       --project=$PROJECT_ID \
       --release-channel=stable \
       --num-nodes=1 \
       --machine-type=e2-medium \
       --workload-pool=$PROJECT_ID.svc.id.goog

把 CLUSTER_NAME 替换为你的 Standard 集群名称。

  1. 为 Docker 容器创建 Artifact Registry 仓库：创建一个 Artifact Registry 仓库，以便安全地存储和管理智能体的 Docker 容器镜像。这个私有仓库有助于确保应用可以随时部署到 GKE，并与 Cloud Build 集成。
gcloud artifacts repositories create adk-repo \
       --repository-format=docker \
       --location=$GOOGLE_CLOUD_LOCATION \
       --project=$PROJECT_ID
  1. 获取仓库 URL：运行此命令以核验仓库的完整路径。下一步为 Docker 镜像打标签时会使用此路径格式。
gcloud artifacts repositories describe adk-repo \
       --location $GOOGLE_CLOUD_LOCATION \
       --project=$PROJECT_ID
  1. 向 Compute Engine 默认服务账号授予所需的 IAM 角色：默认情况下，Compute Engine 默认服务账号没有向 Artifact Registry 推送镜像的权限，也没有查看 Cloud Storage 中对象或日志的权限。为这些操作授予必要角色。
ROLES_TO_ASSIGN=(
       "roles/artifactregistry.writer"
       "roles/storage.objectViewer"
       "roles/logging.viewer"
)

for ROLE in "${ROLES_TO_ASSIGN[@]}"; do
       gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
           --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
           --role="${ROLE}"
done
  1. 构建并推送智能体容器镜像：运行此命令来构建 Docker 镜像，并把它推送到你的 Artifact Registry。请确保 Dockerfile 和应用代码位于 /app 目录内。
export IMAGE_URL="${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest"

gcloud builds submit \
       --tag "$IMAGE_URL" \
       --project="$PROJECT_ID" \
       app
  1. 验证镜像已推送：
gcloud artifacts docker images list \
       $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \
       --project=$PROJECT_ID

#### 使用 Terraform

本节说明如何使用 Terraform 预配 Google Cloud 资源。你克隆的示例仓库包含必要的 Terraform 配置文件。

  1. 初始化 Terraform：进入 terraform 目录并初始化 Terraform。
terraform init
  1. 查看执行计划：此命令显示 Terraform 将做的基础设施变更。
terraform plan -var-file=default_env.tfvars
  1. 应用配置：执行 Terraform 计划，在你的 Google Cloud 项目中创建资源。出现提示时以 yes 确认。
terraform apply -var-file=default_env.tfvars

运行这些命令后，Terraform 会预配你的 GKE 集群和 Artifact Registry 仓库，并配置必要的 IAM 角色和服务账号，包括 GKE 的工作负载身份联合（Workload Identity Federation for GKE）。

要进一步了解如何使用 Terraform，见 Terraform 对 GKE 的支持。

配置 kubectl 以与集群通信

如果你尚未配置 kubectl 与集群通信，请运行以下命令：

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_LOCATION}

把 CLUSTER_NAME 替换为你的 GKE 集群名称。

为 GKE 访问配置工作负载身份联合（Workload Identity Federation）

如果你使用的是 Terraform，可以跳过此步骤。此过程为你的 Kubernetes ServiceAccount 授予与 Vertex AI 交互的权限。

  1. 在集群中创建一个 Kubernetes ServiceAccount。运行此命令之前，请确保已按照配置 kubectl 以与集群通信中的说明操作：
kubectl create serviceaccount vertex-sa
  1. 在项目上为该 Kubernetes ServiceAccount 授予 Vertex AI User 角色（roles/aiplatform.user）：
gcloud projects add-iam-policy-binding $PROJECT_ID \
       --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/vertex-sa" \
       --role="roles/aiplatform.user" \
       --condition=None

部署并配置智能体应用

设置好 Google Cloud 资源后，准备智能体应用以便部署，并配置它在 GKE 上的运行时。这包括定义智能体代码、创建用于将其容器化的 Dockerfile，以及编写用于将其部署到集群的 Kubernetes 清单。

  1. 了解智能体应用结构：/app 目录包含智能体应用的核心文件：
  • main.py：FastAPI 应用入口，负责公开智能体的 API。
  • agent.py：包含 ADK 智能体的逻辑，定义它如何使用 Vertex AI 以及如何处理请求。
  • __init__.py：初始化该 Python 包。
  • requirements.txt：列出智能体的全部 Python 依赖。
  • Dockerfile：定义如何把应用打包成 Docker 镜像。
  1. 创建智能体部署清单：在 tutorials-and-examples/adk/vertex 目录中，创建以下清单，并保存为名为 agent-deployment.yaml 的文件：
apiVersion: apps/v1
kind: Deployment
metadata:
     name: adk-agent-deployment
     labels:
       app: adk-agent
       # Identifies the workload as an AI agent and adds it to the registry
       registry.gke.io/functional-type: "AGENT"
spec:
     replicas: 1
     selector:
       matchLabels:
         app: adk-agent
     template:
       metadata:
         labels:
           app: adk-agent
       spec:
         serviceAccountName: vertex-sa
         containers:
      - name: adk-agent
        image: IMAGE_URL
        ports:
        - containerPort: 8000
        env:
        - name: GOOGLE_CLOUD_PROJECT_ID
          value: PROJECT_ID
        - name: GOOGLE_CLOUD_LOCATION
          value: REGION
        - name: GOOGLE_GENAI_USE_VERTEXAI
          value: "1"
        - name: PORT
          value: "8000"
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1"

替换以下值：

  • IMAGE_URL：你推送到 Artifact Registry 的 Docker 镜像完整 URL（例如 us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest）。你可以从上一节 gcloud artifacts docker images list 命令的输出中取得此值。也可以运行类似下面的命令：sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml。
  • PROJECT_ID：你的 Google Cloud 项目 ID。
  • REGION：预配 GKE 集群所在的 Google Cloud 区域。
  1. 应用部署清单：
kubectl apply -f agent-deployment.yaml

此命令会在 GKE 集群中为你的智能体应用创建 Deployment 及相关 Pod，并把该智能体注册到 Agent Registry。

  1. 公开智能体：你可以使用这些方法公开智能体以便访问。
  • 要从集群外部访问智能体，请创建一个 Kubernetes Service。对于 Web API，LoadBalancer 类型的服务很常见。
  • 对于本地开发和测试，使用 kubectl port-forward 命令直接访问智能体。

LoadBalancer

  1. 创建以下清单，并保存为名为 agent-service.yaml 的文件：
apiVersion: v1
kind: Service
metadata:
  name: adk-agent-service
spec:
  selector:
    app: adk-agent
  type: LoadBalancer # Creates an external IP address for access
  ports:
- protocol: TCP
  port: 80
  targetPort: 8000 # Matches the containerPort exposed in the Deployment
  1. 应用该清单：
kubectl apply -f agent-service.yaml

外部 IP 地址的预配可能需要几分钟。

  1. 验证 IP 地址已预配：
kubectl get service adk-agent-service

在输出中查找 EXTERNAL-IP 值。该值可用后，使用此 IP 地址与已部署的智能体交互。

port-forward

如果你主要使用 port-forward，可以考虑使用 ClusterIP 服务类型而不是 LoadBalancer，因为 ClusterIP 服务是内部的，消耗的资源更少。

POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward $POD_NAME 8000:8000

此命令会阻塞你的终端，但它会把你机器上 localhost:8000 的流量转发到 GKE 集群内运行的智能体。

测试已部署的智能体

智能体应用已经部署并公开后，测试其功能。

本节说明如何确定智能体的端点并测试智能体的 API。

  1. 确定智能体的端点：根据你在上一节选择的公开方式，确定其可访问端点：

LoadBalancer

  1. 获取外部 IP 地址：
kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
  1. 把外部 IP 地址存入环境变量，以便使用：
export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

智能体的基址 URL 是 http://${AGENT_IP}。

port-forward

请确保 kubectl port-forward 命令在另一个终端中运行。智能体的基址 URL 是 http://localhost:8000。

  1. 测试智能体的 API：向其 /run 端点发起 curl 请求，以测试智能体的 API。智能体期望一个带有 message 字段的 JSON 载荷。把 AGENT_BASE_URL 替换为 http://${AGENT_IP}（LoadBalancer）或 http://localhost:8000（port-forward）。
  1. 创建一个新会话。这会让智能体准备好一次新对话。
# The user ID and session ID are arbitrary.
# The appName must match the agent's Python package directory name (in this case, "capital_agent").
curl -X POST AGENT_BASE_URL/apps/capital_agent/users/user-123/sessions/session-123

你可以用以下命令列出可用应用：

curl -X GET AGENT_BASE_URL/list-apps
  1. 使用上一步的会话详情向智能体发送查询。
curl -X POST AGENT_BASE_URL/run \
-H "Content-Type: application/json" \
-d '{
  "appName": "capital_agent",
  "userId": "user-123",
  "sessionId": "session-123",
  "newMessage": {
    "role": "user",
    "parts": [{"text": "Hello, agent! What can you do for me?"}]
  }
}'

你应当收到来自智能体的 JSON 响应，表明它成功处理了请求，并通过 Vertex AI 与 Gemini 模型交互。响应包含智能体基于你的消息生成的回复。

  1. 访问智能体的 Web 界面（如适用）：如果你的智能体包含基于 Web 的用户界面，在 Web 浏览器中打开 AGENT_BASE_URL 即可访问。ADK 通常包含一个用于交互和调试的基本 Web 界面。例如，如果你使用 LoadBalancer 公开智能体，且其 EXTERNAL-IP 为 34.123.45.67，则在浏览器中打开 http://34.123.45.67。

清理

为避免本教程所用资源继续向你的 Google Cloud 账号产生费用，可以删除包含这些资源的项目，或者保留项目并删除各个资源。

删除已部署的资源

为避免本指南中创建的资源继续向你的 Google Cloud 账号产生费用，请运行以下命令：

gcloud

gcloud container clusters delete CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_LOCATION} \
    --project=$PROJECT_ID

gcloud projects remove-iam-policy-binding $PROJECT_ID \
    --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/vertex-sa" \
    --role="roles/aiplatform.user" \
    --condition=None

gcloud artifacts repositories delete adk-repo \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$PROJECT_ID

把 CLUSTER_NAME 替换为你的 GKE 集群名称。

Terraform

  1. 在 Cloud Shell 终端中，进入 tutorials-and-examples/adk/vertex/ 目录：
cd tutorials-and-examples/adk/vertex/
  1. 运行此命令，移除 Terraform 配置文件中定义的全部资源。
cd terraform
terraform destroy

PRIMARY_SOURCE: https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/agentic-adk-vertex

  • #GKE
  • #ADK
  • #Vertex AI
  • #部署
  • #智能体

继续阅读