目录
服务器参数 (Server Arguments):
--host: 指定服务器运行的主机名。--port: 指定服务器运行的端口号。默认值：8000。--uvicorn-log-level: Uvicorn 服务器的日志级别。可选值：debug, info, warning, error, critical, trace。默认值：“info”。--disable-uvicorn-access-log: 是否禁用 Uvicorn 的访问日志。默认值：False (不禁用)。--allow-credentials: 是否允许在跨域请求中发送凭证（如 cookies、authorization headers）。默认值：False (不允许)。--allowed-origins: 允许进行跨域请求的来源列表（用于 CORS）。默认值：['*'] (允许所有来源)。--allowed-methods: 允许的 HTTP 方法列表（用于 CORS）。默认值：['*'] (允许所有方法)。--allowed-headers: 允许的 HTTP 请求头列表（用于 CORS）。默认值：['*'] (允许所有请求头)。--api-key: API 密钥。如果提供此参数，服务器将要求客户端在请求头中提供此密钥以进行验证。--lora-modules: LoRA 模块的配置。可以是以 'name=path' 格式或 JSON 格式提供。例如（旧格式）：'name=path'，示例（新格式）：{"name": "name", "path": "lora_path", "base_model_name": "id"}。--prompt-adapters: Prompt adapter 的配置，格式为 name=path。可以指定多个 adapter。--chat-template: 聊天模板文件的路径，或者是适用于指定模型的单行模板字符串。--chat-template-content-format: 在聊天模板中渲染消息内容的格式。可选值：auto, string, openai。“string” 将内容渲染为字符串（例如 "Hello World")。“openai” 将内容渲染为类似 OpenAI 模式的字典列表（例如 [{"type": "text", "text": "Hello world!"}]）。默认值：“auto”。--response-role: 当 request.add_generation_prompt=true 时，返回的角色名称。默认值：“assistant”。--ssl-keyfile: SSL 私钥文件的路径。--ssl-certfile: SSL 证书文件的路径。--ssl-ca-certs: CA 证书文件的路径。--enable-ssl-refresh: 当 SSL 证书文件更改时，是否刷新 SSL 上下文。默认值：False。--ssl-cert-reqs: 是否需要客户端证书（参见 Python 标准库 ssl 模块）。默认值：0 (不需要)。--root-path: 当应用部署在基于路径的路由代理后面时，FastAPI 的 root_path。--middleware: 应用到 FastAPI 应用的额外 ASGI 中间件。可以接受多个 --middleware 参数。值应该是导入路径。如果提供的是函数，vLLM 将使用 @app.middleware('http') 添加它。如果提供的是类，vLLM 将使用 app.add_middleware() 添加它。默认值：[]。--return-tokens-as-token-ids: 当指定 --max-logprobs 时，将单个 token 表示为 token_id:{token_id} 形式的字符串，以便可以识别非 JSON 可编码的 token。默认值：False。--disable-frontend-multiprocessing: 如果指定，将在与模型服务引擎相同的进程中运行 OpenAI 前端服务器。默认值：False。--enable-request-id-headers: 如果指定，API 服务器将在响应中添加 X-Request-Id 标头。注意：这在高 QPS（每秒查询数）下会损害性能。默认值：False。--enable-auto-tool-choice: 为支持的模型启用自动工具选择。使用 --tool-call-parser 指定要使用的解析器。默认值：False。--tool-call-parser: 选择工具调用解析器，具体取决于您使用的模型。这用于将模型生成的工具调用解析为 OpenAI API 格式。需要与 --enable-auto-tool-choice 一起使用。--tool-parser-plugin: 指定用于将模型生成的工具解析为 OpenAI API 格式的工具解析器插件，在此插件中注册的名称可以在 --tool-call-parser 中使用。默认值：""。--served-model-name: API 中使用的模型名称。可以提供多个名称，服务器将响应任何提供的名称。响应中 model 字段的模型名称将是此列表中的第一个名称。如果未指定，模型名称将与 --model 参数相同。注意，此名称（如果提供多个，则取第一个）也将用于 Prometheus 指标的 model_name 标签内容。--disable-log-requests: 禁用请求日志记录。默认值：False。--max-log-len: 日志中打印的提示符字符或提示符 ID 编号的最大数量。默认值 None 表示无限制。--disable-fastapi-docs: 禁用 FastAPI 的 OpenAPI schema、Swagger UI 和 ReDoc 端点。默认值：False。--enable-prompt-tokens-details: 如果设置为 True，则在 usage 中启用 prompt_tokens_details。默认值：False。--enable-server-load-tracking: 如果设置为 True，则在应用状态中启用 server_load_metrics 的跟踪。默认值：False。
模型参数 (Model Arguments):
--model: 要使用的 Hugging Face 模型的名称或路径。默认值：“facebook/opt-125m”。--task: 模型用于的任务。每个 vLLM 实例仅支持一个任务。当模型仅支持一个任务时，可以使用 “auto” 选择它；否则，必须明确指定使用哪个任务。可选值：auto, generate, embedding, embed, classify, score, reward, transcription。默认值：“auto”。--tokenizer: 要使用的 Hugging Face 分词器的名称或路径。如果未指定，将使用模型名称或路径。--hf-config-path: 要使用的 Hugging Face 配置的名称或路径。如果未指定，将使用模型名称或路径。--skip-tokenizer-init: 跳过分词器和反分词器的初始化。期望输入中包含有效的 prompt_token_ids 且 prompt 为 None。生成的输出将包含 token ID。默认值：False。--revision: 要使用的特定模型版本。可以是分支名称、标签名称或提交 ID。如果未指定，将使用默认版本。--code-revision: Hugging Face Hub 上模型代码要使用的特定修订版本。可以是分支名称、标签名称或提交 ID。如果未指定，将使用默认版本。--tokenizer-revision: 要使用的 Hugging Face 分词器的修订版本。可以是分支名称、标签名称或提交 ID。如果未指定，将使用默认版本。--tokenizer-mode: 分词器模式。可选值：auto, slow, mistral, custom。“auto” 会在可用时使用快速分词器。“slow” 总是使用慢速分词器。“mistral” 总是使用 mistral_common 分词器。“custom” 将使用 --tokenizer 选择预先注册的分词器。默认值：“auto”。--trust-remote-code: 是否信任来自 Hugging Face 的远程代码。默认值：False。--allowed-local-media-path: 允许 API 请求从服务器文件系统指定的目录读取本地图像或视频。这是一个安全风险，只应在受信任的环境中启用。--download-dir: 下载和加载权重的目录。--load-format: 模型权重的加载格式。可选值及说明见上文英文描述。默认值：“auto”。--config-format: 模型配置的加载格式。可选值：auto, hf, mistral。“auto” 会尝试加载 hf 格式，如果不可用则尝试加载 mistral 格式。默认值：“ConfigFormat.AUTO”。--dtype: 模型权重和激活值的数据类型。可选值及说明见上文英文描述。默认值：“auto”。--kv-cache-dtype: KV 缓存存储的数据类型。如果为 “auto”，将使用模型数据类型。CUDA 11.8+ 支持 fp8 (=fp8_e4m3) 和 fp8_e5m2。ROCm (AMD GPU) 支持 fp8 (=fp8_e4m3)。可选值：auto, fp8, fp8_e5m2, fp8_e4m3。默认值：“auto”。--max-model-len: 模型上下文长度。如果未指定，将从模型配置中自动推断。支持 k/m/g/K/M/G 人类可读格式（例如 1k -> 1000, 1K -> 1024）。--guided-decoding-backend: 默认用于引导解码（JSON schema/regex 等）的引擎。目前支持 mlc-ai/xgrammar 和 guidance-ai/llguidance。有效后端值是 “xgrammar”, “guidance”, “auto”。“auto” 会根据请求内容和后端库当前支持情况做出选择，因此行为可能在每个版本中发生变化。默认值：“xgrammar”。--logits-processor-pattern: 可选的正则表达式模式，指定可以通过 logits_processors 额外完成参数传递的有效 logits 处理器限定名称。默认为 None，表示不允许任何处理器。--model-impl: 使用哪个模型实现。可选值：auto, vllm, transformers。“auto” 会尝试使用 vLLM 实现（如果存在），否则回退到 Transformers 实现。“vllm” 使用 vLLM 模型实现。“transformers” 使用 Transformers 模型实现。默认值：“auto”。--generation-config: 生成配置的文件夹路径。默认为 ‘auto’，生成配置将从模型路径加载。如果设置为 ‘vllm’，则不加载生成配置，将使用 vLLM 默认值。如果设置为文件夹路径，则生成配置将从指定的文件夹路径加载。如果在生成配置中指定了 max_new_tokens，则它会为所有请求设置服务器范围的输出 token 数量限制。默认值：auto。--override-generation-config: 以 JSON 格式覆盖或设置生成配置。例如 {"temperature": 0.5}。如果与 --generation-config=auto 一起使用，覆盖参数将与模型的默认配置合并。如果 generation-config 为 None，则仅使用覆盖参数。--qlora-adapter-name-or-path: QLoRA adapter 的名称或路径。--calculate-kv-scales: 当 kv-cache-dtype 为 fp8 时，启用 k_scale 和 v_scale 的动态计算。如果为 false，则将从模型检查点加载 scale（如果可用），否则默认为 1.0。默认值：False。--additional-config: JSON 格式的特定平台的附加配置。不同平台可能支持不同的配置。确保配置对您使用的平台有效。输入格式类似 {"config_key":"config_value"}。
并行参数 (Parallel Arguments):
--distributed-executor-backend: 用于分布式模型工作进程的后端。可选值：“ray” 或 “mp” (multiprocessing)。如果 pipeline_parallel_size 和 tensor_parallel_size 的乘积小于或等于可用的 GPU 数量，将使用 “mp” 以在单个主机上进行处理。否则，如果安装了 Ray，则默认为 “ray”，否则失败。注意：TPU 仅支持 Ray 进行分布式推理。--pipeline-parallel-size, -pp: 流水线并行阶段的数量。默认值：1。--tensor-parallel-size, -tp: 张量并行副本的数量。默认值：1。--data-parallel-size, -dp: 数据并行副本的数量。MoE 层将根据 tensor-parallel-size 和 data-parallel-size 的乘积进行分片。默认值：1。--enable-expert-parallel: 对 MoE 层使用专家并行而不是张量并行。默认值：False。--max-parallel-loading-workers: 分多个批次顺序加载模型，以避免在使用张量并行和大型模型时 RAM OOM（内存不足）。--ray-workers-use-nsight: 如果指定，使用 nsight 来分析 Ray 工作进程。默认值：False。--worker-cls: 用于分布式执行的工作进程类。默认值：“auto”。--worker-extension-cls: 在 worker cls 之上的 worker 扩展类，如果您只想向 worker 类添加新功能而不更改现有功能，这将非常有用。默认值：""。
KV 缓存参数 (KV Cache Arguments):
--block-size: 连续 token 块的大小。在 Neuron 设备上忽略此参数并设置为 --max-model-len。在 CUDA 设备上，仅支持最大 32 的块大小。在 HPU 设备上，块大小默认为 128。可选值：8, 16, 32, 64, 128。--enable-prefix-caching, --no-enable-prefix-caching: 启用自动前缀缓存。使用 --no-enable-prefix-caching 显式禁用。--prefix-caching-hash-algo: 设置前缀缓存的哈希算法。选项是 ‘builtin’ (Python 内建 hash) 或 ‘sha256’ (抗碰撞但有一定开销)。默认值：“builtin”。--disable-sliding-window: 禁用滑动窗口，将上下文限制在滑动窗口大小。默认值：False。--use-v2-block-manager: [已弃用] block manager v1 已移除，SelfAttnBlockSpaceManager (即 block manager v2) 现在是默认值。设置此标志为 True 或 False 对 vLLM 行为无影响。默认值：True。--swap-space: 每个 GPU 的 CPU 交换空间大小 (GiB)。默认值：4。--cpu-offload-gb: 每个 GPU 卸载到 CPU 的空间 (GiB)。默认为 0，表示不卸载。此参数可以看作是虚拟增加 GPU 显存大小的方式。例如，有 24GB GPU，设置此值为 10，可以看作拥有 34GB GPU。需要快速的 CPU-GPU 互连。默认值：0。--gpu-memory-utilization: 用于模型执行器的 GPU 显存比例，范围 0 到 1。例如 0.5 表示使用 50% 显存。如果未指定，默认 0.9。这是每个 vLLM 实例的限制。默认值：0.9。--num-gpu-blocks-override: 如果指定，忽略 GPU 分析结果并使用此数量的 GPU 块。用于测试抢占。--kv-transfer-config: 分布式 KV 缓存传输的配置。应为 JSON 字符串。
调度器参数 (Scheduler Arguments):
--num-lookahead-slots: 推测解码所需的实验性调度配置。将来会被 speculative config 替代。默认值：0。--max-num-batched-tokens: 每次迭代最大批处理 token 数。--max-num-partial-prefills: 对于分块预填充 (chunked prefill)，并发部分预填充的最大数量。默认值：1。--max-long-partial-prefills: 对于分块预填充，将同时预填充的、长度超过 --long-prefill-token-threshold 的提示的最大数量。将其设置小于 --max-num-partial-prefills 可以让较短的提示在某些情况下插队到较长提示之前，从而改善延迟。默认值：1。--long-prefill-token-threshold: 对于分块预填充，如果提示长度超过此 token 数，则认为该请求是长请求。默认值：0。--max-num-seqs: 每次迭代最大序列数。--num-scheduler-steps: 每个调度器调用的最大前向步数。默认值：1。--scheduler-delay-factor: 在调度下一个提示之前应用延迟（延迟因子乘以先前提示的延迟）。默认值：0.0。--enable-chunked-prefill: 如果设置，预填充请求可以根据 max_num_batched_tokens 进行分块。--preemption-mode: 如果是 ‘recompute’，引擎通过重计算执行抢占；如果是 ‘swap’，引擎通过块交换执行抢占。--scheduling-policy: 要使用的调度策略。“fcfs” (先到先得，默认) 或 “priority” (基于给定优先级和到达时间处理请求)。默认值：“fcfs”。--scheduler-cls: 要使用的调度器类。“vllm.core.scheduler.Scheduler” 是默认调度器。可以是类本身或形如 “mod.custom_class” 的类路径。默认值：“vllm.core.scheduler.Scheduler”。
--seed: 用于操作的随机种子。--max-logprobs: 如果在 SamplingParams 中指定了 logprobs，则返回的最大 log prob 数。默认值：20。--disable-log-stats: 禁用统计日志记录。默认值：False。--enforce-eager: 始终使用 eager-mode PyTorch。如果为 False，将混合使用 eager mode 和 CUDA graph 以获得最佳性能和灵活性。默认值：False。--max-seq-len-to-capture: CUDA graph 覆盖的最大序列长度。当序列上下文长度大于此值时，回退到 eager mode。对于编码器-解码器模型，如果编码器输入的序列长度大于此值，也回退到 eager mode。默认值：8192。--disable-custom-all-reduce: 参见 ParallelConfig。默认值：False。--use-tqdm-on-load, --no-use-tqdm-on-load: 加载模型权重时是否启用/禁用进度条。默认值：True。--multi-step-stream-outputs: 如果为 False，则多步执行将在所有步骤结束后才流式传输输出。默认值：True。--speculative-config: 推测解码的配置。应为 JSON 字符串。--model-loader-extra-config: 模型加载器的额外配置。将传递给与所选 load_format 对应的模型加载器。应为 JSON 字符串。--ignore-patterns: 加载模型时要忽略的模式。默认为 original/**/* 以避免重复加载 llama 的检查点。默认值：[]。--compilation-config, -O: 模型的 torch.compile 配置。当为数字 (0, 1, 2, 3) 时，解释为优化级别（0 默认无优化，1、2 用于内部测试，3 推荐用于生产）。要指定完整配置，请使用 JSON 字符串。支持 -O3 形式，等同于 -O 3。--enable-sleep-mode: 为引擎启用睡眠模式（仅支持 cuda 平台）。默认值：False。--disable-cascade-attn: 禁用 V1 的级联注意力 (cascade attention)。虽然不影响数学正确性，但禁用它可能有助于防止潜在的数值问题。注意，即使设置为 False，仅当启发式判断其有益时才会使用级联注意力。默认值：False。--disable-chunked-mm-input: 禁用 V1 的多模态输入分块注意力。如果设置为 true 且启用了分块预填充，则不希望部分调度多模态项。这确保如果请求有混合提示（如文本 TTTT 后跟图像 IIIIIIIIIIII），其中只有部分图像 token 可以被调度（如 TTTTIIIII，剩下 IIIII），它将被调度为一步 TTTT 和下一步 IIIIIIIIII。默认值：False。--disable-async-output-proc: 禁用异步输出处理。可能导致性能下降。默认值：False。
量化参数 (Quantization Arguments):
--quantization, -q: 用于量化权重的方法。可选值见上文英文描述。如果为 None，则首先检查模型配置中的 quantization_config。如果也为 None，则假定模型未量化，并使用 dtype 确定权重类型。
RoPE 参数 (RoPE Arguments):
--rope-scaling: RoPE (旋转位置编码) 缩放配置，JSON 格式。例如 {"rope_type":"dynamic","factor":2.0}。--rope-theta: RoPE theta 值。与 rope_scaling 一起使用。在某些情况下更改 RoPE theta 可提高缩放模型的性能。
HuggingFace 参数 (HuggingFace Arguments):
--hf-token: 用作远程文件 HTTP bearer 授权的 token。如果为 True，将使用运行 huggingface-cli login 时生成的 token（存储在 ~/.huggingface）。--hf-overrides: HuggingFace 配置的额外参数。应为 JSON 字符串，将解析为字典。
分词器池参数 (Tokenizer Pool Arguments):
--tokenizer-pool-size: 用于异步分词的分词器池大小。如果为 0，将使用同步分词。默认值：0。--tokenizer-pool-type: 用于异步分词的分词器池类型。如果 tokenizer_pool_size 为 0 则忽略。默认值：“ray”。--tokenizer-pool-extra-config: 分词器池的额外配置。应为 JSON 字符串。如果 tokenizer_pool_size 为 0 则忽略。
多模态参数 (Multimodal Arguments):
--limit-mm-per-prompt: 对于每个多模态插件，限制每个提示允许多少输入实例。期望逗号分隔列表，例如 image=16,video=2 允许每个提示最多 16 张图像和 2 个视频。默认为每种模态 1 个。--mm-processor-kwargs: 多模态输入映射/处理的覆盖项，例如图像处理器。例如 {"num_crops": 4}。--disable-mm-preprocessor-cache: 如果为 true，则禁用多模态预处理器/映射器的缓存（不推荐）。默认值：False。
LoRA 参数 (LoRA Arguments):
--enable-lora: 如果为 True，启用 LoRA adapter 的处理。默认值：False。--enable-lora-bias: 如果为 True，启用 LoRA adapter 的偏置 (bias)。默认值：False。--max-loras: 单个批次中 LoRA 的最大数量。默认值：1。--max-lora-rank: 最大 LoRA 秩 (rank)。默认值：16。--lora-extra-vocab-size: LoRA adapter 中可以存在的额外词汇表的最大大小（添加到基础模型词汇表中）。默认值：256。--lora-dtype: LoRA 的数据类型。如果为 auto，将默认为基础模型 dtype。可选值：auto, float16, bfloat16。默认值：“auto”。--long-lora-scaling-factors: 指定多个缩放因子（可以与基础模型缩放因子不同，例如 Long LoRA），以允许同时使用以这些缩放因子训练的多个 LoRA adapter。如果未指定，则仅允许使用基础模型缩放因子训练的 adapter。--max-cpu-loras: 存储在 CPU 内存中的 LoRA 的最大数量。必须 >= max_loras。--fully-sharded-loras: 默认情况下，只有一半的 LoRA 计算与张量并行分片。启用此选项将使用完全分片的层。在高序列长度、最大秩或张量并行大小时，这可能更快。默认值：False。
Prompt Adapter 参数 (Prompt Adapter Arguments):
--enable-prompt-adapter: 如果为 True，启用 PromptAdapter 的处理。默认值：False。--max-prompt-adapters: 一个批次中 PromptAdapter 的最大数量。默认值：1。--max-prompt-adapter-token: PromptAdapter token 的最大数量。默认值：0。
设备参数 (Device Arguments):
--device: vLLM 执行的设备类型。可选值：auto, cuda, neuron, cpu, tpu, xpu, hpu。默认值：“auto”。
OpenTelemetry 参数 (OpenTelemetry Arguments):
--show-hidden-metrics-for-version: 启用自指定版本以来已隐藏的已弃用 Prometheus 指标。例如，如果一个先前弃用的指标自 v0.7.0 版本起被隐藏，您可以使用 --show-hidden-metrics-for-version=0.7 作为临时的应急方案，同时迁移到新的指标。该指标很可能在未来的版本中被完全移除。--otlp-traces-endpoint: OpenTelemetry 跟踪信息将发送到的目标 URL。--collect-detailed-traces: 收集指定模块的详细跟踪信息。仅当设置了 --otlp-traces-endpoint 时才有意义。可能会影响性能。可选值：model, worker, all。
Neuron/Pooler 参数 (Neuron/Pooler Arguments):
--override-neuron-config: 覆盖或设置 neuron 设备配置。例如 {"cast_logits_dtype": "bloat16"}。--override-pooler-config: 覆盖或设置池化模型的池化方法。例如 {"pooling_type": "mean", "normalize": false}。
Reasoning 参数 (Reasoning Arguments):
--enable-reasoning: 是否为模型启用 reasoning_content。如果启用，模型将能够生成推理内容。默认值：False。--reasoning-parser: 选择推理内容解析器，具体取决于您使用的模型。用于将推理内容解析为 OpenAI API 格式。需要与 --enable-reasoning 一起使用。可选值：deepseek_r1, granite。