执行摘要

• 一句话：新增延迟指标文档，澄清 TTFT/ITL/TPOT 口径
• 推荐动作：值得一读的文档型 PR：如果你使用 vllm bench serve 或需要对照其他推理框架的延迟指标，本小节是绕不开的参考。值得关注的设计决策：①全文强调"用测量点和公式而非指标名比较"，是处理 benchmark 术语不一致的正解；②TPOT 公式明确排除首 token、ITL 不产生零时长 gap，澄清了规格解码下的常见误解；③双主题 SVG 配图把抽象定义可视化的做法值得在文档中推广。缺点是 PR body 缺动机描述，合并信息全部依赖文档自身，后续维护者需自行补读上下文。

功能与动机

PR body 未填写实质内容（仅有 Purpose / Test Plan / Test Result 模板标题），动机需从文档内容推断，未发现关联 issue。vllm bench serve 输出的延迟指标在社区中经常被误读，尤其在 speculative decoding 下一次引擎 step 可返回多个 token，ITL 与 TPOT 数值差异明显。文档开篇的 note 直接点明问题：'Metric terminology is not standardized across benchmarking tools. When comparing results, use the measurement points and formulas rather than the metric names alone.' 即希望通过明确测量点与公式来统一口径。DarkLight1337 在 approve 时回复 'Thanks for clearing this up!'，印证此前存在关于指标口径的澄清讨论。

实现拆解

1. 文档主体插入：在 docs/benchmarking/cli.md 的 #### Results Visualization 小节之前新增 #### Understanding the Latency Metrics 小节（+39 行），紧接 vllm bench serve 的示例输出，形成"先看输出、再懂语义"的阅读顺序。

2. 指标定义与公式：以列表形式定义 TTFT（请求发出到首个流式输出到达）、ITL（相邻流式输出之间的时间间隔，跨请求聚合统计）、TPOT（每个请求排除首 token 后计算一次，再跨请求聚合）；TPOT 公式以 LaTeX 块给出：(end-to-end latency − TTFT) / (number of output tokens − 1)，并强调跨请求聚合而非逐 token 聚合。

3. 场景对比：明确标准解码下每次流式输出通常只有 1 个 token，ITL 与 TPOT 数值接近；speculative decoding 下一次引擎 step 可输出多个 draft token，ITL 不添加零时长 gap，TPOT 则摊销到每个输出 token，二者差异被显式讲清，这是全文档最有信息量的部分。

4. 可视化配图：新增 docs/assets/benchmarking/latency-metrics-speculative-decoding-{light,dark}.svg 两份 SVG（各 +77 行），经 #only-light / #only-dark 片段按文档站主题切换。图例用 5 tokens、3 次流式输出（100 ms、140 ms、180 ms）演示：两个 ITL 样本各 40 ms、黄色标出 80 ms 生成跨度、TPOT = (180 − 100) / (5 − 1) = 20 ms/token，并带 title/desc 无障碍描述。

5. 配套：无测试、无配置、无 schema 变更；CI 侧由 build-docs 标签触发文档构建，mergify 已生成 ReadTheDocs 预览。

关键文件：

• docs/benchmarking/cli.md（模块 基准文档；类别 docs；类型 documentation）: 本次变更的主体文档，新增 Understanding the Latency Metrics 小节，定义 TTFT / ITL / TPOT 三个指标、给出 TPOT 公式，并对比标准解码与规格解码下的语义差异，是全部信息量的来源。
• docs/assets/benchmarking/latency-metrics-speculative-decoding-light.svg（模块 文档配图；类别 other；类型 documentation）: 浅色主题示意图，绘制 5 tokens、3 次流式输出的延迟时序，直观展示 TTFT、两次 ITL 样本与 TPOT 的推导过程，是文档核心论点的可视化载体。
• docs/assets/benchmarking/latency-metrics-speculative-decoding-dark.svg（模块 文档配图；类别 other；类型 documentation）: 深色主题示意图，与 light 版内容完全一致仅配色不同，经 #only-dark 片段在暗色主题下展示，保证文档两套主题的可读性。

关键符号：未识别

评论区精华

DarkLight1337（review comment）：建议将 "several accepted draft tokens within a single engine tstep" 中的 tstep 改为 step，修正术语拼写。

作者采纳该修正后，DarkLight1337 随即 approve 并回复：

DarkLight1337（approve）：Thanks for clearing this up!

说明此前围绕本文档措辞与指标口径有过往返澄清，最终达成一致。另 claude[bot] 提示该 PR 来自 fork，自动审查被禁用，维护者可用 @claude review 手动触发一次性 review——属流程提示，无技术结论。

• engine tstep 术语拼写修正 (documentation): 作者采纳修正；DarkLight1337 随后 approve，并评论 'Thanks for clearing this up!'，说明此前往返澄清已达成一致。
• fork PR 自动 review 被禁用 (other): 流程性提示，无技术结论。

风险与影响

• 风险：本质为纯文档变更，无运行时回归、性能、安全风险。但需留意：1）TPOT 公式以 LaTeX（$$ 块）嵌入，渲染依赖文档站 MathJax 支持，迁移主题时需回归验证；2）两张 SVG 通过 #only-light / #only-dark 片段语法按主题切换，依赖 Material for MkDocs 的特定行为，脱离该主题可能不显示；3）文档口径与 vllm bench serve 实现存在长期漂移风险——若日后 ITL 聚合方式、TPOT 定义等计算逻辑调整，需同步维护本文档，否则会误导用户；4）SVG 内嵌文字与数值，后续修改需同时改 light/dark 两份。
• 影响：对用户：benchmark 使用者（尤其 speculative decoding 用户）能据此正确解读 vllm bench serve 输出的 TTFT / ITL / TPOT，避免将 ITL 直接等同于每 token 延迟，跨工具比较时有统一参照。对系统：零运行时影响，仅文档站新增内容与两张静态 SVG。对团队：双主题 SVG 带来后续同步维护成本，但换来指标口径明确化，降低答疑与 issue 来回成本。影响程度为低，属于文档体验与信息准确性的改进。
• 风险标记：纯文档变更无运行风险, 指标口径漂移风险, 公式与 SVG 依赖文档站渲染

关联脉络

• PR #50330 [CI] Organize speculative decoding E2E tests by coverage: 与本 PR 无文件交集，但同属 speculative decoding 功能线；本 PR 文档的核心示例正是规格解码的 token bundling 场景，可与该方向的测试拆分为互为参照。关联较弱。