PyTorch PT2 分诊规则详解：torch.compile 问题的组件隔离、标签决策与 Oncall 路由

本文基于 PyTorch 仓库内 PT2 oncall 分诊规范 pt2-triage-rubric.md，系统讲解 oncall: pt2 队列中 Issue 打标签的完整决策流程：如何区分 Dynamo 与 Dynamic Shapes、如何通过 aot_eager / Inductor 后端二分法定位正确性问题的归属组件、哪些情况必须避免给 module: pt2-dispatcher 过度打标，以及何时应重定向给 CPU Inductor 或 Distributed 等其他 oncall。读完本文，读者可以掌握一套可操作、可验证的 PT2 问题归类方法，并能结合仓库源码确认各组件的真实实现边界。

1. 背景：这份规则服务于什么流程

PyTorch 的 Issue 分诊（triage）在仓库中沉淀为一套 Agent 技能目录 .claude/skills/triaging-issues/，其结构为：

• SKILL.md：分诊主流程（0～7 步：跳过已路由 Issue、区分提问与 Bug、转交、重定向到二级 oncall、打模块标签、升级高优先级、自动 bot-triaged、标记 triaged）；
• pt2-triage-rubric.md：当 Issue 命中 oncall: pt2（即 torch.compile / PT2 栈）时的专项打标签细则，即本文主体；
• labels.json：允许自动打标签的白名单目录，标签必须在此文件中存在；
• templates.json：标准回复话术模板；
• scripts/：validate_labels.py（标签白名单校验）、validate_issue_target.py（阻止改错仓库/改错 Issue）、add_bot_triaged.py（变更完成后自动补 bot-triaged 标签）三个钩子脚本。

其中 SKILL.md 的 Step 2.5 明确规定了两条总纲，本规范的所有细则都是它们的展开：

1. oncall: pt2 不是"重定向"终点：与重定向到其他 oncall 后"停止一切后续操作"不同，PT2 的 Issue 要继续走完 Step 4–7 的完整分诊——打上 module: 标签、标记 triaged 等；
2. 每一个 oncall: pt2 的 Issue 必须至少有一个 module: 标签。PT2 的队列覆盖面太广，缺少模块标签 oncall 无法判断受影响的组件。若实在无法确定具体模块，兜底使用 module: compile ux，但应始终先尝试精确定位。

下面的每一节都对应原规范中的一个编号章节，并按"信号 → 标签 → 源码佐证"的方式展开。

2. 组件隔离：Dynamo 与 Dynamic Shapes 的精确区分

规范的第一条纪律是"Be Precise, Don't Over-Tag"，第一个典型易混淆点就是 Dynamo 与 Dynamic Shapes：

信号	应打的标签
dynamic=False 就能修复	仅 module: dynamic shapes
Graph break、字节码（bytecode）错误	module: dynamo
守卫（guard）失败、SymInt 问题	module: dynamic shapes
数据依赖操作（data-dependent，如 .item()）	module: dynamic shapes

规范特别强调：不要给每个 torch.compile 问题都随手贴 module: dynamo。

从源码结构看，这条区分是有实现依据的。Dynamo 本身负责 Python 字节码层的追踪与图划分，而符号化形状（SymInt、守卫）由独立的子系统处理，例如 torch/fx/experimental/symbolic_shapes.py 承载符号推理逻辑，Dynamo 的动态形状配置与测试也集中体现这一点（如 test/dynamo/test_dynamic_shapes.py、torch/_dynamo/ 下的 guards 相关代码）。因此"guard 失败、SymInt 推导错误"归 dynamic shapes，"字节码转换错误、图被错误切断"归 dynamo，二者在代码路径上是可分离的。

3. 后端二分法：正确性问题的归属定位

当 Issue 正文无法直接看出问题组件时，规范给出一个基于后端的二分定位法：

1. 先查评论——调试信息往往已经写在评论里；
2. 按后端复现结果打标签：

复现结果	标签
aot_eager 失败、eager 正常	module: pt2-dispatcher
inductor 失败、aot_eager 正常	module: inductor
在追踪（tracing）阶段就失败（还没到后端）	module: dynamo

这三个后端在仓库中都有真实实现可查：

• aot_eager 注册在 torch/_dynamo/backends/debugging.py：aot_eager 使用 AOT Autograd 搭配"nop compiler"（不生成代码、直接逐算子执行），文件注释明确写道 "aot_eager uses AOT Autograd backend with nop compiler. It is helpful in debugging"，并经 register_backend(name="aot_eager", ...) 注册。同文件还定义了 aot_eager_decomp_partition（L446-L480），其用途注释是 "just replaces the inductor compiler with nop to help isolate inductor vs aot_eager errors"——这正是后端二分法的官方工具；
• eager 即不启用 torch.compile 的原始路径；
• inductor 即默认的 torch/_inductor/ 代码生成器。

