使用 vLLM Recipes 部署大语言模型：从单卡到多节点的完整指南

Posted on In

vLLM 官方 recipes 仓库 提供了超过 57 个生产级部署配方，覆盖 28+ 主流模型家族。本文深入剖析这些配方背后的部署模式、硬件选择、并行策略与调优技巧，帮助你快速从零到一地在生产环境中部署大型语言模型。

Recipes 仓库概览

仓库按模型厂商组织目录，每个模型提供：

  • Markdown 配方文件：详细的部署步骤、性能数据与最佳实践
  • YAML 配置文件：针对不同硬件（Hopper/Blackwell/AMD）的优化参数
  • Python 脚本：云端无服务器部署示例
  • Jupyter Notebook：端到端交互式教程
1
2
3
4
5
6
7
8
9
recipes/
├── Llama/          # Meta Llama 3.1 / 3.3 / 4-Scout
├── DeepSeek/       # DeepSeek V3 / V3.2 / R1 / OCR
├── Qwen/           # Qwen3 / Qwen3-Coder / Qwen3-VL
├── Google/         # Gemma 4 / TranslateGemma
├── OpenAI/         # GPT-OSS-120B
├── Mistral/
├── NVIDIA/         # Nemotron 系列
└── ...             # 20+ 其他模型家族

第一步：选择硬件

NVIDIA GPU

架构 代表型号 特点 推荐量化
Blackwell B200 / B300 原生 FP4 支持，最新一代 NVFP4 / FP8
Hopper H100 / H200 FP8 成熟，主流生产 FP8
Ampere A100 / A800 旧一代，广泛普及 BF16 / INT8

AMD GPU

AMD 的 MI300X 系列对大模型极为友好，单卡 192GB HBM3 内存可以容纳很多无需分片的模型：

1
2
3
4
5
# AMD ROCm 7.0+ 环境变量
export VLLM_ROCM_USE_AITER=1
export VLLM_ROCM_QUICK_REDUCE_QUANTIZATION=INT4

docker pull vllm/vllm-openai-rocm:latest

Google Cloud TPU

  • **Trillium (v6e)**：Google 第六代 TPU，适合大规模推理
  • Ironwood：最新一代，需外部 recipes 支持
  • 使用专用 Docker 镜像：vllm/vllm-tpu:gemma4

第二步：理解并行策略

不同负载场景下，选择合适的并行方式至关重要。

Tensor Parallelism（TP）—— 低延迟场景

将模型权重横向切分到多张卡，每张卡持有全部 layers 但只有部分 heads/channels：

1
2
3
vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --tensor-parallel-size 4   # 4 卡 TP
  --max-model-len 32768

适用：交互式低延迟场景（TTFT < 500ms）

Data Parallelism（DP）—— 高吞吐场景

多个独立引擎实例并行处理不同请求，无需跨卡通信：

1
2
3
vllm serve deepseek-ai/DeepSeek-R1-0528 \
  --data-parallel-size 8     # 8 个独立引擎实例
  --enable-expert-parallel

适用：高并发批量推理场景

Expert Parallelism（EP）—— MoE 模型专用

针对混合专家（MoE）架构，将不同 expert 分布到不同 GPU，减少单卡内存压力：

1
2
3
4
5
# DeepSeek V3 / R1 在 8xH200 上的推荐配置
vllm serve deepseek-ai/DeepSeek-R1-0528 \
  --trust-remote-code \
  --tensor-parallel-size 8 \
  --enable-expert-parallel    # EP 与 TP 可以组合使用

Pipeline Parallelism（PP）—— 超大模型分层

将模型不同 layers 分布到不同 GPU，通过流水线减少气泡：

1
2
3
4
# Kimi-K2 示例
vllm serve moonshotai/Kimi-K2-Instruct \
  --pipeline-parallel-size 2 \
  --tensor-parallel-size 4

策略选择速查表

场景 推荐策略 说明
7B~70B 低延迟 TP=2/4 单节点内高效通信
70B~200B 高吞吐 DP=4/8 + TP=1 避免跨卡 AllReduce 开销
MoE 模型（DeepSeek/Qwen） DP + EP 专家并行降低单卡内存
超大模型（>500B） TP + EP 或 PP 多节点分布式

