Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Autopilot Standard

本教程演示了如何使用 Google Kubernetes Engine (GKE) 部署和管理容器化的智能体 AI/机器学习应用。通过将 Google 智能体开发套件 (ADK) 与自托管的大语言模型 (LLM)（例如由 vLLM 提供的 Llama 3.1）相结合，您可以高效且大规模地将 AI 智能体投入实际应用，同时保持对模型堆栈的完全控制。本教程将指导您完成基于 Python 的代理从开发到在具有 GPU 加速功能的 GKE Autopilot 集群上进行生产部署的端到端流程。

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

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

背景

本部分介绍本教程中使用的关键技术。

智能体开发套件 (ADK)

智能体开发套件 (ADK) 是一个灵活的模块化框架，用于开发和部署 AI 智能体。尽管 ADK 针对 Gemini 和 Google 生态系统进行了优化，但它并不要求您使用特定模型或部署，并且可与其他框架兼容。ADK 旨在让智能体开发更接近于软件开发，以便开发者更轻松地创建、部署和编排从基本任务到复杂工作流的智能体架构。

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

GKE 托管式 Kubernetes 服务

Google Cloud 提供各种各样的服务，包括 GKE，该服务非常适合用于部署和管理 AI/机器学习工作负载。GKE 是一项托管式 Kubernetes 服务，可简化容器化应用的部署、扩缩和管理。GKE 提供必要的基础设施（包括可扩缩资源、分布式计算和高效网络），以满足 LLM 的计算需求。

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

vLLM

vLLM 是一个经过高度优化的开源 LLM 服务框架，可提高 GPU 上的服务吞吐量，具有如下功能：

具有 PagedAttention 且经过优化的 Transformer 实现
连续批处理，可提高整体服务吞吐量。
多个 GPU 上的张量并行处理和分布式服务。

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

目标

本教程介绍了如何执行以下操作：

设置 Google Cloud 环境。
预配启用了 GPU 的 GKE 集群。
使用 vLLM 推理服务器部署 Llama 3.1 模型。
为基于 ADK 的代理构建容器映像。
将代理部署到 GKE 集群，并将其连接到自托管 LLM。
测试已部署的智能体。

架构

本教程介绍了一种可伸缩的架构，用于在 GKE 上部署智能体 AI 应用。ADK 代理应用在标准 CPU 节点池中运行，自托管 LLM（vLLM 上的 Llama 3.1）在支持 GPU 的节点池中运行，两者都在同一 GKE 集群中。此架构将代理的应用逻辑与 LLM 推理工作负载分离，从而允许独立扩缩和管理每个组件。

该架构包含两个核心组件，每个组件都位于各自的 GKE Deployment 中：

ADK 代理应用：代理的自定义构建业务逻辑和工具（例如 get_weather）位于容器映像中。该映像在标准 CPU 节点池池上运行，并使用内部 Kubernetes 服务与 LLM 通信。
自托管 LLM（基于 vLLM 的 Llama 3.1）：Llama 3.1 模型在支持 GPU 的节点池中的专用 vLLM 服务器上运行。此部署使用一个公共容器映像 (vllm/vllm-openai:v0.8.5)，该映像配置为在容器启动时从 Hugging Face 下载并提供指定的模型。代理通过 vllm-llama3-service Kubernetes 服务公开的 REST API 与此服务器通信。

ADK 代理和 vLLM 部署都在同一 GKE 集群上运行。这种在单个集群内的同位简化了网络、管理和部署，同时仍允许为应用组件分配专用硬件。

费用

本教程使用 Google Cloud的以下收费组件：

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

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

确保您在项目中拥有以下一个或多个角色： roles/container.admin、roles/iam.serviceAccountAdmin、roles/artifactregistry.admin、roles/cloudbuild.builds.editor、roles/resourcemanager.projectIamAdmin
检查角色
1. 在 Google Cloud 控制台中，前往 IAM 页面。
  转到 IAM
2. 选择项目。
3. 在主账号列中，找到标识您或您所属群组的所有行。如需了解您属于哪些群组，请与您的管理员联系。
4. 对于指定或包含您的所有行，请检查角色列以查看角色列表是否包含所需的角色。
授予角色
1. 在 Google Cloud 控制台中，前往 IAM 页面。
  转到 IAM
