本文为针对 NLP 方向的复现赛指南

以深度学习为核心的人工智能技术仍在高速发展，通过论文复现，开发者可以获得

基于本指南复现论文过程中，建议开发者准备以下内容。

了解该模型输入输出格式。以BERT的情感分类任务为例，通过阅读论文与参考代码，了解到模型输入为[batch_size, sequence_length]的tensor，类型为int64，label为[batch, ]的label，类型为int64。

准备好训练/验证数据集，用于模型训练与评估

准备好fake input data以及label，与模型输入shape、type等保持一致，用于后续模型前向对齐。

在特定设备(CPU/GPU)上，跑通参考代码的预测过程(前向)以及至少2轮(iteration)迭代过程，保证后续基于PaddlePaddle复现论文过程中可对比。

本文档基于 BERT-SST2-Prod 代码以及reprod_log whl包进行说明与测试。如果希望体验，建议参考BERT-SST2-Prod文档进行安装与测试。

在复现的过程中，只需要将PaddlePaddle的复现代码以及打卡日志上传至github，不能在其中添加参考代码的实现，在验收通过之后，需要删除打卡日志。建议在初期复现的时候，就将复现代码与参考代码分成2个文件夹进行管理。

飞桨训推一体认证 (Training and Inference Pipeline Certification, TIPC) 是一个针对飞桨模型的测试工具，方便用户查阅每种模型的训练推理部署打通情况，并可以进行一键测试。论文训练对齐之后，需要为代码接入TIPC基础链条测试文档与代码，关于TIPC基础链条测试接入规范的文档可以参考：链接。更多内容在3.13章节部分也会详细说明。

面对一篇自然语言处理的论文，复现该论文的整体流程如下图所示。

总共包含12个步骤。为了高效复现论文，设置了6个验收节点。如上图中黄色框所示。后续章节会详细介绍上述步骤和验收节点，具体内容安排如下：

reprod_log是用于论文复现赛中辅助自查和验收工具。该工具源代码地址在：https://github.com/WenmuZhou/reprod_log。主要功能如下：

更多API与使用方法可以参考：reprod_log API使用说明。

下面基于代码：https://github.com/JunnYu/BERT-SST2-Prod/tree/main/pipeline/reprod_log_demo，给出如何使用该工具。

文件夹中包含write_log.py和check_log_diff.py文件，其中write_log.py中给出了ReprodLogger类的使用方法，check_log_diff.py给出了ReprodDiffHelper类的使用方法，依次运行两个python文件，使用下面的方式运行代码。

最终会输出以下内容

可以看出：对于key为demo_test_1的矩阵，由于diff为0，小于设置的阈值1e-6，核验成功；对于key为demo_test_2的矩阵，由于diff为0.33，大于设置的阈值1e-6，核验失败。

在论文复现中，基于reprod_log的结果记录模块，产出下面若干文件

基于reprod_log的ReprodDiffHelper模块，产出下面5个日志文件。

上述文件的生成代码都需要开发者进行开发，验收时需要提供上面罗列的所有文件（不需要提供产生这些文件的可运行程序）以及完整的模型训练评估程序和日志。

BERT-SST2-Prod项目提供了基于reprod_log的5个验收点对齐验收示例，具体代码地址为：https://github.com/JunnYu/BERT-SST2-Prod/tree/main/pipeline，每个文件夹中的README.md文档提供了使用说明。

InsightFace项目中提供了TIPC基础链条验收点的验收示例，参考代码地址为：https://github.com/deepinsight/insightface/blob/master/recognition/arcface_paddle/test_tipc/readme.md，更多关于TIPC基础链条测试接入规范的代码可以参考：https://github.com/PaddlePaddle/models/blob/tipc/docs/tipc_test/development_specification_docs/train_infer_python.md

对齐模型结构时，一般有3个主要步骤：

下面详细介绍这3个部分。

【基本流程】