因此，aot_eager 失败而 eager 正常，说明问题出在 AOT autograd 这条"PT2 dispatcher"路径上；inductor 失败而 aot_eager 正常，说明 AOT autograd 产出的中间结果是正确的，锅在后端代码生成侧。

关键补充规则（原文加粗强调）：如果已确认是 Inductor 问题，且失败设备仅为 "cpu"，则这是 CPU Inductor 问题，必须重定向到 oncall: cpu inductor，而不是留在 oncall: pt2。

4. 静默丢弃的算子：一律归 Dynamo

规范给出了一个明确的归因判断：如果 torch.compile 静默丢弃或忽略了一个在 eager 下正常的操作，那么 Bug 在 Dynamo 的追踪（tracing）环节。

信号	标签
compile 下被跳过的原地修改（detach_()、requires_grad_()）	module: dynamo
副作用未被捕获（全局状态、tensor 元数据等）	module: dynamo

规范同时提醒：不要因为被丢弃的操作涉及 autograd 就顺手加 module: autograd——eager 下工作正常就说明 autograd 引擎本身没问题，问题出在"compile 时该操作没有被记录进图"。

5. 分解（Decomposition）类 Bug

如果某算子在 eager 与 traced 结果之间出现数值分歧，应怀疑是算子分解写错了：

信号	标签
某特定算子 eager 与 traced 结果不一致	module: decompositions
追踪下的高阶梯度（higher-order gradients）错误	module: decompositions
make_fx 符号化追踪与 eager 分歧	module: fx + module: decompositions + oncall: pt2

仓库中分解逻辑的主干位于 torch/_decomp/decompositions.py（另有 decompositions_for_jvp.py、decompositions_for_rng.py 等分支表），Inductor 与 AOT autograd 都会查询这些分解。因此"某个算子分解后与原实现数值不等价"是一个可以明确指向 module: decompositions 的独立故障域。

6. 不要过度打 module: pt2-dispatcher

module: pt2-dispatcher 只应表示 Bug 就在 dispatcher 代码内部，而不是"调用栈里出现过它"。

规范指出的最常见错误：在栈里看到 _aot_autograd/ 就认定是 pt2-dispatcher Bug。事实上 dispatcher 代码几乎在每条调用路径上，出现在栈上不代表 Bug 在那里。

应加 pt2-dispatcher 的情形：

• Bug 明确在 AOT autograd 逻辑中（例如 tensor 元数据处理错误）；
• Bug 在 functionalization（功能化变换）中；
• Bug 在 FakeTensor 实现中；
• Bug 在自定义算子注册/分派中。

不应加 pt2-dispatcher 的情形：

• 只是 AOT autograd 恰好出现在栈上；
• 真正的 Bug 在 functorch 变换中（应改用 module: functorch）；
• 真正的 Bug 在 inductor 代码生成中（应改用 module: inductor）；
• 你并不确定 Bug 到底在哪里。

这与 SKILL.md Step 1.6 中"按根因打标签、而非按错误信息中的关键词打标签"的总原则一致：栈帧和报错关键词只说明"哪里失败了"，不说明"为什么失败"。

7. PT2 拥有该代码时，不要重定向

这是规范中第二次用 "This is critical" 强调的章节。核心原则：

不要因为某子系统"牵涉"到 Bug 就重定向给它的 oncall。只有当 (1) Bug 明确在它自己的代码里，且 (2) PT2 代码没有责任时，才重定向。

不要重定向的例子：

情形	为什么不重定向
Export 触发了 Bug，但 Bug 本身是 AOT autograd 泄漏的 hook	Bug 在 PT2 代码里 → PT2 拥有
DTensor 在 compile 下报出糟糕的报错信息	Bug 在 PT2 的错误处理 → PT2 拥有 UX
分布式训练失败，但栈显示是 Inductor 问题	Bug 在 Inductor → PT2 拥有（Inductor 是 PT2 的组件）

对 PT2-D（PT2 与分布式交叉）问题，可以额外加 oncall: distributed 让分布式团队可见，但不要完全移交——保留 oncall: pt2 标签。

应该重定向的例子：

情形	为什么重定向
MKLDNN 专属的代码生成 Bug	oncall: cpu inductor 拥有 MKLDNN
与 compile 无关的纯 Export 问题	oncall: export 拥有
DTensor tensor subclass 实现内部的 Bug	oncall: distributed 拥有 DTensor 内部

