工具迁移

工具迁移推荐使用命令行方式。

若用户想使用图形开发界面、或已安装MindStudio，可以参考《MindStudio 用户指南》中的“分析迁移>PyTorch GPU2Ascend”章节使用MindStudio中集成的PyTorch GPU2Ascend功能进行工具迁移。

使用命令行方式进行工具迁移的核心步骤如下：

1. 环境准备。
   1. 安装开发套件包Ascend-cann-toolkit。具体操作请参考《CANN 软件安装指南》的“安装开发环境”章节。
   2. 须安装如下依赖（以root用户安装为例，非root用户需加--user参数）。

      pip3 install pandas         #pandas版本号需大于或等于1.2.4
      pip3 install libcst         #Python语法树解析器，用于解析Python文件
      pip3 install jedi           #可选，用于跨文件解析，建议安装

2. 进入迁移工具所在路径。

   cd Ascend-cann-toolkit安装目录/ascend-toolkit/latest/tools/ms_fmk_transplt/

3. 进入分析迁移工具所在路径，执行脚本迁移任务。

   ./pytorch_gpu2npu.sh -i 原始脚本路径 -o 脚本迁移结果输出路径 -v 原始脚本框架版本 [-r 自定义规则json文件路径] [-s] [-sim] [-m] [distributed -t 目标模型变量名 -m 训练脚本的入口文件]

   表1 参数说明

   参数	参数说明	取值示例
   -i --input	要进行迁移的原始脚本文件所在文件夹路径。 必选。	/home/username/fmktransplt
   -o --output	脚本迁移结果文件输出路径。 不开启“distributed”即迁移至单卡脚本场景下，输出目录名为xxx_msft；开启“distributed”即迁移至多卡脚本场景下，输出目录名为xxx_msft_multi，xxx为原始脚本所在文件夹名称。 必选。	/home/username/fmktransplt_output
   -v --version	待迁移脚本的PyTorch版本。目前支持1.8.1和1.11.0。 必选。	1.8.1 1.11.0
   -r --rule	用户自定义通用迁移规则的json文件路径，主要分为：函数参数修改、函数名称修改和模块名称修改三部分。自定义迁移规则json文件的编写请参见《分析迁移工具》中的“msFmkTransplt>PyTorch GPU2Ascend>附录>自定义迁移规则”章节。 可选。	/home/username/fmktransplt_rule.json
   -s --specify-device	可以通过环境变量DEVICE_ID指定device作为高级特性，但有可能导致原本脚本中分布式功能失效。 可选。	-
   -sim --similar	用功能相似的API替换以下工具暂不支持的API，但有可能导致准确性和性能下降。 apex.parallel.DistributedDataParallel torch.cuda.get_device_properties torch.nn.Conv3d torch.nn.functional.pad torch.nn.ReflectionPad2d torch.nn.ReplicationPad2d torch.nn.SyncBatchNorm torch.nn.SyncBatchNorm.convert_sync_batchnorm torch.repeat_interleave torch.set_default_tensor_type 可选。	-
   distributed	将GPU单卡脚本迁移为NPU多卡脚本，仅支持使用torch.utils.data.DataLoader方式加载数据的场景，指定此参数时，才可以指定-t/--target_model参数。 -m，--main：训练脚本的入口python文件，必选。 -t，--target_model：目标模型变量名，默认为“model”，可选。	-
   -m --modelarts	迁移后的脚本支持在ModelArts平台进行训练作业。 可选。	-
   -h --help	显示帮助信息。	-

   如果迁移时启用了“distributed”参数，迁移后会生成如下run_distributed_npu.sh文件，在执行迁移后的模型之前需要把文件中的“please input your shell script here”语句替换成模型原来的训练shell脚本。执行run_distributed_npu.sh文件后会生成指定NPU的log日志。

   export MASTER_ADDR=127.0.0.1
   export MASTER_PORT=63350
   export HCCL_WHITELIST_DISABLE=1   
   
   NPUS=($(seq 0 7))
   export RANK_SIZE=${#NPUS[@]}
   rank=0
   for i in ${NPUS[@]}
   do
       export DEVICE_ID=${i}
       export RANK_ID=${rank}
       echo run process ${rank}
       please input your shell script here > output_npu_${i}.log 2>&1 &
       let rank++
   done

   表2 参数说明

   参数	说明
   MASTER_ADDR	指定训练服务器的ip
   MASTER_PORT	指定训练服务器的端口
   HCCL_WHITELIST_DISABLE	hccl后端环境
   NPUS	指定在特定NPU上运行
   RANK_SIZE	指定调用卡的数量
   DEVICE_ID	指定调用的device_id
   RANK_ID	指定调用卡的逻辑ID

4. 查看结果文件。
   脚本迁移完成后，进入脚本迁移结果输出路径查看结果文件，以GPU单卡脚本迁移为NPU多卡脚本为例：

   ├── xxx_msft/xxx_msft_multi              // 脚本迁移结果输出目录
   │   ├── 生成脚本文件                 // 与迁移前的脚本文件目录结构一致
   │   ├── msFmkTranspltlog.txt         // 脚本迁移过程日志文件，日志文件限制大小为1M，若超过限制将分多个文件进行存储，最多不会超过10个
   │   ├── cuda_op_list.csv            //分析出的cuda算子列表
   │   ├── unknown_api.csv             //支持情况存疑的API列表
   │   ├── unsupported_api.csv         //不支持的API列表
   │   ├── change_list.csv              // 修改记录文件
   │   ├── run_distributed_npu.sh       // 多卡启动shell脚本
   │   ├── ascend_function              // 如果启用了Replace Unsupported APIs参数，会生成该包含等价算子的目录
   │   ├── ascend_modelarts_function
   │   │   ├── modelarts_path_manager.py    // 启用ModelArts参数，会生成该路径映射适配层代码文件
   │   │   ├── path_mapping_config.py       // 启用ModelArts参数，会生成该路径映射配置文件

   

   • 若用户训练脚本中包含昇腾NPU平台不支持的amp_C模块，需要用户手动删除后再进行训练。
   • 由于转换后的脚本与原始脚本平台不一致，迁移后的脚本在调试运行过程中可能会由于算子差异等原因而抛出异常，导致进程终止，该类异常需要用户根据异常信息进一步调试解决。

更多命令行方式工具迁移内容，请参见《分析迁移工具》中的“msFmkTransplt”章节。