Graph capture、replay 与执行证据#

这章解决什么问题#

上一章已经解释了 graph runner 和 backend 为什么会改变执行路径，但还有一层更容易被忽略的现实：一旦系统进入 graph capture / replay 语义，很多调试和性能分析的方法都会跟 eager 执行完全不同。如果不补这一层，execution model 仍然会更像实现概览，而不是可用于分析和定位问题的章节。

capture / replay 为什么不仅是性能优化#

从 cuda_graph_runner.py、cpu_graph_runner.py、piecewise_cuda_graph.md 等路径看，graph runner 不只是“让它跑快一点”的附加优化，而是会改变执行阶段的可见性、限制某些特性组合、并影响 trace / profile 的解释方式。这意味着一旦系统进入 capture / replay，读者就不能再用完全相同的眼光去看执行链。

这类差别对维护者尤其重要。因为很多性能分析、trace 阅读甚至“为什么某个路径现在看不见了”的问题，根本不是功能错了，而是运行时已经进入了另一套执行语义。

为什么 profiling 章节要和这里回扣#

如果你把 profiling 只放在最后的维护章节里，它很容易看起来像外部工具使用说明。但实际上，profiling 的很多解释前提就埋在 execution model 里：什么情况下是 eager、什么情况下是 cuda graph、什么情况下是 piecewise graph、哪些 marker 在 capture 下会消失、哪些 trace 会变得更难读。

因此，这一章的目的不是重复 profiling 指南，而是让 execution model 和 profiling 之间出现一个更自然的桥。优秀技术书会反复做这种桥接，因为它能让后面的工具章节不再像附录。

一个更贴近执行证据的图#

flowchart TD
    A["ForwardMode / batch state"] --> B{"runner 选择"}
    B --> C["eager path"]
    B --> D["cuda graph capture"]
    B --> E["piecewise replay"]
    C --> F["直接 forward 证据"]
    D --> G["capture / replay 证据"]
    E --> G
    F --> H["profile / trace 解读"]
    G --> H

这张图的重点，是把“执行路径”和“证据形态”放到一起。对读者来说，这比单独知道 CudaGraphRunner 存在更有价值，因为它回答了：为什么同一个功能在不同 runner 下，证据面会看起来不一样。

本章对应哪些代码路径#

这一章最重要的锚点包括 python/sglang/srt/model_executor/cuda_graph_runner.py、python/sglang/srt/model_executor/cpu_graph_runner.py、docs/advanced_features/piecewise_cuda_graph.md、docs/advanced_features/attention_backend.md 与 docs/developer_guide/benchmark_and_profiling.md。

小结#

执行模型一旦进入 graph capture / replay 语义，系统就不再只是“怎么跑”，还变成“怎样留下正确证据”。把这层补进来之后，execution model 和 profiling / debug 章节之间的桥就更稳了。