规范给出的一条实用判据（"The test"）：问一句"修复需要改哪里？"如果修复落在 PT2 代码中，PT2 就拥有该 Issue。

另外两个补充要点：

• 为可见性加领域标签是可以的：例如加 module: dtensor 让领域专家看到 Issue，但除非真的移交，否则不要同时加 oncall: 重定向标签；
• 再次强调：确认为 Inductor 且仅 CPU 复现的问题 → 重定向 oncall: cpu inductor。

8. 领域标签与功能标签：完整清单

即便不重定向，也要加领域标签让专家可见：

领域	标签
DTensor	module: dtensor
FSDP	module: fsdp
DDP	module: ddp
Flex attention	module: flex attention

功能维度的标签（打标签前先查是否已有现成标签，不要自创类别）：

功能	标签
缓存问题	compile-cache
确定性（determinism）	module: determinism
编译/启动耗时	module: compile-time
数值问题	module: numerical-stability
UX / 报错信息	module: compile ux

规范最后的"快速标签参考"汇总了全部常用标签，分四类：

核心组件：

• module: dynamo — 追踪、字节码、graph break；
• module: inductor — 代码生成、Triton kernel；
• module: dynamic shapes — 符号化形状、守卫、数据依赖；
• module: pt2-dispatcher — AOT autograd、functionalization、FakeTensor；
• module: cuda graphs — CUDA graph 捕获/重放；
• module: flex attention — Flex attention API；
• module: helion — Helion DSL kernel 编写、编译及 Inductor 融合。

全局性领域：

• module: compile ux — 报错信息、API、编程模型；
• module: startup-compile-tracing time — 编译速度；
• module: performance — 运行时性能；
• module: memory usage — 内存问题。

状态标签：

• triaged — 分诊完成；
• triage review — 需上会讨论；
• needs reproduction — 被复现阻塞；
• needs research — 需要调研。

重定向标签：

• oncall: cpu inductor — CPU/MKLDNN 问题；
• oncall: export — Export 专属问题；
• oncall: distributed — 分布式训练问题。

注意：实际自动分诊时，所有标签都必须在 labels.json 白名单内，且 validate_labels.py 钩子还会额外禁掉 ci-*、sev*、merge blocking、actionable 等必须由人类决策的标签。

9. Helion Kernel 问题的识别与路由

Helion 是一个用 Python DSL 编写 GPU kernel 的项目：用户用 @helion.kernel 与 helion.language（如 hl.tile()）以标准 PyTorch 算子风格写 kernel，由 Helion 编译为 Triton；Helion kernel 还可通过 Inductor 的模板融合钩子（template fusion hooks）融合进 torch.compile 图。

识别信号：

信号	标签
Issue 提到 helion、@helion.kernel、helion.language、hl.tile	module: helion
报错回溯包含 helion/ 或 helion. 帧	module: helion
Helion kernel 单独运行（未过 torch.compile）结果错误	仅 module: helion
Helion kernel 在 torch.compile 下失败或被误编译	module: helion + module: inductor
由 Helion 模板触发的 Inductor 模板融合 Bug	module: helion + module: inductor

路由规则：

• Helion 问题归属 oncall: pt2——Helion 被视为 PT2 组件；
• Bug 纯在 Helion 自身编译（独立 kernel、未经 torch.compile）→ 只打 module: helion，不加 module: inductor；
• Bug 在 Inductor 如何融合/发射 Helion 模板 → 两个标签都加。

常见错误：

• 不要把 Helion 与裸 Triton 混淆：用户直接写 @triton.jit、tl.load 等而未用 Helion 时，那是 module: inductor，不是 module: helion；
• 不要给一般的 Inductor 代码生成 Bug 打 module: helion：Inductor 生成 Triton 代码不等于就是 Helion 问题，Helion 是特定 DSL，必须找到显式的 helion import 或提及。

10. functorch + compile 的交叉

情形	标签
编译一个 functorch 变换（vjp、grad、vmap）	module: functorch、dynamo-functorch
仅当栈里出现 AOT autograd 时才加 pt2-dispatcher	先检查栈再决定

functorch 变换的实现在 torch/_functorch/（如 vmap.py、functional.py 等），它与 Dynamo 的集成路径与 Inductor 不同，因此规范要求"先看栈再决定是否叠加 dispatcher 标签"，避免把变换层的 Bug 误归到 dispatcher。

11. 高优先级判定：不要直接加 high priority

规范第三次使用 "This is critical" 强调流程纪律：不应显式加 high priority，而应加 triage review，让下一次分诊会由 oncall 人工评审后决定。

