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

Autopilot Standard

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

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

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

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

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

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

准备工作

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 role (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 role (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/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 配额。如需了解详情，请参阅分配配额。

  获取对模型的访问权限

  对于您想要使用的任何门控模型（例如 Gemma 或 Llama），在相应的 Hugging Face 模型页面上接受其许可条款。

  如需通过 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-vllm-gpu-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 版本，您可以运行以下脚本。此脚本会安装 tfswitch 工具，并在您的主目录中安装 Terraform v1.8.0。按照脚本中的说明设置必要的环境变量，或将 --modify-rc-file 标志传递给脚本。

     "${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
     export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
     

  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"
     

     Standard

     "${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 代码库中提供的清单。

  下载模型

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

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

  2. 运行以下脚本以配置 Hugging Face 模型下载资源，该资源会将模型下载到 Cloud Storage：

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

  3. 应用 Hugging Face 模型下载资源：

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

  4. 监控 Hugging Face 模型下载作业，直至其完成。

     until kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} wait job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --for=condition=complete --timeout=10s >/dev/null; do
         clear
         kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
         echo -e "\nhf-model-to-gcs logs(last 10 lines):"
         kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} logs job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --container=hf-model-to-gcs --tail 10
     done
     

  5. 验证 Hugging Face 模型下载作业是否已完成。

     kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
     

  6. 删除 Hugging Face 模型下载资源。

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

  部署模型

  1. 加载部署中的环境变量。

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

  2. 验证是否已设置 Hugging Face 模型名称。

     echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
     

  3. 配置 vLLM 资源。

     "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/configure_vllm.sh"
     

  4. 将推理工作负载部署到您的 GKE 集群。

     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. 监控推理工作负载部署，直到其可用。

     until kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
         clear
         kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
         echo -e "\nfetch-safetensors logs(last 10 lines):"
         kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
         echo -e "\ninference-server logs(last 10 lines):"
         kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
     done
     

  1. 验证推理工作负载部署是否可用。

     kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
     echo -e "\nfetch-safetensors logs(last 10 lines):"
     kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
     echo -e "\ninference-server logs(last 10 lines):"
     kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
     

  2. 运行以下脚本以设置端口转发并向模型发送示例请求。

     kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
     PF_PID=$!
     while ! echo -e '\x1dclose\x0d' | telnet localhost 8000 >/dev/null 2>&1; do
         sleep 0.1
     done
     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. 清理资源：

     Autopilot

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

     Standard

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

  后续步骤

  • 详细了解 GKE 上的 AI/机器学习模型推理。
  • 使用 GKE 推理快速入门工具分析模型推理性能和费用。
  • 探索用于构建此架构的 accelerated-platforms GitHub 代码库。