任务 issue

https://gitcode.com/Ascend/pytorch/issues/1626

一、API 功能

API

torch.fx.experimental.symbolic_shapes.ShapeEnv.ignore_fresh_unbacked_symbols

功能

ShapeEnv.ignore_fresh_unbacked_symbols 是 PyTorch symbolic shapes 机制中 ShapeEnv 提供的上下文管理接口，用于临时控制 fresh unbacked symbols 的记录行为。

该 API 主要用于 FakeTensor、动态 shape、higher order operator schema 推导等场景，在上下文进入和退出时维护 ShapeEnv 内部 pending_fresh_unbacked_symbols 状态，保证 symbolic shape 状态管理逻辑正确。

核心特性

• 属于 PyTorch Python 层 symbolic shape 状态管理逻辑；
• 不涉及 Tensor 数值计算；
• 不涉及 NPU 算子、NPU 内存管理、stream、event 或通信逻辑；
• 不依赖底层硬件设备差异；
• 在 CPU/GPU/NPU 环境下 API 语义保持一致。

二、测试用例完备性（多版本）

PyTorch 官方源码中已存在该 API 的测试覆盖，按版本汇总如下：

v2.9.0 ~ v2.12.0 官方用例核心逻辑

from torch._subclasses.fake_tensor import FakeTensorMode
from torch.fx.experimental.symbolic_shapes import ShapeEnv

fake_mode = FakeTensorMode(shape_env=ShapeEnv())
with fake_mode, fake_mode.shape_env.ignore_fresh_unbacked_symbols():
    sym_bool = torch.randn(3, 4).nonzero().size(0) == 0

schema = torch.ops.higher_order.cond.gen_schema(
    sym_bool,
    lambda x: x.sin(),
    lambda x: x.cos(),
    (torch.randn(3, 4),),
)

该用例验证：

• FakeTensorMode 下可正常创建 ShapeEnv；
• ignore_fresh_unbacked_symbols 上下文可正常进入和退出；
• 上下文中构造的 SymBool 可被 higher_order.cond.gen_schema 正确识别；
• schema 生成结果符合预期。

因此，该官方用例已经完整覆盖了该 API 的核心行为。

v2.7.1 补充说明

v2.7.1 PyTorch 官方源码中该 API 已存在，但暂无独立官方测试用例。Torch-NPU v2.7.1 自写测试 PR 中包含 test_shape_env_ignore_fresh_unbacked_symbols 自写用例覆盖该 API 的基本行为，无需新增 upstream patch。

三、API 适配

3.1 API 适配

ShapeEnv.ignore_fresh_unbacked_symbols 属于纯框架层 symbolic shape 上下文管理逻辑，与 NPU 后端计算硬件完全解耦。

该 API 不涉及：

• NPU 后端算子实现；
• NPU kernel 调用；
• NPU 内存分配或释放；
• NPU stream / event 管理；
• 分布式通信逻辑；
• 设备侧数值计算结果。

因此无需对 API 做任何代码层面的修改。

3.2 测试用例适配

官方测试用例无需做任何代码修改，无需新增 NPU 特有逻辑，也无需新增 test_upstream patch。

原因如下：

• 测试目标是 FakeTensorMode、SymBool 和 cond.gen_schema 的框架层逻辑；
• ignore_fresh_unbacked_symbols 只影响 ShapeEnv 内部 symbolic state 管理；
• 用例不依赖 NPU 专有算子行为；
• 用例不验证 NPU 设备侧数值计算；
• 原始 PyTorch 用例已经完整覆盖 API 的核心语义。

因此，该 API 属于"PyTorch 有官方用例，NPU 适配不需要做任何修改"的情况。

四、验证结果

验证文件路径（按版本）

• v2.9.0：test/functorch/test_control_flow.py::test_cond_gen_schema_symbool_inputs
• v2.10.0：test/functorch/test_control_flow.py::test_cond_gen_schema_symbool_inputs
• v2.11.0：test/functorch/test_control_flow.py::test_cond_gen_schema_symbool_inputs、test/test_dynamic_shapes.py 相关用例
• v2.12.0 / master：test/test_dynamic_shapes.py、test/functorch/test_control_flow.py 相关用例

验证执行（v2.9.0 示例）

cd /workspace/user_data/pytorch_official_v2.9.0
python test/functorch/test_control_flow.py -k test_cond_gen_schema_symbool_inputs
python test/functorch/test_control_flow.py TestControlFlow.test_cond_gen_schema_symbool_inputs

