vLLM 运行参数完全指南

版本	特性
v0.4+	PagedAttention V2 · 推测解码 (EAGLE / N-Gram / PARD)
v0.5+	分离式推理 (Disaggregated Prefill/Decode)
v0.6+	专家并行 EP · LMCache 集成 · Chunked Prefill
v0.8+	V1 引擎重构 · 多 LoRA · NUMA 绑定
最新	200+ 模型 · MTP 推测 · KV 传输多后端 (NIXL/UCX/GDS)

02 · 单节点推理参数

GPU 配置 · 内存调度 · 量化

单节点是 vLLM 部署的基础形态。合理的参数配置直接影响推理性能与显存开销——错误配置可能导致 OOM 或 GPU 利用率不足。

GPU 配置

显存与并行

--gpu-memory-utilization 0.9      # 显存占比 0~1
--tensor-parallel-size 4            # 张量并行度，偶数 ≤ 8
--dtype bfloat16                     # 数据类型：bf16 / fp16 / fp32

默认值 gpu-memory-utilization=0.9，生产环境常用 0.9-0.95，显存不足时下调至 0.8

内存调度

批次与上下文

--max-model-len 8192                # 最大上下文长度
--max-num-seqs 64                    # 批次最大序列数
--max-num-batched-tokens 8192       # 批次最大 token 数

降低 max-num-seqs 减少显存压力；增大 max-num-batched-tokens 提升吞吐

参数深度解读

--gpu-memory-utilization float

默认值: 0.9 · 取值范围: 0.0 ~ 1.0

控制 KV cache 可用的 GPU 显存比例。剩余显存用于模型权重、激活值和临时缓冲区。此值越高，KV cache 可用显存越多，可支持更大批次和更长上下文。

场景建议：生产环境 0.9~0.95；显存不足/模型较大 0.8~0.85；调试/多模型共存 0.7~0.75。注意：设置过高 (>0.95) 可能导致 OOM 或 CUDA OOM。

⚠ 此值不是越高越好，需为模型权重和其他开销预留空间

--tensor-parallel-size int / -tp

默认值: 1 · 推荐值: 2/4/8

将模型权重张量切分到多块 GPU 上并行计算。TP 是一种通信密集的并行策略，每层前向传播都需要 GPU 间同步。TP 越大单卡显存需求越低，但通信开销也越大。

场景建议：7B 模型用 1~2 卡；13~34B 用 4 卡；70B 模型用 8 卡。超过 8 卡时通信开销增速超过收益，建议配合 PP 使用。

⚠ 奇数不支持，需为偶数。TP 度越高，GPU 间通信延迟越显著

--max-model-len int

默认值: 模型配置值

限制模型使用的最大上下文长度（prompt + generated tokens）。vLLM 会按此值分配 KV cache 空间，因此该值直接影响显存占用。设置为模型支持的上下文长度的子集可以节约显存。

场景建议：Stream Chat 用 4K~8K；文档分析用 32K~128K。减少此值可以显著降低显存占用，尤其适合长上下文模型但不需要长序列的场景。

--max-num-seqs int

默认值: 动态计算 · 推荐区间: 16~256

控制单次调度批次中最多可并行处理的序列数。每个序列都需要独立的 KV cache 空间。此值影响显存占用和 GPU 计算利用率之间的平衡。

场景建议：延迟敏感（聊天）用 16~32；吞吐优先（批量推理）用 64~256；显存受限场景降低至 16 以下。较大的值可提高吞吐但增加显存压力。

--max-num-batched-tokens int

默认值: 动态计算 · 推荐区间: 256~32768

控制单批次中最多可容纳的总 token 数（所有序列的 prompt + generation tokens 之和）。这是影响吞吐和延迟平衡的关键参数。

场景建议：TTFT（首 token 延迟）敏感场景设 256~1024；吞吐优先场景设 8192~32768；启用了 chunked prefill 后可设更高值以增加 GPU 利用率。

--dtype str

默认值: auto · 可选: float16 / bfloat16 / float32

控制模型推理时的数据类型。bfloat16 是训练/推理的默认选择，float32 提供最高精度但显存占用翻倍。auto 会根据模型配置自动选择。

场景建议：A100/H100 用 bfloat16（最佳性能+稳定性）；V100 用 float16（不支持 bf16）；精度敏感场景用 float32（显存翻倍）。

--block-size int

默认值: 16

PagedAttention 的虚拟内存页大小。更大的 block-size 可以提升 GPU 计算效率但会增加内部碎片。更小的 block-size 减少碎片但增加管理开销。

场景建议：标准 GPU 场景保留 16；CPU 交换/卸载场景用 32；启用了 KV 传输/分离式推理时推荐 64。

--swap-space int (GB)

默认值: 4

设置 CPU 交换空间的容量（单位 GB）。当 GPU 显存不足以容纳所有 KV cache 时，vLLM 将部分 KV cache 交换到 CPU 内存。增加此值可提供更大的溢出缓冲区。

场景建议：标准场景保留默认 4；显存受限（如单卡运行大模型）设置为 16~32；7B 以下模型一般不需要调整。

⚡ 优化级别 --optimization-level vLLM 内置参数

控制 CUDA Graph 等内部优化策略的激进程度。可选值 0（最低）到 3（最高），级别越高吞吐越大，但显存占用和启动开销也相应增加。默认 2。

禁用 CUDA Graph

显存最低

调试 / 排查问题

条件 CUDA Graph

折中

显存紧张但需加速

默认

CUDA Graph + 内存优化

推荐生产

吞吐 & 显存均衡

