test_torchinductor.py 硬件解耦改造方案（讨论稿）

1. 背景与目标

目标文件为 test/inductor/test_torchinductor.py。本轮硬件解耦希望：

1. 解除普通 accelerator 用例中的 "cuda"/"xpu" 等设备硬编码，使注册完成的 PrivateUse1 后端更容易进入测试矩阵。
2. 按证明目标将运行时测试类分为 GENERIC、ACCELERATOR、CPU、CUDA、MPS、XPU 等，通过 HardwareClassification 选择运行。
3. 将 Triton、Flash Attention 等细粒度能力差异交给 capability provider 和 preflight，不为 PrivateUse1 维护用例名白名单。

本文只记录方案讨论，不替代基于最新 upstream 重新生成的逐方法分析报告。

1.1 硬前提：保持外部协议

本次改造不能影响依赖方继续使用 test_torchinductor.py。以下接口与行为必须保持兼容：

• CommonTemplate、CpuTests、GPUTests、copy_tests 以及各类辅助函数和 TestFailure 的导入方式；
• copy_tests 的调用签名、默认复制规则、测试名后缀、skip/xfail/expected-failure 元数据传播方式；
• 外部文件直接实例化、继承或转换 CommonTemplate、CpuTests、GPUTests 的现有用法；
• 外部消费者最终发现的测试集合、test ID 和运行语义。

如果一个方案必须同步迁移所有外部依赖方，或者只能通过改变上述协议才能落地，它就不属于本次改造范围。

2. 文件原本的作用

test_torchinductor.py 是 Inductor 核心测试语料库和生成入口，不是普通的“一个源类对应一个运行类”文件。它主要验证：

• 同一 eager 计算经 Inductor 编译后的数值、dtype、stride、gradient 和 codegen 行为；
• CPU 与 GPU/accelerator 执行策略下的公共测试体复用；
• dynamic shapes、wrapper、subprocess、Graph Pickler、Triton CPU、Pallas/Halide 等整套测试派生。

3. 当前架构

3.1 CommonTemplate

CommonTemplate 不继承 TestCase，本身不是 unittest 运行类。它是可复用的测试体模板：

• 测试方法通过 self.device 获取目标设备；
• 通过 self.common 获取编译/对比策略；
• instantiate_parametrized_tests 先展开 dtype、shape 和配置参数；
• 外部文件可先转换这个模板，再生成自己的测试类。

3.2 copy_tests

copy_tests 将模板方法物化到 CpuTests、GPUTests 或外部派生类中，并：

• 为每个目标创建独立函数对象，避免 unittest skip 相互污染；
• 深拷贝参数化、skip、xfail、expected-failure 等元数据；
• 追加 _cpu/_cuda/_xpu 等 suffix，形成稳定的运行时 test ID。

3.3 当前扩展性的边界

当前架构已支持“外部后端手工定义类并复用模板”，但不等于“注册 DeviceTypeTestBase 后自然进入矩阵”：

• GPU_TYPE 只在 CUDA、MPS、XPU、MTIA 中选择；
• RUN_GPU/HAS_GPU 不会因普通 PrivateUse1 注册而自然成立；
• check_model_gpu 使用全局 GPU_TYPE，而非实际注入的 device；
• GPUTests 同时含有普通 accelerator 与 CUDA/Triton 专属语义，无法添加唯一正确的类级标签。

4. 为什么不能像普通测试类一样改

1. 一个 CommonTemplate 源方法可生成 CPU 和 ACCELERATOR 多个运行目标，源模板没有单一 HardwareClassification。
2. HardwareClassification 只作用于实际 unittest 类，不支持在混合类中按方法过滤。
3. CommonTemplate 已经做参数化展开，不能对同一类再叠加 instantiate_device_type_tests。
4. 重命名类、改变 suffix 或复制时机会影响多个外部派生文件、slow-test 配置和 expected-failure 索引。
5. Triton、cudagraph、CUDA profiler/allocator/ISA、benchmark、Pallas/Halide 等例外不能被机械泛化。

5. 方案评估

已否决方案 A：整体迁移到标准 device-type 测试架构

将所有模板方法按 GENERIC/CPU/ACCELERATOR/CUDA 拆分，并改用 instantiate_device_type_tests。

这个方向在抽象上最接近普通测试文件，但不满足本次“保持外部协议”的硬前提：

• CommonTemplate 不再是原来的完整模板集合，外部转换逻辑获得的方法集会变化；
• copy_tests 的复制协议会被标准展开机制取代或绕过，依赖其命名、过滤和元数据传播的调用方会受到影响；
• CpuTests、GPUTests 的生成方式、类结构和 test ID 可能变化，直接实例化它们的外部用法不再等价；
• 为旧名称增加兼容别名也不能可靠解决问题：别名可能造成 unittest 重复发现，而拆分后的 ACCELERATOR 与 CUDA 语义也无法无损地重新合成为原来的 GPUTests。

因此方案 A 不是本次可选实施方案。只有未来明确允许同步迁移全部消费者、接受对外协议变化并进行独立架构重构时，才值得重新评估。

