PyTorch PT2 编译器栈排错实战：Dynamo 图断裂、Inductor 崩溃与精度偏差的系统化调试方法

PyTorch 2 的编译器栈（Dynamo、Inductor、AOTAutograd、FX）把"写出能跑的模型"变成了"跑得快且结果对"的高难度问题：当 torch.compile 抛出 BackendCompilerFailed、日志里出现 graph break、或者编译后结果与 eager 模式对不上时，如何快速定位根因并修复？本文基于 PyTorch 仓库中 pt2-bug-basher 排错技能文档（.claude/skills/pt2-bug-basher/SKILL.md）整理，完整继承其"先建测试、再查日志、分类定界、Minifier 最小化"的调试方法论，并结合仓库源码逐一验证关键配置项、异常类与工具函数的实际实现，带你掌握一套可复制的 PT2 故障诊断与修复流程。

一、排错总流程：13 步工作流

原技能文档将 PT2 故障排查固化为一条 13 步流水线，核心思想是**"先有失败测试，再碰源码"**——在开始翻代码之前就锁定"修复完成的定义"。完整步骤如下：

1. 环境检查：确认 conda 环境已激活（检查 $CONDA_DEFAULT_ENV），并运行 python -c "import torch; print(torch.__version__)" 确认 torch 可导入。环境不对时先停下来。
2. 复现（Reproduce）：拿到一个可稳定复现的失败。
3. 最小化（Minimize）：剥离无关模型逻辑，使用最小张量形状，隔离触发 bug 的具体 op 或模式。
4. 先加单元测试：在深入代码搜索或根因分析之前，先向代码库添加一个能捕获该 bug 的失败测试。放在与主题匹配的测试文件中，例如 test/dynamo/test_repros.py、test/inductor/test_torchinductor.py、test/export/test_export.py。文档特别提示避免使用 test/dynamo/test_misc.py（该文件已经过大），应找更贴切的测试文件。统一使用 torch.testing._internal.common_utils.TestCase 和 run_tests。测试必须在修复前失败、修复后通过。
5. 在 main 分支验证：创建指向 main 的 worktree，把新测试拷进去跑一遍，确认它在 main 上确实失败。如果 main 上就通过，说明测试没抓住真正的 bug，或 bug 已被修复——停止排查，退出 worktree 回到工作分支。
6. 收集日志：用合适的 TORCH_LOGS 配置运行。
7. 分类：用下文"错误分诊"表格确定故障类别。
8. 检查产物：通过 TORCH_COMPILE_DEBUG=1 查看 FX 图、IR 与生成代码。
9. 定位根因：从报错沿编译管线反向追溯。
10. 修复。
11. 验证：跑新测试加上邻近的相关既有测试（例如改了 is_exporting 的语义，也要跑既有的 test_is_exporting 导出测试）；用 pytest -k 按名字快速筛选。全部通过才算完成。
12. 自审：用 /pr-review 技能审查自己的改动，修掉被标出的问题。
13. 总结：说明根因、改了什么、为什么改、加了哪些测试。

这条流程中"先测试后排查"是关键设计：文档原话是 "Having the test first keeps you grounded — you know exactly what 'fixed' looks like before you start exploring the codebase"（先有测试让你保持锚定——在开始探索代码库之前，你清楚地知道"修好了"长什么样）。

二、调查策略的三个基本原则

2.1 优先用直接工具，而不是搜索引擎式代理

文档建议直接用 Grep、Glob、Read 探索代码，不要启动 meta_codesearch 类代理——它们慢且贵；架构知识加上"关键源码文件"清单（见第五节）已经足够指导你去哪里找，一个定向的函数名 Grep 永远更快。

2.2 先弄清自己处在哪种编译模式

Dynamo、torch.export（strict）与 torch.export（non-strict，默认）三者共享代码但有关键分叉，读实现代码之前必须先判定模式：

模式	判定特征
torch.compile	Dynamo + Inductor；tx.export=False，无 _compiling_state_context()
torch.export（strict）	tx.export=True，_compiling_state_context() 处于激活状态
torch.export（non-strict，默认）	通过 fullgraph_capture 走 Dynamo，但 tx.export 可能与 strict 不同；_compiling_state_context() 激活。需检查 torch._export.config.use_new_tracer_experimental——它决定走哪条代码路径

其中 _compiling_state_context() 定义在 torch/_export/utils.py 中，fullgraph_capture 的入口在 torch/_dynamo/convert_frame.py，新导出追踪器 _dynamo_graph_capture_for_export 位于 torch/_dynamo/functional_export.py。

