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

环境信息

• 操作系统：Ubuntu 22.04
• 昇腾硬件信息：NPU（910B）
• CANN 软件版本：9.0.0
• 安装的对应软件版本：
  • torch 2.7.1+cpu，torch-npu 2.7.1.post4
  • 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

使用场景及问题

当前需确认 torch.sym_ite 在 NPU 环境下的测试覆盖情况，涉及以下 API：

• torch.sym_ite

经检查，PyTorch 官方社区已有对应测试用例，分布在多个测试文件中。本次基于官方用例检查 NPU 环境适配情况，确认是否需要为 torch-npu 各版本（v2.7.1 / v2.11.0 / v2.12.0）提交 test_upstream patch，以及是否需要补充 native API 文档。

一、API 功能说明

torch.sym_ite 是 PyTorch 符号整数系统中的条件选择函数，用于在符号整数或普通整数之间进行分支选择：t if b else f（SymInt-aware 三元运算符）。该 API 属于元编程/符号计算范畴，不涉及张量数据或设备操作，与底层硬件（CPU/CUDA/NPU）完全解耦。该 API 为 PyTorch 公开接口，已由官方添加 docstring 并列入参考页面。
官方文档参考：torch.sym_ite

二、社区用例覆盖情况

通过以下命令在 PyTorch 官方仓库 test/ 目录中搜索 torch.sym_ite 相关用例：

grep -rn "sym_ite" --include="*.py" test/ | awk -F: '{print $1}' | sort -u

搜索运行结果如下：

test/export/test_serialize.py
test/test_dynamic_shapes.py

根据搜索结果，共涉及 2 个测试文件，包含 test_sym_ite 和 test_tracing_sym_ite 等多个测试方法。

结论：PyTorch 官方社区已有完整用例覆盖 torch.sym_ite，本次无需在 torch-npu 的 test/ 目录新增自定义测试文件。

三、NPU 适配分析

torch.sym_ite 为 PyTorch 符号整数系统中的条件选择函数，属于元编程/符号计算范畴，不涉及张量数据或设备操作。其行为与底层硬件完全解耦，无需 monkey-patch 或设备映射。

适配验证

通过以下脚本在 NPU 环境下直接调用 torch.sym_ite，并验证其返回值可用于 NPU 张量创建：

python3 -c "
import torch
import torch_npu

assert torch_npu.npu.is_available(), 'NPU not available'
print('✓ NPU is available')

# 1. 普通整数条件选择
a = 5
b = 3
cond = a > b
result = torch.sym_ite(cond, a, b)
assert result == 5, 'Conditional selection with ints failed'
print('✓ Conditional selection with ints: result =', result)

# 2. NPU 张量形状作为输入
x = torch.randn(5, 3).npu()
result2 = torch.sym_ite(True, x.shape[0], x.shape[1])
assert result2 == 5, 'Shape-based selection failed'
print('✓ Shape-based selection with NPU tensor: result2 =', result2)

# 3. 使用返回值创建 NPU 张量
y = torch.empty(result2, 10).npu()
assert y.device.type == 'npu', 'Tensor not on NPU'
print('✓ New tensor device:', y.device)
print('✓ All tests passed successfully!')
"

输出：

✓ NPU is available
✓ Conditional selection with ints: result = 5
✓ Shape-based selection with NPU tensor: result2 = 5
✓ New tensor device: npu:0
✓ All tests passed successfully!

该验证直接证明：

• torch.sym_ite 在 NPU 环境下可正常调用，返回正确的整数结果。
• 该 API 不执行任何张量数值计算，不涉及设备内存拷贝，与设备类型无关。
• 使用 sym_ite 的返回值作为 NPU 张量的形状参数，能够成功创建 NPU 张量。

四、功能验证

选取 PyTorch 官方测试 test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite 作为验证用例。

测试命令

v2.7.1

