使用迁移工具迁移

描述如何使用迁移工具将TensorFlow 1.15网络自动迁移到昇腾平台。

了解网络迁移工具

【功能介绍】
Ascend平台提供了TensorFlow 1.15网络迁移工具，该工具适用于原生的TensorFlow训练脚本迁移场景，AI算法工程师通过该工具分析原生的TensorFlow Python API和Horovod Python API在昇腾AI处理器上的支持度情况，同时将原生的TensorFlow训练脚本自动迁移成昇腾AI处理器支持的脚本。对于无法自动迁移的API，您可以参考工具输出的迁移报告，对训练脚本进行相应的适配修改。
【获取路径】
- CANN软件安装完成后，迁移工具在“tfplugin安装目录/tfplugin/latest/python/site-packages/npu_bridge/convert_tf2npu/”目录下。
- 您也可以从昇腾开源社区获取“convert_tf2npu”文件夹，并将“convert_tf2npu”文件夹上传到Linux或Windows环境上任意目录即可。

【使用限制】在使用工具进行模型迁移前，先来了解对原始训练脚本的限制：

要求原始脚本在GPU/CPU上跑通，精度收敛。
要求原始脚本仅使用TensorFlow 1.15官方API和Horovod官方API，若用户脚本使用了其他第三方API，当前工具暂不支持迁移。例如：
1. 不支持原生Keras API，但由于TensorFlow官方API中包括了TensorFlow的Keras API，因此支持TensorFlow的Keras API。
2. 不支持CuPy API，即便原始脚本能在GPU上运行成功，但不能保证在昇腾AI处理器运行成功。

原始脚本中的TensorFlow模块和Horovod模块最好按照如下方式引用，否则工具迁移后，无法生成准确的迁移报告（但并不影响脚本迁移）。

         
              import tensorflow as tf
import tensorflow.compat.v1 as tf
import horovod.tensorflow as hvd

当前版本不支持float64/complex64/complex128/DT_VARIANT数据类型。
当前不支持tf.keras和原生Keras的Loss Scale功能迁移。

前提条件

在昇腾AI处理器进行模型迁移之前，建议用户事先准备好基于TensorFlow 1.15开发的训练模型以及配套的数据集，并要求在GPU或CPU上跑通，精度收敛，且达到预期精度和性能要求。同时记录相关精度和性能指标，用于后续在昇腾AI处理器进行精度和性能对比。

迁移操作步骤

安装依赖。
pip3 install pandas==1.3.5

pip3 install xlrd==1.2.0

pip3 install openpyxl

pip3 install tkintertable

pip3 install google_pasta

训练脚本扫描和自动迁移。

该工具支持在Linux或Windows环境进行脚本迁移。

Linux环境操作步骤：

进入迁移工具所在目录，例如“tfplugin安装目录/tfplugin/latest/python/site-packages/npu_bridge/convert_tf2npu/”，执行命令可同时完成脚本扫描和自动迁移，例如：

python3 main.py -i /root/models/official/resnet

其中main.py为工具入口脚本，参数说明如下所示。

表1 参数说明
参数名	参数说明	可选/必选
-i	被迁移的原始脚本路径，当前该路径仅支持配置为文件夹，不支持单个文件。说明：工具仅对-i参数指定的文件夹下的.py文件进行扫描和迁移。如果用户原始脚本跨目录存放，则建议放到同一个目录执行迁移命令，或者在对应目录下依次执行迁移命令。	必选
-o	指定迁移后的脚本路径，该路径不能为原始脚本路径的子目录。该参数可选，如果不指定，默认生成在当前路径下，例如output_npu_20210401150929/xxx_npu_20210401150929。	可选
-r	指定生成的迁移报告路径，该路径不能为原始脚本路径的子目录。该参数可选，如果不指定，默认生成在当前路径下，例如report_npu_20210401150929。	可选
-m	Python执行入口文件。如果原始脚本使用了tf.keras/hvd接口，且脚本中没有main函数，由于迁移工具无法识别入口函数，因此无法进行NPU资源初始化，以及NPU训练相关配置。对于以上场景，需要通过-m参数指定Python执行的入口文件，以便工具可以将用户脚本进行彻底迁移，保证后续训练的顺利执行。配置示例：-m /root/models/xxx.py	可选
-d	如果原始脚本支持分布式训练，需要指定原始脚本使用的分布式策略，便于工具对分布式脚本进行自动迁移。取值： tf_strategy：表示原始脚本使用tf.distribute.Strategy分布式策略 horovod：表示原始脚本使用horovod分布式策略目前session run分布式脚本无法彻底进行自动迁移，使用工具自动迁移完后，需要参考sess.run分布式脚本迁移进行后续的手工改造。	分布式必选

