vllm bench latency

JSON 命令行参数

当传递 JSON 命令行参数时，以下几组参数是等效的

• --json-arg '{"key1": "value1", "key2": {"key3": "value2"}}'
• --json-arg.key1 value1 --json-arg.key2.key3 value2

此外，列表元素可以使用 + 单独传递

• --json-arg '{"key4": ["value3", "value4", "value5"]}'
• --json-arg.key4+ value3 --json-arg.key4+='value4,value5'

参数

--input-len

默认值: 32

--output-len

默认值: 128

--batch-size

默认值：8

--n

每个提示词（prompt）生成的序列数量。

默认值: 1

--use-beam-search

默认值: False

--num-iters-warmup

预热运行的迭代次数。

默认值：10

--num-iters

运行的迭代次数。

默认值：30

--profile

对单个批次的生成过程进行性能分析（profile）

默认值: False

--output-json

以 JSON 格式保存延迟结果的路径。

--disable-detokenize

不进行响应的反令牌化（即：在延迟测量中不包含反令牌化时间）

默认值: False

--disable-log-stats

禁用日志统计信息。

默认值: False

--aggregate-engine-logging

在使用数据并行时，记录聚合统计信息而非单个引擎的统计信息。

默认值: False

--fail-on-environ-validation, --no-fail-on-environ-validation

如果设置，当环境验证失败时，引擎将引发错误。

默认值: False

--shutdown-timeout

关闭超时时间（秒）。0 = 中止，>0 = 等待。

默认值: 0

--gdn-prefill-backend

可选值：flashinfer、triton、cutedsl

选择 GDN 预填充后端。

ModelConfig

模型配置。

--model

要使用的 Hugging Face 模型的名称或路径。当未指定 `served_model_name` 时，它也用作指标输出中 `model_name` 标签的内容。

默认值: Qwen/Qwen3-0.6B

--runner

可选值: auto, draft, generate, pooling

要使用的模型运行器类型。每个 vLLM 实例只支持一个模型运行器，即使同一模型可用于多种类型。

默认值: auto

--convert

Possible choices: auto, classify, embed, none

使用 vllm.model_executor.models.adapters 中定义的适配器转换模型。最常见的用例是将文本生成模型适配用于池化任务。

默认值: auto

--tokenizer

要使用的 Hugging Face 分词器的名称或路径。如果未指定，将使用模型名称或路径。

--tokenizer-mode

可选值：auto、deepseek_v32、deepseek_v4、hf、mistral、slow

分词器模式

• “auto”将为 Mistral 模型使用 mistral_common 中的分词器（如果可用），否则将使用“hf”分词器。
• "hf" 将在可用时使用快速分词器。
• "slow" 将始终使用慢速分词器。
• "mistral" 将始终使用来自 mistral_common 的分词器。
• "deepseek_v32" 将始终使用来自 deepseek_v32 的分词器。
• "deepseek_v4" 将始终使用来自 deepseek_v4 的分词器。
• 其他自定义值可以通过插件支持。

要将为 HF 快速分词器提供支持的 Rust BPE 后端替换为 fastokens 实现，请设置 VLLM_USE_FASTOKENS=1 — 该覆盖适用于加载 HF 快速分词器的任何模式（hf、deepseek_v32、deepseek_v4 等）。

默认值: auto

--trust-remote-code, --no-trust-remote-code

下载模型和分词器时信任远程代码（例如，来自 HuggingFace）。

默认值: False

--dtype

可选值: auto, bfloat16, float, float16, float32, half

模型权重和激活值的数据类型

• "auto" 将对 FP32 和 FP16 模型使用 FP16 精度，对 BF16 模型使用 BF16 精度。
• "half" 表示 FP16。推荐用于 AWQ 量化。
• "float16" 与 "half" 相同。
• "bfloat16" 用于在精度和范围之间取得平衡。
• "float" 是 FP32 精度的简写。
• "float32" 表示 FP32 精度。

默认值: auto

--seed

用于可复现性的随机种子。

我们必须设置全局种子，否则不同的张量并行工作进程会采样到不同的令牌，导致结果不一致。

默认值: 0

--hf-config-path

要使用的 Hugging Face 配置的名称或路径。如果未指定，将使用模型名称或路径。

--allowed-local-media-path

允许 API 请求从服务器文件系统指定的目录中读取本地图像或视频。这是一个安全风险。只应在受信任的环境中启用。

默认值: ""

--allowed-media-domains

如果设置，只有属于此域的媒体 URL 可用于多模态输入。

--revision

要使用的特定模型版本。可以是一个分支名、一个标签名或一个提交 ID。如果未指定，将使用默认版本。

--code-revision

用于 Hugging Face Hub 上模型代码的特定修订版。可以是一个分支名、一个标签名或一个提交 ID。如果未指定，将使用默认版本。

--tokenizer-revision

用于 Hugging Face Hub 上分词器的特定修订版。可以是一个分支名、一个标签名或一个提交 ID。如果未指定，将使用默认版本。

--max-model-len

模型上下文长度（提示和输出）。如果未指定，将从模型配置中自动推导。

通过 --max-model-len 传递时，支持 k/m/g/K/M/G 等人类可读格式。示例

• 1k -> 1000
• 1K -> 1024
• 25.6k -> 25,600
• -1 or 'auto' -> Automatically choose the maximum model length that fits in GPU memory. This will use the model's maximum context length if it fits, otherwise it will find the largest length that can be accommodated.

Parse human-readable integers like '1k', '2M', etc. Including decimal values with decimal multipliers. Also accepts -1 or 'auto' as a special value for auto-detection.

Examples:
- '1k' -> 1,000
- '1K' -> 1,024
- '25.6k' -> 25,600
- '-1' or 'auto' -> -1 (special value for auto-detection)

--quantization, -q

用于量化权重的方法。如果为 None，我们首先检查模型配置文件中的 quantization_config 属性。如果该属性为 None，我们假设模型权重未被量化，并使用 dtype 来确定权重的数据类型。

--quantization-config

面向用户的量化配置。包含逐层类别规范（linear, moe）和忽略模式；请参阅 :class:QuantizationConfigArgs。当 quantization 是 ONLINE_QUANT_SHORTHAND_NAMES 中的值之一时，该配置会自动从匹配的在线简写中填充。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.QuantizationConfigArgs

应为有效的 JSON 字符串或单独传递的 JSON 键。

--allow-deprecated-quantization, --no-allow-deprecated-quantization

Whether to allow deprecated quantization methods.

默认值: False

--enforce-eager, --no-enforce-eager

是否始终使用 eager-mode 的 PyTorch。如果为 True，我们将禁用 CUDA graph 并始终以 eager mode 执行模型。如果为 False，我们将混合使用 CUDA graph 和 eager execution 以获得最佳性能和灵活性。

默认值: False

--enable-return-routed-experts, --no-enable-return-routed-experts

Whether to return routed experts.

默认值: False

--max-logprobs

当在 SamplingParams 中指定 logprobs 时，返回的对数概率的最大数量。默认值来自 OpenAI Chat Completions API 的默认值。-1 表示没有上限，即允许返回所有 (output_length * vocab_size) 个对数概率，这可能导致内存溢出 (OOM)。

默认值: 20

--logprobs-mode

可选值: processed_logits, processed_logprobs, raw_logits, raw_logprobs

指示在 logprobs 和 prompt_logprobs 中返回的内容。支持的模式：1) raw_logprobs, 2) processed_logprobs, 3) raw_logits, 4) processed_logits。Raw 表示应用任何 logit 处理器（如禁用词）之前的值。Processed 表示应用所有处理器（包括温度和 top_k/top_p）之后的值。

默认值: raw_logprobs

--use-fp64-gumbel, --no-use-fp64-gumbel

是否使用 FP64（而不是 FP32）随机噪声进行 Gumbel-max 和等效的指数竞赛采样。FP64 保留了 FP32 均匀/指数抽样可能截断的下尾采样事件，但代价是大多数 GPU 上的吞吐量显著降低。

默认值: False

--disable-sliding-window, --no-disable-sliding-window

是否禁用滑动窗口。如果为 True，我们将禁用模型的滑动窗口功能，限制到滑动窗口大小。如果模型不支持滑动窗口，此参数将被忽略。

默认值: False

--disable-cascade-attn, --no-disable-cascade-attn

禁用 V1 的级联注意力 (cascade attention)。虽然级联注意力不会改变数学正确性，但禁用它可以防止潜在的数值问题。默认值为 True，因此用户必须通过将其设置为 False 来选择加入级联注意力。即使设置为 False，级联注意力也仅在启发式算法认为有益时才会使用。

默认值: True

--skip-tokenizer-init, --no-skip-tokenizer-init

