vLLM 0.19.0+6bc3197f 启动参数完整中文手册

容器基础信息

项	内容
NVIDIA Release	26.04 (build 299333414)
vLLM 版本	0.19.0+6bc3197f
版权	2026 NVIDIA CORPORATION & AFFILIATES
许可协议	NVIDIA 企业软件许可协议 + AI 产品专项条款
CUDA 兼容模式	已开启；容器CUDA 13.2，宿主机驱动595.58.03，内核驱动580.159.03
SHMEM 警告	默认64MB共享内存不足，推荐docker启动参数：--gpus all --ipc=host --ulimit memlock=-1 --ulimit stack=67108864

通用基础参数（顶层无分组参数）

参数	类型/默认值	说明
model_tag	位置参数，默认Qwen/Qwen3-0.6B	待部署模型名称/本地路径
--aggregate-engine-logging	bool，False	多数据并行时输出聚合统计日志，而非每个引擎单独日志
--api-server-count / -asc	int，None	API服务进程数量；未指定时等于data_parallel_size
--config	yaml路径，None	从YAML文件读取全部启动参数
--disable-log-stats	bool，False	关闭运行统计日志输出
--enable-log-requests	bool，False	开启请求日志；INFO打印请求ID/参数/LoRA；DEBUG打印完整Prompt；日志级别由VLLM_LOGGING_LEVEL控制
--fail-on-environ-validation	bool，False	环境校验失败时直接抛出异常退出
--gdn-prefill-backend	flashinfer/triton，None	指定GDN预计算后端
--grpc	bool，False	启用gRPC服务替代HTTP OpenAI接口；需额外安装vllm[grpc]
--headless	bool，False	无头模式，多用于多节点数据并行从属节点
--shutdown-timeout	int，0	服务优雅关闭超时秒数；0=强制终止，大于0=等待请求处理完成
-h / --help	-	查看帮助；支持分段查看：--help=分组名，--help=all查看全部

分模块参数表格

一、Frontend 前端服务（OpenAI兼容接口）

参数	默认值	说明
--allow-credentials	False	允许跨域携带凭证Cookie
--allowed-headers	['*']	CORS允许的请求头列表，逗号分隔
--allowed-methods	['*']	CORS允许的HTTP方法
--allowed-origins	['*']	CORS允许的来源域名
--api-key	None	接口鉴权密钥，支持多密钥空格传入
--chat-template	None	自定义对话模板文件路径
--chat-template-content-format	auto	对话模板内容格式：auto/openai/string
--default-chat-template-kwargs	None	对话模板默认入参，支持JSON字符串或分开传参
--disable-access-log-for-endpoints	None	屏蔽指定接口的访问日志，示例/health,/metrics
--disable-fastapi-docs	False	关闭Swagger、ReDoc、OpenAPI文档页面
--disable-uvicorn-access-log	False	完全关闭uvicorn访问日志
--enable-auto-tool-choice	False	自动识别工具调用格式
--enable-force-include-usage	False	强制返回token用量统计
--enable-log-deltas	False	日志输出指标增量差值
--enable-log-outputs	False	日志打印模型输出文本
--enable-offline-docs	False	离线内置静态文档，适用于无外网环境
--enable-prompt-tokens-details	False	返回Prompt分词详细信息
--enable-request-id-headers	False	响应头携带X-Request-Id
--enable-server-load-tracking	False	开启服务负载监控统计
--enable-ssl-refresh	False	证书文件变更时自动重载SSL上下文
--enable-tokenizer-info-endpoint	False	开放Tokenizer信息查询接口
--exclude-tools-when-tool-choice-none	False	tool_choice为none时过滤工具定义
--h11-max-header-count	256	单请求最大HTTP请求头数量，防攻击
--h11-max-incomplete-event-size	4194304 (4MB)	单条未完成HTTP报文最大字节限制
--host	None	服务监听地址，默认0.0.0.0
--log-config-file	None	自定义日志配置文件路径
--log-error-stack	False	异常时打印完整堆栈日志
--lora-modules	None	预加载LoRA适配器列表
--max-log-len	None	日志文本最大截断长度
--middleware	[]	自定义ASGI中间件导入路径，可多次传入
--port	8000	HTTP服务监听端口
--response-role	None	自定义模型回复role字段值
--return-tokens-as-token-ids	False	接口返回原始token ID而非文本
--root-path	None	反向代理路径前缀，如/vllm
--ssl-ca-certs	None	SSL根证书路径
--ssl-cert-reqs	0	客户端证书校验策略（Python ssl标准参数）
--ssl-certfile	None	HTTPS证书文件路径
--ssl-ciphers	None	TLS加密套件（仅TLS1.2及以下生效）
--ssl-keyfile	None	HTTPS私钥文件路径
--tokens-only	False	仅返回token计数，不返回文本内容
--tool-call-parser	openai	工具调用解析器，支持qwen3_xml/llama4_json等几十种模型专用解析器
--tool-parser-plugin	None	自定义工具解析器插件路径
--tool-server	None	远程工具服务地址
--trust-request-chat-template	False	信任客户端请求内传入的对话模板
--uds	None	Unix域套接字路径；设置后忽略host/port
--uvicorn-log-level	info	Web服务日志级别：critical/debug/error/info/trace/warning

