执行摘要

• 一句话：修复 P/D 下多模块 MTP 未验证 draft 污染 KV cache
• 推荐动作：值得精读，尤其适合关注 P/D 架构、KV connector 与投机解码交叉区域的工程师。核心设计决策是“把跨模块的 lookahead 推导收敛为单一属性 + 单一 backoff 函数”，并以 max 组合语义兼容 Mamba 与 MTP 两类 drafter，这种消除重复推导、防止契约漂移的思路可直接借鉴。基准数据完整（含逐 position 接受率），可作为同类性能修复 PR 的范本。

功能与动机

在多模块 MTP 结合 P/D 时，prefill 实例对完整 prompt 做 prefill，最后 N 个 MTP 层各生成一个 draft token。问题出在最后一个 prefill chunk：MTP 层 i 会把未验证的 draft token 嵌入层 i+1，这些 token 残留在最后 N-1 个 MTP 层的 KV cache 中。standalone 模式下 decode 步骤会依据 rejection 数重建这些槽位，但 P/D 模式下 decode 实例收不到该信息。PR body 明确指出“An acceptance length of 1.089 means ~99% of drafts were rejected. Speculative decoding was effectively inert under P/D before the fix.”

实现拆解

实现分为 4 步：

1. 新增统一契约 VllmConfig.num_prefill_lookahead_tokens（vllm/config/vllm.py）。该属性返回 prefill 阶段 drafter 会读取的、超出 target 模型已计算范围的 token 数：多模块 MTP 返回 num_speculative_tokens（每层 MTP 比前一层多读一个 token，链条需要完整 runway），Eagle 家族其他 drafter 返回 1，非 eagle 配置返回 0。新增它是为了消除调度器、KV cache 管理器、KV connector 各自推导 lookahead 导致的漂移风险。

2. 泛化 NIXL 调度器的 backoff 逻辑（vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_scheduler.py）。新增 _prefill_backoff()，取 max(1 if self._has_mamba else 0, num_prefill_lookahead_tokens - 1)，兼容纯 Mamba、纯多模块 MTP 及两者并存的场景；_truncate_mamba_request_for_prefill 重命名为 _truncate_request_for_prefill 并改为按 backoff 批量删除尾部 token（原先只 pop 1 个）；_get_remote_prefill_token_count 同样改为消费 _prefill_backoff()。on_new_request 中调用条件从 and self._has_mamba 放宽为只要 do_remote_decode 就截断。

3. 收敛各 callsite 到新属性。vllm/v1/core/sched/scheduler.py 中 num_prefill_lookahead 直接赋值为 vllm_config.num_prefill_lookahead_tokens（删除 13 行本地推导）；vllm/v1/worker/gpu/model_runner.py 改为 max(1, vllm_config.num_prefill_lookahead_tokens)；vllm/v1/core/kv_cache_utils.py 中 SlidingWindowSpec.extra_retained_tokens 改为 max(0, num_prefill_lookahead_tokens - 1)。

4. 测试配套。tests/v1/kv_connector/unit/utils.py 为 make_nixl_scheduler / make_nixl_push_scheduler 夹具补上 vllm_config（SimpleNamespace 或 MagicMock 带 num_prefill_lookahead_tokens=0），保证 _prefill_backoff() 在单测中可解析；test_nixl_push_connector.py 将 patch 目标更新为新方法名 _truncate_request_for_prefill。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_scheduler.py（模块 KV 传输；类别 source；类型 core-logic；符号 _prefill_backoff, _truncate_mamba_request_for_prefill, _truncate_request_for_prefill, _get_remote_prefill_token_count）: 修复的核心：新增 _prefill_backoff() 统一 Mamba 与多模块 MTP 的 backoff 语义，泛化 _truncate_request_for_prefill 批量截断尾部 token，并让 _get_remote_prefill_token_count 消费同一 backoff，保证 P 侧截断与 D 侧重算范围严格一致。
• vllm/config/vllm.py（模块 全局配置；类别 source；类型 core-logic；符号 num_prefill_lookahead_tokens）: 新增 num_prefill_lookahead_tokens 属性，作为调度器、KV cache 管理器、KV connector 三方的统一 lookahead 契约，是本 PR 消除重复推导的基础设施。
• vllm/v1/core/sched/scheduler.py（模块 调度器；类别 source；类型 core-logic）: 删除本地重复推导的 num_prefill_lookahead 逻辑（-13 行），改为直接消费新属性，确保调度器与 connector 的截断语义一致。
• vllm/v1/worker/gpu/model_runner.py（模块 模型执行；类别 source；类型 data-contract）: Model Runner V2 中 RequestState 的 num_prefill_lookahead 参数改为 max(1, vllm_config.num_prefill_lookahead_tokens)，避免 MRV2 侧与 connector 侧对 MTP 窗口的理解不一致。
• vllm/v1/core/kv_cache_utils.py（模块 缓存管理；类别 source；类型 core-logic）: 滑动窗口 KV cache 的 extra_retained_tokens 改为 max(0, num_prefill_lookahead_tokens - 1)，保证多模块 MTP 下窗口保留足够的重算 token。
• tests/v1/kv_connector/unit/utils.py（模块 测试夹具；类别 test；类型 test-coverage）: 两个测试夹具均需提供 vllm_config.num_prefill_lookahead_tokens，否则 _prefill_backoff() 在单测中无法解析，属于必要的契约同步。
• tests/v1/kv_connector/unit/test_nixl_push_connector.py（模块 连接器测试；类别 test；类型 test-coverage）: patch 目标随重命名从 _truncate_mamba_request_for_prefill 更新为 _truncate_request_for_prefill，保持抢占保护测试有效。

