最近在部署Deepseek V4模型，顺便更新一下对应的VLLM最新的中文参数，0.7.2版本的连接

0.20.1版本已经翻天覆地了

• CLI 架构重构
• Engine 调度器升级
• V1/V0 engine 演进
• 多模态体系重写
• structured output/tool calling 完整增强
• DeepSeek V4/Qwen3/Gemma3 等新模型体系支持
• CUDA / FlashInfer / FP8 / MLA / MoE 大规模优化
• OpenAI API 兼容层重构

很多命令的行为、参数、默认值都变了，版本做的中文翻译对照，参数由模型自动翻译，可能存在不准确情况，使用时仔细甄别，我只用了一部分参数。格式为markdown直接复制就可以

• vllm serve

## JSON CLI 参数

当传递 JSON CLI 参数时，以下几组参数是等价的：

```
--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'
```

---

## 通用参数

### `--headless`
以无头模式运行。详情请参考多节点数据并行文档。

**默认值：** `False`

### `--api-server-count, -asc`
要运行的 API 服务器进程数量。如果未指定，默认为 `data_parallel_size`。

### `--config`
从配置文件读取 CLI 选项。必须是包含以下选项的 YAML 文件：https://docs.vllm.ai/en/latest/configuration/serve_args.html

### `--grpc`
启动 gRPC 服务器而不是 HTTP OpenAI 兼容服务器。需要：`pip install vllm[grpc]`。

**默认值：** `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`

选择 GDN prefill 后端。

### `--enable-log-requests, --no-enable-log-requests`
启用请求信息日志记录，取决于日志级别：
- INFO：请求 ID、参数和 LoRA 请求。
- DEBUG：提示输入（例如：文本、token ID）。

可通过 `VLLM_LOGGING_LEVEL` 设置最低日志级别。

**默认值：** `False`

---

## Frontend（前端）

OpenAI 兼容前端服务器的参数。

### `--lora-modules`
LoRA 模块配置。

### `--chat-template`
聊天模板路径或名称。

### `--chat-template-content-format`
**可选值：** `auto`, `openai`, `string`

**默认值：** `auto`

### `--trust-request-chat-template, --no-trust-request-chat-template`
是否信任请求中的聊天模板。

**默认值：** `False`

### `--default-chat-template-kwargs`
默认聊天模板关键字参数。应为有效的 JSON 字符串或逐个传递的 JSON 键值。

### `--response-role`
响应角色名称。

**默认值：** `assistant`

### `--return-tokens-as-token-ids, --no-return-tokens-as-token-ids`
是否以 token ID 形式返回 tokens。

**默认值：** `False`

### `--enable-auto-tool-choice, --no-enable-auto-tool-choice`
是否启用自动工具选择。

**默认值：** `False`

### `--exclude-tools-when-tool-choice-none, --no-exclude-tools-when-tool-choice-none`
当 `tool_choice` 为 `none` 时是否排除工具。

**默认值：** `False`

### `--tool-call-parser`
工具调用解析器。

### `--tool-parser-plugin`
工具解析器插件路径。

**默认值：** `""`

### `--tool-server`
工具服务器配置。

### `--log-config-file`
日志配置文件路径。

### `--max-log-len`
日志最大长度。

### `--enable-prompt-tokens-details, --no-enable-prompt-tokens-details`
是否启用提示 token 详细信息。

**默认值：** `False`

### `--enable-server-load-tracking, --no-enable-server-load-tracking`
是否启用服务器负载跟踪。

**默认值：** `False`

### `--enable-force-include-usage, --no-enable-force-include-usage`
是否强制在流式响应中包含 usage 字段。

**默认值：** `False`

### `--enable-tokenizer-info-endpoint, --no-enable-tokenizer-info-endpoint`
是否启用分词器信息端点。

**默认值：** `False`

### `--enable-log-outputs, --no-enable-log-outputs`
是否记录输出内容。

**默认值：** `False`

### `--enable-log-deltas, --no-enable-log-deltas`
是否记录增量内容。

