使用智能体开发套件 (ADK) 和 Vertex AI 在 GKE 上部署智能体 AI 应用

Standard

本指南演示了如何使用 Google Kubernetes Engine (GKE) 部署和管理容器化的智能体 AI/机器学习应用。通过将 Google 智能体开发套件 (ADK) 与作为大语言模型 (LLM) 提供方的 Vertex AI 相结合，您可以高效且大规模地将 AI 智能体投入实际应用。本指南将指导您完成基于 FastAPI 且由 Gemini 2.0 Flash 提供支持的智能体从开发到在 GKE 上进行生产部署的端到端流程。

本指南面向有兴趣使用 Kubernetes 容器编排功能来部署智能体 AI/机器学习应用的机器学习 (ML) 工程师、开发者和云架构师。如需详细了解 Google Cloud 内容中的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

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

背景

本指南结合了多种 Google 技术，可为智能体 AI 创建可扩缩的平台。GKE 为使用 ADK 构建的智能体提供容器编排。通过使用 Vertex AI API 进行 LLM 推断，GKE 集群不需要专门的 GPU 硬件，因为推断由 Google 的托管式基础设施处理。

Google 智能体开发套件 (ADK)

智能体开发套件 (ADK) 是一个灵活的模块化框架，用于开发和部署 AI 智能体。尽管 ADK 针对 Gemini 和 Google 生态系统进行了优化，但它仍不限模型、与部署无关，并且可与其他框架兼容。

如需了解详情，请参阅 ADK 文档。

GKE 托管式 Kubernetes 服务

GKE 是一项托管式 Kubernetes 服务，可用于部署、扩缩和管理容器化应用。GKE 提供必要的基础设施（包括可扩缩资源、分布式计算和高效网络），以满足 LLM 的计算需求。

如需详细了解关键 Kubernetes 概念，请参阅开始了解 Kubernetes。如需详细了解 GKE 以及它如何帮助您扩缩、自动执行和管理 Kubernetes，请参阅 GKE 概览。

Vertex AI

Vertex AI 是 Google Cloud的统一机器学习平台，可让开发者构建、部署和扩缩 AI/ML 模型。对于 GKE 上的智能体 AI 应用，Vertex AI 提供必要的工具和服务，包括对 Gemini 2.0 Flash 等 LLM 的访问权限、用于训练和推理的托管式基础设施，以及用于高效生命周期管理的 MLOps 功能。

通过 Vertex AI API 使用 LLM 时，模型推理会在 Google 的托管式基础设施上进行，从而减少了对 GKE 集群中特定 GPU 或 TPU 配额的需求。

如需详细了解适用于智能体 AI 应用的 Vertex AI，请参阅 Vertex AI 文档。

Gemini 2.0 Flash

Gemini 2.0 Flash 提供了新一代功能并改进了专为智能体工作负载而设计的功能，包括更高的速度、内置工具使用、多模态生成和 100 万个 token 的上下文窗口。Gemini 2.0 Flash 在之前的 Flash 模型的基础上进行了改进，在速度相近的情况下，质量有所提升。

如需了解 Gemini 2.0 Flash 的相关技术信息（例如性能基准、训练数据集相关信息、在可持续发展方面的努力、预期用途和局限性，以及我们在伦理和安全方面的做法），请参阅 Gemini 2.0 Flash 的模型卡片。

目标

本指南介绍如何执行以下操作：

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

费用

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

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

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Enable the APIs

Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin, roles/artifactregistry.admin, roles/cloudbuild.builds.editor, roles/resourcemanager.projectIamAdmin
Check for the roles
1. In the Google Cloud console, go to the IAM page.
  Go to IAM
2. Select the project.
3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.
  前往 IAM
2. 选择项目。
3. 点击 授予访问权限。
4. 在新的主账号字段中，输入您的用户标识符。这通常是 Google 账号的电子邮件地址。
5. 在选择角色列表中，选择一个角色。
6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
7. 点击保存。

准备环境

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

如需使用 Cloud Shell 设置您的环境，请按照以下步骤操作：

在 Google Cloud 控制台中，启动 Cloud Shell 会话，然后点击 激活 Cloud Shell。此操作会在 Google Cloud 控制台的底部窗格中启动会话。

设置默认环境变量：

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）。

克隆示例项目

在 Cloud Shell 终端中，克隆本教程的示例代码库：

git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git

转到教程目录：

cd kubernetes-engine-samples/ai-ml/adk-vertex

创建和配置 Google Cloud 资源

如需将智能体部署到 GKE，请预配必要的Google Cloud 资源。您可以通过两种方式部署智能体：使用 gcloud CLI 直接执行命令行，或使用 Terraform 以基础设施即代码的方式部署。

gcloud

本部分提供了一些 gcloud CLI 命令，用于设置 GKE 集群、Artifact Registry 和 Workload Identity Federation for GKE，以便与 Vertex AI 无缝集成。确保您已按照准备环境中的说明设置环境变量。

创建 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 集群的名称。
为 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
```
获取代码库网址：运行此命令以验证代码库的完整路径。您将在下一步中使用此路径格式来标记 Docker 映像。
```
gcloud artifacts repositories describe adk-repo \
    --location $GOOGLE_CLOUD_LOCATION \
    --project=$PROJECT_ID