关键符号：_prefill_backoff, _truncate_request_for_prefill, _truncate_mamba_request_for_prefill, _get_remote_prefill_token_count, num_prefill_lookahead_tokens

评论区精华

本 PR 的 review 过程非常精简，没有实质性的技术争论：

• claude[bot]：因 PR 来自 fork，自动 review 被禁用，提示维护者可手动触发 @claude review，最终未触发。
• WoosukKwon：直接 APPROVED，无评论。

由于 review 评论为空，设计权衡主要沉淀在 PR body 的基准数据和代码注释中（backoff 取 max 兼顾 Mamba 与 MTP、_p_side_truncated 防重入截断等），未发现未解决的疑虑。

• Fork PR 自动 review 被禁用 (other): 无实质技术讨论，WoosukKwon 直接 APPROVED。

风险与影响

• 风险：
  1. NIXL P/D 路径行为面扩大：on_new_request 不再限定 _has_mamba，所有带 do_remote_decode 的请求都会走截断逻辑；虽然 _prefill_backoff() 在无 Mamba 且无 MTP 时返回 0 而空转，但该分支成为所有 P/D 请求的必经路径，回归影响面比原先大。
  2. 多模型共存场景：当 Mamba 与多模块 MTP 同时出现时 backoff 取较大值，prefill 侧少算的 token 数增加，chunked prefill 边界与 encoder 调度平移的交互需要额外验证，基准未覆盖该组合。
  3. 契约漂移风险：num_prefill_lookahead_tokens 出现后，任何仍按 use_multi_module_mtp() 自行推导 lookahead 的调用点都可能与 connector 侧不一致；本 PR 已收敛 4 个已知调用点，但若未来新增路径未消费该属性，会复现同类 bug。
  4. 验证覆盖有限：基准仅覆盖 Inkling-Small-NVFP4 单一模型、单一 batch 配置，未覆盖纯 Mamba P/D 回归（虽然测试夹具已更新，但缺少针对新属性的行为断言）。
     - 影响：对用户：P/D + 多模块 MTP（如 DSpark）部署的投机解码从“几乎失效”变为显著生效，acceptance_rate 提升 30.4 个百分点、吞吐 +245%、TPOT −72%，属于数量级改善。对系统：改动横跨 NIXL KV connector 调度器、全局配置、V1 调度器、Model Runner V2 和 KV cache 分配逻辑，引入了新的跨模块契约属性，后续相关开发必须统一消费该属性。对团队：提交单次完成、逻辑集中、基准数据完整，降低了 review 成本；测试夹具同步更新说明作者注意到了单测环境的配置解析问题。
     - 风险标记：核心执行路径变更, 跨模块契约调整, 测试覆盖有限, 多模型共存未验证

关联脉络

• PR #56955 [CI] Fix NIXL push worker test stub after failure deferral: 同一测试文件 test_nixl_push_connector.py 的配套修复，同属 NIXL push connector 路径。
• PR #56903 [Perf][DSpark] Collapse DeepSeek-V4.1 draft states before SP all-gather: 同一 DSpark / 多模块 MTP 功能线，围绕 DeepSeek V4.1 投机解码的性能与正确性优化。
• PR #56387 [Bugfix][Spec Decode][MoE] Avoid uninitialized EPLB state in DeepSeek V4.1 DSpark drafter: 同为 DSpark drafter 稳定性修复，体现该功能线的持续加固。
• PR #56888 [MRV2] Buffer util simplifications: 同属 MRV2 改造线，本 PR 也修改了 vllm/v1/worker/gpu/model_runner.py 且标签含 mrv2。