由于PyTorch的API和PaddlePaddle的API非常相似，可以参考PyTorch-PaddlePaddle API映射表，组网部分代码直接进行手动转换即可。

【实战】

BERT网络结构的PyTorch实现: transformers-bert

对应转换后的PaddlePaddle实现: paddlenlp-bert

【基本流程】

组网代码转换完成之后，需要对模型权重进行转换，如果PyTorch repo中已经提供权重，那么可以直接下载并进行后续的转换；如果没有提供，则可以基于PyTorch代码，随机生成一个初始化权重(定义完model以后，使用torch.save() API保存模型权重)，然后进行权重转换。

【注意事项】

在权重转换的时候，需要注意paddle.nn.Linear以及paddle.nn.BatchNorm2D等API的权重保存格式和名称等与PyTorch稍有diff，具体内容可以参考4.1章节。

【实战】

BERT的代码转换脚本可以在这里查看：https://github.com/JunnYu/BERT-SST2-Prod/blob/main/pipeline/weights/torch2paddle.py，

注意：运行该代码需要首先下载Huggingface的BERT预训练模型到该目录下，下载地址为：https://huggingface.co/bert-base-uncased/blob/main/pytorch_model.bin

from collections import OrderedDict

import numpy as npimport paddleimport torchfrom paddlenlp.transformers import BertForPretraining as PDBertForMaskedLMfrom transformers import BertForMaskedLM as PTBertForMaskedLM

def convert_pytorch_checkpoint_to_paddle( pytorch_checkpoint_path="pytorch_model.bin", paddle_dump_path="model_state.pdparams", version="old", ): hf_to_paddle = { "embeddings.LayerNorm": "embeddings.layer_norm", "encoder.layer": "encoder.layers", "attention.self.query": "self_attn.q_proj", "attention.self.key": "self_attn.k_proj", "attention.self.value": "self_attn.v_proj", "attention.output.dense": "self_attn.out_proj", "intermediate.dense": "linear1", "output.dense": "linear2", "attention.output.LayerNorm": "norm1", "output.LayerNorm": "norm2", "predictions.decoder.": "predictions.decoder_", "predictions.transform.dense": "predictions.transform", "predictions.transform.LayerNorm": "predictions.layer_norm", } do_not_transpose = [] if version == "old": hf_to_paddle.update({ "predictions.bias": "predictions.decoder_bias", ".gamma": ".weight", ".beta": ".bias", }) do_not_transpose = do_not_transpose + ["predictions.decoder.weight"]

pytorch_state_dict = torch.load( pytorch_checkpoint_path, map_location="cpu") paddle_state_dict = OrderedDict() for k, v in pytorch_state_dict.items(): is_transpose = False if k[-7:] == ".weight": # embeddings.weight and LayerNorm.weight do not transpose if all(d not in k for d in do_not_transpose): if ".embeddings." not in k and ".LayerNorm." not in k: if v.ndim == 2: v = v.transpose(0, 1) is_transpose = True oldk = k for hf_name, pd_name in hf_to_paddle.items(): k = k.replace(hf_name, pd_name)

# add prefix `bert.` if "bert." not in k and "cls." not in k and "classifier" not in k: k = "bert." + k

print(f"Converting: {oldk} => {k} | is_transpose {is_transpose}") paddle_state_dict[k] = v.data.numpy()

paddle.save(paddle_state_dict, paddle_dump_path)

def compare(out_torch, out_paddle): out_torch = out_torch.detach().numpy() out_paddle = out_paddle.detach().numpy() assert out_torch.shape == out_paddle.shape abs_dif = np.abs(out_torch - out_paddle) mean_dif = np.mean(abs_dif) max_dif = np.max(abs_dif) min_dif = np.min(abs_dif) print("mean_dif:{}".format(mean_dif)) print("max_dif:{}".format(max_dif)) print("min_dif:{}".format(min_dif))

