Skip to content

Commit f59c749

Browse files
frankwhzhangfrankwhzhang
authored
Merge pull request #590 from esythan/master
add doc
2 parents 2973a96 + adcf0bc commit f59c749

File tree

8 files changed

+151
-6
lines changed

8 files changed

+151
-6
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ python -u tools/static_trainer.py -m models/rank/dnn/config.yaml # 静态图训
9292
* [在线Serving部署](doc/serving.md)
9393
* [python端预测库推理](doc/inference.md)
9494
* [Benchmark](doc/benchmark.md)
95+
* [推荐全流程](doc/whole_process.md)
9596

9697
### FAQ
9798
* [常见问题FAQ](doc/faq.md)

‎doc/feature_importance.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# 特征重要性
2+
本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型为例，介绍如何衡量已保存模型中特征的重要性。
3+
基本原理是：
4+
1、加载模型，在固定的测试集上进行预测，得到基线AUC值；
5+
2、shuffle数据中的某个slot，使该slot中的数据随机化，重新预测得到AUC值；
6+
3、比较基线AUC和slot_shuffle后的AUC，AUC下降幅度越大，特征越重要。
7+
8+
## 配置
9+
流式训练配置参见models/rank/slot_dnn/config_offline_infer.yaml，新增配置及作用如下：
10+
| 名称 | 类型 | 取值 | 是否必须 | 作用描述 |
11+
| :---------------------------: | :----------: | :-------------------------------------------------------: | :------: | :------------------------------------------------------------------: |
12+
| init_model_path | string | 任意 | 是 | 已保存的模型路径 |
13+
| shots_shuffle_list | list | 任意 | 是 | 需要衡量的特征列表 |
14+
| candidate_size | int | 任意 | 是 | 需要slot_shuffle的样例个数 |
15+
16+
17+
## 使用方法
18+
请在models/rank/slot_dnn目录下执行如下命令，启动特征重要性衡量脚本。
19+
```bash
20+
fleetrun --server_num=1 --worker_num=1 ../../../tools/feature_importance.py -m config_offline_infer.yaml
21+
```
22+
日志中首先会对原始数据集进行预测，打印基准AUC；然后依次遍历shots_shuffle_list中的slot或者slot组合，对其进行slot_shuffle，预测后打印出相应的AUC，并计算AUC降幅，用户可通过降幅大小衡量特征的重要性。

‎doc/imgs/whole_process.png‎

342 KB
Loading

