add doc

README.md

@@ -92,6 +92,7 @@ python -u tools/static_trainer.py -m models/rank/dnn/config.yaml #  静态图训
 * [在线Serving部署](doc/serving.md)
 * [python端预测库推理](doc/inference.md)
 * [Benchmark](doc/benchmark.md)
+* [推荐全流程](doc/whole_process.md)
 
 ### FAQ
 * [常见问题FAQ](doc/faq.md)

doc/feature_importance.md

@@ -1,9 +1,9 @@
 # 特征重要性
-本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型为例，介绍如何衡量已保存模型中特征的重要性。
-基本原理是：
-1、加载模型，在固定的测试集上进行预测，得到基线AUC值；
-2、shuffle数据中的某个slot，使该slot中的数据随机化，重新预测得到AUC值；
-3、比较基线AUC和slot_shuffle后的AUC，AUC下降幅度越大，特征越重要。
+本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型为例，介绍如何衡量已保存模型中特征的重要性。  
+基本原理是：  
+1、加载模型，在固定的测试集上进行预测，得到基线AUC值；  
+2、shuffle数据中的某个slot，使该slot中的数据随机化，重新预测得到AUC值；  
+3、比较基线AUC和slot_shuffle后的AUC，AUC下降幅度越大，特征越重要。  
 
 ## 配置
 流式训练配置参见models/rank/slot_dnn/config_offline_infer.yaml，新增配置及作用如下：
@@ -15,8 +15,8 @@
 
 
 ## 使用方法
-请在models/rank/slot_dnn目录下执行如下命令，启动特征重要性衡量脚本。
+请在models/rank/slot_dnn目录下执行如下命令，启动特征重要性衡量脚本。  
 ```bash
 fleetrun --server_num=1 --worker_num=1 ../../../tools/feature_importance.py -m config_offline_infer.yaml
 ```
-日志中首先会对原始数据集进行预测，打印基准AUC；然后依次遍历shots_shuffle_list中的slot或者slot组合，对其进行slot_shuffle，预测后打印出相应的AUC，并计算AUC降幅，用户可通过降幅大小衡量特征的重要性。
+日志中首先会对原始数据集进行预测，打印基准AUC；然后依次遍历shots_shuffle_list中的slot或者slot组合，对其进行slot_shuffle，预测后打印出相应的AUC，并计算AUC降幅，用户可通过降幅大小衡量特征的重要性。  

doc/online_trainer.md

@@ -1,6 +1,6 @@
 # 流式训练
-推荐系统在服务的过程中，会不断产生可用于训练CTR模型的日志数据，流式训练是指数据不是一次性放入训练系统中，而是随着时间流式地加入到训练过程中去。每接收一个分片的数据，模型会对它进行预测，并利用该分片数据增量训练模型，同时按一定的频率保存全量或增量模型。
-本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型使用demo数据为例进行介绍  
+推荐系统在服务的过程中，会不断产生可用于训练CTR模型的日志数据，流式训练是指数据不是一次性放入训练系统中，而是随着时间流式地加入到训练过程中去。每接收一个分片的数据，模型会对它进行预测，并利用该分片数据增量训练模型，同时按一定的频率保存全量或增量模型。  
+本教程以[slot_dnn](../models/rank/slot_dnn/README.md)模型使用demo数据为例进行介绍。  
 
 ## 配置
 流式训练配置参见models/rank/slot_dnn/config_online.yaml，新增配置及作用如下：
@@ -16,8 +16,8 @@
 
 ## 数据
 ### 数据落盘目录格式