二、ModelConfig 模型加载与推理基础配置

参数	默认值	说明
--allow-deprecated-quantization	False	允许使用已废弃量化方案
--allowed-local-media-path	空	允许接口读取服务器本地图片/视频目录，存在安全风险
--allowed-media-domains	None	仅允许指定域名的远程多媒体链接输入
--code-revision	None	HuggingFace模型代码分支/tag/commit
--config-format	auto	模型配置读取格式：auto/hf/mistral
--convert	auto	模型适配类型：auto/classify/embed/none，用于文本模型转向量分类模型
--disable-cascade-attn	True	禁用V1级联注意力；关闭可规避数值精度问题，开启自动择优启用
--disable-sliding-window	False	关闭滑动窗口注意力机制
--dtype	auto	权重与激活精度：auto/bfloat16/float16/float32/half
--enable-prompt-embeds	False	允许传入预计算embedding输入，仅可信环境开启
--enable-return-routed-experts	False	MoE模型返回路由专家信息
--enable-sleep-mode	False	引擎休眠模式，仅CUDA/HIP支持
--enforce-eager	False	强制禁用CUDA Graph，全程PyTorch eager执行
--generation-config	auto	生成配置文件夹路径；auto从模型加载，vllm使用内置默认
--hf-config-path	None	自定义HuggingFace config.json路径
--hf-overrides	{}	覆盖模型配置字典，JSON格式传入
--hf-token	None	HF访问令牌，True读取本地登录缓存token
--io-processor-plugin	None	自定义输入输出处理器插件
--logits-processors	None	自定义logit后处理类全路径，多值空格分隔
--logprobs-mode	raw_logprobs	返回概率计算基准：原始logit/处理后logit/原始logprob/处理后logprob
--max-logprobs	20	单次返回top-k token概率上限，-1无限制（易OOM）
--max-model-len	None	模型上下文总长；支持1k/25.6k简写，auto自动适配显存
--model	Qwen/Qwen3-0.6B	模型名称/本地路径
--model-impl	auto	模型执行后端：auto/vllm/transformers/terratorch
--override-attention-dtype	None	强制覆盖注意力计算精度
--override-generation-config	{}	运行时覆盖生成参数，JSON合并模型配置
--pooler-config	None	向量模型池化层配置，JSON传入
--quantization / -q	None	权重量化方式，自动读取模型quantization_config
--renderer-num-workers	1	异步分词、对话模板渲染、多模态预处理线程数
--revision	None	模型权重版本分支/tag/commit
--runner	auto	任务类型：auto/draft/generate/pooling（生成/草稿/向量）
--seed	0	全局随机种子，保证多TP/GPU采样一致性
--served-model-name	None	API对外暴露的模型名，支持多别名
--skip-tokenizer-init	False	跳过分词器初始化，客户端直接传入token_ids
--tokenizer	None	独立分词器路径，不跟随model参数
--tokenizer-mode	auto	分词器类型：hf/slow/mistral/deepseek_v32/qwen_vl等
--tokenizer-revision	None	分词器单独指定版本
--trust-remote-code	False	信任HF远程自定义代码（部分模型必须开启）

三、LoadConfig 权重加载配置

参数	默认值	说明
--download-dir	None	模型缓存下载目录，默认HF缓存
--ignore-patterns	['original/*/']	加载时忽略的文件通配符，默认跳过LLaMA原始checkpoint
--load-format	auto	权重加载格式：safetensors/pt/gguf/instanttensor/npcache等
--model-loader-extra-config	{}	加载器扩展配置，对应所选load_format
--pt-load-map-location	cpu	PyTorch权重加载设备映射，支持cuda设备字典
--safetensors-load-strategy	None	safetensors读取策略：lazy/eager/prefetch/torchao
--use-tqdm-on-load	True	加载权重时显示进度条

