【合入来源】

【开源实习】Torch-NPU API一致性对齐：补齐测试用例、API功能对齐、补齐文档（2）

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

本 PR 覆盖以下 API：

• torch.fx._utils.lazy_format_graph_code

【修改方案】

一、API 功能说明

torch.fx._utils.lazy_format_graph_code 是 torch.fx 中用于延迟格式化 GraphModule 可读代码的 Python helper。

该 API 返回 torch._logging.LazyString，只有在日志系统或调用方真正需要字符串内容时，才调用内部格式化函数。字符串化时会调用 GraphModule.print_readable(print_output=False, **kwargs)，并将结果包装成包含 TRACED GRAPH 标识和标题的可读文本。

该 API 主要用于 FX pass 的日志输出，例如 split_module、runtime_assert、_tensorify_python_scalars 等路径。它不涉及 NPU 算子分派，也不修改 graph 语义。

二、用例完备性说明

经检索，PyTorch 社区测试中暂未发现直接覆盖 torch.fx._utils.lazy_format_graph_code 的专项测试。因此按任务要求在 Torch-NPU test 目录补充自写用例。

新增 TestFXNPU.test_lazy_format_graph_code，验证内容包括：

• 构造最小 torch.nn.Module 并通过 symbolic_trace 得到 GraphModule。
• 调用 lazy_format_graph_code("fx lazy graph", gm, maybe_id=1)。
• 对返回的 LazyString 执行字符串化。
• 断言输出包含 TRACED GRAPH。
• 断言标题包含 ===== fx lazy graph 1 =====。
• 断言输出包含 def forward，证明 GraphModule.print_readable 的结果进入最终格式化文本。

该测试是功能类 API 的最小核心验证，不依赖真实 NPU 张量，不绑定具体算子节点文本，也不覆盖颜色输出等非核心格式细节，避免测试过度约束输出实现。

三、NPU 适配说明

本次不修改 Torch-NPU 生产代码，仅新增测试用例。

lazy_format_graph_code 是 FX Python 层日志辅助函数，不涉及 NPU kernel、device dispatch 或 tensor 精度计算。NPU 适配目标是验证该 API 在 Torch-NPU 测试环境中可正常导入、调用和生成符合预期的 FX graph 可读输出。

为什么不需要修改 API：

• Torch-NPU 未覆写该 API。
• 该 API 行为由 PyTorch torch.fx._utils 提供。
• 当前验证中 API 可正常运行，输出包含预期 graph 标识、标题和 forward 代码。

【资料变更】

不涉及。本 API 的资料补齐由单独文档 PR 提交到 v2.7.1。

【接口变更】

不涉及。

【功能验证】

执行命令：

TORCH_DEVICE_BACKEND_AUTOLOAD=0 PYTHONPATH=<repo>/test python <repo>/test/test_fx.py TestFXNPU.test_lazy_format_graph_code

覆盖版本：

• master
• v2.7.1
• v2.8.0
• v2.9.0
• v2.10.0
• v2.11.0
• v2.12.0

执行结果：

----------------------------------------------------------------------
Ran 1 test in 0.009s

OK

额外检查：

python -m py_compile <repo>/test/test_fx.py
git diff --check

覆盖上述全部版本，结果均通过。

【CheckList】

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