激进 CUDA Graph

最高吞吐

显存充足场景

参数	默认值	说明	调优方向
`--gpu-memory-utilization`	0.9	KV cache 显存占比 (0~1)	↓ 解决 OOM，↑ 增吞吐
`--tensor-parallel-size`	1	张量并行 GPU 数	偶数，一般 ≤ 8
`--dtype`	auto	数据类型选择	A100/H100 用 bfloat16
`--max-num-seqs`	动态	批次最大序列数	↓ 减少显存压力
`--max-num-batched-tokens`	动态	批次最大 token 数	↑ 增吞吐，↓ 降延迟
`--block-size`	16	vLLM block 大小	CPU 场景用 32
`--swap-space`	4	CPU 交换空间 (GB)	大模型可增加
`--enforce-eager`	False	禁用 CUDA graph	OOM 时启用，降显存
`--optimization-level`	2	优化级别，控制 CUDA graph 和算子融合	0 降显存 · 2 生产 · 3 最高吞吐

量化选项

量化减少模型权重比特数，以少量精度损失换取大幅显存节省。GPU 架构兼容性是一个关键选择因素。

~40%

FP8 (e4m3)

H100/H200 原生支持

精度损失极小

~60%

INT8 AWQ

多数 GPU 支持

精度损失小

~70%

GGUF

CPU/GPU 混合

中等精度

~80%

INT4

部分 GPU 支持

注意精度下降

量化 GPU 兼容性

量化方法	H100/H200	A100/A800	V100	RTX 4090	推荐场景
FP8 (e4m3)	✅ 原生	⚠ 模拟	✗	⚠ 模拟	H100 首选量化
INT8 AWQ	✅	✅	✅	✅	通用生产推理
GGUF	✅	✅	✅	✅	CPU 卸载场景
INT4	✅	✅	⚠	✅	极致显存优化

参数权衡速览

⚡ 延迟优先

--max-num-batched-tokens 256
--enable-chunked-prefill
--block-size 64

TTFT ↓

🚀 吞吐优先

--max-num-batched-tokens 16384
--gpu-memory-utilization 0.95
--optimization-level 2

TPS ↑

💾 显存受限

--gpu-memory-utilization 0.8
--quantization fp8
--swap-space 16

OOM 防护

🔬 精度优先

--dtype float32
--enforce-eager
--seed 42

精度最高

部署规模	推荐组合	总 GPU	适用场景
单机 4 卡	`TP=4`	4	小模型多卡加速
单机 8 卡	`TP=8`	8	70B 标准部署
单机 8 卡	`TP=4, PP=2`	8	减少 TP 通信开销
2 节点 16 卡	`TP=8, PP=2`	16	跨节点推理
4 节点 32 卡	`TP=8, PP=2, DP=2`	32	中大规模高吞吐
16 节点 128 卡	`TP=8, PP=2, DP=8`	128	大规模生产集群

后端	参数	场景
Ray	`--dist-executor-backend ray`	多节点集群（默认）
Multiprocessing	`--dist-executor-backend mp`	单节点多卡

04 · 生态集成

LMCache · KV 传输 · 推测解码 · API 生态

vLLM 的生态集成能力大幅扩展了推理场景：LMCache 分布式 KV Cache 实现 3-10x 延迟优化，多种推测解码方法覆盖不同需求，完善的 API 兼容性适配现有工具链。

LMCache 分布式 KV Cache

📤 Prefill → KV 传输 → 📥 Decode

Prefill 节点 — pd_role: sender，缓冲区 1GB
Decode 节点 — pd_role: receiver，缓冲区 2GB
传输通道 — NIXL / NCCL / GDS 后端
性能提升 — 多轮对话 3-10x 延迟降低
适用场景 — RAG 对话、有状态应用、长会话推理

两种配置方式：简单场景仅设环境变量即可，不需要 YAML 文件；分离式 PD 场景需 YAML 文件通过 LMCACHE_CONFIG_FILE 引用

方式一：纯环境变量（简单场景）

# 仅用环境变量，无需 YAML 文件
LMCACHE_CHUNK_SIZE=256 \
LMCACHE_REMOTE_URL=redis://127.0.0.1:6379 \
LMCACHE_LOG_LEVEL=INFO \
vllm serve <model> \
  --kv-transfer-config '{
    "kv_connector":"LMCacheConnectorV1Dynamic",
    "kv_role":"kv_both"
  }'

方式二：YAML 配置文件（分离式 PD）

# lmcache.yaml (Prefill 发送节点)
local_cpu: False
enable_pd: True
transfer_channel: nixl
pd_role: sender
pd_buffer_size: 1073741824
pd_buffer_device: cuda
nixl_backends: [UCX]

# 启动
LMCACHE_CONFIG_FILE=./lmcache.yaml vllm serve ...

LMCache 完整环境变量

变量	默认值	说明
`LMCACHE_CONFIG_FILE`	None	YAML 配置文件路径（分离式 PD 必需）
`LMCACHE_CHUNK_SIZE`	`256`	KV cache 存储的 token 分块大小
`LMCACHE_REMOTE_URL`	None	远程存储 URL，支持 Redis、S3 等后端
`LMCACHE_LOG_LEVEL`	`INFO`	日志级别：DEBUG / INFO / WARNING
`LMCACHE_FORCE_SKIP_SAVE`	False	跳过 KV cache 保存（调试用）
`LMCACHE_OFFLOAD_RPC_PORT`	`100`	Offload RPC 端口
`LMCACHE_RESP_HOST`	None	Redis RESP 主机地址
`LMCACHE_RESP_PORT`	None	Redis RESP 端口

