版本迁移工具

在飞桨框架2.0中，Paddle API的位置、命名、参数、行为，进行了系统性的调整和规范, 将API体系从1.X版本的 paddle.fluid.* 迁移到了 paddle.* 下。paddle.fluid 目录下暂时保留了1.8版本API，主要是兼容性考虑，未来会被删除。

使用版本迁移工具自动迁移Paddle 1.X的代码到Paddle 2.0

飞桨提供了版本迁移工具，该工具按 Paddle 2.0 对于 Paddle 1.X的变化，能够自动实现以下功能：

  • 按照 API映射表 ，将转换工具能否转换这列为True的API由Paddle 1.X 转为 Paddle 2.0，为False的API打印WARNING，提示手动升级。

  • 因为Paddle 2.0.0 默认开启动态图，所以删除用于开启动态图上下文的 with paddle.fluid.dygraph.guard(place) ，并修改该上下文的代码缩进；

  • 删除组网API中的 act 参数，并自动添加相关的激活函数；

目前，版本迁移工具能够处理的API数量为X个，如果你有代码迁移的需求，使用转换工具能够节省你部分时间，帮助你快速完成代码迁移。

警告

版本迁移工具并不能处理所有的情况，对于API的处理只能按照 API映射表 中的关系完成API的变化。如代码中包含有转换工具能否转换这列为False的API或不在此表中的API，在使用本工具后，仍然需要手工来进行检查并做相应的调整。

安装

版本迁移工具可以通过pip的方式安装，方式如下:

  1. $ pip install paddle_upgrade_tool

基本用法

paddle_upgrade_tool 可以使用下面的方式，快速使用:

  1. $ paddle_upgrade_tool --inpath /path/to/model.py

这将在命令行中，以diff的形式，展示model.py从Paddle 1.x转换为Paddle 2.0的变化。如果你确认上述变化没有问题，只需要再执行：

  1. $ paddle_upgrade_tool --inpath /path/to/model.py --write

就会原地改写model.py，将上述变化改写到你的源文件中。 注意：版本转换工具会默认备份源文件，到~/.paddle_upgrade_tool/下。

参数说明如下：

  • –inpath 输入文件路径，可以为单个文件或文件夹。

  • –write 是否原地修改输入的文件，默认值False，表示不修改。如果为True，表示对文件进行原地修改。添加此参数也表示对文件进行原地修改。

  • –backup 可选，是否备份源文件，默认值为~/.paddle_upgrade_tool/，在此路径下备份源文件。

  • –no-log-file 可选，是否需要输出日志文件，默认值为False，即输出日志文件。

  • –log-filepath 可选，输出日志的路径，默认值为report.log，输出日志文件的路径。

  • –no-confirm 可选，输入文件夹时，是否逐文件确认原地写入，只在--write为True时有效，默认值为False，表示需要逐文件确认。

  • –parallel 可选，控制转换文件的并发数，当 no-confirm 为True时不生效，默认值:None。

  • –log-level 可选，log级别，可为[‘DEBUG’,‘INFO’,‘WARNING’,‘ERROR’] 默认值：INFO。

  • –refactor 可选，debug时使用。

  • –print-match 可选，debug时使用。

使用教程

开始

在使用paddle_upgrade_tool前，需要确保已经安装了Paddle 2.0.0版本。

  1. import paddle
  2. print (paddle.__version__)
  1. 2.0.0

克隆paddlePaddle/models来作为工具的测试。

  1. $ git clone https://github.com/PaddlePaddle/models
  1. Cloning into 'models'...
  2. remote: Enumerating objects: 8, done.
  3. remote: Counting objects: 100% (8/8), done.
  4. remote: Compressing objects: 100% (8/8), done.
  5. remote: Total 35011 (delta 1), reused 0 (delta 0), pack-reused 35003
  6. Receiving objects: 100% (35011/35011), 356.97 MiB | 1.53 MiB/s, done.
  7. Resolving deltas: 100% (23291/23291), done.

查看帮助文档

