【合入来源】

https://gitcode.com/Ascend/pytorch/issues/1627
请勿携带内部流程信息（需求链接、问题单、内部issue等）

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

【修改方案】

本 PR 在 v2.7.1 分支的 docs/zh/native_apis/ 目录下，为 pytorch_2-7-1 / 2-9-0 / 2-10-0 / 2-11-0 / 2-12-0 五个版本的 torch-fx.md 补充 issue #1627 要求的 torch.fx.experimental.symbolic_shapes.ShapeEnv 及其各版本实际存在的方法在 Ascend NPU 上的支持度说明，与各版本测试 MR 的验证结论对齐。

合入目标分支：v2.7.1（MR 36144）

回应评审「其他版本为啥没有增加？」
Ascend 仓库在 v2.7.1 分支的 docs/zh/native_apis/ 中同时维护 PyTorch 2.7.1～2.12.0 多版本原生 API 表（分目录 pytorch_2-x-x/）。因此本 MR 在同一合入请求中更新 5 份 torch-fx.md，而非仅改 pytorch_2-7-1。这与「按版本拆测试 MR、按版本拆文档目录」的仓库惯例一致。

1. 上游社区与现有资料情况

资料/测试位置	覆盖侧重点	与本次修改的关系
PyTorch 上游 test/fx/test_symbolic_shapes.py	is_accessor_node、is_concrete_*、is_symbolic 等；文档层未声明 ShapeEnv 守卫类 API 的 NPU 支持度	Ascend 需在 torch-fx.md 中单独声明
test/fx/test_symbolic_shapes_api.py	DimConstraints、definitely_true 等其它 symbolic_shapes API	与 ShapeEnv 守卫类 API 不同类别，文档不混写
test/dynamo/test_export.py 等	导出路径间接使用 ShapeEnv	缺少公开方法的独立支持度表项
各版本 pytorch_2-x-x/torch-fx.md（upstream 基线）	已有 compute_unbacked_bindings、constrain_range、ConvertIntKey、CallMethodKey、canonicalize_bool_expr、check_consistent 等条目	仍缺少 ShapeEnv 及 5～6 个实例方法
测试 MR 36139～36204	各目标分支 TestShapeEnvNPU NPU 单测	本 PR 为测试结论提供文档依据，二者配套

结论：需在 5 个版本目录的 torch-fx.md 中声明 ShapeEnv 守卫类 API 的 NPU 支持情况；按 PyTorch 版本能力决定是否写入 add_backed_var_to_val；链接中 PyTorch 文档版本号与目录一致（2.7、2.9…2.12）。

2. 目标 API 功能说明（全称）

API 全称	功能简述	写入哪些版本 torch-fx.md
torch.fx.experimental.symbolic_shapes.ShapeEnv	符号形状环境，管理动态形状与守卫	2.7.1～2.12.0 全部
torch.fx.experimental.symbolic_shapes.ShapeEnv.produce_guards_expression	根据占位 FakeTensor 等输入，生成守卫表达式字符串	全部（支持）
torch.fx.experimental.symbolic_shapes.ShapeEnv.produce_guards_verbose	结合 Source 生成更详细的守卫信息	全部（不支持，与各版本测试 SKIP 一致）
torch.fx.experimental.symbolic_shapes.ShapeEnv.replace	在 ShapeEnv 符号表上下文中替换 sympy 表达式	全部（支持）
torch.fx.experimental.symbolic_shapes.ShapeEnv.set_unbacked_var_to_val	为 unbacked 符号绑定具体值	全部（支持；低版本测试可能 SKIP，文档仍标支持）
torch.fx.experimental.symbolic_shapes.ShapeEnv.simplify	在 ShapeEnv 环境下对 sympy 表达式做化简	全部（支持）
torch.fx.experimental.symbolic_shapes.ShapeEnv.add_backed_var_to_val	为 backed 符号绑定具体整型值（2.11.0+）	仅 pytorch_2-11-0、pytorch_2-12-0

未写入低版本文档的 API：

