执行摘要

• 一句话：为 bench serve 可视化参数添加文档
• 推荐动作：建议合并，文档补全对用户友好。参数解析方式的变化（逗号分隔）是合理的改进，但应确保在发布说明中提及此 breaking change。代码改动量小且经过评审，正确性有保障。

功能与动机

PR body 明确指出 'This PR mainly add documentation for the features added in (merged) PR #35220'，目的是补全 bench serve 可视化功能的使用文档，使社区用户能够上手使用。

实现拆解

1. 修改参数解析：在 vllm/benchmarks/serve.py 中将 --timeline-itl-thresholds 的 type 从 float 改为 str，nargs=2 改为单值，并在 main_async 中添加逗号分割和校验逻辑，支持 '2,5' 格式，同时保留向后兼容。

2. 添加文档章节：在 docs/benchmarking/cli.md 中新增 Results Visualization 小节，包含 --plot-timeline 和 --plot-dataset-stats 的用法示例、参数解释，并嵌入交互式 HTML 时间线 <iframe> 和数据集统计图。

3. 新增示例资源：添加 docs/assets/contributing/vllm_bench_serve_timeline.html（交互式时间线示例）和 docs/assets/contributing/vllm_bench_serve_dataset_stats.png（数据集统计图），供文档嵌入展示。

4. 配置 typos 忽略：在 pyproject.toml 中将新加入的 HTML 资产文件添加到 typos 忽略列表，避免因 Plotly 生成的内联代码触发拼写检查错误。

关键文件：

• vllm/benchmarks/serve.py（模块 基准测试；类别 source；类型 core-logic）: 核心实现：修改了 --timeline-itl-thresholds 参数的类型和解析逻辑，从 nargs=2 的 float 值改为逗号分隔字符串，并添加了输入校验。
• docs/benchmarking/cli.md（模块 文档；类别 docs；类型 documentation）: 主要文档变更：新增 'Results Visualization' 章节，包含完整命令示例、参数说明和嵌入的交互式时间线。
• docs/assets/contributing/vllm_bench_serve_timeline.html（模块 文档资产；类别 other；类型 core-logic）: 新增的交互式 HTML 时间线示例文件，用于文档嵌入展示。
• pyproject.toml（模块 项目配置；类别 config；类型 configuration）: 将 vllm_bench_serve_timeline.html 加入 typos 忽略列表，因为 Plotly 生成的内联代码包含大量“拼写错误”。
• docs/assets/contributing/vllm_bench_serve_dataset_stats.png（模块 文档资产；类别 other；类型 core-logic）: 新增的数据集统计图示例图片，用于文档展示。

关键符号：main_async

关键源码片段

vllm/benchmarks/serve.py

核心实现：修改了 --timeline-itl-thresholds 参数的类型和解析逻辑，从 nargs=2 的 float 值改为逗号分隔字符串，并添加了输入校验。

# vllm/benchmarks/serve.py
​
# CLI 参数定义区：改为字符串类型，默认逗号分隔
parser.add_argument(
    "--timeline-itl-thresholds",
    type=str,
    default="25,50",
    help="ITL thresholds in milliseconds for timeline plot coloring. "
    "Specify two comma-separated values to categorize inter-token "
    "latencies into three groups: below first threshold (green), "
    "between thresholds (orange), and above second threshold (red).",
)
​
# 在 main_async 中增加校验和解析
async def main_async(args: argparse.Namespace) -> dict[str, Any]:
    # ... 其他代码
    # Validate timeline ITL thresholds
    if args.plot_timeline:
        try:
            itl_thresholds = [
                float(t.strip()) for t in args.timeline_itl_thresholds.split(",")
            ]
            if len(itl_thresholds) != 2:
                raise ValueError(
                    f"Expected 2 ITL threshold values, got {len(itl_thresholds)}"
                )
        except ValueError as e:
            raise ValueError(f"Invalid --timeline-itl-thresholds format: {e}") from e
    # ... 后续校验
​
# 使用时转换为秒
itl_thresholds_sec = [
    float(t) / 1000.0 for t in args.timeline_itl_thresholds.split(",")
]

评论区精华

1. --timeline-itl-thresholds 参数名错误：gemini-code-assist[bot] 指出文档中写成了单数 --timeline-itl-threshold，而实现中使用的是复数 --timeline-itl-thresholds。作者随后修正。

2. 逗号分隔 vs 空格分隔：gemini-code-assist[bot] 最初基于旧代码（空格分隔）提示文档中的逗号用法会导致解析错误。但作者后续修改了实现支持逗号分隔，因此该评论实际已被解决。

3. frder 拼写错误：DarkLight1337 发现 <iframe> 中 frameborder 误写为 frder，作者确认是 typo 并修复。

4. pyproject.toml 中忽略 typo 的原因：DarkLight1337 询问为何需要忽略，作者解释是因为 Plotly 生成的 HTML 包含大量内联代码，触发大量拼写错误。

• 参数名错误：单数 vs 复数 (correctness): 作者已修正文档中的参数名。
• 逗号分隔 vs 空格分隔的兼容性 (correctness): 作者后续修改了实现，支持逗号分隔，因此该问题已通过代码变更解决。
• HTML 拼写错误：frder vs frameborder (correctness): 作者确认是 typo 并提交修正。
• 将 HTML 资产加入 typos 忽略列表的原因 (question): 作者解释 Plotly 生成的 HTML 包含大量内联 JS，触发许多拼写告警，忽略文件是合理的。

风险与影响

• 风险：

  1. 参数格式变更风险：--timeline-itl-thresholds 从空格分隔改为逗号分隔，可能破坏已有用户脚本。但 PR 同时提供了明确的错误提示，且原默认值 25.0 50.0 在新格式下变为 '25,50'，过渡期较短，风险较低。
  2. 文档示例不准确风险：文档中的命令行示例包含 --timeline-itl-thresholds 2,5，若用户误用空格则可能报错，但实际代码已支持逗号，风险可控。
  3. HTML 资产文件过大：新增的 vllm_bench_serve_timeline.html 有 3888 行，包含完整的 Plotly JS 库，可能会增加仓库大小，但对功能无实质风险。
     - 影响：用户：受益于文档指南，能够使用可视化功能调试基准测试结果，无需阅读源码。参数解析方式变化可能影响少量自动化脚本用户。
     系统：无影响，仅文档和微小代码改动。
     团队：文档维护成本增加，但有助于提升社区体验。

• 风险标记：参数格式变更（逗号代替空格）, 文档示例可能误导用户

关联脉络

• PR #35220 [Feature] bench serve visualization: 本 PR 为该 PR 添加文档和一个小改动，是直接关联的上游功能 PR。