def test_forward(): paddle.set_device("cpu") model_torch = PTBertForMaskedLM.from_pretrained("./bert-base-uncased") model_paddle = PDBertForMaskedLM.from_pretrained("./bert-base-uncased") model_torch.eval() model_paddle.eval() np.random.seed(42) x = np.random.randint( 1, model_paddle.bert.config["vocab_size"], size=(4, 64)) input_torch = torch.tensor(x, dtype=torch.int64) out_torch = model_torch(input_torch)[0]

input_paddle = paddle.to_tensor(x, dtype=paddle.int64) out_paddle = model_paddle(input_paddle)[0]

print("torch result shape:{}".format(out_torch.shape)) print("paddle result shape:{}".format(out_paddle.shape)) compare(out_torch, out_paddle)

if __name__ == "__main__": convert_pytorch_checkpoint_to_paddle( "./bert-base-uncased/pytorch_model.bin", "./bert-base-uncased/model_state.pdparams") test_forward() # torch result shape:torch.Size([4, 64, 30522]) # paddle result shape:[4, 64, 30522] # mean_dif:1.666686512180604e-05 # max_dif:0.00015211105346679688 # min_dif:0.0

运行完成之后，会在当前目录生成model_state.pdparams文件，即为转换后的PaddlePaddle预训练模型。Tips: 由于paddlenlp中已有转换后的bert-base-uncased模型，因此可以一键加载，程序会自动下载对应权重！

【基本流程】

【注意事项】

【实战】

BERT模型组网正确性验证可以参考如下示例代码：https://github.com/JunnYu/BERT-SST2-Prod/tree/main/pipeline/Step1

【验收】

对于待复现的项目，前向对齐验收流程如下。

【基本流程】

对于一个数据集，一般有以下一些信息需要重点关注

PaddlePaddle中数据集相关的API为paddle.io.Dataset，PyTorch中对应为torch.utils.data.Dataset，二者功能一致，在绝大多数情况下，可以使用该类构建数据集。它是描述Dataset方法和行为的抽象类，在具体实现的时候，需要继承这个基类，实现其中的__getitem__和__len__方法。除了参考代码中相关实现，也可以参考待复现论文中的说明。

复现完Dataset之后，可以构建Dataloader，对数据进行组batch、批处理，送进网络进行计算。

paddle.io.DataLoader可以进行数据加载，将数据分成批数据，并提供加载过程中的采样。PyTorch对应的实现为torch.utils.data.DataLoader，二者在功能上一致，只是在参数方面稍有diff：（1）PaddlePaddle缺少对pin_memory等参数的支持；（2）PaddlePaddle增加了use_shared_memory参数来选择是否使用共享内存加速数据加载过程。

【注意事项】

论文中一般会提供数据集的名称以及基本信息。复现过程中，我们在下载完数据之后，建议先检查下是否和论文中描述一致，否则可能存在的问题有：

构建数据集时，可以使用PaddleNLP中的数据集加载方式，具体可以参考：如何自定义数据集。对应地，PyTorch中的数据处理api可以参考：huggingface的datasets自定义数据集。对于其中之一，可以找到另一个平台的实现。

此外，

【实战】

BERT模型复现过程中，数据预处理和Dataset、Dataloader的检查可以参考该文件：https://github.com/JunnYu/BERT-SST2-Prod/blob/main/pipeline/Step2/test_data.py

使用方法可以参考数据检查文档。

【基本流程】

PaddlePaddle提供了一系列Metric计算类，比如说Accuracy, Auc, Precision, Recall等，而PyTorch中，目前可以通过组合的方式实现metric计算，或者调用huggingface-datasets，在论文复现的过程中，需要注意保证对于该模块，给定相同的输入，二者输出完全一致。具体流程如下。

【注意事项】

在评估指标对齐之前，需要注意保证对于该模块，给定相同的输入，二者输出完全一致。

【实战】

评估指标对齐检查方法可以参考文档：评估指标对齐检查方法文档

