diff --git a/README.md b/README.md index 47eaae5d3549c30d198090d0082dbffb40d1680d..962108ea1e63c841640b6838513fc6d87effe69b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# PALM +# PaddlePALM -PALM (PAddLe for Multi-task) 是一个强大快速、灵活易用的NLP多任务学习框架,用户仅需书写极少量代码即可完成复杂的多任务训练与推理。同时框架提供了定制化接口,若内置工具、主干网络和任务无法满足需求,开发者可以轻松完成相关组件的自定义。 +PaddlePALM (PAddLe for Multi-task) 是一个强大快速、灵活易用的NLP多任务学习框架,用户仅需书写极少量代码即可完成复杂的多任务训练与推理。同时框架提供了定制化接口,若内置工具、主干网络和任务无法满足需求,开发者可以轻松完成相关组件的自定义。 框架中内置了丰富的主干网络及其预训练模型(BERT、ERNIE等)、常见的任务范式(分类、匹配、机器阅读理解等)和相应的数据集读取与处理工具。相关列表见这里。 @@ -16,7 +16,7 @@ pip install paddlepalm ```shell git clone https://github.com/PaddlePaddle/PALM.git -cd PALM && python setup.py +cd PALM && python setup.py install ``` @@ -46,21 +46,23 @@ cd PALM && python setup.py #### 模型准备 -我们提供了ERNIE作为框架默认的主干模型,为了加速模型收敛,获得更佳的测试集表现,我们强烈建议用户在预训练模型的基础上进行多任务学习(而不是从参数随机初始化开始)。用户可通过运行脚本`script/download_pretrain_models`下载需要的预训练模型,下载预训练ERNIE的命令如下 +我们提供了BERT、ERNIE等主干模型及其相关预训练模型。为了加速模型收敛,获得更佳的测试集表现,我们强烈建议用户在预训练模型的基础上进行多任务学习(而不是从参数随机初始化开始)。用户可通过运行脚本`script/download_pretrain_models`下载需要的预训练模型,例如,下载预训练BERT模型的命令如下 ```shell -bash script/download_pretrain_backbone.sh ernie +bash script/download_pretrain_backbone.sh bert ``` -然后通过`script/convert_params.sh`将预训练模型转换成框架可用的预训练backbone +脚本会自动在当前文件夹中创建一个pretrain_model目录,并在其中创建bert子目录,里面存放预训练模型(`params`文件夹内)、相关的网络参数(`bert_config.json`)和字典(`vocab.txt`)。 -```python -bash script/convert_params.sh pretrain_model/ernie/params +然后通过运行`script/convert_params.sh`将预训练模型转换成框架可用的预训练backbone + +```shell +bash script/convert_params.sh pretrain_model/bert/params ``` -*注:目前框架还支持BERT作为主干模型,未来将支持更多的预置主干网络,如XLNet、多层LSTM等。* +*注:未来框架将支持更多的预置主干网络,如XLNet、多层LSTM等。此外,用户可以自定义添加新的主干网络,详情见[这里]()* -## 启动单任务训练 +## DEMO1:单任务训练 接下来我们启动一个复杂的机器阅读理解任务的训练,我们在`data/mrqa`文件夹中提供了EMNLP2019 MRQA机器阅读理解评测的部分比赛数据。 @@ -71,18 +73,19 @@ bash run_demo1.sh ``` - 下面以该任务为例,讲解如何基于paddlepalm框架轻松实现该任务。 -首先,我们编写该任务实例的配置文件`mrqa.yaml`,框架将自动解析该配置文件并创建相应的任务实例。配置文件需符合yaml格式的要求。一个任务实例的配置文件最少应包含`train_file`,`reader`和`paradigm`这三个字段,分别代表训练集的文件路径`train_file`、使用的数据集载入与处理工具`reader`、任务范式`paradigm`。 +**1. 配置任务实例** + +首先,我们编写该任务实例的配置文件`mrqa.yaml`,若该任务实例参与训练或预测,则框架将自动解析该配置文件并创建相应的任务实例。配置文件需符合yaml格式的要求。一个任务实例的配置文件最少应包含`train_file`,`reader`和`paradigm`这三个字段,分别代表训练集的文件路径`train_file`、使用的数据集载入与处理工具`reader`、任务范式`paradigm`。 ```yaml train_file: data/mrqa/mrqa-combined.train.raw.json -reader: mrc4ernie +reader: mrc4ernie # 我们接下来会使用ERNIE作为主干网络,因此使用ernie配套的数据集处理工具mrc4ernie paradigm: mrc ``` -*注:框架内置的其他数据集载入与处理工具和任务范式列表见这里* +*注:框架内置的其他数据集载入与处理工具和任务范式列表见[这里]()* 此外,我们还需要配置reader的预处理规则,各个预置reader支持的预处理配置和规则请参考【这里】。预处理规则同样直接写入`mrqa.yaml`中。 @@ -94,6 +97,10 @@ do_lower_case: True vocab_path: "pretrain_model/ernie/vocab.txt" ``` +更详细的任务实例配置方法可参考这里 + +**2.配置全局参数** + 然后我们配置全局的学习规则,同样使用yaml格式描述,我们新建`mtl_conf.yaml`。在这里我们配置一下需要学习的任务、模型的保存路径`save_path`和规则、使用的模型骨架`backbone`、学习器`optimizer`等。 ```yaml @@ -112,9 +119,11 @@ num_epochs: 2 warmup_proportion: 0.1 ``` -*注:框架支持的其他backbone参数如日志打印控制等见这里* +*注:框架支持的其他backbone参数如日志打印控制等见[这里]()* + +**3.开始训练** -而后我们就可以启动MRQA任务的训练了(该代码位于`demo1.py`中)。 +下面我们开始尝试启动MRQA任务的训练(该代码位于`demo1.py`中)。框架的核心组件是`Controller`, ```python # Demo 1: single task training of MRQA @@ -128,7 +137,7 @@ if __name__ == '__main__': -## 启动多任务训练 +## DEMO2:多任务训练 本节我们考虑更加复杂的学习目标,我们引入一个问答匹配(QA Matching)任务来辅助MRQA任务的学习。在多任务训练结束后,我们希望使用训练好的模型来对MRQA任务的测试集进行预测。 @@ -152,6 +161,8 @@ reader: match4ernie paradigm: match ``` +*注:更详细的任务实例配置方法可参考[这里]()* + **2.配置全局参数** 由于MRQA和Matching任务有相同的字典、大小写配置、截断长度等,因此我们可以将这些各个任务中相同的参数写入到全局配置文件`mtl_config.yaml`中,**框架会自动将该文件中的配置广播(broadcast)到各个任务实例。** @@ -179,7 +190,7 @@ weight_decay: 0.1 这里我们可以使用`target_tag`来标记目标任务和辅助任务,各个任务的tag使用逗号`,`隔开。target_tag与task_instance中的元素一一对应,当某任务的tag设置为1时,表示对应的任务被设置为目标任务;设置为0时,表示对应的任务被设置为辅助任务,默认情况下所以任务均被设置为目标任务(即默认`target_tag`为全1)。 -辅助任务不会保存推理模型,且不会影响训练的终止。当所有的目标任务达到预期的训练步数后多任务学习终止,框架自动为每个目标任务保存推理模型(inference model)到设置的`save_path`位置。 +辅助任务不会保存预测模型,且不会影响训练的终止。当所有的目标任务达到预期的训练步数后多任务学习终止,框架自动为每个目标任务保存预测模型(inference model)到设置的`save_path`位置。 在训练过程中,默认每个训练step会从各个任务等概率采样,来决定当前step训练哪个任务。若用户希望改变采样比率,可以通过`mix_ratio`字段来进行设置,例如 @@ -205,14 +216,29 @@ if __name__ == '__main__': **4.预测** +在得到目标任务的预测模型(inference_model)后,我们可以加载预测模型对该任务的测试集进行预测。在多任务训练阶段,在全局配置文件的`save_path`指定的路径下会为每个目标任务创建同名子目录,子目录中都有预测模型文件夹`infermodel`。我们可以将该路径传给框架的`controller`来完成对该目标任务的预测。 + +例如,我们在上一节得到了mrqa任务的预测模型。首先创建一个新的*Controller*,**并且创建时要将`for_train`标志位置为*False***。而后调用*pred*接口,将要预测的任务实例名字和预测模型的路径传入,即可完成相关预测。预测的结果默认保存在任务实例配置文件的`pred_output_path`指定的路径中。代码段如下: + ```python controller = palm.Controller(config='demo2_config.yaml', task_dir='demo2_tasks', for_train=False) - controller.pred('mrqa', inference_model_dir='output_model/secondrun/infer_model') + controller.pred('mrqa', inference_model_dir='output_model/secondrun/mrqa/infermodel') ``` + ## 进阶篇 -### 设置辅助任务 +### 设置多个目标任务 + +框架内支持设定多个目标任务,当全局配置文件的`task_instance`字段指定超过一个任务实例时,这多个任务实例默认均为目标任务(即`target_tag`字段被自动填充为全1)。对于被设置成目标任务的任务实例,框架会为其计算预期的训练步数(详情见下一节)并在达到预期训练步数后为其保存预测模型。 + +当框架存在多个目标任务时,全局配置文件中的`num_epochs`(训练集遍历次数)仅会作用于第一个出现的目标任务,称为主任务(main task)。框架会根据主任务的训练步数来推理其他目标任务的预期训练步数(可通过`mix_ratio`控制)。**注意,除了用来标记`num_epochs`的作用对象外,主任务与其他目标任务没有任何不同。**例如 + +```yaml +task_instance: domain_cls, mrqa, senti_cls, mlm, qq_match +target_tag: 0, 1, 1, 0, 1 +``` +在上述的设置中,mrqa,senti_cls和qq_match这三个任务被标记成了目标任务(其中mrqa为主任务),domain_cls和mlm被标记为了辅助任务。辅助任务仅仅“陪同”目标任务训练,框架不会为其保存预测模型(inference_model),也不会计算预期训练步数。但包括辅助任务在内,各个任务的采样概率是可以被控制的,详情见下一小节。 ### 更改任务采样概率(期望的训练步数)