任务 issue 来源：【社区任务】7月社区任务第一期-Ascend for PyTorch API 一致性开发（83） #2706

环境信息

操作系统：Ubuntu 22.04.5 LTS
机器架构：aarch64
昇腾硬件信息：Ascend 910B3 NPU
npu-smi版本：25.2.0
CANN软件版本：9.1.0-beta.1

安装的对应软件版本：

- torch 2.7.1+cpu，torch-npu 2.7.1
- torch 2.9.0+cpu，torch-npu 2.9.0.post2
- torch 2.10.0+cpu，torch-npu 2.10.0
- torch 2.11.0+cpu，torch-npu 2.11.0rc1
- torch 2.12.0+cu130，torch-npu 2.12.0rc1

使用场景及问题

当前需确认以下 API 在 NPU 环境下的测试覆盖和适配情况：

Tensor.indices

经检查，PyTorch 官方已有直接测试用例：

test/test_sparse.py::TestSparse.test_basic

该用例在 NPU 上需要进行数据类型适配，因此本任务走 1.1 路线：PyTorch 官方有用例，并且需要进行 NPU 适配。

按照当前版本要求，本次处理：

v2.7.1
v2.11.0
v2.12.0

v2.9.0 和 v2.10.0 已进入维护阶段，暂不提交测试 patch；master 不需要提交 patch。

一、API功能说明

Tensor.indices 用于获取已合并 Sparse COO Tensor 的索引张量：

• 已合并 Tensor 调用后，返回结果应与 Tensor._indices 一致；
• 未合并 Tensor 调用时，应抛出异常。

二、官方用例覆盖情况

PyTorch 官方直接测试用例及准确行号范围如下：

PyTorch v2.7.1：
test/test_sparse.py::TestSparse.test_basic
test/test_sparse.py:L289-L322

PyTorch v2.11.0：
test/test_sparse.py::TestSparse.test_basic
test/test_sparse.py:L356-L390

PyTorch v2.12.0：
test/test_sparse.py::TestSparse.test_basic
test/test_sparse.py:L357-L391

该用例直接覆盖以下场景：

if not coalesced:
    with self.assertRaisesRegex(
        RuntimeError,
        "Cannot get indices on an uncoalesced tensor",
    ):
        x.indices()
else:
    self.assertEqual(x.indices(), x._indices())

因此，无需在 torch-npu 的 test/ 目录新增自定义测试用例，只需适配现有官方用例。

三、NPU适配分析

官方用例默认使用：

@dtypes(torch.double, torch.cdouble)

在 NPU 上会生成 float64 和 complex128 测试实例。当前 NPU 的 Sparse COO coalesce() 不支持上述 values 数据类型，导致用例在执行到 Tensor.indices 断言前失败。

本次为 PrivateUse1/NPU 单独指定支持的 torch.float。

PyTorch v2.7.1 修改为：

@coalescedonoff
@dtypes(torch.double, torch.cdouble)
@dtypesIfPRIVATEUSE1(torch.float)
def test_basic(self, device, dtype, coalesced):

PyTorch v2.11.0 和 v2.12.0 保留原有 MPS 配置，并增加：

@coalescedonoff
@dtypes(torch.double, torch.cdouble)
@dtypesIfMPS(torch.float32, torch.complex64)
@dtypesIfPRIVATEUSE1(torch.float)
def test_basic(self, device, dtype, coalesced):

修改后：

• CPU 继续使用 torch.double 和 torch.cdouble；
• MPS 保持原有数据类型配置；
• NPU 使用支持的 torch.float；
• 保留官方用例原有断言逻辑；
• 不修改 Tensor.indices 接口实现。

四、各版本patch处理

v2.7.1

v2.7.1 已存在：

test_upstream/test/test_sparse.py.patch

原 patch 未适配 TestSparse.test_basic 的 NPU 数据类型，本次在已有 patch 中增加：

@dtypesIfPRIVATEUSE1(torch.float)

同时修正原 patch 中两处设备判断与实际设备不一致的问题。

原代码已经将内部测试设备修改为 npu:0，但外层仍使用：

if torch.cuda.is_available():

本次修改为：

if torch.npu.is_available():

确保设备可用性判断与实际测试设备一致。

对应处理路线为 1.1.2：修改已有 patch。

v2.11.0

v2.11.0 原本不存在：

test_upstream/test/test_sparse.py.patch

本次新增该 patch，并完成以下适配：

• 导入 dtypesIfPRIVATEUSE1；
• 为 TestSparse.test_basic 增加 @dtypesIfPRIVATEUSE1(torch.float)；
• 删除未直接使用且不必要的 import torch_npu；
• 保留依赖导入副作用的 transfer_to_npu；
• 按照仓库惯例使用 # noqa: F401 处理未直接引用的导入；
• 将 transfer_to_npu 放在现有 torch、torch.testing 相关导入之后。

最终保留的导入为：

from torch_npu.contrib import transfer_to_npu  # noqa: F401

transfer_to_npu 用于完成 PyTorch 官方测试到 NPU 的转换，依赖导入副作用，因此不能删除。单独的 import torch_npu 不再需要。

对应处理路线为 1.1.1：新增 patch。

v2.12.0

v2.12.0 原本不存在：