第三步：量化策略

量化大幅降低显存占用，提高吞吐，但需要权衡精度损失。

FP8（推荐用于 H100/H200/B200）

显存减少 ~50%，精度损失极小：

1
2
# config.yaml
kv-cache-dtype: fp8
1
2
3
vllm serve nvidia/Llama-3.3-70B-Instruct-FP8 \
  --config Llama3.3_Hopper.yaml \
  --tensor-parallel-size 2

NVFP4（Blackwell 专属）

在 B200 上进一步将显存压缩 ~75%，性能损失可控：

1
2
3
4
5
export VLLM_USE_FLASHINFER_MOE_FP4=1

vllm serve nvidia/DeepSeek-R1-FP4 \
  --tensor-parallel-size 4 \
  --enable-expert-parallel

BF16（兼容性最广）

A100 等老一代 GPU 默认精度，无量化损失但显存占用最大：

1
2
3
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --dtype bfloat16 \
  --tensor-parallel-size 1

第四步：典型模型部署案例

案例一：Llama 3.3-70B — Blackwell 优化部署

目标硬件：1x NVIDIA B200
配置文件：Llama/Llama3.3_Blackwell.yaml

1
2
3
4
5
6
7
8
9
10
11
# Llama3.3_Blackwell.yaml
kv-cache-dtype: fp8
compilation-config: >
  {"pass_config": {
    "fuse_allreduce_rms": true,
    "fuse_attn_quant": true,
    "eliminate_noops": true
  }}
async-scheduling: true
no-enable-prefix-caching: true
max-num-batched-tokens: 8192
1
2
3
4
5
docker pull vllm/vllm-openai:v0.12.0

vllm serve nvidia/Llama-3.3-70B-Instruct-FP4 \
  --config Llama3.3_Blackwell.yaml \
  --tensor-parallel-size 1

关键参数解读：

  • fuse_allreduce_rms：融合 AllReduce 与 RMSNorm，减少 kernel 启动开销
  • async-scheduling：CPU 调度与 GPU 解码重叠，提升利用率
  • max-num-batched-tokens: 8192：控制每个迭代的 token 预算

案例二：DeepSeek-R1 — MoE 多卡部署

目标硬件：8x NVIDIA H200
模型规模：671B 参数，37B 激活

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 高负载场景：DP + EP（推荐）
vllm serve deepseek-ai/DeepSeek-R1-0528 \
  --trust-remote-code \
  --data-parallel-size 8 \
  --enable-expert-parallel \
  --kv-cache-dtype fp8 \
  --max-model-len 65536 \
  --gpu-memory-utilization 0.90 \
  --host 0.0.0.0 --port 8000

# 低延迟场景：TP + EP
vllm serve deepseek-ai/DeepSeek-R1-0528 \
  --trust-remote-code \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --kv-cache-dtype fp8

为什么推荐 DP+EP？

DeepSeek 的 MoE kernel 已针对 TP=1 高度优化，使用 TP 跨卡切分反而引入 AllReduce 开销。高并发场景下，DP=8 可以将 8 个独立实例全部塞满，吞吐远超 TP=8 单实例。

案例三：Gemma4-31B — 多模态 Docker 部署

支持模态：文本 + 图像（动态分辨率）+ 音频 + 视频

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
docker run -itd --name gemma4 \
    --ipc=host \
    --network host \
    --shm-size 16G \
    --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -e HF_TOKEN=$HF_TOKEN \
    vllm/vllm-openai:gemma4 \
        --model google/gemma-4-31B-it \
        --tensor-parallel-size 2 \
        --max-model-len 32768 \
        --gpu-memory-utilization 0.90 \
        --limit-mm-per-prompt image=4,audio=1 \
        --reasoning-parser gemma4 \
        --host 0.0.0.0 --port 8000

多模态请求示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="token")

response = client.chat.completions.create(
    model="google/gemma-4-31B-it",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://..."}},
            {"type": "text", "text": "描述这张图片中的内容"}
        ]
    }],
    max_tokens=1024
)

案例四：Qwen3-Coder-480B — 超大 MoE 代码模型

目标硬件：8x NVIDIA H200（480B 参数，35B 激活）

