【合入来源】

issue：【社区任务】7月社区任务第三期-Ascend for PyTorch API 一致性开发（124） #3235

issue：[Usage]: torch.Generator.clone_state NPU一致性验证 #3476

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

【修改方案】

1. API基础功能及用例覆盖

torch.Generator.clone_state 用于克隆当前 Generator 的随机数状态，返回一个新的 Generator 对象。克隆后的 Generator 应保持与原 Generator 克隆时一致的 RNG 状态，从而保证后续随机数生成结果可复现。

PyTorch v2.7.1 官方社区中已存在 torch.Generator.clone_state 相关用例，检索结果包括：

test/test_cuda.py:1965
test/test_cuda.py:2068
test/inductor/test_cudagraph_trees.py:2673

其中本次适配的官方目标用例为：

test/test_cuda.py::TestCuda.test_graphsafe_set_get_rng_state
test/test_cuda.py:L1951-L2028

该用例直接覆盖以下 Generator RNG 状态相关功能：

• graphsafe_get_state
• clone_state
• graphsafe_set_state
• 默认 Generator 在图场景下的 RNG 状态一致性

因此，本次无需新增自定义测试用例，只需适配现有 PyTorch 官方用例。

2. v2.7.1原有patch情况

v2.7.1 已存在：

test_upstream/test/test_cuda.py.patch

原 patch 已对 test/test_cuda.py 中部分 CUDA 相关测试进行了 NPU 适配，但未覆盖 torch.Generator.clone_state 对应的官方目标用例：

test/test_cuda.py::TestCuda.test_graphsafe_set_get_rng_state

原始官方用例中使用了 CUDA 专属接口和 CUDA 设备：

torch.Generator(device="cuda")
torch.cuda.CUDAGraph()
torch.cuda.Stream()
torch.cuda.default_generators[0]
torch.cuda.stream(s)
torch.cuda.current_stream().wait_stream(s)
torch.rand(..., device="cuda")

在 NPU 环境下直接运行时，该用例会因 CUDA graph 条件不满足而跳过，无法覆盖 torch.Generator.clone_state 在 NPU 上的行为。

此外，在导入测试依赖时，torch.cuda.get_device_capability() 在 NPU 环境下可能返回 None，而 PyTorch 内部 common_cuda.py 中存在与 tuple 比较的逻辑，可能导致导入阶段触发异常：

TypeError: '>=' not supported between instances of 'NoneType' and 'tuple'

3. 本次修改内容

本次在已有 test_upstream/test/test_cuda.py.patch 基础上补充 test_graphsafe_set_get_rng_state 的 NPU 适配。

主要修改如下：

1. 将目标用例中的 CUDA 设备张量替换为 NPU 设备张量：

torch.rand(..., device="npu")

2. 将 Generator 初始化设备从 CUDA 替换为 NPU：

generator = torch.Generator(device="npu")

3. 将 CUDA graph 相关接口替换为 NPU graph 对应接口：

g = torch.npu.NPUGraph()
s = torch.npu.Stream()
default_generator = torch.npu.default_generators[0]

4. 将 CUDA stream 上下文替换为 NPU stream 上下文：

with torch.npu.stream(s):

5. 将 CUDA stream 同步替换为 NPU stream 同步：

torch.npu.current_stream().wait_stream(s)

6. 将原 CUDA graph 可用性判断替换为 NPU 可用性判断：

@unittest.skipIf(
    not torch.npu.is_available(), "NPU not available, skipping tests"
)

7. 增加 torch.cuda.get_device_capability() 返回 None 时的兼容处理，避免测试导入阶段触发 NoneType 与 tuple 比较异常：

if torch.cuda.get_device_capability() is None:
    torch.cuda.get_device_capability = lambda device=None: (0, 0)  # noqa: E731

8. 增加以下装饰器，避免 CUDA memory leak / non-default stream 检查逻辑影响 NPU 目标用例运行：

@skipCUDAMemoryLeakCheckIf(True)
@skipCUDANonDefaultStreamIf(True)

导入顺序说明

test/test_cuda.py 中 torch_npu / transfer_to_npu 的导入位置属于初始化依赖例外。

原因是 TestCuda 类存在类级跳过条件：

@unittest.skipIf(not TEST_CUDA, "CUDA not available, skipping tests")
class TestCuda(TestCase):

TEST_CUDA 会在 torch.testing._internal.common_cuda 导入阶段计算。若严格将 torch_npu / transfer_to_npu 放到所有 torch.testing 导入之后，NPU 环境下 TEST_CUDA 会提前计算为 False，导致目标用例 test_graphsafe_set_get_rng_state 被类级 skip，无法覆盖 torch.Generator.clone_state。

因此本 patch 保留 transfer_to_npu 在 common_cuda 导入前初始化。该处理不使用 try-except，不修改 TestCuda 类级 skip 条件，也不新增 NPU 专用测试类，仅用于保证官方目标用例能在 NPU 上真实执行。

本次只适配官方已有用例，不修改 torch.Generator.clone_state 接口实现。
本次适配的 test_graphsafe_set_get_rng_state 已能覆盖 torch.Generator.clone_state 在 NPU Generator RNG 状态克隆场景下的核心行为。

【资料变更】

已检查 master 分支 docs/zh/api/native_api 资料目录，torch.Generator.clone_state 为 PyTorch Generator 公开接口，非私有接口。该 API 属于 Generator 状态类 API，非计算类 API，与具体数据类型无关，限制与说明填写为 -。

根据 master 分支最新资料目录规则，pytorch_2-9-0 与 pytorch_2-10-0 目录已删除，本次不再补充；新增 pytorch_2-13-0 目录需要同步检查并刷新。资料补齐以 master 分支 docs/zh/api/native_api 当前实际存在的版本目录为准。

资料补齐已在 master 分支单独提交 PR。本次未新增独立的 torch-Generator.md 文件，而是在各版本已有 torch.md 的 ## Generators 章节中补充 clone_state() 条目，位置放在 set_state() 之后，保持 torch.Generator 相关 API 统一维护在 torch.md 中。

【接口变更】

不涉及。

本次仅适配 PyTorch 官方测试用例，不修改客户可见接口，不修改 torch.Generator.clone_state 功能实现。

【功能验证】

运行环境

操作系统：Ubuntu 22.04.5 LTS
机器架构：aarch64
昇腾硬件：Ascend 910B3 NPU
npu-smi版本：25.2.0
CANN版本：9.1.0-beta.1
Python版本：3.11
torch版本：2.7.1+cpu
torch-npu版本：2.7.1

将最终 patch 应用到干净的 PyTorch v2.7.1 工作树后，运行官方目标用例。

cd /workspace

source /workspace/envs/torch-npu-2.7.1/bin/activate
source /usr/local/Ascend/ascend-toolkit/set_env.sh

unset PYTHONPATH
export PYTHONPATH=/workspace/pytorch-v2.7.1/test
export PYTHONNOUSERSITE=1
export PYTORCH_PRINT_REPRO_ON_FAILURE=0

python /workspace/pytorch-v2.7.1/test/test_cuda.py -v -k test_graphsafe_set_get_rng_state

验证结果：

test_graphsafe_set_get_rng_state (__main__.TestCuda.test_graphsafe_set_get_rng_state) ... ok

----------------------------------------------------------------------
Ran 1 test in 0.191s

OK

最终 patch 可以在干净工作树中正常应用，修改后的官方用例已在 NPU 上通过，可以覆盖 torch.Generator.clone_state 的核心功能。

【CheckList】

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