跳过分词器和反分词器的初始化。期望输入中包含有效的 prompt_token_ids 并且 prompt 为 None。生成的输出将包含 token id。

默认值: False

--enable-prompt-embeds, --no-enable-prompt-embeds

如果为 True，则允许通过 prompt_embeds 键传递文本嵌入作为输入。

警告：如果传递了错误形状的嵌入，vLLM 引擎可能会崩溃。仅对受信任的用户启用此标志！

默认值: False

--served-model-name

API 中使用的模型名称。如果提供了多个名称，服务器将响应任何提供的名称。响应的 model 字段中的模型名称将是此列表中的第一个名称。如果未指定，模型名称将与 --model 参数相同。请注意，此名称（或多个名称）也将用于 prometheus 指标的 model_name 标签内容，如果提供多个名称，指标标签将采用第一个。

--config-format

可选值: auto, hf, mistral

要加载的模型配置格式

• "auto" 将在尝试加载 mistral 格式后，如果可用，则尝试以 hf 格式加载配置。
• "hf" 将以 hf 格式加载配置。
• "mistral" 将以 mistral 格式加载配置。

默认值: auto

--hf-token

The token to use as HTTP bearer authorization for remote files . If True, will use the token generated when running hf auth login (stored in ~/.cache/huggingface/token).

--hf-overrides

如果是一个字典，包含要转发给 Hugging Face 配置的参数。如果是一个可调用对象，则调用它来更新 HuggingFace 配置。

默认值: {}

--model-class-overrides

覆盖用于一个或多个架构的模型类，将架构名称映射到 "module:class" 目标（与 ModelRegistry.register_model 接受的格式相同）。这会在运行时注册目标类，例如 {"GlmMoeDsaForCausalLM": "vllm.models.deepseek_v32.nvidia.model:DeepseekV32ForCausalLM"}。此参数仅用于开发和调试目的。

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: {}

--pooler-config

池化器配置，用于控制池化模型中输出池化的行为。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.PoolerConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--generation-config

生成配置的文件夹路径。默认为 "auto"，生成配置将从模型路径加载。如果设置为 "vllm"，则不加载生成配置，将使用 vLLM 的默认值。如果设置为文件夹路径，则将从指定的文件夹路径加载生成配置。如果在生成配置中指定了 max_new_tokens，那么它将为所有请求设置服务器范围的输出令牌数量限制。

默认值: auto

--override-generation-config

覆盖或设置生成配置。例如 {"temperature": 0.5}。如果与 --generation-config auto 一起使用，覆盖参数将与模型的默认配置合并。如果与 --generation-config vllm 一起使用，则仅使用覆盖参数。

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: {}

--enable-sleep-mode, --no-enable-sleep-mode

为引擎启用睡眠模式（仅支持 cuda 和 hip 平台）。

默认值: False

--enable-cumem-allocator, --no-enable-cumem-allocator

启用自定义 cumem 分配器，以利用先进的 GPU 内存分配功能（例如多节点 NVLink 支持）。

睡眠模式会自动启用此分配器。仅支持 cuda 和 hip 平台。

默认值: False

--model-impl

可选值: auto, terratorch, transformers, vllm

使用哪个模型实现

• "auto" 将尝试使用 vLLM 实现（如果存在），如果不存在 vLLM 实现，则回退到 Transformers 实现。
• "vllm" 将使用 vLLM 模型实现。
• "transformers" 将使用 Transformers 模型实现。
• "terratorch" 将使用 TerraTorch 模型实现。

默认值: auto

--override-attention-dtype

覆盖注意力的 dtype

--logits-processors

一个或多个 logits 处理器的完全限定类名或类定义。

--io-processor-plugin

在模型启动时加载的 IOProcessor 插件名称。

--renderer-num-workers

渲染器线程池中的工作线程数。异步渲染器路径（例如由 vllm serve 启动的与 OpenAI 兼容的 API 服务器）会使用该线程池，以在并发请求中并行执行分词、聊天模板渲染和多模态预处理。

离线 LLM 入口点使用同步渲染器路径并串行处理提示词（包括多模态预处理），因此该设置在此处无效。

默认值: 1

LoadConfig

加载模型权重的配置。

--load-format

要加载的模型权重格式。

• "auto" 将尝试以 safetensors 格式加载权重，如果 safetensors 格式不可用，则回退到 pytorch bin 格式。
• "pt" 将以 pytorch bin 格式加载权重。
• "safetensors" 将以 safetensors 格式加载权重。
• "instanttensor" 将使用 InstantTensor 在 CUDA 设备上加载 Safetensors 权重，实现流水线预取的分布式加载和快速直接 I/O。
• "npcache" 将以 pytorch 格式加载权重，并存储一个 numpy 缓存以加快加载速度。
• "dummy" 将使用随机值初始化权重，主要用于性能分析。
• "tensorizer" 将使用 CoreWeave 的 tensorizer 库进行快速权重加载。更多信息请参见示例部分的 Tensorize vLLM Model 脚本。
• "runai_streamer" 将使用 Run:ai Model Streamer 加载 Safetensors 权重。
• "runai_streamer_sharded" 将使用 Run:ai Model Streamer 从预分片的检查点文件加载权重。
• "bitsandbytes" 将使用 bitsandbytes 量化加载权重。
• "sharded_state" 将从预分片的检查点文件加载权重，支持高效加载张量并行模型。
• "mistral" 将从 Mistral 模型使用的合并 safetensors 文件加载权重。
• "modelexpress" 将使用 ModelExpress 加载权重。
• 其他自定义值可以通过插件支持。

默认值: auto

--download-dir

下载和加载权重的目录，默认为 Hugging Face 的默认缓存目录。

--safetensors-load-strategy

可选值: eager, lazy, prefetch, torchao, None

指定 Safetensors 权重的加载策略。

• None（默认）：使用内存映射（惰性）加载。检测到 NFS 文件系统且检查点总大小在可用 RAM 的 90% 以内时，自动启用预取。
• "lazy"：从文件内存映射权重。实现按需加载，对于本地存储上的模型非常高效。与默认值 (None) 不同，不会在 NFS 上执行自动预取。
• "eager"：在加载前将整个文件预先读取到 CPU 内存中。建议用于网络文件系统（如 Lustre, NFS）上的模型，因为它避免了低效的随机读取，显著加快了模型初始化速度。但会占用更多 CPU RAM。
• "prefetch"：检查点文件在工作进程加载之前被读取到操作系统页面缓存中，从而加快模型加载阶段。适用于网络或高延迟存储。
• "torchao"：先加载权重，然后重构为 torchao 张量子类。用于使用 torchao 量化并以 safetensors 保存的检查点。需要 torchao >= 0.14.0。

--safetensors-prefetch-num-threads

启用 safetensors 预取时，用于将 safetensors 检查点文件预取到操作系统页面缓存中的工作线程数。

默认值：8

--safetensors-prefetch-block-size

每次 safetensors 检查点文件预取的读取大小（字节）。

解析像 '1k', '2M' 等人类可读的整数。包括带小数乘数的小数值。

Examples:
- '1k' -> 1,000
- '1K' -> 1,024
- '25.6k' -> 25,600

默认值：16777216

--model-loader-extra-config

模型加载器的额外配置。这将传递给与所选 load_format 对应的模型加载器。

默认值: {}

--ignore-patterns

加载模型时要忽略的模式列表。默认为 "original/*/" 以避免重复加载 llama 的检查点。

默认值: ['original/**/*']

--use-tqdm-on-load, --no-use-tqdm-on-load

是否在加载模型权重时启用 tqdm 以显示进度条。

默认值: True

--pt-load-map-location

用于加载 PyTorch 检查点的映射位置，以支持仅能在特定设备（如 "cuda"）上加载的检查点，这等同于 {"": "cuda"}。另一个支持的格式是映射不同的设备，如从 GPU 1 到 GPU 0：{"cuda:1": "cuda:0"}。注意，当从命令行传入时，字典中的字符串需要双引号进行 JSON 解析。更多详情，请参见 torch.load 参数的原始文档。

默认值: cpu

AttentionConfig

vLLM 中注意力机制的配置。

--attention-backend

要使用的注意力后端。使用 "auto" 或 None 进行自动选择。

MambaConfig

Mamba SSM 后端的配置。

--mamba-backend

要使用的 Mamba SSU 后端。

默认值：MambaBackendEnum.TRITON

--enable-mamba-cache-stochastic-rounding, --no-enable-mamba-cache-stochastic-rounding

将 SSM 状态写入 fp16 缓存时启用随机舍入。使用随机位来去除舍入误差的偏差，这可以提高长序列的数值稳定性。

默认值: False

--mamba-cache-philox-rounds