方案 B：分类感知的物化层

“物化”是指把模板测试转换成 unittest 可以执行的具体测试。当前 copy_tests 已经承担这个职责：

CommonTemplate -> 参数化展开 -> copy_tests -> CpuTests / GPUTests

方案 B 是让 copy_tests 根据测试分类，把方法分别复制到 CPU、ACCELERATOR、CUDA 等运行类，再给这些类添加对应标签。capability 仍只负责运行前的能力检查，不参与分类。

这个方案的问题在于 GPUTests 同时包含通用 accelerator 和 CUDA/Triton 专属测试：

• 不拆 GPUTests，就无法添加唯一正确的类级标签；
• 拆分或改造 GPUTests，会改变外部直接实例化、继承和转换它的行为；
• 同时保留旧类和新分类类，会造成测试重复 discovery。

因此，方案 B 只能做不参与 discovery 的“影子物化”，用于生成分类映射和比较 test ID；它不能作为正式改造方案。正式物化只有在能够证明 GPUTests 外部行为完全不变且不会重复 discovery 时，才可重新考虑。

方案 C：保留当前文件，由外部后端适配器调用

PrivateUse1 后端自行定义 TestCase、device、runner 和用例过滤，继续调用 copy_tests。

• 优点：上游改动最小，现有 CPU/CUDA/XPU/MPS 行为风险低。
• 缺点：每个树外后端需维护用例名白名单和能力差异，上游新增/重命名方法容易漂移，不能达到“注册后自然进入矩阵”的长期目标。
• 当前结论：可作为短期方案，或在标准迁移风险过高时作为专项例外。

方案 D：有限解耦，保留生成框架为专项例外

只处理能局部证明安全的具体 CPU 类、独立类标签和明确设备硬编码；CommonTemplate/copy_tests/RUN_GPU/GPU_TYPE 在本轮保留。

• 优点：风险最低，符合 skill 对动态生成和例外的停止规则。
• 缺点：无法完成整个文件的 PrivateUse1 自动准入。
• 当前结论：可用影子物化建立证据；正式修改采用此方案，不强行修改生成架构。

6. 当前推荐的实施方式

方案 A 和正式物化方案 B 均不满足当前兼容前提。当前建议用影子物化建立证据，并以方案 D 作为正式代码修改边界：

1. 在与最新源码匹配的环境中保存当前文件和所有直接消费者的完整 discovery manifest。
2. 在 agent_space 建立不参与 unittest discovery 的影子物化工具，比较分类映射、test ID 和元数据。
3. 正式代码只修改能局部证明安全的独立测试类、标签和设备硬编码。
4. 保留 CommonTemplate/copy_tests/GPUTests 生成链作为专项例外；capability 也不能用来掩盖这个混合类问题。

7. 主要风险

1. 用例静默丢失或重复：源方法数和生成总数相等也不能证明 test ID 集合等价。
2. 元数据丢失：参数化、skip、xfail、expected-failure 可在多层 wrapper/深拷贝后改变。
3. 类别污染：普通 accelerator 和 CUDA/Triton 专属语义留在同一运行类时，任何单一标签都不正确。
4. 设备和名称不一致：GPU_TYPE 同时控制 runner、设备和 suffix，机械替换可导致运行设备与 test ID 不一致。
5. 外部接口破坏：dynamic shapes、C++ wrapper、Halide、Pallas、Graph Pickler 等测试依赖这里的公共 import、类和 helper；接口迁移会直接破坏调用方，而兼容别名还可能造成重复 discovery。
6. 能力查询时序：capability 在 import/discovery 阶段查询可能早于树外后端注册并缓存错误结果。
7. 验证环境不完整：当前本地 venv 对应旧源码，NPU 容器又缺少完整目标文件；源码/可编辑 PyTorch/后端不匹配时不能作等价性结论。
8. 影子结果被误作正式实现：影子物化只能分析生成差异，不能给正式测试类添加标签，也不能自动解决 PrivateUse1 准入。

8. 行为一致性门禁

每个阶段必须满足：

• 新旧完整 test ID 集合差分中，只包含分析报告批准的变化；
• 每个源方法到目标方法的映射闭合，无丢失、无重复；
• 参数笛卡尔积和逐变体 decorator 等价；
• 公共 import 和直接消费者 discovery 无未解释变化；
• CommonTemplate、copy_tests、CpuTests、GPUTests、辅助函数和 TestFailure 的现有外部调用方式保持可用；
• 例外测试保持原测试体、gate 和证明目标；
• 每次代码修改后重跑全 PR 类身份审计；
• 生成链修改按三级实机风险执行 CPU 控制组、NPU 和所有直接消费者验证。

任一门禁无法闭合时，停止该阶段，不继续叠加后续分类、矩阵扩展或 capability 修改。

9. 当前结论

CommonTemplate/copy_tests 是有意设计的 Inductor 测试生成架构，其中 copy_tests 已经承担物化职责。方案 A 和正式物化方案 B 都会改变运行类或外部协议，当前均不实施。影子物化只用于分析；正式修改采用方案 D 的边界，必要时由方案 C 提供短期外部适配。