vLLM CLI 指南¶

vllm 命令行工具用于运行和管理 vLLM 模型。您可以通过以下命令查看帮助信息：

vllm --help

可用命令

vllm {chat,complete,serve,bench,collect-env,run-batch}

serve¶

启动 vLLM OpenAI 兼容 API 服务器。

示例

# Start with a model
vllm serve meta-llama/Llama-2-7b-hf

# Specify the port
vllm serve meta-llama/Llama-2-7b-hf --port 8100

# Check with --help for more options
# To list all groups
vllm serve --help=listgroup

# To view a argument group
vllm serve --help=ModelConfig

# To view a single argument
vllm serve --help=max-num-seqs

# To search by keyword
vllm serve --help=max

# To view full help with pager (less/more)
vllm serve --help=page

选项¶

`--headless`¶

在无头模式下运行。有关更多详细信息，请参阅多节点数据并行文档。

默认值：False

`--api-server-count`, `-asc`¶

要运行的 API 服务器进程数量。

默认值：1

`--config`¶

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

默认值：None

`--disable-log-stats`¶

禁用日志统计。

默认值：False

`--enable-prompt-adapter`¶

[已废弃] 提示适配器已被移除。将此标志设置为 True 或 False 不影响 vLLM 的行为。

默认值：False

`--disable-log-requests`¶

禁用请求日志记录。

默认值：False

前端¶

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

`--host`¶

主机名。

默认值：None

`--port`¶

端口号。

默认值：8000

`--uvicorn-log-level`¶

可选值：critical, debug, error, info, trace, warning

uvicorn 的日志级别。

默认值：info

`--disable-uvicorn-access-log`, `--no-disable-uvicorn-access-log`¶

禁用 uvicorn 访问日志。

默认值：False

`--allow-credentials`, `--no-allow-credentials`¶

允许凭据。

默认值：False

`--allowed-origins`¶

允许的源。

默认值：['*']

`--allowed-methods`¶

允许的方法。

默认值：['*']

`--allowed-headers`¶

允许的头。

默认值：['*']

`--api-key`¶

如果提供，服务器将要求在请求头中包含此密钥。

默认值：None

`--lora-modules`¶

LoRA 模块配置，可以是 'name=path' 格式或 JSON 格式或 JSON 列表格式。示例（旧格式）：'name=path' 示例（新格式）：{"name": "name", "path": "lora_path", "base_model_name": "id"}

默认值：None

`--chat-template`¶

指定模型的聊天模板文件路径，或单行形式的模板。

默认值：None

`--chat-template-content-format`¶

可选值：auto, openai, string

在聊天模板中渲染消息内容的格式。

"string" 将内容渲染为字符串。示例："Hello World"
"openai" 将内容渲染为字典列表，类似于 OpenAI 架构。示例：[{"type": "text", "text": "Hello world!"}]

默认值：auto

`--response-role`¶

如果 request.add_generation_prompt=true，则返回的角色名称。

默认值：assistant

`--ssl-keyfile`¶

SSL 密钥文件的文件路径。

默认值：None

`--ssl-certfile`¶

SSL 证书文件的文件路径。

默认值：None

`--ssl-ca-certs`¶

CA 证书文件。

默认值：None

`--enable-ssl-refresh`, `--no-enable-ssl-refresh`¶

当 SSL 证书文件更改时刷新 SSL 上下文。

默认值：False

`--ssl-cert-reqs`¶

是否需要客户端证书（参见 stdlib ssl 模块）。

默认值：0

`--root-path`¶

当应用位于基于路径的路由代理后时，FastAPI 的 root_path。

默认值：None

`--middleware`¶

应用于应用程序的额外 ASGI 中间件。我们接受多个 --middleware 参数。该值应为导入路径。如果提供函数，vLLM 将使用 @app.middleware('http') 将其添加到服务器。如果提供类，vLLM 将使用 app.add_middleware() 将其添加到服务器。

默认值：[]

`--return-tokens-as-token-ids`, `--no-return-tokens-as-token-ids`¶

当指定 --max-logprobs 时，将单个令牌表示为 'token_id:{token_id}' 形式的字符串，以便识别无法进行 JSON 编码的令牌。

默认值：False

`--disable-frontend-multiprocessing`, `--no-disable-frontend-multiprocessing`¶

如果指定，将在与模型服务引擎相同的进程中运行 OpenAI 前端服务器。

默认值：False

`--enable-request-id-headers`, `--no-enable-request-id-headers`¶

如果指定，API 服务器将向响应添加 X-Request-Id 头。注意：在高 QPS 下这会影响性能。

