# PR #30586 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Move breakable CUDA graph back into model_executor/runner_backend_utils
- 合并时间：2026-07-09 14:19
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/30586

---

# 执行摘要

- 一句话：将 BCG 核心移回原模块并删除顶层包
- 推荐动作：对于关注模块组织和代码重构的读者值得精读，了解如何安全地回退一次不成熟的包提取。对于普通开发者，只需注意新导入路径即可。

# 功能与动机

Reverts the package relocation from sgl-project/sglang#27436, which hoisted the BCG core out to sglang.srt.breakable_cuda_graph. The full implementation now lives back at sglang.srt.model_executor.runner_backend_utils.breakable_cuda_graph and the top-level package is removed; all importers are repointed. 此次回退旨在简化模块结构，减少一个顶层包，降低维护复杂度。

# 实现拆解

1. **删除顶层包**：移除 `python/sglang/srt/breakable_cuda_graph/` 下的全部 4 个文件（`__init__.py`、`breakable_cuda_graph.py`、`context.py`、`cuda_utils.py`），共约 530 行。
2. **恢复子模块实现**：在 `python/sglang/srt/model_executor/runner_backend_utils/breakable_cuda_graph/` 中，将 `breakable_cuda_graph.py` 从 backwards-compatible re-export shim 改为完整的 BCG 实现（包含 `_check_cuda_bindings`、`get_current_stream`、`_capture_status`、`_is_stream_capturing`、`_hooked_wait_stream` 等），并从 `__all__` 中移除了 `get_current_replay_token`。
3. **增强上下文管理**：`context.py` 从 shim 改为真实实现，并在 `enable_breakable_cuda_graph` 中添加异常日志，输出 `BCG_FAILURE_HINT`。
4. **独立 replay_token**：在 `sglang/multimodal_gen/runtime/breakable_cuda_graph/replay_token.py` 新增 `get_current_replay_token` 和 `replay_token_scope`，使扩散运行时不再依赖 SRT 顶层包。
5. **扩散注意力层适配**：修改 `layer.py` 的导入路径，并新增 `_BCGBoxedTupleOutput` 类，用于包装注意力前向的元组输出，以兼容 BCG 的 `_copy_output`。

关键文件：
- `python/sglang/srt/model_executor/runner_backend_utils/breakable_cuda_graph/breakable_cuda_graph.py`（模块 BCG 核心；类别 source；类型 data-contract；符号 _check_cuda_bindings, get_current_stream, _capture_status, _is_stream_capturing）: 核心文件，从 shim 变为完整 BCG 实现
- `python/sglang/srt/breakable_cuda_graph/breakable_cuda_graph.py`（模块 BCG 核心；类别 source；类型 deletion；符号 _check_cuda_bindings, get_current_stream, get_current_replay_token, _capture_status）: 被删除的顶层 BCG 核心文件
- `python/sglang/srt/model_executor/runner_backend_utils/breakable_cuda_graph/context.py`（模块 BCG 上下文；类别 source；类型 data-contract；符号 is_in_breakable_cuda_graph, enable_breakable_cuda_graph）: 从 shim 改为真实实现，新增异常日志
- `python/sglang/multimodal_gen/runtime/layers/attention/layer.py`（模块 注意力层；类别 source；类型 core-logic；符号 _BCGBoxedTupleOutput, __init__, astuple, _forward_boxing_tuples）: 扩散注意力层导入路径调整和新增 _BCGBoxedTupleOutput
- `python/sglang/multimodal_gen/runtime/breakable_cuda_graph/replay_token.py`（模块 重放令牌；类别 source；类型 core-logic；符号 get_current_replay_token, replay_token_scope）: 新增 replay_token 模块，独立实现 get_current_replay_token

关键符号：_check_cuda_bindings, get_current_stream, _capture_status, _is_stream_capturing, _hooked_wait_stream, _install_wait_stream_hook, _uninstall_wait_stream_hook, is_in_breakable_cuda_graph, enable_breakable_cuda_graph, get_current_replay_token, _BCGBoxedTupleOutput, astuple, _forward_boxing_tuples

## 关键源码片段

### `python/sglang/srt/model_executor/runner_backend_utils/breakable_cuda_graph/breakable_cuda_graph.py`

核心文件，从 shim 变为完整 BCG 实现

```python
def _check_cuda_bindings():
    # 检查 cuda-python 包是否可用，不可用时抛出 ImportError
    if rt is None:
        raise ImportError(
            'Breakable CUDA graph on NVIDIA requires the cuda-python package. '
            'Install it with: pip install cuda-python'
        )


def get_current_stream(device: torch.device | None = None) -> torch.cuda.Stream:
    # 获取当前 BCG 捕获关联的流，否则返回设备当前流
    stream = _current_stream_var.get()
    if stream is None:
        return torch.cuda.current_stream(device)
    return stream

```

# 评论区精华

PR 无 review 评论，仅由维护者 BBuf 批准。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 1. 导入路径变更若遗漏某些引用点可能导致运行时 ImportError；但已通过全量搜索替换确保覆盖（涉及 11 个文件）。
 2. context.py 中的 enable_breakable_cuda_graph 新增了异常日志和不同的失败提示，可能改变异常处理语义（之前只是恢复全局变量，现在会记录日志并重新抛出），但整体风险较低。
 3. 移除了 get_current_replay_token 从 SRT 侧，扩散侧独立实现；若未来有代码通过 SRT 导入 get_current_replay_token 将无法找到，但已确认扩散侧是唯一使用者。
 4. 无测试配套修改，可能隐藏回归。
 - 影响：对用户无直接功能变化。对系统内部模块组织有正向影响：减少一个顶层包，降低 import 链长度，使 BCG 相关代码集中于 model_executor 子模块。对团队维护者：需要适应新的导入路径，但代码功能一致。
 - 风险标记：核心路径变更 , 导入路径重定向 , 缺少测试覆盖 , 异常处理语义变化

# 关联脉络

- PR #27436 [diffusion] Enable breakable CUDA graph (BCG) for diffusion DiTs: 本 PR 撤销了 #27436 的包重定位操作