API	未写入目录	原因
ShapeEnv.add_backed_var_to_val	pytorch_2-7-1 / 2-9-0 / 2-10-0	PyTorch 2.11.0+ 才引入；v2.7.1～v2.10.0 无此方法，与对应测试 MR 故意不包含 一致

关于 add_backed_var_to_val（回应评审疑问）
该 API 来自 issue #1627，非其它 API 的前置条件。低版本文档/测试均故意不写入；2.11.0、2.12.0 文档已在本 MR 写入，与 MR 36203、MR 36204 对齐。

3. 资料修改思路

3.1 总体原则

1. 五份文档、同一 MR：在 v2.7.1 分支更新 pytorch_2-7-1～pytorch_2-12-0 共 5 个 torch-fx.md（回应「其他版本也需增加」）。
2. API 全称：表格「API名称」列使用 torch.fx.experimental.symbolic_shapes.ShapeEnv.* 完整限定名；链接指向对应 PyTorch 版本官方文档。
3. 与测试对齐：「是否支持」「限制与说明」与各版本 TestShapeEnvNPU 在 CI 上的 PASS/SKIP 结论一致。
4. 追加不替换：在 upstream 已有 symbolic_shapes 条目（至 check_consistent）之后追加 ShapeEnv 行；不删改、不重排无关 API 行。
5. 单 MR 多目录：v2.7.1 分支承载多版本文档树，不为 2.9.0～2.12.0 再开独立 docs MR（其它目标分支 upstream 通常无 native_apis 树）。

3.2 各版本文件与配套测试 MR

文档路径	追加行数	含 add_backed_var_to_val	PyTorch 文档链接版本	配套测试 MR
docs/zh/native_apis/pytorch_2-7-1/torch-fx.md	6	否	2.7	36139 → v2.7.1
docs/zh/native_apis/pytorch_2-9-0/torch-fx.md	6	否	2.9	36201 → v2.9.0
docs/zh/native_apis/pytorch_2-10-0/torch-fx.md	6	否	2.10	36202 → v2.10.0
docs/zh/native_apis/pytorch_2-11-0/torch-fx.md	7	是	2.11	36203 → v2.11.0
docs/zh/native_apis/pytorch_2-12-0/torch-fx.md	7	是	2.12	36204 → v2.12.0

3.3 与 upstream 合并及冲突处理

rebase 到最新 v2.7.1 时，各版本 torch-fx.md 末尾 upstream 已存在例如：

• compute_unbacked_bindings / constrain_range / constrain_unify
• ConvertIntKey / ConvertIntKey.get
• CallMethodKey / CallMethodKey.get
• canonicalize_bool_expr / check_consistent

本 PR 在 check_consistent 行之后追加 ShapeEnv 条目（仅追加、不删改 upstream 已有行）。

回应评审「你为啥要把文档中原来的内容删了？」
此前一次修复误用旧版文件整段覆盖最新 torch-fx.md，导致 upstream 已合入的 ShapeEnv.create_sym*node、Graph.find_nodes 等行在 diff 中显示为删除。已修正：rebase 至最新 v2.7.1（c7ae51d89），对 5 份文件纯追加 ShapeEnv 行；diff 为 +32 / -0（5 files changed, 32 insertions only）。commit 149825a5f。

3.4 分 API 文档标注（2.7.1～2.10.0 六行通用）

API 全称（简写）	是否支持	限制与说明	典型测试结论
ShapeEnv	是	-	测试环境基础
produce_guards_expression	是	支持fp32	PASS
produce_guards_verbose	否	-	SKIP（bare Source() 无法满足 name）
replace	是	-	PASS
set_unbacked_var_to_val	是	-	SKIP（non-nested SymInt 等上游限制，API 仍存在）
simplify	是	-	PASS

2.11.0 / 2.12.0 在上述 6 行基础上，在 replace 与 set_unbacked_var_to_val 之间（字母序）额外增加一行：

API	是否支持	限制与说明
add_backed_var_to_val	是	-

3.5 是否覆盖主要使用场景

