# 使用 Terraform 在 GKE 上部署 vLLM：企业级大语言模型推理基础设施实践

> 本文介绍如何通过 Terraform 在 Google Kubernetes Engine 上部署 vLLM，实现自动化模型下载、GPU 自动扩缩容和安全的 Hugging Face Token 管理，为企业提供可扩展的高性能 LLM 推理基础设施。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-25T22:45:02.000Z
- 最近活动: 2026-05-25T22:49:10.324Z
- 热度: 161.9
- 关键词: vLLM, GKE, Terraform, LLM推理, GPU, Kubernetes, 基础设施即代码, 投机解码, 成本优化
- 页面链接: https://www.zingnex.cn/forum/thread/terraform-gke-vllm
- Canonical: https://www.zingnex.cn/forum/thread/terraform-gke-vllm
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：kweinmeister
- 来源平台：GitHub
- 原始标题：vllm-gke-terraform
- 原始链接：https://github.com/kweinmeister/vllm-gke-terraform
- 来源发布时间/更新时间：2026-05-25T22:45:02Z

---

## 引言：为什么需要 Terraform 化的 LLM 推理基础设施

随着大语言模型在生产环境中的广泛应用，企业面临着如何高效、安全、可扩展地部署推理服务的挑战。vLLM 作为高性能的 LLM 推理引擎，配合 Kubernetes 的编排能力，已成为业界主流方案。然而，手动配置 GPU 节点池、存储卷、模型下载和推理服务不仅繁琐，还容易出错。

Terraform 作为基础设施即代码（IaC）的行业标准，能够将整个部署流程标准化、版本化、可复现。本文将深入解析一个开源项目，展示如何在 Google Kubernetes Engine（GKE）上通过 Terraform 一键部署完整的 vLLM 推理基础设施。

---

## 架构概览：双节点池与成本优化策略

该 Terraform 模块的核心设计亮点在于其双节点池架构，兼顾性能与成本效益：

### Spot 节点池（成本优化）

Spot 实例利用 GCP 的闲置计算资源，价格可比标准实例低 60-91%。对于批处理或非关键推理任务，这是理想选择。需要注意的是，Spot 实例可能被随时回收，因此不适合需要 100% 可用性的生产环境。

### On-Demand 节点池（稳定保障）

作为 Spot 节点池的 fallback，On-Demand 节点池确保在 Spot 资源不足时，推理服务仍能正常运行。这种混合策略让企业在成本和稳定性之间取得平衡。

### 持久化存储（PVC）

模块自动创建 Persistent Volume Claim 用于缓存 Hugging Face 模型。首次下载后，模型文件存储在集群存储中，后续 Pod 启动时可直接挂载，显著减少冷启动时间。

---

## 安全实践：Token 管理与访问控制

在生产环境中，API Token 的安全管理至关重要。该项目采用了多层安全策略：

### 环境变量注入

Hugging Face Token 通过 Terraform 变量 `TF_VAR_hf_token` 注入，避免硬编码到代码仓库。这种方式支持 CI/CD 流水线中的密钥管理服务集成。

### Kubernetes Secrets

Token 最终以 Kubernetes Secret 的形式存储在集群中，只有授权的 Pod 才能访问。这比直接在容器镜像中嵌入 Token 要安全得多。

### 内部服务隔离

默认配置下，vLLM 服务仅暴露为 Kubernetes 内部 Service，没有公网 IP。用户需要通过 `kubectl port-forward` 在本地建立安全隧道来访问，这大大降低了攻击面。

---

## 部署流程：从代码到运行的完整路径

### 前置准备

部署前需要完成以下准备工作：

1. **GCP 项目配置**：确保项目已启用结算，并开启 Container Engine API
2. **本地工具链**：安装 gcloud CLI、Terraform（v1.5+）、kubectl
3. **Terraform 状态存储**：创建 GCS Bucket 用于存储状态文件，启用版本控制以防意外

### 核心部署步骤

```bash
# 克隆仓库
git clone https://github.com/kweinmeister/vllm-gke-terraform.git
cd vllm-gke-terraform

# 配置执行权限
chmod +x scripts/validate-cache.sh

# 设置环境变量
export TF_VAR_hf_token="hf_你的令牌"
export PROJECT_ID=$(gcloud config get-value project)
export TF_STATE_BUCKET=$PROJECT_ID-tf-state

# 初始化并部署
terraform init -backend-config="bucket=$TF_STATE_BUCKET"
terraform plan
terraform apply
```

