训练与预测：文本匹配

├── data                                                                                    ## 示例数据文件夹，包括各任务所需的训练集、测试集、验证集和预测集
│   ├── dev_data
│   │   └── dev.txt
│   ├── dev_data_tokenized
│   │   └── dev.txt
│   ├── dict
│   │   └── vocab.txt
│   ├── download_data.sh
│   ├── predict_data
│   │   └── infer.txt
│   ├── predict_data_tokenized
│   │   └── infer.txt
│   ├── test_data
│   │   └── test.txt
│   ├── test_data_tokenized
│   │   └── test.txt
│   ├── train_data_pairwise
│   │   └── train.txt
│   ├── train_data_pairwise_tokenized
│   │   └── train.txt
│   └── train_data_pointwise
│       └── train.txt
├── data_set_reader                                                                ## 与匹配任务相关的数据读取代码
│   └── ernie_classification_dataset_reader.py        ## 使用ERNIE的FC匹配任务专用的数据读取代码
├── examples                                                                            ## 各典型网络的json配置文件，infer后缀的为对应的预测配置文件
│   ├── mtch_bow_pairwise_ch_infer.json
│   ├── mtch_bow_pairwise_ch.json
│   ├── mtch_ernie_fc_pointwise_ch_infer.json
│   ├── mtch_ernie_fc_pointwise_ch.json
│   ├── mtch_ernie_pairwise_simnet_ch_infer.json
│   ├── mtch_ernie_pairwise_simnet_ch.json
│   ├── mtch_ernie_pointwise_simnet_ch_infer.json
│   └── mtch_ernie_pointwise_simnet_ch.json
├── inference                                                                            ## 模型预测代码
│   └── custom_inference.py                                                ## 文本匹配任务通用的模型预测代码
├── model                                                                                    ## 文本匹配任务相关的网络文件
│   ├── base_matching.py
│   ├── bow_matching_pairwise.py
│   ├── ernie_matching_fc_pointwise.py
│   ├── ernie_matching_siamese_pairwise.py
│   └── ernie_matching_siamese_pointwise.py
├── run_infer.py                                                                    ## 依靠json进行模型预测的入口脚本
├── run_trainer.py                                                                ## 依靠json进行模型训练的入口脚本
└── trainer                                                                                ## 模型训练和评估代码
    ├── custom_dynamic_trainer.py                                    ## 动态库模式下的模型训练评估代码
    └── custom_trainer.py                                                    ## 静态图模式下的模型训练评估代码