用于随机舍入随机数生成的 Philox PRNG 轮数。0 使用 Triton 默认值。较高的值以计算代价提高随机性质量。

默认值: 0

StructuredOutputsConfig

包含引擎结构化输出配置的数据类。

--reasoning-parser

根据您使用的模型选择推理解析器。这用于将推理内容解析为 OpenAI API 格式。

默认值: ""

--reasoning-parser-plugin

可以动态加载和注册的动态推理解析器插件的路径。

默认值: ""

ParallelConfig

分布式执行的配置。

--distributed-executor-backend

可选值: external_launcher, mp, ray, uni

分布式模型工作器要使用的后端，可以是“ray”或“mp”（多进程）。如果 pipeline_parallel_size 和 tensor_parallel_size 的乘积小于或等于可用 GPU 数量，则将使用“mp”将处理保留在单个主机上。否则，将引发错误。要使用“mp”，您还必须设置 nnodes，要使用“ray”，您必须手动设置 distributed_executor_backend 为“ray”。

注意：TPU 平台仅支持 Ray 进行分布式推理。

--pipeline-parallel-size, -pp

流水线并行组的数量。

默认值: 1

--master-addr

当 distributed_executor_backend 为 mp 时，用于多节点分布式推理的分布式主节点地址。

默认值: 127.0.0.1

--master-port

当 distributed_executor_backend 为 mp 时，用于多节点分布式推理的分布式主节点端口。

默认值: 29501

--nnodes, -n

当 distributed_executor_backend 为 mp 时，用于多节点分布式推理的节点数量。

默认值: 1

--node-rank, -r

当 distributed_executor_backend 为 mp 时，用于多节点分布式推理的分布式节点排名。

默认值: 0

--distributed-timeout-seconds

分布式操作（如 init_process_group）的超时时间（秒）。如果设置，该值将作为超时参数传递给 torch.distributed.init_process_group。如果为 None，则使用 PyTorch 的默认超时（NCCL 为 600 秒）。对于模型下载可能缓慢的多节点设置，请增加此值。

--cpu-distributed-timeout-seconds

CPU 通信组的超时时间（以秒为单位）。如果为 None，则使用 PyTorch 的默认超时时间（gloo 默认为 1800 秒）。

--numa-bind, --no-numa-bind

为 GPU 工作子进程启用 NUMA 绑定。

默认情况下，工作线程会被绑定到其 GPU 的 NUMA 本地 CPU 和内存；在支持 PCT 的 Xeon 处理器上，它们还会自动绑定到该 SKU 的 PCT 优先级内核。

默认值: False

--numa-bind-nodes

将每个 GPU 工作进程绑定到的 NUMA 节点。

为每个可见 GPU 指定一个 NUMA 节点，例如对于 4-GPU 系统，GPU 0-1 在 NUMA 节点 0，GPU 2-3 在 NUMA 节点 1，指定为 [0, 0, 1, 1]。如果未设置且 numa_bind=True，vLLM 会自动检测 GPU 到 NUMA 的拓扑结构。这些值将传递给 numactl --membind 和 --cpunodebind，因此必须是有效的 numactl NUMA 节点索引。

--numa-bind-cpus

绑定每个 GPU 工作进程的可选 CPU 列表。

为每个可见 GPU 指定一个 CPU 列表，例如 ["0-3", "4-7", "8-11", "12-15"]。设置后，vLLM 使用 numactl --physcpubind 而不是 --cpunodebind。这对于绑定到 PCT 或其他高频核心等自定义策略非常有用。每个条目必须使用 numactl --physcpubind CPU 列表语法，例如 "0-3" 或 "0,2,4-7"。

--device-ids

要使用的逗号分隔的物理 GPU 设备 ID 或 UUID（例如 `--device-ids "2,3,5,7"`）。避免设置 `CUDA_VISIBLE_DEVICES`，从而为 GPU-NIC 亲和性和 DeepGEMM 保留完整的 GPU 拓扑可见性。注意：对 Ray 执行器无效；请改用 Ray 放置组进行 GPU 选择。

--tensor-parallel-size, -tp

张量并行组的数量。

默认值: 1

--decode-context-parallel-size, -dcp

解码上下文并行组的数量，因为世界大小不因 dcp 而改变，它只是重用 TP 组的 GPU，并且 tp_size 需要能被 dcp_size 整除。

默认值: 1

--dcp-comm-backend

可选值：a2a, ag_rs

解码上下文并行 (DCP) 的通信后端。- "ag_rs"：AllGather + ReduceScatter（默认，现有行为）- "a2a"：部分输出 + LSE 的全对全 (All-to-All) 交换，然后使用 Triton 内核合并。对于 MLA 模型，将每层的 NCCL 调用次数从 3 次减少到 2 次。

默认值：ag_rs

--dcp-kv-cache-interleave-size

使用 DCP 时 kv_cache 存储的交错大小。dcp_kv_cache_interleave_size 已被 cp_kv_cache_interleave_size 替代，并将在 PCP 完全支持后弃用。

默认值: 1

--cp-kv-cache-interleave-size

使用 DCP 或 PCP 时 kv_cache 存储的交错大小。对于 `total_cp_rank = pcp_rank * dcp_world_size + dcp_rank` 和 `total_cp_world_size = pcp_world_size * dcp_world_size`。在 total_cp_rank i 上存储 interleave_size 个令牌，然后在 total_cp_rank i+1 上存储下一个 interleave_size 个令牌。Interleave_size=1：令牌级对齐，其中令牌 `i` 存储在 total_cp_rank `i %% total_cp_world_size` 上。Interleave_size=block_size：块级对齐，其中令牌首先填充到前面的排名。只有在 (rank i, block j) 完全占用后，令牌才会存储在 (rank i+1, block j) 中。Block_size 应大于或等于 cp_kv_cache_interleave_size。Block_size 应能被 cp_kv_cache_interleave_size 整除。

默认值: 1

--prefill-context-parallel-size, -pcp

预填充上下文并行组的数量。

默认值: 1

--data-parallel-size, -dp

数据并行组的数量。MoE 层将根据张量并行大小和数据并行大小的乘积进行分片。

默认值: 1

--data-parallel-rank, -dpn

此实例的数据并行秩（Rank）。设置后，将为 MoE 数据并行部署启用外部负载均衡器模式。不支持非 MoE 模型；若为非 MoE 模型请启动独立的 vLLM 实例。

--data-parallel-start-rank, -dpr

二级节点的起始数据并行排名。

--data-parallel-size-local, -dpl

在此节点上运行的数据并行副本数量。

--data-parallel-address, -dpa

数据并行集群头节点的地址。

--data-parallel-rpc-port, -dpp

用于数据并行 RPC 通信的端口。

--data-parallel-backend, -dpb

数据并行的后端，可以是 "mp" 或 "ray"。

默认值: mp

--data-parallel-hybrid-lb, --no-data-parallel-hybrid-lb, -dph

是否使用“混合”DP LB 模式。仅适用于在线服务且 data_parallel_size > 0。允许在“每个节点”基础上运行 AsyncLLM 和 API 服务器，其中 vLLM 在本地数据并行排名之间进行负载均衡，但外部 LB 在 vLLM 节点/副本之间进行负载均衡。与 --data-parallel-start-rank 结合使用时显式设置。

默认值: False

--data-parallel-external-lb, --no-data-parallel-external-lb, -dpe

是否使用“外部”数据并行负载均衡（DP LB）模式。仅适用于在线服务且 data_parallel_size > 0 的情况。这对于 Kubernetes 中“每个 Pod 一个 Rank”的宽 expert-parallel（EP）设置非常有用。仅支持 MoE 部署；非 MoE 模型应使用独立的 vLLM 实例，不带 --data-parallel-* 参数。当显式地向 vllm serve 提供 --data-parallel-rank 时，此项会隐式设置。

默认值: False

--data-parallel-multi-port-external-lb, -dpm

运行一个节点本地监控程序（supervisor），为每个本地数据并行秩（rank）启动一个外部负载均衡 API 服务器，并在监控端口上公开汇总的健康状况。

默认值: False

--enable-expert-parallel, --no-enable-expert-parallel, -ep

对 MoE 层使用专家并行而不是张量并行。

默认值: False

--enable-ep-weight-filter, --no-enable-ep-weight-filter

当专家并行 (EP) 处于活动状态时，在模型加载期间跳过非本地专家权重。每个秩仅从磁盘读取其自己的专家分片，这可以显著减少具有每个专家权重张量（如 DeepSeek, Mixtral, Kimi-K2.5）的 MoE 模型的存储 I/O。对 3D 融合专家检查点（如 GPT-OSS）或非 MoE 模型没有影响。

默认值: False

--all2all-backend

