昇腾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支持度分析报告和迁移过程中对原训练脚本的修改内容，并支持单卡脚本迁移为多卡脚本。
[object Object]
环境准备
该工具功能的实际执行仅依赖CPU，且需提前安装以下必选依赖：
迁移功能执行完成后，若需在NPU上运行迁移后的训练脚本，还需完成以下额外依赖的安装：
配置环境变量。
安装CANN软件后，使用CANN运行用户进行编译、运行时，需要以CANN运行用户登录环境，执行
[object Object]命令设置环境变量。其中${install_path}为CANN软件的安装目录，例如：/usr/local/Ascend/cann。[object Object]
约束
- 分析和迁移工具当前支持PyTorch2.1.0、2.6.0、2.7.1、2.8.0版本训练脚本的分析和迁移。
- 原脚本需要在GPU环境下且基于Python3.7及以上能够运行成功。
- 分析迁移后的执行逻辑与迁移前需保持一致。
- 若原始代码中调用了第三方库，迁移过程可能会存在适配问题。在迁移原始代码前，用户需要根据已调用的第三方库，自行安装昇腾已适配的第三方库版本，已适配的第三方库信息和使用指南请参考《》。
- APEX中使用的FusedAdam优化器不支持使用自动迁移和PyTorch GPU2Ascend工具进行迁移，若原始代码中包含该优化器，用户需自行修改。
- 当前分析工具不支持对原生函数self.dropout()、nn.functional.softmax()、torch.add、bboexs_diou()、bboexs_giou()、LabelSmoothingCrossEntropy()或ColorJitter进行亲和API分析，若原训练脚本涉及以上原生函数，请参考《》中“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训练系列产品的训练服务器，并安装对应的驱动和固件。请参考《》安装昇腾NPU驱动和CANN软件（包含Toolkit、ops包）。
以安装PyTorch 2.1.0版本为例，具体操作请参考《》的“”章节，完成PyTorch框架和torch_npu插件的安装。
自动迁移（推荐）
修改内容少，只需在训练脚本中导入库代码，迁移后直接在昇腾NPU平台上运行。
-
[object Object]
切换目录至迁移完成后的训练脚本所在路径（以/home/user为例），执行以下命令使用虚拟数据集进行训练，迁移完成后的训练脚本可在NPU上正常运行。
开始打印迭代日志，说明训练功能迁移成功。
[object Object]迁移工具自动保存权重成功，说明迁移成功。
使用PyTorch GPU2Ascend工具迁移
进入迁移工具所在路径。
[object Object]-
[object Object]
/home/user为原始脚本路径， /home/out为脚本迁移结果输出路径，2.1.0为原始脚本的PyTorch框架版本。
切换目录至迁移完成后的训练脚本所在路径（以/home/user为例），执行以下命令使用虚拟数据集进行训练，迁移完成后的训练脚本可在NPU上正常运行。
开始打印迭代日志，说明训练功能迁移成功。
[object Object]完成脚本迁移，进入脚本迁移结果的输出路径查看结果件。
[object Object]
迁移工具自动保存权重成功，说明迁移成功。
功能说明
PyTorch Analyse工具提供分析脚本，帮助用户在执行迁移操作前，分析基于GPU平台的PyTorch训练脚本中API、第三方库套件、亲和API分析以及动态shape的支持情况，具体请参见。
分析脚本所在路径为：msfmktransplt/src/ms_fmk_transplt/pytorch_analyse.sh。
表 1 分析模式介绍 [object Object][object Object]
命令格式
其中“[]”表示可选参数，实际使用可不用添加；“<>”表示变量。
参数说明
表 2 参数说明[object Object][object Object]
使用示例（API支持情况分析）
进入分析工具所在路径。
[object Object]启动分析任务。
[object Object]其中/home/xxx/analysis为待分析脚本路径，/home/xxx/analysis_output为分析结果输出路径，2.1.0为待分析脚本框架版本。
若
[object Object]参数指定的分析模式为dynamic_shape，分析任务完成后需参考对训练脚本进行修改，才能获取动态shape分析报告。
使用示例（不支持迁移的第三方库API信息分析）
进入分析工具所在路径。
[object Object]使用-m参数的third_party第三方库套件分析功能，获得第三方库中不支持迁移的API列表（csv文件）。
[object Object]third_party_input_path为第三方库文件夹路径，third_party_output_path为结果输出路径，2.1.0为待分析脚本框架版本。
该命令执行完成后，在third_party_output_path目录下生成第三方库中不支持迁移的API列表，即framework_unsupported_op.csv文件。
将上述步骤中获取的csv文件传入-api，获取当前训练脚本中不支持迁移的三方库API信息。
[object Object]input_path为模型脚本文件夹路径，output_path为结果输出路径。
输出结果文件说明[object Object][object Object]
分析模式为“torch_apis“时，分析结果如下所示：
[object Object]表 3 “torch_apis“模式csv文件介绍
[object Object]undefined
图1 不支持的API列表示例
[object Object][object Object]
表 4 PyTorch API接口信息[object Object][object Object]
[object Object][object Object]
[object Object]分析模式为“third_party“时，分析结果如下所示：
[object Object]表 5 “third_party”模式csv文件介绍
[object Object]undefined
图2 不支持的API列表示例 [object Object][object Object]
分析模式为“affinity_apis“时，分析结果如下所示：
[object Object]分析报告affinity_api_call.csv包括原生API的调用信息，并将其分为几种类型：class（类）、function（方法）、torch（Pytorch框架API）以及special（特殊表达式）。用户可以根据分析报告，在训练脚本中将原生API手动替换为指定的亲和API，替换后的脚本在昇腾AI处理器上运行时，性能更优。分析报告示例如下。
图3 亲和API分析报告示例
分析模式为“dynamic_shape”时，分析结果如下所示：
[object Object]生成动态shape分析结果件后，还需要先修改分析结果输出目录下训练脚本文件中的读取训练数据集的for循环，手动开启动态shape检测，请参考下方示例进行修改。
修改前：
[object Object]修改后：
[object Object]运行分析修改后的训练脚本，将在分析结果件所在的根目录下生成保存动态shape的分析报告msft_dynamic_shape_analysis_report.csv。
[object Object]
功能说明
本章节将指导用户将PyTorch训练脚本从GPU平台迁移至昇腾NPU平台。自动迁移方式支持PyTorch2.1.0、2.6.0、2.7.1、2.8.0版本的训练脚本的迁移，自动迁移方式较简单，且修改内容最少，只需在训练脚本中导入库代码。
注意事项
- 由于自动迁移工具使用了Python的动态特性，但torch.jit.script不支持Python的动态语法，因此用户原训练脚本中包含torch.jit.script时使用自动迁移功能会产生冲突。目前自动迁移时会屏蔽torch.jit.script功能，若用户脚本中必须使用torch.jit.script功能，请使用进行迁移。
- 自动迁移工具与昇腾已适配的第三方库可能存在功能冲突，若发生冲突，请使用进行迁移。
- 当前自动迁移暂不支持channel_last特性，建议用户使用contiguous进行替换。
- 若原脚本中使用的backend为nccl，在init_process_group初始化进程组后，backend已被自动迁移工具替换为hccl。如果后续代码逻辑包含backend是否为nccl的判断，例如assert backend in ['gloo', 'nccl']、if backend == 'nccl'，请手动将字符串nccl改写为hccl。
- 若用户训练脚本中包含昇腾NPU平台不支持的torch.cuda.default_generators接口，需要手动修改为torch_npu.npu.default_generators接口。
迁移操作使用示例
导入自动迁移的库代码。
在训练入口
[object Object]文件的首行，插入以下引用内容。例如train.py中的首行插入以下引用内容。[object Object]
迁移异常处理[object Object][object Object]
- 如果模型包含评估、在线推理功能，也可在对应脚本中导入自动迁移库代码，并通过对比评估推理结果和日志打印情况，判断与GPU、CPU是否一致决定是否迁移成功。
- 若训练过程中提示部分CUDA接口报错，可能是部分API（算子API或框架API）不支持引起，用户可参考以下方案进行解决。
功能说明
本章节介绍PyTorch GPU2Ascend工具的迁移方式。
注意事项
- 由于转换后的脚本与原始脚本平台不一致，迁移后的脚本在调试运行过程中可能会由于算子差异等原因而出现异常，导致进程终止，该类异常需要用户根据异常信息进一步调试解决。
- 分析迁移后可以参考原始脚本提供的训练流程进行训练。
命令格式
其中“[]”表示可选参数，实际使用可不用添加；“<>”表示变量。
参数说明
表 6 参数说明[object Object][object Object]
使用示例
进入迁移工具所在路径。
[object Object]启动迁移任务。
[object Object]其中/home/username/fmktransplt为原始脚本路径，/home/username/fmktransplt_output为脚本迁移结果输出路径，2.1.0为原始脚本框架版本，/home/train/train.py为训练脚本的入口文件，model为目标模型变量名。distributed及其参数-m、-t在语句最后指定。
参考示例：
[object Object]完成脚本迁移，进入脚本迁移结果的输出路径查看结果件。
[object Object]
成功保存权重，说明保存权重功能迁移成功。
训练完成后，迁移工具自动保存权重成功，说明迁移成功。
功能说明
本章节主要介绍在特殊场景中进行模型迁移训练时需要注意的配置事项。
注意事项
无。
使用示例
为了提升模型运行速度，建议开启使用二进制算子，请参考《》中的“”章节安装Toolkit开发套件包及ops算子包后，参考如下方式开启：
单卡场景下，修改训练入口文件例如main.py文件，在import torch_npu下方添加如下代码。
[object Object]多卡场景下，如果拉起多卡训练的方式为mp.spawn，则torch_npu.npu.set_compile_mode(jit_compile=False)必须加在进程拉起的主函数中才能使能二进制，否则使能方式与单卡场景相同。
[object Object]
用户训练脚本中包含昇腾NPU平台不支持的torch.nn.DataParallel接口，需要手动修改为torch.nn.parallel.DistributedDataParallel接口执行多卡训练，参考进行修改。
若用户训练脚本中包含昇腾NPU平台不支持的amp_C模块，需要用户手动删除import amp_C相关代码内容后，再进行训练。
若用户训练脚本中包含torch.cuda.get_device_capability接口，迁移后在昇腾NPU平台上运行时，会返回“None”值。
[object Object]
torch.cuda.get_device_properties接口迁移后在昇腾NPU平台上运行时，返回值不包含minor和major属性，建议用户注释掉调用minor和major属性的代码。
torch.utils.data.DataLoader是PyTorch中一个用于数据加载的工具类，主要用于将样本数据划分为多个小批次(batch)，以便进行训练、测试、验证等任务，查看模型脚本中的数据集加载方式是否是通过torch.utils.data.DataLoader加载，示例代码如下：
如果迁移时启用了“distributed“参数，想将GPU单卡脚本迁移为NPU多卡脚本，需进行如下操作获取结果文件：
[object Object]
训练脚本语句替换。
将执行迁移命令后生成的“run_distributed_npu.sh“文件中的please input your shell script here语句替换成模型原来的训练shell脚本。例如将“please input your shell script here”替换为模型训练命令“bash_model_train_script.sh _--data_path data_path”。
“run_distributed_npu.sh“文件如下所示：
[object Object]表 7 run_distributed_npu.sh参数说明
[object Object]undefined
替换后，执行“run_distributed_npu.sh“文件，会生成指定NPU的log日志。
查看结果文件。
脚本迁移完成后，进入结果输出路径查看结果文件。以GPU单卡脚本迁移为NPU多卡脚本为例，结果文件包含以下内容：
[object Object]查看迁移后的py脚本，可以看到脚本中的CUDA侧API被替换成NPU侧的API。
[object Object]
问题现象
运行转换后代码无报错，仅提示“Segmentation fault”信息。
原因分析
可能原因一：
代码中引用了TensorBoard或第三方库中包含TensorBoard，以下为已知的引用TensorBoard的第三方库。
- wandb：若该库仅用来打log，可以删除该库的调用。
- transformers：该库深度绑定TensorFlow、TensorBoard。
可能原因二：
训练脚本中包含两个0维Tensor在不同设备上进行比较的代码，当前该比较不支持在torch_npu上运行。
解决方案
原因一解决方案：
注释掉相关的Summary、Writer调用即可规避该错误。Summary、Writer多用于记录日志和绘图，不影响网络跑通和精度收敛。
原因二解决方案：
在脚本启动命令前添加python -X faulthandler打印线程信息，定位到具体的报错位置，进行pdb调试。来定位脚本中是否存在两个0维Tensor在不同设备上进行比较的代码，需要用户手动修改为在同一设备上进行比较，示例如下：
修改前，在CPU和NPU上进行比较：
[object Object]修改后，添加如下信息，修改为同在NPU上进行比较：
[object Object]
引用库找不到的问题，有可能是以下三种情况，请根据实际情况进行排查：
问题现象一
当前目录或子目录中存在的文件夹或者文件找不到引用库。
解决方案一
只需将该目录的父目录加到PYTHONPATH环境变量中即可。
问题现象二
找不到的引用库为requirements.txt中说明需要pip安装的包。
解决方案二
可以使用pip install 包名进行安装，若安装失败可以git clone安装包，使用python3 setup.py install安装。
问题现象三
找不到的引用库为readme.md中说明需要通过git clone下载安装的安装包。
解决方案三
请按照要求下载并安装。
问题现象
解决方案
如上图所示，将label_batch.npu()改成label_batch.int().npu()，即把当前报错行的变量类型改成int32，规避此类Muls算子不支持int64的问题。
问题现象
报错“No supported Ops kernel and engine are found for [ReduceStdV2A], optype [ReduceStdV2A]”，算子ReduceStdV2A不支持。
解决方案
可以通过用std求标准差再平方得到var，均值单独调用mean接口求来规避问题例如：
具体到代码中修改：
表 8 常见运行报错