2. 选择项目。
3. 点击 授予访问权限。
4. 在新的主账号字段中，输入您的用户标识符。这通常是 Google 账号的电子邮件地址。
5. 点击选择角色，然后搜索相应角色。
6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
7. 点击 Save（保存）。
从 Hugging Face 获取读取访问权限令牌，以便下载 Llama 模型。您还需要申请对 Llama 3.1 模型的访问权限。

准备环境

本教程使用 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_REGION=REGION
export PROJECT_ID=PROJECT_ID
```
替换以下值：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- REGION：用于预配 GKE 集群、Artifact Registry 和其他区域级资源的 Google Cloud 区域（例如 us-east4）。请务必指定支持 L4 GPU 和 G2 机器类型实例的区域。如需查看区域可用性，请参阅 Compute Engine 文档中的 GPU 区域和可用区。

克隆示例项目

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

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

转到教程目录：

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

创建和配置 Google Cloud 资源

如需部署代理，您首先需要预配必要的 Google Cloud资源。您可以使用 gcloud CLI 或 Terraform 创建 GKE 集群和 Artifact Registry 代码库。

gcloud

本部分提供了一些 gcloud CLI 命令，用于设置 GKE 集群和 Artifact Registry。

创建 GKE 集群：您可以在 GKE Autopilot 或 Standard 集群中部署容器化智能体应用。使用 Autopilot 集群可获得全托管式 Kubernetes 体验。如需选择最适合您的工作负载的 GKE 操作模式，请参阅 GKE 操作模式简介。
Autopilot
在 Cloud Shell 中，运行以下命令：
gcloud container clusters create-auto CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION
将 CLUSTER_NAME 替换为 GKE 集群的名称。

在 Autopilot 模式下，GKE 会根据工作负载的资源请求自动预配节点。通过使用 nodeSelector 在 deploy-llm.yaml 清单中请求 LLM 所需的 GPU。

如需添加请求 nvidia-l4 GPU 的 nodeSelector，请按以下步骤操作：
1. 在编辑器中打开 kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml。
2. 在 spec.template.spec 下添加以下 nodeSelector：
  
  nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
Standard
1. 在 Cloud Shell 中，运行以下命令以创建 Standard 集群：
  
  gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION
  
  将 CLUSTER_NAME 替换为 GKE 集群的名称。
2. 运行以下命令，为集群创建启用 GPU 的节点池：
  
  gcloud container node-pools create gpu-node-pool \ --cluster=CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION \ --machine-type=g2-standard-8 \ --accelerator=type=nvidia-l4,count=1 \ --enable-gvnic
  
  deploy-llm.yaml 文件指定了 G2 机器系列中可用的 nvidia-l4 GPU。如需详细了解此机器类型，请参阅 Compute Engine 文档中的 GPU 机器类型。
创建 Artifact Registry 代码库：创建 Artifact Registry 代码库，以安全地存储和管理智能体的 Docker 容器映像。
```
gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION
```
将 REPO_NAME 替换为要使用的 Artifact Registry 代码库的名称（例如 adk-repo）。
获取代码库网址：如需验证代码库的完整路径，请运行此命令。您将在构建代理映像时使用此格式来标记 Docker 映像。
```
gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION
```

Terraform

本部分介绍如何使用示例代码库中包含的 Terraform 配置自动预配 Google Cloud 资源。

前往 Terraform 目录：\terraform 目录包含创建 GKE 集群和其他必需资源的所有必要配置文件。
```
cd terraform
```
创建 Terraform 变量文件：复制提供的示例变量文件 (example_vars.tfvars)，以创建您自己的 vars.tfvars 文件。
```
cp example_vars.tfvars vars.tfvars
```
在编辑器中打开 vars.tfvars 文件，并将占位值替换为您的具体配置。您至少必须将 PROJECT_ID 替换为您的 Google Cloud 项目 ID，并将 CLUSTER_NAME 替换为您的 GKE 集群的名称。
初始化 Terraform：如需下载 Google Cloud所需的提供方插件，请运行此命令。
```
terraform init
```
查看执行计划：此命令会显示 Terraform 将进行的基础设施更改。
```
terraform plan -var-file=vars.tfvars
```
应用配置：执行 Terraform 计划，以在 Google Cloud 项目中创建资源。在系统提示时，使用 yes 表示确认。
```
terraform apply -var-file=vars.tfvars
```

运行这些命令后，Terraform 会预配您的 GKE 集群和 Artifact Registry 代码库，并配置必要的 IAM 角色和服务账号，包括 Workload Identity Federation for GKE。

如需详细了解如何使用 Terraform，请参阅使用 Terraform 预配 GKE 资源。

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

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

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

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

构建代理映像

使用 gcloud CLI 或 Terraform 创建基础架构后，请按照以下步骤构建代理应用。

为 Cloud Build 授予所需的 IAM 角色：Cloud Build 服务需要权限才能将代理的容器映像推送到 Artifact Registry。向 Cloud Build 使用的 Compute Engine 默认服务账号授予 roles/artifactregistry.writer 角色。
1. 为 Compute Engine 默认服务账号构建邮箱：
```
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
```
2. 将 roles/artifactregistry.writer 角色授予服务账号：
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer
```
构建并推送智能体容器映像：从项目根目录 (adk/llama/vllm) 中运行以下命令，以构建 Docker 映像并将其推送到 Artifact Registry。
```
export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL
```
验证映像是否已推送：构建流程成功完成后，通过列出代码库中的映像来验证代理的容器映像是否已推送到 Artifact Registry。
```
gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
```
您应该会看到一个输出，其中列出了您刚刚推送并标记为 latest 的映像。