KV Transfer 配置详解

连接器	配置	kv_role	传输方式	场景
LMCacheConnectorV1	`kv_connector: "LMCacheConnectorV1"`	kv_both	LMCache 分布式缓存	多轮对话加速
P2pNcclConnector	`kv_connector: "P2pNcclConnector"`	producer / consumer	GPU 间 NCCL 直连	单机分离式推理
NixlConnector	`kv_connector: "NixlConnector"`	producer / consumer	网络传输 (UCX/GDS)	跨节点分离式推理

Prefill 实例 (vLLM)

--kv-transfer-config '{
  "kv_connector":"P2pNcclConnector",
  "kv_role":"kv_producer",
  "kv_buffer_size":"1e9",
  "kv_port":"21001"
}'

Decode 实例 (vLLM)

--kv-transfer-config '{
  "kv_connector":"P2pNcclConnector",
  "kv_role":"kv_consumer",
  "kv_buffer_size":"8e9",
  "kv_port":"22001"
}'

推测解码 (Speculative Decoding)

推测解码使用一个较小的草稿模型快速生成候选 token，再由目标模型验证，在保证输出质量的同时降低延迟。核心参数 num_speculative_tokens 控制每步提议 token 数。

方法对比

方法	延迟	额外模型	低 QPS	高 QPS
EAGLE	高收益	是	最佳	中高
EAGLE3	高收益	是	最佳	中高
PARD	高收益	是	高	中高
Draft Model	高收益	是	高	中
N-Gram	低中	否	低	中
Suffix	低中	否	低	中
MTP	高收益	视模型	高	中高

OpenAI 兼容 API

vLLM 提供完整的 OpenAI API 兼容接口，支持 Chat Completions、Completions、Embeddings 等主流端点，可直接替换 OpenAI API 调用。

API 端点

/v1/chat/completions — 聊天补全
/v1/completions — 文本补全
/v1/embeddings — 向量嵌入
/v1/models — 模型列表
/health — 健康检查
/metrics — Prometheus 指标

HuggingFace 集成

直接加载 HF Hub 模型：--model Qwen/Qwen2.5-7B
本地缓存优先，自动下载
--trust-remote-code — 允许 HuggingFace 加载模型仓库中的自定义 Python 代码（模型架构、分词器等）。部分新模型使用 transformers 未内置的自定义架构，需要通过此参数授权执行仓库中的 modeling 文件。安全提醒：请确保模型来源可信
--hf-config-path 指定配置文件
--hf-model-pattern 模型加载过滤

监控与可观测性

Prometheus — /metrics 端点暴露，支持自定义标签
vllm:num_requests_running — 当前运行请求数
vllm:kv_cache_usage_perc — KV Cache 使用率
vllm:time_to_first_token_seconds — TTFT 延迟
vllm:e2e_request_latency_seconds — 端到端延迟
Grafana — 官方 Dashboard 模板
OpenTelemetry — 链路追踪
Logging — --log-level 控制日志级别

平台集成

Kubernetes

容器化部署

# vLLM 官方 Docker 镜像
docker pull vllm/vllm-openai

# K8s 关键配置
resources:
  nvidia.com/gpu: 8
env:
- name: NCCL_IB_HCA
  value: mlx5_0
volumeMounts:
- mountPath: /dev/shm
  name: dshm
  emptyDir:
    medium: Memory
    sizeLimit: "16Gi"

LangChain

框架集成

通过 OpenAI 兼容 API 直接接入：

# LangChain 调用
ChatOpenAI(
  base_url="http://localhost:8000/v1",
  api_key="not-needed",
  model="Qwen2.5-7B"
)

# LlamaIndex
Vllm(model="Qwen2.5-7B")

Ray

集群管理

# Ray 集群模式
RAY_DASHBOARD_ADDR=127.0.0.1:8265 \
vllm serve <model> \
  --distributed-executor-backend ray

# 查看集群状态
ray status
ray list nodes

Prometheus 指标参考

vLLM 在 /metrics 端点暴露丰富的 Prometheus 指标，覆盖引擎状态、请求 SLO、KV Cache 效率等维度，可直接接入 Grafana 监控大屏。生产环境建议搭配 --log-level info 和 --kv-cache-metrics-sample 开启 KV 块级指标。

📊 服务器级别指标

指标名称	类型	含义	监控目的
vllm:num_requests_running	Gauge	当前正在运行的请求数	引擎负载饱和度
vllm:num_requests_swapped	Gauge	被 swap 到 CPU 的请求数	显存压力信号
vllm:num_requests_waiting	Gauge	排队等待的请求数	请求堆积程度
vllm:kv_cache_usage_perc	Gauge	KV Cache 使用百分比	显存瓶颈预警（>0.9 风险）
vllm:prefix_cache_hits	Counter	Prefix Cache 命中数	前缀复用效率
vllm:prefix_cache_queries	Counter	Prefix Cache 查询总数	计算命中率 = hits / queries
vllm:prompt_tokens_total	Counter	累计处理的 Prompt Token 数	总体流量规模
vllm:generation_tokens_total	Counter	累计生成的 Token 数	总体输出量
vllm:request_success_total	Counter	累计成功请求数	服务可用性

⏱ 请求级别指标（Histogram）

Histogram 类型指标提供 _count、_sum 和 _bucket，可按百分位（p50/p90/p99）计算延迟 SLO。