2.3 区分 trace-time 与 runtime

许多 PT2 bug 源于混淆这两个阶段：

• Trace-time（追踪期）：发生在 Dynamo 的符号化解释器内部。Dynamo 拦截函数调用并可能对其做常量折叠——例如 is_exporting() 在追踪期会被直接折叠为 ConstantVariable(True)。
• Runtime（运行期）：真实的张量、真实的 Python 调用，以及 torch.compiler._is_exporting_flag 这类模块级标志。

调试技巧：文档建议直接在源文件里加临时 print()，而不是从外部 monkey-patch——dispatch 链会让 monkey-patch 变得不可靠。

三、收集信息：按故障类别选诊断工具

目的	命令
快速概览	TORCH_LOGS="+dynamo,graph_breaks,recompiles" python your_script.py
完整调试产物	TORCH_COMPILE_DEBUG=1 python your_script.py（生成 torch_compile_debug/ 目录，含 FX 图、Inductor IR 与生成代码）
仅看生成代码	TORCH_LOGS="output_code" python your_script.py
结构化追踪	TORCH_TRACE=/path/to/trace python your_script.py，然后 tlparse /path/to/trace
单线程（配合 pdb）	TORCHINDUCTOR_COMPILE_THREADS=1 python your_script.py

这些日志别名并非凭空而来：在 torch/_logging/_registrations.py 中，guards、recompiles、recompiles_verbose、graph_breaks、output_code、schedule 等别名均已注册，可确认各别名确实由该文件统一管理。

关于 TORCHINDUCTOR_COMPILE_THREADS：从 torch/_inductor/config.py 中 decide_compile_threads() 的实现看，环境变量 TORCHINDUCTOR_COMPILE_THREADS 的优先级最高，其次是 win32 强制单线程，否则默认取 min(32, cpu_count)。设为 1 可以让编译过程变成单线程，从而稳定地进入 pdb。

四、错误分诊表：看异常定类别

根据报错信息与 traceback 先对故障分类，再进入对应小节：

错误特征	类别	跳转
日志中出现 Unsupported: ... 或 graph break	图断裂（Graph break）	4.1
BackendCompilerFailed	Inductor/后端崩溃	4.2
RecompileError 或 cache_size_limit	重复编译	4.3
精度不一致 / 数值结果错误	精度问题	4.4
InternalTorchDynamoError	Dynamo 自身 bug	4.5
Segfault 或 CUDA IMA	运行时崩溃	4.6
Triton 断言 / 索引越界	Triton 内核 bug	4.7

从源码结构看，这张表的可靠性是成立的：torch/_dynamo/exc.py 中确实定义了完整的异常层级，包括 InternalTorchDynamoError（L175）、BackendCompilerFailed（L283）、Unsupported（L301）、RecompileError（L339）——即分诊表中列出的每一种异常都对应真实的异常类。

4.1 图断裂（Graph Breaks）

图断裂会把编译后的图切成更小的子图，常常导致性能回退或行为异常。

诊断：

TORCH_LOGS="graph_breaks" python your_script.py

关键文件：

• torch/_dynamo/exc.py —— Unsupported 异常类
• torch/_dynamo/variables/ —— 大部分图断裂决策发生地

常见成因：不支持的 Python 结构（数据依赖的控制流、不支持的内建函数）；无法追踪的张量操作（对输入的 in-place 操作、不支持的 dtype）；调用不可追踪的函数。

修复思路：① 读图断裂信息，找出不支持的操作；② 查是否存在对应的分解（decomposition）或受支持的替代写法；③ 如果操作确实无法追踪，考虑 torch._dynamo.allow_in_graph 或重构用户代码。

4.2 后端编译器失败（Backend Compiler Failures）

BackendCompilerFailed 意味着 Inductor（或其他后端）在编译期间崩溃。

诊断——用 Minifier 隔离最小失败图：

TORCHDYNAMO_REPRO_AFTER=aot TORCHDYNAMO_REPRO_LEVEL=2 python your_script.py

该组合会生成 minifier_launcher.py，用于隔离最小失败图。

关键文件：

• torch/_dynamo/repro/after_aot.py —— AOT 之后失败的重现/最小化工具
• torch/_inductor/ —— 后端本体

修复思路：① 跑 minifier 得到最小复现；② 用 TORCH_COMPILE_DEBUG=1 检查 FX 图，弄清涉及哪些 op；③ 判断是 lowering 问题（torch/_inductor/lowering.py）、调度问题还是代码生成问题；④ 若错误在 codegen，直接看生成的输出代码。

