以下是 vLLM（特别是 v0.8+ 版本）常用启动参数的详细解释，包括：
- 参数含义
- 典型取值
- 使用场景与好处
- 注意事项
🧠 vLLM 核心参数详解（适用于 OpenAI API Server）
说明：以下参数基于
vllm.entrypoints.openai.api_server启动方式。
1. 模型与基础配置
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--model |
模型路径（Hugging Face 或本地） | /models/Qwen2.5-72B-Instruct |
必填，指定要加载的模型 |
--tokenizer |
自定义 tokenizer 路径（可选） | /models/Qwen2.5-Tokenizer |
当 tokenizer 与 model 分离时使用 |
--trust-remote-code |
允许运行远程代码（如自定义 modeling 文件） | True |
Qwen 系列必须开启，否则加载失败 |
--dtype |
模型计算精度 | half（FP16）、bfloat16、float32 |
FP16 节省显存；A100 可用 bfloat16 提升稳定性 |
--kv-cache-dtype |
KV Cache 存储精度 | auto、fp8、float16 |
非 Hopper GPU 请用 auto；FP8 仅 H100 支持 |
✅ 建议：普通用户用
--dtype half --kv-cache-dtype auto
2. 并行与设备
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--tensor-parallel-size |
张量并行度（GPU 数量） | 8 |
多卡推理必需；将模型权重分到多张 GPU |
--pipeline-parallel-size |
流水线并行（一般不用） | 1 |
大于 1 时用于超大模型（>100B），但增加通信开销 |
--device |
设备类型 | cuda（默认） |
通常无需指定 |
--distributed-executor-backend |
分布式后端 | ray、mp |
默认自动选择；调试时可指定 |
✅ 建议：8 卡就设
--tensor-parallel-size 8
3. 显存与内存管理（关键！）
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--gpu-memory-utilization |
GPU 显存使用上限（0~1） | 0.95 |
避免 OOM；0.9 是安全起点 |
--swap-space |
预留 CPU 内存（GB）用于 KV Cache offload | 4（默认）、1 |
不是硬盘 swap！是 RAM；太小会导致初始化失败 |
--cpu-offload-gb |
将部分模型权重 offload 到 CPU 内存 | 0（默认） |
仅当显存不足时使用；会大幅降低速度 |
--block-size |
PagedAttention 内存块大小 | 16（默认） |
越小越省内存，但调度开销略增 |
⚠️ 注意：
--swap-space=0.5在并发或长上下文下极易失败- 如果你有 8×32G 显存，完全不需要
--cpu-offload-gb
4. 性能与吞吐优化
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--max-num-seqs |
最大并发请求数 | 4 |
控制同时处理的请求数；太高会爆显存 |
--max-num-batched-tokens |
单次批处理最大 token 数 | 32768 |
越高吞吐越好，但需更多显存 |
--enable-chunked-prefill |
启用分块预填充 | True |
支持超长上下文（>32K）必需 |
--enforce-eager |
禁用 CUDA Graph（强制 eager 模式） | False（默认） |
除非调试，否则不要开；会降低吞吐 |
--disable-custom-all-reduce |
禁用自定义 all-reduce 通信 | True |
在某些 NCCL 版本下更稳定（尤其多机） |
✅ 好处举例：
- 开启
--enable-chunked-prefill后，即使 prompt 有 50K tokens 也能处理- 提高
--max-num-batched-tokens可让多个短请求合并执行，提升吞吐 2~5 倍
5. 长上下文与高级功能
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--max-model-len |
模型支持的最大上下文长度 | 32768 |
超过此值会被截断 |
--num-lookahead-slots |
用于 speculative decoding（提前解码） | 2 |
可提升生成速度（需配合 draft model） |
--max-long-partial-prefills |
控制长请求的分块策略 | 1 |
避免长 prompt 阻塞调度器 |
--prefix-caching |
缓存相同前缀的 KV Cache | （v0.8+ 默认启用） | 对重复 system prompt 场景节省显存 |
✅ 好处举例：
--max-model-len 32768+--enable-chunked-prefill→ 支持 32K 上下文--prefix-caching在 chat 场景中可减少 30%+ 显存（相同历史对话）
6. 服务与 API 相关
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--host |
绑定 IP | 0.0.0.0 |
允许外部访问 |
--port |
服务端口 | 8000 |
OpenAI API 默认端口 |
--served-model-name |
返回给客户端的模型名 | "Qwen2.5-72B-Instruct" |
兼容 OpenAI 客户端 |
--uvicorn-log-level |
日志级别 | info、warning |
控制日志输出量 |
7. 调试与稳定性
| 参数 | 含义 | 示例值 | 好处 / 说明 |
|---|---|---|---|
--log-level |
vLLM 内部日志级别 | INFO |
查看 block 分配、显存使用等 |
--disable-frontend-multiprocessing |
禁用前端多进程 | True |
调试时方便查看完整日志 |
🎯 实用配置组合示例
场景 1：8×A10（32G），32GB RAM，跑 Qwen2.5-72B
bash
--tensor-parallel-size 8 \
--dtype half \
--gpu-memory-utilization 0.95 \
--max-model-len 32768 \
--enable-chunked-prefill \
--swap-space 1 \
--max-num-seqs 2 \
--max-num-batched-tokens 32768 \
--disable-custom-all-reduce \
--trust-remote-code✅ 优势：稳定、支持长上下文、不爆内存
场景 2：单卡 A100 80G，追求最高吞吐
bash
--tensor-parallel-size 1 \
--dtype bfloat16 \
--gpu-memory-utilization 0.9 \
--max-num-seqs 16 \
--max-num-batched-tokens 65536 \
--enable-chunked-prefill✅ 优势：高并发、高吞吐，适合 API 服务
场景 3：显存紧张（如 24G 卡跑 70B）
bash
--tensor-parallel-size 4 \
--cpu-offload-gb 10 \
--swap-space 4 \
--max-num-seqs 1⚠️ 代价：速度慢 3~5 倍，仅作兜底方案
🔚 总结
| 类别 | 关键参数 | 推荐做法 |
|---|---|---|
| 模型加载 | --model, --trust-remote-code |
Qwen 必开 trust |
| 显存控制 | --gpu-memory-utilization, --swap-space |
swap ≥1，util ≤0.95 |
| 多卡 | --tensor-parallel-size |
= GPU 数量 |
| 长上下文 | --max-model-len, --enable-chunked-prefill |
必须一起用 |
| 性能 | --max-num-seqs, --max-num-batched-tokens |
根据 RAM/显存调整 |
| 避坑 | --kv-cache-dtype fp8, --cpu-offload-gb |
非 H100 别用 fp8；显存够就别 offload |