指标名称	含义	典型告警阈值
vllm:time_to_first_token_seconds	首 Token 延迟（TTFT）	p99 > 5s 告警
vllm:inter_token_latency_seconds	Token 间延迟（TPOT）	p99 > 200ms 告警
vllm:e2e_request_latency_seconds	端到端请求延迟	视业务场景
vllm:request_prompt_tokens	每个请求的 Prompt Token 数	超长请求分布
vllm:request_generation_tokens	每个请求的生成 Token 数	max_tokens 分布
vllm:request_prefill_time_seconds	Prefill 阶段耗时	长 Context 场景关注
vllm:request_decode_time_seconds	Decode 阶段耗时	长生成场景关注

🗃 KV Cache 驻留指标

需要 --kv-cache-metrics-sample 参数开启，用于分析缓存效率和内存压力。

指标名称	含义	分析价值
vllm:kv_block_lifetime_seconds	KV Block 从创建到释放的生存时间	缓存压力 & 分页效率
vllm:kv_block_idle_before_evict_seconds	Block 被逐出前的空闲时间	Cache 策略有效性
vllm:kv_block_reuse_gap_seconds	Block 两次复用之间的间隔	前缀复用率

🌐 HTTP 指标

由 prometheus_fastapi_instrumentator 自动采集，反映 API 网关层健康状况。

指标名称	类型	含义
http_requests_total	Counter	HTTP 请求总数（按 method/path/status 分）
http_request_size_bytes	Gauge	请求体大小（按 method/path 分）
http_response_size_bytes	Gauge	响应体大小（按 method/path 分）
http_request_duration_seconds	Histogram	HTTP 请求处理延迟（按 method/path 分）

Prometheus 抓取配置

scrape_configs:
  - job_name: 'vllm'
    scrape_interval: 10s
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: /metrics

Grafana 查询示例

# p99 TTFT
histogram_quantile(0.99,
  rate(vllm:time_to_first_token_seconds_bucket[5m]))

# KV Cache 使用率
vllm:kv_cache_usage_perc

# 请求吞吐量
rate(vllm:request_success_total[5m])

05 · 场景化配置

十一种典型场景及参数选择理由

每个场景说明优化目标、参数选择理由和完整配置。关键在于理解"为什么这样设置"——知其然，更要知其所以然。

一、开发与轻量部署

开发测试

场景 1：小模型单卡（≤7B）

Qwen2.5-7B · Llama-3.1-8B · 单张 A100/RTX 4090

参数选择理由

--gpu-memory-utilization 0.9：保留 10% 显存给模型权重和临时缓冲区。7B 模型权重约 14GB（bf16），KV cache 和其余开销之间需要留出余量，0.9 是稳妥的起点。
--max-num-seqs 64：开发测试场景并发请求量一般不高，64 足以支撑多轮并发测试。调低此值可降低显存压力。
--enable-prefix-caching：开启前缀缓存后，相同 system prompt 的 KV cache 可复用，开发阶段反复测试相同 prompt 时显著减少 Prefill 计算。

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-num-seqs 64 \
  --enable-prefix-caching

✓ 优化目标：低成本快速验证 | ⚠ TP=1 单卡运行，无需设置 tensor-parallel-size

低资源

场景 2：边缘/低资源部署

低显存 GPU · 受限环境 · CPU Offloading

参数选择理由

--gpu-memory-utilization 0.7：仅分配 70% 显存给 KV cache，预留更多空间给模型权重。边缘设备显存有限，宁可降低吞吐也要避免 OOM。
--enforce-eager：禁用 CUDA graph 优化。CUDA graph 需要额外显存来缓存计算图，禁用后以速度换显存，适合显存极度受限场景。
--swap-space 16：将 16GB CPU 内存作为 KV cache 溢出缓冲区。当 GPU 显存不足时将部分 KV cache 换出到 CPU，牺牲速度保可用性。

vllm serve <model> \
  --enforce-eager \
  --gpu-memory-utilization 0.7 \
  --swap-space 16 \
  --max-num-seqs 16

✓ 优化目标：OOM 防护 · 稳定运行 | ⚠ swap 过大可能影响推理速度，需平衡

二、在线推理（延迟敏感）

低延迟

场景 3：延迟敏感—聊天应用

低 QPS · 实时对话 · TTFT 关键

参数选择理由

--speculative-config EAGLE：推测解码用草稿模型快速生成候选 token，目标模型只需验证，减少串行解码步数。低 QPS 场景下草稿模型不会争抢 GPU，收益最显著。
--max-num-batched-tokens 256：限制批次 token 数上限，确保每个请求不必等待队列中其他请求的 token 处理完。值越小，单个请求的首 token 延迟（TTFT）越低。
聊天场景特点是请求到达间隔大（低 QPS），每个请求对响应速度敏感。降低 TP 也有帮助（TP=4 vs TP=8 通信开销更小）。

vllm serve <model> \
  --speculative-config '{
    "method":"eagle",
    "model":"yuhuili/EAGLE-LLaMA3-8B",
    "num_speculative_tokens":3
  }' \
  --max-num-batched-tokens 256 \
  --tensor-parallel-size 4

✓ 优化目标：TTFT ↓ · ITL ↓ | ⚠ 推测解码需要额外草稿模型显存，显存紧张时优先用 N-Gram

生产推理

场景 4：大模型多卡（70B）

Llama-3.1-70B · Qwen2.5-72B · 8×A100/H100

参数选择理由

