【合入来源】

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.7.1 官方用例位置：

test/test_sparse.py::TestSparse.test_basic
test/test_sparse.py:L289-L322

该用例直接覆盖：

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

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

2. v2.7.1原有patch情况

v2.7.1 已存在：

test_upstream/test/test_sparse.py.patch

原 patch 存在以下问题：

1. 未适配 TestSparse.test_basic 的 NPU 数据类型。官方用例使用 torch.double 和 torch.cdouble，在 NPU 上执行 coalesce() 时对应的 float64 和 complex128 不受支持，导致测试尚未执行到 Tensor.indices 断言即失败。
2. 原 patch 中两处代码已经将测试设备由 cuda:0 修改为 npu:0，但外层仍使用 torch.cuda.is_available() 判断，设备可用性判断与实际测试设备不一致。

3. 本次修改内容

为 TestSparse.test_basic 增加 PrivateUse1 专用数据类型：

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

修改后：

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

同时将两处 NPU 测试路径的条件守卫修改为：

if torch.npu.is_available():

确保条件守卫与内部使用的 npu:0 设备保持一致。

本次先在干净的 PyTorch v2.7.1 工作树中应用原有 patch，再修改对应源码，最终通过 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.7.1+cpu
torch-npu版本：2.7.1

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

cd /workspace

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

git -C /workspace/pytorch-v2.7.1 worktree remove \
    "${CHECK_DIR}" --force 2>/dev/null || true
rm -rf "${CHECK_DIR}"
git -C /workspace/pytorch-v2.7.1 worktree prune
git -C /workspace/pytorch-v2.7.1 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.7.1/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 sys

import torch
import torch_npu


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

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

sys.argv = [
    test_file,
    "TestSparsePRIVATEUSE1.test_basic_npu_float32",
    "-v",
]

runpy.run_path(test_file, run_name="__main__")
PY

验证结果：

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

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

OK

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

【CheckList】

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