**默认值：** `True`

### `--log-error-stack, --no-log-error-stack`
是否记录错误堆栈。

**默认值：** `False`

### `--tokens-only, --no-tokens-only`
是否仅返回 tokens（不包含文本）。

**默认值：** `False`

### `--host`
主机名。

### `--port`
端口号。

**默认值：** `8000`

### `--uds`
Unix 域套接字路径。如果设置，将忽略 `host` 和 `port` 参数。

### `--uvicorn-log-level`
**可选值：** `critical`, `debug`, `error`, `info`, `trace`, `warning`

uvicorn 的日志级别。

**默认值：** `info`

### `--disable-uvicorn-access-log, --no-disable-uvicorn-access-log`
禁用 uvicorn 访问日志。

**默认值：** `False`

### `--disable-access-log-for-endpoints`
要从 uvicorn 访问日志中排除的端点路径列表（逗号分隔）。用于减少健康检查等高频端点的日志噪音。例如：`"/health,/metrics,/ping"`。设置后，对这些路径的请求访问日志将被抑制，同时保留其他端点的日志。

### `--allow-credentials, --no-allow-credentials`
是否允许凭据。

**默认值：** `False`

### `--allowed-origins`
允许的来源。

**默认值：** `['*']`

### `--allowed-methods`
允许的 HTTP 方法。

**默认值：** `['*']`

### `--allowed-headers`
允许的 HTTP 头。

**默认值：** `['*']`

### `--api-key`
如果提供，服务器将要求请求头中携带这些密钥之一。

### `--ssl-keyfile`
SSL 密钥文件路径。

### `--ssl-certfile`
SSL 证书文件路径。

### `--ssl-ca-certs`
CA 证书文件路径。

### `--enable-ssl-refresh, --no-enable-ssl-refresh`
SSL 证书文件更改时刷新 SSL 上下文。

**默认值：** `False`

### `--ssl-cert-reqs`
是否要求客户端证书（参见 stdlib ssl 模块）。

**默认值：** `0`

### `--ssl-ciphers`
HTTPS 的 SSL 加密套件（仅适用于 TLS 1.2 及以下）。例如：`'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305'`

### `--root-path`
当应用位于基于路径的路由代理后面时的 FastAPI `root_path`。

### `--middleware`
要应用于应用的额外 ASGI 中间件。可接受多个 `--middleware` 参数。值应为导入路径。如果提供函数，vLLM 将使用 `@app.middleware('http')` 添加；如果提供类，则使用 `app.add_middleware()` 添加。

**默认值：** `[]`

### `--enable-request-id-headers, --no-enable-request-id-headers`
如果指定，API 服务器将在响应中添加 `X-Request-Id` 头。

**默认值：** `False`

### `--disable-fastapi-docs, --no-disable-fastapi-docs`
禁用 FastAPI 的 OpenAPI schema、Swagger UI 和 ReDoc 端点。

**默认值：** `False`

### `--h11-max-incomplete-event-size`
h11 解析器允许的不完整 HTTP 事件（头部或正文）的最大大小（字节）。有助于缓解头部滥用。默认：4194304（4 MB）。

**默认值：** `4194304`

### `--h11-max-header-count`
h11 解析器允许的 HTTP 请求头最大数量。有助于缓解头部滥用。默认：256。

**默认值：** `256`

### `--enable-offline-docs, --no-enable-offline-docs`
为隔离环境启用离线 FastAPI 文档。使用 vLLM 捆绑的静态资源。

**默认值：** `False`

### `--enable-flash-late-interaction, --no-enable-flash-late-interaction`
如果设置，在 API 服务器进程中于 GPU 上运行 MaxSim 池化评分。可显著提升延迟交互评分性能。

**默认值：** `True`

---

## ModelConfig（模型配置）

模型的配置。

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

**默认值：** `Qwen/Qwen3-0.6B`

### `--runner`
**可选值：** `auto`, `draft`, `generate`, `pooling`

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

**默认值：** `auto`

### `--convert`
**可选值：** `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` 的分词器。