--tensor-parallel-size 8：70B 模型权重约 140GB（bf16），单张 A100(80GB) 无法容纳。8 卡 TP 将权重切分到每卡约 17.5GB，同时 KV cache 也可分摊到各卡。
--gpu-memory-utilization 0.95：8×80GB 总显存 640GB，预留 5% 给模型权重以外开销已足够。高比值让 KV cache 有更大空间支撑高并发。
--max-num-batched-tokens 8192：兼顾延迟和吞吐的平衡点。低于 8192 则 GPU 利用率不足，高于此值 TTFT 会明显增加。
--dtype bfloat16：A100/H100 原生支持 bf16，相比 fp16 有更好的数值稳定性。fp32 显存翻倍，不推荐。

vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 8 \
  --gpu-memory-utilization 0.95 \
  --max-num-batched-tokens 8192 \
  --dtype bfloat16 \
  --optimization-level 2

✓ 优化目标：高吞吐 · 稳定生产 | ⚠ 确保 8 卡之间使用 NVLink/NVSwitch，避免 PCIe 通信瓶颈

三、批量处理（吞吐优先）

高吞吐

场景 5：吞吐优先—高 QPS 批量推理

批量处理 · 离线推理 · 高并发 API

参数选择理由

--max-num-batched-tokens 16384：大批次让 GPU 计算单元满载。vLLM 的连续批处理在批次足够大时 GPU 利用率从 40% 提升到 90%+。
--enable-chunked-prefill：将长 prompt 切块，与 decode 交错执行，避免单个长 prompt 的 Prefill 阻塞后续 decode。
--gpu-memory-utilization 0.95：尽可能多的显存用于 KV cache，以支持更大的并发批次。

vllm serve <model> \
  --max-num-batched-tokens 16384 \
  --enable-chunked-prefill \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 128 \
  --optimization-level 2

✓ 优化目标：TPS ↑ · GPU 满载 | ⚠ 吞吐提升以增加 TTFT 为代价，不适合实时交互

长上下文

场景 6：长上下文处理

128K 上下文 · 文档分析 · 代码库理解

参数选择理由

--max-model-len 131072：显式设置为 128K。注意 KV cache 随上下文长度线性增长，128K 约消耗 40-80GB 显存（取决于模型）。
--enable-chunked-prefill：长 prompt 的 Prefill 计算量巨大，分块处理避免单次 Prefill 长时间占用 GPU。
--max-num-batched-tokens 4096：长上下文下每个请求本身 token 数就大，批次上限设太高易 OOM。4096 在长序列和 GPU 利用率之间取得平衡。
--block-size 64：大 block 减少 PagedAttention 的内存管理开销。长序列时 block 管理开销显著，64 比默认 16 减少 75% 的管理操作。

vllm serve <model> \
  --max-model-len 131072 \
  --enable-chunked-prefill \
  --max-num-batched-tokens 4096 \
  --block-size 64 \
  --gpu-memory-utilization 0.9

✓ 优化目标：长序列稳定 · 显存控制 | ⚠ 128K 上下文会消耗约 40-80GB 显存（取决于模型大小）

四、MoE 与量化优化

MoE

场景 7：MoE 模型推理

DeepSeek-V3 · Qwen3MoE · Llama-4

参数选择理由

--enable-expert-parallel：将 MoE 层的不同 expert 分配到不同 GPU，每卡只计算其负责的 expert，大幅降低单卡计算量和显存需求。
--tensor-parallel-size 8：将 attention 和 shared expert 等非 MoE 部分用 TP 切分。EP + TP 组合是 MoE 推理的标准做法。

vllm serve deepseek-ai/DeepSeek-V3 \
  --enable-expert-parallel \
  --tensor-parallel-size 8 \
  --gpu-memory-utilization 0.9 \
  --dtype bfloat16

✓ 优化目标：EP 均匀分配 · 高效路由 | ⚠ EP 要求所有 GPU 型号相同，确保 expert 负载均衡

量化部署

场景 8：FP8 量化部署（H100）

H100/H200 专用 · 显存节省 40% · 精度无损

参数选择理由

--quantization fp8：将权重从 bf16 转为 fp8（e4m3），大小减半。H100 的 FP8 Tensor Core 原生支持，计算速度不降反升。精度损失约 0.1-0.5%。
--kv-cache-dtype fp8_e4m3：KV cache 也使用 FP8 存储，进一步减半。e4m3 格式在 LLM 场景下精度表现良好。
--gpu-memory-utilization 0.95：FP8 量化后显存余量更充裕，可以支撑更大的并发批次。

vllm serve <model> \
  --quantization fp8 \
  --kv-cache-dtype fp8_e4m3 \
  --gpu-memory-utilization 0.95 \
  --tensor-parallel-size 8 \
  --dtype bfloat16

✓ 优化目标：显存节省 40% · 精度无损 | ⚠ FP8 量化仅 H100/H200 有原生加速，A100 只能模拟运行

五、分布式推理与缓存加速

分布式

场景 9：多节点大规模推理

16 节点 × 128 GPU · 千卡集群

参数选择理由

--tensor-parallel-size 8：限制在单节点内，利用 NVLink 高速通信。TP 通信密集，跨网络执行会严重降速。
--pipeline-parallel-size 2：PP 跨节点通信量远小于 TP，适合跨机部署。PP=2 将模型层分两段，节点间只需传输中间激活。
--data-parallel-size 8：DP 无通信开销，每个副本独立处理请求。8 个 DP 副本线性扩展吞吐 8 倍。
--distributed-executor-backend ray：多节点必须使用 Ray 作为分布式后端，负责节点发现和任务调度。

vllm serve <model> \
  --tensor-parallel-size 8 \
  --pipeline-parallel-size 2 \
  --data-parallel-size 8 \
  --distributed-executor-backend ray \
  --gpu-memory-utilization 0.9