四、AttentionConfig 注意力内核基础配置

参数	默认值	说明
--attention-backend	None	手动指定注意力计算内核，auto自动择优

五、StructuredOutputsConfig 结构化输出（推理解析）

参数	默认值	说明
--reasoning-parser	空	思维链内容专用解析器
--reasoning-parser-plugin	空	自定义推理解析插件路径

六、ParallelConfig 分布式并行（TP/PP/EP/DP/DCP/PCP）

参数	默认值	说明
--all2all-backend	allgather_reducescatter	MoE专家并行通信All2All内核
--cp-kv-cache-interleave-size	1	DCP/PCP KV缓存分片交错粒度，1=token级，block_size=块级
--data-parallel-address / -dpa	None	数据并行集群主节点地址
--data-parallel-backend / -dpb	mp	DP后端：mp多进程 / ray分布式
--data-parallel-external-lb / -dpe	False	外部负载均衡DP模式，K8s单Pod单Rank场景
--data-parallel-hybrid-lb / -dph	False	混合DP负载均衡，本地Rank负载均衡+外部节点LB
--data-parallel-rank / -dpn	None	当前实例DP序号，开启外部LB时必填
--data-parallel-rpc-port / -dpp	None	DP进程RPC通信端口
--data-parallel-size / -dp	1	数据并行副本数量
--data-parallel-size-local / -dpl	None	单节点本地启动DP副本数
--data-parallel-start-rank / -dpr	None	多节点从属节点起始DP序号
--dbo-decode-token-threshold	32	Dual Batch Overlap解码批阈值，token超阈值启用微批
--dbo-prefill-token-threshold	512	预填充批DBO阈值
--dcp-comm-backend	ag_rs	DCP通信内核：ag_rs(AllGather)/a2a(AllToAll)
--dcp-kv-cache-interleave-size	1	废弃参数，替换为cp-kv-cache-interleave-size
--decode-context-parallel-size / -dcp	1	解码上下文并行组数，TP总数需被DCP整除
--disable-custom-all-reduce	False	禁用自定义集合通信，降级NCCL原生
--disable-nccl-for-dp-synchronization	None	DP同步强制使用Gloo替代NCCL，异步调度默认开启
--distributed-executor-backend	None	分布式worker后端：mp/ray/external_launcher/uni
--distributed-timeout-seconds	None	NCCL分布式初始化超时秒数，多节点加载慢时调大
--enable-dbo	False	开启双批次重叠调度提升吞吐
--enable-elastic-ep	False	MoE弹性专家并行，无状态NCCL分组
--enable-ep-weight-filter	False	MoE加载仅读取当前Rank对应专家分片，大幅降低IO
--enable-eplb	False	MoE专家负载均衡
--enable-expert-parallel / -ep	False	MoE启用专家并行EP替代TP
--eplb-config	默认均衡配置JSON	EP负载均衡窗口、冗余专家、异步调度等参数
--expert-placement-strategy	linear	专家分片策略：linear连续分片 / round_robin轮询分片
--master-addr	127.0.0.1	多节点MP分布式主节点地址
--master-port	29501	多节点MP分布式通信端口
--max-parallel-loading-workers	None	并行加载权重进程数，防止TP大模型CPU内存溢出
--nnodes / -n	1	分布式集群总节点数（MP模式）
--node-rank / -r	0	当前节点序号（MP模式）
--pipeline-parallel-size / -pp	1	流水线并行层数
--prefill-context-parallel-size / -pcp	1	预填充上下文并行组数
--ray-workers-use-nsight	False	Ray worker启用Nsight性能剖析
--tensor-parallel-size / -tp	1	张量并行GPU分片数量
--ubatch-size	0	微批尺寸
--worker-cls	auto	自定义推理Worker类路径
--worker-extension-cls	空	Worker扩展注入类，用于RPC扩展功能

七、CacheConfig KV缓存显存调度

