已关闭
[Usage]: API一致性说明：torch.fx.experimental.symbolic_shapes.DimConstraints.solve 与 torch.fx.experimental.symbolic_shapes.DimDynamic 在 NPU 环境无需额外适配 #2431
Goko创建于 6月18日关闭于 7月7日
6月18日 添加了label：usage
7月7日 issue状态由 TODO 改变为 DONE
7月7日 关闭了 issue
7月7日 添加了label：resolved
在提交新问题之前，请确保您已经在社区中搜索过相关问题，并使用了社区中提供的资源/工具后，仍未找到满意的解决方式。
环境信息
使用场景及问题
一、验证环境
公开任务：
本说明不包含内部需求链接、内部问题单或其他非公开流程信息。
二、本说明覆盖范围
本任务涉及以下 5 个 API：
其中，符合“PyTorch upstream 已有直接使用，且无需 NPU 专用用例适配 patch”的 API 为：
两者的最终处理方式不同：
DimConstraints.solve的 upstream 直接用例无需 NPU 迁移，不生成test_upstreampatch；为了在 Torch-NPU API 测试文件中形成聚焦、稳定的直接看护，本任务仍新增了轻量自写 UT。DimDynamic在 PyTorch upstream 和 Torch-NPU 现有测试中均已有直接覆盖，因此不生成test_upstreampatch，也不重复新增独立 UT。其余三个
DimConstraints方法在 upstream 中未发现目标方法的直接调用，已通过配套测试 PR 新增自写 UT，不属于本说明中的“无需新增用例适配”范围。三、API 功能说明
1. DimConstraints.solve
API：
功能：
DimConstraints.solve用于汇总已添加的符号等式、不等式、替换关系和 congruence 信息，执行符号约束求解，并将结论分类写入静态结果、动态结果、替换关系等内部集合。该方法主要处理：
它属于 FX / Dynamo symbolic shapes 的 Python 层编译前端逻辑，不直接执行 Tensor 数值计算，不调用 NPU 算子或 kernel，也不涉及 NPU 内存、stream、event 或通信逻辑。
各目标版本中的方法签名均为：
2. DimDynamic
API：
功能：
DimDynamic是 symbolic shapes 使用的枚举类型，用于描述符号维度采用的动态策略。当前验证环境中包含：这些枚举值供
StatelessSymbolicContext、StatefulSymbolicContext等符号上下文决定尺寸和步长的动态性。该 API 本身只提供 Python 枚举语义，不创建 Tensor，不执行设备计算，也不包含 NPU 专用逻辑。四、PyTorch upstream 源码存在性检查
使用 Gitee PyTorch 官方镜像，在以下版本中检查：
目标源码文件：
各版本均检索到：
源码位置复查结果：
因此，这两个 API 在任务覆盖的 PyTorch 官方版本中均为已有原生接口，不需要在 Torch-NPU 中新增同名实现。
五、PyTorch upstream 测试覆盖情况
1. DimConstraints.solve
对各版本官方测试执行直接调用检索：
grep -rn "dim_constraints\.solve()" test --include="*.py"各版本均在
test/test_dynamic_shapes.py中存在直接调用：已进一步查看 v2.7.1 对应调用上下文。该用例构造：
并断言：
对该上下文进行设备和 Tensor 创建关键字检查，未发现：
因此，upstream 中的
DimConstraints.solve直接调用不需要将 CPU Tensor 迁移到 NPU，也没有需要修改为 NPU 专用逻辑的代码。2. DimDynamic
对各版本官方测试执行直接使用检索：
grep -rn "DimDynamic\." test --include="*.py"直接命中数量：
相关使用分布在 dynamic shapes、Dynamo、export、symbolic context 等测试场景中。其核心行为是把
DimDynamic.DUCK、DimDynamic.INFER_STRIDE等枚举值传入符号上下文，用于描述尺寸和步长的动态策略。DimDynamic本身不是设备计算接口。其枚举值不会触发 CUDA/NPU Tensor 创建、设备迁移或数值计算，因此不存在将该枚举“适配到 NPU”的实现改写点。六、Torch-NPU 已有测试、patch 与资料复查
复查分支：
v2.8.0已结束维护，不纳入本任务。复查路径：
1. DimConstraints.solve
复查时各目标分支的有效命中计数为：
粗检索曾在
test/unsupported_test_cases/.pytorch-disabled-tests*.json中命中test_dim_constraints_solve_full，但该内容只是禁用记录，并非测试实现。最终复查已排除 disabled JSON，避免把测试名称误判为已有覆盖。因此：
DimConstraints.solvepatch 需要修改；test_upstreampatch；test/fx/test_symbolic_shapes_api.py中新增轻量自写测试。新增测试：
该方法还会在
forced_specializations和prettify_results测试中被调用，因此在四个新增测试中的实际调用次数为 3 次，覆盖动态约束结果与静态特化相关路径。2. DimDynamic
各目标分支复查结果：
具体
test命中计数：命中主要来自：
其中，
test/fx/test_symbolic_shapes_api.py已有以下直接测试：这些测试直接使用：
因此
DimDynamic已满足 Torch-NPU 侧基础直接看护需求。新增同类枚举测试只会重复已有覆盖，没有必要。七、API 源码设备依赖分析
1. DimConstraints.solve
solve的输入和内部状态由符号变量、SymPy 表达式、Source 元信息、替换关系及约束集合组成。其输出通过更新约束对象内部集合体现，不返回设备 Tensor。源码实现和直接测试上下文中均未发现：
因此该方法不需要 API 功能层面的 NPU 分支实现，也不需要 CPU/NPU 数值精度对比。
2. DimDynamic
DimDynamic是 PythonEnum。枚举成员本身不包含设备分发、Tensor 运算或 NPU 状态，不存在 kernel、精度、dtype、layout、stream 或内存相关适配逻辑。因此，该 API 不需要修改 Torch-NPU 产品源码。
八、当前环境最小行为验证
验证环境：
1. DimDynamic
执行枚举检查后得到：
说明当前 Torch-NPU 环境可以正常导入并枚举
DimDynamic。2. DimConstraints.solve
构造简单约束：
constraints.add(s0 >= 2) constraints.solve()求解后得到动态约束结果：
配套测试断言：
self.assertEqual(constraints._static_results, set()) self.assertEqual(constraints._dynamic_results, {"2 <= x"})说明当前 Torch-NPU 环境可以正常构造、调用
DimConstraints.solve，结果与 PyTorch 预期一致。九、NPU 适配判断
基于源码、upstream 测试、Torch-NPU 仓库和当前运行环境的多轮复查，判断如下。
1. DimConstraints.solve
dim_constraints.solve()直接调用；DimConstraints和 Source 元信息；test_upstreamNPU patch；2. DimDynamic
DimDynamic.*直接使用；DUCK和INFER_STRIDE；test_upstreampatch；十、其他三个 API 的处理边界
以下三个方法虽然同样不需要修改产品源码，但 upstream 未发现目标方法的直接调用，因此不能按“已有 upstream 用例，issue 说明即可”的路线处理：
本任务已在
test/fx/test_symbolic_shapes_api.py中分别新增直接测试：因此，本说明不会把这三个方法误写为“无需新增测试处理”。
十一、相关交付 PR
测试 PR：
资料 PR：
上述 6 个测试 PR 和 1 个资料 PR 的 CI 均已通过。
十二、处理结论
DimConstraints.solve
test_upstreampatch；DimDynamic
test_upstreampatch；综上，
DimConstraints.solve与DimDynamic均不需要 NPU 专用 API 实现或 upstream 用例 patch；其中solve已通过轻量自写 UT 补充聚焦看护，DimDynamic则直接复用现有测试覆盖。欢迎加入社区，感谢您对社区的贡献 🎉!