[RFC]: Consistent semantics for drafted, verified and accepted spec decode tokens

快速结论：该 Issue 讨论的是投机解码（speculative decoding）指标语义不一致的问题：开启自适应验证（AV）和结构化输出（SO）后，[RFC]: Consistent semantics for drafted, verified and accepted spec decode tokens 所描述的 drafted 计数不再等于“提议的草稿 token 数”，也不等于“被目标模型验证的 token 数”，从而出现指标可疑甚至违反不变式的情况。排查时优先确认是否同时启用了 AV 与 SO，并核对 drafted / verified / accepted 三个计数的关系。

适用环境：Issue 仅确认涉及 vLLM 的投机解码路径，包括 sync/async scheduling、adaptive verification（AV）与 structured outputs（SO）。操作系统、Python、CUDA、PyTorch、显卡型号与具体 vLLM 版本号在 Issue 中均未给出，请勿据此推断。

最快修复方案：采用已合并的修复 PR vllm-project/vllm #64156，将 drafted 统一定义为“由 drafter 提议的 token 数”（包含语法非法与被 AV 跳过的 token），新增并上报 verified（进入目标模型前向计算的 token 数），并让 num_spec_steps 在 sync 与 async 调度下计数一致。

注意事项：按提案，启用 SO 后 num_draft_tokens 会上升、draft_acceptance_rate 会下降，这是语义修正而非性能回退；现有基于 accepted / drafted 的看板与基准（如 AIPerf、Datadog）会显示更低的接受率。该 PR 的具体合入发布版本未在 Issue 中说明，升级前请核对对应版本的发布说明。

问题场景

在 vLLM 中使用投机解码（SD），并通过指标（Prometheus 等）观察草稿 token 的起草数、接受数与接受率时触发。典型触发组合是 adaptive verification（AV）与 structured outputs（SO）同时开启，尤其是在 async scheduling 路径下。此时用户会看到 num_draft_tokens 既不是 drafter 提议的 token 数，也不是目标模型实际验证的 token 数；在 async + SO + AV 组合下，若单独补报 verified，还可能出现 drafted < verified，违反 drafted >= verified >= accepted 不变式。此外，sync 与 async scheduling 对 num_spec_steps 的计数方式也不一致（关联 #56977）。

报错原文

[RFC]: Consistent semantics for drafted, verified and accepted spec decode tokens

Invariant: drafted >= verified >= accepted, in total and at every step.

- It is not "proposed tokens". Grammar-invalid draft tokens are subtracted, but draft tokens skipped by AV are kept.
- It is not "verified tokens". Async scheduling subtracts grammar-invalid draft tokens, even though they were included in the target forward pass.

Async + AV, grammar rejects last 2 draft tokens | Target verifies the first 3 (the 3rd is invalid), accepts 1 | 4 | 3 | 1 | 2 (less than `verified`)

原因分析

可能原因是指标语义未随 AV 与 SO 的引入而统一定义。当前 num_draft_tokens 统计的是通过语法检查的草稿 token：一方面把语法非法的草稿 token 减掉了，另一方面又保留了被 AV 跳过的草稿 token，因此它既不等于“提议数”，也不等于“验证数”。在 async scheduling 下，语法非法的草稿 token 虽已被计入目标模型前向计算，却仍被从计数中扣除，进一步造成与 verified 的偏差。同时 verified 完全没有上报，缺失了这一层区分。

环境排查

确认当前 vLLM 是否为包含 PR #64156 的版本；Issue 未给出具体版本号，请以发布说明为准。
确认是否启用投机解码，以及 drafter 的草稿 token 数 k。
确认是否开启 adaptive verification（AV）。
确认是否开启 structured outputs（SO）。
确认使用 sync scheduling 还是 async scheduling。
核对所查看的指标名（如 vllm:spec_decode_num_draft_tokens、num_spec_steps）及其看板计算方式。
Python、CUDA、PyTorch 与显卡型号信息 Issue 未涉及，按实际部署记录核对即可，不作为本问题的判定依据。

解决步骤

先判断现象是否属于语义变化而非性能退化：检查是否只在上表中的 SO/AV 组合下指标偏离，例如 SO 下 num_draft_tokens 升高、draft_acceptance_rate 降低，且 sync 与 async 调度表现一致。
升级到包含 PR #64156 的 vLLM 版本（该 PR 为本 Issue 的已合并修复）。
按新语义读取指标：drafted 为 drafter 提议的 token 数（含语法非法与 AV 跳过的 token），verified 为进入目标模型前向计算的 token 数，accepted 为目标模型接受的 token 数。
调整看板与基准统计口径：接受率改用 accepted / drafted，平均接受长度仍为 1 + accepted / num_spec_steps；如需评估 draft 质量，可另看 accepted / verified（可优先尝试，Issue 评论中仅作为建议讨论）。
如依赖旧的 num_draft_tokens 口径排查回归，需自行记录升级前后数值，避免把语义变化误判为性能问题。

验证方法

在新版本上运行包含 AV、SO 与 sync/async 调度的用例，确认每一步及总量都满足 drafted >= verified >= accepted；确认 num_spec_steps 在 sync 与 async 调度下对同一请求计数一致，包括全部草稿 token 被语法拒绝的情况；确认 verified 已在与 drafted、accepted 相同的位置（指标与周期日志）上报；在 async + AV + SO 组合下确认不再出现 drafted 小于 verified 的情况。