4.3 重复编译问题（Recompilation）

守卫（guard）过于具体导致缓存未命中时，会发生过度重复编译。

诊断：

TORCH_LOGS="recompiles,recompiles_verbose,guards" python your_script.py

关键配置（均在 torch/_dynamo/config.py 中可验证）：

• torch._dynamo.config.recompile_limit，源码确认默认值为 8（config.py#L121）
• torch._dynamo.config.fail_on_recompile_limit_hit，默认为 False；置为 True 可在触达上限时抛出硬错误（config.py#L135）。另有一个 accumulated_recompile_limit 默认 256，用于累积重编译上限

常见成因：张量形状变化但未标记为 dynamic；Python 标量值在调用之间变化；调用之间存在全局状态变更。

修复思路：① 从日志读取重编译原因；② 找到失守的 guard；③ 用 torch._dynamo.mark_dynamic() 把相关维度标记为 dynamic，或修复 guard 不稳定的根源。

4.4 精度问题（Accuracy）

编译后模型产生与 eager 模式不同的数值结果。

诊断：

TORCHDYNAMO_REPRO_AFTER=aot TORCHDYNAMO_REPRO_LEVEL=4 python your_script.py

Level 4 会以 fp64 为参考对比 compiled 与 eager 的输出，精度失败时 dump 复现。

关键工具（在 torch/_dynamo/debug_utils.py 中均可确认）：

• same_two_models()（debug_utils.py#L631）—— 两模型输出一致性比较
• backend_accuracy_fails()（debug_utils.py#L739）—— 后端精度失败判定
• cast_to_fp64()（debug_utils.py#L733）—— fp64 参考转换
• torch._dynamo.config.repro_tolerance，默认 1e-3（config.py#L356）

修复思路：① 用 minifier 拿到最小失败图；② 在 fp64 精度下对比 eager 与 compiled 输出；③ 对 op 做二分查找，定位开始分叉的那个操作；④ 检查已知的数值问题（归约顺序、融合内核、dtype 提升）。

4.5 Dynamo 内部错误

InternalTorchDynamoError 指示 bug 在 Dynamo 本身。

诊断：

TORCHDYNAMO_VERBOSE=1 python your_script.py
# 或等价写法：
TORCH_LOGS="+dynamo" python your_script.py

关键文件：

• torch/_dynamo/symbolic_convert.py —— 字节码解释器
• torch/_dynamo/variables/ —— 变量追踪系统
• torch/_dynamo/guards.py —— guard 生成

修复思路：① 用 TORCHDYNAMO_VERBOSE=1 拿到完整堆栈；② 确定是哪条字节码指令或哪类变量导致崩溃；③ 建最小复现（错误信息中常常直接附带 minifier 路径）；④ 必要时用 TORCHINDUCTOR_COMPILE_THREADS=1 配合 pdb 调试。

4.6 运行时崩溃

Segfault 与 CUDA illegal memory access（IMA）发生在编译代码执行期间。

诊断——先让崩溃确定化：

PYTORCH_NO_CUDA_MEMORY_CACHING=1 CUDA_LAUNCH_BLOCKING=1 python your_script.py

CUDA IMA 加 NaN 检查：

TORCHINDUCTOR_NAN_ASSERTS=1 python your_script.py

Inductor 级别的同步调试：

torch._inductor.config.triton.debug_sync_kernel = True  # 每个 kernel 后同步
torch._inductor.config.triton.debug_sync_graph = True   # 图前后同步

以上三个开关在源码中都有对应实现：nan_asserts 由环境变量 TORCHINDUCTOR_NAN_ASSERTS 解析（torch/_inductor/config.py#L233），triton.debug_sync_graph 与 triton.debug_sync_kernel 默认均为 False（torch/_inductor/config.py#L2048-L2051）。

修复思路：① 用上面两个环境变量让崩溃确定化；② 检查是否输入不匹配（shapes、devices、dtypes）；③ 用 TORCH_LOGS="output_code" 检查生成的 kernel 代码；④ 用 TORCHINDUCTOR_NAN_ASSERTS=1 找到第一个产生坏值的 kernel；⑤ 检查 dynamic shapes 问题（历史上是 IMA 的常见来源）。

4.7 Triton 内核失败

Triton 断言失败或生成 kernel 中的索引越界。

诊断：

TORCH_LOGS="output_code,schedule" python your_script.py

关键文件：