‎doc/online_trainer.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# 流式训练
2+
推荐系统在服务的过程中，会不断产生可用于训练CTR模型的日志数据，流式训练是指数据不是一次性放入训练系统中，而是随着时间流式地加入到训练过程中去。每接收一个分片的数据，模型会对它进行预测，并利用该分片数据增量训练模型，同时按一定的频率保存全量或增量模型。
3+
本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型使用demo数据为例进行介绍。
4+
5+
## 配置
6+
流式训练配置参见models/rank/slot_dnn/config_online.yaml，新增配置及作用如下：
7+
| 名称 | 类型 | 取值 | 是否必须 | 作用描述 |
8+
| :---------------------------: | :----------: | :-------------------------------------------------------: | :------: | :------------------------------------------------------------------: |
9+
| split_interval | int | 任意 | 是 | 数据落盘分片间隔时间（分钟） |
10+
| split_per_pass | int | 任意 | 是 | 训练一个pass包含多少个分片的数据 |
11+
| start_day | string | 任意 | 是 | 训练开始的日期（例：20190720） |
12+
| end_day | string | 任意 | 是 | 训练结束的日期（例：20190720） |
13+
| checkpoint_per_pass | int | 任意 | 是 | 训练多少个pass保存一个模型（模型保存的频率） |
14+
| data_donefile | string | 任意 | 否 | 用于探测当前分片数据是否落盘完成的标识文件 |
15+
| data_sleep_second | int | 任意 | 否 | 当前分片数据尚未完成的等待时间 |
16+
17+
## 数据
18+
### 数据落盘目录格式
19+
在train_data_dir目录下，再建立两层目录，第一层目录对应训练数据的日期（8位），第二层目录对应训练数据的具体时间（4位，前两位为小时，后两位为分钟），并且需要与配置文件中的split_interval配置对应。
20+
例如：train_data_dir配置为“data”目录，split_interval配置为5，则具体的目录结构如下：
21+
```txt
22+
├── data
23+
├── 20190720 # 训练数据的日期
24+
├── 0000 # 训练数据的时间（第1个分片）
25+
├── data_part1 # 具体的训练数据文件
26+
├── ......
27+
├── 0005 # 训练数据的时间（第2个分片）
28+
├── data_part1 # 具体的训练数据文件
29+
├── ......
30+
├── 0010 # 训练数据的时间（第3个分片）
31+
├── data_part1 # 具体的训练数据文件
32+
├── ......
33+
├── ......
34+
├── 2355 # 训练数据的时间（该日期下最后1个分片）
35+
├── data_part1 # 具体的训练数据文件
36+
├── ......
37+
```
38+
### 数据等待方式
39+
开启配置中的data_donefile后，当数据目录中存在data_donefile配置对应的文件（一般是一个空文件）时，才会对该目录下的数据执行后续操作，否则，等待data_sleep_second时间后，重新探测是否存在data_donefile文件。
40+
41+
## 模型
42+
流式训练采用静态图参数服务器方式训练，在组网时需要注意几点：
43+
1. embedding层需使用paddle.static.nn.sparse_embedding，其中size参数的第一维可指定任意值，第二维为embedding向量的维度。
44+
2. 在组网中增加inference_feed_vars、inference_target_var两个变量的赋值，指明inference_model的输入和输出，供线上预测使用。
45+
3. 在组网中增加all_vars变量的赋值，可用于在线离线一致性检查。
46+
4. 如果希望在训练过程中dump出组网中的变量和网络参数（主要用于训练中的调试和异常检查），请赋值train_dump_fields和train_dump_params；如果希望在预测过程中dump出组网中的变量（主要用于线上预测所需特征的离线灌库），请赋值infer_dump_fields。
47+
48+
## 训练
49+
请在models/rank/slot_dnn目录下执行如下命令，启动流式训练。
50+
```bash
51+
fleetrun --server_num=1 --worker_num=1 ../../../tools/static_ps_online_trainer.py -m config_online.yaml
52+
```
53+
启动后，可以在该目录下的log/workerlog.0文件中查看训练日志。
54+
正确的训练过程应该包含以下几个部分：
55+
1. 参数初始化：打印config_online.yaml中配置的参数。
56+
2. 获取之前已经训练好的模型并加载模型，如果之前没有保存模型，则跳过加载模型这一步。
57+
3. 循环训练每个pass的数据，其中包括获取训练数据（建立训练数据处理pipe）；利用上个pass的模型预测当前pass的数据，并获取预测AUC；训练当前pass的数据，并获取训练AUC。
58+
4. 保存模型：根据checkpoint_per_pass配置，在固定pass数据训练完成之后，保存模型。
59+
60+
## 模型
61+
目前流式训练支持保存两种格式的模型。
62+
### 全量模型
63+
全量模型（checkpoint）用于流式训练的热启，具体目录为model_save_path/{$day}/{$pass_id}。
64+
其中model_save_path为config_online.yaml中的配置，day对应8位日期，pass_id对应流式训练过程中的第几个pass。
65+
目录下的embedding.shard目录为sparse特征对应的embedding，其中.txt文件为具体的embedding值和优化方法需要的统计量，.meta文件指明.txt文件的具体schema。
66+
目录下的其他文件为dense参数，文件名即为这些参数在组网中对应的var_name。
67+
### inference_model
68+
用于线上预测的模型，保存于model_save_path/day/inference_model_{$pass_id}中，分为model、sparse、dense三个部分。
69+
其中sparse和dense参数与checkpoint模型类似，多出一个名为“__model__”的文件，保存的是在线服务使用的组网（可能经过裁剪），线上服务可以直接加载。

