---
title: 分析迁移工具
description: "昇腾NPU是AI算力的后起之秀，但目前训练和在线推理脚本大多是基于GPU的。由于NPU与GPU的架构差异，基于GPU的训练和在线推理脚本不能直接在NPU上使用。"
url: https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/latest/devaids/migrationtools/msfmktransplt/README.md
sourcePath: /source/zh/CANNCommunityEdition/920beta1/devaids/migrationtools/msfmktransplt/README.md
indexId: 3deac093bcf35a0ce5ff41701f8d0211b30da748b5e9cad843a4fc96b7980c8c87
---
# 分析迁移工具
## 简介
昇腾NPU是AI算力的后起之秀，但目前训练和在线推理脚本大多是基于GPU的。由于NPU与GPU的架构差异，基于GPU的训练和在线推理脚本不能直接在NPU上使用。
分析迁移工具（msTransplant，MindStudio Transplant）提供PyTorch训练脚本一键式迁移至昇腾NPU的功能，开发者可做到少量代码修改或零代码完成迁移。该工具提供PyTorch Analyse功能，帮助用户分析PyTorch训练脚本的API、第三方库API、亲和API分析以及动态shape的支持情况。同时提供了自动迁移和PyTorch GPU2Ascend工具两种迁移方式，将基于GPU的脚本迁移为基于NPU的脚本，这种自动化方法节省了人工手动进行脚本迁移的学习成本与工作量，大幅提升了迁移效率。
- （推荐）自动迁移：修改内容少，只需在训练脚本中导入库代码，迁移后直接在昇腾NPU平台上运行。
- PyTorch GPU2Ascend工具迁移：迁移过程会生成分析文件，支持用户查看API支持度分析报告和迁移过程中对原训练脚本的修改内容，并支持单卡脚本迁移为多卡脚本。
> [!NOTE] 说明
> 使用分析迁移工具迁移前，请用户自行确认原工程内各参数的正确性，需在原工程运行成功的基础上使用工具进行迁移。
## 使用前准备
**环境准备**
该工具功能的实际执行仅依赖CPU，且需提前安装以下必选依赖：
```shell
pip3 install pandas # 必选，pandas版本号需大于或等于1.2.4
pip3 install libcst # 必选，语义分析库，用于解析Python文件
pip3 install prettytable # 必选，将数据可视化为图表形式
pip3 install jedi # 必选，用于跨文件解析
```
迁移功能执行完成后，若需在NPU上运行迁移后的训练脚本，还需完成以下额外依赖的安装：
- 安装配套版本的CANN Toolkit开发套件包和ops算子包，请参见《[CANN 快速安装](https://www.hiascend.com/cann/download)》。
- 配置环境变量。
安装CANN软件后，使用CANN运行用户进行编译、运行时，需要以CANN运行用户登录环境，执行`source $_{install_path}_set_env.sh`命令设置环境变量。其中${install_path}为CANN软件的安装目录，例如：/usr/local/Ascend/cann。
> [!NOTE] 说明
>
> 上述环境变量只在当前窗口生效，用户可以将上述命令写入~.bashrc文件，使其永久生效，操作如下：
> 1. 以安装用户在任意目录下执行`vi ~.bashrc`，打开.bashrc文件，并在该文件最后添加上述环境变量。
> 2. 执行`:wq!`命令，保存文件并退出。
> 3. 执行`source ~.bashrc`命令，使环境变量生效。
**约束**
- 分析和迁移工具当前支持PyTorch2.1.0、2.6.0、2.7.1、2.8.0版本训练脚本的分析和迁移。
- 原脚本需要在GPU环境下且基于Python3.7及以上能够运行成功。
- 分析迁移后的执行逻辑与迁移前需保持一致。
- 若原始代码中调用了第三方库，迁移过程可能会存在适配问题。在迁移原始代码前，用户需要根据已调用的第三方库，自行安装昇腾已适配的第三方库版本，已适配的第三方库信息和使用指南请参考《[TorchNPU配套软件库](https://gitcode.com/Ascend/docs/blob/master/FrameworkPTAdapter/26.1.0/zh/supported_suites_and_third_party_libraries/supported_suites_and_third_party_libraries.md)》。
- APEX中使用的FusedAdam优化器不支持使用自动迁移和PyTorch GPU2Ascend工具进行迁移，若原始代码中包含该优化器，用户需自行修改。
- 当前分析工具不支持对原生函数self.dropout()、nn.functional.softmax()、torch.add、bboexs_diou()、bboexs_giou()、LabelSmoothingCrossEntropy()或ColorJitter进行亲和API分析，若原训练脚本涉及以上原生函数，请参考《[TorchNPU自定义API参考](https://gitcode.com/Ascend/op-plugin/blob/26.1.0/docs/zh/custom_APIs/overview.md)》中“Python接口 > torch_npu.contrib”节点进行分析和替换。
- 若用户训练脚本中包含昇腾NPU平台不支持的**amp_C**模块，需要用户手动删除import amp_C相关代码内容后，再进行训练。
- 由于转换后的脚本与原始脚本平台不一致，迁移后的脚本在调试运行过程中可能会由于算子差异等原因而抛出异常，导致进程终止，该类异常需要用户根据异常信息进一步调试解决。
**安全注意事项**
- 在Linux环境使用工具时，出于安全性及权限最小化角度考虑，本工具不应使用root等高权限账户进行操作，建议使用普通用户权限安装执行。
- 在Linux环境使用工具时，请确保使用前执行用户的umask值大于等于0027，否则可能会造成工具生成的数据文件和目录权限过大。
- 在Linux环境使用工具时，用户须自行保证使用最小权限原则，如给工具输入的文件要求other用户不可写，在一些对安全要求更严格的功能场景下还需确保输入的文件group用户不可写。
- 由于本工具依赖CANN，为保证安全，应使用同一低权限用户默认安装的CANN包，source命令执行后请不要随意修改set_env.sh中涉及的环境变量。
- 本工具为开发调测工具，不建议在生产环境使用。
## 快速入门
**概述**
分析迁移工具可将基于GPU的训练脚本迁移为支持NPU的脚本，大幅度提高脚本迁移速度，降低开发者的工作量。本样例可以让开发者快速体验自动迁移（推荐）和PyTorch GPU2Ascend工具的迁移效率。
本样例选用ResNet50模型，数据集为ImageNet。
**环境准备**
- 准备一台基于Atlas训练系列产品的训练服务器，并安装对应的驱动和固件。驱动和固件的安装请参考《[CANN 软件安装指南](https://www.hiascend.com/document/detail/zh/canncommercial/900/softwareinst/instg/instg_0000.html?OS=openEuler&InstallType=netconda)》中的“[安装NPU驱动固件](https://www.hiascend.com/document/detail/zh/canncommercial/900/softwareinst/instg/instg_0005.html?OS=openEuler&InstallType=netconda)”章节。
- 安装开发套件包Ascend-cann-toolkit及ops算子包，具体请参考《[CANN 软件安装指南](https://www.hiascend.com/document/detail/zh/canncommercial/900/softwareinst/instg/instg_0000.html?OS=openEuler&InstallType=netyum)》的“[安装CANN](https://www.hiascend.com/document/detail/zh/canncommercial/900/softwareinst/instg/instg_0089.html?OS=openEuler&InstallType=netyum)”节点。
- 以安装PyTorch 2.1.0版本为例，具体操作请参考《[TorchNPU软件安装](https://gitcode.com/Ascend/pytorch/blob/v2.7.1-26.1.0/docs/zh/installation_guide/installation_description.md)》的“[方式一：离线安装（Whl）](https://gitcode.com/Ascend/pytorch/blob/v2.7.1-26.1.0/docs/zh/installation_guide/installation_via_binary_package.md)”章节，完成PyTorch框架和TorchNPU插件的安装。
- 下载[main.py](https://gitee.com/ascend/mstt/blob/master/sample/transfer_to_npu/main.py)文件，将获得ResNet50模型放到用户自定义路径下（如/home/user）。
**自动迁移（推荐）**
修改内容少，只需在训练脚本中导入库代码，迁移后直接在昇腾NPU平台上运行。
1. 在训练脚本[main.py](https://gitee.com/ascend/mstt/blob/master/sample/transfer_to_npu/main.py)文件中导入自动迁移的库代码。
```python
from torch.utils.data import Subset
import torch_npu
from torch_npu.contrib import transfer_to_npu
.....
```
2. 切换目录至迁移完成后的训练脚本所在路径（以/home/user为例），执行以下命令使用虚拟数据集进行训练，迁移完成后的训练脚本可在NPU上正常运行。
开始打印迭代日志，说明训练功能迁移成功。
```shell
cd /home/user
python main.py -a resnet50 --gpu 1 --epochs 1 --dummy # --gpu 1表示使用卡1，--epochs 1是指迭代次数为1
```
3. 迁移工具自动保存权重成功，说明迁移成功。
**使用PyTorch GPU2Ascend工具迁移**
1. 进入迁移工具所在路径。
```shell
cd msfmktransplt/src/ms_fmk_transplt/
```
2. 执行脚本迁移任务，参考**表 6** 参数说明配置信息。
```shell
bash pytorch_gpu2npu.sh -i /home/user -o /home/out -v 2.1.0
```
/home/user为原始脚本路径， /home/out为脚本迁移结果输出路径，2.1.0为原始脚本的PyTorch框架版本。
3. 切换目录至迁移完成后的训练脚本所在路径（以/home/user为例），执行以下命令使用虚拟数据集进行训练，迁移完成后的训练脚本可在NPU上正常运行。
开始打印迭代日志，说明训练功能迁移成功。
```shell
cd /home/user
python main.py -a resnet50 --gpu 1 --epochs 1 --dummy # --gpu 1表示使用卡1，--epochs 1是指迭代次数为1
```
4. 完成脚本迁移，进入脚本迁移结果的输出路径查看结果件。
> [!NOTE] 说明
> 脚本迁移过程中会启动迁移分析，默认使用torch_apis和affinity_apis的分析模式，可参见输出结果文件说明查看对应的结果件。
5. 迁移工具自动保存权重成功，说明迁移成功。
## 迁移分析
**功能说明**
PyTorch Analyse工具提供分析脚本，帮助用户在执行迁移操作前，分析基于GPU平台的PyTorch训练脚本中API、第三方库套件、亲和API分析以及动态shape的支持情况，具体请参见**表 1** 分析模式介绍。
分析脚本所在路径为：msfmktransplt/src/ms_fmk_transplt/pytorch_analyse.sh。
**表 1** 分析模式介绍
|分析模式|分析脚本|分析结果|调优建议
|--|--|--|--
|第三方库套件分析模式|需用户提供待分析的第三方库套件源码。|可快速获得源码中不支持的第三方库API和CUDA信息。说明：第三方库API是指在第三方库代码中的函数，如果某函数的函数体内使用了不支持的torch算子或者CUDA自定义算子，则此函数就是第三方库不支持的API。如果第三方库中其他函数调用了这些不支持的API，则这些调用函数也为不支持的API。| -
|API支持情况分析模式|需用户提供待分析的PyTorch训练脚本。|可快速获得训练脚本中不支持的torch API和CUDA API信息。|输出训练脚本中API精度和性能调优的专家建议。
|动态shape分析模式|需用户提供待分析的PyTorch训练脚本。|可快速获得训练脚本中包含的动态shape信息。|-
|亲和API分析模式 |需用户提供待分析的PyTorch训练脚本。|可快速获得训练脚本中可替换的亲和API信息。|-
**命令格式**
```shell
bash pytorch_analyse.sh -i -o