部署模型

设置 GKE 集群并构建代理映像后，下一步是将自托管的 Llama 3.1 模型部署到集群。为此，请部署一个预配置的 vLLM 推理服务器，该服务器会从 Hugging Face 拉取模型并在集群内部提供该模型。

为 Hugging Face 凭证创建 Kubernetes Secret：如需允许 GKE 集群下载受限的 Llama 3.1 模型，您必须以 Kubernetes Secret 的形式提供 Hugging Face 令牌。deploy-llm.yaml 清单配置为使用此密钥进行身份验证。
```
kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN
```
将 HUGGING_FACE_TOKEN 替换为您的令牌。
查看清单：从项目根目录 (adk/llama/vllm) 前往包含模型Deployment清单的 /deploy-llm 目录。
```
cd deploy-llm
```
应用清单：运行以下命令，将 deploy-llm.yaml 清单应用到您的集群。
```
kubectl apply -f deploy-llm.yaml
```
该命令会创建以下三个 Kubernetes 资源：
- 运行 vLLM 服务器的 Deployment，配置为使用 meta-llama/Llama-3.1-8B-Instruct 模型。
- 名为 vllm-llama3-service 的Service，用于在内部集群 IP 地址上公开 vLLM 服务器，以便 ADK 代理与其通信。
- 包含 Llama 3.1 模型所需的 Jinja 对话模板的 ConfigMap。
验证模型Deployment：vLLM 服务器从 Hugging Face 拉取模型文件。此过程可能需要几分钟时间。您可以监控 Pod 的状态，以确保其已准备就绪。
1. 等待Deployment变为可用状态。
```
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
```
2. 查看正在运行的 Pod 的日志，确认服务器已成功启动。
```
export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD
```
  当您看到类似于以下内容的日志输出时，表示部署已准备就绪，这表明 LLM 服务器已启动，并且 API 路由可用：
```
INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```
3. 直接向模型服务器发送请求，以确认 LLM 是否已准备就绪。为此，请打开新的 Cloud Shell 终端，然后运行以下命令将 vllm-llama3-service 转发到本地机器：
```
kubectl port-forward service/vllm-llama3-service 8000:8000
```
4. 在另一个终端中，使用 curl 向模型的 API 端点发送示例请求。例如：
```
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Hello!",
    "max_tokens": 10
  }'
```
  如果该命令返回成功的 JSON 响应，则表示 LLM 已准备就绪。现在，您可以返回端口转发进程的终端窗口并按 Ctrl+C 来终止该进程，然后继续部署代理。

部署代理应用

下一步是部署基于 ADK 的代理应用。

前往 /deploy-agent 目录：从项目根目录 (adk/llama/vllm) 前往包含智能体源代码和部署清单的 /deploy-agent 目录。
```
cd ../deploy-agent
```
更新代理部署清单：
1. 示例 deploy-agent.yaml 清单文件在容器映像网址中包含项目 ID 的占位符。您必须将占位符替换为您的 Google Cloud 项目 ID。
```
image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
```
  如需就地执行此替换，您可以运行以下命令：
