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

Autopilot Standard

---

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

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

• 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 用户角色和任务。

准备工作

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.

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.

Enable the APIs

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

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.

Enable the APIs

• Make sure that you have the following role or roles on the project: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, and roles/serviceusage.serviceUsageAdmin

  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（保存）。
  • 创建 Hugging Face 账号。
  • 确保您的项目具有足够的 GPU 配额。如需了解详情，请参阅分配配额。

  获取对模型的访问权限

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

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

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

  1. 依次点击您的个人资料 > 设置 > 访问令牌。
  2. 选择新建令牌 (New Token)。
  3. 指定您选择的名称和一个至少为读取的角色。
  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 Inference Quickstart 工具分析模型推理性能和费用。
  • 探索 GitHub 上基于此架构构建的其他使用情形和模式。