已开启

8月社区任务第三期-Ascend for PyTorch API 一致性开发（19、22） #4603

nasa___1创建于 9月4日

9月4日创建

【合入来源】

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

需求
问题单
issue/工单 https://gitcode.com/Ascend/pytorch-ecosystem/issues/245 https://gitcode.com/Ascend/pytorch-ecosystem/issues/249
重构优化
资料更新

1、API功能分析

torch.autograd.forward_ad.enter_dual_level

该函数用于开启一个新的前向模式自动微分（Forward-mode AD）计算层级（Dual Level），并返回该层级的唯一整数标识符（level）。在完成相应的前向计算后，必须显式调用对应的 exit_dual_level 关闭该层级以释放相关计算上下文。

torch.autograd.forward_ad.unpack_dual

该函数用于从一个 Dual Tensor 中解包出其原始值（primal）与指定层级下的前向切向量（tangent/derivative），并以具名元组（DualLevel(primal, tangent)）的形式返回。

因此这两个API会涉及到torch-npu算子实现，因此需要在torch-npu平台上补充这两个API的测试用例。

2、上游用例检查情况

API	上游测试情况	主要测试位置	结论
`torch.autograd.forward_ad.enter_dual_level`	有直接测试，但数量较少；同时被 `dual_level()` 大量间接调用	`test/test_autograd.py` → `TestAutogradForwardMode`	有覆盖，偏生命周期/异常场景
`torch.autograd.forward_ad.unpack_dual`	有大量直接测试	`test/test_autograd.py` → `TestAutogradForwardMode`、`TestAutogradForwardModeBatchedGrad`	覆盖较充分

API	上游已有测试	是否涉及 NPU Tensor	torch-npu 是否建议补测	优先级
`forward_ad.enter_dual_level`	是	间接涉及	建议补	中
`forward_ad.unpack_dual`	是	直接涉及	建议补	高

3. 资料检查

torch.autograd.forward_ad.enter_dual_level

这个API在官方都有独立条目，但是当前资料补充缺失，因此需要进行资料补充。

torch.autograd.forward_ad.unpack_dual

这个API在官方有独立条目，而且当前资料补充已经覆盖：

4. API功能测试

用例覆盖场景：

用例覆盖场景

测试项	覆盖内容	预期结果
enter_dual_level层级创建	直接调用`enter_dual_level()`创建前向AD层级	返回有效的整数level
显式level参数	使用返回的level调用`make_dual`和`unpack_dual`	成功创建和解析NPU dual tensor
NPU设备保持	检查解析出的primal和tangent所在设备	primal和tangent均位于NPU设备
level退出与清理	调用`exit_dual_level`后重新解析原dual tensor	tangent被清除并返回`None`
unpack_dual前向梯度解析	对NPU dual tensor计算`x * x`并解析结果	primal等于`x²`，tangent等于`2xx_tangent`
CPU/NPU结果一致性	使用CPU计算预期primal和tangent，与NPU结果比较	CPU与NPU计算结果一致
数据类型覆盖	分别使用`float16`和`float32`创建NPU dual tensor	两种数据类型均能正确解析，且dtype保持不变
普通NPU张量解析	对非dual NPU tensor调用`unpack_dual`	primal等于原始输入，tangent为`None`

测试方法

source /usr/local/Ascend/ascend-toolkit/set_env.sh
TORCH_DEVICE_BACKEND_AUTOLOAD=1 python test_forward_ad_enter_dual_level_unpack_dual.py -v

测试结果

A2/A3芯片：

v2.7.1

v.2.11.0

v2.12.0

A5芯片

v2.7.1

v2.11.0

v2.12.0

【CheckList】

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

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

N nasa___1

9月4日修改标题为 “8月社区任务第三期-Ascend for PyTorch API 一致性开发（19、22）”，原标题为“8月社区任务第三期-Ascend for PyTorch API 一致性开发（22、19）”

TorchNPU-Bot成员

9月4日添加了label：triage-review

TorchNPU-Bot成员

9月4日评论：

issue待分派，添加triage-review标签

N nasa___1

9月4日修改了issue 的描述

N nasa___1

9月4日修改了issue 的描述

群

群青世界成员

28 天前评论：

社区任务交付件初审结论：✔

1. 现状分析

涉及 API：torch.autograd.forward_ad.enter_dual_level、torch.autograd.forward_ad.unpack_dual
核心功能：管理 forward AD 层级并解析 dual Tensor 的 primal 与 tangent。
用例完整性：官方测试覆盖 enter_dual_level 生命周期和 unpack_dual 多种 forward-mode 场景，NPU Tensor 组合需要适配验证。
任务规范：1.1①。

2. 适配方案

API适配：无需适配，API已支持。
用例适配：用例存在硬编码，需要用例解耦跟踪。
资料检查：目标 API 官方资料条目已有，其中一个资料支持状态需按 Issue 记录处理。

3. NPU 功能验证

验证策略：在 NPU dual Tensor 上验证前向梯度解析及 CPU/NPU 结果一致性。
验证环境及版本：正文列出的 PyTorch/Torch-NPU 版本和 NPU 环境。
验证结果：官方测试覆盖和 NPU forward AD 验证路径已完成记录。
运行日志：正文保留 primal/tangent 结果一致性测试表。

4. 最终结论

分类结论：1.1①。
API适配结论：无需适配，API已支持。
用例适配结论：用例存在硬编码，需要用例解耦跟踪。
交付结论：本 Issue 已完成 API 功能、用例情况、NPU 验证和资料检查说明。

群群青世界成员

28 天前添加了label：bot-triaged

群群青世界成员

28 天前添加了label：event: api-consistency