vllm serve 的作用
vllm serve 是 vLLM 的统一服务入口，一条命令拉起 OpenAI 兼容的 HTTP 服务。它的参数可以归成四组：显存预算、并行切分、上下文与批处理上限、量化与精度。调参的本质是在「装得下模型」「扛得住并发」「单请求足够快」三者之间做取舍，改任何一项都要回到这三个目标复核。
基本信息
| 适用版本 | 较新版本统一为 vllm serve，旧版走 python -m 入口 |
|---|---|
| 默认端口 | 8000 |
| 必需输入 | Hugging Face 模型名或本地权重目录 |
| 参数查询 | vllm serve --help（以本机版本为准） |
典型启动命令
典型启动命令
# 两卡张量并行、九成显存预算、8K 上下文、指定对外模型名
vllm serve /models/Qwen --host 0.0.0.0 --port 8000 \
--tensor-parallel-size 2 --gpu-memory-utilization 0.9 \
--max-model-len 8192 --served-model-name my-model
# 排查启动失败：先关 CUDA Graph 换取可读报错，再逐步加回
vllm serve /models/Qwen --enforce-eager --max-model-len 4096常用参数
| 参数 | 作用与取舍 |
|---|---|
| --tensor-parallel-size | 张量并行卡数，把权重与 KV 按卡切分；卡数越多通信开销越大 |
| --pipeline-parallel-size | 流水并行层数，跨机切层，常用于单机放不下的超大模型 |
| --gpu-memory-utilization | 引擎可用显存比例，直接决定 KV 池大小，过高更早 OOM |
| --max-model-len | 单请求上下文上限，KV 池按此预留，不要随手写大 |
| --max-num-seqs | 单批最大并发序列数，限制同时在处理的请求数量 |
| --max-num-batched-tokens | 单批 token 总预算，预填充与解码共享这份预算 |
| --quantization | 量化内核（awq / gptq / fp8 等），必须与权重格式匹配 |
| --kv-cache-dtype | KV 缓存精度，选 fp8 可省显存但要回归输出质量 |
| --served-model-name | 对外暴露的模型名，客户端 model 字段填这个 |
| --enable-prefix-caching | 复用相同前缀的 KV，多轮对话与固定系统提示收益明显 |
| --api-key | 简易密钥校验，只能兜底，生产仍需网关统一鉴权 |
参数以本机 vllm serve --help 为准：默认值随版本变化，尤其并发与批 token 上限，照抄旧文容易得到与预期不同的并发表现。
--gpu-memory-utilization 拉到 0.95 以上会挤压 KV 池：短上下文压测看不出异常，长上下文并发时更早出现排队与 OOM，通常留一成余量。
启动日志会打印 KV 池可容纳的块数与 token 数，这是判断「还能不能加压」的第一手数据，比事后翻监控猜显存更可靠。
关闭图捕获（--enforce-eager）能让报错更早、更可读，代价是损失一部分吞吐与首 token 延迟表现：排查阶段可以开，长期运行要恢复。
启动日志读法
| 日志项 | 含义 |
|---|---|
| max_model_len | 实际生效的上下文上限，与命令行是否一致要核对 |
| KV cache blocks | KV 池可容纳的块数，直接决定并发 token 总量 |
| Maximum concurrency | 按当前配置推算的并发请求上限，用作压测起点 |
| tensor parallel size | 并行配置是否按预期生效，多卡时重点核对 |
| 模型加载耗时 | 权重读取与初始化时间，影响扩容切流速度 |
多实例部署要给每个实例显式指定端口，并把监听地址限制为环回或内网：端口冲突与地址意外暴露是两个最常见的事故来源。
调参顺序
- 先定装得下：只调 --max-model-len 与量化档位，确认模型能加载并跑通一次请求，此刻不看并发
- 再定并发：在目标上下文长度下加压，观察 KV 池水位与排队请求数，据此调 --max-num-seqs
- 后定延迟：批预算偏大时首 token 延迟上升，用 --max-num-batched-tokens 往回收
- 再算成本：记录稳定态吞吐，换算每百万 token 成本，与云 API 报价横向比较
- 最后定基线：把最终参数、权重版本与压测结果一起存档，作为下次发布的回归对标