✓ 总 GPU = 8 × 2 × 8 = 128 | ⚠ 节点间建议使用 InfiniBand，否则 PP 传输可能成为瓶颈

缓存加速

场景 10：LMCache 缓存加速

多轮对话 · RAG 场景 · 有状态推理

参数选择理由

LMCACHE_CONFIG_FILE：指定 LMCache 配置，定义 KV cache 存储后端（GPU/CPU/磁盘/远程）。对话场景优先 GPU 或 CPU 内存以降低读取延迟。
"kv_connector":"LMCacheConnectorV1"：将 KV cache 写入 LMCache 的分布式存储。多轮对话中历史 KV cache 从缓存直接读取，无需重新 Prefill。
3-10x 延迟降低的原因：每轮只有新增 prompt 需要 Prefill，历史 KV cache 从缓存加载。轮次越多，节省越明显。

LMCACHE_CONFIG_FILE=./lmcache.yaml \
vllm serve <model> \
  --kv-transfer-config '{
    "kv_connector":"LMCacheConnectorV1Dynamic",
    "kv_role":"kv_both",
    "kv_connector_module_path":
     "lmcache.integration.vllm.lmcache_connector_v1"
  }'

✓ 优化目标：3-10x 多轮对话延迟降低 | ⚠ 需要安装 lmcache 包并启动 LMCache 服务

六、多模态推理

视觉

场景 11：视觉语言模型

LLaVA · Qwen-VL · Pixtral

参数选择理由

--trust-remote-code：部分模型（包括多模态、新架构模型）的配置中引用了 HuggingFace 仓库内的自定义 Python 代码，如 modeling_llava.py、tokenization_qwen.py 等。transformers 默认禁止执行远程代码以防止安全风险，此参数授权加载。不仅多模态需要，DeepSeek-V3、Qwen2.5 等使用自定义模型架构的也需启用。请确保模型来源可信。
--max-model-len 8192：图像编码后产生大量视觉 token（一张图约 256-1024 tokens），8K 上下文在理解和 token 消耗间取得平衡。
--limit-mm-per-prompt：限制每轮图片/视频数量，防止多张高分辨率图片导致显存爆炸。

vllm serve <model> \
  --trust-remote-code \
  --max-model-len 8192 \
  --limit-mm-per-prompt '{
    "image":5,"video":1
  }' \
  --gpu-memory-utilization 0.9

✓ 优化目标：多模态输入 · 图片理解 | ⚠ 图片分辨率越高，视觉 token 越多，需注意 max-model-len 限制

最佳实践：先单卡测试参数 → 多卡性能调优 → 多节点生产部署，逐步推进。每次只调整 1~2 个参数，观察指标变化后再进行下一步。建议记录每次参数组合的 TTFT、ITL、TPS 指标，用数据驱动决策。

06 · 参数速查

完整参考手册

涵盖单节点、多节点、生态集成的全部核心参数与常用环境变量，快速定位最佳配置。

40+

核心运行参数 + 环境变量

覆盖从显存管理到分布式通信的完整推理栈

单节点推理参数

参数名	默认值	可选值	说明	建议值
`--model`	必需	模型名 / HuggingFace 路径	指定要加载的模型名称或路径	`Qwen/Qwen2.5-7B`
`--gpu-memory-utilization`	`0.9`	`0.0 ~ 1.0`	KV cache 占用 GPU 显存比例	生产 0.9~0.95，OOM 时 0.8
`--tensor-parallel-size`	`1`	偶数，≤ 8	张量并行 GPU 数量	7B=1~2，13~34B=4，70B=8
`--dtype`	`auto`	auto / float16 / bfloat16 / float32	推理数据类型	A100/H100 用 bfloat16
`--max-model-len`	模型默认	int，≤ 模型最大上下文	最大上下文长度（prompt + 生成）	对话 8K，文档 32K~128K
`--max-num-seqs`	动态计算	`16 ~ 256`	批次最大并行序列数	延迟敏感 16~32，吞吐 64~256
`--max-num-batched-tokens`	动态计算	`256 ~ 65536`	批次最大 token 总数	延迟低 256，吞吐高 16384
`--quantization`	None	fp8 / fp8_e4m3 / fp8_e5m2 / awq / gguf / squeezellm	模型权重量化方法	H100 用 fp8，通用用 awq
`--kv-cache-dtype`	auto	auto / fp8_e4m3 / fp8_e5m2	KV cache 存储数据类型	H100+fp8 时用 fp8_e4m3
`--block-size`	`16`	`8 / 16 / 32 / 64`	PagedAttention 内存块大小	GPU 默认 16，CPU 32，长序列 64
`--swap-space`	`4`	int（单位 GB）	KV cache CPU 交换空间	大模型 16~32
`--enforce-eager`	False	flag	禁用 CUDA graph，减少显存	OOM 时启用
`--optimization-level`	`2`	0: 无 / 1: 部分 / 2: 完整(默认) / 3: 激进	优化级别，控制 CUDA graph 和算子融合	默认 2；显存紧张 0；吞吐极致 3
`--enable-prefix-caching`	False	flag	启用自动前缀 KV cache 复用	重复 prompt 场景启用
`--enable-chunked-prefill`	auto	flag	将长 prefill 分块执行，避免阻塞	吞吐优先场景启用
`--seed`	None	int	随机种子，保证可复现性	调试用 42

多节点分布式参数