• torch/_inductor/codegen/triton.py —— Triton 代码生成
• torch/_inductor/scheduler.py —— kernel 融合决策

修复思路：① 从 output_code 日志拿到生成的 Triton kernel；② 检查索引计算里的 off-by-one 或错误的 stride 推导；③ 用 TORCH_COMPILE_DEBUG=1 看 IR，回溯到对应的 FX op；④ 检查融合决策是否构造了非法的索引组合。

五、关键源码文件速查表

排错时按功能定位源码，以下为原技能文档给出的文件清单（均已与仓库实际结构核对）：

文件	用途
torch/_dynamo/exc.py	异常层级与错误格式化
torch/_dynamo/debug_utils.py	Minifier 支持、精度检查、输入序列化
torch/_dynamo/repro/after_dynamo.py	Dynamo 阶段失败的重现/最小化
torch/_dynamo/repro/after_aot.py	AOTAutograd 之后失败的重现/最小化
torch/_dynamo/repro/aoti.py	AOTI 失败的重现/最小化
torch/_dynamo/config.py	Dynamo 配置（repro 级别、重编译上限）
torch/_dynamo/variables/torch.py	Torch 函数处理、追踪状态函数
torch/_dynamo/variables/higher_order_ops.py	HOP 追踪（cond、map 等）
torch/_dynamo/symbolic_convert.py	字节码解释器、InstructionTranslator
torch/_dynamo/convert_frame.py	Frame 编译、fullgraph_capture 入口
torch/_dynamo/functional_export.py	新导出追踪器（_dynamo_graph_capture_for_export）
torch/_dynamo/eval_frame.py	torch._dynamo.export、optimize_assert
torch/_export/_trace.py	导出管线（_export、_strict_export、_non_strict_export、_export_to_aten_ir）
torch/_export/utils.py	_compiling_state_context()
torch/compiler/init.py	is_compiling()、is_exporting()、运行时标志
torch/_higher_order_ops/cond.py	torch.cond 实现与代理追踪
torch/_higher_order_ops/utils.py	HOP 分支追踪用的 reenter_make_fx
torch/_inductor/config.py	Inductor 配置（调试开关、trace 设置）
torch/_inductor/debug.py	DebugContext、图可视化、IR 日志
torch/_logging/_registrations.py	所有已注册的日志别名与 artifacts

六、Minifier 三步用法

Minifier 的作用是把失败图缩减到最小复现。完整三步：

# 第 1 步：生成 minifier 启动器
TORCHDYNAMO_REPRO_AFTER=aot TORCHDYNAMO_REPRO_LEVEL=2 python your_script.py

# 第 2 步：运行 minifier
python minifier_launcher.py minify

# 第 3 步：运行最小化后的复现
python minifier_launcher.py run

对于精度问题，改用 level 4：

TORCHDYNAMO_REPRO_AFTER=aot TORCHDYNAMO_REPRO_LEVEL=4 python your_script.py

从源码实现看，这套机制的行为与文档描述一致：torch/_dynamo/config.py#L332-L340 中 repro_after 直接解析环境变量 TORCHDYNAMO_REPRO_AFTER，repro_level 解析 TORCHDYNAMO_REPRO_LEVEL（默认值 2，精度场景升到 4）；而启动器文件由 torch/_dynamo/debug_utils.py 中的 get_minifier_repro_path() 写入 minifier_dir() 下的 minifier_launcher.py——即第一步命令结束后，工作目录里出现的 minifier_launcher.py 正是该函数写出的产物，随后用它执行 minify 与 run 子命令即可完成"缩小复现 → 运行复现"的闭环。

七、收尾自检清单

按这套方法论完成一次排错后，用下面四问自检：

1. 失败测试是否已在修复前失败、修复后通过，且邻近相关测试（pytest -k 筛选）全部通过？
2. 故障是否先经分诊表归类，并使用了与该类别匹配的诊断开关（graph_breaks / output_code / recompiles+guards / level 4 精度对比 / NAN_ASSERTS 等）？
3. 根因是否沿管线回溯到了具体环节（guard、lowering、scheduler、codegen 之一），而非停留在"改好了"？
4. 总结是否讲清了根因、改动内容与理由，可供他人复用？

掌握上述流程后，无论遇到 torch.compile 报错、BackendCompilerFailed 异常、重编译失控还是精度偏差，你都能按"环境 → 复现 → 最小化 → 测试 → 日志 → 分类 → 产物 → 根因 → 修复 → 验证"的路径稳定推进，而不必在庞大的编译器代码库中盲目摸索。