其他自定义值可通过插件支持。

**默认值：** `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`
用于可重复性的随机种子。

必须设置全局种子，否则不同的张量并行工作进程将采样不同的 token，导致结果不一致。

**默认值：** `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` 或 `'auto'` -> 自动选择适合 GPU 内存的最大模型长度。如果模型的上下文长度能容纳则使用它，否则找到可容纳的最大长度。

解析可读整数，如 `'1k'`、`'2M'` 等，包括带小数乘数的十进制值。也接受 `-1` 或 `'auto'` 作为自动检测的特殊值。

### `--quantization, -q`
用于量化权重的方法。如果为 None，首先检查模型配置文件中的 `quantization_config` 属性。如果也为 None，则假设模型权重未量化，并使用 `dtype` 确定权重的数据类型。

### `--allow-deprecated-quantization, --no-allow-deprecated-quantization`
是否允许使用已弃用的量化方法。

**默认值：** `False`

### `--enforce-eager, --no-enforce-eager`
是否始终使用 eager 模式 PyTorch。如果为 True，将禁用 CUDA graph 并始终以 eager 模式执行模型。如果为 False，将混合使用 CUDA graph 和 eager 执行以获得最大性能和灵活性。

**默认值：** `False`

### `--enable-return-routed-experts, --no-enable-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`：原始 logits
4. `processed_logits`：处理后 logits

"原始"表示在应用任何 logit 处理器（如禁用词）之前的值。"处理后"表示应用所有处理器后的值，包括温度参数和 top_k/top_p。

**默认值：** `raw_logprobs`

### `--disable-sliding-window, --no-disable-sliding-window`
是否禁用滑动窗口。如果为 True，将禁用模型的滑动窗口功能，限制到滑动窗口大小。如果模型不支持滑动窗口，此参数将被忽略。

**默认值：** `False`

### `--disable-cascade-attn, --no-disable-cascade-attn`
为 V1 禁用级联注意力。虽然级联注意力不会改变数学正确性，但禁用它可能有助于防止潜在的数值问题。默认值为 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`
用于远程文件的 HTTP Bearer 授权的 token。如果为 True，将使用运行 `hf auth login` 时生成的 token（存储在 `~/.cache/huggingface/token`）。

### `--hf-overrides`
如果为字典，包含要转发到 Hugging Face 配置的参数。如果为可调用对象，则调用它来更新 HuggingFace 配置。

**默认值：** `{}`

### `--pooler-config`
池化器配置，控制池化模型中输出池化的行为。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

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

**默认值：** `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`

### `--model-impl`
**可选值：** `auto`, `terratorch`, `transformers`, `vllm`

使用哪种模型实现：
- `auto`：尝试使用 vLLM 的实现（如果存在），如果不可用则回退到 Transformers 实现。
- `vllm`：使用 vLLM 模型实现。
- `transformers`：使用 Transformers 模型实现。
- `terratorch`：使用 TerraTorch 模型实现。

**默认值：** `auto`

### `--override-attention-dtype`
覆盖注意力的数据类型。

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

### `--io-processor-plugin`
在模型启动时加载的 IOProcessor 插件名称。

### `--renderer-num-workers`
渲染器线程池中的工作线程数。此线程池处理异步分词、聊天模板渲染和多模态预处理。

**默认值：** `1`

---

## LoadConfig（加载配置）

模型权重加载的配置。

### `--load-format`
要加载的模型权重格式：
- `auto`：尝试以 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`：从预分片检查点文件加载权重，支持高效加载张量并行模型。
- `gguf`：从 GGUF 格式文件加载权重。
- `mistral`：从 Mistral 模型使用的合并 safetensors 文件加载权重。

其他自定义值可通过插件支持。

**默认值：** `auto`

### `--download-dir`
下载和加载权重的目录，默认为 Hugging Face 的默认缓存目录。