{
  "dataset_reader": {
    "train_reader": {        ## 训练、验证、测试各自基于不同的数据集，数据格式也可能不一样，可以在json中配置不同的reader，此处为训练集的reader。
      "name": "train_reader",
      "type": "ErnieClassificationDataSetReader",        ## 其封装了常见的读取tsv、txt文件、组batch等操作，此处为ERNIE的单塔模型，则采用ErnieClassificationDataSetReader，关于各DataSetReader的区别详见-文心中的基本概念Reader部分。
      "fields": [        ## 域（field）是文心的高阶封装，对于同一个样本存在不同域的时候，不同域有单独的数据类型（文本、数值、整型、浮点型）、单独的词表(vocabulary)等，可以根据不同域进行语义表示，如文本转id等操作，field_reader是实现这些操作的类。
        {
          "name": "text_a",        ## 文本匹配的第一列文本特征域，命名为"text_a"。        
          "data_type": "string",         ## data_type定义域的数据类型，文本域的类型为string，整型数值为int，浮点型数值为float。
          "reader": {"type": "ErnieClassificationFieldReader"},        ## 采用针对文本域的通用reader "CustomTextFieldReader"。数值数组类型域为"ScalarArrayFieldReader"，数值标量类型域为"ScalarFieldReader"，这里的取值是对应FieldReader的类名，关于各个FieldReader的区别详见-文心中的基本概念Reader部分。
          "tokenizer": {
            "type": "FullTokenizer",    ## 指定该文本域的tokenizer为FullTokenizer，type的取值是对应Tokenizer的类名，关于各个Tokenizer的区别详见-文心中的基本概念Reader部分。
            "split_char": " ",        ## 切词之后的明文使用的分隔符在这里设置，默认是通过空格区分不同的token。
            "unk_token": "[UNK]",        ## unk标记为"[UNK]"， 即词表之外的token所对应的默认id，unk必须是词表文件中存在的token。
            "params": null        ## 如果需要一些额外的参数传入tokenizer的时候可以使用该字段。
          },
          "need_convert": true,        ## "need_convert"为true说明数据格式是明文字符串，需要通过词表转换为id。
          "vocab_path": "../../models_hub/ernie_3.0_base_ch_dir/vocab.txt",        ## 指定该文本域的词表，"need_convert"为true时一定要设置。
          "max_seq_len": 512,        ## 设定当前域转为id之后的最大长度。
          "truncation_type": 0,        ## 选择文本超长截断的策略，0为从头开始到最大长度截断，1为从头开始到max_len-1的位置截断，末尾补上最后一个id（词或字），2为保留头和尾两个位置，然后按从头开始到最大长度方式截断。
          "padding_id": 0,        ## 设定padding时对应的id值，文心内部会按batch中的最长文本大小对整个batch中的数据进行padding补齐。
          "embedding": null
        },
        {
          "name": "text_b",        ## 文本匹配的第二列文本特征域，命名为"text_b"，具体配置说明可参考text_a。
          ......
        },
        {
          "name": "label",        ## 文本匹配的第三列标签域，命名为"label"。
          "data_type": "int",    ## 标签是整型数值。
          "reader": {
            "type": "ScalarFieldReader"
          },
          "tokenizer": null,    ## 标签域通常为为单一数值无需分词操作，置为null即可。若您的label是明文文本，且需要分词的话，这里就需要配置对应的tokenizer，规则如上方文本域的tokenizer配置。
          "need_convert": false,    ## 单一数值可无需转换为id，若为明文字符串或需建立映射关系，需要通过词表转换为id。
          "vocab_path": "",
          "max_seq_len": 1,        ## 设定每个域的最大长度，当前例子中的label域是一个int数值，所以最大长度是1。
          "truncation_type": 0,
          "padding_id": 0,
          "embedding": null
        }
      ],
      "config": {
        "data_path": "./data/train_data_pointwise",        ## 训练数据train_reader的数据路径，路径为文件夹目录。
        "shuffle": false,         ## 数据在读取过程中是否需要打乱顺序。
        "batch_size": 8,         ## 超参数之一，表示每个step训练多少个样本。
        "epoch": 5,                     ## 超参数之一，表示该数据集中的数据会被重复训练多少轮。
        "sampling_rate": 1.0,        ## 数据集的采样率
        "need_data_distribute": true,        ## 表示数据读取过程中是否需要按卡数进行分发，true表示每张卡在同一个step中读取到的数据是不一样的，false表示每张卡在同一个step中读取到的数据是一样的，训练集默认为true，测试集、验证集、预测集都是false。
        "need_generate_examples": false        ## 表示在数据读取过程中除了id化好的tensor数据外，是否需要返回原始明文样本。
      }
    },
    "test_reader": {        ## 若要评估测试集，需配置test_reader，其配置方式与train_reader类似， 强烈建议shuffle参数设置为false，epoch参数设置为1。
      ......
        },
    "dev_reader": {        ## 若要评估验证集，需配置dev_reader，其配置方式与train_reader类似， 强烈建议shuffle参数设置为false，epoch参数设置为1。
            ......
    }
  },
    ......
}