可选值: allgather_reducescatter, deepep_high_throughput, deepep_low_latency, deepep_v2, flashinfer_all2allv, flashinfer_nvlink_one_sided, flashinfer_nvlink_two_sided, mori_high_throughput, mori_low_latency, naive, nixl_ep, pplx

MoE 专家并行通信的 All2All 后端。可用选项

• “allgather_reducescatter”：基于 allgather 和 reducescatter 的 all2all
• “deepep_high_throughput”：使用 deepep 高吞吐量内核
• “deepep_low_latency”：使用 deepep 低延迟内核
• "mori_high_throughput"：基于 InterNodeV1 适用于多节点的 MoRI EP
• "mori_low_latency"：基于 InterNodeV1LL 适用于多节点的 MoRI EP
• "nixl_ep"：使用 nixl-ep 内核
• "flashinfer_nvlink_two_sided"：为 mnnvl 使用 FlashInfer 双边内核
• "flashinfer_nvlink_one_sided"：使用 FlashInfer 高吞吐量 a2a 内核

默认：allgather_reducescatter

--enable-dbo, --no-enable-dbo

为模型执行器启用双批次重叠。

默认值: False

--ubatch-size

ubatch 的数量。

默认值: 0

--enable-elastic-ep, --no-enable-elastic-ep

为 DP/EP 启用具有无状态 NCCL 组的弹性专家并行。

默认值: False

--dbo-decode-token-threshold

仅包含解码的批次的双批次重叠阈值。如果请求中的令牌数大于此阈值，将使用微批处理。否则，请求将在单个批次中处理。

默认值: 32

--dbo-prefill-token-threshold

包含一个或多个预填充的批次的双批次重叠阈值。如果请求中的令牌数大于此阈值，将使用微批处理。否则，请求将在单个批次中处理。

默认值: 512

--disable-nccl-for-dp-synchronization, --no-disable-nccl-for-dp-synchronization

Forces the dp synchronization logic in vllm/v1/worker/dp_utils.py to use Gloo instead of NCCL for its all reduce.

Defaults to True when async scheduling is enabled, False otherwise.

--enable-eplb, --no-enable-eplb

为 MoE 层启用专家并行负载均衡。

默认值: False

--eplb-config

专家并行配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.EPLBConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值：EPLBConfig(window_size=1000, step_interval=3000, num_redundant_experts=0, log_balancedness=False, log_balancedness_interval=1, use_async=True, policy='default', communicator=None)

--expert-placement-strategy

可选值: linear, round_robin

MoE 层的专家放置策略

• "linear": 专家以连续的方式放置。例如，有 4 个专家和 2 个排名，排名 0 将有专家 [0, 1]，排名 1 将有专家 [2, 3]。
• "round_robin": 专家以轮询的方式放置。例如，有 4 个专家和 2 个排名，排名 0 将有专家 [0, 2]，排名 1 将有专家 [1, 3]。此策略可以帮助改善无冗余专家的分组专家模型的负载均衡。

默认值: linear

--max-parallel-loading-workers

在多个批次中顺序加载模型时，并行加载工作进程的最大数量。用于在使用张量并行和大型模型时避免 RAM OOM。

--ray-workers-use-nsight, --no-ray-workers-use-nsight

是否使用 nsight 对 Ray 工作进程进行性能分析，请参见 https://docs.rayai.org.cn/en/latest/ray-observability/user-guides/profiling.html#profiling-nsight-profiler。

默认值: False

--disable-custom-all-reduce, --no-disable-custom-all-reduce

禁用自定义 all-reduce 内核并回退到 NCCL。

默认值: False

--worker-cls

要使用的 worker 类的全名。如果为 "auto"，将根据平台确定 worker 类。

默认值: auto

--worker-extension-cls

要使用的 worker 扩展类的全名。worker 扩展类由 worker 类动态继承。这用于向 worker 类注入新的属性和方法，以用于 collective_rpc 调用。

默认值: ""

CacheConfig

KV 缓存的配置。

--block-size

以标记数量计算的连续缓存块大小。接受 None（表示“使用默认值”）。构造完成后，始终为 int 类型。

--gpu-memory-utilization

用于模型执行器的 GPU 内存比例，取值范围为 0 到 1。例如，值 0.5 表示 50%% 的 GPU 内存利用率。如果未指定，将使用默认值 0.92。这是一个单实例限制，仅适用于当前 vLLM 实例。即使你在同一块 GPU 上运行了另一个 vLLM 实例也没关系。例如，如果你在同一块 GPU 上运行了两个 vLLM 实例，你可以将每个实例的 GPU 内存利用率设置为 0.5。

默认值：0.92

--kv-cache-memory-bytes

每个 GPU 的 KV 缓存大小（以字节为单位）。默认情况下，此值设置为 None，vllm 可以根据 gpu_memory_utilization 自动推断 kv 缓存大小。但是，用户可能希望手动指定 kv 缓存内存大小。与使用 gpu_memory_utilization 相比，kv_cache_memory_bytes 允许更精细地控制内存使用量。请注意，kv_cache_memory_bytes（当不为 None 时）会忽略 gpu_memory_utilization。

解析像 '1k', '2M' 等人类可读的整数。包括带小数乘数的小数值。

Examples:
- '1k' -> 1,000
- '1K' -> 1,024
- '25.6k' -> 25,600

--kv-cache-dtype

可选值: auto, bfloat16, float16, fp8, fp8_ds_mla, fp8_e4m3, fp8_e5m2, fp8_inc, fp8_per_token_head, int4_per_token_head, int8_per_token_head, nvfp4, turboquant_3bit_nc, turboquant_4bit_nc, turboquant_k3v4_nc, turboquant_k8v4

kv 缓存存储的数据类型。如果为 "auto"，将使用模型数据类型。CUDA 11.8+ 支持 fp8 (=fp8_e4m3) 和 fp8_e5m2。ROCm (AMD GPU) 支持 fp8 (=fp8_e4m3)。Intel Gaudi (HPU) 支持 fp8 (使用 fp8_inc)。某些模型（即 DeepSeekV3.2）默认为 fp8，设置为 bfloat16 以使用 bfloat16，对于不默认为 fp8 的模型，这是一个无效选项。

默认值: auto

--num-gpu-blocks-override

要使用的 GPU 块数量。如果指定，这将覆盖分析得出的 `num_gpu_blocks`。如果为 `None` 则不执行任何操作。用于测试抢占。

--enable-prefix-caching, --no-enable-prefix-caching

是否启用前缀缓存。

默认值: False

--prefix-caching-hash-algo

可能的选项：sha256, sha256_cbor, xxhash, xxhash_cbor

设置前缀缓存的哈希算法

• “sha256”在哈希之前使用 Pickle 进行对象序列化。这是当前默认值，因为 SHA256 是避免潜在哈希冲突的最安全选择。
• "sha256_cbor" 提供一个可复现、跨语言兼容的哈希。它使用规范的 CBOR 序列化对象，并使用 SHA-256 进行哈希。
• “xxhash”使用 Pickle 序列化和 xxHash（128 位）进行更快的非加密哈希。需要可选的 xxhash 包。重要提示：使用不被认为在密码学上安全的哈希算法理论上会增加哈希冲突的风险，这可能导致未定义行为，甚至在多租户环境中泄露私人信息。即使冲突仍然非常不可能，在启用此功能之前，考虑您的安全风险容忍度与性能优势也很重要。
• “xxhash_cbor”结合了规范 CBOR 序列化和 xxHash 进行可重复的哈希。需要可选的 xxhash 包。

默认值: sha256

--calculate-kv-scales, --no-calculate-kv-scales

已弃用：此选项已弃用，并将在 v0.19 中移除。它启用了当 kv_cache_dtype 为 fp8 时 k_scale 和 v_scale 的动态计算。如果为 False，比例将从模型检查点加载（如果可用）。否则，比例将默认为 1.0。

默认值: False

--kv-cache-dtype-skip-layers

用于跳过 KV 缓存量化的层模式。接受层索引（例如 '0', '2', '4'）或注意力类型名称（例如 'sliding_window'）。

默认值：[]

--kv-sharing-fast-prefill, --no-kv-sharing-fast-prefill

