You are an engineer proficient in torch_npu interface adaptation. This Skill provides torch_npu interface compatibility queries and extended interface reference.
Official reference documentation (the following links contain version number paths; you MUST check the latest version documentation from the Ascend official website in real time; the links are for reference only):
- Training Migration Guide: Ascend Official Website → Documentation → PyTorch Framework Adaptation → Training Migration Guide
- PyTorch Native Interface Support: Ascend Official Website → Documentation → PyTorch Framework Adaptation → Interface Reference → PyTorch Native Interfaces
- torch_npu Extended Interfaces: Ascend Official Website → Documentation → PyTorch Framework Adaptation → Interface Reference → Extended Interfaces
- torch_npu Official Repository:https://gitcode.com/Ascend/pytorch
I. torch_npu Overview
1.1 Positioning of torch_npu
torch_npu is the Ascend NPU adaptation extension for PyTorch. Through the plugin mechanism provided by PyTorch 2.1, it dynamically adds Ascend backend adaptation, including support for a series of capabilities such as NPU devices and HCCL.
PyTorch 原生支持:
torch.cpu ← CPU后端
torch.cuda ← NVIDIA GPU后端
扩展支持:
torch.npu ← 昇腾NPU后端(通过torch_npu包提供)
1.2 torch_npu Installation and Import
You MUST check the latest version documentation on the Ascend official website in real time; the following links are for reference only: Ascend Official Website → Documentation → PyTorch Framework Adaptation → Software Installation Guide → Installation → Install Using Binary Package Reference link:https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md
According to the target PyTorch version, architecture (aarch64/x86_64), and Python version, find the corresponding download link from the above documentation.
# 方式1:wget下载whl包安装(推荐,优先使用)
# 示例:PyTorch 2.9.0 + aarch64 + Python 3.11 + CANN 9.0.0
pip install pyyaml setuptools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
wget https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp311-cp311-manylinux_2_28_aarch64.whl
pip install torch-2.9.0+cpu-cp311-cp311-manylinux_2_28_aarch64.whl
wget https://gitcode.com/Ascend/pytorch/releases/download/v26.0.0-pytorch2.9.0/torch_npu-2.9.0.post2-cp311-cp311-manylinux_2_28_aarch64.whl
pip install torch_npu-2.9.0.post2-cp311-cp311-manylinux_2_28_aarch64.whl
# 方式2:pip直接安装(备选,网络通畅时使用)
# pip install torch-npu=={version} -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com # version必须与PyTorch版本对应
# 如阿里源失败,尝试清华源:pip install torch-npu=={version} -i https://pypi.tuna.tsinghua.edu.cn/simple
# 如镜像源均失败,回退至默认源:pip install torch-npu=={version}
# 导入(必须在import torch之后)
import torch
import torch_npu # 注册NPU后端
# 验证
print(torch.npu.is_available()) # True
1.3 torch_npu Source Code Repository
- Repository address:https://gitcode.com/Ascend/pytorch
- Release download:https://gitcode.com/Ascend/pytorch/releases
1.4 Obtaining Solutions from Source Code
When interface adaptation issues cannot be resolved from this Skill or the official documentation, you can pull the torch_npu code repository and analyze the interface implementation and adaptation solution based on the actual code:
# 拉取代码仓(--recursive确保第三方依赖也被拉取)
git clone https://gitcode.com/Ascend/pytorch.git --recursive
# 切换到与当前PyTorch版本对应的分支
cd pytorch
git checkout v{PyTorch版本号}
# 如果克隆时未加--recursive,可后续补充拉取子模块
git submodule update --init --recursive
II. NPU Support Status of PyTorch Interfaces
2.1 Interface Support Query
Ascend officially provides an interface support list differentiated by PyTorch version. You MUST consult the corresponding documentation according to the PyTorch version actually used:
| PyTorch Version | Interface Documentation Path |
|---|---|
| 2.10.0 | apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-10-0/overview.md |
| 2.9.0 | apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-9-0/overview.md |
| 2.8.0 | apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-8-0/overview.md |
| 2.7.1 | apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-7-1/overview.md |
| 2.6.0 | apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-6-0/overview.md |
| 2.1.0 | apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-1-0/overview.md |
The above paths are all based on the documentation root directory
https://www.hiascend.com/document/detail/zh/Pytorch/2600/. Versions iterate quickly; you MUST refer to the latest version documentation on the official website.
Query Method:
- Determine the PyTorch version used by the current project
- Open the interface support documentation for the corresponding version
- Search for the target interface name and check whether it is in the support list
- If it is in the support list, confirm the description of behavior differences for the interface
- If it is not in the support list, check the torch_npu extended interface documentation for an alternative
2.2 torch_npu Extended Interfaces
torch_npu provides extended interfaces dedicated to Ascend NPU. You MUST consult the official extended interface documentation to confirm interface names, parameters, and usage:
- Extended Interface Documentation: Ascend Official Website → Documentation → PyTorch Framework Adaptation → Interface Reference → Extended Interfaces
2.3 Common Unsupported Interfaces or Interfaces with Behavior Differences
| Interface | Status | Alternative |
|---|---|---|
torch.cuda.* |
Needs to be replaced with torch.npu.* |
See Migration Skill Chapter 2 Device Mapping Replacement Rules |
torch.backends.cudnn.* |
Not supported | Delete or conditionally skip |
| Custom CUDA extension (.cu) | Not supported | Use torch_npu extended interfaces or PyTorch native implementation |