通过python3 main.py -h可以获取迁移工具使用帮助。

Windows环境操作步骤：
```
python3 main_win.py
```
在弹出的窗口根据界面提示进行操作。
1. 根据界面提示设置相关输入。
2. 点击“开始分析”，能看到分析结果，并在指定的路径下生成迁移后的脚本，在指定的“输出分析报告路径”下生成分析报告。
3. 点击“重新开始分析”，则返回选择路径窗口，可以重新指定输入脚本，再次分析。
4. 点击“退出”，则退出TensorFlow 1.15网络迁移工具。

迁移过程中，打印如下信息，表明正在扫描相关文件进行脚本迁移。
图1 迁移过程信息
迁移结束后，生成迁移后的脚本，以及迁移报告。
图2 迁移结束信息
- 如果没有生成failed_report.txt，一般迁移后的模型即可直接在昇腾AI处理器执行训练，如果训练失败，可详细分析迁移报告，同时酌情修改训练脚本再次训练，如果仍然训练失败，请到昇腾开源社区求助。
- 如果生成了failed_report.txt，请优先根据报错修改训练脚本，再执行训练。

迁移报告说明

success_report.txt：记录工具对脚本的全部修改点，例如：

# 表示resnet_run_loop.py第91行的map_and_batch()的drop_remainder参数配置为True
/root/models/models/official/resnet/resnet_run_loop.py:91 change map_and_batch(xxx) to map_and_batch(xxx, drop_remainder=True)
# 表示resnet_run_loop.py第4行新增“from npu_bridge.npu_init import *”头文件引用，用于导入NPU相关库。
/root/models/models/official/resnet/resnet_run_loop.py:4 from npu_bridge.npu_init import *
Finish conver file: /root/models/models/official/resnet/resnet_run_loop.py

failed_report.txt：记录迁移过程中的报错信息以及不支持的API，例如：

/root/ast_test/hvd/model_lib.py:704 is horovod api. The '-d' argument conflicts with the Horovod distributed strategy in your script
Finish conver file: /root/ast_test/hvd/model_lib.py
/root/ast_test/hvd/test.py:3, NPU Unsupport API: hvd.allreduce

api_analysis_report.xlsx：为API支持度分析报告，用户可以筛选“不支持（无迁移方案，建议不使用）”和“废弃类”API单独分析，并根据修改建议修改训练脚本。

图3 API支持度分析报告举例
点击放大

表2 工具迁移API支持度说明
工具迁移API支持度	说明
支持（无需迁移）	此类API在昇腾AI处理器上绝对支持，无需适配修改。例如"tf.abs"等接口，在昇腾AI处理器上能够完全支持，不需要迁移。
工具迁移后API功能支持	工具迁移后，该API在昇腾AI处理器上可以支持。
工具迁移后训练功能打通	工具迁移后，能够保证在昇腾AI处理器训练执行成功，但原有API功能可能不完全支持。例如"tf.config.experimental.set_memory_growth"接口，它的作用一般是将所有GPU设置为仅在需要时申请显存空间，在昇腾AI处理器上训练时，该接口实际并不生效。因此，迁移工具会直接return返回None，从而保证在昇腾AI处理器上训练正常执行。 "tf.config.experimental.set_memory_growth" --> 直接return返回None
不支持（不影响迁移，无需干预）	此类API在昇腾AI处理器上不支持，但不影响脚本执行，无需用户干预。例如"tf.config.experimental.get_memory_growth"接口，由于工具会将"tf.config.experimental.set_memory_growth"直接return返回None，因此对应的get接口也不会影响脚本在昇腾AI处理器上的执行，即便出现这个接口，用户也无需干预。
不支持（无迁移方案，建议不使用）	此类API在昇腾AI处理器上不支持，且当前暂无具体迁移方案，建议您不要使用，否则会引起训练失败。例如"tf.distribute.experimental.TPUStrategy"等TPU相关接口，需通过Google TPU设备执行，昇腾AI处理器上不支持，建议用户不要使用。另外，"tf.enable_eager_execution"等eager功能相关接口，在当前版本也不支持，建议用户不要使用。
废弃类	此类API在TensorFlow 1.15版本已经废弃，建议用户使用TensorFlow官网推荐的API，否则可能会引起训练失败。例如"tf.colocate_with"等接口。
兼容类	此类API主要作为TensorFlow 2.X版本中支持TensorFlow 1.X功能所使用，在TensorFlow 1.X脚本中不会使用到。例如"tf.compat.v1.abs"和"tf.compat.v2.abs"等接口。

need_migration_doc.txt：需要用户手工迁移的API。

api_brief_report.txt：汇总脚本中API支持度统计结果，例如：

