[Doc]: Docs use CLI flag names that `vllm serve` does not register

这是 vLLM 文档配置项拼写不一致的问题,不是运行故障。多数页面把 `vllm serve` 的命令行参数写成下划线形式(如 `--hf_overrides`),而参数实际注册和 `--help` 输出的是连字符形式(如 `--hf-overrides`)。优先核对文档页面的拼写是否与 `vllm

快速结论:这是 vLLM 文档配置项拼写不一致的问题,不是运行故障。多数页面把 `vllm serve` 的命令行参数写成下划线形式(如 `–hf_overrides`),而参数实际注册和 `–help` 输出的是连字符形式(如 `–hf-overrides`)。优先核对文档页面的拼写是否与 `vllm serve –help` 输出一致。

适用环境:vLLM 仓库 main 分支文档(涉及 docs/models、docs/features、docs/design、docs/serving、docs/getting_started 等页面);Issue 未提供具体的 Python、CUDA、显卡版本信息,故不补充。

最快修复方案:将文档中下划线拼写的参数统一改为连字符形式,即把 --hf_overrides 改为 --hf-overrides、--tokenizer_mode 改为 --tokenizer-mode、--config_format 改为 --config-format、--load_format 改为 --load-format 等,共涉及 9 个文档页面。该修复已由 PR #65039(合并了 #65040 的改动)合入 main 分支。

注意事项:下划线拼写在 Python 路径下并未失效——vllm serve 使用 FlexibleArgumentParser,会在查找参数前把长选项中的下划线重写为连字符,因此两种拼写都能被接受。但 Rust 前端的 vllm-rs frontend 和 vllm-rs render 直接用 clap 解析 argv,会拒绝下划线拼写并报 clap 错误;只有 vllm-rs serve 在 #65370 中学会了下划线归一化。另外,docs/design/custom_op.md 中的点号形式 --compilation-config.custom_ops '...' 是 FlexibleArgumentParser 的既有特性,修复后仍保留。

问题场景

用户在阅读 vLLM main 分支的文档页面并按文档示例执行 vllm serve 命令时,发现文档里写的参数名(下划线形式)与 vllm serve --help 以及自动生成的 CLI 参考 docs/cli/serve.md 中列出的参数名(连字符形式)不一致。受影响页面包括:

  • docs/models/pooling_models/scoring.md:--hf_overrides(5 处)
  • docs/features/tool_calling.md:--tokenizer_mode、--config_format、--load_format(10 处)
  • docs/design/torch_compile.md、docs/design/debug_vllm_compile.md、docs/serving/expert_parallel_deployment.md:--compilation_config
  • docs/design/custom_op.md:--compilation_config.custom_ops(6 处,点号形式)
  • docs/features/custom_logitsprocs.md:--logits_processors(2 处)
  • docs/features/speculative_decoding/extract_hidden_states.md:--speculative_config、--kv_transfer_config
  • docs/getting_started/installation/gpu.xpu.inc.md:--max_model_len

报错原文

[Doc]: Docs use CLI flag names that `vllm serve` does not register

Several pages document `vllm serve` options with the underscore spelling
(e.g. `--hf_overrides`) while the options are registered under the dash-separated
spelling (e.g. `--hf-overrides`).

原因分析

问题根源是文档拼写与参数注册名不一致,而不是命令本身不可用。参数在 vllm/engine/arg_utils.py 和 vllm/entrypoints/common/cli_args.py 中按连字符形式注册,vllm serve --help 和生成的 CLI 参考也使用连字符形式。但文档中有页面写成了下划线形式,FlexibleArgumentParser 会重写长选项名,使两种拼写都能解析,因此这些下划线写法并没有直接报错,只是与文档整体风格和注册名不一致。

Issue 指出有两个页面自身前后不一致,说明这些更可能是笔误而非有意采用另一种拼写:scoring.md 在同一页面既有 --hf-overrides 又有 --hf_overrides;tool_calling.md 在同一行混用了 --tokenizer_mode 和连字符形式的 --tool-call-parser。

Rust 前端是例外:vllm-rs frontend 和 vllm-rs render 用 clap 直接解析 argv,会以下划线拼写报 clap 错误;vllm-rs serve 已在 #65370 中加入归一化处理。

环境排查

  • 确认 vLLM 是否拉取自 main 分支(问题描述基于 main 上的文档状态)。
  • 确认当前文档页面的拼写:打开上述 9 个页面,检查相关参数是下划线还是连字符形式。
  • 对照 vllm serve --help 输出中同名参数的实际拼写。
  • 如使用 Rust 前端,确认是否为 vllm-rs frontend 或 vllm-rs render(这两个命令对下划线拼写会直接报错),以及是否已包含 #65370 的改动。
  • Issue 未提供 Python、PyTorch、CUDA、显卡等版本信息,无需据此排查。

解决步骤

  1. 以 vllm serve --help 中打印的参数名为准,确认连字符形式是应记录的形式。
  2. 在 docs/models/pooling_models/scoring.md 中把 --hf_overrides 改为 --hf-overrides。
  3. 在 docs/features/tool_calling.md 中把 --tokenizer_mode、--config_format、--load_format 改为 --tokenizer-mode、--config-format、--load-format。
  4. 在 docs/design/torch_compile.md、docs/design/debug_vllm_compile.md、docs/serving/expert_parallel_deployment.md 中把 --compilation_config 改为 --compilation-config。
  5. 在 docs/features/custom_logitsprocs.md 中把 --logits_processors 改为 --logits-processors。
  6. 在 docs/features/speculative_decoding/extract_hidden_states.md 中把 --speculative_config、--kv_transfer_config 改为 --speculative-config、--kv-transfer-config。
  7. 在 docs/getting_started/installation/gpu.xpu.inc.md 中把 --max_model_len 改为 --max-model-len。
  8. 对于 docs/design/custom_op.md:点号形式 --compilation-config.custom_ops '...' 作为 FlexibleArgumentParser 的既有特性保留;同时把两个 custom_ops 示例改为每个列表项一条指令的形式(["all", "-op1"]、["none", "+op1", "+op2"]),这是 CompilationConfig 校验所要求的形式;CompilationConfig.custom_ops 的 docstring 也同步修正。
  9. docs/design/huggingface_integration.md 中的 --trust_remote_code 按 Issue 计划不作修改(该段正由 #47887 重写)。

上述改动已由 #65039 合入 main(#65040 被关闭,其改动并入 #65039),无需自行重复提交相同修复。

验证方法

在 main 分支上打开 Issue 列出的 9 个页面,确认对应参数均使用连字符拼写,且与 vllm serve --help 及 docs/cli/serve.md 一致;custom_op.md 中的 custom_ops 示例应为每个列表项一条指令的形式。

参考来源

vllm-project/vllm #65042

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36544

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注