默认值：False

`--enable-auto-tool-choice`, `--no-enable-auto-tool-choice`¶

如果指定，当 tool_choice='none' 时，在提示中排除工具定义。

默认值：False

`--exclude-tools-when-tool-choice-none`, `--no-exclude-tools-when-tool-choice-none`¶

为受支持的模型启用自动工具选择。使用 --tool-call-parser 指定要使用的解析器。

默认值：False

`--tool-call-parser`¶

可选值：deepseek_v3, glm45, granite-20b-fc, granite, hermes, hunyuan_a13b, internlm, jamba, kimi_k2, llama4_pythonic, llama4_json, llama3_json, minimax, mistral, phi4_mini_json, pythonic, qwen3_coder, xlam

根据您正在使用的模型选择工具调用解析器。这用于将模型生成的工具调用解析为 OpenAI API 格式。--enable-auto-tool-choice 所必需。您可以从内置解析器中选择任何选项，或通过 --tool-parser-plugin 注册插件。

默认值：None

`--tool-parser-plugin`¶

特殊的工具解析器插件，用于将模型生成的工具解析为 OpenAI API 格式，此插件中注册的名称可以在 --tool-call-parser 中使用。

默认值：``

`--log-config-file`¶

vllm 和 uvicorn 的日志配置 JSON 文件路径

默认值：None

`--max-log-len`¶

日志中打印的提示字符或提示 ID 号的最大数量。默认 None 表示无限制。

默认值：None

`--disable-fastapi-docs`, `--no-disable-fastapi-docs`¶

禁用 FastAPI 的 OpenAPI 架构、Swagger UI 和 ReDoc 端点。

默认值：False

`--enable-prompt-tokens-details`, `--no-enable-prompt-tokens-details`¶

如果设置为 True，则在使用中启用 prompt_tokens_details。

默认值：False

`--enable-server-load-tracking`, `--no-enable-server-load-tracking`¶

如果设置为 True，则在应用程序状态中启用跟踪 server_load_metrics。

默认值：False

`--enable-force-include-usage`, `--no-enable-force-include-usage`¶

如果设置为 True，则在每个请求中都包含使用情况。

默认值：False

`--enable-tokenizer-info-endpoint`, `--no-enable-tokenizer-info-endpoint`¶

启用 /get_tokenizer_info 端点。可能暴露聊天模板和其他分词器配置。

默认值：False

ModelConfig¶

模型的配置。

`--model`¶

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

默认值：Qwen/Qwen3-0.6B

`--task`¶

可选值：auto, classify, draft, embed, embedding, generate, reward, score, transcription

模型要执行的任务。如果模型支持多个模型运行器，则此参数用于选择要运行的模型运行器。

请注意，模型可能支持使用相同模型运行器的其他任务。

默认值：auto

`--tokenizer`¶

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

默认值：None

`--tokenizer-mode`¶

可选值：auto, custom, mistral, slow

分词器模式

"auto" 将在可用时使用快速分词器。
"slow" 将始终使用慢速分词器。
"mistral" 将始终使用 mistral_common 中的分词器。
"custom" 将使用 --tokenizer 选择预注册的分词器。

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

用于重现性的随机种子。在 V0 中初始化为 None，但在 V1 中初始化为 0。

默认值：None

`--hf-config-path`¶

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

默认值：None

`--allowed-local-media-path`¶

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

默认值：``

`--revision`¶

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

默认值：None

`--code-revision`¶

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

默认值：None

`--rope-scaling`¶

RoPE 缩放配置。例如，{"rope_type":"dynamic","factor":2.0}。

应为有效的 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'

默认值：{}

`--rope-theta`¶

RoPE theta。与 rope_scaling 一起使用。在某些情况下，更改 RoPE theta 可以提高缩放模型的性能。

默认值：None

`--tokenizer-revision`¶

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

默认值：None

`--max-model-len`¶

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

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

1k -> 1000
1K -> 1024
25.6k -> 25,600

默认值：None

`--quantization`, `-q`¶

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

默认值：None

`--enforce-eager`, `--no-enforce-eager`¶

是否始终使用 eager-mode PyTorch。如果为 True，我们将禁用 CUDA 图并始终以 eager 模式执行模型。如果为 False，我们将使用 CUDA 图和 eager 执行的混合模式，以实现最大的性能和灵活性。

默认值：False

`--max-seq-len-to-capture`¶

CUDA 图覆盖的最大序列长度。当序列的上下文长度大于此值时，我们将回退到 eager 模式。此外，对于编码器-解码器模型，如果编码器输入的序列长度大于此值，我们将回退到 eager 模式。

