【合入来源】

issue： [社区任务]: Tensor.indices API一致性验证补齐 #3317
issue： 【社区任务】7月社区任务第一期-Ascend for PyTorch API 一致性开发（83） #2706

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

【修改方案】

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

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

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

PyTorch v2.11.0 官方用例位置：

test/test_sparse.py::TestSparse.test_basic
test/test_sparse.py:L356-L390

该用例覆盖未合并 Tensor 的异常场景，以及已合并 Tensor 的索引返回结果，因此无需新增自定义用例。

2. v2.11.0原始用例情况

v2.11.0 原本不存在：

test_upstream/test/test_sparse.py.patch

官方用例默认使用：

@dtypes(torch.double, torch.cdouble)

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

原始用例运行结果：

TestSparseNPU.test_basic_npu_complex128 ... ERROR
TestSparseNPU.test_basic_npu_float64 ... ERROR

Ran 2 tests

FAILED (errors=2)

3. 本次修改内容

新增：

test_upstream/test/test_sparse.py.patch

为 PrivateUse1/NPU 导入数据类型装饰器，并增加支持的数据类型：

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

导入处理如下：

• import torch_npu 未被直接使用，且导入 torch_npu.contrib.transfer_to_npu 时会加载对应包，因此删除该重复导入；
• from torch_npu.contrib import transfer_to_npu 用于完成 PyTorch 官方测试到 NPU 的转换，依赖导入副作用，因此予以保留；
• 由于 transfer_to_npu 未在文件中直接引用，按照仓库惯例增加 # noqa: F401；
• 该导入放在现有 torch、torch.testing 相关导入之后，符合标准库、第三方库、自定义扩展模块的导入顺序。

最终保留的导入为：

from torch_npu.contrib import transfer_to_npu  # noqa: F401

修改后：

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

本次从干净的 PyTorch v2.11.0 工作树修改 test/test_sparse.py，并通过：

git diff -- test/test_sparse.py

重新生成 patch，未手工编辑 patch 文件。

【资料变更】

不涉及资料修改。

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

docs/zh/api/native_api

PyTorch 2.7.1、2.9.0、2.10.0、2.11.0 和 2.12.0 对应的 torch-Tensor.md 中均已存在唯一的 Tensor.indices 条目，支持状态均登记为：

是否支持：是，暂不支持 Ascend 950DT

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

【接口变更】

不涉及。

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

【功能验证】

运行环境

操作系统：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.11.0+cpu
torch-npu版本：2.11.0rc1

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

cd /workspace

CHECK_DIR="/workspace/pytorch-v2.11.0-patch-check"
PATCH="/workspace/torch-npu-v2.11.0/test_upstream/test/test_sparse.py.patch"

git -C /workspace/pytorch-v2.11.0 worktree remove \
    "${CHECK_DIR}" --force 2>/dev/null || true
rm -rf "${CHECK_DIR}"
git -C /workspace/pytorch-v2.11.0 worktree prune
git -C /workspace/pytorch-v2.11.0 worktree add \
    --detach "${CHECK_DIR}" HEAD

git -C "${CHECK_DIR}" apply --check "${PATCH}"
git -C "${CHECK_DIR}" apply "${PATCH}"
git -C "${CHECK_DIR}" diff --check

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

unset PYTHONPATH
export PYTHONPATH="${CHECK_DIR}/test"
export PYTHONNOUSERSITE=1
export PYTORCH_PRINT_REPRO_ON_FAILURE=0

python - <<'PY'
import runpy
import unittest

import torch
import torch_npu


torch.npu.get_device_capability = lambda *args, **kwargs: (0, 0)
torch.cuda.get_device_capability = lambda *args, **kwargs: (0, 0)

test_file = (
    "/workspace/pytorch-v2.11.0-patch-check/"
    "test/test_sparse.py"
)

namespace = runpy.run_path(
    test_file,
    run_name="tensor_indices_v211",
)

test_class = namespace["TestSparseNPU"]
suite = unittest.TestSuite([
    test_class("test_basic_npu_float32"),
])

result = unittest.TextTestRunner(verbosity=2).run(suite)
raise SystemExit(0 if result.wasSuccessful() else 1)
PY

验证结果：

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

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

OK

最终 patch 可以在干净工作树中正常应用，适配后的官方目标用例已在 NPU 环境执行通过，可以覆盖 Tensor.indices 的核心功能。

【CheckList】

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