cd /workspace/pytorch-v2.7.1 && \
export PYTHONPATH=$(pwd) && \
python3 -c "import torch_npu; assert torch_npu.npu.is_available(), 'NPU not available'" && \
PYTHONWARNINGS=ignore python3 -m unittest test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite -v

v2.11.0

cd /workspace/pytorch-v2.11.0 && \
export PYTHONPATH=$(pwd) && \
python3 -c "import torch_npu; assert torch_npu.npu.is_available(), 'NPU not available'" && \
PYTHONWARNINGS=ignore python3 -m unittest test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite -v

v2.12.0

cd /workspace/pytorch-v2.12.0 && \
export PYTHONPATH=$(pwd) && \
python3 -c "import torch_npu; assert torch_npu.npu.is_available(), 'NPU not available'" && \
PYTHONWARNINGS=ignore python3 -m unittest test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite -v

测试结果

v2.7.1

test_tracing_sym_ite (test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite) ... ok
----------------------------------------------------------------------
Ran 1 test in 0.128s
OK

v2.11.0

test_tracing_sym_ite (test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite) ... ok
----------------------------------------------------------------------
Ran 1 test in 0.138s
OK

v2.12.0

test_tracing_sym_ite (test.test_dynamic_shapes.TestPySymInt.test_tracing_sym_ite) ... ok
----------------------------------------------------------------------
Ran 1 test in 0.286s
OK

因此，torch.sym_ite 在 v2.7.1、v2.11.0、v2.12.0 三个版本的 torch-npu 环境下功能正常。

五、test_upstream patch 处理

本次直接运行 PyTorch 官方原始测试文件：
test/test_dynamic_shapes.py

v2.7.1、v2.11.0、v2.12.0 三个版本均无需修改即可通过。

测试过程中不需要修改以下内容：

• 张量创建逻辑；
• sym_ite 调用方式；
• 测试设备；
• 测试断言；
• 测试预期结果。

因此，目标官方用例无需进行 NPU 专项适配，本任务无需为该 API 新增或修改 test_upstream patch。
同时，由于 PyTorch 官方已有相关测试覆盖，本任务无需在 master 分支的 test/ 目录新增自定义测试用例。

六、资料检查

检查 master 分支 docs/zh/api/native_api/ 下各版本 torch.md 对 torch.sym_ite 的标注：

for ver in 2.7.1 2.11.0 2.12.0 2.13.0; do
    dir="pytorch_${ver//./-}"
    echo "=== $dir ==="
    grep -i "sym_ite" docs/zh/api/native_api/$dir/torch.md || echo "❌ 未找到"
done

执行结果：

=== pytorch_2-7-1 ===
❌ 未找到
=== pytorch_2-11-0 ===
❌ 未找到
=== pytorch_2-12-0 ===
❌ 未找到
=== pytorch_2-13-0 ===
❌ 未找到

结论：各版本均未标注 torch.sym_ite。torch.sym_ite 为 PyTorch 公开接口（非私有接口），属于符号整数计算类 API，不涉及 Tensor 数据计算，需要在 torch.md 的 ## Symbolic Numbers 部分补充文档资料。

七、结论

• torch.sym_ite 已有 PyTorch 官方社区用例覆盖。
• 官方核心用例位于 test/test_dynamic_shapes.py 和 test/export/test_serialize.py。
• 对应测试为 TestPySymInt.test_tracing_sym_ite。
• v2.7.1、v2.11.0、v2.12.0 三个版本均验证通过。
• 该 API 为符号整数逻辑操作，不涉及张量设备或数值计算，无需 NPU 专项适配。
• 无需在 torch-npu 的 test/ 目录新增测试用例。
• 无需为该 API 新增或修改 test_upstream patch。
• 无需进行 API 功能补齐。
• 该 API 属于 PyTorch 公开接口，当前文档尚未收录，需要补充文档资料。
• 本任务需要提交资料 PR（仅文档修改，不涉及代码/测试）。
• 本任务满足 1.2 路线要求，即“PyTorch 官方已有用例，且 NPU 环境下无需修改即可通过”，但需补充文档资料。