默认值：8192

`--max-logprobs`¶

当 SamplingParams 中指定 logprobs 时返回的最大对数概率数。默认值来自 OpenAI Chat Completions API 的默认值。

默认值：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 表示应用这些处理器之后的值。

默认值：raw_logprobs

`--disable-sliding-window`, `--no-disable-sliding-window`¶

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

默认值：False

`--disable-cascade-attn`, `--no-disable-cascade-attn`¶

禁用 V1 的级联注意力。尽管级联注意力不改变数学正确性，但禁用它有助于防止潜在的数值问题。请注意，即使此设置为 False，级联注意力也只会在启发式判断有利时使用。

默认值：False

`--skip-tokenizer-init`, `--no-skip-tokenizer-init`¶

跳过分词器和反分词器的初始化。期望输入中提供有效的 prompt_token_ids 和 None 作为提示。生成的输出将包含令牌 ID。

默认值：False

`--enable-prompt-embeds`, `--no-enable-prompt-embeds`¶

如果为 True，则通过 prompt_embeds 键启用将文本嵌入作为输入。请注意，启用此功能将使图编译所需时间加倍。

默认值：False

`--served-model-name`¶

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

默认值：None

`--disable-async-output-proc`¶

禁用异步输出处理。这可能导致性能下降。

默认值：False

`--config-format`¶

可选值：auto, hf, mistral

要加载的模型配置格式

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

默认值：auto

`--hf-token`¶

用作远程文件 HTTP 持有者授权的令牌。如果为 True，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。

默认值：None

`--hf-overrides`¶

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

默认值：{}

`--override-neuron-config`¶

初始化非默认神经元配置或覆盖特定于神经元设备的默认神经元配置，此参数将用于配置无法从 vllm 参数中收集的神经元配置。例如 {"cast_logits_dtype": "bfloat16"}。

应为有效的 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'

默认值：{}

`--override-pooler-config`¶

初始化非默认池化配置或覆盖池化模型的默认池化配置。例如 {"pooling_type": "mean", "normalize": false}。

默认值：None

`--logits-processor-pattern`¶

可选的正则表达式模式，指定可以通过 logits_processors 额外完成参数传递的有效 logits 处理器合格名称。默认为 None，表示不允许任何处理器。

默认值：None

`--generation-config`¶

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

默认值：auto

`--override-generation-config`¶

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

应为有效的 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'

默认值：{}

`--enable-sleep-mode`, `--no-enable-sleep-mode`¶

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

默认值：False

`--model-impl`¶

可选值：auto, vllm, transformers

要使用的模型实现

"auto" 将尝试使用 vLLM 实现，如果存在；如果vLLM实现不可用，则回退到 Transformers 实现。
"vllm" 将使用 vLLM 模型实现。
"transformers" 将使用 Transformers 模型实现。

默认值：auto

`--override-attention-dtype`¶

覆盖注意力的 dtype

默认值：None

LoadConfig¶

加载模型权重的配置。

`--load-format`¶

要加载的模型权重格式

"auto" 将尝试以 safetensors 格式加载权重，如果 safetensors 格式不可用，则回退到 pytorch bin 格式。
"pt" 将以 pytorch bin 格式加载权重。
"safetensors" 将以 safetensors 格式加载权重。
"npcache" 将以 pytorch 格式加载权重并存储 numpy 缓存以加速加载。
"dummy" 将使用随机值初始化权重，主要用于性能分析。
"tensorizer" 将使用 CoreWeave 的 tensorizer 库进行快速权重加载。有关更多信息，请参见示例部分的 Tensorize vLLM Model 脚本。
"runai_streamer" 将使用 Run:ai Model Streamer 加载 Safetensors 权重。
"bitsandbytes" 将使用 bitsandbytes 量化加载权重。
"sharded_state" 将从预分片检查点文件加载权重，支持高效加载张量并行模型。
"gguf" 将从 GGUF 格式文件加载权重（详细信息请参阅 https://github.com/ggml-org/ggml/blob/master/docs/gguf.md）。
"mistral" 将从 Mistral 模型使用的合并 safetensors 文件加载权重。
其他自定义值可以通过插件支持。

默认值：auto

`--download-dir`¶

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

默认值：None

`--model-loader-extra-config`¶

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

默认值：{}

`--ignore-patterns`¶

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

默认值：None

`--use-tqdm-on-load`, `--no-use-tqdm-on-load`¶

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

默认值：True

`--pt-load-map-location`¶

