已合并
[docs]v2.9.0文档产品名称更新 #39994
chenzhenxi创建于 7月3日
[docs]v2.9.0文档产品名称更新 #39994
已合并
chenzhenxi创建于 7月3日
16 个文件变更+174-148
MREADME.md+58-58
@@ -1,8 +1,8 @@
1-# Ascend Extension for PyTorch1+# TorchNPU
2 2 
3## Overview3## Overview
4 4 
5-This repository develops the **Ascend Extension for PyTorch** named **torch_npu** to adapt **Ascend NPU** to **PyTorch** so that developers who use the **PyTorch** can obtain powerful compute capabilities of **Ascend AI Processors**.5+**TorchNPU** is a PyTorch adapter plugin that brings **Ascend NPU** support into the **PyTorch** ecosystem, enabling developers to harness the high-performance computing power of Ascend AI processors.
6 6 
7Ascend is a full-stack AI computing infrastructure for industry applications and services based on Huawei Ascend processors and software. For more information about Ascend, see [Ascend Community](https://www.hiascend.com/en/).7Ascend is a full-stack AI computing infrastructure for industry applications and services based on Huawei Ascend processors and software. For more information about Ascend, see [Ascend Community](https://www.hiascend.com/en/).
8 8 
@@ -10,93 +10,92 @@ Ascend is a full-stack AI computing infrastructure for industry applications and
10 10 
11### From Binary11### From Binary
12 12 
13-Provide users with wheel package to quickly install **torch_npu**. Before installing **torch_npu**, complete the installation of **CANN** according to [Ascend Auxiliary Software](#ascend-auxiliary-software). To obtain the **CANN** installation package, refer to the [CANN Installation](https://www.hiascend.com/cann).13+Provide users with wheel package to quickly install **TorchNPU**. Before installing **TorchNPU**, complete the installation of **CANN** according to [Ascend Auxiliary Software](#ascend-auxiliary-software). To obtain the **CANN** installation package, refer to the [CANN Installation](https://www.hiascend.com/cann).
14 14 
151. **Install PyTorch**151. **Install PyTorch**
16 16 
17-Install **PyTorch** through pip.17+ Install **PyTorch** through pip.
18 18 
19-**For Aarch64:**19+ **For Aarch64:**
20 20 
21-```bash21+ ```bash
22-pip3 install torch==2.9.022+ pip3 install torch==2.9.0
23-```23+ ```
24 24 
25-**For x86:**25+ **For x86:**
26 26 
27-```bash27+ ```bash
28-pip3 install torch==2.9.0+cpu --index-url https://download.pytorch.org/whl/cpu28+ pip3 install torch==2.9.0+cpu --index-url https://download.pytorch.org/whl/cpu
29-```29+ ```
30 30 
31-2. **Install torch-npu dependencies**31+2. **Install TorchNPU dependencies**
32 32 
33-Run the following command to install dependencies.33+ Run the following command to install dependencies.
34 34 
35-```bash35+ ```bash
36-pip3 install pyyaml36+ pip3 install pyyaml
37-pip3 install setuptools37+ pip3 install setuptools
38-```38+ ```
39 39 
40-If the installation fails, use the download link or visit the [PyTorch official website](https://pytorch.org/) to download the installation package of the corresponding version.40+ If the installation fails, use the download link or visit the [PyTorch official website](https://pytorch.org/) to download the installation package of the corresponding version.
41 41 
42-| OS arch | Python version | link |42+ | OS arch | Python version | link |
43-|---------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|43+ |---------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44-| x86 | Python3.10 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp310-cp310-manylinux_2_28_x86_64.whl#sha256=bd2a257e670ede9fc01c6d76dccdc473040913b8e9328169bf177dbdc38e2484) |44+ | x86 | Python3.10 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp310-cp310-manylinux_2_28_x86_64.whl#sha256=bd2a257e670ede9fc01c6d76dccdc473040913b8e9328169bf177dbdc38e2484) |
45-| x86 | Python3.11 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp311-cp311-manylinux_2_28_x86_64.whl#sha256=add3e93ecc1eeaa6853f6a973ce60ffb3cb14ed2e80f5055e139b09385dce0a7) |45+ | x86 | Python3.11 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp311-cp311-manylinux_2_28_x86_64.whl#sha256=add3e93ecc1eeaa6853f6a973ce60ffb3cb14ed2e80f5055e139b09385dce0a7) |
46-| aarch64 | Python3.10 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp310-cp310-manylinux_2_28_aarch64.whl#sha256=b224792ea567b52c7f1ce1d789567f6920e06fd3b339fa1e1b05948845f783ad) |46+ | aarch64 | Python3.10 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp310-cp310-manylinux_2_28_aarch64.whl#sha256=b224792ea567b52c7f1ce1d789567f6920e06fd3b339fa1e1b05948845f783ad) |
47-| aarch64 | Python3.11 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp311-cp311-manylinux_2_28_aarch64.whl#sha256=da77341ccaba31762d9238b0942c165c4582a26818f3045b052b39cebdd7ad9d) |47+ | aarch64 | Python3.11 | [link](https://download.pytorch.org/whl/cpu/torch-2.9.0%2Bcpu-cp311-cp311-manylinux_2_28_aarch64.whl#sha256=da77341ccaba31762d9238b0942c165c4582a26818f3045b052b39cebdd7ad9d) |
48 48 
49-3. **Install torch-npu**49+3. **Install TorchNPU**
50 50 
51-```51+ ```bash
52-pip3 install torch-npu==2.9.0rc152+ pip3 install torch-npu==2.9.0rc1
53- 53+ ```
54-```
55 54 
56### From Source55### From Source
57 56 
58-In some special scenarios, users may need to compile **torch-npu** by themselves.Select a branch in table [Ascend Auxiliary Software](#ascend-auxiliary-software) and a Python version in table [PyTorch and Python Version Matching Table](#pytorch-and-python-version-matching-table) first. The docker image is recommended for compiling torch-npu through the following steps(It is recommended to mount the working path only and avoid the system path to reduce security risks.), the generated .whl file path is ./dist/. Note that gcc version has the following constraints if you try to compile without using docker image: we recommend to use gcc 13.3 for both ARM and X86.57+In some special scenarios, users may need to compile **TorchNPU** by themselves.Select a branch in table [Ascend Auxiliary Software](#ascend-auxiliary-software) and a Python version in table [PyTorch and Python Version Matching Table](#pytorch-and-python-version-matching-table) first. The docker image is recommended for compiling TorchNPU through the following steps(It is recommended to mount the working path only and avoid the system path to reduce security risks.), the generated .whl file path is ./dist/. Note that gcc version has the following constraints if you try to compile without using docker image: we recommend to use gcc 13.3 for both ARM and X86.
59 58 
60-1. **Clone torch-npu**59+1. **Clone TorchNPU**
61 60 
62- ```61+ ```bash
63- git clone https://gitcode.com/Ascend/pytorch.git -b v2.9.0 --depth 162+ git clone https://gitcode.com/Ascend/pytorch.git -b v2.9.0 --depth 1
64- ```63+ ```
65 64 
662. **Build Docker Image**652. **Build Docker Image**
67 66 
68- ```67+ ```bash
69- cd pytorch/ci/docker/{arch} # {arch} for X86 or ARM68+ cd pytorch/ci/docker/{arch} # {arch} for X86 or ARM
70- docker build -t manylinux-builder:v1 .69+ docker build -t manylinux-builder:v1 .
71- ```70+ ```
72 71 
733. **Enter Docker Container**723. **Enter Docker Container**
74 73 
75- ```74+ ```bash
76- docker run -it -v /{code_path}/pytorch:/home/pytorch manylinux-builder:v1 bash75+ docker run -it -v /{code_path}/pytorch:/home/pytorch manylinux-builder:v1 bash
77- # {code_path} is the torch_npu source code path76+ # {code_path} is the torch_npu source code path
78- ```77+ ```
79 78 
80-4. **Compile torch-npu**79+4. **Compile TorchNPU**
81 80 
82- Take **Python 3.10** as an example.81+ Take **Python 3.10** as an example.
83 82 
84- ```83+ ```bash
85- cd /home/pytorch84+ cd /home/pytorch
86- bash ci/build.sh --python=3.1085+ bash ci/build.sh --python=3.10
87- ```86+ ```
88 87 
89**Tips**88**Tips**
90 89 
91 If you would like to compile with new C++ ABI, then first run this command, at this point, the recommended compilation environment is same to community torch package: glibc 2.28, gcc 13.390 If you would like to compile with new C++ ABI, then first run this command, at this point, the recommended compilation environment is same to community torch package: glibc 2.28, gcc 13.3
92 91
93- ```92+ ```bash
94 export _GLIBCXX_USE_CXX11_ABI=193 export _GLIBCXX_USE_CXX11_ABI=1
95 ```94 ```
96 95 
97 Meanwhile, we support configuring -fabi-version using the following variables,require consistency with the community torch package96 Meanwhile, we support configuring -fabi-version using the following variables,require consistency with the community torch package
98 97 
99- ```98+ ```bash
100 export _ABI_VERSION=1899 export _ABI_VERSION=18
101 ```100 ```
102 101 
@@ -128,7 +127,7 @@ print(z)
128 127 
129## User Manual128## User Manual
130 129 
131-Refer to [API of Ascend Extension for PyTorch](docs/api/torch_npu_apis.md) for more detailed information.130+Refer to [API of TorchNPU](docs/api/torch_npu_apis.md) for more detailed information.
132 131 
133## PyTorch and Python Version Matching Table132## PyTorch and Python Version Matching Table
134 133 
@@ -145,7 +144,6 @@ Refer to [API of Ascend Extension for PyTorch](docs/api/torch_npu_apis.md) for m
145| PyTorch2.8.0 | Python3.9.x,Python3.10.x,Python3.11.x |144| PyTorch2.8.0 | Python3.9.x,Python3.10.x,Python3.11.x |
146| PyTorch2.9.0 | Python3.10.x,Python3.11.x |145| PyTorch2.9.0 | Python3.10.x,Python3.11.x |
147 146 
148- 
149## Ascend Auxiliary Software147## Ascend Auxiliary Software
150 148 
151**PyTorch Extension** versions follow the naming convention `{PyTorch version}-{Ascend version}`, where the former represents the PyTorch version compatible with the **PyTorch Extension**, and the latter is used to match the CANN version. The detailed matching is as follows:149**PyTorch Extension** versions follow the naming convention `{PyTorch version}-{Ascend version}`, where the former represents the PyTorch version compatible with the **PyTorch Extension**, and the latter is used to match the CANN version. The detailed matching is as follows:
@@ -210,6 +208,7 @@ Refer to [API of Ascend Extension for PyTorch](docs/api/torch_npu_apis.md) for m
210## Hardware support208## Hardware support
211 209 
212The Ascend training device includes the following models, all of which can be used as training environments for PyTorch models210The Ascend training device includes the following models, all of which can be used as training environments for PyTorch models
211+ 
213| Product series | Product model |212| Product series | Product model |
214|-----------------------|----------------------------------|213|-----------------------|----------------------------------|
215| Atlas Training series products | Atlas 800(model: 9000) |214| Atlas Training series products | Atlas 800(model: 9000) |
@@ -223,13 +222,14 @@ The Ascend training device includes the following models, all of which can be us
223| | Atlas 300T A2 |222| | Atlas 300T A2 |
224 223 
225The Ascend inference device includes the following models, all of which can be used as inference environments for large models224The Ascend inference device includes the following models, all of which can be used as inference environments for large models
225+ 
226| Product series | Product model |226| Product series | Product model |
227|-----------------------|----------------------------------|227|-----------------------|----------------------------------|
228| Atlas 800I A2 Inference product | Atlas 800I A2 |228| Atlas 800I A2 Inference product | Atlas 800I A2 |
229 229 
230## Pipeline Status230## Pipeline Status
231 231 
232-Due to the asynchronous development mechanism of upstream and downstream, incompatible modifications in upstream may cause some functions of **torch_npu** to be unavailable (only upstream and downstream development branches are involved, excluding stable branches). Therefore, we built a set of daily tasks that make it easy to detect relevant issues in time and fix them within 48 hours (under normal circumstances), providing users with the latest features and stable quality.232+Due to the asynchronous development mechanism of upstream and downstream, incompatible modifications in upstream may cause some functions of **TorchNPU** to be unavailable (only upstream and downstream development branches are involved, excluding stable branches). Therefore, we built a set of daily tasks that make it easy to detect relevant issues in time and fix them within 48 hours (under normal circumstances), providing users with the latest features and stable quality.
233 233 
234| **OS** | **CANN Version(Docker Image)** | **Upstream Branch** | **Downstream Branch** | **Period** | **Status** |234| **OS** | **CANN Version(Docker Image)** | **Upstream Branch** | **Downstream Branch** | **Period** | **Status** |
235| :---: | :---: | :---: | :---: | :---: | :---: |235| :---: | :---: | :---: | :---: | :---: | :---: |
@@ -250,9 +250,9 @@ The version branches of AscendPyTorch have the following maintenance phases:
250| Maintained | 1 year/3.5 years | Regular Release branch for 1 year, Long Term Support branch maintenance for 3.5 years. Fix major issues, do not incorporate new features, and release patch versions based on the impact of fixed bugs. |250| Maintained | 1 year/3.5 years | Regular Release branch for 1 year, Long Term Support branch maintenance for 3.5 years. Fix major issues, do not incorporate new features, and release patch versions based on the impact of fixed bugs. |
251| End Of Life (EOL) | N/A | Do not accept any modification to a branch. |251| End Of Life (EOL) | N/A | Do not accept any modification to a branch. |
252 252 
253-## PyTorch Maintenance Policies253+## TorchNPU Maintenance Policies
254 254 
255-| **PyTorch** | **Maintenance Policies** | **Status** | **Launch Date** | **Subsequent Status** | **EOL Date** |255+ | **TorchNPU** | **Maintenance Policies** | **Status** | **Launch Date** | **Subsequent Status** | **EOL Date** |
256|-------------|--------------------------|-------------|-----------------|-------------------------------------------------------------------|--------------|256|-------------|--------------------------|-------------|-----------------|-------------------------------------------------------------------|--------------|
257| 2.9.0 | Regular Release | Development | 2026/01/15 | Expected to enter maintenance status from July 15, 2026 | - | 257| 2.9.0 | Regular Release | Development | 2026/01/15 | Expected to enter maintenance status from July 15, 2026 | - |
258| 2.8.0 | Regular Release | Development | 2025/10/15 | Expected to enter maintenance status from March 15, 2026 | - | 258| 2.8.0 | Regular Release | Development | 2025/10/15 | Expected to enter maintenance status from March 15, 2026 | - |
@@ -270,7 +270,7 @@ The version branches of AscendPyTorch have the following maintenance phases:
270 270 
271## Reference Documents271## Reference Documents
272 272 
273-For more detailed information on installation guides, model migration, training/inference tutorials, and API lists, please refer to the [Ascend Extension for PyTorch on the HiAI Community](https://www.hiascend.com/software/ai-frameworks?framework=pytorch).273+For more detailed information on installation guides, model migration, training/inference tutorials, and API lists, please refer to the [Ascend for PyTorch Community](https://www.hiascend.com/software/ai-frameworks?framework=pytorch).
274 274 
275| Document Name | Document Link |275| Document Name | Document Link |
276|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|276|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
@@ -281,4 +281,4 @@ For more detailed information on installation guides, model migration, training/
281 281 
282## License282## License
283 283 
284-Ascend Extension for PyTorch has a BSD-style license, as found in the [LICENSE](LICENSE) file.284+TorchNPU has a BSD-style license, as found in the [LICENSE](LICENSE) file.
@@ -1,8 +1,8 @@
1-# Ascend Extension for PyTorch插件1+# TorchNPU
2 2 
3## 简介3## 简介
4 4 
5-本项目开发了名为**torch_npu**的**Ascend Extension for PyTorch**插件,使昇腾NPU可以适配PyTorch框架,为使用PyTorch框架的开发者提供昇腾AI处理器的超强算力。5+**TorchNPU**是为PyTorch框架开发的适配插件,旨在将昇腾NPU接入PyTorch生态,为使用PyTorch框架的开发者提供昇腾AI处理器的超强算力。
6 6 
7昇腾为基于华为昇腾处理器和软件的行业应用及服务提供全栈AI计算基础设施。您可以通过访问[昇腾社区](https://www.hiascend.com/zh/),了解关于昇腾的更多信息。7昇腾为基于华为昇腾处理器和软件的行业应用及服务提供全栈AI计算基础设施。您可以通过访问[昇腾社区](https://www.hiascend.com/zh/),了解关于昇腾的更多信息。
8 8 
@@ -26,30 +26,28 @@
26 26 
27## 版本说明27## 版本说明
28 28 
29-Ascend Extension for PyTorch的版本说明包含版本配套说明、版本兼容性说明和更新说明等,具体请参见《[Ascend Extension for PyTorch 版本说明](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/release_notes/release_notes.md)》。29+TorchNPU的版本说明包含版本配套说明、版本兼容性说明和更新说明等,具体请参见《[TorchNPU 版本说明](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/release_notes/release_notes.md)》。
30- 
31 30 
32## 环境部署31## 环境部署
33 32 
34-Ascend Extension for PyTorch插件的安装操作,具体请参见《[Ascend Extension for PyTorch 软件安装](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/installation_guide/menu_installation_guide.md)》。33+TorchNPU插件的安装操作,具体请参见《[TorchNPU 软件安装](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/installation_guide/menu_installation_guide.md)》。
35 34 
36## 快速入门35## 快速入门
37 36 
38-以CNN模型为例,介绍将其迁移至昇腾NPU上进行训练的方法,具体操作请参见《[Ascend Extension for PyTorch 快速入门](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/quick_start/quick_start.md)》。37+以CNN模型为例,介绍将其迁移至昇腾NPU上进行训练的方法,具体操作请参见《[TorchNPU 快速入门](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/quick_start/quick_start.md)》。
39 38 
40## 特性介绍39## 特性介绍
41 40 
42-Ascend Extension for PyTorch插件从内存资源优化、通信性能优化、计算性能优化、辅助报错定位等方面精心打造了一系列独特的特性,具体特性指导请参见《[PyTorch 框架特性指南](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/framework_feature_guide_pytorch/menu_framework_feature.md)》。41+TorchNPU插件从内存资源优化、通信性能优化、计算性能优化、辅助报错定位等方面精心打造了一系列独特的特性,具体特性指导请参见《[PyTorch 开发指南](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/framework_feature_guide_pytorch/menu_development_guide.md)》。
43 42 
44## API参考43## API参考
45 44 
46- 原生PyTorch API在昇腾NPU设备上的支持情况请参见《[PyTorch 原生API支持度](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/native_apis/menu_pt_native_apis.md)》。45- 原生PyTorch API在昇腾NPU设备上的支持情况请参见《[PyTorch 原生API支持度](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/native_apis/menu_pt_native_apis.md)》。
47-- Ascend Extension for PyTorch插件提供了部分自定义API接口,具体使用请参见《[Ascend Extension for PyTorch自定义API](https://gitcode.com/Ascend/op-plugin/blob/master/docs/zh/custom_APIs/menu_Pytorch_API.md)》。46+- TorchNPU插件提供了部分自定义API接口,具体使用请参见《[TorchNPU自定义API](https://gitcode.com/Ascend/op-plugin/blob/master/docs/zh/custom_APIs/menu_Pytorch_API.md)》。
48 47 
49## 分支维护策略48## 分支维护策略
50 49 
51-Ascend Extension for PyTorch版本分支的维护阶段如下:50+TorchNPU版本分支的维护阶段如下:
52- 
53 51 
54| **状态** | **时间** | **说明** |52| **状态** | **时间** | **说明** |
55| ------------------- | -------- | ------------------------------------------------ |53| ------------------- | -------- | ------------------------------------------------ |
@@ -77,17 +75,21 @@ Ascend Extension for PyTorch版本分支的维护阶段如下:
77| 1.5.0 | 长期支持 | EOL | 2021/7/29 | | 2022/7/29 |75| 1.5.0 | 长期支持 | EOL | 2021/7/29 | | 2022/7/29 |
78 76 
79## 贡献指导77## 贡献指导
80-介绍如何向Ascend Extension for PyTorch插件库贡献代码,具体请参见[Ascend Extension for PyTorch插件 贡献指南](CONTRIBUTING.md)。78+ 
79+介绍如何向TorchNPU插件库贡献代码,具体请参见[TorchNPU插件 贡献指南](CONTRIBUTING.md)。
81 80 
82## 联系我们81## 联系我们
83 82 
84欢迎大家为社区做贡献。如果有任何疑问或建议,请提交[GitCode Issues](https://gitcode.com/Ascend/pytorch/issues),我们会尽快回复。感谢您的支持。83欢迎大家为社区做贡献。如果有任何疑问或建议,请提交[GitCode Issues](https://gitcode.com/Ascend/pytorch/issues),我们会尽快回复。感谢您的支持。
85 84 
86## 安全声明85## 安全声明
87-Ascend Extension for PyTorch的系统安全加固、运行用户建议和文件权限控制等内容,请参见[Ascend Extension for PyTorch插件 安全声明](SECURITYNOTE.md)。86+ 
87+TorchNPU的系统安全加固、运行用户建议和文件权限控制等内容,请参见[TorchNPU插件 安全声明](SECURITYNOTE.md)。
88 88 
89## 免责声明89## 免责声明
90-致Ascend Extension for PyTorch插件使用者90+ 
91+致TorchNPU插件使用者
92+ 
91- 本插件仅供调试和开发使用,使用者需自行承担使用风险,并理解以下内容:93- 本插件仅供调试和开发使用,使用者需自行承担使用风险,并理解以下内容:
92 - 数据处理及删除:用户在使用本插件过程中产生的数据属于用户责任范畴。建议用户在使用完毕后及时删除相关数据,以防信息泄露。94 - 数据处理及删除:用户在使用本插件过程中产生的数据属于用户责任范畴。建议用户在使用完毕后及时删除相关数据,以防信息泄露。
93 - 数据保密与传播:使用者了解并同意不得将通过本插件产生的数据随意外发或传播。对于由此产生的信息泄露、数据泄露或其他不良后果,本插件及其开发者概不负责。95 - 数据保密与传播:使用者了解并同意不得将通过本插件产生的数据随意外发或传播。对于由此产生的信息泄露、数据泄露或其他不良后果,本插件及其开发者概不负责。
@@ -97,8 +99,8 @@ Ascend Extension for PyTorch的系统安全加固、运行用户建议和文件
97 99 
98## License100## License
99 101 
100-Ascend Extension for PyTorch插件的使用许可证,具体请参见[LICENSE](LICENSE)文件。102+TorchNPU插件的使用许可证,具体请参见[LICENSE](LICENSE)文件。
101 103 
102## 致谢104## 致谢
103 105 
104-感谢来自社区的每一个PR,欢迎贡献Ascend Extension for PyTorch插件!106+感谢来自社区的每一个PR,欢迎贡献TorchNPU插件!
@@ -1,4 +1,4 @@
1-# Ascend Extension for PyTorch插件 安全声明1+# TorchNPU插件 安全声明
2 2 
3## 系统安全加固3## 系统安全加固
4 4 
@@ -8,13 +8,13 @@
8 8 
9## 运行用户建议9## 运行用户建议
10 10 
11-出于安全性及权限最小化角度考虑,不建议使用root等管理员类型账户使用torch_npu11+出于安全性及权限最小化角度考虑,不建议使用root等管理员类型账户使用TorchNPU
12 12 
13## 文件权限控制13## 文件权限控制
14 14 
151. 建议用户对训练所需文件、训练过程中保存的文件、用户个人的隐私数据、商业资产等敏感文件做好权限控制等安全措施,例如多用户共享数据集场景下的数据集文件写权限控制、profiler等场景产生数据文件权限控制等,设定的权限建议参见[文件权限参考](#文件权限参考)进行设置。151. 建议用户对训练所需文件、训练过程中保存的文件、用户个人的隐私数据、商业资产等敏感文件做好权限控制等安全措施,例如多用户共享数据集场景下的数据集文件写权限控制、profiler等场景产生数据文件权限控制等,设定的权限建议参见[文件权限参考](#文件权限参考)进行设置。
16 16 
17-2. torch_npu中profiler工具会生成性能记录文件,生成的文件权限为640,文件夹权限为750,用户可根据需要自行对生成后的相关文件进行权限控制。17+2. TorchNPU中profiler工具会生成性能记录文件,生成的文件权限为640,文件夹权限为750,用户可根据需要自行对生成后的相关文件进行权限控制。
18 18 
193. 用户安装和使用过程需要做好权限控制,建议参见[文件权限参考](#文件权限参考)进行设置。如需要保存安装/卸载日志,可在安装/卸载命令后面加上参数--log FILE, 注意对FILE文件及目录做好权限管控。193. 用户安装和使用过程需要做好权限控制,建议参见[文件权限参考](#文件权限参考)进行设置。如需要保存安装/卸载日志,可在安装/卸载命令后面加上参数--log FILE, 注意对FILE文件及目录做好权限管控。
20 20 
@@ -44,30 +44,30 @@
44 44 
45## 调试工具声明45## 调试工具声明
46 46 
47-torch_npu内集成性能分析工具profiler:47+TorchNPU内集成性能分析工具profiler:
48 48 
49 - 集成原因:对标PyTorch原生支持能力,提供NPU PyTorch框架开发性能分析能力,加速性能分析调试过程。49 - 集成原因:对标PyTorch原生支持能力,提供NPU PyTorch框架开发性能分析能力,加速性能分析调试过程。
50- - 使用场景:默认不采集,如用户需要进行性能分析时,可在模型训练脚本中添加Ascend Extension for PyTorch Profiler接口,执行训练的同时采集性能数据,完成训练后直接输出可视化的性能数据文件。50+ - 使用场景:默认不采集,如用户需要进行性能分析时,可在模型训练脚本中添加TorchNPU Profiler接口,执行训练的同时采集性能数据,完成训练后直接输出可视化的性能数据文件。
51 - 风险提示:使用该功能会在本地生成性能数据,用户需加强对相关性能数据的保护,请在需要模型性能分析时使用,分析完成后及时关闭。Profiler工具具体细节请参考[《PyTorch 性能分析工具介绍》](https://www.hiascend.com/document/detail/zh/Pytorch/710/ptmoddevg/trainingmigrguide/performance_tuning_0014.html)。51 - 风险提示:使用该功能会在本地生成性能数据,用户需加强对相关性能数据的保护,请在需要模型性能分析时使用,分析完成后及时关闭。Profiler工具具体细节请参考[《PyTorch 性能分析工具介绍》](https://www.hiascend.com/document/detail/zh/Pytorch/710/ptmoddevg/trainingmigrguide/performance_tuning_0014.html)。
52 52 
53## 数据安全声明53## 数据安全声明
54 54 
551. PyTorch使用过程中需要加载和保存数据,部分接口使用风险模块pickle,可能存在数据风险,如torch.load、torch.jit.load、torch.distributed.scatter_object_list等接口,可参考[torch.load](https://pytorch.org/docs/main/generated/torch.load.html#torch.load)、[collective-functions](https://pytorch.org/docs/main/distributed.html#collective-functions)了解具体风险。551. PyTorch使用过程中需要加载和保存数据,部分接口使用风险模块pickle,可能存在数据风险,如torch.load、torch.jit.load、torch.distributed.scatter_object_list等接口,可参考[torch.load](https://pytorch.org/docs/main/generated/torch.load.html#torch.load)、[collective-functions](https://pytorch.org/docs/main/distributed.html#collective-functions)了解具体风险。
56-2. Ascend Extension for PyTorch依赖CANN的基础能力实现AOE性能调优、算子dump、日志记录等功能,用户需要关注上述功能生成文件的权限控制,加强对相关数据的保护。56+2. TorchNPU依赖CANN的基础能力实现AOE性能调优、算子dump、日志记录等功能,用户需要关注上述功能生成文件的权限控制,加强对相关数据的保护。
57 57 
58## 构建安全声明58## 构建安全声明
59 59 
60-torch_npu支持源码编译安装,在编译时会下载依赖第三方库并执行构建shell脚本,在编译过程中会产生临时程序文件和编译目录。用户可根据需要自行对源代码目录内的文件进行权限管控降低安全风险。60+TorchNPU支持源码编译安装,在编译时会下载依赖第三方库并执行构建shell脚本,在编译过程中会产生临时程序文件和编译目录。用户可根据需要自行对源代码目录内的文件进行权限管控降低安全风险。
61 61 
62## 运行安全声明62## 运行安全声明
63 63 
641. 建议用户结合运行环境资源状况编写对应训练脚本。若训练脚本与资源状况不匹配,如数据集加载内存大小超出内存容量限制、训练脚本在本地生成数据超过磁盘空间大小等情况,可能引发错误并导致进程意外退出。641. 建议用户结合运行环境资源状况编写对应训练脚本。若训练脚本与资源状况不匹配,如数据集加载内存大小超出内存容量限制、训练脚本在本地生成数据超过磁盘空间大小等情况,可能引发错误并导致进程意外退出。
65-2. PyTorch和torch_npu在运行异常时会退出进程并打印报错信息,属于正常现象。建议用户根据报错提示定位具体错误原因,包括设定算子同步执行、查看CANN日志、解析生成的Core Dump文件等方式。65+2. PyTorch和TorchNPU在运行异常时会退出进程并打印报错信息,属于正常现象。建议用户根据报错提示定位具体错误原因,包括设定算子同步执行、查看CANN日志、解析生成的Core Dump文件等方式。
66-3. PyTorch和torch_npu的分布式特性仅适用于内部通信。出于性能考虑,这些分布式特性不包含任何授权协议,并且会发送未加密的消息。关于PyTorch分布式特性的详细说明及安全注意事项,可参考[using-distributed-features](https://github.com/pytorch/pytorch/security#using-distributed-features)。66+3. PyTorch和TorchNPU的分布式特性仅适用于内部通信。出于性能考虑,这些分布式特性不包含任何授权协议,并且会发送未加密的消息。关于PyTorch分布式特性的详细说明及安全注意事项,可参考[using-distributed-features](https://github.com/pytorch/pytorch/security#using-distributed-features)。
67 67 
68## 公网地址声明68## 公网地址声明
69 69 
70-torch_npu的配置文件和脚本中存在[公网地址](#公网地址)70+TorchNPU的配置文件和脚本中存在[公网地址](#公网地址)
71 71 
72### 公网地址72### 公网地址
73 73 
@@ -91,8 +91,8 @@ torch_npu支持源码编译安装,在编译时会下载依赖第三方库并
91| 自研 | 不涉及 | .github\workflows\\_build-and-test.yml | https://mirrors.huaweicloud.com/repository/pypi/simple | workflow配置文件,用于配置pip源 |91| 自研 | 不涉及 | .github\workflows\\_build-and-test.yml | https://mirrors.huaweicloud.com/repository/pypi/simple | workflow配置文件,用于配置pip源 |
92| 自研 | 不涉及 | setup.cfg | https://gitcode.com/ascend/pytorch | 用于打包whl的url入参 |92| 自研 | 不涉及 | setup.cfg | https://gitcode.com/ascend/pytorch | 用于打包whl的url入参 |
93| 自研 | 不涉及 | setup.cfg | https://gitcode.com/ascend/pytorch/tags | 用于打包whl的download_url入参 |93| 自研 | 不涉及 | setup.cfg | https://gitcode.com/ascend/pytorch/tags | 用于打包whl的download_url入参 |
94-| 自研 | 不涉及 | third_party\op-plugin\ci\build.sh | https://gitcode.com/ascend/pytorch.git | 编译脚本根据torch_npu仓库地址拉取代码进行编译 |94+| 自研 | 不涉及 | third_party\op-plugin\ci\build.sh | https://gitcode.com/ascend/pytorch.git | 编译脚本根据TorchNPU仓库地址拉取代码进行编译 |
95-| 自研 | 不涉及 | third_party\op-plugin\ci\exec_ut.sh | https://gitcode.com/ascend/pytorch.git | UT脚本根据torch_npu仓库地址拉取代码进行UT测试 |95+| 自研 | 不涉及 | third_party\op-plugin\ci\exec_ut.sh | https://gitcode.com/ascend/pytorch.git | UT脚本根据TorchNPU仓库地址拉取代码进行UT测试 |
96| 开源引入 | https://github.com/pytorch/pytorch/blob/v2.8.0/test/nn/test_convolution.py <br> https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_mps.py <br> https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_serialization.py | test\url.ini | https://download.pytorch.org/test_data/legacy_conv2d.pt | 用于test脚本下载相关pt文件 |96| 开源引入 | https://github.com/pytorch/pytorch/blob/v2.8.0/test/nn/test_convolution.py <br> https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_mps.py <br> https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_serialization.py | test\url.ini | https://download.pytorch.org/test_data/legacy_conv2d.pt | 用于test脚本下载相关pt文件 |
97| 开源引入 | https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_serialization.py | test\url.ini | https://download.pytorch.org/test_data/legacy_serialized.pt | 用于test脚本下载相关pt文件 |97| 开源引入 | https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_serialization.py | test\url.ini | https://download.pytorch.org/test_data/legacy_serialized.pt | 用于test脚本下载相关pt文件 |
98| 开源引入 | https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_serialization.py | test\url.ini | https://download.pytorch.org/test_data/gpu_tensors.pt | 用于test脚本下载相关pt文件 |98| 开源引入 | https://github.com/pytorch/pytorch/blob/v2.8.0/test/test_serialization.py | test\url.ini | https://download.pytorch.org/test_data/gpu_tensors.pt | 用于test脚本下载相关pt文件 |
@@ -106,11 +106,11 @@ torch_npu支持源码编译安装,在编译时会下载依赖第三方库并
106 106 
107## 公开接口声明107## 公开接口声明
108 108 
109-Ascend Extension for PyTorch是PyTorch适配插件,支持用户使用PyTorch在昇腾设备上进行训练和推理。Ascend Extension for PyTorch适配后支持用户使用PyTorch原生接口。除了原生PyTorch接口外,Ascend Extension for PyTorch提供了部分自定义接口,包括自定义算子、亲和库和其他接口,支持PyTorch接口和自定义接口连接,具体可参见[《Ascend Extension for PyTorch自定义API参考》](https://www.hiascend.com/document/detail/zh/Pytorch/710/apiref/torchnpuCustomsapi/context/%E6%A6%82%E8%BF%B0.md)以及[《PyTorch原生接口清单》](https://www.hiascend.com/document/detail/zh/Pytorch/710/apiref/PyTorchNativeapi/ptaoplist_000003.html)。109+TorchNPU是PyTorch适配插件,支持用户使用PyTorch在昇腾设备上进行训练和推理。TorchNPU适配后支持用户使用PyTorch原生接口。除了原生PyTorch接口外,TorchNPU提供了部分自定义接口,包括自定义算子、亲和库和其他接口,支持PyTorch接口和自定义接口连接,具体可参见[《TorchNPU自定义API参考》](https://www.hiascend.com/document/detail/zh/Pytorch/710/apiref/torchnpuCustomsapi/context/%E6%A6%82%E8%BF%B0.md)以及[《PyTorch原生接口清单》](https://www.hiascend.com/document/detail/zh/Pytorch/710/apiref/PyTorchNativeapi/ptaoplist_000003.html)。
110 110 
111-参考[PyTorch社区公开接口规范](https://github.com/pytorch/pytorch/wiki/Public-API-definition-and-documentation),Ascend Extension for PyTorch提供了对外的自定义接口。如果一个函数看起来符合公开接口的标准且在文档中有展示,则该接口是公开接口。否则,使用该功能前可以在社区询问该功能是否确实是公开的或意外暴露的接口,因为这些未暴露接口将来可能会被修改或者删除。111+参考[PyTorch社区公开接口规范](https://github.com/pytorch/pytorch/wiki/Public-API-definition-and-documentation),TorchNPU提供了对外的自定义接口。如果一个函数看起来符合公开接口的标准且在文档中有展示,则该接口是公开接口。否则,使用该功能前可以在社区询问该功能是否确实是公开的或意外暴露的接口,因为这些未暴露接口将来可能会被修改或者删除。
112 112 
113-Ascend Extension for PyTorch项目采用C++和Python联合开发,当前除Libtorch场景外正式接口只提供Python接口,在torch_npu的二进制包中动态库不直接提供服务,暴露的接口为内部使用,不建议用户使用。113+TorchNPU项目采用C++和Python联合开发,当前除Libtorch场景外正式接口只提供Python接口,在TorchNPU的二进制包中动态库不直接提供服务,暴露的接口为内部使用,不建议用户使用。
114 114 
115## 通信安全加固115## 通信安全加固
116 116 
@@ -210,7 +210,7 @@ PyTorch分布式训练服务需要在设备间进行通信,通信开启的端
210 210 
211## 通信矩阵211## 通信矩阵
212 212 
213-PyTorch提供分布式训练能力,支持在单机和多机场景下进行训练,需要进行网络通信。其中PyTorch需要使用TCP进行通信,torch_npu使用CANN中HCCL在NPU设备间通信,通信端口见[通信矩阵信息](#通信矩阵信息)。用户需要注意并保障节点间通信网络安全,可以使用iptables等方式消减安全风险,可参考[通信安全加固](#通信安全加固)进行网络安全加固。213+PyTorch提供分布式训练能力,支持在单机和多机场景下进行训练,需要进行网络通信。其中PyTorch需要使用TCP进行通信,TorchNPU使用CANN中HCCL在NPU设备间通信,通信端口见[通信矩阵信息](#通信矩阵信息)。用户需要注意并保障节点间通信网络安全,可以使用iptables等方式消减安全风险,可参考[通信安全加固](#通信安全加固)进行网络安全加固。
214 214 
215### 通信矩阵信息215### 通信矩阵信息
216 216 
@@ -230,15 +230,15 @@ PyTorch提供分布式训练能力,支持在单机和多机场景下进行训
230| 所属平面 | 不涉及 | 不涉及 |230| 所属平面 | 不涉及 | 不涉及 |
231| 版本 | 所有版本 | 所有版本 |231| 版本 | 所有版本 | 所有版本 |
232| 特殊场景 | 无 | 无 |232| 特殊场景 | 无 | 无 |
233-| 备注 | 该通信过程由开源软件PyTorch控制,配置为PyTorch原生设置,可参考[PyTorch文档](https://pytorch.org/docs/stable/distributed.html#launch-utility)。源端口由操作系统自动分配,分配范围由操作系统的配置决定,例如ubuntu:采用/proc/sys/net/ipv4/ipv4_local_port_range文件指定,可通过cat /proc/sys/net/ipv4/ipv4_local_port_range或sysctl net.ipv4.ip_local_port_range查看 | 该通信过程由CANN中HCCL组件控制,torch_npu不进行控制,端口范围可参考[《环境变量参考》](https://www.hiascend.com/document/detail/zh/canncommercial/82RC1/maintenref/envvar/envref_07_0001.html)的“执行相关 > 集合通信 >HCCL_IF_BASE_PORT” |233+| 备注 | 该通信过程由开源软件PyTorch控制,配置为PyTorch原生设置,可参考[PyTorch文档](https://pytorch.org/docs/stable/distributed.html#launch-utility)。源端口由操作系统自动分配,分配范围由操作系统的配置决定,例如ubuntu:采用/proc/sys/net/ipv4/ipv4_local_port_range文件指定,可通过cat /proc/sys/net/ipv4/ipv4_local_port_range或sysctl net.ipv4.ip_local_port_range查看 | 该通信过程由CANN中HCCL组件控制,TorchNPU不进行控制,端口范围可参考[《环境变量参考》](https://www.hiascend.com/document/detail/zh/canncommercial/82RC1/maintenref/envvar/envref_07_0001.html)的“执行相关 > 集合通信 >HCCL_IF_BASE_PORT” |
234 234 
235## 漏洞机制说明235## 漏洞机制说明
236 236 
237-Ascend Extension for PyTorch 社区非常重视社区版本的安全性,专门设置了漏洞管理专员负责处理漏洞相关的事务,同时为了构建更安全的AI全流程工具链,我们也欢迎您一起参与。237+Ascend for PyTorch 社区非常重视社区版本的安全性,专门设置了漏洞管理专员负责处理漏洞相关的事务,同时为了构建更安全的AI全流程工具链,我们也欢迎您一起参与。
238 238 
239### 漏洞处理流程239### 漏洞处理流程
240 240 
241-对于每一个安全漏洞,Ascend Extension for PyTorch 社区会安排人员进行跟踪和处理,漏洞处理的端到端流程如下图所示。241+对于每一个安全漏洞,Ascend for PyTorch 社区会安排人员进行跟踪和处理,漏洞处理的端到端流程如下图所示。
242 242 
243![漏洞处理流程](./figures/cve.png)243![漏洞处理流程](./figures/cve.png)
244 244 
@@ -246,22 +246,22 @@ Ascend Extension for PyTorch 社区非常重视社区版本的安全性,专门
246 246 
247### 漏洞上报247### 漏洞上报
248 248 
249-您可以通过提交issue的方式联系 Ascend Extension for PyTorch 社区团队,我们将会第一时间安排安全漏洞专项人员向您联系。249+您可以通过提交issue的方式联系 Ascend for PyTorch 社区团队,我们将会第一时间安排安全漏洞专项人员向您联系。
250注意,为了确保安全性,请不要在issue中描述涉及安全隐私的具体信息。250注意,为了确保安全性,请不要在issue中描述涉及安全隐私的具体信息。
251 251 
252#### 上报响应252#### 上报响应
253 253 
254-1. Ascend Extension for PyTorch 社区会在3个工作日内确认、分析、上报安全漏洞问题,同时启动安全处理流程。254+1. Ascend for PyTorch 社区会在3个工作日内确认、分析、上报安全漏洞问题,同时启动安全处理流程。
255-2. Ascend Extension for PyTorch 安全团队在确认安全漏洞问题后,会对问题进行分发和跟进。255+2. TorchNPU 安全团队在确认安全漏洞问题后,会对问题进行分发和跟进。
2563. 在安全漏洞问题从分类、确定、修复和发布的过程中,我们会及时更新报告。2563. 在安全漏洞问题从分类、确定、修复和发布的过程中,我们会及时更新报告。
257 257 
258### 漏洞评估258### 漏洞评估
259 259 
260-业界普遍使用 CVSS 标准评估漏洞的严重性,Ascend Extension for PyTorch 在使用 CVSS v3.1 进行漏洞评估时,需要设定漏洞攻击场景,基于在该攻击场景下的实际影响进行评估。漏洞严重等级评估是指针对漏洞利用难易程度,以及利用后对机密性、完整性、可用性的影响进行评估,并生成一个评分值。260+业界普遍使用 CVSS 标准评估漏洞的严重性,TorchNPU 在使用 CVSS v3.1 进行漏洞评估时,需要设定漏洞攻击场景,基于在该攻击场景下的实际影响进行评估。漏洞严重等级评估是指针对漏洞利用难易程度,以及利用后对机密性、完整性、可用性的影响进行评估,并生成一个评分值。
261 261 
262#### 漏洞评估标准262#### 漏洞评估标准
263 263 
264-Ascend Extension for PyTorch 通过以下向量评估一个漏洞的严重等级:264+TorchNPU 通过以下向量评估一个漏洞的严重等级:
265 265 
266- 攻击向量(AV):表示攻击的“远程性”以及如何利用此漏洞。266- 攻击向量(AV):表示攻击的“远程性”以及如何利用此漏洞。
267- 攻击复杂性(AC):讲述攻击执行的难度以及成功进行攻击需要哪些因素。267- 攻击复杂性(AC):讲述攻击执行的难度以及成功进行攻击需要哪些因素。
@@ -304,8 +304,8 @@ Ascend Extension for PyTorch 通过以下向量评估一个漏洞的严重等级
304 304 
305### 漏洞披露305### 漏洞披露
306 306 
307-安全漏洞修复后 Ascend Extension for PyTorch 社区会发布安全公告 (SA)以及安全说明(SN) ,安全公告内容包括该漏洞的技术细节、类型、上报人、CVE ID 以及受到该漏洞影响的版本和修复版本等信息。307+安全漏洞修复后 Ascend for PyTorch 社区会发布安全公告 (SA)以及安全说明(SN) ,安全公告内容包括该漏洞的技术细节、类型、上报人、CVE ID 以及受到该漏洞影响的版本和修复版本等信息。
308-为了保护 Ascend Extension for PyTorch 用户的安全,在进行调查、修复和发布安全公告之前, Ascend Extension for PyTorch 社区不会公开披露、讨论或确认 Ascend Extension for PyTorch 产品的安全问题。308+为了保护 TorchNPU 用户的安全,在进行调查、修复和发布安全公告之前, Ascend for PyTorch 社区不会公开披露、讨论或确认 TorchNPU 产品的安全问题。
309 309 
310### 附录310### 附录
311 311 
@@ -2,9 +2,9 @@
2 2 
3This folder hosts the `Dockerfile` to build docker images with various platforms.3This folder hosts the `Dockerfile` to build docker images with various platforms.
4 4 
5-## Build torch_npu from Docker container5+## Build TorchNPU from Docker container
6 6 
7-**Clone torch-npu**7+**Clone TorchNPU**
8 8 
9```Shell9```Shell
10git clone https://gitcode.com/ascend/pytorch.git --depth 110git clone https://gitcode.com/ascend/pytorch.git --depth 1
@@ -31,7 +31,7 @@ docker run -it -v /{code_path}/pytorch:/home/pytorch manylinux-builder:v1 bash
31# {code_path} is the torch_npu source code path31# {code_path} is the torch_npu source code path
32```32```
33 33 
34-**Compile torch_npu**34+**Compile TorchNPU**
35 35 
36Take Python 3.10 as an example36Take Python 3.10 as an example
37 37 
@@ -12,7 +12,7 @@ base manylinux + Python 软链接 + pip 源 + 基础系统包(curl/wget
12 └── dev builder + CANN(Toolkit + Ops + NNAL 可选) ← 运行环境12 └── dev builder + CANN(Toolkit + Ops + NNAL 可选) ← 运行环境
13```13```
14 14 
15-- **builder**(默认):用于编译 torch_npu wheel,不含 CANN15+- **builder**(默认):用于编译 TorchNPU wheel,不含 CANN
16- **dev**:基于 builder,叠加 CANN 运行环境;继承全部编译工具链,可在容器内直接重新编译16- **dev**:基于 builder,叠加 CANN 运行环境;继承全部编译工具链,可在容器内直接重新编译
17 17 
18> Driver 不包含在镜像中,用户需在宿主机自行安装。镜像仅提供 CANN 编译环境,运行时需宿主机已安装匹配的 NPU 驱动。18> Driver 不包含在镜像中,用户需在宿主机自行安装。镜像仅提供 CANN 编译环境,运行时需宿主机已安装匹配的 NPU 驱动。
@@ -2,9 +2,9 @@
2 2 
3## 环境约束3## 环境约束
4 4 
5-1)**torch_npu 和 CANN 环境**5+1)**TorchNPU 和 CANN 环境**
6 6 
7-本样例依赖 torch_npu 运行环境,推荐 torch_npu 26.1.0 及配套 CANN 9.1.0 版本。7+本样例依赖 TorchNPU 运行环境,推荐 TorchNPU 26.1.0 及配套 CANN 9.1.0 版本。
8 8 
92)**triton-ascend >= 3.2.2**92)**triton-ascend >= 3.2.2**
10 10 
@@ -1,29 +1,38 @@
1-## 简介1+# 简介
2-test目录为PTA相关的测试用例。2+ 
3+test目录为TorchNPU相关的测试用例。
4+ 
3## 安装依赖5## 安装依赖
4 6 
5`pip3 install -r requirements.txt`7`pip3 install -r requirements.txt`
6 8 
7## 补全脚本9## 补全脚本
10+ 
8该操作需要联网11该操作需要联网
9-```12+ 
13+```bash
10cd test14cd test
11bash get_synchronized_files.sh15bash get_synchronized_files.sh
12```16```
17+ 
13通过以上操作,会自动补齐testfiles_synchronized.txt和testfolder_synchronized.txt中的文件或文件夹。18通过以上操作,会自动补齐testfiles_synchronized.txt和testfolder_synchronized.txt中的文件或文件夹。
19+ 
14## 跳过失败用例20## 跳过失败用例
21+ 
15`export DISABLED_TESTS_FILE=./unsupported_test_cases/.pytorch-disabled-tests.json`22`export DISABLED_TESTS_FILE=./unsupported_test_cases/.pytorch-disabled-tests.json`
16 23 
17如果不是在test目录下运行测试用例,需要传入.pytorch-disabled-tests.json的绝对路径。24如果不是在test目录下运行测试用例,需要传入.pytorch-disabled-tests.json的绝对路径。
25+ 
18## 执行方式26## 执行方式
27+ 
19### 执行单个测试脚本28### 执行单个测试脚本
29+ 
20运行以test开头的文件。以test_autocast.py为例:30运行以test开头的文件。以test_autocast.py为例:
21 31 
22方式一:32方式一:
23 33 
24`python test_autocast.py`34`python test_autocast.py`
25 35 
26- 
27方式二:36方式二:
28 37 
29`python run_test.py -i test_autocast`38`python run_test.py -i test_autocast`
@@ -31,6 +40,7 @@ bash get_synchronized_files.sh
31说明:部分以test开头的脚本不是直接运行的脚本,比如jit中的测试脚本是通过test_jit.py执行的。40说明:部分以test开头的脚本不是直接运行的脚本,比如jit中的测试脚本是通过test_jit.py执行的。
32 41 
33### 执行具体的用例42### 执行具体的用例
43+ 
34通过-k参数传入具体的用例名。以test_autocast.py为例:44通过-k参数传入具体的用例名。以test_autocast.py为例:
35 45 
36方式一:46方式一:
@@ -42,24 +52,26 @@ bash get_synchronized_files.sh
42`python run_test.py -v -i test_autocast -- -k test_autocast_nn_fp32`52`python run_test.py -v -i test_autocast -- -k test_autocast_nn_fp32`
43 53 
44### 执行全量UT的方式54### 执行全量UT的方式
45-```55+ 
56+```bash
46# 进入到test目录的上一级57# 进入到test目录的上一级
47cd ../58cd ../
48```59```
49 60 
50运行非分布式全量用例:61运行非分布式全量用例:
51 62 
52-```63+```bash
53python ci/access_control_test.py --all64python ci/access_control_test.py --all
54```65```
55 66 
56运行分布式全量用例:67运行分布式全量用例:
57 68 
58-```69+```bash
59python ci/access_control_test.py --distributed70python ci/access_control_test.py --distributed
60```71```
61 72 
62## FAQ73## FAQ
74+ 
631. 报错:"dictionary changed size during interation". 751. 报错:"dictionary changed size during interation".
64 76 
65 如果python 环境是3.8.1版本,报错在unitest/case.py中,可考虑是sys.modules被修改导致的。第三方包可能会有对sys.modules的修改,比如beartype。 77 如果python 环境是3.8.1版本,报错在unitest/case.py中,可考虑是sys.modules被修改导致的。第三方包可能会有对sys.modules的修改,比如beartype。
@@ -1,41 +1,50 @@
1# 简介1# 简介
2+ 
2Torch 的 Inductor-MLIR 编译优化是基于 torch.compile 接口、融合 MLIR(Multi-Level Intermediate Representation)技术的新一代后端优化方案。Inductor-MLIR 是 PyTorch 编译体系对原生 Inductor 后端的扩展升级,在保留 torch.compile 动态图捕获 + 静态图优化 + 高效代码生成的核心逻辑的基础上,借助 MLIR 的多层级、跨架构编译能力,适配多类硬件架构的深度优化需求,显著提升不同算力平台下模型训练与推理的编译灵活性和性能上限。3Torch 的 Inductor-MLIR 编译优化是基于 torch.compile 接口、融合 MLIR(Multi-Level Intermediate Representation)技术的新一代后端优化方案。Inductor-MLIR 是 PyTorch 编译体系对原生 Inductor 后端的扩展升级,在保留 torch.compile 动态图捕获 + 静态图优化 + 高效代码生成的核心逻辑的基础上,借助 MLIR 的多层级、跨架构编译能力,适配多类硬件架构的深度优化需求,显著提升不同算力平台下模型训练与推理的编译灵活性和性能上限。
4+ 
3Inductor-MLIR 包含如下核心组件:5Inductor-MLIR 包含如下核心组件:
4-|组件| 定位 |作用|6+ 
5-|-|-|-|7+| 组件 | 定位 | 作用 |
6-|Dynamo |前端编译器(代码转换器) |延续 TorchDynamo 的核心能力,JIT 将用户的 eager(动态图)代码编译为 FX Graph,完成动态图到静态中间表示的捕获,为 Inductor-MLIR 后端提供统一的输入,保证前端编译逻辑的一致性|8+| --- | --- | --- |
7-|Inductor-MLIR |核心编译器(多层级 IR 优化器) |作为 Inductor-MLIR 的核心,将 FX Graph 转换MLIR 多层级中间表示(IR);通过跨层级优化策略(如算子拆分与融合、数据类型优化、计算图化简)兼顾编译灵活性与优化深度,适配不同硬件的编译性|9+| Dynamo | 前端编译器(代码转换器) | 延续 TorchDynamo 的核心能力JIT 用户的 eager(动态图)代码编译FX Graph,完成动态图到静态中间表示的捕获为 Inductor-MLIR 后端提供统一输入,保证前端编译逻辑的一致 |
8-|MLIR CodeGen |代码生成器(硬件感知代码生成器) |接收优化后的 MLIR IR,针对目标硬件生成专属能底层代码|10+| Inductor-MLIR | 核心编译器(多层级 IR 优化器) | 作为 Inductor-MLIR 核心层,将 FX Graph 转换为 MLIR 多层级中间表示(IR);通过跨层级的优化策略(如算子拆分与融合、数据类型优化、计算图化简)兼顾编译灵活性与优化深度,适配不同硬件的编译特 |
11+| MLIR CodeGen | 代码生成器(硬件感知代码生成器) | 接收优化后的 MLIR IR,针对目标硬件生成专属的高性能底层代码 |
9 12 
10# 使用指导13# 使用指导
14+ 
11## 环境配置15## 环境配置
12 16 
13-* torch_npu:2.6.0或之后版本的torch_npu支持torch.compile接口;17+* TorchNPU:2.6.0或之后版本的TorchNPU支持torch.compile接口;
14* torch-mlir:Inductor后端的MLIR模式依赖torch-mlir。用户可以从[LINK](https://repo.oepkgs.net/ascend/pytorch/vllm/torch/)获取torch-mlir软件包;18* torch-mlir:Inductor后端的MLIR模式依赖torch-mlir。用户可以从[LINK](https://repo.oepkgs.net/ascend/pytorch/vllm/torch/)获取torch-mlir软件包;
15 19 
16## 使用方式20## 使用方式
21+ 
17MLIR使用方式有三种, 任选一种即可调用22MLIR使用方式有三种, 任选一种即可调用
18 23 
191. config导入(torch.compile之前导入)241. config导入(torch.compile之前导入)
20-```25+ 
21-torch._inductor.config.npu_backend == "mlir"26+ ```python
22-torch.compile(op_calc)(x)27+ torch._inductor.config.npu_backend == "mlir"
23-```28+ torch.compile(op_calc)(x)
29+ ```
24 30 
252. 环境变量导入(npu初始化之前导入)312. 环境变量导入(npu初始化之前导入)
26 32 
27-```33+ ```python
28-import os34+ import os
29-os.environ['TORCHINDUCTOR_NPU_BACKEND'] = 'mlir'35+ os.environ['TORCHINDUCTOR_NPU_BACKEND'] = 'mlir'
30-torch.compile(op_calc)(x)36+ torch.compile(op_calc)(x)
31-```37+ ```
38+ 
323. options导入393. options导入
33-```40+ 
34-torch.compile(op_calc,options={"npu_backend":"mlir"})(x)41+ ```python
35-```42+ torch.compile(op_calc,options={"npu_backend":"mlir"})(x)
43+ ```
44+ 
36## 示例45## 示例
37 46 
38-```47+```python
39import os48import os
40# 环境变量调用需要在torch_npu初始化之前49# 环境变量调用需要在torch_npu初始化之前
41os.environ['TORCHINDUCTOR_NPU_BACKEND'] = 'mlir'50os.environ['TORCHINDUCTOR_NPU_BACKEND'] = 'mlir'
@@ -62,9 +71,12 @@ compile_func = torch.compile(op_calc, options={"npu_backend": "mlir"})
62compile_out, codes = run_and_get_code(compile_func,x,y)71compile_out, codes = run_and_get_code(compile_func,x,y)
63print(codes[0])72print(codes[0])
64```73```
74+ 
65## 输出mlir融合算子75## 输出mlir融合算子
76+ 
66codes 为捕获到的 MLIR 输出代码片段,该代码中包含 call 函数与 benchmark_compiled_model 函数,其中 call 函数内部封装了 MLIR 编译生成的算子逻辑。77codes 为捕获到的 MLIR 输出代码片段,该代码中包含 call 函数与 benchmark_compiled_model 函数,其中 call 函数内部封装了 MLIR 编译生成的算子逻辑。
67-```78+ 
79+```python
68def call(args):80def call(args):
69 arg0_1, arg1_1 = args81 arg0_1, arg1_1 = args
70 args.clear()82 args.clear()
@@ -77,4 +89,5 @@ def call(args):
77 del arg1_189 del arg1_1
78 return (buf0, )90 return (buf0, )
79```91```
80-其中mlir_fused_mul_0.run 是 MLIR 编译生成的核心执行接口,用于在指定 NPU 设备和计算流上执行融合乘法算子计算,接收输入张量并将计算结果写入输出张量,是 MLIR 对原始乘法逻辑优化后的底层实现。92+ 
93+其中mlir_fused_mul_0.run 是 MLIR 编译生成的核心执行接口,用于在指定 NPU 设备和计算流上执行融合乘法算子计算,接收输入张量并将计算结果写入输出张量,是 MLIR 对原始乘法逻辑优化后的底层实现。
@@ -83,7 +83,7 @@ print(model(torch.randn(8, 10, device=device)))
83 83 
84#### 加载并运行 AOTI 模型(C++ 接口)84#### 加载并运行 AOTI 模型(C++ 接口)
85 85 
86-可以使用C++接口加载并运行AOTI模型。Inductor NPU对比GPU需要额外依赖```libtorch_npu.so```,该so由PTA的编译脚本```build_libtorch_npu.py```生成。86+可以使用C++接口加载并运行AOTI模型。Inductor NPU对比GPU需要额外依赖```libtorch_npu.so```,该so由TorchNPU的编译脚本```build_libtorch_npu.py```生成。
87 87 
88```C++88```C++
89#include <iostream>89#include <iostream>
@@ -1,7 +1,7 @@
1# 环境变量列表1# 环境变量列表
2 2 
3本手册描述开发者在使用inductor-ascend过程中可使用的环境变量。3本手册描述开发者在使用inductor-ascend过程中可使用的环境变量。
4-Ascend Extension for PyTorch环境变量请参考《[Ascend Extension for PyTorch环境变量参考](https://www.hiascend.com/document/detail/zh/Pytorch/730/comref/Envvariables/docs/zh/environment_variable_reference/env_variable_list.md)》。4+TorchNPU环境变量请参考《[TorchNPU环境变量参考](https://www.hiascend.com/document/detail/zh/Pytorch/730/comref/Envvariables/docs/zh/environment_variable_reference/env_variable_list.md)》。
5基于CANN构建AI应用和业务过程中使用的环境变量请参考《[CANN 环境变量参考](https://www.hiascend.com/document/detail/zh/canncommercial/850/maintenref/envvar/envref_07_0001.html)》。5基于CANN构建AI应用和业务过程中使用的环境变量请参考《[CANN 环境变量参考](https://www.hiascend.com/document/detail/zh/canncommercial/850/maintenref/envvar/envref_07_0001.html)》。
6 6 
7**表 1** 环境变量列表7**表 1** 环境变量列表
@@ -2,7 +2,7 @@
2 2 
3## 图优化特性简介3## 图优化特性简介
4 4 
5-在CANN(华为计算加速网络)异构计算架构中支持多种AI框架。该架构基于开源的PyTorch,并通过torch_npu适配昇腾AI处理器。torch_npu 利用 PyTorch 中的 Inductor 编译器能力,实现模型的加速编译。由于开源 PyTorch 对昇腾的适配性较弱,且对不同模型的图优化能力不足,需要通过自定义的优化 pass(优化步骤)来增强图优化能力,从而进一步提升模型性能。5+在CANN(华为计算加速网络)异构计算架构中支持多种AI框架。该架构基于开源的PyTorch,并通过TorchNPU适配昇腾AI处理器。TorchNPU 利用 PyTorch 中的 Inductor 编译器能力,实现模型的加速编译。由于开源 PyTorch 对昇腾的适配性较弱,且对不同模型的图优化能力不足,需要通过自定义的优化 pass(优化步骤)来增强图优化能力,从而进一步提升模型性能。
6 6 
7![Alt text](image.png)7![Alt text](image.png)
8 8 
@@ -46,7 +46,7 @@ batch_embedding_fusion_pass
46 46 
47**前置条件**47**前置条件**
48 48 
49-- 已在系统上安装 `torch_npu` 包(对应的版本需匹配所使用的 PyTorch 版本)。49+- 已在系统上安装 `TorchNPU` 包(对应的版本需匹配所使用的 PyTorch 版本)。
50- 机器配备 Ascend NPU 并已正确安装驱动和运行时环境。50- 机器配备 Ascend NPU 并已正确安装驱动和运行时环境。
51- 确认 PyTorch 版本 >= 2.0,以支持 `torch.compile`51- 确认 PyTorch 版本 >= 2.0,以支持 `torch.compile`
52 52 
@@ -12,7 +12,7 @@ Inductor作为PyTorch编译模式的核心backend选项,可通过torch.compile
12 12 
13在Ascend上使用PyTorch编译模式的Inductor后端,请按以下步骤操作:13在Ascend上使用PyTorch编译模式的Inductor后端,请按以下步骤操作:
14 14 
15-1. **环境准备**:确保已安装Ascend驱动、CANN和pta对应版本的PyTorch15+1. **环境准备**:确保已安装Ascend驱动、CANN和TorchNPU对应版本的PyTorch
162. **环境变量配置**:设置必要的Ascend驱动和CANN环境变量162. **环境变量配置**:设置必要的Ascend驱动和CANN环境变量
173. **验证安装**:运行简单的测试用例验证环境配置173. **验证安装**:运行简单的测试用例验证环境配置
184. **开始使用**:参考昇腾社区的PyTorch编译模式介绍手册 《[PyTorch编译模式](https://www.hiascend.com/document/detail/zh/Pytorch/730/ptmoddevg/Frameworkfeatures/docs/zh/framework_feature_guide_pytorch/pytorch_compilation_mode.md)》184. **开始使用**:参考昇腾社区的PyTorch编译模式介绍手册 《[PyTorch编译模式](https://www.hiascend.com/document/detail/zh/Pytorch/730/ptmoddevg/Frameworkfeatures/docs/zh/framework_feature_guide_pytorch/pytorch_compilation_mode.md)》
@@ -2,9 +2,9 @@
2 2 
3## 2.1 兼容性说明3## 2.1 兼容性说明
4 4 
5-目前Inductor Ascend暂未提供独立软件包,而是作为Ascend Extension for PyTorch的子目录(与PyTorch社区相同),随着torch_npu包一起发布。请直接安装torch_npu插件,即可使用Inductor Ascend。5+目前Inductor Ascend暂未提供独立软件包,而是作为TorchNPU的子目录(与PyTorch社区相同),随着TorchNPU包一起发布。请直接安装TorchNPU插件,即可使用Inductor Ascend。
6-torch_npu的安装操作具体参考《[Ascend Extension for PyTorch 软件安装指南](https://www.hiascend.com/document/detail/zh/Pytorch/730/configandinstg/instg/docs/zh/installation_guide/installation_description.md)》,请保证与CANN相关包的版本匹配(参见《[版本说明](https://www.hiascend.com/document/detail/zh/Pytorch/730/releasenote/docs/zh/release_notes/release_notes.md)》),否则功能可能无法正常使用。6+TorchNPU的安装操作具体参考《[TorchNPU 软件安装指南](https://www.hiascend.com/document/detail/zh/Pytorch/730/configandinstg/instg/docs/zh/installation_guide/installation_description.md)》,请保证与CANN相关包的版本匹配(参见《[版本说明](https://www.hiascend.com/document/detail/zh/Pytorch/730/releasenote/docs/zh/release_notes/release_notes.md)》),否则功能可能无法正常使用。
7-需要注意的是,当安装的torch_npu版本为2.7.1及之后版本,均可正常使用Inductor Ascend,对于其他torch_npu版本请参见对应版本文档中的安装介绍。7+需要注意的是,当安装的TorchNPU版本为2.7.1及之后版本,均可正常使用Inductor Ascend,对于其他TorchNPU版本请参见对应版本文档中的安装介绍。
8 8 
9### PyTorch版本支持9### PyTorch版本支持
10 10 
@@ -4,7 +4,7 @@
4 4 
5Inductor-Ascend在继承Pytorch社区Inductor能力的基础上,针对昇腾Ascend硬件,进行了亲和性改进和优化。其目标是:提供昇腾亲和的torch.compile图模式后端;生成昇腾亲和的Triton DSL,支持基于triton的算子自动融合;支持动态shape。5Inductor-Ascend在继承Pytorch社区Inductor能力的基础上,针对昇腾Ascend硬件,进行了亲和性改进和优化。其目标是:提供昇腾亲和的torch.compile图模式后端;生成昇腾亲和的Triton DSL,支持基于triton的算子自动融合;支持动态shape。
6 6 
7-如图1(推荐场景-图模式-软件栈)所示,Inductor-Ascend和社区Inductor的执行流程类似,其内嵌于PyTorch-Adapter(torch-npu)中,当用户开启图模式后端torch.compile(backend="inductor")时,Inductor-Ascend承接Dynamo抓取的FX Graph,进行编译、融合,生成昇腾亲和融合算子Triton DSL;最后由Triton-Ascend、AscendNPU-IR编译优化,生成昇腾指令机器码(二进制)。7+如图1(推荐场景-图模式-软件栈)所示,Inductor-Ascend和社区Inductor的执行流程类似,其内嵌于TorchNPU中,当用户开启图模式后端torch.compile(backend="inductor")时,Inductor-Ascend承接Dynamo抓取的FX Graph,进行编译、融合,生成昇腾亲和融合算子Triton DSL;最后由Triton-Ascend、AscendNPU-IR编译优化,生成昇腾指令机器码(二进制)。
8 8 
9和社区类似,对于无法参与融合的算子(AtenOp),Inductor-Ascend会将其作fallback处理,即fallback到ACLNN算子、手写算子等。9和社区类似,对于无法参与融合的算子(AtenOp),Inductor-Ascend会将其作fallback处理,即fallback到ACLNN算子、手写算子等。
10 10 
@@ -1,11 +1,10 @@
1# 模型性能分析1# 模型性能分析
2 2 
3-Inductor的性能调优方法可参考pytorch官方文档, 《[Profiling to understand torch.compile performance](https://docs.pytorch.org/docs/stable/user_guide/torch_compiler/torch.compiler_profiling_torch_compile.html)》,其中`torch.profiler.profile()`需要按照`torch_npu`相关接口进行适配,适配方法参考《[Ascend PyTorch调优工具](https://www.hiascend.com/document/detail/zh/canncommercial/850/devaids/Profiling/atlasprofiling_16_0033.html)》。3+Inductor的性能调优方法可参考pytorch官方文档, 《[Profiling to understand torch.compile performance](https://docs.pytorch.org/docs/stable/user_guide/torch_compiler/torch.compiler_profiling_torch_compile.html)》,其中`torch.profiler.profile()`需要按照`TorchNPU`相关接口进行适配,适配方法参考《[Ascend PyTorch调优工具](https://www.hiascend.com/document/detail/zh/canncommercial/850/devaids/Profiling/atlasprofiling_16_0033.html)》。
4 4 
5例如,Torch社区中的`ModelWithBreaks`用例可参考如下进行改造,改造后的代码如下:5例如,Torch社区中的`ModelWithBreaks`用例可参考如下进行改造,改造后的代码如下:
6 6 
7-``` python7+```python
8- 
9import torch8import torch
10import torch._dynamo9import torch._dynamo
11import torch_npu10import torch_npu
@@ -1,8 +1,8 @@
1# 问题定位方法1# 问题定位方法
2 2 
3参考Pytorch社区文档:《[问题定位方法](https://docs.pytorch.org/docs/stable/user_guide/torch_compiler/torch.compiler_troubleshooting.html)》。3参考Pytorch社区文档:《[问题定位方法](https://docs.pytorch.org/docs/stable/user_guide/torch_compiler/torch.compiler_troubleshooting.html)》。
4-如果出现其他错误,请按问题反馈流程提交ISSUE至Ascend Extension for PyTorch社区。4+如果出现其他错误,请按问题反馈流程提交ISSUE至Ascend for PyTorch社区。
5 5 
6-# 问题反馈流程6+## 问题反馈流程
7 7 
8-Issue 中应提供 PTA(Ascend Extension for PyTorch)、Triton-Ascend、CANN 的版本信息、最小复现 demo 源码以及报错的堆栈或截图,提交至《[Ascend Extension for PyTorch社区](https://gitcode.com/Ascend/pytorch/issues)》,同时在ISSUE名称中添加[Inductor]标签。8+Issue 中应提供 TorchNPU、Triton-Ascend、CANN 的版本信息、最小复现 demo 源码以及报错的堆栈或截图,提交至《[Ascend for PyTorch社区](https://gitcode.com/Ascend/pytorch/issues)》,同时在ISSUE名称中添加[Inductor]标签。