### `--safetensors-load-strategy`
指定 safetensors 权重的加载策略：
- None（默认）：使用内存映射（延迟）加载。当检测到 NFS 文件系统且总检查点大小在可用 RAM 的 90% 以内时，会自动启用预取。
- `lazy`：从文件内存映射权重。这启用按需加载，对于本地存储上的模型非常高效。与默认值（None）不同，不会在 NFS 上执行自动预取。
- `eager`：在加载前将整个文件读入 CPU 内存。推荐用于网络文件系统（如 Lustre、NFS）上的模型，因为它避免了低效的随机读取，显著加快模型初始化速度。但使用更多 CPU RAM。
- `prefetch`：在 worker 加载之前将检查点文件读入操作系统页面缓存，加快模型加载阶段。适用于网络或高延迟存储。
- `torchao`：先加载权重，然后重建为 torchao 张量子类。用于使用 torchao 量化并使用 safetensors 保存检查点的情况。需要 torchao >= 0.14.0。

### `--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` 中 `map_location` 参数的原始文档。

**默认值：** `cpu`

---

## AttentionConfig（注意力配置）

vLLM 中注意力机制的配置。

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

---

## MambaConfig（Mamba 配置）

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`

用于分布式模型 worker 的后端，`"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 为 600s）。在模型下载可能较慢的多节点设置中增加此值。

### `--numa-bind, --no-numa-bind`
为 GPU worker 子进程启用 NUMA 绑定。

**默认值：** `False`

### `--numa-bind-nodes`
将每个 GPU worker 绑定到的 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 worker 绑定到的可选 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"`。

### `--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` 个 token，然后在 `total_cp_rank i+1` 上存储下一个 `interleave_size` 个 token。
- `Interleave_size=1`：token 级别对齐，token i 存储在 `total_cp_rank i %% total_cp_world_size` 上。
- `Interleave_size=block_size`：块级别对齐，token 首先填充到前面的秩。只有在（秩 i，块 j）完全占用后，token 才会存储在（秩 i+1，块 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`
此实例的数据并行秩。设置后，启用外部负载均衡器模式。

### `--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`。启用后，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 中的"one-pod-per-rank"宽 EP 设置。当显式向 `vllm serve` 提供 `--data-parallel-rank` 时隐式设置。

**默认值：** `False`

### `--enable-expert-parallel, --no-enable-expert-parallel, -ep`
对 MoE 层使用专家并行而不是张量并行。

**默认值：** `False`

### `--enable-ep-weight-filter, --no-enable-ep-weight-filter`
在专家并行激活时，在模型加载期间跳过非本地专家权重。每个秩只从磁盘读取自己的专家分片，这可以大幅减少具有逐专家权重张量的 MoE 模型（如 DeepSeek、Mixtral、Kimi-K2.5）的存储 I/O。对 3D 融合专家检查点（如 GPT-OSS）或非 MoE 模型无影响。

**默认值：** `False`

### `--all2all-backend`
**可选值：** `allgather_reducescatter`, `deepep_high_throughput`, `deepep_low_latency`, `flashinfer_all2allv`, `flashinfer_nvlink_one_sided`, `flashinfer_nvlink_two_sided`, `mori`, `naive`, `nixl_ep`, `pplx`

MoE 专家并行通信的 All2All 后端。可用选项：
- `allgather_reducescatter`：基于 allgather 和 reducescatter 的 All2all
- `deepep_high_throughput`：使用 deepep 高吞吐量内核
- `deepep_low_latency`：使用 deepep 低延迟内核
- `mori`：使用 mori 内核
- `nixl_ep`：使用 nixl-ep 内核
- `flashinfer_nvlink_two_sided`：使用 flashinfer 双侧内核用于 mnnvl
- `flashinfer_nvlink_one_sided`：使用 flashinfer 高吞吐量 a2a 内核

**默认值：** `allgather_reducescatter`

### `--enable-dbo, --no-enable-dbo`
为模型执行器启用双批次重叠。

**默认值：** `False`

### `--ubatch-size`
微批次大小。

**默认值：** `0`

### `--enable-elastic-ep, --no-enable-elastic-ep`
为 DP/EP 启用弹性专家并行，使用无状态 NCCL 组。

**默认值：** `False`

### `--dbo-decode-token-threshold`
仅包含解码的批次的双批次重叠阈值。如果请求中的 token 数大于此阈值，将使用微分批。否则，请求将在单个批次中处理。

**默认值：** `32`

### `--dbo-prefill-token-threshold`
包含一个或多个预填充的批次的双批次重叠阈值。如果请求中的 token 数大于此阈值，将使用微分批。否则，请求将在单个批次中处理。

**默认值：** `512`

### `--disable-nccl-for-dp-synchronization, --no-disable-nccl-for-dp-synchronization`
强制 `vllm/v1/worker/dp_utils.py` 中的 DP 同步逻辑使用 Gloo 而不是 NCCL 进行 all reduce。

启用异步调度时默认为 True，否则为 False。

### `--enable-eplb, --no-enable-eplb`
为 MoE 层启用专家并行负载均衡。

**默认值：** `False`

### `--eplb-config`
专家并行配置。

API 文档：https://docs.vllm.ai/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=False, 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`
按顺序多批次加载模型时的最大并行加载 worker 数。用于在使用张量并行和大型模型时避免 RAM 内存不足。

