【合入来源】

• 需求

• 问题单

• issue/工单

• 重构优化

• 资料更新

• 来源任务 Issue：【社区任务】7月社区任务第二期-Ascend for PyTorch API 一致性开发（31）

• 结果 Issue：torch.autograd.grad_mode.set_grad_enabled.clone API 一致性补齐

【分支范围】

本 PR 面向 v2.7.1 目标分支。

本任务整体覆盖：

master、v2.7.1、v2.11.0、v2.12.0

v2.9.0、v2.10.0 已进入维护阶段，不再合入新特性或本类新增测试，因此本任务
不再对这两个分支作补齐要求。

【修改方案】

本次仅补充 torch.autograd.grad_mode.set_grad_enabled.clone 的 NPU 单元测试，
不修改 API 实现。

修改文件：

test/npu/test_locally_disabling_gradient_omputation.py

整改后提交：

源分支：pr/set-grad-enabled-clone-v2.7.1
Commit：1da804b44681ace1c8ff9fd7b06e9ccf3d05b31c
提交标题：test: add clone coverage for set_grad_enabled
文件 SHA-256：642c2b526d025de467b3b1ef728526b64977e22485ceafb0e8c60a58f25b1120

文件头增加 Huawei BSD 3-Clause copyright 和 API 覆盖说明：

# Copyright (c) 2026 Huawei Technologies Co., Ltd
# All rights reserved.
#
# Licensed under the BSD 3-Clause License (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://opensource.org/licenses/BSD-3-Clause
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Add validation cases for gradient-mode APIs on NPU.

