执行摘要
本PR引入了Breakable CUDA Graph机制，通过在CUDA图捕获中插入断点，解决了标准CUDA图调试困难和操作不兼容的问题。提供了调试模式（--debug-cuda-graph）和选择性断点装饰器（@eager_on_graph），在保持性能优势的同时增强可调试性和兼容性。该变更影响CUDA图核心路径，建议团队关注其设计决策和潜在风险。
功能与动机
为什么做？ 标准CUDA图捕获整个前向传播为单一不透明图，导致两大问题：1) 调试困难——当图内出错时，无法单步或插入打印语句；2) 操作不兼容——某些动态操作（如主机-设备同步）无法被捕获，传统方案需完全禁用CUDA图，牺牲性能。Breakable CUDA Graph旨在通过插入图断点，将计算分割为多个捕获段，允许特定操作以非图方式运行，从而兼顾性能与灵活性。
实现拆解
实现分为五个关键部分：
- 核心模块：新增
breakable_cuda_graph.py，提供 eager_on_graph 装饰器标记非图操作，BreakableCUDAGraphCapture 上下文管理器管理捕获段。
- 集成点：修改
cuda_graph_runner.py 的 _capture_graph 方法，根据环境变量 SGLANG_USE_BREAKABLE_CUDA_GRAPH 或 --debug-cuda-graph 选择上下文管理器，代码片段如下：
python
if envs.SGLANG_USE_BREAKABLE_CUDA_GRAPH.get():
graph_ctx = BreakableCUDAGraphCapture
else:
graph_ctx = self.device_module.graph
- 命令行参数：在
server_args.py 中添加 --debug-cuda-graph 参数，启用时设置环境变量并输出警告日志。
- 文档：新增
breakable_cuda_graph.md，详细说明动机、用法和示例命令。
- 测试：添加
test_breakable_cuda_graph.py，验证无断点、单断点和多断点场景的捕获回放正确性。
评论区精华
review讨论聚焦于三个关键点：
- ROCm兼容性：BBuf指出
--debug-cuda-graph 在ROCm平台可能失败，因为 BreakableCUDAGraph 只在非HIP构建中导入，建议守卫路径。
- 结构化输出回写：BBuf强调调试模式下结构化输出（如
LogitsProcessorOutput）可能未正确回写，导致输出过时；最终提交通过修复 _copy_output 处理解决了此问题。
- 设计细节：ch-wan建议添加try-except并询问debug模式是否应用于piecewise cuda graph，表明集成需考虑现有特性。
风险与影响
风险：
- ROCm兼容性：
cuda_graph_runner.py 中缺少完整守卫，ROCm启用debug模式可能引发NameError。
- 性能开销：过度使用图断点会削弱CUDA图性能收益，需谨慎设计断点位置。
- 复杂性：新增机制增加了CUDA图逻辑复杂度，可能引入回归bug，尤其在结构化输出处理中。
影响：
- 用户：获得强大调试工具，提升开发效率；生产环境可通过选择性断点兼容不兼容操作。
- 系统：调试模式下性能下降，但选择性使用时开销最小；增强CUDA图灵活性和可靠性。
- 团队：需维护新模块并确保测试覆盖，但为后续CUDA图优化提供基础。
关联脉络
从近期历史PR看，#22404 修复了CUDA图捕获逻辑，确保捕获与重放一致，与本PR的调试机制形成互补，共同提升CUDA图系统的健壮性。此外，本PR与AMD平台优化（如 #22228）无直接关联，但体现了框架在多平台下的调试能力增强趋势。整体上，sglang仓库正持续改进CUDA图相关特性，以平衡性能、兼容性和可维护性。
参与讨论