pt_load_map_location：加载 pytorch 检查点的映射位置，以支持只能在某些设备（如 "cuda"）上加载的检查点，这相当于 {"": "cuda"}。另一种支持的格式是不同设备之间的映射，例如从 GPU 1 到 GPU 0：{"cuda:1": "cuda:0"}。请注意，从命令行传入时，字典中的字符串需要双引号才能进行 json 解析。有关更多详细信息，请参阅 https://pytorch.ac.cn/docs/stable/generated/torch.load.html 中 map_location 的原始文档。

默认值：cpu

DecodingConfig¶

包含引擎解码策略的数据类。

`--guided-decoding-backend`¶

可选值：auto, guidance, lm-format-enforcer, outlines, xgrammar

默认情况下，哪个引擎将用于引导式解码（JSON 模式/正则表达式等）。使用 "auto" 时，我们将根据请求内容和后端库当前支持的功能做出有倾向性的选择，因此行为可能在每个版本中有所变化。

默认值：auto

`--guided-decoding-disable-fallback`, `--no-guided-decoding-disable-fallback`¶

如果为 True，vLLM 将在出错时不再回退到其他后端。

默认值：False

`--guided-decoding-disable-any-whitespace`, `--no-guided-decoding-disable-any-whitespace`¶

如果为 True，模型在引导式解码期间将不会生成任何空格。这仅支持 xgrammar 和 guidance 后端。

默认值：False

`--guided-decoding-disable-additional-properties`, `--no-guided-decoding-disable-additional-properties`¶

如果为 True，guidance 后端将不会在 JSON 模式中使用 additionalProperties。这仅支持 guidance 后端，用于使其行为更好地与 outlines 和 xgrammar 对齐。

默认值：False

`--reasoning-parser`¶

可选值：deepseek_r1, glm45, granite, hunyuan_a13b, mistral, qwen3

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

默认值：``

ParallelConfig¶

分布式执行的配置。

`--distributed-executor-backend`¶

可选值：external_launcher, mp, ray, uni, None

用于分布式模型工作器的后端，可以是 "ray" 或 "mp"（多进程）。如果 pipeline_parallel_size 和 tensor_parallel_size 的乘积小于或等于可用 GPU 数量，将使用 "mp" 在单个主机上进行处理。否则，如果安装了 Ray，将默认为 "ray"，否则失败。请注意，tpu 仅支持 Ray 进行分布式推理。

默认值：None

`--pipeline-parallel-size`, `-pp`¶

流水线并行组的数量。

默认值：1

`--tensor-parallel-size`, `-tp`¶

张量并行组的数量。

默认值：1

`--data-parallel-size`, `-dp`¶

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

默认值：1

`--data-parallel-rank`, `-dpn`¶

此实例的数据并行等级。设置时，启用外部负载均衡器模式。

默认值：None

`--data-parallel-start-rank`, `-dpr`¶

辅助节点的起始数据并行等级。

默认值：None

`--data-parallel-size-local`, `-dpl`¶

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

默认值：None

`--data-parallel-address`, `-dpa`¶

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

默认值：None

`--data-parallel-rpc-port`, `-dpp`¶

数据并行 RPC 通信的端口。

默认值：None

`--data-parallel-backend`, `-dpb`¶

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

默认值：mp

`--data-parallel-hybrid-lb`, `--no-data-parallel-hybrid-lb`¶

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

默认值：False

`--enable-expert-parallel`, `--no-enable-expert-parallel`¶

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

默认值：False

`--enable-eplb`, `--no-enable-eplb`¶

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

默认值：False

`--num-redundant-experts`¶

用于专家并行的冗余专家数量。

默认值：0

`--eplb-window-size`¶

专家负载记录的窗口大小。

默认值：1000

`--eplb-step-interval`¶

专家并行中重新安排专家的间隔。

请注意，如果此值大于 EPLB 窗口大小，则只有最后 eplb_window_size 步的指标将用于重新安排专家。

默认值：3000

`--eplb-log-balancedness`, `--no-eplb-log-balancedness`¶

记录专家并行每一步的平衡性。默认关闭此功能，因为它会增加通信开销。

默认值：False

`--max-parallel-loading-workers`¶

在分批顺序加载模型时，最大并行加载工作器数量。避免在使用张量并行和大型模型时出现 RAM OOM。

默认值：None

