操作步骤

启动脚本迁移。
通过以下任一方式发起脚本迁移任务：
- 在工具栏选择“Ascend > Migration Tools > X2MindSpore”。
- 单击工具栏中图标。
- 右键单击工程目录中的文件夹，选择“X2MindSpore”。

参数配置。

X2MindSpore启动后界面如图1 X2MindSpore参数配置界面所示，用户自行根据实际情况配置参数。

图1 X2MindSpore参数配置界面（开启Distributed）
点击放大

图2 X2MindSpore参数配置界面（开启Graph）
点击放大

表1 X2MindSpore参数说明
参数	参数说明
Framework	要进行迁移的原始脚本的框架，必选。取值如下。 PyTorch（默认） TensorFlow 1 TensorFlow 2
Input Path	要进行迁移的原始工程目录。必选。
Output Path	分析迁移结果文件输出路径。会在该路径下输出带有x2ms或x2ms_multi后缀的目录。必选。不开启迁移至多卡脚本功能场景下，输出目录名为xxx_x2ms；开启迁移至多卡脚本功能场景下，输出目录名为xxx_x2ms_multi，xxx为原始脚本所在文件夹名称。
Distributed	将GPU单卡脚本迁移为多卡脚本。“Framework”参数选择“PyTorch”和“TensorFlow 2”时展现。开启此参数，将展示“Device”参数。目前该功能不支持TensorFlow 1。可选。默认关闭。
Device	将GPU单卡脚本迁移为指定设备的多卡脚本。"Distributed"开启时展示。必选。取值如下。 Ascend（默认） GPU
Graph	迁移后的脚本支持在MindSpore 1.8及更新版本的Graph模式下运行。“Framework”参数选择“PyTorch”时展现。开启此参数，将展示“Target Model”参数。可选。默认关闭（即默认迁移至PyNative模式）。目前该参数仅支持表1中ResNet和BiT系列的模型迁移至Graph模式，且不能与“Distributed”同时使用。
Target Model	"Graph"开启后此参数才会体现。目标模型变量名，默认为“model”，可选。

单击“Transplant”，执行迁移任务。

完成后，Output Path输出目录下查看结果文件。

├── xxx_x2ms/xxx_x2ms_multi              // 脚本迁移结果输出目录
│   ├── 迁移后的脚本文件             // 与迁移前的脚本文件目录结构一致。
│   ├── x2ms_adapter                 // 适配层文件。
│   ├── unsupported_api.csv          // 不支持API列表文件。
│   ├── custom_supported_api.csv     // 工具自定义适配API列表文件（目前仅支持PyTorch框架的训练脚本）。
│   ├── supported_api.csv            // 支持API列表文件。
│   ├── deleted_api.csv              // 删除API列表文件。
│   ├── x2mindspore.log              // 迁移日志，日志文件限制大小为1M，若超过限制将分多个文件进行存储，最多不会超过10个。
│   ├── run_distributed_ascend.sh       // 启用Distributed参数，且Device指定Ascend设备时，会生成该多卡启动shell脚本。
│   ├── rank_table_2pcs.json            // 启用Distributed参数，且Device指定Ascend设备时，会生成该2卡环境组网信息样例文件。
│   ├── rank_table_8pcs.json            // 启用Distributed参数，且Device指定Ascend设备时，会生成该8卡环境组网信息样例文件。

在执行迁移后的模型文件前请先将输出的工程路径加入环境变量PYTHONPATH中。

迁移完成后

如果启用了Distributed参数，迁移后需要根据Device指定的设备完成运行多卡脚本的特定操作。

Device指定Ascend设备。

参见配置分布式环境变量配置生成的分布式环境变量配置文件。

将run_distributed_ascend.sh文件中的“please input your shell script here”语句替换成模型原来的训练Python脚本执行命令。

#!/bin/bash
echo "=============================================================================================================="
echo "Please run the script as: "
echo "bash run_distributed_ascend.sh RANK_TABLE_FILE RANK_SIZE RANK_START DEVICE_START"
echo "For example: bash run_distributed_ascend.sh /path/rank_table.json 8 0 0"
echo "It is better to use the absolute path."
echo "=============================================================================================================="
execute_path=$(pwd)
echo "${execute_path}"
export RANK_TABLE_FILE=$1
export RANK_SIZE=$2
RANK_START=$3
DEVICE_START=$4
for((i=0;i<RANK_SIZE;i++));
do
  export RANK_ID=$((i+RANK_START))
  export DEVICE_ID=$((i+DEVICE_START))
  rm -rf "${execute_path}"/device_$RANK_ID
  mkdir "${execute_path}"/device_$RANK_ID
  cd "${execute_path}"/device_$RANK_ID || exit
  "please input your shell script here" > train$RANK_ID.log 2>&1 &
done

表2 参数说明
参数	说明
RANK_TABLE_FILE	多卡环境的组网信息文件。
RANK_SIZE	昇腾AI处理器的数量。
RANK_START	指定调用昇腾AI处理器的逻辑起始ID，当前仅支持单机多卡，填0即可。
DEVICE_START	指定调用昇腾AI处理器的物理起始ID。

该脚本会在工程路径下创建device_{RANK_ID}目录，在该目录内去执行网络脚本，所以替换训练Python脚本执行命令时要注意训练Python脚本相对路径的变化。

执行run_distributed_ascend.sh脚本以启动用户原工程。以8卡环境为例，命令如下。
```
bash run_distributed_ascend.sh RANK_TABLE_FILE RANK_SIZE RANK_START DEVICE_START
```

具体MindSpore分布式训练（Ascend）请参见分布式并行训练（Ascend）。

Device指定GPU设备。
在GPU硬件平台上，MindSpore采用OpenMPI的mpirun进行分布式训练，可通过以下命令运行多卡脚本。
```
mpirun -n {多卡脚本运行的GPU卡数量} {模型原来的训练shell脚本执行命令}
```
具体MindSpore分布式训练（GPU）请参见分布式并行训练（GPU）。

如果启用了Graph参数，需要把训练脚本中WithLossCell类的construct函数修改为只包括模型的前向计算和loss计算，具体修改请参见迁移后脚本中的Transplant advice。
由于转换后的脚本与原始脚本框架不一致，迁移后的脚本在调试运行过程中可能会由于MindSpore框架的某些限制而抛出异常，导致进程终止，该类异常需要用户根据异常信息进一步调试解决。
分析迁移后可以参考模型训练进行训练。

迁移操作

操作步骤

迁移完成后