-在train_data_dir目录下，再建立两层目录，第一层目录对应训练数据的日期（8位），第二层目录对应训练数据的具体时间（4位，前两位为小时，后两位为分钟），并且需要与配置文件中的split_interval配置对应。
-例如：train_data_dir配置为“data”目录，split_interval配置为5，则具体的目录结构如下：
+在train_data_dir目录下，再建立两层目录，第一层目录对应训练数据的日期（8位），第二层目录对应训练数据的具体时间（4位，前两位为小时，后两位为分钟），并且需要与配置文件中的split_interval配置对应。  
+例如：train_data_dir配置为“data”目录，split_interval配置为5，则具体的目录结构如下：  
 ```txt
 ├── data
     ├── 20190720              # 训练数据的日期
@@ -40,28 +40,30 @@
 
 ## 模型
 流式训练采用静态图参数服务器方式训练，在组网时需要注意几点：
-1、embedding层需使用paddle.static.nn.sparse_embedding，其中size参数的第一维可指定任意值，第二维为embedding向量的维度。
-2、
+1. embedding层需使用paddle.static.nn.sparse_embedding，其中size参数的第一维可指定任意值，第二维为embedding向量的维度。  
+2. 在组网中增加inference_feed_vars、inference_target_var两个变量的赋值，指明inference_model的输入和输出，供线上预测使用。
+3. 在组网中增加all_vars变量的赋值，可用于在线离线一致性检查。
+4. 如果希望在训练过程中dump出组网中的变量和网络参数（主要用于训练中的调试和异常检查），请赋值train_dump_fields和train_dump_params；如果希望在预测过程中dump出组网中的变量（主要用于线上预测所需特征的离线灌库），请赋值infer_dump_fields。
 
 ## 训练
-请在models/rank/slot_dnn目录下执行如下命令，启动流式训练。
+请在models/rank/slot_dnn目录下执行如下命令，启动流式训练。  
 ```bash
 fleetrun --server_num=1 --worker_num=1 ../../../tools/static_ps_online_trainer.py -m config_online.yaml
 ```
-启动后，可以在该目录下的log/workerlog.0文件中查看训练日志。
-正确的训练过程应该包含以下几个部分：
-1、参数初始化：打印config_online.yaml中配置的参数。
-2、获取之前已经训练好的模型并加载模型，如果之前没有保存模型，则跳过加载模型这一步。
-3、循环训练每个pass的数据，其中包括获取训练数据（建立训练数据处理pipe）；利用上个pass的模型预测当前pass的数据，并获取预测AUC；训练当前pass的数据，并获取训练AUC。
-4、保存模型：根据checkpoint_per_pass配置，在固定pass数据训练完成之后，保存模型。
+启动后，可以在该目录下的log/workerlog.0文件中查看训练日志。  
+正确的训练过程应该包含以下几个部分：  
+1. 参数初始化：打印config_online.yaml中配置的参数。  
+2. 获取之前已经训练好的模型并加载模型，如果之前没有保存模型，则跳过加载模型这一步。  
+3. 循环训练每个pass的数据，其中包括获取训练数据（建立训练数据处理pipe）；利用上个pass的模型预测当前pass的数据，并获取预测AUC；训练当前pass的数据，并获取训练AUC。  
+4. 保存模型：根据checkpoint_per_pass配置，在固定pass数据训练完成之后，保存模型。  
 
 ## 模型
-目前流式训练支持保存两种格式的模型。
+目前流式训练支持保存两种格式的模型。  
 ### 全量模型
 全量模型（checkpoint）用于流式训练的热启，具体目录为model_save_path/{$day}/{$pass_id}。
-其中model_save_path为config_online.yaml中的配置，day对应8位日期，pass_id对应流式训练过程中的第几个pass。
-目录下的embedding.shard目录为sparse特征对应的embedding，其中.txt文件为具体的embedding值和优化方法需要的统计量，.meta文件指明.txt文件的具体schema。
-目录下的其他文件为dense参数，文件名即为这些参数在组网中对应的var_name
+其中model_save_path为config_online.yaml中的配置，day对应8位日期，pass_id对应流式训练过程中的第几个pass。  
+目录下的embedding.shard目录为sparse特征对应的embedding，其中.txt文件为具体的embedding值和优化方法需要的统计量，.meta文件指明.txt文件的具体schema。  
+目录下的其他文件为dense参数，文件名即为这些参数在组网中对应的var_name。  
 ### inference_model
-用于线上预测的模型，保存于model_save_path/day/inference_model_{$pass_id}中，分为model、sparse、dense三个部分。
-其中sparse和dense参数与checkpoint模型类似，多出一个名为“__model__”的文件，保存的是在线服务使用的组网（可能经过裁剪），线上服务可以直接加载。
+用于线上预测的模型，保存于model_save_path/day/inference_model_{$pass_id}中，分为model、sparse、dense三个部分。  
+其中sparse和dense参数与checkpoint模型类似，多出一个名为“__model__”的文件，保存的是在线服务使用的组网（可能经过裁剪），线上服务可以直接加载。  

doc/onoff_diff.md

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

doc/whole_process.md

@@ -0,0 +1,22 @@
+# 推荐全流程
+基于推荐场景的技术需求和项目经验，PaddleRec目前已覆盖推荐系统从模型准备到最终线上推理服务的全过程，本教程将索引在推荐全流程中所需的各项功能。 
+
+## 数据准备
+PaddleRec支持多种数据源，包括文件、kafka、odps、tf_record等，具体数据源适配和接入方法参见[数据接入](../tools/dataset/README.md)
+
+## 分布式训练
+由于在推荐系统中，会不断产生用于训练模型的日志数据，因此往往采用流式训练模式，即训练数据不是一次性放入训练系统中，而是随着时间不断加入。流式训练具体内容参见[流式训练](./online_trainer.md)  
+如果你正在做推荐系统的召回模块，可以参考[dssm模型](../models/match/dssm/readme.md)，除了具体的组网实现之外，在进阶教程中还提供了关于召回模块需要的离线灌库和裁剪网络功能。  
+如果你正在做推荐系统的精排模块，可以参考[slot_dnn模型](../models/rank/slot_dnn/README.md)。  
+
+## 特征重要性
+在训练过程中，如果你想要衡量模型中特征的重要性，可以参考[特征重要性](./feature_importance.md)
+
+## 预测
+分布式训练过程中，会保存inference_model用于线上预测。
+1、如果你想要搭建一个独立的预测服务，请参考[Serving部署](./serving.md)
+2、如果你已经拥有一个线上服务，想要在其中增加Paddle的推荐预测内容，请参考[Inference部署](../tools/inference/README.md)
+
+## 在线离线一致性检查
+在线上服务搭建完成，正式投入使用之前，需要进行在线离线一致性检查，确保在线服务的正确性，具体内容参见[在线离线一致性检查](./onoff_diff.md)
+

models/match/dssm/readme.md

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