你可以直接通过下面的方式，查看帮助文档。

  1. $ paddle_upgrade_tool -h
  1. usage: paddle_upgrade_tool [-h] [--log-level {DEBUG,INFO,WARNING,ERROR}]
  2.                            [--no-log-file] [--log-filepath LOG_FILEPATH] -i
  3.                            INPATH [-b [BACKUP]] [-w] [--no-confirm]
  4.                            [-p PARALLEL]
  5.                            [-r {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}]
  6.                            [--print-match]
  8. optional arguments:
  9.   -h, --help            show this help message and exit
  10.   --log-level {DEBUG,INFO,WARNING,ERROR}
  11.                         set log level, default is INFO
  12.   --no-log-file         don't log to file
  13.   --log-filepath LOG_FILEPATH
  14.                         set log file path, default is "report.log"
  15.   -i INPATH, --inpath INPATH
  16.                         the file or directory path you want to upgrade.
  17.   -b [BACKUP], --backup [BACKUP]
  18.                         backup directory, default is the
  19.                         "~/.paddle_upgrade_tool/".
  20.   -w, --write           modify files in-place.
  21.   --no-confirm          write files in-place without confirm, ignored without
  22.                         --write.
  23.   -p PARALLEL, --parallel PARALLEL
  24.                         specify the maximum number of concurrent processes to
  25.                         use when refactoring, ignored with --no-confirm.
  26.   -r {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}, --refactor {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}
  27.                         this is a debug option. Specify refactor you want to
  28.                         run. If none, all refactors will be run.
  29.   --print-match         this is a debug option. Print matched code and node
  30.                         for each file.

Paddle 1.x的例子

这里是一个基于Paddle 1.x实现的一个mnist分类，部分内容如下：

  1. $ head -n 198 models/dygraph/mnist/train.py | tail -n  20
  1. with fluid.dygraph.guard(place):
  2.     if args.ce:
  3.         print("ce mode")
  4.         seed = 33
  5.         np.random.seed(seed)
  6.         fluid.default_startup_program().random_seed = seed
  7.         fluid.default_main_program().random_seed = seed
  9.     if args.use_data_parallel:
  10.         strategy = fluid.dygraph.parallel.prepare_context()
  11.     mnist = MNIST()
  12.     adam = AdamOptimizer(learning_rate=0.001, parameter_list=mnist.parameters())
  13.     if args.use_data_parallel:
  14.         mnist = fluid.dygraph.parallel.DataParallel(mnist, strategy)
  16.     train_reader = paddle.batch(
  17.         paddle.dataset.mnist.train(), batch_size=BATCH_SIZE, drop_last=True)
  18.     if args.use_data_parallel:
  19.         train_reader = fluid.contrib.reader.distributed_batch_reader(
  20.             train_reader)

使用paddle_upgrade_tool进行转化

paddle_upgrade_tool支持单文件的转化，你可以通过下方的命令直接转化单独的文件。

  1. $ paddle_upgrade_tool --inpath models/dygraph/mnist/train.py

注意，对于参数的删除及一些特殊情况，迁移工具都会打印WARNING信息，需要你仔细核对相关内容。 如果你觉得上述信息没有问题，可以直接对文件进行原地修改，方式如下：

  1. $ paddle_upgrade_tool --inpath models/dygraph/mnist/train.py --write

此时，命令行会弹出下方的提示：

  1. "models/dygraph/mnist/train.py" will be modified in-place, and it has been backed up to "~/.paddle_upgrade_tool/train.py_backup_2020_09_09_20_35_15_037821". Do you want to continue? [Y/n]:

输入y 后即开始执行代码迁移。为了高效完成迁移，工具这里采用了原地写入的方式。此外，为了防止特殊情况，工具会备份转换前的代码到 ~/.paddle_upgrade_tool 目录下，如果需要，你可以在备份目录下找到转换前的代码。

代码迁移完成后，会生成一个report.log文件，记录了迁移的详情。内容如下：

  1. $ cat report.log

注意事项

  • 本迁移工具不能完成所有API的迁移，有少量的API需要你手动完成迁移，具体信息可见WARNING。

使用Paddle 2.0

完成迁移后，代码就从Paddle 1.x迁移到了Paddle 2.0，你就可以在Paddle 2.0下进行相关的开发。