参数	默认值	说明
--block-size	None	KV缓存单块token容量，自动适配硬件
--calculate-kv-scales	False	已废弃，FP8 KV scale动态计算开关
--enable-prefix-caching	None	开启前缀缓存，共享相同上下文KV块大幅提速
--gpu-memory-utilization	0.9	显存分配比例，0~1，预留显存用于激活/权重
--kv-cache-dtype	auto	KV缓存精度：fp8/bf16/fp16/fp8_e4m3/fp8_e5m2等
--kv-cache-dtype-skip-layers	[]	指定层不做KV量化，支持层号/滑动窗口标识
--kv-cache-memory-bytes	None	手动限定单卡KV缓存总字节，覆盖gpu-memory-utilization
--kv-offloading-backend	native	KV缓存CPU卸载后端：native/lmcache
--kv-offloading-size	None	KV缓存卸载到CPU内存总容量GiB，开启即启用卸载
--kv-sharing-fast-prefill	False	实验性KV共享预填充优化，当前无效果
--mamba-block-size	None	Mamba模型缓存块大小，必须是8倍数，仅前缀缓存开启生效
--mamba-cache-dtype	auto	Mamba卷积+SSM缓存精度
--mamba-cache-mode	none	Mamba缓存策略：none/all/align
--mamba-ssm-cache-dtype	auto	Mamba状态缓存单独精度配置
--num-gpu-blocks-override	None	手动覆盖GPU缓存块总数，用于抢占测试
--prefix-caching-hash-algo	sha256	前缀缓存哈希算法：安全sha256/高速xxhash

八、OffloadConfig 模型权重CPU卸载

参数	默认值	说明
--cpu-offload-gb	0	每GPU可卸载至CPU内存的权重容量GiB，虚拟扩充显存
--cpu-offload-params	空集合	仅匹配指定权重段执行卸载，空则无差别卸载
--offload-backend	auto	卸载内核：uva零拷贝 / prefetch异步预取
--offload-group-size	0	分层预取卸载分组大小，0关闭
--offload-num-in-group	1	每组内卸载层数上限
--offload-params	空集合	prefetch模式仅卸载匹配参数层
--offload-prefetch-step	1	提前预取层数，越高掩盖传输延迟，占用更多显存

九、MultiModalConfig 多模态图文视频配置

参数	默认值	说明
--enable-mm-embeds	False	允许传入预计算多模态Embedding，仅可信服务
--interleave-mm-strings	False	string模板模式支持图文交错输入
--language-model-only	False	禁用所有多模态输入，等同于所有模态limit=0
--limit-mm-per-prompt	{}	单请求多媒体数量上限，支持图片/视频数量与分辨率限制JSON
--media-io-kwargs	None	多媒体预处理入参，如视频采样帧数
--mm-encoder-attn-backend	None	视觉编码器注意力内核强制指定
--mm-encoder-only	False	仅运行视觉编码器，不加载语言模型，用于分离式部署
--mm-encoder-tp-mode	weights	视觉编码器TP分片策略：weights权重分片 / data数据并行批处理
--mm-processor-cache-gb	4	多模态预处理缓存容量GiB，多进程会重复占用
--mm-processor-cache-type	lru	缓存类型：lru本地缓存 / shm共享内存缓存
--mm-processor-kwargs	None	覆盖模型自带图像处理器参数
--mm-shm-cache-max-object-size-mb	128	shm缓存单文件最大MB限制
--mm-tensor-ipc	direct_rpc	多模态张量进程通信方式：rpc序列化 / torch共享内存零拷贝
--skip-mm-profiling	False	跳过多模态显存预计算，加快启动，但需人工预估显存
--video-pruning-rate	None	视频帧裁剪比例0~1，降低视频token数量

十、LoRAConfig 适配器微调模型

参数	默认值	说明
--default-mm-loras	None	多模态默认绑定LoRA，每种模态自动加载指定适配器
--enable-lora	None	全局开启LoRA动态加载能力
--enable-tower-connector-lora	False	实验：视觉编码器LoRA支持（Qwen-VL等）
--fully-sharded-loras	False	LoRA权重全分片TP计算，长序列/高Rank性能提升，显存占用更高
--lora-dtype	auto	LoRA权重精度，默认跟随基座模型
--lora-target-modules	None	限定LoRA作用层后缀，缩小计算范围提升速度
--max-cpu-loras	None	CPU内存缓存LoRA适配器最大数量，必须≥max-loras
--max-lora-rank	16	支持的LoRA最高秩
--max-loras	1	单批次并发LoRA适配器上限
--specialize-active-lora	False	按活跃LoRA数量单独捕获CUDA Graph，吞吐量提升，启动变慢

十一、ObservabilityConfig 监控、指标、链路追踪

