【合入来源】

https://gitcode.com/Ascend/pytorch/issues/1856
https://gitcode.com/Ascend/pytorch/issues/2482

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

Fork: gcw_IDzXRVNw/pytorch_npu
分支: test/fx-graphmodule-api-v2.9.0 → Ascend/pytorch:v2.9.0
关联 Issue: https://gitcode.com/Ascend/pytorch/issues/1856

【修改方案】

本 PR 为用户提供的任务 issue #1856 的交付。社区用例情况：

• 已在 PyTorch 官方社区 pytorch/test/test_fx.py 下逐一搜索 GraphModule.code、GraphModule.graph 等 API，确认上游不存在针对这些属性的独立测试用例（仅作为辅助断言在其他测试中引用），因此自行编写测试用例。

一、API 功能说明

torch.fx.GraphModule 是 PyTorch FX 框架的核心输出类，将 fx.Graph 转化为可执行的 nn.Module，并通过 Python 代码生成实现 Python-to-Python 变换。本次验证的 10 个 API 均为纯 Python 图操作，与底层计算设备完全解耦：

• torch.fx.GraphModule：nn.Module 子类，持有 fx.Graph 并自动生成 Python forward 代码，是 FX Python-to-Python 变换的基础
• torch.fx.GraphModule.__init__：从 Module/dict 根对象和 Graph 构造 GraphModule，自动拷贝图中引用的属性和子模块
• torch.fx.GraphModule.add_submodule：在指定路径添加子模块，自动创建中间占位 Module
• torch.fx.GraphModule.code：只读 property，返回从 Graph 生成的 Python 源码字符串
• torch.fx.GraphModule.delete_all_unused_submodules：遍历 Graph 节点收集引用，删除未使用的子模块
• torch.fx.GraphModule.delete_submodule：删除指定路径的子模块，路径无效或为非 Module 时返回 False
• torch.fx.GraphModule.graph：property (getter/setter)，获取底层 Graph 或设置新 Graph（setter 自动触发 recompile）
• torch.fx.GraphModule.print_readable：生成可读的模块源码打印输出
• torch.fx.GraphModule.recompile：从 Graph 重新编译forward()方法，返回 PythonCode 对象
• torch.fx.GraphModule.to_folder：将模块导出到文件夹（含 module.py、state_dict.pt、init.py）

上述 API 的实现特征：全部定义在 torch.fx.graph_module.GraphModule 上，torch_npu 未做任何覆盖/重写。所有 API 操作对象为 Python 对象（Graph、Node、Module 层级、字符串），不涉及 Tensor 计算或硬件算子。

二、测试文件 test_fx_graph_module_api.py 用例完备性说明

【结论】所有用例覆盖 API 的基础功能、异常行为、接口存在性、以及 NPU 设备场景，34 个测试用例完整覆盖昇腾 NPU 适配所需的最小功能集。

三、昇腾 NPU 适配说明

本次 GraphModule 相关 API 在昇腾 NPU 上的验证采用如下方式，符合硬件适配要求：

• 所有 10 个 API 均为纯 Python 框架层图操作（操作 Graph/Node/Module 层级对象和字符串），与底层 CPU/GPU/NPU 计算硬件完全解耦，无需任何 NPU 特定代码适配
• 测试文件包含专用 TestFxGraphModuleOnNpu 类（3 个测试用例），显式将模块和张量迁移到 NPU 设备（npu:0），验证在真实 NPU 环境下 code、graph、recompile、forward 全部正常工作
• torch_npu 未对任何 GraphModule API 进行覆盖/重写，所有 API 行为与 PyTorch 上游完全一致

【结论】本测试文件的设计合理，可充分保证 GraphModule 在昇腾 NPU 环境下的功能正确性与可用性。

【资料变更】

文档变更已在 v2.7.1 分支的 PR 中合入，本 PR 仅提交测试文件。

【接口变更】

不涉及

【功能验证】

• 测试文件路径：test/fx/test_fx_graph_module_api.py
• 测试环境：torch 2.7.1+cpu + torch_npu 2.7.1.post4 + NPU 910B3 + CANN 8.5.0
• 本地验证结果（完整运行日志）：

root@hostname:/tmp# python test/fx/test_fx_graph_module_api.py -v
test_code_consistent_after_recompile ... ok
test_code_contains_forward ... ok
test_code_contains_op_names ... ok
test_code_returns_string ... ok
test_graph_getter_has_nodes ... ok
test_graph_getter_is_consistent ... ok
test_graph_getter_returns_graph ... ok
test_graph_setter_forward_works ... ok
test_graph_setter_preserves_lint ... ok
test_graph_setter_raises_on_non_graph ... ok
test_graph_setter_reassigns_graph ... ok
test_graph_setter_triggers_recompile ... ok
test_init_from_dict ... ok
test_init_from_module ... ok
test_init_raises_on_bad_type ... ok
test_init_sets_class_name ... ok
test_code_and_graph_on_npu ... ok
test_forward_on_npu ... ok
test_recompile_on_npu ... ok
test_print_readable_contains_child_code ... ok
test_print_readable_returns_string ... ok
test_recompile_preserves_forward ... ok
test_recompile_returns_python_code ... ok
test_add_submodule_nested ... ok
test_add_submodule_overwrite_fails_on_non_module ... ok
test_add_submodule_root_level ... ok
test_delete_all_unused_preserves_used ... ok
test_delete_all_unused_removes_orphans ... ok
test_delete_submodule_existing ... ok
test_delete_submodule_nested ... ok
test_delete_submodule_non_module ... ok
test_delete_submodule_nonexistent ... ok
test_to_folder_creates_files ... ok
test_to_folder_module_file_content ... ok

----------------------------------------------------------------------
Ran 34 tests in 2.316s
OK

【结论】执行测试用例后，34 passed，所有测试用例在 NPU 环境下执行通过。GraphModule 核心 API 在 NPU 上验证正确。

【CheckList】

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR 标题正确使用类型标签：test(fx)
• PR 持续集成流水线（CI）执行通过，代码检查无异常