使用场景	文档是否体现	说明
Dynamo / FX 导出中的守卫生成	produce_guards_expression / produce_guards_verbose	verbose 标「不支持」与 CI SKIP 一致
sympy 表达式改写与化简	replace / simplify	标「支持」
unbacked 符号绑定	set_unbacked_var_to_val	标「支持」；测试 SKIP 属上游限制
backed 符号绑定（2.11+）	add_backed_var_to_val	仅 2.11/2.12 文档写入

3.6 与测试 MR 的配套关系

类型	MR	变更
测试 v2.7.1	36139	test/fx/test_symbolic_shapes.py → TestShapeEnvNPU（5 API）
测试 v2.9.0	36201	同上（5 API）
测试 v2.10.0	36202	同上（5 API）
测试 v2.11.0	36203	同上（6 API，含 add_backed）
测试 v2.12.0	36204	同上（6 API）
文档（本 MR）	36144	5 份 torch-fx.md ShapeEnv 表项

测试与文档 API 列表、支持度标注 一一对应；低版本均不含 add_backed_var_to_val。

4. 变更范围

• 修改 5 个文件（仅资料，无业务代码/测试代码）：
  • docs/zh/native_apis/pytorch_2-7-1/torch-fx.md
  • docs/zh/native_apis/pytorch_2-9-0/torch-fx.md
  • docs/zh/native_apis/pytorch_2-10-0/torch-fx.md
  • docs/zh/native_apis/pytorch_2-11-0/torch-fx.md
  • docs/zh/native_apis/pytorch_2-12-0/torch-fx.md
• diff 统计：5 files changed，各文件在 check_consistent 后 +6 或 +7 行 ShapeEnv 条目
• 最新 commit：149825a5f（append-only，无删除行）

【资料变更】

涉及。 在 5 份 torch-fx.md 中补充 ShapeEnv 类及 5～6 个实例方法的支持度与限制说明，作为 issue #1627 在 Ascend 原生 API 文档侧的交付物。

【接口变更】

不涉及。未修改用户可见接口或跨仓接口行为。

【功能验证】

验证方式

1. 逐文件核对：5 份 torch-fx.md 均在 check_consistent 之后含 ShapeEnv 块；行数 6/6/6/7/7 正确。
2. 逐版本对照测试 MR：支持度与对应测试 MR 预期 PASS/SKIP 一致。
3. Diff 范围：仅上述 5 个 markdown，无测试/业务代码。
4. 合并状态：rebase 最新 v2.7.1，mergeable / 无冲突。

文档与测试对照表

v2.7.1（pytorch_2-7-1 + MR 36139）

API 全称	torch-fx.md	MR 36139 预期
ShapeEnv.produce_guards_expression	是	PASS
ShapeEnv.produce_guards_verbose	否	SKIP
ShapeEnv.replace	是	PASS
ShapeEnv.set_unbacked_var_to_val	是	SKIP
ShapeEnv.simplify	是	PASS
ShapeEnv.add_backed_var_to_val	未写入	不测

v2.9.0 / v2.10.0（pytorch_2-9-0 / 2-10-0 + MR 36201 / 36202）

与 v2.7.1 相同 6 行、相同支持度标注；不含 add_backed_var_to_val。测试预期均为 3 PASS + 2 SKIP。

v2.11.0 / v2.12.0（pytorch_2-11-0 / 2-12-0 + MR 36203 / 36204）

在 v2.7.1 六行基础上 +1 行 add_backed_var_to_val（是）。测试预期 3～4 PASS + 2～3 SKIP（视 wheel 是否导出 add_backed）。

自验证

• 本地/CI diff 仅 5 个 torch-fx.md；ShapeEnv 条目链接版本与目录一致。
• 已回应评审：五版本文档均已增加，非仅 2.7.1。
• 

【CheckList】

• 五版本 torch-fx.md 均已补充 ShapeEnv（回应「其他版本为啥没有增加」）
• 2.7.1～2.10.0 文档不含 add_backed_var_to_val；2.11.0/2.12.0 含
• API 使用全称，与各版本 TestShapeEnvNPU 范围一致
• 仅修改资料，未改动业务代码与测试
• PR 标题使用类型标签（如 docs:）
• PR 持续集成流水线（CI）执行通过