参数名	默认值	可选值	说明	建议值
`--nnodes`	`1`	int	总节点数。Ray 后端自动检测，仅 mp 后端需显式声明	2~16
`--node-rank`	`0`	`0 ~ nnodes-1`	当前节点编号。Ray 后端自动分配，仅 mp 后端需显式声明	主节点 0，工作节点 1+
`--master-addr`	`localhost`	IP 地址	主节点地址。仅 mp 后端需要，Ray 后端通过 Ray 集群发现	主节点内网 IP
`--master-port`	`2222`	int（端口号）	主节点通信端口。仅 mp 后端需要	默认 2222
`--pipeline-parallel-size`	`1`	int	流水线并行度，跨节点分割层	2~4（跨节点推荐 2）
`--tensor-parallel-size`	`1`	偶数 ≤ 8	张量并行度，单节点内分割权重	8（利用 NVLink）
`--data-parallel-size`	`1`	int	数据并行度，模型副本数	按扩展需求设定
`--distributed-executor-backend`	`ray`	ray / mp	分布式执行器后端	多节点用 ray，单机多卡用 mp
`--headless`	False	flag	工作节点模式（不启动 API 服务）	工作节点必须启用
`--numa-bind`	False	flag	自动绑定 NUMA 节点优化性能	多插槽服务器启用

生态集成参数

参数名	默认值	可选值	说明	建议值
`--kv-transfer-config`	None	JSON 字符串	KV 传输配置：连接器类型、节点角色、缓冲区大小等，完整 JSON 结构见下方	见下方配置详解
`--speculative-config`	None	JSON 字符串	推测解码配置：方法、草稿模型、候选 token 数等，完整 JSON 结构见下方	见下方配置详解
`--enable-expert-parallel`	False	flag	MoE 模型启用专家并行	DeepSeek-V3 等 MoE 模型启用
`--served-model-name`	model 名称	string	API 中暴露的模型名	自定义别名
`--trust-remote-code`	False	flag	信任 HuggingFace 远程自定义代码。安全风险：会执行仓库中的 Python 文件	新架构模型、多模态模型需要
`--limit-mm-per-prompt`	None	JSON	限制每轮多模态输入数量	`{"image":5,"video":1}`
`--host`	`0.0.0.0`	IP 地址	API 服务绑定地址	默认 0.0.0.0
`--port`	`8000`	int	API 服务端口	默认 8000
`--api-server-count`	`1`	int	API 服务器进程数，多进程提高并发	高并发可 ≥ 2
`--log-level`	INFO	DEBUG / INFO / WARNING / ERROR	日志级别	生产 INFO，排查用 DEBUG

--kv-transfer-config 完整 JSON 结构

子字段	类型	必填	说明	可选值 / 示例
`kv_connector`	string	是	KV 传输连接器类型	`LMCacheConnectorV1Dynamic` / `P2pNcclConnector` / `NixlConnector`
`kv_role`	string	是	本节点角色	`kv_producer`(Prefill) / `kv_consumer`(Decode) / `kv_both`
`kv_rank`	int	否	节点逻辑编号（手动指定）	`0`(Prefill) / `1`(Decode)
`kv_connector_module_path`	string	按连接器	自定义连接器的 Python 模块导入路径	`lmcache.integration.vllm.lmcache_connector_v1`
`kv_buffer_size`	string	否	传输缓冲区大小	`1GB` / `2GB` / `512MB`
`kv_rank_override`	int	否	覆盖自动分配的 kv_rank	`0` ~ `N-1`
`kv_ip`	string	Nixl 需要	Nixl 连接的目标 IP	`192.168.1.100`
`kv_port`	int	Nixl 需要	Nixl 连接的目标端口	`12345`

典型配置示例

LMCache 集成（kv_both）

--kv-transfer-config '{
  "kv_connector": "LMCacheConnectorV1Dynamic",
  "kv_role": "kv_both",
  "kv_connector_module_path":
    "lmcache.integration.vllm.lmcache_connector_v1"
}'

分离式 Prefill 节点

--kv-transfer-config '{
  "kv_connector": "P2pNcclConnector",
  "kv_role": "kv_producer",
  "kv_buffer_size": "1GB"
}'

分离式 Decode 节点

--kv-transfer-config '{
  "kv_connector": "NixlConnector",
  "kv_role": "kv_consumer",
  "kv_buffer_size": "2GB",
  "kv_ip": "192.168.1.100",
  "kv_port": 12345
}'

LMCache + PD 分离

LMCACHE_CONFIG_FILE=./lmcache.yaml \
--kv-transfer-config '{
  "kv_connector": "LMCacheConnectorV1Dynamic",
  "kv_role": "kv_producer",
  "kv_connector_module_path":
    "lmcache.integration.vllm.lmcache_connector_v1"
}'

--speculative-config 完整 JSON 结构

子字段	类型	适用方法	说明	可选值 / 示例
`method`	string	全部	推测解码方法	`eagle` / `eagle3` / `pard` / `ngram` / `suffix` / `mtp`
`model`	string	EAGLE/PARD	草稿模型路径或名称	`EAGLE-LLaMA3-8B` / `draft-model-path`
`num_speculative_tokens`	int	全部	每步推测的候选 token 数	`3` ~ `8`，推荐 `5`
`draft_tensor_parallel_size`	int	EAGLE	草稿模型的 TP 度	`1` ~ `8`，默认 1
`prompt_lookup_min`	int	N-Gram	N-Gram 最小匹配长度	`2`
`prompt_lookup_max`	int	N-Gram	N-Gram 最大匹配长度	`5`
`max_draft_len`	int	全部	草稿序列最大长度	`512` ~ `2048`
`spacy_draft`	bool	Suffix	启用 spaCy 句式匹配	`true` / `false`

