【合入来源】

如有社区issue，请关联issue链接
请勿携带内部流程信息（需求链接、问题单、内部issue等）

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

关联issue：https://gitcode.com/Ascend/pytorch/issues/1625

【修改方案】

完善 Torch-NPU 对 torch.fx.experimental.symbolic_shapes.ShapeEnv 类 5 个 API 在 NPU 环境下的兼容性验证，覆盖以下 API：

1. 上游社区用例情况分析

在 PyTorch 上游仓库（github.com/pytorch/pytorch）中搜索这 5 个 API：

• format_guards：仅在 test/functorch/test_aotdispatch.py（第10150行）和 test/test_proxy_tensor.py（第1963行）中间接调用，无直接 API 验证用例
• freeze：上游 test/ 目录下无任何 ShapeEnv.freeze() 的直接调用
• freeze_runtime_asserts：上游 test/ 目录下无任何调用
• get_axioms：上游 test/ 目录下无任何直接调用（仅在 torch/_inductor/sizevars.py 等内部使用）
• get_implications：上游 test/ 目录下无任何直接调用（仅在 symbolic_shapes.py 内部被其他方法调用）

上游 test/fx/ 目录下不存在 test_symbolic_shapes.py 文件，该文件为 torch-npu 社区自建。

结论：5 个 API 均属于上游"无直接用例"场景，按 1.3 规范自写用例，提交到 torch-npu 的 test 目录。

2. NPU 适配方案

5 个 API 均为 ShapeEnv 类的纯 Python 方法，操作 sympy 符号表达式与内部状态，不涉及张量计算和 NPU 算子调用，在 NPU 上行为与 CPU 完全一致，无需做任何 NPU 适配修改。

3. 新增测试用例

在已有 test/fx/test_symbolic_shapes.py 的 TestShapeEnvNPU 类中追加 5 个测试方法：

4. API 补齐

不需要。5 个 API 均为纯 Python 方法，在 NPU 上运行结果与 CPU 完全一致。

5. 多版本分支合入

文档 PR：https://gitcode.com/Ascend/pytorch/pull/36879

【资料变更】

涉及。torch.fx.experimental.symbolic_shapes 下的 5 个 API 实际已支持，但 docs/zh/native_apis 中缺少对应文档。

v2.7.1 分支资料变更内容：

1. 新增 docs/zh/native_apis/pytorch_2-7-1/torch-fx-experimental-symbolic_shapes.md、pytorch_2-9-0/torch-fx-experimental-symbolic_shapes.md、pytorch_2-10-0/torch-fx-experimental-symbolic_shapes.md、pytorch_2-11-0/torch-fx-experimental-symbolic_shapes.md、pytorch_2-12-0/torch-fx-experimental-symbolic_shapes.md
2. 修改对应版本 PyTorch-*.md，添加子模块链接

API 支持情况：

资料 PR 仅合入 v2.7.1 分支，刷新 pytorch_2-7-1、pytorch_2-9-0、pytorch_2-10-0、pytorch_2-11-0、pytorch_2-12-0 五个版本的 API 支持情况。v2.9.0 及以后分支无 docs/zh/native_apis 目录，无需处理。

【接口变更】

不涉及（无新增/修改对外 C++ 或 Python 接口，仅新增测试与文档）

【功能验证】

1. 测试环境

• 设备：Ascend NPU
• 框架：对应分支 Torch-NPU + PyTorch
• 说明：5 个 API 为 ShapeEnv 类的纯 Python 方法，操作符号表达式与内部状态，不涉及张量计算，在 NPU 上行为与 CPU 完全一致

2. 测试命令

cd <pytorch-repo-root>
python test/fx/test_symbolic_shapes.py

3.测试结果

4.与上游用例的关系

【CheckList】

PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]

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