### `--ray-workers-use-nsight, --no-ray-workers-use-nsight`
是否使用 nsight 分析 Ray worker，参见 https://docs.ray.io/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`
以 token 数量表示的连续缓存块大小。接受 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'` 等，包括带小数乘数的十进制值。

示例：
- `'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`, `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`
是否启用前缀缓存。

### `--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），某些层可以跳过与预填充对应的 token。此标志允许符合条件的层的注意力元数据被覆盖，以实现在某些模型（如 Gemma3n）中实现此优化所需的元数据。

**默认值：** `False`

### `--mamba-cache-dtype`
**可选值：** `auto`, `float16`, `float32`

用于 Mamba 缓存（卷积状态和 SSM 状态）的数据类型。如果设置为 `'auto'`，将从模型配置中推断数据类型。

**默认值：** `auto`

### `--mamba-ssm-cache-dtype`
**可选值：** `auto`, `float16`, `float32`

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

**默认值：** `auto`

### `--mamba-block-size`
mamba 缓存的连续缓存块大小（以 token 数量计）。仅当启用前缀缓存时才能设置。值必须是 8 的倍数，以与 `causal_conv1d` 内核对齐。

### `--mamba-cache-mode`
**可选值：** `align`, `all`, `none`

Mamba 层的缓存策略：
- `none`：在前缀缓存禁用时设置。
- `all`：缓存位置 `i * block_size` 处所有 token 的 mamba 状态。这是启用前缀缓存时的默认行为（对于支持它的模型）。
- `align`：仅缓存每个调度步骤最后一个 token 以及 token 位于位置 `i * block_size` 时的 mamba 状态。

**默认值：** `none`

### `--kv-offloading-size`
KV 缓存卸载缓冲区大小（GiB）。当 TP > 1 时，这是所有 TP 秩的总缓冲区大小。默认设置为 None，表示不启用 KV 卸载。设置后，vLLM 将使用 `kv_offloading_backend` 启用 KV 缓存卸载到 CPU。

### `--kv-offloading-backend`
**可选值：** `lmcache`, `native`

用于 KV 缓存卸载的后端。支持的后端包括 `'native'`（vLLM 原生 CPU 卸载）、`'lmcache'`。仅当设置 `kv_offloading_size` 时才激活 KV 卸载。

**默认值：** `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。然后您可以加载需要至少 26GB GPU 内存的 13B 模型 BF16 权重。注意，这需要快速的 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，启用在 API 请求中直接传入多模态嵌入向量。

**默认值：** `False`

---

## LoRAConfig（LoRA 配置）

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`
如果为 True，将启用多模态模型的塔（视觉编码器）和连接器的 LoRA 支持。这是实验性功能，目前仅支持部分多模态模型（如 Qwen VL 系列）。默认为 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`
是否根据活动 LoRA 适配器数量构建 lora 内核网格。设置为 True 时，将为不同数量的活动 LoRA（最大到 `max_loras` 的 2 的幂）捕获单独的 CUDA graph，这可以提高可变 LoRA 使用模式的性能，但会增加启动时间和内存使用。仅在 `cudagraph_specialize_lora` 为 True 时生效。

**默认值：** `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 graph 指标（填充/未填充 token 数、运行时 cudagraph 调度模式及其在每个日志记录间隔观察到的频率）。

