通过预配置的架构在 GKE 上提供开放 LLM

本页面介绍如何使用预配置的、可用于生产环境的参考架构，在 GKE 上快速部署和提供热门的开放大语言模型 (LLM)，以进行推理。此方法使用基础设施即代码 (IaC)，通过封装在 CLI 脚本中的 Terraform 来创建标准化、安全且可伸缩的 GKE 环境，该环境专为 AI 推理工作负载而设计。

在本指南中，您将使用 vLLM 服务框架，在 GKE 上使用单主机 GPU 节点来部署和提供 LLM。本指南提供了有关部署以下开放模型的说明和配置：

• Google Gemma 3 27B-it
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• OpenAI gpt-oss-20b

本指南适用于机器学习 (ML) 工程师以及对探索 Kubernetes 容器编排功能以部署开放模型进行推理感兴趣的数据和 AI 专家。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE 用户角色和任务。

如需详细分析这些开放模型的模型服务性能和费用，您还可以使用 GKE 推理快速入门工具。如需了解详情，请参阅 GKE 推理快速入门指南和随附的 Colab 笔记本。

获取对模型的访问权限

注意： 您必须在相应 Hugging Face 模型页面上接受您要使用的任何受限模型（例如 Gemma 或 Llama）的许可条款。

如需通过 Hugging Face 访问模型，您需要 Hugging Face 令牌。

如果您还没有令牌，请按照以下步骤生成新令牌：

1. 点击您的个人资料 > 设置 > 访问令牌。
2. 选择新建令牌 (New Token)。
3. 指定您选择的名称和一个至少为 Read 的角色。
4. 选择生成令牌。
5. 将生成的令牌复制到剪贴板。

预配 GKE 推理环境

在本部分中，您将部署提供模型所需的必要基础架构。

启动 Cloud Shell

本指南使用 Cloud Shell 执行命令。Cloud Shell 预安装了必要的工具，包括 gcloud、kubectl 和 git。

在 Google Cloud 控制台中，启动 Cloud Shell 实例：

打开 Cloud Shell

此操作会在 Google Cloud 控制台的底部窗格中启动会话。

部署基础架构

如需预配 GKE 集群和访问 Hugging Face 模型所需的资源，请按以下步骤操作：

1. 在 Cloud Shell 中，克隆以下 Git 代码库：

   git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \
   cd accelerated-platforms && \
   export ACP_REPO_DIR="$(pwd)"
   

2. 设置环境变量：

   export TF_VAR_platform_default_project_id=PROJECT_ID
   export HF_TOKEN_READ=HF_TOKEN
   

   替换以下值：

   • PROJECT_ID：您的 Google Cloud项目 ID。
   • HF_TOKEN：您之前生成的 Hugging Face 令牌。

3. 本指南需要使用 Terraform 1.8.0 版或更高版本。Cloud Shell 默认安装了 Terraform v1.5.7。

   如需更新 Cloud Shell 中的 Terraform 版本，您可以运行以下脚本。此脚本会安装 terraform-switcher 工具并更改您的 shell 环境。

   "${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
   source ~/.bashrc
   

4. 运行以下部署脚本。部署脚本会启用必需的 Google Cloud API，并为此指南预配必要的基础设施。这包括新的 VPC 网络、具有专用节点的 GKE 集群和其他支持资源。该脚本可能需要几分钟才能完成。

   您可以在 GKE Autopilot 或 Standard 集群中使用 GPU 部署模型。Autopilot 集群可提供全代管式 Kubernetes 体验。 如需详细了解如何选择最适合您的工作负载的 GKE 操作模式，请参阅GKE 操作模式简介。

   Autopilot

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-ap.sh"
   

   标准

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-standard.sh"
   

   此脚本完成后，您将获得一个可用于推理工作负载的 GKE 集群。

5. 运行以下命令，从共享配置中设置环境变量：

   source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
   

6. 部署脚本会在 Secret Manager 中创建一个 Secret 来存储您的 Hugging Face 令牌。您必须先手动将令牌添加到此 Secret，然后再部署集群。在 Cloud Shell 中，运行以下命令将令牌添加到 Secret Manager。

   echo ${HF_TOKEN_READ} | gcloud secrets versions add ${huggingface_hub_access_token_read_secret_manager_secret_name} \
       --data-file=- \
       --project=${huggingface_secret_manager_project_id}
   

部署开放模型

现在，您可以下载并部署模型了。

1. 为要部署的模型设置环境变量：

   Gemma 3 27B-it

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="google/gemma-3-27b-it"
   

   Llama 4 Scout 17B-16E-Instruct

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="meta-llama/llama-4-scout-17b-16e-instruct"
   

   Qwen3 32B

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="qwen/qwen3-32b"
   

   gpt-oss 20B

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="openai/gpt-oss-20b"
   

   如需了解其他配置（包括其他模型变体和 GPU 类型），请参阅 accelerated-platforms GitHub 代码库中提供的清单。

2. 从部署中获取环境变量。这些环境变量包含您预配的基础设施的必要配置详细信息。

   source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
   

3. 运行以下脚本以配置将模型下载到 Cloud Storage 的 Kubernetes 作业：

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"
   

4. 部署模型下载作业：

   kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"
   

5. 等待下载完成。监控作业的状态，当 COMPLETIONS 为 1/1 时，按 Ctrl+C 退出。

   watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs
   

6. 将推理工作负载部署到 GKE 集群。

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/configure_deployment.sh"
   
   kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

测试部署

1. 等待推理服务器 Pod 准备就绪。当 READY 列为 1/1 时，按 Ctrl+C 退出。

   watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

2. 运行以下脚本以设置端口转发并向模型发送示例请求。此示例使用 Gemma 3 27b-it 模型的载荷格式。

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
   PF_PID=$!
   curl http://127.0.0.1:8000/v1/chat/completions \
     --data '{
       "model": "/gcs/'${HF_MODEL_ID}'",
       "messages": [ { "role": "user", "content": "What is GKE?" } ]
     }' \
     --header "Content-Type: application/json" \
     --request POST \
     --show-error \
     --silent | jq
   kill -9 ${PF_PID}
   

   您应该会看到模型针对问题给出的 JSON 回答。

清理

为避免产生费用，请删除您创建的所有资源。

1. 删除推理工作负载：

   kubectl delete --ignore-not-found --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

2. 移除基础 GKE 集群：

   Autopilot

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-ap.sh"
   

   标准

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-standard.sh"
   

后续步骤

• 详细了解 GKE 上的 AI/机器学习模型推理。
• 使用 GKE 推理快速入门工具分析模型推理性能和费用。
• 探索 GitHub 上基于此架构构建的其他使用情形和模式。