‎doc/onoff_diff.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# 在线离线一致性检查
2+
在线上服务搭建完成之后，为保证正确性，需要对同一批数据进行在线和离线预测，并对比结果，结果一致，才能启动线上服务。
3+
需要注意的是，在线/离线两个环境，预测的数据、加载的模型需保持一致。
4+
5+
## 在线预测
6+
参见在线预测模块(tools/inference)。
7+
需要开启debug模式，数据预测过程中打印每一层的输出tensor。
8+
如果线上预测是通过kv存储获取embedding向量，则还需要将预测数据中的所有feasign对应的embedding输出到文件中。
9+
10+
## 离线预测
11+
如果sparse embedding过大，离线预测无法单机进行，则需要从线上拿到预测数据所有feasign对应的embedding，并转换成离线能够加载的模型格式，这部分操作在get_xbox_model.py脚本中进行。
12+
离线预测使用tools/static_ps_offline_infer.py脚本，开启dump功能，打印每一层的输出tensor。
13+
14+
## 一致性检查
15+
得到在线/离线的预测结果之后，使用onoff_diff.py进行一致性检查。
16+
17+
## 具体操作
18+
本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型为例，介绍在线离线一致性检查的具体操作
19+
1. 启动前准备：
20+
准备预测数据，放入在线环境相应位置及离线slot_dnn目录的infer_data/online下，同时在离线slot_dnn目录中建立infer_data/offline空文件夹
21+
将离线训练好的模型cp到在线环境中（包括slot_dnn目录下的all_vars.txt文件及模型保存目录下的model和参数文件）
22+
2. 启动在线预测：生成cube.result及std.log文件
23+
3. 将上述两个文件cp至tools/onoff_diff/data文件夹下，std.log重命名为log.online
24+
4. 在tools/onoff_diff目录下运行sh run.sh，完成离线预测及在线离线一致性检查工作

‎doc/whole_process.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 推荐全流程
2+
基于推荐场景的技术需求和项目经验，PaddleRec目前已覆盖推荐系统从模型准备到最终线上推理服务的全过程，具体内容参见下图：
3+
<p align="center">
4+
<img align="center" src="./imgs/whole_process.png">
5+
<p>
6+
7+
1. 线上服务产生的日志，拼接后落盘到存储上形成数据源，数据经过处理进入离线分布式训练系统。
8+
2. 训练过程持续产生用于线上预测服务的向量库及模型。
9+
3. 离线训练产生的向量灌入在线服务向量库，模型配送到线上，经过在线离线一致性检查后，在线预测服务即可投入使用。
10+
11+
## 数据准备
12+
PaddleRec支持多种数据源，包括文件、kafka、odps、tf_record等，具体数据源适配和接入方法参见[数据接入](../tools/dataset/README.MD)
13+
14+
## 分布式训练
15+
由于在推荐系统中，会不断产生用于训练模型的日志数据，因此往往采用流式训练模式，即训练数据不是一次性放入训练系统中，而是随着时间不断加入。流式训练具体内容参见[流式训练](./online_trainer.md)
16+
1. 如果你正在做推荐系统的召回模块，可以参考[dssm模型](../models/match/dssm/readme.md)，除了具体的组网实现之外，在进阶教程中还提供了关于召回模块需要的离线灌库和裁剪网络功能。
17+
2. 如果你正在做推荐系统的精排模块，可以参考[slot_dnn模型](../models/rank/slot_dnn/README.md)。
18+
19+
## 特征重要性
20+
在训练过程中，如果你想要衡量模型中特征的重要性，可以参考[特征重要性](./feature_importance.md)
21+
22+
## 预测
23+
分布式训练过程中，会保存inference_model用于线上预测。
24+
1. 如果你想要搭建一个独立的预测服务，请参考[Serving部署](./serving.md)
25+
2. 如果你已经拥有一个线上服务，想要在其中增加Paddle的推荐预测内容，请参考[Inference部署](../tools/inference/README.md)
26+
27+
## 在线离线一致性检查
28+
在线上服务搭建完成，正式投入使用之前，需要进行在线离线一致性检查，确保在线服务的正确性，具体内容参见[在线离线一致性检查](./onoff_diff.md)

‎models/match/dssm/readme.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,8 @@ bash run.sh #动态图训练并测试，最后得到指标
105105
```
106106

107107
## 进阶使用
108-
DSSM作为推荐系统中一种向量召回的方式，一般需要将doc侧的向量预先计算出来，灌入向量搜索引擎（例如milvus）中，同时保存的模型仅为query侧的模型。线上使用阶段，输入query侧的数据，计算出query侧向量后，直接通过向量搜索引擎召回对应的doc。
109-
一般在训练的过程中，增加预测阶段，dump出全量的doc侧向量，需要做如下修改：
108+
DSSM作为推荐系统中一种向量召回的方式，一般需要将doc侧的向量预先计算出来，灌入向量搜索引擎（例如milvus）中，同时保存的模型仅为query侧的模型。线上使用阶段，输入query侧的数据，计算出query侧向量后，直接通过向量搜索引擎召回对应的doc。
109+
一般在训练的过程中，增加预测阶段，dump出全量的doc侧向量，需要做如下修改：
110110
1. 为了区分dump出的向量，预测阶段使用的数据需要增加insid和content两个字段，其中insid唯一标记样本，content指明对应的doc。并在数据处理脚本中对这两个字段进行解析，详见bq_reader_train_insid.py脚本。
111111
2. dataset选择InmemoryDataset，同时设置
112112
```python