# 未去重的统计结果，分类和API支持度表中的一致
1.In brief: Total API: 231, in which Support: 222, API support after migration: 5, Network training support after migration: 0, Not support but no impact on migration: 0, Not support or recommended: 2, Compatible: 0, Deprecated: 2, Analysing: 0
# 去重后的统计结果，分类和API支持度表中的一致
2.After eliminate duplicate: Total API: 98, in which Support: 92, API support after migration: 4, Network training support after migration: 0, Not support but no impact on migration: 0, Not support or recommended: 1, Compatible: 0, Deprecated: 1, Analysing: 0

配置NPU相关参数

Ascend平台提供了功能调试、性能/精度调优等功能，自动迁移后，可通过如下session配置的方式使能相关功能，详细的参数说明可参见session配置。

检查迁移后的脚本是否存在“init_resource”。

如果存在，则参考如下示例，在init_resource函数中传入session_config的配置，需要注意，仅initialize_system中支持的配置项可在init_resource函数的config中进行配置，若需配置其他功能，请在运行配置中添加，可参见2。

           
                if __name__ == '__main__':
  # 增加session配置“allow_soft_placement=True”，允许TensorFlow自动分配设备。
  session_config = tf.ConfigProto(allow_soft_placement=True)
  # 添加名字为“NpuOptimizer”的NPU优化器，网络编译时，NPU只会遍历“NpuOptimizer”下的session配置。
  custom_op = session_config.graph_options.rewrite_options.custom_optimizers.add()
  custom_op.name = "NpuOptimizer"
  # 配置session参数
  custom_op.parameter_map["profiling_mode"].b = True
  ... ...

  (npu_sess, npu_shutdown) = init_resource(config=session_config)
  tf.app.run()
  shutdown_resource(npu_sess, npu_shutdown)
  close_session(npu_sess)

如果不存在，则直接执行下一步。

在运行配置中添加相关session配置。

针对Estimator模型的脚本，在迁移后的脚本中查找“npu_run_config_init”，找到运行配置函数，例如示例中的“run_config”，在运行配置参数中添加相关session参数，如下面示例中的“aoe_mode”参数。

           
                session_config = tf.ConfigProto(allow_soft_placement=True)
# 添加名字为“NpuOptimizer”的NPU优化器，网络编译时，NPU只会遍历“NpuOptimizer”下的session配置。
custom_op = session_config.graph_options.rewrite_options.custom_optimizers.add()
custom_op.name = 'NpuOptimizer'
# 配置session参数
custom_op.parameter_map["aoe_mode"].s = tf.compat.as_bytes("2")

run_config = tf.estimator.RunConfig(
    train_distribute=distribution_strategy,
    session_config=session_config,
    save_checkpoints_secs=60*60*24)

classifier = tf.estimator.Estimator(
    model_fn=model_function, model_dir=flags_obj.model_dir, config=npu_run_config_init(run_config=run_config))

针对sess.run模式的脚本，在迁移后的脚本中查找“npu_config_proto”，找到运行配置参数（例如下面示例中的“session_config”），在运行配置参数中添加相关session参数，如下面示例中的“aoe_mode”参数。

           
                session_config = tf.ConfigProto(allow_soft_placement=True)
# 添加名字为“NpuOptimizer”的NPU优化器，网络编译时，NPU只会遍历“NpuOptimizer”下的session配置。
custom_op = session_config.graph_options.rewrite_options.custom_optimizers.add()
custom_op.name = 'NpuOptimizer'
# 配置session参数
custom_op.parameter_map["aoe_mode"].s = tf.compat.as_bytes("2")
config = npu_config_proto(config_proto=session_config)
with tf.Session(config=config) as sess:
    sess.run(tf.global_variables_initializer())
    interaction_table.init.run()

针对Keras模式的脚本，在迁移后的脚本中查找“set_keras_session_npu_config”函数，找到运行配置参数（例如下面示例中的“config_proto”），在运行配置参数中添加相关session参数，如下面示例中的“aoe_mode”参数。

           
                import tensorflow as tf
import tensorflow.python.keras as keras
from tensorflow.python.keras import backend as K
from npu_bridge.npu_init import *

config_proto = tf.ConfigProto(allow_soft_placement=True)
# 添加名字为“NpuOptimizer”的NPU优化器，网络编译时，NPU只会遍历“NpuOptimizer”下的session配置。
custom_op = config_proto.graph_options.rewrite_options.custom_optimizers.add()
custom_op.name = 'NpuOptimizer'
# 配置session参数
custom_op.parameter_map["aoe_mode"].s = tf.compat.as_bytes("2")
npu_keras_sess = set_keras_session_npu_config(config=config_proto)

#数据预处理...
#模型搭建...
#模型编译...
#模型训练...

父主题： 自动迁移