**默认值：** `False`

### `--enable-layerwise-nvtx-tracing, --no-enable-layerwise-nvtx-tracing`
启用逐层 NVTX 追踪。这将追踪模型中每层或每个模块的执行，并将输入/输出形状等信息附加到 nvtx 范围标记。注意，这在启用 CUDA graph 时不工作。

**默认值：** `False`

### `--enable-mfu-metrics, --no-enable-mfu-metrics`
启用模型 FLOPs 利用率（MFU）指标。

**默认值：** `False`

### `--enable-logging-iteration-details, --no-enable-logging-iteration-details`
启用迭代详细信息的日志记录。如果设置，vllm EngineCore 将记录迭代详细信息，包括上下文/生成请求和 token 的数量以及迭代的 CPU 时间消耗。

**默认值：** `False`

---

## SchedulerConfig（调度器配置）

调度器配置。

### `--max-num-batched-tokens`
单次迭代中可处理的最大 token 数量。

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

解析可读整数，如 `'1k'`、`'2M'` 等，包括带小数乘数的十进制值。

示例：
- `'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`
对于分块预填充，如果提示超过此 token 数，则请求被视为长请求。

**默认值：** `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 中使用。这确保如果请求有混合提示（如文本 token TTTT 后跟图像 token IIIIIIIIII），其中只能调度部分图像 token（如 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 缓存，而不仅仅是检查第一个块。防止分块预填充时的过度接纳和 KV 缓存抖动。

**默认值：** `True`

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

### `--async-scheduling, --no-async-scheduling`
如果设置为 False，禁用异步调度。异步调度有助于避免 GPU 利用率间隙，从而提高延迟和吞吐量。

### `--stream-interval`
流式传输的间隔（或缓冲区大小），以 token 长度计。较小的值（1）通过立即发送每个 token 使流式传输更平滑，而较大的值（例如 10）通过批量发送多个 token 减少主机开销并可能提高吞吐量。

**默认值：** `1`

---

## CompilationConfig（编译配置）

编译配置。

### `--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` 较小的场景中避免内存不足，并防止捕获许多大图（>512），这会大大增加启动时间而性能收益有限。

---

## KernelConfig（内核配置）

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

### `--ir-op-priority`
前向传递期间用于调度/降级的 vLLM IR 操作优先级。平台默认值在 `VllmConfig.post_init` 期间自动追加。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

**默认值：** `IrOpPriorityConfig(rms_norm=[])`

### `--enable-flashinfer-autotune, --no-enable-flashinfer-autotune`
如果为 True，在内核预热期间运行 FlashInfer 自动调优。

### `--moe-backend`
**可选值：** `aiter`, `auto`, `cutlass`, `deep_gemm`, `deep_gemm_mega_moe`, `emulation`, `flashinfer_cutedsl`, `flashinfer_cutlass`, `flashinfer_trtllm`, `marlin`, `triton`

MoE 专家计算内核的后端。可用选项：
- `auto`：根据模型和硬件自动选择最佳后端
- `triton`：使用基于 Triton 的融合 MoE 内核
- `deep_gemm`：使用 DeepGEMM 内核（仅 FP8 块量化）
- `deep_gemm_mega_moe`：使用 DeepGEMM mega MoE 内核
- `cutlass`：使用 vLLM CUTLASS 内核
- `flashinfer_trtllm`：使用 FlashInfer 与 TRTLLM-GEN 内核
- `flashinfer_cutlass`：使用 FlashInfer 与 CUTLASS 内核
- `flashinfer_cutedsl`：使用 FlashInfer 与 CuteDSL 内核（仅 FP4）
- `marlin`：使用 Marlin 内核（仅权重量化）
- `aiter`：使用 AMD AITer 内核（仅 ROCm）
- `emulation`：使用 BF16/FP16 GEMM，反量化权重并运行 QDQ 激活。

**默认值：** `auto`

---

## VllmConfig（VLLM 配置）

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

### `--speculative-config, -sc`
推测解码配置。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

### `--kv-transfer-config`
分布式 KV 缓存传输的配置。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

### `--kv-events-config`
事件发布的配置。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

### `--ec-transfer-config`
分布式 EC 缓存传输的配置。

API 文档：https://docs.vllm.ai/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.ai/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.ai/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_cudnn_prefill=False, use_trtllm_ragged_deepseek_prefill=False, use_trtllm_attention=None, disable_flashinfer_prefill=True, disable_flashinfer_q_quantization=False, use_prefill_query_quantization=False, use_fp4_indexer_cache=False)`