‎tools/readme.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# PaddleRec小工具
22

3-
本目录下包含了paddlerec的各种训练模式的核心代码，以及经常用到的一些工具脚本。
3+
本目录下包含了paddlerec的各种训练模式的核心代码，以及经常用到的一些工具脚本。
44

55
## 工具简介
66

@@ -13,11 +13,12 @@
1313
| static_ps_trainer.py | static_ps_trainer.py是基于参数服务器模式(ParameterServer)的分布式训练相关代码，目前仅支持使用静态图的方式训练 | 可以支持在linux环境下从任意目录通过相对路径启动。 | 支持在任意目录下运行，以dnn模型为示例，在PaddleRec根目录中运行的命令为：fleetrun --worker_num=1 --server_num=1 tools/static_ps_trainer.py -m models/rank/dnn/config.yaml |
1414
| static_gpubox_trainer.py | static_gpubox_trainer.py是基于异构参数服务器纯GPU模式(ParameterServer)的分布式训练相关代码，目前仅支持使用静态图的方式训练 | 可以支持在linux环境下从任意目录通过相对路径启动。 | 支持在任意目录下运行，以dnn模型为示例，在PaddleRec根目录中运行的命令为：sh tools/run_gpubox.sh 。详细可参考[GPUBOX原理与使用](https://fleet-x.readthedocs.io/en/latest/paddle_fleet_rst/parameter_server/performance/heterps.html) |
1515
| cal_pos_neg.py | 输入一个文件，文件中包含以"tab"分割的查询内容(query)，模型计算正负例的相似度(sim)和真实标签(label)，计算正逆序比(正序率)的脚本 | 可以在windows/linux/macos环境下从任意目录通过相对路径启动 | 支持在任意目录下运行，以dssm模型为示例，在dssm模型目录中运行的命令为：python ../../../tools/cal_pos_neg.py pair.txt |
16-
| feature_importance.py | -- | -- | -- |
16+
| feature_importance.py | 模型特征重要性衡量工具 | 可以在linux环境下从任意目录通过相对路径启动 | 具体用法见[特征重要性](../doc/feature_importance.md) |
1717
| paddle_infer.py | 使用python版本的预测库进行推理 | 可以支持在linux环境下启动 | 具体用法见[python端预测库推理](../doc/inference.md) |
18-
| ps_online_trainer.py | -- | -- | -- |
1918
| rec_client.py | 在服务器端启动serving服务成功后，部署客户端 | 可以支持在linux环境下启动 | 具体用法见[在线Serving部署](../doc/serving.md) |
20-
| static_ps_online_trainer.py | -- | -- | -- |
19+
| static_ps_online_trainer.py | 流式训练 | 可以在linux环境下从任意目录通过相对路径启动 | 具体用法见[流式训练](../doc/online_trainer.md) |
20+
| static_ps_offline_infer.py | 基于参数服务器(ParameterServer)模式的分布式预测相关代码，目前仅支持使用静态图的方式预测 | 可以在linux环境下从任意目录通过相对路径启动 | 支持在任意目录下运行，以slot_dnn模型为示例，在PaddleRec根目录中运行的命令为：fleetrun --worker_num=1 --server_num=1 tools/static_ps_offline_infer.py -m models/rank/slot_dnn/config_offline_infer.yaml |
2121
| to_static.py | 动态图保存下来的模型模型转化为静态图进行inference | 可以支持在linux环境下启动 | 具体用法见[python端预测库推理](../doc/inference.md) |
2222
| webserver.py | 使用web方式启动serving服务端 | 可以支持在linux环境下启动 | 具体用法见[在线Serving部署](../doc/serving.md) |
23+
| onoff_diff | 在线离线一致性检查 | 可以在linux环境下从任意目录通过相对路径启动 | 具体用法见[在线离线一致性检查](../doc/onoff_diff.md) |
2324

0 commit comments

Comments
 (0)