```

向 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

构建并推送智能体容器映像：运行此命令以构建 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

验证映像是否已推送：

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 配置文件。

初始化 Terraform：前往 terraform 目录并初始化 Terraform。
```
terraform init
```
查看执行计划：此命令会显示 Terraform 将进行的基础设施更改。
```
terraform plan -var-file=default_env.tfvars
```
应用配置：执行 Terraform 计划，以在 Google Cloud 项目中创建资源。在系统提示时，使用 yes 表示确认。
```
terraform apply -var-file=default_env.tfvars
```
运行这些命令后，Terraform 会预配您的 GKE 集群和 Artifact Registry 代码库，并配置必要的 IAM 角色和服务账号，包括 Workload Identity Federation for GKE。

如需详细了解如何使用 Terraform，请参阅针对 GKE 的 Terraform 支持。

配置 `kubectl` 以与您的集群通信

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

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

将 CLUSTER_NAME 替换为 GKE 集群的名称。

配置 Workload Identity Federation for GKE 访问权限

如果您使用的是 Terraform，则可以跳过此步骤。此流程会将 Kubernetes 服务账号 (KSA) 关联到 IAM 服务账号，以安全地授予智能体对 Google Cloud 服务的访问权限。

创建用于 Vertex AI 访问的服务账号：

gcloud iam service-accounts create vertex-sa \
    --project=$PROJECT_ID

向服务账号授予 aiplatform.user 角色。这样一来，服务账号便可与 Vertex AI 进行交互。

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/aiplatform.user"

在集群中创建 KSA。请务必先按照配置 kubectl 以与您的集群通信中的说明操作，然后再运行此命令。
```
kubectl create serviceaccount vertex-sa
```

批注 KSA 以将其与您的服务账号相关联：

kubectl annotate serviceaccount vertex-sa \
    iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com

向您的服务账号授予权限，使其能够充当 KSA 的 Workload Identity Federation for GKE 用户：

gcloud iam service-accounts add-iam-policy-binding vertex-sa@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:$PROJECT_ID.svc.id.goog[default/vertex-sa]"

部署和配置智能体应用

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

了解智能体应用结构：/app 目录包含您的智能体应用的核心文件：
- main.py：FastAPI 应用入口点，负责公开智能体的 API。
- agent.py：包含 ADK 智能体的逻辑，用于定义该智能体如何使用 Vertex AI 和处理请求。
- __init__.py：初始化 Python 软件包。
- requirements.txt：列出智能体的所有 Python 依赖项。
- Dockerfile：定义如何将应用打包到 Docker 映像中。

创建智能体部署清单：在 tutorials-and-examples/adk/vertex 目录中，创建以下清单作为名为 agent-deployment.yaml 的文件：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: adk-agent-deployment
  labels:
    app: adk-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 映像的完整网址（例如 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 区域。

应用部署清单：
```
kubectl apply -f agent-deployment.yaml
```
此命令会在 GKE 集群中为智能体应用创建 Deployment 和关联的 Pod。
公开智能体：您可以使用这些方法公开智能体以供访问。
- 如需从集群外部访问智能体，请创建一项 Kubernetes 服务。对于 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
2. 应用清单：
  kubectl apply -f agent-service.yaml
  外部 IP 地址可能需要几分钟才能完成预配。
3. 验证 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。

确定智能体的端点：根据您在上一部分中选择公开智能体的方式，确定智能体的可访问端点：
LoadBalancer
1. 检索外部 IP 地址：
  kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
2. 将外部 IP 地址存储在环境变量中，以便于更轻松地使用：
  export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
  智能体的基础网址为 http://${AGENT_IP}。
port-forward
确保 kubectl port-forward 命令在单独的终端中运行。智能体的基础网址为 http://localhost:8000。
测试智能体的 API：通过向智能体的 /run 端点发出 curl 请求来测试智能体的 API。智能体需要包含消息字段的 JSON 载荷。将 AGENT_BASE_URL 替换为 http://${AGENT_IP}（对于 LoadBalancer）或 http://localhost:8000（对于端口转发）。
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
```
2. 使用上一步中的会话详细信息向智能体发送查询。
```
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 模型互动。响应包含智能体根据您的消息生成的回复。
访问智能体的 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 "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/aiplatform.user"

gcloud iam service-accounts delete vertex-sa@$PROJECT_ID.iam.gserviceaccount.com

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

将 CLUSTER_NAME 替换为 GKE 集群的名称。

Terraform

在 Cloud Shell 终端中，前往 tutorials-and-examples/adk/vertex/ 目录：
```
cd tutorials-and-examples/adk/vertex/
```
运行此命令，移除 Terraform 配置文件中定义的所有资源。
```
cd terraform
terraform destroy
```

后续步骤

了解如何配置 Pod 横向自动扩缩器 (HPA)，以根据需求自动调整智能体的资源。
了解如何为Google Cloud上运行的 Web 应用配置 Identity-Aware Proxy (IAP)，从而提供集中式授权以访问智能体的界面。
了解如何使用 Cloud Logging 和 Cloud Monitoring 深入了解 GKE 集群中智能体的性能和运行状况。
探索 GKE AI 实验室中的实验性示例，这些示例可帮助您使用 GKE 加速智能体 AI 计划。

使用智能体开发套件 (ADK) 和 Vertex AI 在 GKE 上部署智能体 AI 应用 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

背景

Google 智能体开发套件 (ADK)

GKE 托管式 Kubernetes 服务

Vertex AI

Gemini 2.0 Flash

目标

费用

准备工作

Check for the roles

Grant the roles

准备环境

克隆示例项目

创建和配置 Google Cloud 资源

gcloud

Autopilot

Standard

Terraform

配置 kubectl 以与您的集群通信

配置 Workload Identity Federation for GKE 访问权限

部署和配置智能体应用

LoadBalancer

port-forward

测试已部署的智能体

LoadBalancer

port-forward

清理

删除已部署的资源

gcloud

Terraform

后续步骤

使用智能体开发套件 (ADK) 和 Vertex AI 在 GKE 上部署智能体 AI 应用

配置 `kubectl` 以与您的集群通信