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

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

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

注意 ：本教程中的方法需要预配具有 GPU 硬件的 GKE 集群来运行 LLM，这与 Vertex AI 方法不同，后者由 Google 的托管式基础设施处理模型推理。如需详细了解 Vertex AI 方法，请参阅使用 ADK 和 Vertex AI 在 GKE 上部署智能体 AI 应用。

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

• GKE
• 使用 Docker 进行容器化

背景

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

智能体开发套件 (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 文档。

准备环境

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

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

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

2. 设置默认环境变量：

   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 区域和可用区。

克隆示例项目

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

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

2. 转到教程目录：

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

创建和配置 Google Cloud 资源

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

gcloud

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

1. 创建 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 文件指定了 nvidia-l4 GPU，该 GPU 可在 G2 机器系列中使用。如需详细了解此机器类型，请参阅 Compute Engine 文档中的 GPU 机器类型。

2. 创建 Artifact Registry 代码库：创建 Artifact Registry 代码库，以安全地存储和管理智能体的 Docker 容器映像。

   gcloud artifacts repositories create REPO_NAME \
       --repository-format=docker \
       --location=$GOOGLE_CLOUD_REGION
   

   将 REPO_NAME 替换为要使用的 Artifact Registry 代码库的名称（例如 adk-repo）。

3. 获取代码库网址：如需验证代码库的完整路径，请运行此命令。您将在构建代理映像时使用此格式来标记 Docker 映像。

   gcloud artifacts repositories describe REPO_NAME \
       --location $GOOGLE_CLOUD_REGION
   

Terraform

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

1. 前往 Terraform 目录：\terraform 目录包含创建 GKE 集群和其他必需资源的所有必要配置文件。

   cd terraform
   

2. 创建 Terraform 变量文件：复制提供的示例变量文件 (example_vars.tfvars)，以创建您自己的 vars.tfvars 文件。

   cp example_vars.tfvars vars.tfvars
   

   在编辑器中打开 vars.tfvars 文件，并将占位值替换为您的具体配置。您至少必须将 PROJECT_ID 替换为您的 Google Cloud 项目 ID，并将 CLUSTER_NAME 替换为您的 GKE 集群的名称。

3. 初始化 Terraform：如需下载 Google Cloud所需的提供程序插件，请运行此命令。

   terraform init
   

4. 查看执行计划：此命令会显示 Terraform 将进行的基础设施更改。

   terraform plan -var-file=vars.tfvars
   

5. 应用配置：执行 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 创建基础架构后，请按照以下步骤构建代理应用。

1. 为 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}[e-mail]
      

   2. 将 roles/artifactregistry.writer 角色授予服务账号：

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

2. 构建并推送智能体容器映像：从项目根目录 (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
   

3. 验证映像是否已推送：构建流程成功完成后，通过列出代码库中的映像来验证代理的容器映像是否已推送到 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 拉取模型并在集群内部提供该模型。

1. 为 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 替换为您的令牌。

2. 查看清单：从项目根目录 (adk/llama/vllm) 前往包含模型Deployment清单的 /deploy-llm 目录。

   cd deploy-llm
   

3. 应用清单：运行以下命令，将 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。

4. 验证模型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 的代理应用。

1. 前往 /deploy-agent 目录：从项目根目录 (adk/llama/vllm) 前往包含智能体源代码和部署清单的 /deploy-agent 目录。

   cd ../deploy-agent
   

2. 更新代理部署清单：

   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
      

3. 应用清单：运行以下命令，将 deploy-agent.yaml 清单应用到集群。

   kubectl apply -f deploy-agent.yaml
   

   此命令会创建两个 Kubernetes 资源：

   • 名为 adk-agent 的 Deployment，用于运行您自定义构建的代理容器映像。
   • 名为 adk-agent 的 NodePort 类型的Service，用于公开代理应用，以便进行测试。

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

   1. 等待Deployment变为可用状态：

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

   2. 查看正在运行的代理 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 服务器和代理应用后，您可以通过与代理的网页界面互动来测试端到端功能。

注意： 本教程使用 LLM 根据您的提示确定要调用的工具，但该工具本身使用硬编码的模拟数据（而不是实时 API）以简化操作。代理的 get_weather 工具从预定义的字典中检索“巴黎”“渥太华”和“东京”的天气信息，而不是从实时外部服务中检索。

1. 将代理的服务转发到本地机器：adk-agent 服务属于 NodePort 类型，但从 Cloud Shell 环境访问该服务的最直接方式是使用 kubectl port-forward 命令。运行以下命令，创建通往代理 Pod 的安全隧道。

   kubectl port-forward $AGENT_POD 8001:8001
   

2. 访问代理的网页界面：在 Cloud Shell 中，点击网页预览按钮，然后选择在端口 8001 上预览。系统会打开一个新的浏览器标签页，其中显示代理的聊天界面。

3. 与代理互动：向代理提出一个会调用其 get_weather 工具的问题。例如：

   What's the weather like in Tokyo?
   

   代理会先调用 LLM 来了解意图，并确定是否需要使用 get_weather 工具。然后，它将执行该工具，并将“东京”作为参数。最后，它将使用工具的输出生成回答。您应该会看到如下所示的响应：

     The weather in Tokyo is 25°C and sunny.
   

4. （可选）验证日志中的工具调用：您可以查看相应 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 来终止该进程。