# PR #7001 完整报告

- 仓库：`PaddlePaddle/FastDeploy`
- 标题：[Feature] Support mtp overlap schedule
- 合并时间：2026-04-01 14:24
- 原文链接：http://prhub.com.cn/PaddlePaddle/FastDeploy/pull/7001

---

# 执行摘要

- 一句话：支持 MTP 场景开启 overlap schedule 优化，提升解码性能。
- 推荐动作：建议技术管理者和工程师精读此 PR，重点关注：
 - 内核修改中的无效槽位处理逻辑（如 if (bs_idx < 0) return;），以理解 overlap schedule 下的防御性编程。
 - gpu_model_runner.py 中的 overlap schedule 实现，特别是 _resolve_current_launch_token_num 方法的变更，体现了性能优化设计。
 - 注意 fastdeploy-bot 指出的 API 不匹配 bug 的修复情况，确保跨平台兼容性。

# 功能与动机

PR body 明确说明动机是“支持 MTP（不开启 logprob）场景下开启 overlap schedule”，以优化性能，通过避免同步开销和延迟数据传输来提升效率。

# 实现拆解

实现方案拆解为以下关键点：
1. **移除 CPU-GPU 同步**：在多个 CUDA 内核（如 draft_model_preprocess.cu、unified_update_model_status.cu）中，移除 not_need_stop 等张量的 GPU 拷贝，直接使用 CPU 数据，减少同步开销。
2. **异步拷贝优化**：在 fastdeploy/model_executor/pre_and_post_process.py 中，将 save_output 逻辑重构为 save_output_specualate，延迟 accept_tokens_cpu 等数据的传输到非关键路径。
3. **处理无效槽位**：在 overlap schedule 下，空间预分配引入无效槽位，多个 CUDA 内核（如 reasoning_phase_token_constraint.cu）添加 if (bs_idx < 0) return; 检查，提前退出处理。
4. **新增字段和标志**：在 forward_meta.py 中添加 real_bsz 字段，在 mtp.py 中添加 exist_prefill_flag，用于缓存状态避免重复计算。
5. **更新 overlap schedule 逻辑**：在 gpu_model_runner.py 中，修改 _resolve_current_launch_token_num 和 _predict_next_launch_token_num，支持 MTP 场景下的 overlap 调度，并统一使用 CPU barrier。

关键文件：
- `fastdeploy/spec_decode/mtp.py`（模块 Speculative Decoding）: 核心 MTP 逻辑修改，包括添加 exist_prefill_flag、异步拷贝优化和修复 XPU 分支 bug
- `fastdeploy/worker/gpu_model_runner.py`（模块 Scheduler）: overlap schedule 实现的关键变更，更新了 token 计数和调度逻辑
- `custom_ops/gpu_ops/speculate_decoding/speculate_preprocess.cu`（模块 GPU Ops）: 修改了批次 ID 和填充逻辑，支持 overlap schedule 下的无效槽位处理
- `fastdeploy/model_executor/pre_and_post_process.py`（模块 Model Executor）: 后处理重构，新增 save_output_specualate 函数实现异步拷贝
- `fastdeploy/model_executor/graph_optimization/cudagraph_piecewise_backend.py`（模块 Graph Optimization）: 更新了 real_bsz 处理逻辑，支持 MTP 和 overlap schedule 下的 CUDAGraph 优化

关键符号：_resolve_current_launch_token_num, save_output_specualate, DraftModelPreprocess, eagle_get_self_hidden_states, speculate_schedule_cache


# 评论区精华

Review 中核心讨论包括：
- **fastdeploy-bot 指出 P1 逻辑 bug**：在 fastdeploy/spec_decode/mtp.py 的 XPU 分支中，eagle_get_self_hidden_states 内核 API 不匹配，可能传递错误参数导致结果错误；bot 建议使用 last_seq_lens_encoder 而非 step_idx，此问题在 commit 历史中有修复（如 fix xpu bug）。
- **freeliuzc 建议删除废弃变量**：在 fastdeploy/worker/input_batch.py 中，删除 last_seq_lens_encoder 等未使用变量，作者 Sunny-bot1 响应“done”。
- **gongshaotian 提到限制**：评论“NOTE：RL 场景当前没法开 Overlap schedule”，指出强化学习场景下无法应用此优化，需注意兼容性。
- **整体批准与测试覆盖**：review 被多位维护者批准（LGTM），但 Codecov 报告显示 patch 覆盖率为 86.9%，有 11 行未覆盖，需关注测试完整性。

 - API 不匹配 bug 在 XPU 分支 (correctness): 需要修复为使用 last_seq_lens_encoder 而非 step_idx；commit 历史显示有相关修复（如 fix xpu bug）
- 删除废弃变量 (design): 作者 Sunny-bot1 响应“done”，变量被移除
- RL 场景下 overlap schedule 限制 (design): 需用户注意优化不适用于 RL 配置，PR 未修改此限制

# 风险与影响

- 风险：技术风险具体包括：
 1. **逻辑错误风险**：fastdeploy-bot 指出的 API 不匹配 bug（如 eagle_get_self_hidden_states 在 XPU 分支），若未完全修复，可能导致 MTP 在 XPU 平台上输出错误。
 2. **回归风险**：修改了 23 个文件，包括核心 CUDA 内核（如 speculate_preprocess.cu）和调度逻辑（gpu_model_runner.py），影响推测解码和 overlap schedule 路径，可能引入新 bug 或性能倒退。
 3. **兼容性风险**：gongshaotian 评论提到 RL 场景无法开启 overlap schedule，优化可能不适用于所有配置，需用户注意场景限制。
 4. **测试覆盖不足**：Codecov 报告显示 86.9% 覆盖率，有 11 行代码未覆盖，可能隐藏未测试的边缘情况。
- 影响：影响范围和程度评估：
- **对用户**：在 MTP 不开启 logprob 的解码阶段，默认开启 overlap schedule 可提升性能（如 PR body 中的 GLM TP4 效果图），但需注意 RL 场景下无效。
- **对系统**：优化了 CPU-GPU 数据流，减少同步开销，可能提高整体吞吐量；但修改涉及核心推测解码和调度模块，影响面较广。
- **对团队**：引入新设计（如异步拷贝、无效槽位处理），需工程师关注代码变更以维护一致性；review 中讨论的 bug 需确保修复，避免生产问题。
- 风险标记：API 不匹配 bug, 测试覆盖不足 , 核心路径变更 , 兼容性限制

# 关联脉络

- PR #6680 [Optimization] Optimize ttft for prefill pd: 都涉及调度优化，PR #6680 优化预填充调度，本 PR 优化 MTP 解码调度，可视为调度模块的演进
- PR #7030 [Optimization]Merge Text processor: 都包含代码重构和性能优化，PR #7030 统一处理器逻辑，本 PR 优化数据流，反映仓库对效率的持续改进