【验收】

对于待复现的项目，评估指标对齐验收流程如下。

【基本流程】

PaddlePaddle与PyTorch均提供了很多loss function，用于模型训练，具体的API映射表可以参考：Loss类API映射列表。以CrossEntropyLoss为例，主要区别为：

如果论文中使用的loss function没有指定的API，则可以尝试通过组合API的方式，实现自定义的loss function。

具体流程如下。

【注意事项】

【实战】

本部分可以参考文档：https://github.com/JunnYu/BERT-SST2-Prod/blob/main/pipeline/Step3/README.md。

【验收】

对于待复现的项目，损失函数对齐验收流程如下。

【基本流程】

PaddlePaddle中的optimizer有paddle.optimizer等一系列实现，PyTorch中则有torch.Optim等一系列实现。

【注意事项】

以SGD等优化器为例，PaddlePaddle与Pytorch的优化器区别主要如下。

【实战】

本部分对齐建议对照PaddlePaddle优化器API文档与参考代码的优化器实现进行对齐，用之后的反向对齐统一验证该模块的正确性。

【基本流程】

【注意事项】

PaddlePaddle中，需要首先构建学习率策略，再传入优化器对象中；对于PyTorch，如果希望使用更丰富的学习率策略，需要先构建优化器，再传入学习率策略类API。

【实战】

学习率复现对齐，可以参考代码：学习率对齐验证文档。

【基本流程】

L2正则化策略用于模型训练，可以防止模型对训练数据过拟合，L1正则化可以用于得到稀疏化的权重矩阵，PaddlePaddle中有paddle.regularizer.L1Decay与paddle.regularizer.L2Decay API。PyTorch中，torch.optim集成的优化器只有L2正则化方法，直接在构建optimizer的时候，传入weight_decay参数即可。

【注意事项】

【实战】

本部分对齐建议对照PaddlePaddle正则化API文档与参考代码的优化器实现进行对齐，用之后的反向对齐统一验证该模块的正确性。

【基本流程】

此处可以通过numpy生成假的数据和label（推荐），也可以准备固定的真实数据。具体流程如下。

【注意事项】

梯度的打印方法示例代码如下所示，注释掉的内容即为打印网络中所有参数的梯度shape。

output = model(input_ids) loss = criterion(output, labels) loss.backward() optimizer.step() optimizer.clear_grad() loss_list.append(loss) return loss_list

【实战】

本部分可以参考文档：反向对齐操作文档。

【验收】

对于待复现的项目，反向对齐验收流程如下。

【基本流程】

该部分内容与3.2节内容基本一致，参考PyTorch的代码，实现训练集数据读取与预处理模块即可。

【注意事项】

该部分内容，可以参考3.8节的自测方法，将输入的fake data & label替换为训练的dataloader，但是需要注意的是：

对于PaddlePaddle来说

【基本流程】

【注意事项】

【实战】

本部分对齐建议对照PaddlePaddle 初始化API文档与参考代码的初始化实现对齐。

【基本流程】

完成前面的步骤之后，就可以开始全量数据的训练对齐任务了。按照下面的步骤进行训练对齐。

【注意事项】

【强烈】建议先做完反向对齐之后再进行模型训练对齐，二者之间的不确定量包括：数据集、PaddlePaddle与参考代码在模型training mode下的区别，初始化参数。

在训练对齐过程中，受到较多随机量的影响，精度有少量diff是正常的，以SST-2数据集的分类为例，diff在0.15%以内可以认为是正常的，这里可以根据不同的任务，适当调整对齐检查的阈值(ReprodDiffHelper.report函数中的diff_threshold参数)。

训练过程中的波动是正常的，如果最终收敛结果不一致，可以

【实战】

本部分可以参考文档：训练对齐操作文档。

【验收】

对于待复现的项目，训练对齐验收流程如下。

