Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

Autopilot Standard

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

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

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

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

准备工作

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

确保您在项目中拥有以下一个或多个角色： roles/artifactregistry.admin、roles/browser、roles/compute.networkAdmin、 roles/container.clusterAdmin、roles/iam.roleAdmin、roles/iam.serviceAccountAdmin、 roles/resourcemanager.projectIamAdmin、roles/serviceusage.serviceUsageAdmin 和 roles/secretmanager.secretVersionManager
检查角色
1. 在 Google Cloud 控制台中，前往 IAM 页面。
  转到 IAM
2. 选择项目。
3. 在主账号 列中，找到标识您或您所属群组的所有行。如需了解您所属的群组，请与您的管理员联系。
4. 对于指定或包含您的所有行，请检查角色列以查看角色列表是否包含所需的角色。
授予角色
1. 在 Google Cloud 控制台中，前往 IAM 页面。
  转到 IAM
2. 选择项目。
3. 点击 授予访问权限。
4. 在新的主账号 字段中，输入您的用户标识符。这通常是员工身份池中的用户的标识符。如需了解详情，请参阅在 IAM 政策中表示员工池用户，或与您的管理员联系。
5. 点击选择角色，然后搜索相应角色。
6. 如需授予其他角色，请点击 添加其他角色 ，然后添加其他各个角色。
7. 点击 Save （保存）。

创建 Hugging Face 账号。
确保您的项目具有足够的 GPU 配额。如需了解更多信息，请参阅分配配额。

获取对模型的访问权限

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

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

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

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

预配 GKE 推理环境

在本部分中，您将部署必要的基础设施来部署模型。

启动 Cloud Shell

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

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

打开 Cloud Shell

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

部署基础架构

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

在 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)"

设置环境变量：
```
export TF_VAR_platform_default_project_id=PROJECT_ID
export HF_TOKEN_READ=HF_TOKEN
```
替换以下值：
- PROJECT_ID：您的 Google Cloud项目 ID。
- HF_TOKEN：您之前生成的 Hugging Face 令牌。
本指南需要使用 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}
```
运行以下部署脚本。部署脚本会启用必需的 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 集群。

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

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

部署脚本会在 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}
```

部署开放模型

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

选择型号

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

Gemma 4 26B-A4B-it

# Default: H100
export ACCELERATOR_TYPE="h100"
export HF_MODEL_ID="google/gemma-4-26b-a4b-it"

# Alternative: RTX Pro 6000
# export ACCELERATOR_TYPE="rtx-pro-6000"
# export HF_MODEL_ID="google/gemma-4-26b-a4b-it"

Gemma 4 31B-it

# Default: H100
export ACCELERATOR_TYPE="h100"
export HF_MODEL_ID="google/gemma-4-31b-it"

# Alternative: RTX Pro 6000
# export ACCELERATOR_TYPE="rtx-pro-6000"
# export HF_MODEL_ID="google/gemma-4-31b-it"

Gemma 4 E2B-it

export ACCELERATOR_TYPE="l4"
export HF_MODEL_ID="google/gemma-4-e2b-it"

Gemma 4 E4B-it

export ACCELERATOR_TYPE="l4"
export HF_MODEL_ID="google/gemma-4-e4b-it"

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

下载模型

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

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

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

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

应用 Hugging Face 模型下载资源：

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

监控 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

验证 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'

删除 Hugging Face 模型下载资源。

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

部署模型

加载部署中的环境变量。

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

验证是否已设置 Hugging Face 模型名称。
```
echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
```

配置 vLLM 资源。

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

将推理工作负载部署到您的 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}"

测试部署

监控推理工作负载部署，直到其可用。

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

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

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

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

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 响应，其中回答了该问题。

清理

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

删除推理工作负载：

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}"

清理资源：

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 推理快速入门工具分析模型推理性能和费用。
探索用于构建此架构的 accelerated-platforms GitHub 代码库。

通过预配置的架构在 GKE 上提供开放 LLM 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

检查角色

授予角色

获取对模型的访问权限

预配 GKE 推理环境

启动 Cloud Shell

部署基础架构

Autopilot

标准

部署开放模型

选择型号

Gemma 4 26B-A4B-it

Gemma 4 31B-it

Gemma 4 E2B-it

Gemma 4 E4B-it

Gemma 3 27B-it

Llama 4 Scout 17B-16E-Instruct

Qwen3 32B

gpt-oss 20B

下载模型

部署模型

测试部署

清理

Autopilot

标准

后续步骤

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