# PR #29070 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[DSV4] perf: Enable alt stream during BCG prefill
- 合并时间：2026-08-11 20:10
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/29070

---

# 执行摘要

- 一句话：DSV4 BCG prefill 启用多流重叠，TTFT 提升约 1%-4%
- 推荐动作：值得精读。源码只有 5 行，但 review 过程展示了三条可复用的工程准则：
 1) 对模型专属配置项保持警惕，优先用数据证明必要性；
 2) 用 128-8k ISL 的 TTFT sweep 支撑「移除 gate」的决策，而不是凭直觉保留阈值；
 3) 主动识别上游 PR（#29866）已覆盖自己的封装并删除 wrapper，避免重复实现与维护负担。建议同时阅读 #29866 理解 get_is_capture_mode 的语义扩展，以及 #33865 了解 DSV4 prefill CP 组合的限制来源。

# 功能与动机

PR body 指出 shared expert alt stream 执行可以用于 BCG prefill，并配了串行与流并行两张 profile 对比图，目标是改善 TTFT、交互性与吞吐。作者在 rescoping 说明中进一步澄清：main 上 _forward_prepare_multi_stream 仍被 decode 大小限制（Blackwell 128 / 其他 64）门控，prefill bucket 无法获得 attention 预处理重叠，因此需要为 BCG prefill 放开该限制，同时维持 DSA prefill CP 与 HIP 路径的排除。

# 实现拆解

1. 放宽多流门控：在 python/sglang/srt/models/deepseek_v4.py 的 forward() 中，enable_multi_stream 条件由 `x.shape[0] <= self._multi_stream_bs_limit` 扩展为 `is_in_breakable_cuda_graph() or x.shape[0] <= self._multi_stream_bs_limit`，使 BCG 的 breakable CUDA graph 捕获 / 回放上下文不再受 decode 批量上限约束，attention 的 q/kv-prep 多流重叠可进入 prefill 图；DSA prefill CP 与 HIP 无 compressor 两个排除分支原样保留。
2. 移除初版配置层：早期提交引入了 SGLANG_OPT_DSV4_PREFILL_MULTI_STREAM_MAX_TOKENS 环境变量，并读取 get_server_args().cuda_graph_config.prefill.max_bs 作为 4096 默认上限；nvpohanh 质疑模型专属 env var 的必要性及 8192/4096 默认值不一致，同时 CI 因进程级全局配置直接读取的断言失败（deepseek_v4.py:737），最终提交 2619ba（fix: remove DSV4 prefill token env override）删除该配置。
3. 与上游实现去重：提交 53ea8f 说明 #29866（已合入 main）使 get_is_capture_mode() 在 breakable CUDA graph 上下文（replay_session 后的 enable_breakable_cuda_graph）返回 true，覆盖 warmup/capture/replay 三阶段，因此本 PR 最初加的 model_capture_mode() wrapper 被删除；同时 shared-vs-routed expert 双流重叠（forward_normal_dual_stream）也已由 #29866 带入 BCG prefill，多流门控收敛到一处。
4. 数据驱动简化：按 b8zhong 要求完成 ISL 128-8192 的 TTFT sweep（8×B200、16 prompts、OSL16、flush-cache），256-8192 区间均值提升 0.95%-3.74%，128 判定为一次 cold outlier 主导的噪声；据此 b8zhong 建议移除 gate 与 threshold，作者确认后最终仅保留门控分支扩展。
5. 测试与验证配套：未新增单元测试；通过重跑 test_deepseek_v4_flash_fp4/fp8_b200/h200、megamoe_b200、deepseek_v4_flash_fp4_b200_cp 等 e2e 用例，并以 gsm8k（96.29%）验证精度无回退。

关键文件：
- `python/sglang/srt/models/deepseek_v4.py`（模块 模型前向；类别 source；类型 core-logic；符号 DeepseekV4Attention.forward）: 唯一变更文件，DSV4 attention forward 的 enable_multi_stream 门控在此扩展，是 BCG prefill 多流重叠能生效的关键开关。

关键符号：DeepseekV4Attention.forward

## 关键源码片段

### `python/sglang/srt/models/deepseek_v4.py`

唯一变更文件，DSV4 attention forward 的 enable_multi_stream 门控在此扩展，是 BCG prefill 多流重叠能生效的关键开关。