参数	默认值	说明
--collect-detailed-traces	None	OTLP链路追踪采集粒度：all/model/worker，需配置otlp-traces-endpoint
--cudagraph-metrics	False	开启CUDA Graph批填充、执行模式指标
--enable-layerwise-nvtx-tracing	False	逐层NVTX性能标记，与CUDA Graph互斥
--enable-logging-iteration-details	False	每次调度迭代打印请求、token耗时明细
--enable-mfu-metrics	False	开启模型FLOPs硬件利用率指标
--kv-cache-metrics	False	KV缓存块生命周期、复用率采样指标
--kv-cache-metrics-sample	0.01	KV指标采样比例1%
--otlp-traces-endpoint	None	OpenTelemetry追踪上报地址
--show-hidden-metrics-for-version	None	启用已标记废弃的旧Prometheus指标，用于平滑迁移

十二、SchedulerConfig 请求调度批处理

参数	默认值	说明
--async-scheduling	None	异步调度，消除GPU空闲间隙，提升吞吐延迟
--disable-chunked-mm-input	False	分块预填充时不拆分单条多媒体输入，完整处理图片/视频
--disable-hybrid-kv-cache-manager	None	统一KV块分配策略，不区分滑动窗口/全局注意力
--enable-chunked-prefill	None	长Prompt分块预填充，避免单条长请求阻塞队列
--long-prefill-token-threshold	0	判定为超长Prompt的token阈值
--max-long-partial-prefills	1	同时并发处理的超长分块Prompt数量
--max-num-batched-tokens	None	单次迭代GPU最大总token上限，控制显存峰值
--max-num-partial-prefills	1	同时执行分块预填充的请求数
--max-num-seqs	None	单次迭代最大并发序列数
--scheduler-cls	None	自定义调度器类路径
--scheduler-reserve-full-isl	True	准入前校验整条序列可存入KV缓存，防止频繁抢占
--scheduling-policy	fcfs	调度策略：fcfs先来先服务 / priority优先级调度
--stream-interval	1	流式输出token缓冲间隔，1逐token输出，大数减少网络开销

十三、CompilationConfig 编译、CUDA Graph、Torch Inductor

参数	默认值	说明
--cudagraph-capture-sizes	None	手动指定需要捕获CUDA Graph的批大小列表
--max-cudagraph-capture-size	None	CUDA Graph捕获最大批尺寸，自动生成1/2/4/8~512阶梯尺寸

十四、KernelConfig 内核与MoE计算

参数	默认值	说明
--enable-flashinfer-autotune	None	启动时自动调优FlashInfer内核参数
--moe-backend	auto	MoE专家计算内核：triton/deep_gemm/cutlass/flashinfer系列/marlin等

十五、VllmConfig 顶层综合优化参数

参数	默认值	说明
--additional-config	{}	平台扩展配置字典
--attention-config / -ac	默认注意力JSON	批量配置注意力内核、预填充拆分、FP8量化开关等
--compilation-config / -cc	默认编译JSON	统一控制inductor、cudagraph捕获、编码器编译等全部编译参数
--ec-transfer-config	None	EC缓存分布式传输配置
--kernel-config	默认内核JSON	批量设置FlashInfer自动调优、MoE后端
--kv-events-config	None	KV缓存事件发布回调配置
--kv-transfer-config	None	分布式KV缓存跨GPU传输参数
--optimization-level	2(-O2)	优化等级：O0启动快/O2平衡/O3吞吐量最优
--performance-mode	balanced	运行模式：balanced均衡 / interactivity低延迟 / throughput高吞吐
--profiler-config	默认性能采集JSON	Torch Profiler堆栈、FLOPs、内存采集开关
--reasoning-config	None	思维链模型专用推理参数
--speculative-config / -sc	None	投机解码（草稿模型）完整配置
--structured-outputs-config	默认结构化输出JSON	JSON/工具调用输出约束开关、推理解析器绑定
--weight-transfer-config	None	RL训练权重分布式传输配置

JSON参数传参语法说明

1. 完整JSON写法

   --json-arg '{"key1": "val", "key2": {"sub": 123}}'

2. 分层简写写法

   --json-arg.key1 val --json-arg.key2.sub 123

3. 列表多值传入（+标识追加）

   --json-arg.list+ item1 --json-arg.list+ item2,item3

最后更新于  2026-06-20 21:31:51  并被添加「」标签，已有 23 位童鞋阅读过。

本站使用「署名 4.0 国际」创作共享协议，可自由转载、引用，但需署名作者且注明文章出处