{
  "predict_reader": {        ## 预测推理时须配置predict_reader，其配置方式与train_reader类似，需要注意的是，提供的示例无label域，因此predict_reader无需配置label域，强烈建议shuffle参数设置为false，epoch参数设置为1。
      "name": "predict_reader",
      "type": "ErnieClassificationDataSetReader",
      "fields": [
        {
          "name": "text_a",
          ......
        },
        {
          "name": "text_b",
          ......
      ],
      "config": {
        "data_path": "./data/predict_data",        ## 预测数据的数据路径，路径为文件夹目录。
        "shuffle": false,
        "batch_size": 8,
        "epoch": 1,
        "sampling_rate": 1.0,
        "need_data_distribute": false,
        "need_generate_examples": true
      }
    }
}

"model": {
    "type": "BowMatchingPairwise",    ## 文心采用模型(models)的方式定义神经网络的基本操作，本例采用预置的模型BowMatchingPairwise（类名）实现文本匹配，具体网络可参考./models目录。
    "is_dygraph": 1,        ## is_dygraph表示是否采用动态图模式训练，与trainer中的type字段结合使用，is_dygraph=1时，trainer的type必须是动态图trainer，is_dygraph=0时，trainer的type必须是静态图trainer。
    "optimization": {        ## 预置模型的优化器所需的参数配置。
      "learning_rate": 2e-05        ## 学习率
    },
    "vocab_size": 52445                    ## 词表大小，供组网使用，默认为示例词表大小22812，若为采用ERNIE可忽略。
},

"model": {
  "type": "ErnieMatchingFcPointwise",        ## 使用的模型网络类。
    "is_dygraph": 0,
    "optimization": {                                            ## 优化器设置，建议使用文心ERNIE推荐的默认设置。
      "learning_rate": 5e-05,
      "use_lr_decay": true,
      "warmup_steps": 0,
      "warmup_proportion": 0.1,
      "weight_decay": 0.01,
      "use_dynamic_loss_scaling": false,
      "init_loss_scaling": 128,
      "incr_every_n_steps": 100,
      "decr_every_n_nan_or_inf": 2,
      "incr_ratio": 2.0,
      "decr_ratio": 0.8
    },
    "embedding": {                                                ## ERNIE中的embedding参数设置，必填参数。
      "config_path": "../../models_hub/ernie_3.0_base_ch_dir/ernie_config.json"        ## 当前ERNIE模型的配置文件，请填入所采用的ERNIE预训练模型对应的模型配置文件。
    }
}

"trainer": {
  "type": "CustomDynamicTrainer",        ## 表示使用的trainer对应的类名，注意要区分静态图（CustomTrainer）和动态图(CustomDynamicTrainer)。
  "PADDLE_PLACE_TYPE": "gpu",                ## 表示运行时的设备类别，取值为cpu和gpu。
  "PADDLE_IS_FLEET": 0,                            ## 表示是否使用fleetrun模式进行训练，gpu多卡情况下必须设置为1，并使用fleetrun命令进行训练。
  "train_log_step": 10,                            ## 训练时打印训练日志的间隔步数。
  "use_amp": true,                                    ## 是否开启混合精度模式的训练。
  "is_eval_dev": 0,                                    ## 是否在训练的时候评估验证集，1为需评估，此时必须配置dev_reader。
  "is_eval_test": 1,                                ## 是否在训练的时候评估测试集，1为需评估，此时必须配置test_reader。
  "eval_step": 100,                                    ## 进行测试集或验证集评估的间隔步数。
  "save_model_step": 200,                        ## 保存模型时的间隔步数，建议设置为eval_step的整数倍。
  "load_parameters": "",                        ## 加载已训练好的模型的op参数值，不会加载训练步数、学习率等训练参数，可用于加载预训练模型。如需使用填写具体文件夹路径即可。
  "load_checkpoint": "",                        ## 加载已训练好的模型的所有参数，包括学习率等，可用于热启动。如需使用填写具体文件夹路径即可。
  "pre_train_model": [                            ## 加载预训练模型，ERNIE任务的必填参数，非ERNIE任务置为[]即可。
    {
      "name": "ernie_3.0_base_ch",    ## 预训练模型的名称。
      "params_path": "../../models_hub/ernie_3.0_base_ch_dir/params"        ## 预训练模型的参数目录。
    }
  ],
  "output_path": "./output/mtch_ernie_3.0_base_fc_pointwise_ch",                ## 保存模型的输出路径，若为空则默认。为"./output"
  "extra_param": {"meta":{"job_type": "text_matching"}                                    ## 额外的参数信息。
}

"inference": {
  "output_path": "./output/predict_result.txt",    ## 预测结果的输出路径，若为空则默认输出路径为"./output/predict_result.txt"
  "PADDLE_PLACE_TYPE": "gpu",        ## 表示运行时的设备类别，取值为cpu和gpu。
  "num_labels": 2,        ## 表示匹配模型结果的类别数据，用于预测结果解析。
  "thread_num": 1,        ## 预测过程中设置的进程数。
  "inference_model_path": "output/mtch_ernie_3.0_base_fc_pointwise_ch/save_inference_model/inference_step_1251",        ## 待预测的模型路径。
  ......
}

# ernie_3.0_base模型下载
# 进入models_hub目录
cd ./wenxin_appzoo/models_hub
# 运行下载脚本
sh download_ernie_3.0_base_ch.sh

python run_trainer.py --param_path ./examples/mtch_ernie_fc_pointwise_ch.json

python run_infer.py --param_path ./examples/mtch_ernie_fc_pointwise_ch_infer.json