执行摘要

• 一句话：将 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 实现

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 的包重定位操作