1
2
3
4
5
6
7
8
VLLM_USE_DEEP_GEMM=1 vllm serve Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 \
  --max-model-len 131072 \
  --enable-expert-parallel \
  --data-parallel-size 8 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --gpu-memory-utilization 0.92 \
  --host 0.0.0.0 --port 8000

实测性能（8xH200）：

指标 数值
请求吞吐 0.13 req/s
输出 token 吞吐 131.88 tok/s
中位 TTFT 6935.71 ms
中位 TPOT 67.23 ms

第五步：高级特性配置

Speculative Decoding（EAGLE3）

通过小 draft 模型预测多个 token，大模型一次验证，可提升 2-3x 解码速度：

1
2
3
4
5
6
7
8
9
10
# GPT-OSS_EAGLE3_Blackwell.yaml
kv-cache-dtype: fp8
speculative-config: >
  {
    "model": "nvidia/gpt-oss-120b-Eagle3-v2",
    "num_speculative_tokens": 3,
    "method": "eagle3",
    "draft_tensor_parallel_size": 1
  }
stream-interval: 20
1
2
3
vllm serve nvidia/OpenAI-GPT-OSS-120B \
  --config GPT-OSS_EAGLE3_Blackwell.yaml \
  --tensor-parallel-size 8

Tool Calling & Function Calling

1
2
3
4
# 启用自动工具选择
vllm serve Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 工具调用请求示例
tools = [{
    "type": "function",
    "function": {
        "name": "read_file",
        "description": "读取文件内容",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
        }
    }
}]

response = client.chat.completions.create(
    model="Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
    messages=[{"role": "user", "content": "读取 /etc/hosts 文件"}],
    tools=tools,
    tool_choice="auto"
)

Async Scheduling（异步调度）

V1 架构中，CPU 调度与 GPU 解码可以重叠执行，消除调度气泡：

1
async-scheduling: true

此选项对高并发场景（batch size > 32）收益显著，可将 GPU 利用率从 ~85% 提升至 ~95%。

第六步：云端无服务器部署（Modal 示例）

对于无需常驻服务器的场景，Modal 提供按需 GPU 调用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# gemma4-modal.py（简化版）
import modal

app = modal.App("gemma4-vllm")

image = (
    modal.Image.debian_slim()
    .pip_install("vllm==0.9.0")
)

@app.cls(
    gpu=modal.gpu.H200(count=2),
    image=image,
    volumes={"/root/.cache/huggingface": modal.Volume.from_name("hf-cache")},
    max_containers=3,         # 最大并发实例数
    scaledown_window=300,     # 5 分钟无请求后缩容
)
class VllmService:
    @modal.enter()
    def load_model(self):
        from vllm import LLM
        self.llm = LLM(
            model="google/gemma-4-31B-it",
            tensor_parallel_size=2,
            max_model_len=32768,
        )

    @modal.method()
    def generate(self, prompt: str) -> str:
        outputs = self.llm.generate([prompt])
        return outputs[0].outputs[0].text

优势：

  • 零闲置成本，按调用计费
  • 自动扩缩容
  • 无需管理 Kubernetes

第七步：性能基准测试

在部署完成后，用官方 benchmark 工具验证性能：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 标准吞吐测试
vllm bench serve \
  --model deepseek-ai/DeepSeek-R1-0528 \
  --dataset-name random \
  --random-input-len 8000 \
  --random-output-len 1024 \
  --max-concurrency 512 \
  --num-prompts 2560 \
  --ignore-eos \
  --save-result \
  --result-filename results.json

# 结果分析
python -c "
import json
with open('results.json') as f:
    r = json.load(f)
print(f'请求吞吐: {r[\"request_throughput\"]:.2f} req/s')
print(f'输出 token 吞吐: {r[\"output_throughput\"]:.2f} tok/s')
print(f'中位 TTFT: {r[\"median_ttft_ms\"]:.1f} ms')
print(f'中位 TPOT: {r[\"median_tpot_ms\"]:.1f} ms')
"

关键性能指标