典型配置示例

EAGLE（需额外草稿模型）

--speculative-config '{
  "method": "eagle",
  "model": "EAGLE-LLaMA3-8B",
  "num_speculative_tokens": 5,
  "draft_tensor_parallel_size": 1
}'

加速比最高（2-3x），需额外显存

N-Gram（无需额外模型）

--speculative-config '{
  "method": "ngram",
  "num_speculative_tokens": 5,
  "prompt_lookup_min": 2,
  "prompt_lookup_max": 5
}'

零额外显存，适合重复性高的场景

MTP（DeepSeek-V3 原生）

--speculative-config '{
  "method": "mtp",
  "num_speculative_tokens": 3
}'

使用模型原生 MTP head，无需额外加载

PARD（并行解码）

--speculative-config '{
  "method": "pard",
  "model": "draft-model",
  "num_speculative_tokens": 5
}'

类似 EAGLE 的并行推测方案

常见问题排查

以下按现象分类，每个问题列出根因、诊断方法和解决方案，由简到繁逐步推进。

💥 显存不足（OOM）

根因：KV cache + 模型权重 + 中间激活超出 GPU 显存总量。

诊断： nvidia-smi 查看显存使用率；vllm:kv_cache_usage_perc 监控指标 > 0.9 触发预警。

解决方案：

第一步：--gpu-memory-utilization 0.8 降低显存占比
第二步：--max-num-seqs 32 减少并发批大小
第三步：--quantization fp8 或 AWQ 量化权重
第四步：--swap-space 16 增加 CPU 交换空间
第五步：--enforce-eager 禁用 CUDA graph（等价 optimization-level 0）
终极：增加 GPU 数，扩大 TP/PP 度分散显存

🐢 延迟过高（TTFT / TPOT）

根因：Prefill 阶段计算量大或 decode 阶段 GPU 利用率不足。

诊断：TTFT 高 → prefill 瓶颈；TPOT 高 → decode 瓶颈。关注 vllm:time_to_first_token_seconds 和 vllm:inter_token_latency_seconds 的 p99 分位。

解决方案：

TTFT 高：--enable-chunked-prefill 将长 prefill 切分；--max-num-batched-tokens 256 限制批大小
TPOT 高：设置 --optimization-level 2 启用 CUDA Graph；--block-size 64 减少 block 管理开销
推测解码：EAGLE 2-3x 加速 decode；N-Gram 零开销方案
减少 TP 度：--tensor-parallel-size 4 → 2（通信开销可能超计算加速收益）
分离式推理：Prefill/Decode 分节点部署，各自独立优化

📉 吞吐过低（TPS）

根因：GPU 利用率不足、批大小过小或 KV cache 复用率低。

诊断：查看 vllm:num_requests_running 是否未达上限；nvidia-smi 检查 GPU 计算/显存利用率 < 80%。

解决方案：

增大批大小：--max-num-batched-tokens 16384 + --max-num-seqs 128
Prefix Cache：--enable-prefix-caching 复用公共前缀（对话历史、System Prompt）
数据并行：--data-parallel-size 4 或 8 横向扩展
优化级别：--optimization-level 2（默认）启用 CUDA Graph + 算子融合
Chunked Prefill：--enable-chunked-prefill 避免 prefill 阻塞 decode
多进程 API：--api-server-count 2 提高 HTTP 并发处理能力

🔗 通信瓶颈（多节点）

根因：跨节点 NCCL 通信时延过高，TP 通信密集放大瓶颈。

诊断：NCCL_DEBUG=TRACE 查看通信拓扑和带宽；nvlink-status 检查 NVLink 连接；ibstatus 检查 InfiniBand 链路。

解决方案：

硬件层：GPUDirect RDMA 直通；Docker 加 --ipc=host --shm-size=16G；启用 InfiniBand
通信层：设置 NCCL_IB_HCA=mlx5_0 指定 IB 网卡；NCCL_NET=IB 强制 IB 协议
策略层：TP ≤ 8 避免跨节点 TP；增大 PP 减少跨节点通信量；优先在同节点内完成 TP
替代方案：用 DP 替代 TP 做横向扩展；EP 对 MoE 模型更高效

📌 快速排查路线

OOM

↓显存占比 → 量化

TTFT 高

chunked prefill ←

TPOT 高

CUDA Graph → EAGLE

TPS 低

增批大小 → DP 扩展

通信慢

RDMA → 减TP → 增PP

vLLM Parameters

为高性能推理而生

GPU 配置 · 内存调度 · 量化

显存与并行

批次与上下文

参数深度解读

量化选项

参数权衡速览

TP · PP · EP · DP

多节点配置（Ray 自动发现节点）

多节点配置（手动指定拓扑）

并行策略选型建议

执行器后端

NCCL 通信调优

LMCache · KV 传输 · 推测解码 · API 生态

Prefill 实例 (vLLM)

Decode 实例 (vLLM)

推测解码 (Speculative Decoding)

OpenAI 兼容 API

平台集成

容器化部署

框架集成

集群管理

Prometheus 指标参考

📊 服务器级别指标

⏱ 请求级别指标（Histogram）

🗃 KV Cache 驻留指标

🌐 HTTP 指标

十一种典型场景及参数选择理由

一、开发与轻量部署

二、在线推理（延迟敏感）

三、批量处理（吞吐优先）

四、MoE 与量化优化

五、分布式推理与缓存加速

六、多模态推理

完整参考手册

核心运行参数 + 环境变量

常见问题排查