引擎启动参数全解
- vLLM 的全部参数定义在
vllm/config/(各子配置类)与vllm/engine/arg_utils.py,支持vllm serve --config config.yaml文件化。 - 本章按"调什么、为什么、本机建议值"讲最常用的 40+ 个,其余学会用
--help+ explorer 查。 - CLI 帮助按配置组组织:不再一屏甩出 200+ 个参数,而是按「配置组」(ModelConfig / ParallelConfig / CacheConfig / ...)组织,支持按组、按单个 flag 精确查询。
文章目录
-
- [0. 参数的四个观察方法](#0. 参数的四个观察方法)
- [1. 网络与服务](#1. 网络与服务)
- [2. 模型与分词](#2. 模型与分词)
- [3. 显存与调度(性能调优核心)](#3. 显存与调度(性能调优核心))
- [4. 并行](#4. 并行)
- [5. 加速开关(默认值要记牢)](#5. 加速开关(默认值要记牢))
- [6. 推理特性开关](#6. 推理特性开关)
- [7. 本机推荐起手配置(双 3090 + Qwen3-8B)](#7. 本机推荐起手配置(双 3090 + Qwen3-8B))
- [7.5 启动加速三件套(生产与学习都受益)](#7.5 启动加速三件套(生产与学习都受益))
- [8. 环境变量 Top 10](#8. 环境变量 Top 10)
- [9. 在 explorer 中验证](#9. 在 explorer 中验证)
-
学习仓库:kill-life/vllm-learn
0. 参数的四个观察方法
bash
# 1) 官方文档参数大全(最权威)
open https://docs.vllm.ai/en/stable/configuration/engine_args.html # 参数大全在 configuration/ 路径下
# 2) CLI 自带帮助(容器内)------支持分段查询:
vllm serve --help # 默认只列"常用 + 配置组目录",不再刷屏
vllm serve --help=all # 全量参数(等价旧版 --help)
vllm serve --help=ModelConfig # 按配置组查(组名大小写不敏感)
vllm serve --help=kv-cache-dtype # 按单个 flag 查(_ 与 - 通用)
# 3) 服务运行时看"实际生效值"(含默认值推导结果)
curl -s http://127.0.0.1:8000/server_info | python3 -m json.tool
# 4) 排障时收集环境指纹(提 issue 前必跑)
vllm collect-env
🔧 explorer「API 调试」有
GET /server_info预置项,「服务端参数字典」页还有全字段中文释义。改参数重启后,对比server_info是验证生效的标准手段。
1. 网络与服务
| 参数 | 默认 | 说明与本机建议 |
|---|---|---|
--host |
0.0.0.0 | compose 已显式设置 |
--port |
8000 | vLLM 约定俗成端口 |
--api-key |
None | 生产必加;学习环境不加 |
--served-model-name |
模型路径 | 对外暴露的 model id。不设它时客户端必须传完整路径 ,只写短名会 404(The model \qwen3.5-4B` does not exist);本项目 .env.example默认--served-model-name qwen3.5-4B`,换模型要同步改 |
--api-server-count |
1 | 值得开 :>1 时每个连接路由到最空闲的 API worker,短请求 req/s 提升明显;学习机 2 卡 8B 可试 2 |
--allowed-origins |
无 | 默认 CORS 不放行任何来源;浏览器跨域直连 API 必须显式列出来源,如 --allowed-origins http://127.0.0.1:18082 |
--sse-keep-alive-interval |
--- | SSE 流式长连接的保活间隔(弱网/长思考模型防断连) |
--disable-log-stats |
False(开指标) | 关掉后 /metrics 与运行日志停更,别加 |
--enable-log-requests / --no-enable-log-requests |
off | 记录请求内容(排障利器,合规注意) |
--otlp-traces-endpoint |
--- | 设置后启用 OpenTelemetry 追踪 |
--grpc-port |
--- | Rust 前端,另开 gRPC 端口(高并发场景) |
2. 模型与分词
| 参数 | 默认 | 说明 |
|---|---|---|
| 位置参数 | 必填 | HF hub 名或本地路径 |
--runner |
auto | 运行器类型:generate(生成)/ pooling(嵌入、重排、分类)/ draft。池化模型(嵌入/重排)用它显式声明,嵌入模型教程见 20 |
--dtype |
auto | auto=按 config;AWQ 老模型有时需 half |
--trust-remote-code |
False | 自定义建模代码的模型需要(如 jina-embeddings-v5) |
--hf-overrides |
--- | 以 JSON 覆盖 HF config 字段,不下载额外权重(如 jina-v5 切任务适配器 --hf-overrides '{"jina_task": "retrieval"}',教程 20) |
--max-model-len |
按 config | 上下文长度上限;KV 池放不下会启动失败并给出提示,小显存学会主动调小 |
--limit-mm-per-prompt |
--- | 限制每个 prompt 的多模态输入(如 '{"image": 1, "video": 0}'),EmbeddingGemma2 等多模态模型靠它跳过不用的模态编码器省显存 |
--chat-template |
None | 覆盖 tokenizer 内置模板(模型不讲人话时先查这里) |
--tokenizer-mode |
auto | mistral 等特殊分词器时改 |
--load-format |
auto | dummy 随机权重用于结构实验 |
--generation-config |
auto | 读取模型 generation_config 作为采样默认值 |
3. 显存与调度(性能调优核心)
| 参数 | 默认 | 说明与本机建议 |
|---|---|---|
--gpu-memory-utilization |
1.0(v0.34 起,extensible KV cache 默认开启) | 旧版按比例估算显存,v0.34 改按 warmup 后实际空闲显存分配 KV。一般不要显式设置 ;与其它进程共享显存时才降到 0.85~0.88。要退回旧式固定比例预留,需同时加 --disable-extensible-kv-cache(本机实测:0.85 + disable 时 KV 容量 198,982 tokens,extensible 默认 238,873) |
--max-num-seqs |
1024(探推导出) | 单步批内序列上限 = decode 并发上限;OOM 在 decode 报错时降它 |
--max-num-active-seqs |
--- | 与 max-num-seqs 区分的"活跃序列"上限(配合准入控制精细限流) |
--max-num-queued-reqs / --max-num-queued-tokens |
--- | 排队请求/排队 token 上限(背压控制,防止长 prompt 把队列拖垮) |
--max-num-batched-tokens |
8192(探推导出) | 单步批 token 预算;chunked prefill 的块大小也随之确定 |
--enable-chunked-prefill |
默认开 | 长 prompt 切块与 decode 交错;保 decode 时延的关键 |
--long-prefill-token-threshold-adaptive |
--- | 按负载自适应调整长 prefill 切块阈值(高并发下 TTFT 更稳) |
--block-size |
64(v0.34 起,原 16) | KV 分页块大小(token/块);混合注意力(Mamba/GDN)模型按模型页大小推导,本机 Qwen3.5-4B 实测解析为 576 |
--attention-backend |
auto | attention 后端(FlashAttention/FlashInfer/Triton...按硬件自动选,3090 用 FA2/FlashInfer 系) |
--kv-cache-dtype |
auto | 取值包括 fp8/fp8_per_token_head/int8_per_token_head/int4_per_token_head/nvfp4/nvfp4_4over6/turboquant_*/ultraquant_4bit。NVFP4 KV 可用于 SM8x(3090/4090),消费卡也能压 KV 显存 |
--kv-cache-dtype-skip-layers |
\[\] | 按层号/注意力类型跳过 KV 量化(个别层敏感时) |
--prefix-cache-retention-interval |
--- | 前缀缓存块保留策略(长会话/多轮场景调优) |
--enforce-eager |
False | 禁 CUDA Graph(排障/省显存时用,吞吐下降) |
调参口诀:
bash
启动日志 GPU KV cache size: XXX tokens ------ 和业务需求比:
够用且有余 ✓ 合适
提示 KV cache 放不下 max-model-len → 降 --max-model-len 或升 gpu-memory-utilization
prefill 阶段 OOM → --max-num-batched-tokens 降到 4096/2048
decode 阶段 OOM → --max-num-seqs 降档 或 gpu-memory-utilization 0.8
preemption(vllm:num_preemptions)频繁 → 降 max-num-seqs / max-model-len / 并发
4. 并行
| 参数 | 默认 | 说明 |
|---|---|---|
--tensor-parallel-size |
1 | 张量并行:权重按层内切开,双卡 8B 用 2 |
--pipeline-parallel-size |
1 | 流水线并行(按层深切) |
--data-parallel-size |
1 | 数据并行副本数(配合 external LB 或内置协调器) |
--enable-expert-parallel |
False | MoE 专家并行 |
--distributed-executor-backend |
auto | mp(多进程,默认)/ ray / uni |
--disable-custom-all-reduce |
False | 消费级双卡 P2P 异常时的排障开关 |
5. 加速开关(默认值要记牢)
| 参数 | 默认 | 说明 |
|---|---|---|
--enable-prefix-caching |
v1 默认开 | 关闭用 --no-enable-prefix-caching(对照实验常用) |
| chunked prefill | 默认开 | - |
| CUDA Graph(cudagraph 模式) | 默认 FULL/PIECEWISE | --compilation-config '{"cudagraph_mode": ...}' 细调 |
--compilation-config |
- | torch.compile 级别/模式(JSON 串,进阶);含 STOCK_TORCH_COMPILE 模式(MRV2) |
--enable-shm-tensor-arena |
默认开 | 共享内存 tensor arena:多模态大张量广播给 worker 只拷一份,省显存/加速启动(默认开启,通常不用管) |
--enable-flash-late-interaction |
True | ColBERT/ColPali 类 late-interaction 打分用 GPU 融合 MaxSim 内核(嵌入/重排模型吞吐关键) |
6. 推理特性开关
| 参数 | 说明 |
|---|---|
--enable-auto-tool-choice |
打开工具调用解析(必须配 --tool-call-parser) |
--tool-call-parser |
按模型选解析器(本项目默认 qwen3_xml:Qwen3.5-4B 输出 XML 风格工具调用;hermes 只认 JSON 风格,配错时 tool_calls=null)。另支持 hf:直接读 checkpoint 的 response_template,带该字段的模型免专用解析器(教程 08/21) |
--reasoning-parser |
推理模型把 <think> 内容分离到 reasoning_content;同样支持 hf(读 response_template) |
--tool-strict-level |
工具参数越界时的严格度(报错/钳制/忽略) |
--enable-lora --max-lora-rank 64 |
LoRA 适配器支持(/v1/load_lora_adapter 热加载) |
--speculative-config '{"method":"mtp","num_speculative_tokens":2}' |
推测解码(JSON 配置)。本项目默认 MTP(模型自带 MTP 头,实测 C=1 +83% / C=16 +40%);无 MTP 头的模型可用 ngram;ngram 还可用 GPU n-gram 投机器(变长 draft) |
--kv-transfer-config |
KV 传输连接器(LMCache/PD 分离) |
--enable-scale-out |
跨机 scale-out 服务(多机横向扩展入口) |
7. 本机推荐起手配置(双 3090 + Qwen3-8B)
bash
VLLM_MODEL=Qwen/Qwen3-8B
VLLM_EXTRA_ARGS="--tensor-parallel-size 2 --gpu-memory-utilization 0.88 --max-model-len 32768 --enable-prefix-caching"
7.5 启动加速三件套(生产与学习都受益)
- 启动慢可以拆成三个可独立优化的环节,对应三条命令:
| 环节 | 工具 | 说明 |
|---|---|---|
| 内核下载/编译 | vllm download-kernels |
预装 FlashInfer 预编译内核(--dry-run 先看清单),免掉首次启动时的下载/JIT 编译,冷启动明显变快 |
| 权重加载 + autotune | vllm preload --model <model> |
启动常驻权重缓存 daemon(每 GPU 一个),量化后权重留在 GPU 显存,后续引擎经 CUDA IPC 直接取;--preload-autotune 还会把 FlashInfer autotune 表保温,重启容器免重编译 autotune |
| 整引擎快照 | vllm snapshot create/inspect/restore |
TP=1 引擎初始化完成后打快照,restore 同机秒级恢复------A/B 对比参数、教学演示时反复重启不再等权重加载 |
配套:--sleep-mode-offload-cudagraph(sleep 时把 CUDA Graph 也卸到 CPU,省更多显存)、--sleep-preserve-parameter-names(sleep 时保留指定参数,如 draft.*)。
8. 环境变量 Top 10
| 变量 | 默认 | 用途 |
|---|---|---|
VLLM_CACHE_ROOT |
~/.cache/vllm | 编译缓存根(做卷持久化) |
VLLM_SERVER_DEV_MODE |
0 | 开启 dev 端点 :/server_info、/reset_prefix_cache、/sleep、/start_profile 等------本项目默认 =1(学习环境),生产必须关 |
HF_ENDPOINT |
--- | HF 镜像(本项目已设 hf-mirror.com) |
CUDA_VISIBLE_DEVICES |
--- | 限定可见 GPU(PD 分离/单卡实验) |
VLLM_LOGGING_LEVEL |
INFO | 排障时 DEBUG |
VLLM_LOG_STATS_INTERVAL |
10s | 运行日志打印间隔 |
VLLM_WORKER_MULTIPROC_METHOD |
fork | worker 启动方式 |
VLLM_ENABLE_V1_MULTIPROCESSING |
1 | EngineCore 是否独立进程(0 = 同进程,方便打断点,教程 05) |
VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS |
1 | 显存画像是否估算 CUDA Graph 占用(启动日志会给出等效 gpu-memory-utilization 换算) |
VLLM_CHAT_TEMPLATE_RENDER_TIMEOUT |
--- | chat template 渲染超时上限,防模板注入耗尽资源(GHSA-4hhp) |
VLLM_P2P_MAX_PEERS / VLLM_P2P_HANDSHAKE_TIMEOUT_S |
128 / 30 | P2P ZMQ 对端上限与超时,防 socket 耗尽(GHSA-frvg) |
VLLM_BATCH_INVARIANT |
0 | =1 时强制 batch 不变性(同输入不同 batch 结果一致,RL/可复现研究用) |
VLLM_USE_V1(V0/V1 切换)、VLLM_ATTENTION_BACKEND、VLLM_TORCH_PROFILER_DIR等旧环境变量已不存在;后端切换用--attention-backend,profiler 目录用--profiler-config '{"torch_profiler_dir": "..."}'。依赖与运行时:
transformers>=5.16.1,<5.23.0、tokenizers>=0.23.3、Python ≥3.11(镜像为 3.12)。
9. 在 explorer 中验证
- 「源码搜索」搜
class CacheConfig,浏览vllm/config/下各子配置类------所有参数一目了然。 - 搜
def __post_init__(默认值推导逻辑所在),理解"auto"参数如何变成实际值。 - 「API 调试」发
GET /server_info(注意是 GET),把返回里vllm_config.*的键与本章表格对上(例如找到cache_config.num_gpu_blocks的实际数字,×block_size就是 KV 池 token 容量)。 - 实验:在
.env的VLLM_EXTRA_ARGS加--no-enable-prefix-caching重建(docker compose up -d),对比/server_info里enable_prefix_caching的变化。