指标 说明 优化方向
TTFT Time to First Token，首 token 延迟 减少 prefill 负载，使用 chunked prefill
TPOT Time Per Output Token，每个解码 token 时间 增大 batch size，使用 FP8/FP4
ITL Inter-Token Latency，token 间隔 等同 TPOT，交互式场景关注
吞吐 tok/s，系统总体处理能力 增大 batch，使用 DP 扩展

延迟 vs 吞吐调优

1
2
3
4
5
6
7
8
9
10
11
# 最低延迟配置（小 batch，多卡 TP）
vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --tensor-parallel-size 8 \
  --max-num-seqs 8 \
  --max-num-batched-tokens 2048

# 最高吞吐配置（大 batch，少卡 TP）
vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --tensor-parallel-size 1 \
  --max-num-seqs 512 \
  --max-num-batched-tokens 32768

常见问题与调优

OOM（显存不足）

1
2
3
4
5
6
7
8
# 降低显存使用率
--gpu-memory-utilization 0.80   # 默认 0.90

# 限制最大上下文长度
--max-model-len 16384

# 启用 CPU offload
--swap-space 16   # 16GB CPU 内存作为 swap

吞吐低于预期

1
2
3
4
5
6
7
8
9
10
11
# 检查 GPU 利用率
watch -n 1 nvidia-smi

# 增大 token 预算
--max-num-batched-tokens 16384

# 启用异步调度
--async-scheduling

# 禁用 prefix caching（稳定基准）
--no-enable-prefix-caching

CUDA Graph 问题

1
2
3
4
5
# 调整 CUDA graph 捕获大小
--max-cudagraph-capture-size 2048

# 如果 graph 捕获 OOM，减小此值或禁用
--enforce-eager   # 禁用 CUDA graph，仅用于调试

AMD GPU 特定问题

1
2
3
4
# MI300X 推荐环境变量
export VLLM_ROCM_USE_AITER=1
export VLLM_ROCM_QUICK_REDUCE_QUANTIZATION=INT4
export HSA_OVERRIDE_GFX_VERSION=9.4.2   # MI300X gfx942

完整部署模板

单节点 Docker Compose

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# docker-compose.yml
version: '3.8'
services:
  vllm:
    image: vllm/vllm-openai:v0.12.0
    runtime: nvidia
    environment:
      - HF_TOKEN=${HF_TOKEN}
      - NVIDIA_VISIBLE_DEVICES=all
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    shm_size: '16gb'
    ipc: host
    command: >
      --model meta-llama/Llama-3.3-70B-Instruct
      --tensor-parallel-size 4
      --max-model-len 32768
      --gpu-memory-utilization 0.90
      --kv-cache-dtype fp8
      --async-scheduling
      --host 0.0.0.0
      --port 8000
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Kubernetes Deployment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# vllm-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-llama3-70b
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:v0.12.0
        resources:
          limits:
            nvidia.com/gpu: "4"
            memory: "200Gi"
          requests:
            nvidia.com/gpu: "4"
        env:
        - name: HF_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token
              key: token
        args:
        - --model
        - meta-llama/Llama-3.3-70B-Instruct
        - --tensor-parallel-size
        - "4"
        - --max-model-len
        - "32768"
        - --kv-cache-dtype
        - fp8
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 120
          periodSeconds: 30
        volumeMounts:
        - name: hf-cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: hf-cache
        persistentVolumeClaim:
          claimName: hf-cache-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: ClusterIP

总结

vLLM recipes 仓库展示了一套成熟的大模型部署最佳实践体系：

维度 关键选择
硬件 B200（前沿）→ H100/H200（主流）→ A100（兼容）→ MI300X（AMD）
量化 NVFP4（B200）→ FP8（H100+）→ BF16（A100）
并行 TP（低延迟）/ DP（高吞吐）/ EP（MoE 模型）
部署 Docker（快速）/ K8s（生产）/ Modal（Serverless）
优化 async-scheduling + CUDA graph + prefix caching

选择建议：

  1. 研究/测试：单卡 Docker，BF16 精度，简单配置
  2. 小规模生产（7B~70B）：2-4 卡 TP，FP8，Docker 或 K8s
  3. 大规模生产（70B~671B）：DP + EP，FP8/FP4，K8s + 自动扩缩
  4. 突发负载：Modal 或云端按需 GPU，零闲置成本

参考资料