### 模型下载 Job

部署过程中会创建一个 Kubernetes Job，专门负责从 Hugging Face 下载模型。这个设计很聪明：模型下载是一个一次性的、可能耗时的操作，使用 Job 而不是在推理 Pod 的 init 容器中完成，可以让推理服务更快启动。

---

## 配置灵活性：从 Qwen3-32B 到自定义模型

虽然默认配置使用 Qwen/Qwen3-32B 模型，但模块设计充分考虑了灵活性：

### 模型切换

通过修改 `model_id` 变量，可以轻松切换到其他 Hugging Face 模型。模块支持任意兼容 vLLM 的模型架构。

### 硬件配置

默认使用 `g2-standard-48` 节点配 4x NVIDIA L4 24GB GPU，适合中等规模模型。对于需要更高性能的场景，可切换到 `a3-highgpu-8g` 节点配 8x NVIDIA H100 80GB GPU，但成本会显著增加。

### 推理参数调优

模块暴露了大量 vLLM 参数供调优，包括：
- `gpu_memory_utilization`：控制 GPU 显存使用率
- `vllm_dtype`：数据类型（fp16/bf16等）
- `max_model_len`：最大序列长度
- `enable_speculative_decoding`：启用投机解码加速

### 零副本启动

通过设置 `replicas = 0`，可以先完成模型下载和验证，再手动扩容。这在成本敏感的场景下特别有用——只在需要推理时才支付 GPU 费用。

---

## 投机解码：加速推理的黑科技

该项目支持 vLLM 的投机解码（Speculative Decoding）功能，这是提升推理速度的高级特性。

### 工作原理

投机解码使用一个较小的草稿模型（draft model）快速生成候选 Token，然后用主模型并行验证。如果验证通过，就能一次输出多个 Token，显著提升吞吐。

### 配置示例

项目中配置了 `Zhihu-ai/Zhi-Create-Qwen3-32B-Eagle3` 作为 Qwen3-32B 的投机模型。启用后，适合对延迟敏感但可接受轻微精度波动的场景。

---

## 运维考量：监控、扩展与成本控制

### 自动扩缩容

GKE 的节点自动扩缩容与 vLLM 的 Pod 水平扩缩容结合，可以实现负载自适应。当请求量增加时自动添加 GPU 节点，低峰期自动缩容。

### 成本警告

项目文档明确提醒：GPU 节点成本高昂。以美国区域为例：
- L4 GPU 节点：约 $1.5/小时
- H100 GPU 节点：约 $15+/小时

建议生产环境配置预算告警，并考虑使用 Committed Use Discounts 降低成本。

### 多模型部署

通过 `name_prefix` 变量，可以在同一集群中部署多个模型实例，每个实例有独立的资源命名空间，互不干扰。

---

## 实践启示：企业级 LLM 部署的关键经验

从这个开源项目中，我们可以提炼出以下企业级 LLM 部署的关键经验：

1. **基础设施即代码**：Terraform 让部署可复现、可审计、可回滚，是生产环境的标准做法。

2. **分层成本优化**：Spot + On-Demand 的混合策略，配合按需扩缩容，能在保证可用性的前提下最大化成本效益。

3. **安全左移**：从 Token 管理到网络隔离，安全应该内建在基础设施层，而不是事后补救。

4. **存储优化**：PVC 缓存避免重复下载，对于动辄几十 GB 的大模型尤为重要。

5. **模块化设计**：清晰的变量和输出定义，让不同团队可以基于同一模块定制自己的部署。

---

## 结语

vLLM on GKE with Terraform 项目展示了如何将大语言模型推理服务以企业级标准部署到云端。它不仅是一个可用的 Terraform 模块，更是一套经过实践检验的 LLM 基础设施最佳实践。无论是初创公司验证想法，还是大型企业扩展 AI 服务，这个方案都提供了坚实的起点。

对于希望自建 LLM 推理基础设施的团队，建议从默认配置开始，逐步根据业务需求调整硬件规格、模型选择和成本策略。记住：在生产环境中运行 GPU 工作负载时，监控和成本控制与性能同样重要。