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

目标

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

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

架构

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

图 1：一种可在 GKE 上部署代理式 AI 的可伸缩架构。

该架构有两个核心组件，每个组件都位于自己的 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的以下收费组件：

• GKE
• Artifact Registry
• Cloud Build

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

准备工作

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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

• 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. 点击 Save（保存）。
  8. 从 Hugging Face 获取读取访问令牌，以便下载 Llama 模型。您还需要申请访问 Llama 3.1 模型。

  准备环境

  本教程使用 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
        

     标准

     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) 导航到包含模型部署清单的 /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 的服务，用于在内部集群 IP 地址上公开 vLLM 服务器，以便 ADK 代理与其通信。
     • 包含 Llama 3.1 模型所需的 Jinja 对话模板的 ConfigMap。

  4. 验证模型部署：vLLM 服务器从 Hugging Face 拉取模型文件。此过程可能需要几分钟时间。您可以监控 Pod 的状态，确保其已准备就绪。

     1. 等待部署变为可用状态。

        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 类型的服务，用于公开代理应用，以便进行测试。

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

     1. 等待部署变为可用状态：

        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 服务器和代理应用后，您可以通过与代理的 Web 界面互动来测试端到端功能。

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

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

     kubectl port-forward $AGENT_POD 8001:8001
     

  2. 访问代理的 Web 界面：在 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 来终止该进程。

  清理

  为避免因本教程中使用的资源导致您的 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 目录中运行一个命令，即可销毁所有资源。

  1. 从项目根目录 (adk/llama/vllm) 导航到 /terraform 目录：

     cd terraform
     

  2. 运行此命令，移除 Terraform 配置文件中定义的所有资源：

     terraform destroy
     

  后续步骤

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