在某些 KV 共享设置中，例如 YOCO (https://arxiv.org/abs/2405.05254)，某些层可以跳过与预填充对应的令牌。此标志允许将符合条件的层的注意力元数据覆盖为在某些模型（例如 Gemma3n）中实现此优化所需的元数据。注意：MRv2（v2 模型运行器）不支持 KV 缓存共享。

默认值: False

--mamba-cache-dtype

可选值：auto、bfloat16、float16、float32

用于 Mamba 缓存（包括 conv 和 ssm 状态）的数据类型。如果设置为 'auto'，数据类型将从模型配置中推断。

默认值: auto

--mamba-ssm-cache-dtype

可选值：auto、bfloat16、float16、float32

用于 Mamba 缓存（仅 ssm 状态，conv 状态仍由 mamba_cache_dtype 控制）的数据类型。如果设置为 'auto'，ssm 状态的数据类型将由 mamba_cache_dtype 决定。

默认值: auto

--mamba-block-size

Mamba 缓存的连续缓存块大小（以令牌数量为单位）。仅在前缀缓存启用时可设置。值必须是 8 的倍数，以与 causal_conv1d 内核对齐。

--prefix-match-unit

前缀缓存命中可以落到的最细粒度令牌边界（以令牌计）。

前缀缓存键每 prefix_match_unit 个令牌计算一次。只要每个 KV 缓存组的 block_size 能被它整除，它就可以设置得比物理 KV 缓存块大小（例如 32 对 1024 令牌混合模型块）更细，从而实现在物理块内部边界处的缓存命中。它只控制匹配粒度，不控制状态存储的频率。

这等于 KV 缓存代码中使用的 hash_block_size。

--mamba-cache-mode

Possible choices: align, all, none

The cache strategy for Mamba layers. - "none": set when prefix caching is disabled. - "all": cache the mamba state of all tokens at position i * block_size. This is the default behavior (for models that support it) when prefix caching is enabled. - "align": only cache the mamba state of the last token of each scheduler step and when the token is at position i * block_size.

Default: none

--kv-offloading-size

Size of the KV cache offloading buffer in GiB. When TP > 1, this is the total buffer size summed across all TP ranks. By default, this is set to None, which means no KV offloading is enabled. When set, vLLM will enable KV cache offloading to CPU using the kv_offloading_backend.

--kv-offloading-backend

Possible choices: lmcache, native

The backend to use for KV cache offloading. Supported backends include 'native' (vLLM native CPU offloading), 'lmcache'. KV offloading is only activated when kv_offloading_size is set.

Default: native

OffloadConfig

模型权重卸载配置，旨在降低 GPU 内存使用率。

--offload-backend

可选值：auto, prefetch, uva

权重卸载的后端。选项：- "auto"：根据哪个子配置具有非默认值进行选择（如果 offload_group_size > 0 则为 prefetch，如果 cpu_offload_gb > 0 则为 uva）。- "uva"：UVA (统一虚拟寻址) 零拷贝卸载。- "prefetch"：基于组的层卸载的异步预取。

默认值: auto

--cpu-offload-gb

每个 GPU 卸载到 CPU 的空间（GiB）。默认值为 0，表示不卸载。直观地说，该参数可以看作是一种增加 GPU 内存大小的虚拟方式。例如，如果您有一个 24 GB GPU 并将其设置为 10，则实际上可以将其视为一个 34 GB GPU。然后，您可以加载带有 BF16 权重的 13B 模型，该模型至少需要 26GB GPU 内存。注意，这需要快速的 CPU-GPU 互连，因为模型的一部分在每次模型前向传递时都会从 CPU 内存实时加载到 GPU 内存中。这使用 UVA (统一虚拟寻址) 进行零拷贝访问。

默认值: 0

--cpu-offload-params

目标为 CPU 卸载的参数名称段集合。未匹配的参数不会被卸载。如果此集合为空，参数将被非选择性地卸载，直到达到 cpu_offload_gb 定义的内存限制。示例：- 对于参数名称 "mlp.experts.w2_weight"：- "experts" 或 "experts.w2_weight" 将匹配。- "expert" 或 "w2" 将不会匹配（必须是精确的段）。这允许区分诸如 "w2_weight" 和 "w2_weight_scale" 之类的参数。

默认值：set()

--offload-group-size

将每 N 层分为一组。卸载每组的最后 offload_num_in_group 层。默认值为 0（禁用）。示例：group_size=8, num_in_group=2 卸载层 6,7,14,15,22,23,... 与 cpu_offload_gb 不同，这使用明确的异步预取来隐藏传输延迟。

默认值: 0

--offload-num-in-group

每组要卸载的层数。必须 <= offload_group_size。默认值为 1。

默认值: 1

--offload-prefetch-step

预取提前的层数。较高的值可以隐藏更多延迟，但会占用更多 GPU 内存。默认值为 1。

默认值: 1

--offload-params

目标为预取卸载的参数名称段集合。未匹配的参数不会被卸载。如果此集合为空，则卸载每个被卸载层的所有参数。使用段匹配："w13_weight" 匹配 "mlp.experts.w13_weight" 但不匹配 "mlp.experts.w13_weight_scale"。

默认值：set()

MultiModalConfig

控制多模态模型的行为。

--language-model-only, --no-language-model-only

如果为 True，则通过将所有模态限制设为 0 来禁用所有多模态输入。等同于为每个模态将 --limit-mm-per-prompt 设置为 0。

默认值: False

--limit-mm-per-prompt

每个模态下每个提示词允许的输入项和选项的最大数量。

每个模态默认为 999。

旧格式（仅计数）

可配置格式（带选项）：{"video": {"count": 1, "num_frames": 32, "width": 512, "height": 512}, "image": {"count": 5, "width": 512, "height": 512}}

混合格式（结合两者）：{"image": 16, "video": {"count": 1, "num_frames": 32, "width": 512, "height": 512}}

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: {}

--enable-mm-embeds, --no-enable-mm-embeds

如果为 `True`，则启用传递多模态嵌入：对于 `LLM` 类，这指的是 `multi_modal_data` 下的张量输入；对于兼容 OpenAI 的服务器，这指的是内容为 `"type": "*_embeds"` 的聊天消息。

当为某模态设置 --limit-mm-per-prompt 为 0 并启用此选项时，预计算的嵌入将跳过该模态的计数验证，从而在不加载编码器模块的情况下节省内存，同时仍启用嵌入作为输入。大于 0 的限制仍然适用于嵌入。

警告：如果传递了错误形状的嵌入，vLLM 引擎可能会崩溃。仅对受信任的用户启用此标志！

默认值: False

--media-io-kwargs

传递给处理媒体输入的额外参数，按模态键控。例如，要为视频设置 num_frames，设置 `--media-io-kwargs '{"video": {"num_frames": 40} }'`

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: {}

--mm-processor-kwargs

要转发给模型处理多模态数据（例如图像处理器）的参数。覆盖从 `transformers.AutoProcessor.from_pretrained` 获取的多模态处理器的设置。

可用的覆盖项取决于正在运行的模型。

例如，对于 Phi-3-Vision：`{"num_crops": 4}`。

应为有效的 JSON 字符串或单独传递的 JSON 键。

--mm-processor-cache-gb

多模态处理器缓存的大小（以 GiB 为单位），用于避免重新处理过去的多模态输入。

此缓存为每个 API 进程和引擎核心进程复制，导致总内存使用量为 `mm_processor_cache_gb * (api_server_count + data_parallel_size)`。

设置为 `0` 以完全禁用此缓存（不推荐）。

默认值: 4

--mm-processor-cache-type

可选值: lru, shm

用于多模态预处理器/映射器的缓存类型。如果为 `shm`，使用共享内存 FIFO 缓存。如果为 `lru`，使用镜像 LRU 缓存。

默认值: lru

--mm-shm-cache-max-object-size-mb

存储在多模态处理器共享内存缓存中每个对象的大小限制（以 MiB 为单位）。仅当 `mm_processor_cache_type` 为 `"shm"` 时有效。

默认值: 128

--mm-encoder-only, --no-mm-encoder-only

When enabled, skips the language component of the model.

This is usually only valid in disaggregated Encoder process.

默认值: False

--mm-encoder-tp-mode

可选值: data, weights

指示如何使用张量并行 (TP) 优化多模态编码器推理。

• `"weights"`：在同一个 vLLM 引擎内，将每层的权重在 TP 排名之间分割。（默认 TP 行为）
• `"data"`：在同一个 vLLM 引擎内，将批处理的输入数据在 TP 排名之间分割以并行处理数据，同时在每个 TP 排名上托管完整的权重。此批处理级别的 DP 不应与 API 请求级别的 DP（由 `--data-parallel-size` 控制）混淆。这仅在每个模型的基础上支持，如果编码器不支持 DP，则回退到 `"weights"`。

默认值: weights

--mm-encoder-attn-backend

Optional override for the multi-modal encoder attention backend when using vision transformers. Accepts any value from vllm.v1.attention.backends.registry.AttentionBackendEnum (e.g. FLASH_ATTN).

--mm-encoder-attn-dtype

可选值：fp8、None

ViT 编码器注意力的可选数据类型（dtype）覆盖。设置为 "fp8" 可以通过 FlashInfer cuDNN 后端启用 FP8 量化。在没有缩放文件（scale file）的情况下设置为 "fp8" 时，将自动使用动态缩放。有关详细信息，请参阅 docs/features/quantization/fp8_vit_attn.md。

--mm-encoder-fp8-scale-path

包含 ViT 编码器注意力逐层 FP8 Q/K/V 缩放系数的 JSON 文件路径。提供此项时（伴随 mm_encoder_attn_dtype="fp8"），将使用静态缩放。省略时，将使用动态缩放。

--mm-encoder-fp8-scale-save-path

当配合动态 FP8 缩放设置时（mm_encoder_attn_dtype="fp8" 且没有 mm_encoder_fp8_scale_path），在 amax 历史缓冲区写满后，将校准后的缩放系数保存到此文件中。保存的文件随后可在后续运行中用作 mm_encoder_fp8_scale_path。

--mm-encoder-fp8-scale-save-margin

自动保存时乘以缩放系数的安全裕度。大于 1 的值可留出余量，以便激活值大于校准集的输入不会超出 FP8 范围。默认值为 1.5。

默认值：1.5

--interleave-mm-strings, --no-interleave-mm-strings

在使用 --chat-template-content-format=string 的同时，为多模态提示启用完全交错支持。

默认值: False

--skip-mm-profiling, --no-skip-mm-profiling

启用时，跳过多模态内存分析，仅在引擎初始化期间使用语言主干模型进行分析。

这减少了引擎启动时间，但将估算多模态编码器激活和嵌入缓存的峰值内存使用量的责任转移给了用户。

默认值: False

--video-pruning-rate

通过高效视频采样设置视频修剪率。值在 [0;1) 范围内，并确定要从每个视频中修剪的媒体令牌的分数。

--mm-tensor-ipc

可选值：direct_rpc, torch_shm

多模态张量的 IPC（进程间通信）方法。- "direct_rpc"：通过 RPC 使用 msgspec 序列化 - "torch_shm"：使用 torch.multiprocessing 共享内存进行零拷贝 IPC。默认为 "direct_rpc"。

默认值：direct_rpc

--mm-ipc-gpu-memory-gb

在引擎设备上为 API 服务器（前端）进程中的 GPU 侧多模态工作（如硬件视频解码）预留的 GPU 内存量（以 GiB 为单位）。

此预算是从引擎的 KV 缓存内存中划出的，因此物理上存在可用空间，前端 GPU 解码路径在设备上分配之前会从一个此大小的阻塞字节计数信号量中获取。

设置为 0（默认值）以禁用前端 GPU 多模态内存门控。

默认值: 0

LoRAConfig

LoRA 配置。

--enable-lora, --no-enable-lora

如果为 True，启用对 LoRA 适配器的处理。

--max-loras

单个批次中 LoRA 的最大数量。

默认值: 1

--max-lora-rank

可选值: 1, 8, 16, 32, 64, 128, 256, 320, 512

最大 LoRA 秩。

默认值: 16

--lora-dtype

LoRA 的数据类型。如果为 auto，将默认为基础模型的数据类型。

默认值: auto

--enable-tower-connector-lora, --no-enable-tower-connector-lora

If True, LoRA support for the tower (vision encoder) and connector of multimodal models will be enabled. This is an experimental feature and currently only supports some MM models such as the Qwen VL series. The default is False.

默认值: False

--max-cpu-loras

存储在 CPU 内存中的最大 LoRA 数量。必须 >= `max_loras`。

--fully-sharded-loras, --no-fully-sharded-loras

默认情况下，只有一半的 LoRA 计算与张量并行进行分片。启用此选项将使用完全分片的层。在高序列长度、最大秩或张量并行大小时，这可能会更快。

默认值: False

--lora-target-modules

将 LoRA 限制在特定的模块后缀（例如 ["o_proj", "qkv_proj"]）。如果为 None，则使用所有支持的 LoRA 模块。这允许在部署时控制哪些模块应用 LoRA，对于性能调优非常有用。

--default-mm-loras

将特定模态映射到 LoRA 模型路径的字典；此字段仅适用于多模态模型，并且当模型在给定模态存在时总是期望 LoRA 处于活动状态时应加以利用。请注意，目前，如果请求提供多个附加模态，每个模态都有自己的 LoRA，我们不应用 default_mm_loras，因为我们目前每个提示只支持一个 lora 适配器。在离线模式下运行时，n 个模态的 lora ID 将自动分配为 1-n，模态名称按字母顺序排列。

应为有效的 JSON 字符串或单独传递的 JSON 键。

--specialize-active-lora, --no-specialize-active-lora

Whether to construct lora kernel grid by the number of active LoRA adapters. When set to True, separate cuda graphs will be captured for different counts of active LoRAs (powers of 2 up to max_loras), which can improve performance for variable LoRA usage patterns at the cost of increased startup time and memory usage. Only takes effect when cudagraph_specialize_lora is True.

默认值: False

--enable-mixed-moe-lora-format, --no-enable-mixed-moe-lora-format

如果为 True，无论模型的 is_3d_moe_weight 标志如何，都强制引擎使用通用 2D MoE LoRA 包装器（FusedMoEWithLoRA），以便在同一个部署中提供 2D 格式和 3D 格式的 MoE LoRA 适配器。仅对 MoE 模型有意义；否则会被忽略。默认值 False 会保持现有的由模型驱动的行为。

默认值: False

ObservabilityConfig

可观察性配置 - 指标和追踪。

--show-hidden-metrics-for-version

启用自指定版本以来已隐藏的已弃用 Prometheus 指标。例如，如果一个先前已弃用的指标自 v0.7.0 版本以来已被隐藏，您可以使用 `--show-hidden-metrics-for-version=0.7` 作为临时应急措施，同时迁移到新的指标。该指标很可能会在即将发布的版本中完全移除。

--otlp-traces-endpoint

将发送 OpenTelemetry 追踪的目标 URL。

--collect-detailed-traces

可选值: all, model, worker, None, model,worker, model,all, worker,model, worker,all, all,model, all,worker

仅在设置了 `--otlp-traces-endpoint` 时设置此项才有意义。如果设置，它将为指定的模块收集详细的追踪。这涉及使用可能昂贵和/或阻塞的操作，因此可能会对性能产生影响。

请注意，为每个请求收集详细的计时信息可能会很昂贵。

--kv-cache-metrics, --no-kv-cache-metrics

启用 KV 缓存驻留指标（生命周期、空闲时间、重用间隔）。使用采样来最小化开销。需要启用日志统计信息（即，未设置 --disable-log-stats）。

默认值: False

--kv-cache-metrics-sample

KV 缓存指标的采样率 (0.0, 1.0]。默认 0.01 = 1%% 的块。

默认值: 0.01

--cudagraph-metrics, --no-cudagraph-metrics

启用 CUDA 图指标（填充/未填充令牌的数量、运行时 cudagraph 分派模式，以及它们在每个日志记录间隔观察到的频率）。

默认值: False

--enable-layerwise-nvtx-tracing, --no-enable-layerwise-nvtx-tracing

启用分层 NVTX 追踪。此功能追踪模型中每一层或模块的执行情况，并将输入/输出形状等信息附加到 nvtx 范围标记中。注意，在启用 CUDA 图的情况下此功能不可用。

默认值: False

--enable-mfu-metrics, --no-enable-mfu-metrics

启用模型 FLOPs 利用率（MFU）指标。

默认值: False

--enable-logging-iteration-details, --no-enable-logging-iteration-details

Enable detailed logging of iteration details. If set, vllm EngineCore will log iteration details This includes number of context/generation requests and tokens and the elapsed cpu time for the iteration.

默认值: False

--jit-monitor-mode

可选值: error, warn

如何处理热身后的 JIT 编译事件。

默认值: warn

--jit-monitor-verbose, --no-jit-monitor-verbose

记录每个受监控的 JIT 编译及其运行时详细信息。这可能会发出大量日志并增加开销，因此仅用于调试。

默认值: False

SchedulerConfig

调度器配置。

--max-num-batched-tokens

单次迭代中可处理的最大标记数量。

此处的默认值主要是为了方便测试。在实际使用中，应在 `EngineArgs.create_engine_config` 中设置此值。

解析像 '1k', '2M' 等人类可读的整数。包括带小数乘数的小数值。

Examples:
- '1k' -> 1,000
- '1K' -> 1,024
- '25.6k' -> 25,600

--max-num-scheduled-tokens

调度器在单次迭代中可能发出的最大令牌数量。

这通常等于 max_num_batched_tokens，但在模型可能将令牌附加到批次中（例如推测解码）的情况下，它可能会更小。默认为 max_num_batched_tokens。

解析像 '1k', '2M' 等人类可读的整数。包括带小数乘数的小数值。

Examples:
- '1k' -> 1,000
- '1K' -> 1,024
- '25.6k' -> 25,600

--max-num-seqs

单次迭代中要处理的最大序列数。

此处的默认值主要是为了方便测试。在实际使用中，应在 `EngineArgs.create_engine_config` 中设置此值。

--max-num-partial-prefills

对于分块预填充，可以同时部分预填充的最大序列数。

默认值: 1

--max-long-partial-prefills

对于分块预填充，将同时预填充的、提示长度超过 long_prefill_token_threshold 的最大提示数。将此值设置得小于 max_num_partial_prefills 将允许较短的提示在某些情况下插队到较长提示的前面，从而改善延迟。

默认值: 1

--long-prefill-token-threshold

对于分块预填充，如果提示长于此令牌数量，则认为请求是长请求。0 禁用此上限（默认）。

默认值: 0

--scheduling-policy

可选值: fcfs, priority

要使用的调度策略

• "fcfs" 表示先到先得，即按到达顺序处理请求。
• "priority" 表示根据给定的优先级（值越小表示处理越早）和到达时间（决定平局）处理请求。

默认值: fcfs

--enable-chunked-prefill, --no-enable-chunked-prefill

如果为 True，可以根据剩余的 `max_num_batched_tokens` 对预填充请求进行分块。

此处的默认值主要是为了方便测试。在实际使用中，应在 `EngineArgs.create_engine_config` 中设置此值。

--disable-chunked-mm-input, --no-disable-chunked-mm-input

如果设置为 true 并且启用了分块预填充，我们不希望部分调度多模态项。仅在 V1 中使用。这确保了如果一个请求有混合提示（如文本令牌 TTTT 后跟图像令牌 IIIIIIIIII），其中只有部分图像令牌可以被调度（如 TTTTIIIII，剩下 IIIII），它将被调度为 TTTT 在一个步骤中，IIIIIIIIII 在下一个步骤中。

默认值: False

--scheduler-cls

要使用的调度器类。"vllm.v1.core.sched.scheduler.Scheduler" 是默认调度器。可以是一个类本身，也可以是 "mod.custom_class" 形式的类路径。

--scheduler-reserve-full-isl, --no-scheduler-reserve-full-isl

如果为 True，调度程序在接收新请求前会检查完整输入序列长度是否适配 KV 缓存，而不是仅检查第一个块。可防止 chunked prefill 导致的过度接纳和 KV 缓存抖动。

默认值: True

--watermark

在将等待或被抢占的请求加入运行队列时，保留的总 KV 缓存块的空闲比例（即水印）。当 GPU 内存稀缺时，此预留空间有助于避免频繁的 KV 缓存逐出以及由此导致的请求重复抢占。必须在范围 [0.0, 1.0) 内；0.0（默认值）禁用水印。

默认值：0.0

--prefill-schedule-interval

对于数据并行部署，每 N 个引擎步骤（在所有 DP 排名中对齐）才接受新的预填充请求，以更好地平衡每步骤的前向传递时间。

默认值: 1

--disable-hybrid-kv-cache-manager, --no-disable-hybrid-kv-cache-manager

如果设置为 True，KV 缓存管理器将为所有注意力层分配相同大小的 KV 缓存，即使存在多种类型的注意力层，如全注意力层和滑动窗口注意力层。如果设置为 None，则默认值将根据环境和启动配置确定。

--async-scheduling, --no-async-scheduling

If set to False, disable async scheduling. Async scheduling helps to avoid gaps in GPU utilization, leading to better latency and throughput.

--stream-interval

流式传输的间隔（或缓冲区大小），以令牌长度为单位。较小的值（1）通过立即发送每个令牌使流式传输更平滑，而较大的值（例如 10）通过在发送前批处理多个令牌来减少主机开销并可能增加吞吐量。

默认值: 1

CompilationConfig

编译配置。

You must pass CompilationConfig to VLLMConfig constructor.
VLLMConfig's post_init does further initialization. If used outside of the
VLLMConfig, some fields will be left in an improper state.

It contains PassConfig, which controls the custom fusion/transformation passes.
The rest has three parts:

- Top-level Compilation control:
    - [`mode`][vllm.config.CompilationConfig.mode]
    - [`debug_dump_path`][vllm.config.CompilationConfig.debug_dump_path]
    - [`cache_dir`][vllm.config.CompilationConfig.cache_dir]
    - [`backend`][vllm.config.CompilationConfig.backend]
    - [`custom_ops`][vllm.config.CompilationConfig.custom_ops]
    - [`splitting_ops`][vllm.config.CompilationConfig.splitting_ops]
    - [`compile_mm_encoder`][vllm.config.CompilationConfig.compile_mm_encoder]
- CudaGraph capture:
    - [`cudagraph_mode`][vllm.config.CompilationConfig.cudagraph_mode]
    - [`cudagraph_capture_sizes`]
    [vllm.config.CompilationConfig.cudagraph_capture_sizes]
    - [`max_cudagraph_capture_size`]
    [vllm.config.CompilationConfig.max_cudagraph_capture_size]
    - [`cudagraph_num_of_warmups`]
    [vllm.config.CompilationConfig.cudagraph_num_of_warmups]
    - [`cudagraph_copy_inputs`]
    [vllm.config.CompilationConfig.cudagraph_copy_inputs]
- Inductor compilation:
    - [`compile_sizes`][vllm.config.CompilationConfig.compile_sizes]
    - [`compile_ranges_endpoints`]
        [vllm.config.CompilationConfig.compile_ranges_endpoints]
    - [`inductor_compile_config`]
    [vllm.config.CompilationConfig.inductor_compile_config]
    - [`inductor_passes`][vllm.config.CompilationConfig.inductor_passes]
    - custom inductor passes

Why we have different sizes for cudagraph and inductor:
- cudagraph: a cudagraph captured for a specific size can only be used
    for the same size. We need to capture all the sizes we want to use.
- inductor: a graph compiled by inductor for a general shape can be used
    for different sizes. Inductor can also compile for specific sizes,
    where it can have more information to optimize the graph with fully
    static shapes. However, we find the general shape compilation is
    sufficient for most cases. It might be beneficial to compile for
    certain small batchsizes, where inductor is good at optimizing.

--cudagraph-capture-sizes

捕获 cudagraph 的大小。- None (默认)：捕获大小从 vllm 配置中推断。- list[int]：捕获大小按给定值指定。

--max-cudagraph-capture-size

最大 cudagraph 捕获大小。

如果指定了 cudagraph_capture_sizes，此值将设置为该列表中的最大大小（或在指定时检查一致性）。如果未指定 cudagraph_capture_sizes，则会自动生成大小列表，遵循模式

[1, 2, 4] + list(range(8, 256, 8)) + list(
range(256, max_cudagraph_capture_size + 1, 16))

如果未指定，max_cudagraph_capture_size 默认为 min(max_num_seqs*2, 512)。这可以在内存紧张且 max_num_seqs 较小的情况下避免 OOM，并防止捕获许多大型图（>512），这会大大增加启动时间而性能提升有限。

KernelConfig

内核选择和预热行为的配置。

--ir-op-priority

前向传递期间用于调度/降低的 vLLM IR 操作优先级。平台默认值会在 VllmConfig.post_init 期间自动添加。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.IrOpPriorityConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值：IrOpPriorityConfig(rms_norm=[], fused_add_rms_norm=[])

--enable-flashinfer-autotune, --no-enable-flashinfer-autotune

如果为 True，则在内核预热期间运行 FlashInfer 自动调优。

--moe-backend

可选值: aiter, auto, cutlass, deep_gemm, deep_gemm_mega_moe, emulation, flashinfer_b12x, flashinfer_cutedsl, flashinfer_cutlass, flashinfer_trtllm, flydsl, hpc, humming, marlin, triton, triton_unfused

MoE 专家计算内核的后端。可用选项：

• "auto"：根据模型和硬件自动选择最佳后端
• "triton"：使用基于 Triton 的融合 MoE 内核
• "deep_gemm"：使用 DeepGEMM 内核（仅限 FP8 块量化）
• "deep_gemm_mega_moe"：使用 DeepGEMM mega MoE 内核
• "cutlass"：使用 vLLM CUTLASS 内核
• "flashinfer_trtllm"：使用带 TRTLLM-GEN 内核的 FlashInfer
• "flashinfer_cutlass"：使用带 CUTLASS 内核的 FlashInfer
• "flashinfer_cutedsl"：使用带 CuteDSL 内核的 FlashInfer（仅限 FP4）
• "flashinfer_b12x"：为 SM12x (RTX Pro 6000 / DGX Spark) 使用 FlashInfer CuteDSL 融合 MoE
• "marlin"：使用 Marlin 内核（仅权重权重量化）
• "humming"：使用 Humming 混合精度内核
• "triton_unfused"：使用 Triton 未融合的 MoE 内核
• "aiter"：使用 AMD AITer 内核（仅限 ROCm）
• "flydsl"：使用 AMD FlyDSL 内核（仅限 ROCm）
• "hpc"：使用 HPC 内核（仅限 FP8 和 Hopper）
• "emulation"：使用 BF16/FP16 GEMM，对权重进行反量化并在激活值上运行 QDQ。

默认值: auto

--linear-backend

可选值: aiter, auto, conch, cutlass, deep_gemm, emulation, exllama, fbgemm, flashinfer_b12x, flashinfer_cudnn, flashinfer_cutedsl, flashinfer_cutlass, flashinfer_trtllm, humming, machete, marlin, torch, triton, xpu, xpu_woq

量化线性层 GEMM 内核的后端。可用选项包括：

• "auto"：根据模型和硬件自动选择最佳后端
• "cutlass"：使用基于 CUTLASS 的内核
• "flashinfer_cutlass"：使用带 CUTLASS 内核的 FlashInfer
• "flashinfer_cutedsl"：将 FlashInfer 与 CuTe-DSL 内核（NVFP4, MXFP8）结合使用
• "flashinfer_trtllm"：使用带有 TensorRT-LLM 内核的 FlashInfer
• "flashinfer_cudnn"：使用带有 cuDNN 内核的 FlashInfer
• "flashinfer_b12x"：使用 FlashInfer b12x CuteDSL NVFP4 GEMM (SM120+)
• "marlin"：使用 Marlin 内核
• "triton"：使用基于 Triton 的内核
• "deep_gemm"：使用 DeepGEMM 内核
• "torch"：使用 PyTorch 原生 scaled_mm 内核
• "aiter"：使用 AMD AITer 内核（仅限 ROCm）
• "machete"：使用 Machete 内核（混合精度）
• "fbgemm"：使用 FBGEMM 内核
• "conch"：使用 Conch 混合精度内核
• "exllama"：使用 Exllama 混合精度内核
• "emulation"：使用慢速反量化至 BF16 的模拟（仅用于测试）
• "xpu"：使用 XPU 内核
• "xpu_woq"：对仅权重量化（例如 W8A16）使用 XPU 内核

默认值: auto

VllmConfig

包含所有 vllm 相关配置的数据类。这简化了在代码库中传递不同配置的过程。

--speculative-config, -sc

推测解码配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.SpeculativeConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--spec-method

可选值: bailing_hybrid_mtp, custom_class, deepseek_mtp, dflash, draft_model, dspark, eagle, eagle3, ernie_mtp, exaone4_5_mtp, exaone_moe_mtp, extract_hidden_states, gemma4_mtp, glm4_moe_lite_mtp, glm4_moe_mtp, glm_ocr_mtp, hy_v3_mtp, longcat_flash_mtp, medusa, mimo_mtp, mimo_v2_mtp, minimax_m3_mtp, mlp_speculator, mtp, nemotron_h_mtp, ngram, ngram_gpu, pangu_ultra_moe_mtp, qwen3_5_mtp, qwen3_next_mtp, step3p5_mtp, suffix, None

要使用的推测性方法（speculative method）的名称。如果用户提供并设置了 model 参数，在可能的情况下，系统会自动检测推测性方法类型；如果未提供 model 参数，则必须提供该方法名称。

如果使用 ngram 方法，应考虑相关配置 prompt_lookup_max 和 prompt_lookup_min。

--spec-model

草稿模型（draft model）、eagle 头或附加权重的名称（如果提供）。

--spec-tokens

推测性标记（speculative tokens）的数量（如果提供）。如果存在草稿模型配置，它将默认使用其中的数量，否则该项是必需的。

--diffusion-config, -dc

扩散式 LLM (dLLM) 配置。

API 文档: https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.DiffusionConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--kv-transfer-config

分布式 KV 缓存传输的配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.KVTransferConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--kv-events-config

事件发布的配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.KVEventsConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--ec-transfer-config

分布式 EC 缓存传输的配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.ECTransferConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--compilation-config, -cc

模型的 `torch.compile` 和 cudagraph 捕获配置。

作为简写，可以通过 -cc.parameter=argument 附加编译参数，例如 `-cc.mode=3` (与 `-cc='{"mode":3}'` 相同)。

您可以像这样指定完整的编译配置：`{"mode": 3, "cudagraph_capture_sizes": [1, 2, 4, 8]}`

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.CompilationConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: {'mode': None, 'debug_dump_path': None, 'cache_dir': '', 'compile_cache_save_format': 'binary', 'backend': 'inductor', 'custom_ops': [], 'ir_enable_torch_wrap': None, 'splitting_ops': None, 'compile_mm_encoder': False, 'cudagraph_mm_encoder': False, 'encoder_cudagraph_token_budgets': [], 'encoder_cudagraph_max_vision_items_per_batch': 0, 'encoder_cudagraph_max_frames_per_batch': None, 'compile_sizes': None, 'compile_ranges_endpoints': None, 'inductor_compile_config': {'enable_auto_functionalized_v2': False, 'combo_kernels': True, 'benchmark_combo_kernel': True}, 'inductor_passes': {}, 'cudagraph_mode': None, 'cudagraph_num_of_warmups': 0, 'cudagraph_capture_sizes': None, 'cudagraph_copy_inputs': False, 'cudagraph_specialize_lora': True, 'use_inductor_graph_partition': None, 'pass_config': {}, 'max_cudagraph_capture_size': None, 'dynamic_shapes_config': {'type': <DynamicShapesType.BACKED: 'backed'>, 'evaluate_guards': False, 'assume_32_bit_indexing': False}, 'local_cache_dir': None, 'fast_moe_cold_start': None, 'static_all_moe_layers': []}

--attention-config, -ac

注意力配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.AttentionConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: AttentionConfig(backend=None, flash_attn_version=None, use_prefill_decode_attention=False, flash_attn_max_num_splits_for_cuda_graph=32, tq_max_kv_splits_for_cuda_graph=32, use_trtllm_attention=None, disable_flashinfer_q_quantization=False, mla_prefill_backend=None, use_prefill_query_quantization=False, use_fp4_indexer_cache=False, indexer_kv_dtype='bf16', use_non_causal=False, sparse_mla_force_mqa=False, flex_attn_block_m=None, flex_attn_block_n=None, flex_attn_q_block_size=None, flex_attn_kv_block_size=None)

--reasoning-config

推理模型的配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.ReasoningConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

--kernel-config

内核配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.KernelConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值: KernelConfig(ir_op_priority=IrOpPriorityConfig(rms_norm=[], fused_add_rms_norm=[]), enable_flashinfer_autotune=None, enable_cutedsl_warmup=True, moe_backend='auto', linear_backend='auto')

--additional-config

用于指定平台的附加配置。不同平台可能支持不同的配置。请确保所用配置对您使用的平台有效。内容必须是可哈希的。

默认值: {}

--structured-outputs-config

结构化输出配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.StructuredOutputsConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值：StructuredOutputsConfig(backend='auto', disable_any_whitespace=False, disable_additional_properties=False, reasoning_parser='', reasoning_parser_plugin='', enable_in_reasoning=False)

--profiler-config

分析配置。

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.ProfilerConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。

默认值：ProfilerConfig(profiler=None, torch_profiler_dir='', torch_profiler_with_stack=True, torch_profiler_with_flops=False, torch_profiler_use_gzip=True, torch_profiler_dump_cuda_time_total=True, torch_profiler_record_shapes=False, torch_profiler_with_memory=False, ignore_frontend=False, delay_iterations=0, max_iterations=0, warmup_iterations=0, active_iterations=5, wait_iterations=0)

--optimization-level

优化级别。这些级别在启动时间成本和性能之间进行权衡，-O0 具有最佳启动时间，-O3 具有最佳性能。默认使用 -O2。请参阅 OptimizationLevel 获取完整描述。

默认：2

--performance-mode

可选值：balanced, interactivity, throughput

运行时行为的性能模式，默认为 'balanced'。'interactivity' 在小批处理大小时偏向于低端到端每请求延迟（细粒度 CUDA 图，延迟导向内核）。'throughput' 在高并发下偏向于聚合的 tokens/sec（更大的 CUDA 图，更激进的批处理，吞吐量导向内核）。

默认值：balanced

--weight-transfer-config

The configurations for weight transfer during RL training.

API 文档：https://docs.vllm.com.cn/en/latest/api/vllm/config/#vllm.config.WeightTransferConfig

应为有效的 JSON 字符串或单独传递的 JSON 键。