test_upstream/test/test_sparse.py.patch

本次新增该 patch，采用与 v2.11.0 相同的适配方式：

• 导入 dtypesIfPRIVATEUSE1；
• 为 TestSparse.test_basic 增加 @dtypesIfPRIVATEUSE1(torch.float)；
• 删除未直接使用且不必要的 import torch_npu；
• 保留依赖导入副作用的 transfer_to_npu；
• 按照仓库惯例使用 # noqa: F401；
• 将 transfer_to_npu 放在现有 torch、torch.testing 相关导入之后。

最终保留的导入为：

from torch_npu.contrib import transfer_to_npu  # noqa: F401

对应处理路线为 1.1.1：新增 patch。

五、功能验证

最终 patch 分别应用到对应 PyTorch 干净工作树后，重新运行官方目标用例。

v2.7.1

test_basic_npu_float32 (__main__.TestSparsePRIVATEUSE1.test_basic_npu_float32) ... ok

----------------------------------------------------------------------
Ran 1 test in 0.611s

OK

v2.11.0

原始用例使用 float64 和 complex128，在 Sparse COO coalesce() 阶段失败。

适配后结果如下：

test_basic_npu_float32 (tensor_indices_v211.TestSparseNPU.test_basic_npu_float32) ... ok

----------------------------------------------------------------------
Ran 1 test in 0.607s

OK

v2.12.0

test_basic_npu_float32 (tensor_indices_v212.TestSparseNPU.test_basic_npu_float32) ... ok

----------------------------------------------------------------------
Ran 1 test in 0.619s

OK

三个目标版本修改后的官方用例均在 NPU 环境下执行通过，能够正常覆盖：

• 未合并 Sparse COO Tensor 的异常场景；
• 已合并 Sparse COO Tensor 的索引返回结果；
• Tensor.indices 与 Tensor._indices 的一致性。

六、资料检查

已基于 torch-npu 最新 master 分支检查资料目录：

docs/zh/api/native_api

本次检查以下版本：

pytorch_2-7-1
pytorch_2-9-0
pytorch_2-10-0
pytorch_2-11-0
pytorch_2-12-0

各版本的 torch-Tensor.md 中均已存在唯一的 Tensor.indices 条目，具体位置如下：

PyTorch 2.7.1：
docs/zh/api/native_api/pytorch_2-7-1/torch-Tensor.md:L2533-L2541

PyTorch 2.9.0：
docs/zh/api/native_api/pytorch_2-9-0/torch-Tensor.md:L2533-L2541

PyTorch 2.10.0：
docs/zh/api/native_api/pytorch_2-10-0/torch-Tensor.md:L2534-L2542

PyTorch 2.11.0：
docs/zh/api/native_api/pytorch_2-11-0/torch-Tensor.md:L2534-L2542

PyTorch 2.12.0：
docs/zh/api/native_api/pytorch_2-12-0/torch-Tensor.md:L2534-L2542

五个版本的资料均登记为：

**原生文档**：[Tensor.indices](对应版本的PyTorch原生文档链接)

**是否支持**：是，暂不支持<term>Ascend 950DT</term>

Tensor.indices 属于非计算类 API，与输入数据类型无关。现有资料未填写 fp16、fp32 等具体数据类型，符合非计算类 API 的资料填写要求。

本次验证环境为 Ascend 910B3，不属于资料中注明暂不支持的 Ascend 950DT，资料支持状态与实际验证结果一致。

PyTorch 2.6 和 2.8 按当前规则无需刷新。

因此，本任务无需修改资料，也无需单独提交 master 资料 PR。

七、PR信息

v2.7.1：

https://gitcode.com/Ascend/pytorch/pull/42541

v2.11.0：

https://gitcode.com/Ascend/pytorch/pull/42805

v2.12.0：
https://gitcode.com/Ascend/pytorch/pull/42806

八、结论

• Tensor.indices 已有 PyTorch 官方直接测试用例覆盖。
• 已补充三个目标版本中 TestSparse.test_basic 的准确行号范围。
• 官方用例覆盖已合并和未合并 Sparse COO Tensor 场景。
• 原用例的 float64 和 complex128 在 NPU Sparse COO coalesce() 场景下不受支持。
• 本次为 PrivateUse1/NPU 单独指定 torch.float。
• v2.7.1 修改已有 test_sparse.py.patch。
• v2.11.0 和 v2.12.0 分别新增 test_sparse.py.patch。
• v2.11.0、v2.12.0 删除不必要的 import torch_npu。
• 保留依赖导入副作用的 transfer_to_npu，并使用 # noqa: F401。
• 三个版本的 patch 均从对应 PyTorch 干净工作树通过 git diff 重新生成。
• 三个目标版本的 test_basic_npu_float32 均重新验证通过。
• v2.11.0 和 v2.12.0 使用去掉多余 v 的规范源分支名。
• v2.9.0 和 v2.10.0 已进入维护阶段，暂不提交测试 patch。
• master 不需要提交 patch。
• 无需修改 Tensor.indices 接口实现。
• 无需新增 torch-npu 自定义测试用例。
• 现有资料记录正确，无需修改资料。
• 本任务满足 1.1 路线要求。

欢迎加入社区，感谢您对社区的贡献 🎉!