```python
# deepseek_v4.py 中 attention forward 的多流重叠门控（最终落地版本）。
# 相比初版，此处已移除模型专属环境变量与 token 上限，只剩一个条件分支扩展。
enable_multi_stream = (
    envs.SGLANG_OPT_USE_MULTI_STREAM_OVERLAP.get()
    and self.alt_streams is not None
    and get_is_capture_mode()
    # 关键新增分支：BCG 的 breakable CUDA graph 捕获 / 回放上下文下，
    # prefill 不再受 decode 专属 batch 上限（Blackwell 128 / 其他 64）约束，
    # 使 q/kv-prep 双流重叠能进入 prefill CUDA graph，减少串行等待。
    and (
        is_in_breakable_cuda_graph()
        or x.shape[0] <= self._multi_stream_bs_limit
    )
    # 保留既有排除项：DSA prefill CP 组合与 HIP 无 compressor 路径
    # 仍不走多流，避免与既有 attention 路径冲突或破坏分片语义。
    and not (self.dsa_enable_prefill_cp and dsa_use_prefill_cp(forward_batch))
    and not (_is_hip and self.compressor is None)
)

```

# 评论区精华

核心交锋集中在「是否需要配置项」与「门控是否该存在」两点：nvpohanh 对模型专属 env var 持谨慎态度，原话为 "I am reluctant to introduce model-specific env vars unless necessary"，并指出默认值矛盾（env 默认 8192 而代码内回退 4096）；b8zhong 要求先补数据再定设计："Can we get some more TTFT benchmarks using BCG and prefill from 128 to 8k tokens?"，mattteochen 完成后给出 sweep 表，128 被判定为一次 cold outlier 主导的噪声；基于数据，b8zhong 直接建议 "I think we should remove the gate and remove the threshold, do you agree?"，作者答复 "Yes, removed"，最终实现比初版少了一整个配置层；此外 nvpohanh 定位了 CI 失败根因：`direct process-global config field reads grew: 1 > baseline 0`，指向 get_server_args().cuda_graph_config 的进程级全局读取，推动作者删除该读取。

- 模型专属 env var 必要性与默认值不一致 (design): 作者在后续 benchmark 基础上删除了整个 env var 与上限，未引入模型专属配置。
- 基于 TTFT sweep 数据移除 gate 与 threshold (performance): 合并版本只剩 is_in_breakable_cuda_graph() 分支，无阈值限制。
- get_server_args() 进程级全局配置直接读取违反断言 (correctness): 该读取随 env var 一起被删除，最终版本不包含进程级全局配置直接读取。
- #29866 语义扩展后 wrapper 冗余 (design): 删除 wrapper，多流门控收敛到一处，避免重复实现。

# 风险与影响

- 风险：性能回归边界：TTFT sweep 覆盖到 ISL 8192，更高 ISL、更高并发或混合请求批次的 BCG prefill 多流重叠收益未验证，且数据显示增益随 ISL 增长递减（3.74%→0.95%）。语义耦合：门控依赖 #29866 引入的 get_is_capture_mode() 在 breakable 上下文返回 true 的语义，以及 is_in_breakable_cuda_graph() 的可用性，上游若调整 capture mode 判定会静默改变生效范围。平台风险：HIP（gfx942）与 DSA prefill CP 组合被显式排除，这两个组合的多流行为未被验证。测试风险：无直接单元测试覆盖该门控分支，仅依赖 DSV4 e2e 重跑；enable_multi_stream 位于每个 attention layer 每次 forward 的核心路径，误开会导致整链路行为变化。兼容性：SGLANG_OPT_USE_MULTI_STREAM_OVERLAP 默认开启，BCG prefill 用户升级后自动获得新行为，属于隐式行为变更。
- 影响：影响范围限定在 DSV4 + BCG prefill + 默认开启 SGLANG_OPT_USE_MULTI_STREAM_OVERLAP 的部署：TTFT 改善 0.95%-3.74%（ISL 256-8192），吞吐约 1%-2%，单 batch 1k1k prefill 从 0.0762s 降至 0.0713s。对用户是隐式性能提升，无需改配置；对团队而言，它把 multi-stream 重叠能力正式从 decode 扩展到 prefill，为后续 MQA q/kv-prep 多流上限等 prefill 优化扫清了门控障碍。H200 等非 HIP 平台理论上同样受惠，但 CUDA graph 捕获行为需在对应平台验证。
- 风险标记：核心路径变更 , 缺少直接测试覆盖 , 依赖上游语义变更 , 平台排除分支未验证

# 关联脉络

- PR #29866 get_is_capture_mode() returns true inside breakable CUDA graph contexts（讨论中引用，非当前历史列表内）: 该 PR 使 get_is_capture_mode() 在 breakable CUDA graph 上下文返回 true，直接取代了本 PR 初版的 model_capture_mode() wrapper，并已把 dual-stream MoE overlap 带入 BCG prefill；本 PR 最终实现建立在其语义之上。
- PR #33865 Fix DSpark + DeepSeek V4 prefill CP compatibility: 同一文件 deepseek_v4.py 的 prefill 路径修复，本 PR 门控中保留的 `dsa_enable_prefill_cp and dsa_use_prefill_cp(forward_batch)` 排除条件与它同属 DSV4 prefill CP 组合的正确性保障线。