如果希望使用单机多卡提升训练效率，可以从以下几个过程对代码进行修改。

对于PaddlePaddle来说，多卡数据读取这块主要的变化在sampler

对于单机单卡，sampler实现方式如下所示。

对于单机多卡任务，sampler实现方式如下所示。

注意：在这种情况下，单机多卡的代码仍然能够以单机单卡的方式运行，因此建议以这种sampler方式进行论文复现。

如果以多卡的方式运行，需要初始化并行训练环境，代码如下所示。

在模型组网并初始化参数之后，需要使用paddle.DataParallel()对模型进行封装，使得模型可以通过数据并行的模式被执行。代码如下所示。

以模型保存为例，我们只需要在0号卡上保存即可，否则多个trainer同时保存的话，可能会造成写冲突，导致最终保存的模型不可用。

对于单机单卡或者单机多卡的启动脚本可以参考：https://github.com/PaddlePaddle/PaddleNLP/tree/develop/examples/language_model/bert

对于单机单卡，启动脚本如下所示

对于单机多卡（示例中为4卡训练），启动脚本如下所示：

注意：这里4卡训练时，虽然单卡的batch size没有变化(32)，但是总卡的batch size相当于是单卡的4倍，因此学习率也设置为了单卡时的4倍。

【实战】

本部分可以参考paddlenlp库中的例子：单机多卡训练。

【基本流程】

完成模型的训练、导出inference、基于PaddleInference的推理过程的文档与代码。参考链接：

基于TIPC基础链条测试接入规范，完成该模型的TIPC基础链条开发以及测试文档/脚本，目录为test_tipc，测试脚本名称为test_train_inference_python.sh，该任务中只需要完成少量数据训练模型，少量数据预测的模式即可，用于测试TIPC流程的模型和少量数据需要放在当前repo中。

【注意事项】

【实战】

TIPC基础链条测试接入用例可以参考：InsightFace-paddle TIPC基础链条测试开发文档。

【验收】

如果遇到Paddle不包含的OP或者API，比如(1) 如果是某些算法实现存在调用了外部OP，而且Paddle也不包含该OP实现；(2) 其他框架存在的API或者OP，但是Paddle中没有这些OP。此时：

PaddlePaddle与PyTorch对于不同名称的API，实现的功能可能是相同的，复现的时候注意，比如paddle.optimizer.lr.StepDecay与torch.optim.lr_scheduler.StepLR ，关于PaddlePaddle与PyTorch更多API的映射关系可以参考：API映射表。

对于PaddlePaddle来说，通过paddle.set_device函数（全局）来确定模型结构是运行在什么设备上，对于torch来说，是通过model.to("device") （局部）来确定模型结构的运行设备，这块在复现的时候需要注意。

def print_hook_fn(grad): print(grad)

x = paddle.to_tensor([0., 1., 2., 3.], stop_gradient=False)h = x.register_hook(print_hook_fn)w = x * 4w.backward()# backward之后会输出下面的内容# Tensor(shape=[4], dtype=float32, place=CPUPlace, stop_gradient=False,# [4., 4., 4., 4.])

有条件的话，复现工作之前最好先基于官方代码完成训练，保证与官方指标能够对齐，并且将训练策略和训练过程中的关键指标记录保存下来，比如每个epoch的学习率、Train Loss、Eval Loss、Eval Acc等，在复现网络的训练过程中，将关键指标保存下来，这样可以将两次训练中关键指标的变化曲线绘制出来，能够很方便的进行对比。

训练过程中可以对loss或者acc进行可视化，和竞品loss或者acc进行直观的对比；如果训练较大的数据集，1次完整训练的成本比较高，此时可以隔一段时间查看一下，如果精度差异比较大，建议先停掉实验，排查原因。

如果训练的过程中出nan，一般是因为除0或者log0的情况， 可以着重看下几个部分：

如果训练过程中如果出现不收敛的情况，可以

https://github.com/PaddlePaddle/