`--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 调用中使用。

默认值：``

`--enable-multimodal-encoder-data-parallel`, `--no-enable-multimodal-encoder-data-parallel`¶

对视觉编码器使用数据并行而不是张量并行。目前仅支持 LLama4

默认值：False

CacheConfig¶

KV 缓存的配置。

`--block-size`¶

可选值：1, 8, 16, 32, 64, 128

连续缓存块的令牌数量大小。在神经元设备上，此参数被忽略并设置为 --max-model-len。在 CUDA 设备上，仅支持块大小不超过 32。在 HPU 设备上，块大小默认为 128。

此配置没有静态默认值。如果用户未指定，它将在 Platform.check_and_update_config() 中根据当前平台进行设置。

默认值：None

`--gpu-memory-utilization`¶

用于模型执行器的 GPU 内存比例，范围从 0 到 1。例如，0.5 的值表示 50% 的 GPU 内存利用率。如果未指定，将使用默认值 0.9。这是每个实例的限制，仅适用于当前的 vLLM 实例。您在同一 GPU 上运行另一个 vLLM 实例无关紧要。例如，如果您在同一 GPU 上运行两个 vLLM 实例，您可以将每个实例的 GPU 内存利用率设置为 0.5。

默认值：0.9

`--swap-space`¶

每个 GPU 的 CPU 交换空间大小（GiB）。

默认值：4

`--kv-cache-dtype`¶

可选值：auto, fp8, fp8_e4m3, fp8_e5m2, fp8_inc

kv 缓存存储的数据类型。如果为 "auto"，将使用模型数据类型。CUDA 11.8+ 支持 fp8 (=fp8_e4m3) 和 fp8_e5m2。ROCm (AMD GPU) 支持 fp8 (=fp8_e4m3)。Intel Gaudi (HPU) 支持 fp8 (使用 fp8_inc)。

默认值：auto

`--num-gpu-blocks-override`¶

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

默认值：None

`--enable-prefix-caching`, `--no-enable-prefix-caching`¶

是否启用前缀缓存。V0 默认禁用。V1 默认启用。

默认值：None

`--prefix-caching-hash-algo`¶

可选值：builtin, sha256, sha256_cbor_64bit

设置前缀缓存的哈希算法

"builtin" 是 Python 的内置哈希。
"sha256" 具有抗碰撞性但有一定开销。此选项使用 Pickle 进行对象序列化，然后进行哈希。
"sha256_cbor_64bit" 提供可重现、跨语言兼容的哈希。它使用规范 CBOR 序列化对象，并使用 SHA-256 进行哈希。结果哈希由 SHA-256 摘要的低 64 位组成。

默认值：builtin

`--cpu-offload-gb`¶

每块 GPU 卸载到 CPU 的空间大小（GiB）。默认值为 0，表示不卸载。直观地，此参数可以看作是增加 GPU 内存大小的一种虚拟方式。例如，如果您有一块 24 GB 的 GPU 并将其设置为 10，您实际上可以将其视为一块 34 GB 的 GPU。然后您可以加载一个需要至少 26GB GPU 内存的 13B 模型（使用 BF16 权重）。请注意，这需要快速的 CPU-GPU 互连，因为模型的一部分会在每个模型前向传递中动态地从 CPU 内存加载到 GPU 内存中。

默认值：0

`--calculate-kv-scales`, `--no-calculate-kv-scales`¶

当 kv_cache_dtype 为 fp8 时，此参数启用 k_scale 和 v_scale 的动态计算。如果为 False，则将从模型检查点加载尺度（如果可用）。否则，尺度将默认为 1.0。

默认值：False

MultiModalConfig¶

控制多模态模型的行为。

`--limit-mm-per-prompt`¶

每个模态每条提示允许的最大输入项数。对于每种模态，V0 默认为 1，V1 默认为 999。

例如，要允许每条提示最多 16 张图片和 2 个视频：{"images": 16, "videos": 2}

应为有效的 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'

默认值：{}

`--media-io-kwargs`¶

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

应为有效的 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'

默认值：{}

`--mm-processor-kwargs`¶

覆盖从 transformers.AutoProcessor.from_pretrained 获取的多模态处理器。

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

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

应为有效的 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'

默认值：None

`--disable-mm-preprocessor-cache`, `--no-disable-mm-preprocessor-cache`¶

如果为 True，禁用已处理多模态输入的缓存。

默认值：False

`--interleave-mm-strings`, `--no-interleave-mm-strings`¶

为多模态提示启用完全交错支持。

默认值：False

LoRAConfig¶

LoRA 的配置。

`--enable-lora`, `--no-enable-lora`¶

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

默认值：None

`--enable-lora-bias`, `--no-enable-lora-bias`¶

启用 LoRA 适配器的偏置。

默认值：False

`--max-loras`¶

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

默认值：1

`--max-lora-rank`¶

最大 LoRA 等级。

默认值：16

`--lora-extra-vocab-size`¶

LoRA 适配器中可以存在的额外词汇的最大大小（添加到基础模型词汇中）。

默认值：256

`--lora-dtype`¶

可选值：auto, bfloat16, float16

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

默认值：auto

`--max-cpu-loras`¶

存储在 CPU 内存中的 LoRA 最大数量。必须大于或等于 max_loras。

默认值：None

`--fully-sharded-loras`, `--no-fully-sharded-loras`¶

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

默认值：False

`--default-mm-loras`¶

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

应为有效的 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'

默认值：None

SpeculativeConfig¶

推测解码的配置。

`--speculative-config`¶

推测解码的配置。应为 JSON 字符串。

默认值：None

ObservabilityConfig¶

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

`--show-hidden-metrics-for-version`¶

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

默认值：None

`--otlp-traces-endpoint`¶

OpenTelemetry 追踪将发送到的目标 URL。

默认值：None

`--collect-detailed-traces`¶

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

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

请注意，收集每个请求的详细计时信息可能开销很大。

默认值：None

SchedulerConfig¶

调度器配置。

`--max-num-batched-tokens`¶

单次迭代中要处理的最大令牌数。

此配置没有静态默认值。如果用户未指定，它将在 EngineArgs.create_engine_config 中根据使用上下文进行设置。

默认值：None

`--max-num-seqs`¶

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

此配置没有静态默认值。如果用户未指定，它将在 EngineArgs.create_engine_config 中根据使用上下文进行设置。

默认值：None

`--max-num-partial-prefills`¶

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

默认值：1

`--max-long-partial-prefills`¶

对于分块预填充，比 long_prefill_token_threshold 更长的提示符，将并发预填充的最大数量。将其设置为小于 max_num_partial_prefills 将在某些情况下允许较短的提示符跳到较长提示符的前面，从而改善延迟。

默认值：1

`--cuda-graph-sizes`¶

Cuda 图捕获大小 1. 如果未提供，则默认设置为 [min(max_num_seqs * 2, 512)] 2. 如果提供一个值，则捕获列表将遵循模式：[1, 2, 4] + [i for i in range(8, cuda_graph_sizes + 1, 8)] 3. 如果提供多个值（例如 1 2 128），则捕获列表将遵循提供的列表。

默认值：[]

`--long-prefill-token-threshold`¶

对于分块预填充，如果提示符长度超过此令牌数量，则认为请求较长。

默认值：0

`--num-lookahead-slots`¶

每个序列每步分配的预留槽位数量，超出已知令牌 ID。这用于推测解码，以存储可能或可能不被接受的令牌的 KV 激活。

注意：这将在未来被推测配置取代；在此之前它用于启用正确性测试。

默认值：0

`--scheduler-delay-factor`¶

在调度下一个提示之前，应用一个延迟（延迟因子乘以之前的提示延迟）。

默认值：0.0

`--preemption-mode`¶

可选值：recompute, swap, None

是否通过交换或重新计算执行抢占。如果未指定，我们按如下方式确定模式：我们默认使用重新计算，因为它比交换开销更低。但是，当序列组有多个序列（例如，束搜索）时，目前不支持重新计算。在这种情况下，我们改用交换。

默认值：None

`--num-scheduler-steps`¶

每个调度器调用最大前向步数。

默认值：1

`--multi-step-stream-outputs`, `--no-multi-step-stream-outputs`¶

如果为 False，则多步将在所有步骤结束时流式输出

默认值：True

`--scheduling-policy`¶

可选值：fcfs, priority

要使用的调度策略

"fcfs" 意味着先进先出，即请求按到达顺序处理。
"priority" 意味着请求根据给定优先级（值越低越早处理）和到达时间（决定任何平局）处理。

默认值：fcfs

`--enable-chunked-prefill`, `--no-enable-chunked-prefill`¶

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

默认值：None

`--disable-chunked-mm-input`, `--no-disable-chunked-mm-input`¶

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

默认值：False

`--scheduler-cls`¶

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

默认值：vllm.core.scheduler.Scheduler

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

如果设置为 True，即使存在多种注意力层（如全注意力层和滑动窗口注意力层），KV 缓存管理器也将为所有注意力层分配相同大小的 KV 缓存。

默认值：False

`--async-scheduling`, `--no-async-scheduling`¶

实验性：如果设置为 True，则执行异步调度。这可能有助于减少 CPU 开销，从而改善延迟和吞吐量。但是，异步调度目前不支持某些功能，例如结构化输出、推测解码和管道并行。

默认值：False

VllmConfig¶

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

`--kv-transfer-config`¶

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

应为有效的 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'

默认值：None

`--kv-events-config`¶

事件发布的配置。

应为有效的 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'

默认值：None

`--compilation-config`, `-O`¶

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

作为简写，可以使用 -O 直接指定编译级别 n：-O3 等同于 -O.level=3（与 -O='{"level":3}' 相同）。目前，也支持 -O和 -O=，但未来可能会被更清晰的 -O语法取代。

注意：级别 0 是没有任何优化的默认级别。级别 1 和 2 仅用于内部测试。级别 3 是生产推荐级别，也是 V1 中的默认级别。

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

应为有效的 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'

默认值：{"level":0,"debug_dump_path":"","cache_dir":"","backend":"","custom_ops":[],"splitting_ops":[],"use_inductor":true,"compile_sizes":null,"inductor_compile_config":{"enable_auto_functionalized_v2":false},"inductor_passes":{},"use_cudagraph":true,"cudagraph_num_of_warmups":0,"cudagraph_capture_sizes":null,"cudagraph_copy_inputs":false,"full_cuda_graph":false,"max_capture_size":null,"local_cache_dir":null}

`--additional-config`¶

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

默认值：{}

chat¶

通过运行中的 API 服务器生成聊天补全。

# Directly connect to localhost API without arguments
vllm chat

# Specify API url
vllm chat --url http://{vllm-serve-host}:{vllm-serve-port}/v1

# Quick chat with a single prompt
vllm chat --quick "hi"

complete¶

通过运行中的 API 服务器根据给定提示生成文本补全。

# Directly connect to localhost API without arguments
vllm complete

# Specify API url
vllm complete --url http://{vllm-serve-host}:{vllm-serve-port}/v1

# Quick complete with a single prompt
vllm complete --quick "The future of AI is"

bench¶

运行基准测试，包括在线服务延迟和离线推理吞吐量。

要使用基准测试命令，请使用 pip install vllm[bench] 安装额外依赖项。

可用命令

vllm bench {latency, serve, throughput}

latency¶

对单批请求的延迟进行基准测试。

vllm bench latency \
    --model meta-llama/Llama-3.2-1B-Instruct \
    --input-len 32 \
    --output-len 1 \
    --enforce-eager \
    --load-format dummy

serve¶

对在线服务吞吐量进行基准测试。

vllm bench serve \
    --model meta-llama/Llama-3.2-1B-Instruct \
    --host server-host \
    --port server-port \
    --random-input-len 32 \
    --random-output-len 4  \
    --num-prompts  5

throughput¶

对离线推理吞吐量进行基准测试。

vllm bench throughput \
    --model meta-llama/Llama-3.2-1B-Instruct \
    --input-len 32 \
    --output-len 1 \
    --enforce-eager \
    --load-format dummy

collect-env¶

开始收集环境信息。

vllm collect-env

run-batch¶

运行批量提示并将结果写入文件。

示例

# Running with a local file
vllm run-batch \
    -i offline_inference/openai_batch/openai_example_batch.jsonl \
    -o results.jsonl \
    --model meta-llama/Meta-Llama-3-8B-Instruct

# Using remote file
vllm run-batch \
    -i https://raw.githubusercontent.com/vllm-project/vllm/main/examples/offline_inference/openai_batch/openai_example_batch.jsonl \
    -o results.jsonl \
    --model meta-llama/Meta-Llama-3-8B-Instruct

vLLM CLI 指南¶

serve¶

选项¶

--headless¶

--api-server-count, -asc¶

--config¶

--disable-log-stats¶

--enable-prompt-adapter¶

--disable-log-requests¶

前端¶

--host¶

--port¶

--uvicorn-log-level¶

--disable-uvicorn-access-log, --no-disable-uvicorn-access-log¶

--allow-credentials, --no-allow-credentials¶

--allowed-origins¶

--allowed-methods¶

--allowed-headers¶

--api-key¶

--lora-modules¶

--chat-template¶

--chat-template-content-format¶

--response-role¶

--ssl-keyfile¶

--ssl-certfile¶

--ssl-ca-certs¶

--enable-ssl-refresh, --no-enable-ssl-refresh¶

--ssl-cert-reqs¶

--root-path¶

--middleware¶

--return-tokens-as-token-ids, --no-return-tokens-as-token-ids¶

--disable-frontend-multiprocessing, --no-disable-frontend-multiprocessing¶

--enable-request-id-headers, --no-enable-request-id-headers¶

--enable-auto-tool-choice, --no-enable-auto-tool-choice¶

--exclude-tools-when-tool-choice-none, --no-exclude-tools-when-tool-choice-none¶

--tool-call-parser¶

--tool-parser-plugin¶

--log-config-file¶

--max-log-len¶

--disable-fastapi-docs, --no-disable-fastapi-docs¶

--enable-prompt-tokens-details, --no-enable-prompt-tokens-details¶

--enable-server-load-tracking, --no-enable-server-load-tracking¶

--enable-force-include-usage, --no-enable-force-include-usage¶

--enable-tokenizer-info-endpoint, --no-enable-tokenizer-info-endpoint¶

ModelConfig¶

--model¶

--task¶

--tokenizer¶

--tokenizer-mode¶

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

--dtype¶

--seed¶

--hf-config-path¶

--allowed-local-media-path¶

--revision¶

--code-revision¶

--rope-scaling¶

--rope-theta¶

--tokenizer-revision¶

--max-model-len¶

--quantization, -q¶

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

--max-seq-len-to-capture¶

--max-logprobs¶

--logprobs-mode¶

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

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

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

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

--served-model-name¶

--disable-async-output-proc¶

--config-format¶

--hf-token¶

--hf-overrides¶

--override-neuron-config¶

--override-pooler-config¶

--logits-processor-pattern¶

--generation-config¶

--override-generation-config¶

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

`--headless`¶

`--api-server-count`, `-asc`¶

`--config`¶

`--disable-log-stats`¶

`--enable-prompt-adapter`¶

`--disable-log-requests`¶

`--host`¶

`--port`¶

`--uvicorn-log-level`¶

`--disable-uvicorn-access-log`, `--no-disable-uvicorn-access-log`¶

`--allow-credentials`, `--no-allow-credentials`¶

`--allowed-origins`¶

`--allowed-methods`¶

`--allowed-headers`¶

`--api-key`¶

`--lora-modules`¶

`--chat-template`¶

`--chat-template-content-format`¶

`--response-role`¶

`--ssl-keyfile`¶

`--ssl-certfile`¶

`--ssl-ca-certs`¶

`--enable-ssl-refresh`, `--no-enable-ssl-refresh`¶

`--ssl-cert-reqs`¶

`--root-path`¶

`--middleware`¶

`--return-tokens-as-token-ids`, `--no-return-tokens-as-token-ids`¶

`--disable-frontend-multiprocessing`, `--no-disable-frontend-multiprocessing`¶

`--enable-request-id-headers`, `--no-enable-request-id-headers`¶

`--enable-auto-tool-choice`, `--no-enable-auto-tool-choice`¶

`--exclude-tools-when-tool-choice-none`, `--no-exclude-tools-when-tool-choice-none`¶

`--tool-call-parser`¶

`--tool-parser-plugin`¶

`--log-config-file`¶

`--max-log-len`¶

`--disable-fastapi-docs`, `--no-disable-fastapi-docs`¶

`--enable-prompt-tokens-details`, `--no-enable-prompt-tokens-details`¶

`--enable-server-load-tracking`, `--no-enable-server-load-tracking`¶

`--enable-force-include-usage`, `--no-enable-force-include-usage`¶

`--enable-tokenizer-info-endpoint`, `--no-enable-tokenizer-info-endpoint`¶

`--model`¶

`--task`¶

`--tokenizer`¶

`--tokenizer-mode`¶

`--trust-remote-code`, `--no-trust-remote-code`¶

`--dtype`¶

`--seed`¶

`--hf-config-path`¶

`--allowed-local-media-path`¶

`--revision`¶

`--code-revision`¶

`--rope-scaling`¶

`--rope-theta`¶

`--tokenizer-revision`¶

`--max-model-len`¶

`--quantization`, `-q`¶

`--enforce-eager`, `--no-enforce-eager`¶

`--max-seq-len-to-capture`¶

`--max-logprobs`¶

`--logprobs-mode`¶

`--disable-sliding-window`, `--no-disable-sliding-window`¶

`--disable-cascade-attn`, `--no-disable-cascade-attn`¶

`--skip-tokenizer-init`, `--no-skip-tokenizer-init`¶

`--enable-prompt-embeds`, `--no-enable-prompt-embeds`¶

`--served-model-name`¶

`--disable-async-output-proc`¶

`--config-format`¶

`--hf-token`¶

`--hf-overrides`¶

`--override-neuron-config`¶

`--override-pooler-config`¶

`--logits-processor-pattern`¶

`--generation-config`¶

`--override-generation-config`¶

`--enable-sleep-mode`, `--no-enable-sleep-mode`¶

`--model-impl`¶

`--override-attention-dtype`¶

`--load-format`¶

`--download-dir`¶

`--model-loader-extra-config`¶