模型部署推理框架[3]:引擎启动参数

引擎启动参数全解

  • 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 中验证

  1. 「源码搜索」搜 class CacheConfig,浏览 vllm/config/ 下各子配置类------所有参数一目了然。
  2. 搜 def __post_init__(默认值推导逻辑所在),理解"auto"参数如何变成实际值。
  3. 「API 调试」发 GET /server_info(注意是 GET),把返回里 vllm_config.* 的键与本章表格对上(例如找到 cache_config.num_gpu_blocks 的实际数字,×block_size 就是 KV 池 token 容量)。
  4. 实验:在 .env 的 VLLM_EXTRA_ARGS 加 --no-enable-prefix-caching 重建(docker compose up -d),对比 /server_info 里 enable_prefix_caching 的变化。
相关推荐
缘友一世5 小时前
模型部署推理框架[2]:总体架构和Docker部署实战
vllm
爱笑的k117 天前
nano-vllm 源码剖析:千行 Python 手写离线推理引擎的调度、显存与并行时序
开发语言·python·vllm
code2cat11 天前
【随笔】推理准入控制:请求进来之前,先给KV缓存留出位置
缓存·大语言模型·vllm
code2cat16 天前
【随笔】连续批处理:长短请求怎样在迭代之间补位
java·人工智能·后端·大语言模型·vllm
一枕槐安48717 天前
Qwen 通义千问本地部署与推理服务封装
fastapi·qwen·vllm·流式推理·openai兼容api·awq量化
mumu15717 天前
快速上手大模型推理vllm
人工智能·python·大语言模型·agent·vllm
code2cat18 天前
【随笔】vLLM前缀缓存:相同的开头怎样少算一次
人工智能·python·缓存·vllm
JAI科研22 天前
把一个 Qwen3.8的聊天模型改造成 JEV 决策模型
人工智能·语言模型·自然语言处理·chatgpt·transformer·vllm·sglang
谢白羽23 天前
从传统运维到 AI Infra: K8s 上调度 100 张 GPU踩坑笔记
运维·人工智能·缓存·kubernetes·vllm·sglang·vllm-omni