```
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
```
2. 确保 readinessProbe 路径设置为 / 而不是 /dev-ui。如需就地执行此替换，您可以运行以下命令：
```
sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
```
应用清单：运行以下命令，将 deploy-agent.yaml 清单应用到您的集群。
```
kubectl apply -f deploy-agent.yaml
```
此命令会创建两个 Kubernetes 资源：
- 名为 adk-agent 的 Deployment，用于运行您自定义构建的代理容器映像。
- 名为 adk-agent 的 NodePort 类型的Service，用于公开代理应用，以便进行测试。

验证代理部署：检查 Pod 的状态，确保其正常运行。

等待Deployment变为可用状态：

kubectl wait --for=condition=available --timeout=300s deployment/adk-agent

查看正在运行的代理 Pod 中的日志：

export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD

当您看到类似于以下内容的日志输出时，表示部署成功，这表明 Uvicorn 服务器正在运行并已准备好接受请求：

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

测试已部署的智能体

成功部署 vLLM 服务器和代理应用后，您可以通过与代理的网页界面互动来测试端到端功能。

将代理的服务转发到本地机器：adk-agent 服务属于 NodePort 类型，但从 Cloud Shell 环境访问该服务的最直接方式是使用 kubectl port-forward 命令。运行以下命令，为代理的 Pod 创建安全隧道。
```
kubectl port-forward $AGENT_POD 8001:8001
```
访问代理的网页界面：在 Cloud Shell 中，点击网页预览按钮，然后选择在端口 8001 上预览。系统会打开一个新的浏览器标签页，其中显示代理的聊天界面。
与代理互动：向代理提出一个会调用其 get_weather 工具的问题。例如：
```
What's the weather like in Tokyo?
```
代理会先调用 LLM 来了解意图，并确定是否需要使用 get_weather 工具。然后，它将执行该工具，并将“东京”作为参数。最后，它将使用工具的输出生成回答。您应该会看到如下所示的响应：
```
  The weather in Tokyo is 25°C and sunny.
```
（可选）验证日志中的工具调用：您可以查看相应 Pod 的日志，了解代理与 LLM 的互动以及工具执行情况。
1. 代理 Pod 日志：在新终端中，查看 adk-agent Pod 的日志。您会看到工具调用及其结果。
```
kubectl logs -f $AGENT_POD
```
  输出显示了工具的调用和结果的处理。
2. LLM Pod 日志：查看 vllm-llama3-deployment Pod 的日志，了解来自代理的传入请求。
```
kubectl logs -f $LLM_POD
```
  日志显示了代理发送给 LLM 的完整提示，包括系统消息、您的查询和 get_weather 工具的定义。

测试完成后，您可以返回到 port-forward 进程的终端窗口，然后按 Ctrl+C 来终止该进程。

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除已部署的资源

为避免因您在本教程中创建的资源导致您的 Google Cloud 账号产生费用，请运行以下命令：

gcloud

如果您使用 gcloud CLI 创建了资源，请运行以下命令来删除 GKE 集群和 Artifact Registry 代码库，并将服务账号的权限恢复到原始状态。

gcloud container clusters delete CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION

gcloud artifacts repositories delete REPO_NAME \
    --location=$GOOGLE_CLOUD_REGION

gcloud projects remove-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer

Terraform

如果您使用 Terraform 来预配基础设施，则只需在 /terraform 目录中运行一个命令，即可销毁所有资源。

从项目根目录 (adk/llama/vllm) 前往 /terraform 目录：
```
cd terraform
```
运行此命令，移除 Terraform 配置文件中定义的所有资源：
```
terraform destroy
```

后续步骤

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

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

背景

智能体开发套件 (ADK)

GKE 托管式 Kubernetes 服务

vLLM

目标

架构

费用

准备工作

检查角色

授予角色

准备环境

克隆示例项目

创建和配置 Google Cloud 资源

gcloud

Autopilot

Standard

Terraform

配置 kubectl 以与您的集群通信

构建代理映像

部署模型

部署代理应用

测试已部署的智能体

清理

删除已部署的资源

gcloud

Terraform

后续步骤

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

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