This file validates torch.no_grad, torch.enable_grad, torch.set_grad_enabled,
and torch.autograd.grad_mode.set_grad_enabled.clone, including clone object
independence, mode preservation, grad-mode restoration, and decorator behavior
with NPU tensors.
"""

1. clone 直接行为

整改后的 test_set_grad_enabled_clone：

def test_set_grad_enabled_clone(self):
    initial_grad_enabled = torch.is_grad_enabled()

    with torch.set_grad_enabled(initial_grad_enabled):
        for mode in (False, True):
            ctx = torch.set_grad_enabled(mode)
            cloned = ctx.clone()

            self.assertIsNot(ctx, cloned)
            self.assertIsInstance(
                cloned,
                torch.autograd.grad_mode.set_grad_enabled,
            )
            self.assertEqual(cloned.mode, mode)

    self.assertEqual(torch.is_grad_enabled(), initial_grad_enabled)

验证：

• torch.set_grad_enabled(False).clone()；
• torch.set_grad_enabled(True).clone()；
• clone 后对象与原对象不是同一实例；
• clone 后对象类型保持；
• clone 后 mode 状态保持；
• 测试结束后线程 grad mode 与测试开始时一致。

2. NPU Tensor 装饰器调用链

整改后的 test_set_grad_enabled_clone_decorator：

def test_set_grad_enabled_clone_decorator(self):
    initial_grad_enabled = torch.is_grad_enabled()
    x = torch.tensor(
        [1.0],
        device="npu:0",
        requires_grad=True,
    )

    with torch.set_grad_enabled(initial_grad_enabled):
        @torch.set_grad_enabled(False).clone()
        def grad_disabled(tensor):
            return tensor * 2

        with torch.enable_grad():
            disabled_result = grad_disabled(x)

        self.assertEqual(disabled_result.device, x.device)
        self.assertFalse(disabled_result.requires_grad)

        @torch.set_grad_enabled(True).clone()
        def grad_enabled(tensor):
            return tensor * 2

        with torch.no_grad():
            enabled_result = grad_enabled(x)

        self.assertEqual(enabled_result.device, x.device)
        self.assertTrue(enabled_result.requires_grad)

    self.assertEqual(torch.is_grad_enabled(), initial_grad_enabled)

该用例在测试代码中显式调用：

torch.set_grad_enabled(False).clone()
torch.set_grad_enabled(True).clone()

并直接验证：

• 外层梯度开启时，clone 后的 mode=False 装饰器使 NPU 输出
  requires_grad=False；
• 外层 torch.no_grad() 时，clone 后的 mode=True 装饰器使 NPU 输出
  requires_grad=True；
• 输出 Tensor 仍位于输入 NPU 设备；
• 测试结束后线程 grad mode 恢复。

3. 导入清理

继续保持移除冗余的：

import torch_npu  # noqa: F401

当前通过：

from torch_npu.testing.testcase import TestCase, run_tests

使用项目测试基类和测试入口，不使用 noqa 掩盖未使用导入。

本次不涉及：

• PyTorch API 功能实现；
• Torch-NPU C++ 适配；
• NPU Kernel；
• test_upstream patch；
• 跨代码仓接口变更。

【社区用例检索与新增必要性】

在 origin/v2.7.1（bacce7d835e779a6417047f18547f58fc0e37739）中执行：

git grep -n -E \
  'set_grad_enabled.*clone|clone.*set_grad_enabled|test_.*set_grad_enabled.*clone' \
  -- test

直接 clone 测试匹配数：

0

相关基础测试包括：

• test/test_autograd.py::test_set_grad_enabled
• test/test_autograd.py::test_set_grad_enabled_wraps
• test/npu/test_locally_disabling_gradient_omputation.py::test_set_grad_enabled

这些用例覆盖基础上下文管理器或通用装饰器行为，但没有直接检查 clone 后对象的
身份、类型和 mode，没有验证测试前后线程 grad mode 保持，也没有使用 clone
后对象作为装饰器对 NPU Tensor 输出进行断言。因此需要在现有 Torch-NPU NPU
测试文件中新增本用例，不能直接以社区基础用例替代。

【资料变更】

涉及。

torch.autograd.grad_mode.set_grad_enabled.clone 为 PyTorch 对外公开的
set_grad_enabled 子方法。经资料补齐要求复核，当前 Torch-NPU Native API
资料仅登记父 API，缺少 clone() 子方法，因此本任务另行提交资料补齐 PR。

资料补齐信息：

目标分支：master
源分支：docs/set-grad-enabled-clone
基线提交：462f4e18a8303698aca3997edfcc5dd3b1707968
资料提交：fcc55fd51dc6e4ba5a4068cb9805d15a59021bc3
提交标题：docs: add support status for set_grad_enabled.clone
资料 PR：[PR #44139](https://gitcode.com/Ascend/pytorch/pull/44139)

资料修改文件：

docs/zh/api/native_api/pytorch_2-7-1/torch.md
docs/zh/api/native_api/pytorch_2-11-0/torch.md
docs/zh/api/native_api/pytorch_2-12-0/torch.md
docs/zh/api/native_api/pytorch_2-13-0/torch.md

资料中将 clone() 作为
torch.autograd.grad_mode.set_grad_enabled 的子方法登记，支持状态与父 API
保持一致：

• Atlas A2 训练系列产品：支持；
• Atlas A3 训练系列产品：支持；
• Ascend 950DT：暂不支持。

该 API 为非计算类上下文对象复制方法，与 Tensor 数据类型无关，因此资料中不
增加 fp16、fp32、bf16 等 dtype 限制说明。

资料分支已完成本地检查并成功推送，diff --check、四版本条目覆盖及远端 SHA
验证均通过。

【接口变更】

不涉及。

本次不修改函数实现、接口签名、返回类型或其他组件交互。

【功能验证】

环境

目标分支：v2.7.1
torch：2.7.1+cpu
torch-npu：2.7.1.post2
NPU available：True
NPU device count：1

命令

python test/npu/test_locally_disabling_gradient_omputation.py -v

隔离验证还分别从初始 grad mode 为 False 和 True 的状态执行两个 clone 测试。

测试场景

test_enable_grad
test_no_grad
test_set_grad_enabled
test_set_grad_enabled_clone
test_set_grad_enabled_clone_decorator

隔离验证场景：

initial=False → before=False → after=False
initial=True  → before=True  → after=True

完整原始输出

==================================================
TARGET_BRANCH=v2.7.1
SOURCE_BRANCH=pr/set-grad-enabled-clone-v2.7.1
COMMIT=1da804b44681ace1c8ff9fd7b06e9ccf3d05b31c
PYTHON=envs/torch_npu_2.7.1/bin/python
TEST_FILE=/tmp/set_grad_enabled_clone_final_tests_590/v2.7.1/test/npu/test_locally_disabling_gradient_omputation.py
TEST_FILE_SHA256=642c2b526d025de467b3b1ef728526b64977e22485ceafb0e8c60a58f25b1120
==================================================

===== ENVIRONMENT PROBE =====
python_executable=/workspace/user_data/torch_npu_api_check/check_close_args/envs/torch_npu_2.7.1/bin/python
python_version=3.11.15
platform=Linux-5.10.0-216.0.0.115.oe2203sp4.aarch64-aarch64-with-glibc2.35
torch_version=2.7.1+cpu
torch_npu_version=2.7.1.post2
torch_file=/workspace/user_data/torch_npu_api_check/check_close_args/envs/torch_npu_2.7.1/lib/python3.11/site-packages/torch/__init__.py
torch_npu_file=/workspace/user_data/torch_npu_api_check/check_close_args/envs/torch_npu_2.7.1/lib/python3.11/site-packages/torch_npu/__init__.py
npu_available=True
npu_device_count=1
initial_grad_enabled=True
ENVIRONMENT_PROBE_EXIT_CODE=0

===== FULL TEST FILE =====
COMMAND=env -u PYTHONPATH PYTHONNOUSERSITE=1 envs/torch_npu_2.7.1/bin/python /tmp/set_grad_enabled_clone_final_tests_590/v2.7.1/test/npu/test_locally_disabling_gradient_omputation.py -v
test_enable_grad (__main__.TestLDGComputation.test_enable_grad) ... ok
test_no_grad (__main__.TestLDGComputation.test_no_grad) ... ok
test_set_grad_enabled (__main__.TestLDGComputation.test_set_grad_enabled) ... ok
test_set_grad_enabled_clone (__main__.TestLDGComputation.test_set_grad_enabled_clone) ... ok
test_set_grad_enabled_clone_decorator (__main__.TestLDGComputation.test_set_grad_enabled_clone_decorator) ... ok

----------------------------------------------------------------------
Ran 5 tests in 0.361s

OK
FULL_TEST_EXIT_CODE=0

===== GRAD MODE ISOLATION PROBE =====
test_set_grad_enabled_clone (set_grad_enabled_clone_test_module.TestLDGComputation.test_set_grad_enabled_clone) ... ok
test_set_grad_enabled_clone_decorator (set_grad_enabled_clone_test_module.TestLDGComputation.test_set_grad_enabled_clone_decorator) ... ok

----------------------------------------------------------------------
Ran 2 tests in 0.211s

OK
test_set_grad_enabled_clone (set_grad_enabled_clone_test_module.TestLDGComputation.test_set_grad_enabled_clone) ... ok
test_set_grad_enabled_clone_decorator (set_grad_enabled_clone_test_module.TestLDGComputation.test_set_grad_enabled_clone_decorator) ... ok

----------------------------------------------------------------------
Ran 2 tests in 0.002s

OK
PROCESS_ORIGINAL_GRAD_MODE=True
ISOLATION_RESULT=initial:False,before:False,after:False,tests_run:2,successful:True
ISOLATION_RESULT=initial:True,before:True,after:True,tests_run:2,successful:True
PROCESS_FINAL_GRAD_MODE=True
GRAD_MODE_ISOLATION_PROBE=PASS
GRAD_MODE_ISOLATION_EXIT_CODE=0

RESULT=PASS
v2.7.1_TEST_COLLECTOR_EXIT_CODE=0
v2.7.1_WORKTREE_REMOVE_EXIT_CODE=0

该版本执行结果：

Ran 5 tests in 0.361s
OK
FULL_TEST_EXIT_CODE=0

ISOLATION_RESULT=initial:False,before:False,after:False,tests_run:2,successful:True
ISOLATION_RESULT=initial:True,before:True,after:True,tests_run:2,successful:True
GRAD_MODE_ISOLATION_PROBE=PASS
GRAD_MODE_ISOLATION_EXIT_CODE=0

【test_upstream patch】

不涉及。

本 PR 只修改 Torch-NPU 自定义 NPU 测试，不修改 PyTorch 官方测试逻辑或断言，
无需新增或修改 test_upstream patch。

【CheckList】

• 代码注释和格式符合规范（本次未新增业务日志）
• 文件包含规范 copyright 和 API 覆盖说明
• 测试代码显式调用目标 clone()
• 测试结束后恢复线程 grad mode
• False/True 初始 grad mode 隔离验证通过
• 使用 NPU Tensor 验证装饰器调用链的计算图行为
• 使用项目测试基类和 run_tests，未直接导入 unittest
• 仅保留一次任务提交，且只修改目标测试文件
• PR 标题正确使用 test 类型标签
• Native API 资料补齐分支已完成并推送
• 资料补齐 PR 已创建并回填链接
• 本轮最新 PR 持续集成流水线（CI）执行通过