命中任意一条即应标记 triage review：

判据	例子
Crash（segfault、非法内存访问）	设备端断言（device-side assert）、SIGSEGV
静默错误结果	输出与 eager 不同且无任何报错
回归（Regression）	"这个功能在版本 X 还能用"
不稳定测试（Flaky test）	通常意味着回归
重要模型性能回归（>10%）	常见模型出现显著变慢
重要用户/生态方	HuggingFace、常见使用模式

这与 SKILL.md Step 5a 的自动化约束互相印证：机器人只允许加 triage review 且此时不得加 triaged，high priority 必须经人工确认。

12. Fuzzer（模糊测试）问题的处理流程

对带 topic: fuzzer 的 Issue，规范要求五条处理步骤：

1. 确认 rtol/atol 处于默认容差；
2. 不要比较 max/min 的索引（索引对微小数值差异极度敏感，会引入容差问题）；
3. 数值对比使用 torch._dynamo.utils.same 并传入 fp64_ref 参数；
4. 若满足上述标准且 Bug 看起来常见/容易 → 按常规流程分诊；
5. 若问题复杂且罕见 → 加 low priority。

第 3 条在仓库中有直接源码印证：torch/_dynamo/utils.py 中的 same() 函数签名正是 same(ref, res, fp64_ref=None, ...)，文档字符串为 "Check correctness to see if ref and res match"。其容差逻辑基于 fp64_ref（当 fp64_ref is None 时退化为 ref）计算数值误差的容差倍数——即用 float64 参考值作为"真值"来放大/校准允许的误差，这正是处理 fuzzer 生成极端输入时"哪些差异是浮点噪声、哪些是真 Bug"的关键工具。fuzzer 复现代码的典型调用方式如 from torch._dynamo.utils import same，传入 eager 结果、traced 结果与 float64 参考结果进行三路对比。

13. CPU Inductor 路由细则

规范将 CPU Inductor 路由规则同时写进了第 2 节与快速参考章节，其判定条件为：当 Issue 明显属于 Inductor 的 CPU 后端专属问题时，路由到 oncall: cpu inductor（而不是泛化的 oncall: pt2）——

• 标题或正文提到 [CPU]、cpu 或 MKLDNN；
• CPU 专属代码生成 Bug（例如 CPU 上的 float16 处理）；
• 仅 CPU 复现、CUDA 上不复现的问题；
• MKLDNN 专属 kernel 问题。

规范给出的示例："[Inductor][CPU][float16] LayerNorm outputs NaN" → 应打 oncall: cpu inductor，而不是 oncall: pt2。

需要与 SKILL.md 中的一般性说明对照理解：在通用分诊入口，oncall: cpu inductor 被视为 PT2 的子队列，一般情况用 oncall: pt2 即可；但一旦按上述规则完成"CPU 专属"定位，就应该直接落到子队列，由 CPU Inductor oncall 接手。

14. 小结：一条 PT2 Issue 的完整打标签路径

综合全篇规范，一条 oncall: pt2 Issue 的标准处理路径可以归纳为：

1. 先精确定位组件（第 2 节）：Dynamo 字节码/图划分 vs 动态形状/守卫/SymInt，不要默认 module: dynamo；
2. 正确性问题做后端二分（第 3 节）：eager / aot_eager / inductor 三级复现，结果直接映射到 pt2-dispatcher、inductor、dynamo；
3. 核对特殊归因规则（第 4–7 节）：静默丢弃算子 → dynamo；算子数值分歧 → decompositions；栈上有 _aot_autograd/ 不代表 dispatcher 之罪；
4. 用"修复落在哪里"判据决定路由（第 7 节）：修复在 PT2 代码中则 PT2 全权拥有；CPU 专属 Inductor 问题转 oncall: cpu inductor；仅加领域 module: 标签提高可见性、不轻易加 oncall: 移交标签；
5. 补齐功能与状态标签（第 8、11、12 节）：缓存/确定性/编译耗时/数值/UX 等专用标签 + triage review（而非 high priority）+ fuzzer 问题的默认容差与 same(fp64_ref=...) 验证纪律；
6. 每个 PT2 Issue 最终必须落到至少一个 module: 标签，无法定位时兜底 module: compile ux。

这套规则的价值在于把"贴标签"从凭感觉变成了有信号、有判据、可复核的工程决策，且每一条判据都能在仓库源码（torch/_dynamo/backends/debugging.py 的调试后端、torch/_decomp/decompositions.py 的分解表、torch/_dynamo/utils.py 的 same() 校验工具等）中找到对应实现，从而保证 oncall 团队分诊结论与代码边界一致。