### `--reasoning-config`
推理模型的配置。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

### `--kernel-config`
内核配置。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

**默认值：** `KernelConfig(ir_op_priority=IrOpPriorityConfig(rms_norm=[]), enable_flashinfer_autotune=None, moe_backend='auto')`

### `--additional-config`
指定平台的额外配置。不同平台可能支持不同的配置。确保配置对您使用的平台有效。内容必须是可哈希的。

**默认值：** `{}`

### `--structured-outputs-config`
结构化输出配置。

API 文档：https://docs.vllm.ai/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.ai/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 graph、面向延迟的内核）。
- `'throughput'`：在高并发下倾向于聚合 token/sec（更大的 CUDA graph、更积极的批处理、面向吞吐量的内核）。

**默认值：** `balanced`

### `--weight-transfer-config`
RL 训练期间权重传输的配置。

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

应为有效的 JSON 字符串或逐个传递的 JSON 键值。

• 常用命令

vllm serve Qwen/Qwen2.5-72B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 32768 \
  --max-num-seqs 256 \
  --dtype auto \
  --enforce-eager \
  --enable-prefix-caching \
  --enable-chunked-prefill \
  --max-num-batched-tokens 32768 \
  --api-key sk-your-secret-key-here \
  --served-model-name qwen2.5-72b \
  --trust-remote-code \
  --disable-log-stats \
  --uvicorn-log-level warning \
  --disable-uvicorn-access-log

安全相关

# 使用 API Key 认证
--api-key sk-your-strong-random-key-here

# 如果需要 HTTPS，配置 SSL
--ssl-keyfile /path/to/private.key \
--ssl-certfile /path/to/certificate.crt

# 限制跨域来源（前端分离部署时）
--allowed-origins '["https://your-frontend-domain.com"]'

性能调优相关

# 分块预填充，提升高并发吞吐量
--enable-chunked-prefill \
--max-num-batched-tokens 32768 \

# 前缀缓存，提升 RAG 等场景效率
--enable-prefix-caching

# 禁用 CUDA Graph（大模型防止 OOM）
--enforce-eager

# 设置异步调度
--async-scheduling

内存优化相关

# 控制 GPU 内存使用
--gpu-memory-utilization 0.90

# 启用 CPU 卸载（当 GPU 内存不足时）
--cpu-offload-gb 20

# KV 缓存卸载到 CPU（长上下文场景）
--kv-offloading-size 10 \
--kv-offloading-backend native

日志与监控

# 生产环境精简日志
--disable-log-stats \
--uvicorn-log-level warning \
--disable-uvicorn-access-log

# 启用 Prometheus 指标监控
# 访问 http://host:8000/metrics 查看指标

# 启用 KV 缓存指标
--kv-cache-metrics \
--kv-cache-metrics-sample 0.01

多模态模型

# 视觉语言模型（如 Qwen-VL）
vllm serve Qwen/Qwen2-VL-72B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 32768 \
  --limit-mm-per-prompt '{"image": 10, "video": 2}'