vllm 启动的参数解释，怎么才能将显存用到极致

vllm显存优化与参数调优指南

原创于 2025-10-14 21:14:07 发布 · 2.1k 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#vllm

最关键的引擎参数（决定并发 & 显存分配）

批处理/并发相关
• --max-num-seqs
同时并行的序列（请求）上限。数值越大，并发越高，但需要更多 KV Cache 显存。和下一项共同决定批量大小。
• --max-num-batched-tokens
预填充（prefill）阶段单批可打包的 prompt token 上限；数值越大，prefill 吞吐越高，但占用更多显存与瞬时算力。官方调优文档建议基线是 2048，提升它通常能显著提高吞吐。

显存总盘子
• --gpu-memory-utilization
vLLM 预留给“模型执行器（权重 + 激活 + KV Cache）”的显存比例（01，默认 0.9）。想“吃满”显存，就把它调到稳定上限（例如 0.90.95，视你的卡与驱动而定）。

上下文长度
• --max-model-len
本实例支持的最大上下文窗口。越大=每个请求的 KV Cache 越大。如果业务不需要超长上下文，把它下调能显著腾出显存给并发。（经验：很多 8B/32B 模型设 8k/16k 就够用，长文档另开“长上下文实例”）

并行切分
• --tensor-parallel-size
张量并行，把同一个模型切到多张 GPU 上；适用于大模型“装不下单卡”的场景，或想用更多显存提升并发。注意 TP 会引入跨卡通信开销，规模太大时反而影响延迟。

为什么这些参数影响“能同时处理多少个请求”？
本质是 PagedAttention 把各请求的 KV Cache 分页管理，批调度 + 页表映射让显存碎片最小化并发最大化；因此“批量大小（上两项）+ 显存比例（上一项）+ 上下文长度”共同决定并发上限。

⸻

其他常用/重要参数（按主题）

模型装载
• --model（HF 名称或本地路径）、–revision、–trust-remote-code、–download-dir
指定模型与版本、是否信任自定义代码、下载缓存目录。
• --dtype（auto/float16/bfloat16/fp8…）
推理精度选择。bf16 稳定性好；fp8/量化能显著省权重显存，但KV Cache 仍常用 FP16/BF16（KV 低比特是活跃议题但不总是默认/稳定）。
• --tokenizer, --tokenizer-revision, --tokenizer-mode
指定/加速分词器。

服务端（OpenAI 兼容）
• --host, --port, --served-model-name（可多名别名）
起一个 OpenAI 兼容 HTTP 服务，客户端按 OpenAI SDK 直连即可。更多 server 级参数参见 vllm serve --help/Server Args 文档。
• --api-server-count
起多个 API 前端进程，对 Encoder/Embedding 这类“非自回归”模型的并发有时更有效（社区反馈）。

调度/时延优化
• --enable-chunked-prefill
让长 prompt 的预填充分块交错执行，减轻“队头阻塞”。
• --num-scheduler-steps
调度器每次可调度步数；适当增大可提升吞吐，但可能拉高尾延迟。（见社区案例）

观测与指标
• /metrics（Prometheus）导出：
可看到 vllm_running_requests、vllm_waiting_requests、vllm_gpu_memory_usage_bytes 等，直接用来判断是否“顶满”。

⸻

“显存吃满”的两套实战配置

目标：在稳定前提下尽可能把显存用于 KV Cache 与批处理，提升吞吐/并发。下面给出两套“可抄作业”的思路，你可据机型/模型微调。

A) 吞吐优先（批大、压榨显存）

vllm serve /root/models/qwen3 \
  --host 0.0.0.0 --port 8000 \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.92 \
  --max-model-len 8192 \
  --max-num-batched-tokens 65536 \
  --max-num-seqs 512 \
  --enable-chunked-prefill \
  --served-model-name qwen3

调参逻辑：
• 把 gpu-memory-utilization 顶到 0.9+ 的稳定上限；
• 将 max-num-batched-tokens 大幅提高（如 32k/64k）以抬高 prefill 吞吐；
• 视卡/驱动把 max-num-seqs 拉到 256/512，观察 /metrics 的 waiting 是否下降；
• 把 max-model-len 设为够用的就行（8k/16k），给并发腾显存。

B) 时延优先（低抖动、首 Token 更快）

vllm serve /root/models/qwen3 \
  --host 0.0.0.0 --port 8000 \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.88 \
  --max-model-len 8192 \
  --max-num-batched-tokens 4096 \
  --max-num-seqs 128 \
  --served-model-name qwen3

调参逻辑：
• 降低 max-num-batched-tokens，减轻预填充“巨批”的排队；
• 降低 max-num-seqs，让 decode 阶段更平滑；
• gpu-memory-utilization 稍微收一档，提高稳定余量。

⸻

量化/并行的取舍要点
• 量化（AWQ/GPTQ/FP8/Marlin 等）能显著降低权重显存，让你把省下的空间给 max-num-seqs 与 max-num-batched-tokens，通常能换来更高并发。但KV Cache 仍占大头（和上下文长度线性相关），量化对 KV 的节省有限（KV 低比特仍在推进/探索）。
• TP（张量并行）越大，单实例可用总显存越多、可承载更大批/更长上下文，但跨卡通信变多；如果模型本来就很小，反而考虑多副本（数据并行/多进程） + 负载均衡提升整体吞吐。

⸻

观测与压测：确定“真的吃满了”
• 看日志或 /metrics：
running_requests / waiting_requests、gpu_memory_usage_bytes、gpu_cache_usage_perc； waiting 长期 >0 说明还可加大批/并发或开副本。
• 压测：
用 hey/wrk/k6 持续增大并发，记录首 token 延迟（TTFT）、每秒 tokens、错误率（出现 Server busy、OOM 就退一步）。社区在 encoder/embedding 场景还会调 --api-server-count 以提升并行度。

⸻

两条“省显存→提并发”的黄金法则
1. 缩短上下文：把 --max-model-len 调到业务需要值即可，KV Cache ∝ 上下文长度，省下来的就是并发位。
2. 批得更聪明：先把 --max-num-batched-tokens 拉高，再用 --max-num-seqs 填满“decode 并行度”，最后把 --gpu-memory-utilization 往上顶到稳定边缘。

⸻

兼容/平台小贴士
• OpenAI 兼容启动与参数总览见 vLLM CLI/Server Args 文档；不确定时跑 vllm serve --help。
• Ascend/TPU/其它 xPU：不同后端对参数支持略有差异（例如某些并行/调度项），以对应后端/发行版文档与 issue 说明为准。
• **KV Cache CPU Offload（老版本特性）**在 v1 路线基本弃用；不要指望它解决吃满问题，直接在 GPU 侧做批和上下文的取舍更有效。