执行结果

Traceback (most recent call last):
  File "/workspace/user_data/pytorch_official_v2.9.0/test/functorch/test_control_flow.py", line 6, in <module>
    import torch
  File "/workspace/user_data/pytorch_official_v2.9.0/torch/__init__.py", line 57, in <module>
    from torch.torch_version import __version__ as __version__
  File "/workspace/user_data/pytorch_official_v2.9.0/torch/torch_version.py", line 5, in <module>
    from torch.version import __version__ as internal_version
ModuleNotFoundError: No module named 'torch.version'

结果说明

当前 /workspace/user_data/pytorch_official_v2.X.Y 为 PyTorch 官方源码检索目录，并非已完成编译或安装的 PyTorch 运行环境，缺少构建过程中生成的 torch.version 文件，因此无法直接在该源码目录执行官方测试。

该错误发生在 import torch 阶段，尚未进入 test_cond_gen_schema_symbool_inputs 用例逻辑，不属于 API 功能错误，也不属于 NPU 适配问题。

本 issue 基于 PyTorch 多版本官方源码用例检索和 API 语义分析，确认该 API 官方已有用例且无需 NPU 侧代码适配。后续以社区审核和 CI 验证结果为准。

五、验证日志说明

如果执行过程中出现 schema、FakeTensor、symbolic shape 相关日志，但最终测试结果为 OK，则属于测试过程中的预期行为，不代表 NPU 适配问题。

该测试重点不是验证 NPU 数值计算，而是验证：

• ShapeEnv.ignore_fresh_unbacked_symbols 上下文管理逻辑；
• SymBool 构造；
• higher_order.cond.gen_schema 对 SymBool 输入的识别能力。

六、验证结论

torch.fx.experimental.symbolic_shapes.ShapeEnv.ignore_fresh_unbacked_symbols 在 PyTorch v2.9.0 / v2.10.0 / v2.11.0 / v2.12.0 / master 中均已有官方上游测试覆盖；v2.7.1 中该 API 已存在但官方无独立测试，由 Torch-NPU 自写测试覆盖。

该 API 属于设备无关的 symbolic shape 上下文管理接口，官方用例主要验证 FakeTensorMode 下 SymBool 构造与 higher_order.cond.gen_schema schema 推导逻辑，不涉及 NPU 后端特有行为。

因此，Torch-NPU 各版本 API 补齐阶段对该 API 无需新增 test_upstream patch，无需修改 API 实现，仅在本 issue 中统一说明 NPU 适配无需修改。

七、关联 PR

按导师"一个版本一个 PR"要求，已将各版本的自写测试 PR 与 upstream patch PR 合并为单 PR。当前活跃 PR 列表如下：

PR 内容统一说明：

• 自写测试文件 test/fx/test_symbolic_shapes.py 已按 Torch-NPU 测试规范重构：
  • 文件头加入英文 docstring；
  • 移除 unittest / torch_npu 导入与 @unittest.skipUnless 装饰器；
  • 使用 torch.accelerator.current_accelerator() 推导 device_type，张量统一通过 .to(device_type) 切到 NPU；
  • 全部断言使用 self.assert*，无 print / try / except；
  • 类前后空 2 行、方法前空 1 行，符合 PEP8。
• 自写测试覆盖 8 个用例，对应 API：is_accessor_node、is_concrete_int、is_concrete_float、is_concrete_bool、is_symbolic、ShapeEnv.get_pruned_guards、ShapeEnv.ignore_fresh_unbacked_symbols、ShapeEnv.is_unbacked_symint。
• 上游 patch（test_upstream/test/test_proxy_tensor.py.patch）在各 release 版本的官方 PyTorch 源码上 dry-run 通过，覆盖 ShapeEnv.produce_guards / ShapeEnv.get_nontrivial_guards。

旧 PR（已关闭，仅作历史追溯）：

• v2.7.1 旧自写测试 PR：#36447
• v2.7.1 旧 upstream patch PR：#36453（已合入 v2.7.1）
• v2.9.0 旧自写测试 PR：#36356
• v2.9.0 旧 upstream patch PR：#36369
• v2.10.0 旧自写测试 PR：#36393
• v2.10.0 旧 upstream patch PR：#36396
• v2.11.0 旧自写测试 PR：#36403
• v2.11.0 旧 upstream patch PR：#36418
• v2.12.0 旧自写测试 PR：#36434
• v2.12.0 旧 upstream patch PR：#36439