本教程介绍如何将 Google Kubernetes Engine (GKE) 上的 GPU 和 vLLM 服务框架搭配使用来部署和提供 Gemma 3 大语言模型 (LLM)。本教程为理解和探索在托管式 Kubernetes 环境中部署实际 LLM 以进行推理提供了基础。您会将运行 vLLM 的预构建容器部署到 GKE。您还将配置 GKE，以便从 Hugging Face 加载 Gemma 1B、4B、12B 和 27B 权重。
本教程适用于机器学习 (ML) 工程师、平台管理员和运维人员，以及希望使用 Kubernetes 容器编排功能在 H200、H100、A100 和 L4 GPU 硬件上处理 AI/机器学习工作负载的数据和 AI 专家。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE 用户角色和任务。
如果您需要统一的托管式 AI 平台，旨在经济高效地快速构建和部署机器学习模型，我们建议您试用我们的 Vertex AI 部署解决方案。
在阅读本页面之前，请确保您熟悉以下内容：
背景
本部分介绍本指南中使用的关键技术。
Gemma
Gemma 是一组公开提供的轻量级生成式人工智能 (AI) 多模态模型（根据开放许可发布）。这些 AI 模型可以在应用、硬件、移动设备或托管服务中运行。Gemma 3 引入了多模态功能，支持视觉语言输入和文本输出。它可处理最多 128,000 个 token 的上下文窗口，并支持 140 多种语言。Gemma 3 还提供改进的数学、推理和聊天功能，包括结构化输出和函数调用。
您可以使用 Gemma 模型生成文本，也可以针对专门任务对这些模型进行调优。
如需了解详情，请参阅 Gemma 文档。
GPU
利用 GPU，您可以加速在节点上运行的特定工作负载（例如机器学习和数据处理）。GKE 提供了一系列机器类型选项以用于节点配置，包括配备 NVIDIA H200、H100、L4 和 A100 GPU 的机器类型。
vLLM
vLLM 是一个经过高度优化的开源 LLM 服务框架，可提高 GPU 上的服务吞吐量，具有如下功能：
- 具有 PagedAttention 且经过优化的 Transformer（转换器）实现
- 连续批处理，可提高整体服务吞吐量
- 多个 GPU 上的张量并行处理和分布式服务
如需了解详情，请参阅 vLLM 文档。
获取对模型的访问权限
如需通过 Hugging Face 访问模型，您需要 Hugging Face 令牌。
如果您还没有令牌，请按照以下步骤生成新令牌：
- 点击您的个人资料 > 设置 > 访问令牌。
- 选择新建令牌 (New Token)。
- 指定您选择的名称和一个至少为
Read的角色。 - 选择生成令牌。
- 将生成的令牌复制到剪贴板。
准备环境
在本教程中，您将使用 Cloud Shell 来管理Google Cloud上托管的资源。Cloud Shell 中预安装了本教程所需的软件，包括 kubectl 和 gcloud CLI。
如需使用 Cloud Shell 设置您的环境，请按照以下步骤操作：
在 Google Cloud 控制台中，点击 Google Cloud 控制台中的
激活 Cloud Shell 以启动 Cloud Shell 会话。此操作会在 Google Cloud 控制台的底部窗格中启动会话。设置默认环境变量：
gcloud config set project PROJECT_ID gcloud config set billing/quota_project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAME export HF_TOKEN=HF_TOKEN替换以下值：
PROJECT_ID：您的 Google Cloud项目 ID。REGION：支持要使用的加速器类型的区域，例如适用于 L4 GPU 的us-central1。CLUSTER_NAME：您的集群的名称。HF_TOKEN：您之前生成的 Hugging Face 令牌。
创建和配置 Google Cloud 资源
请按照以下说明创建所需的资源。
创建 GKE 集群和节点池
您可以在 GKE Autopilot 或 Standard 集群中的 GPU 上应用 Gemma。我们建议您使用 Autopilot 集群获得全托管式 Kubernetes 体验。如需选择最适合您的工作负载的 GKE 操作模式，请参阅选择 GKE 操作模式。
Autopilot
在 Cloud Shell 中，运行以下命令：
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
替换以下值：
PROJECT_ID：您的 Google Cloud项目 ID。CONTROL_PLANE_LOCATION：集群控制平面的 Compute Engine 区域。提供支持要使用的加速器类型的区域，例如适用于 L4 GPU 的us-central1。CLUSTER_NAME：您的集群的名称。
GKE 会根据所部署的工作负载的请求，创建具有所需 CPU 和 GPU 节点的 Autopilot 集群。
Standard
在 Cloud Shell 中，运行以下命令以创建 Standard 集群：
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=CONTROL_PLANE_LOCATION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1替换以下值：
PROJECT_ID：您的 Google Cloud项目 ID。CONTROL_PLANE_LOCATION：集群控制平面的 Compute Engine 区域。提供支持要使用的加速器类型的区域，例如适用于 L4 GPU 的us-central1。CLUSTER_NAME：您的集群的名称。
集群创建可能需要几分钟的时间。
如需为集群创建具有适当磁盘大小的节点池，请运行以下命令：
Gemma 3 1B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE 会创建一个节点池，其中每个节点有一个 L4 GPU。
Gemma 3 4B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE 会创建一个节点池，其中每个节点有一个 L4 GPU。
Gemma 3 12B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-48 \ --num-nodes=1GKE 会创建一个节点池，其中每个节点有四个 L4 GPU。
Gemma 3 27B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-a100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a2-ultragpu-1g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256GKE 会创建一个节点池，其中包含一个 A100 80GB GPU。
为 Hugging Face 凭据创建 Kubernetes Secret
在 Cloud Shell 中，执行以下操作：
配置
kubectl，使其能够与您的集群通信：gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGION替换以下值：
REGION：支持要使用的加速器类型的区域，例如适用于 L4 GPU 的us-central1。CLUSTER_NAME：您的集群的名称。
创建包含 Hugging Face 令牌的 Kubernetes Secret：
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -将
HF_TOKEN替换为您之前生成的 Hugging Face 令牌。
部署 vLLM
在本部分中，您将部署 vLLM 容器以应用您要使用的 Gemma 模型。为了部署模型，本教程将使用 Kubernetes Deployment。Deployment 是一个 Kubernetes API 对象，可让您运行在集群节点中分布的多个 Pod 副本。
Gemma 3 1B-it
请按照以下说明部署 Gemma 3 1B 指令调优模型（纯文本输入）。
创建以下
vllm-3-1b-it.yaml清单：应用清单：
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
请按照以下说明部署 Gemma 3 4B 指令调优模型。
创建以下
vllm-3-4b-it.yaml清单：应用清单：
kubectl apply -f vllm-3-4b-it.yaml在我们的示例中，我们使用 vLLM 选项
--max-model-len=32768将上下文窗口限制为 32 K。如果您需要更大的上下文窗口（最多 128 K），请调整清单和节点池配置，以增加 GPU 容量。
Gemma 3 12B-it
请按照以下说明部署 Gemma 3 12B 指令调优模型。
创建以下
vllm-3-12b-it.yaml清单：应用清单：
kubectl apply -f vllm-3-12b-it.yaml在我们的示例中，我们使用 vLLM 选项
--max-model-len=16384将上下文窗口大小限制为 16 K。如果您需要更大的上下文窗口（最多 128 K），请调整清单和节点池配置，以增加 GPU 容量。
Gemma 3 27B-it
请按照以下说明部署 Gemma 3 27B 指令调优模型。
创建以下
vllm-3-27b-it.yaml清单：应用清单：
kubectl apply -f vllm-3-27b-it.yaml在我们的示例中，我们使用 vLLM 选项
--max-model-len=32768将上下文窗口大小限制为 32 K。如果您需要更大的上下文窗口（最多 128K），请调整清单和节点池配置，以增加 GPU 容量。
集群中的 Pod 会从 Hugging Face 下载模型权重并启动服务引擎。
等待部署成为可用状态：
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
查看正在运行的部署的日志：
kubectl logs -f -l app=gemma-server
部署资源会下载模型数据。此过程可能需要几分钟的时间。输出类似于以下内容：
INFO: Automatically detected platform cuda.
...
INFO [launcher.py:34] Route: /v1/chat/completions, Methods: POST
...
INFO: Started server process [13]
INFO: Waiting for application startup.
INFO: Application startup complete.
Default STARTUP TCP probe succeeded after 1 attempt for container "vllm--google--gemma-3-4b-it-1" on port 8080.
确保模型已完全下载，然后再继续下一部分。
应用模型
在本部分中，您将与模型互动。
设置端口转发
运行以下命令以设置到模型的端口转发：
kubectl port-forward service/llm-service 8000:8000
输出类似于以下内容：
Forwarding from 127.0.0.1:8000 -> 8000
使用 curl 与模型互动
本部分介绍如何执行基本的冒烟测试来验证所部署的 Gemma 3 指令调优模型。对于其他模型，请将 gemma-3-4b-it 替换为相应模型的名称。
此示例展示了如何使用纯文本输入来测试 Gemma 3 4B 指令调优模型。
在新的终端会话中，使用 curl 与模型聊天：
curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-4b-it",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
输出类似于以下内容：
{
"id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
"object": "chat.completion",
"created": 1741763029,
"model": "google/gemma-3-4b-it",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": 106
}
],
"usage": {
"prompt_tokens": 15,
"total_tokens": 668,
"completion_tokens": 653,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
（可选）通过 Gradio 聊天界面与模型互动
在本部分中，您将构建一个网页聊天应用，可让您与指令调优模型互动。为简单起见，本部分仅介绍使用 4B-it 模型的测试方法。
Gradio 是一个 Python 库，它具有一个可为聊天机器人创建界面的 ChatInterface 封装容器。
部署聊天界面
在 Cloud Shell 中，将以下清单保存为
gradio.yaml。将google/gemma-2-9b-it更改为google/gemma-3-4b-it或您在部署中使用的其他 Gemma 3 模型的名称。应用清单：
kubectl apply -f gradio.yaml等待部署成为可用状态：
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
使用聊天界面
在 Cloud Shell 中，运行以下命令：
kubectl port-forward service/gradio 8080:8080这会创建从 Cloud Shell 到 Gradio 服务的端口转发。
点击 Cloud Shell 任务栏右上角的
网页预览按钮。点击在端口 8080 上预览。浏览器中会打开一个新的标签页。使用 Gradio 聊天界面与 Gemma 互动。添加提示，然后点击提交。
问题排查
- 如果您收到
Empty reply from server消息，则容器可能尚未完成模型数据下载。再次检查 Pod 的日志中是否包含Connected消息，该消息表明模型已准备好进行应用。 - 如果您看到
Connection refused，请验证您的端口转发已启用。
观察模型性能
如需查看模型的可观测性指标对应的信息中心，请按以下步骤操作：
在 Google Cloud 控制台中，前往已部署的模型页面。
如需查看特定部署的详细信息（包括其指标、日志和信息中心），请点击列表中的模型名称。
在模型详情页面中，点击可观测性标签页以查看以下信息中心。如果系统提示，请点击启用以对集群启用指标收集。
- 基础设施使用情况信息中心会显示利用率指标。
- DCGM 信息中心会显示 DCGM 指标。
- 如果您使用的是 vLLM，则可以使用模型性能信息中心，该信息中心会显示 vLLM 模型性能的指标。
您还可以在 Cloud Monitoring 中的 vLLM 信息中心集成中查看指标。 这些指标会针对所有 vLLM 部署进行汇总，且没有预设过滤条件
如需使用 Cloud Monitoring 中的信息中心，您必须在 GKE 集群中启用 Google Cloud Managed Service for Prometheus，该服务会从 vLLM 收集指标。vLLM 默认以 Prometheus 格式公开指标；您无需安装其他导出工具。如需了解如何使用 Google Cloud Managed Service for Prometheus 从模型收集指标，请参阅 Cloud Monitoring 文档中的 vLLM 可观测性指南。