Merge branch 'master' into bug_fix

690d7be2 · tangwei12 · GitHub · 07f9c21f · 3cd0fd19 · 690d7be2
16 changed file
--- a/README.md
+++ b/README.md
 <p align="center">
 <img align="center" src="doc/imgs/logo.png">
 <p>
 <p align="center">
-    <br>
+<img align="center" src="doc/imgs/structure.png">
-    <img alt="Release" src="https://img.shields.io/badge/Release-0.1.0-yellowgreen">
+<p>
-    <img alt="License" src="https://img.shields.io/github/license/PaddlePaddle/Serving">
+<p align="center">
-    <img alt="Slack" src="https://img.shields.io/badge/Join-Slack-green">
+<img align="center" src="doc/imgs/overview.png">
-    <br>
 <p>
-<h2 align="center">什么是PaddleRec</h2>
+<h2 align="center">什么是推荐系统?</h2>
 <p align="center">
-<img align="center" src="doc/imgs/structure.png">
+<img align="center" src="doc/imgs/rec-overview.png">
 <p>
- 源于飞桨生态的搜索推荐模型**一站式开箱即用工具** 
+- 推荐系统是在互联网信息爆炸式增长的时代背景下，帮助用户高效获得感兴趣信息的关键；
- 适合初学者，开发者，研究者从调研，训练到预测部署的全流程解决方案
- 包含语义理解、召回、粗排、精排、多任务学习、融合等多个任务的推荐搜索算法库
- 配置**yaml**自定义选项，即可快速上手使用单机训练、大规模分布式训练、离线预测、在线部署
+- 推荐系统也是帮助产品最大限度吸引用户、留存用户、增加用户粘性、提高用户转化率的银弹。
-<h2 align="center">PadlleRec概览</h2>
+- 有无数优秀的产品依靠用户可感知的推荐系统建立了良好的口碑，也有无数的公司依靠直击用户痛点的推荐系统在行业中占领了一席之地。
-<p align="center">
+  > 可以说，谁能掌握和利用好推荐系统，谁就能在信息分发的激烈竞争中抢得先机。
-<img align="center" src="doc/imgs/overview.png">
+  > 但与此同时，有着许多问题困扰着推荐系统的开发者，比如：庞大的数据量，复杂的模型结构，低效的分布式训练环境，波动的在离线一致性，苛刻的上线部署要求，以上种种，不胜枚举。
-<p>
+<h2 align="center">什么是PaddleRec?</h2>
-<h2 align="center">推荐系统-流程概览</h2>
-<p align="center">
+- 源于飞桨生态的搜索推荐模型 **一站式开箱即用工具** 
-<img align="center" src="doc/imgs/rec-overview.png">
+- 适合初学者，开发者，研究者的推荐系统全流程解决方案
-<p>
+- 包含内容理解、匹配、召回、排序、 多任务、重排序等多个任务的完整推荐搜索算法库
+    |   方向   |                                   模型                                    | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 |
+    | :------: | :-----------------------------------------------------------------------: | :---------: | :---------: | :-----------: |
+    | 内容理解 | [Text-Classifcation](models/contentunderstanding/classification/model.py) |      ✓      |      x      |       ✓       |
+    | 内容理解 |         [TagSpace](models/contentunderstanding/tagspace/model.py)         |      ✓      |      x      |       ✓       |
+    |   召回   |                    [DSSM](models/match/dssm/model.py)                     |      ✓      |      x      |       ✓       |
+    |   召回   |        [MultiView-Simnet](models/match/multiview-simnet/model.py)         |      ✓      |      x      |       ✓       |
+    |   召回   |                   [TDM](models/treebased/tdm/model.py)                    |      ✓      |      x      |       ✓       |
+    |   召回   |                [Word2Vec](models/recall/word2vec/model.py)                |      ✓      |      x      |       ✓       |
+    |   召回   |                     [SSR](models/recall/ssr/model.py)                     |      ✓      |      ✓      |       ✓       |
+    |   召回   |                 [Gru4Rec](models/recall/gru4rec/model.py)                 |      ✓      |      ✓      |       ✓       |
+    |   召回   |             [Youtube_dnn](models/recall/youtube_dnn/model.py)             |      ✓      |      ✓      |       ✓       |
+    |   召回   |                     [NCF](models/recall/ncf/model.py)                     |      ✓      |      ✓      |       ✓       |
+    |   排序   |                      [Dnn](models/rank/dnn/model.py)                      |      ✓      |      x      |       ✓       |
+    |   排序   |                   [DeepFM](models/rank/deepfm/model.py)                   |      ✓      |      x      |       ✓       |
+    |   排序   |                  [xDeepFM](models/rank/xdeepfm/model.py)                  |      ✓      |      x      |       ✓       |
+    |   排序   |                      [DIN](models/rank/din/model.py)                      |      ✓      |      x      |       ✓       |
+    |   排序   |                [Wide&Deep](models/rank/wide_deep/model.py)                |      ✓      |      x      |       ✓       |
+    |  多任务  |                  [ESMM](models/multitask/esmm/model.py)                   |      ✓      |      ✓      |       ✓       |
+    |  多任务  |                  [MMOE](models/multitask/mmoe/model.py)                   |      ✓      |      ✓      |       ✓       |
+    |  多任务  |           [ShareBottom](models/multitask/share-bottom/model.py)           |      ✓      |      ✓      |       ✓       |
+    |  重排序  |                [Listwise](models/rerank/listwise/model.py)                |      ✓      |      x      |       ✓       |
-<h2 align="center">便捷安装</h2>
+<h2 align="center">快速安装</h2>
 ### 环境要求
 * Python 2.7/ 3.5 / 3.6 / 3.7
 * PaddlePaddle  >= 1.7.2
 * 操作系统: Windows/Mac/Linux
-  > Windows下目前仅提供单机训练，建议使用Linux
+  > Windows下目前仅提供单机训练，建议分布式使用Linux
 ### 安装命令
@@ -55,7 +76,7 @@
 - 安装方法二
  源码编译安装
-  1. 安装飞桨  **注：需要用户安装版本 >1.7.2 的飞桨**
+  1. 安装飞桨  **注：需要用户安装版本 >=1.7.2 的飞桨**
    ```shell
    python -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
@@ -70,139 +91,41 @@
    ```
-<h2 align="center">快速启动</h2>
+<h2 align="center">一键启动</h2>
-### 启动内置模型的默认配置
-目前框架内置了多个模型，一行命令即可使用内置模型开始单机训练和本地模拟分布式训练。
+我们以排序模型中的`dnn`模型为例介绍PaddleRec的一键启动。训练数据来源为[Criteo数据集](https://www.kaggle.com/c/criteo-display-ad-challenge/)，我们从中截取了100条数据：
-  > 本地模拟分布式(`local_cluster`)为`1个server + 1个trainer`的参数服务器模式
-我们以排序模型中的`dnn`模型为例介绍PaddleRec的简单使用。训练数据来源为[Criteo数据集](https://www.kaggle.com/c/criteo-display-ad-challenge/)，我们从中截取了100条方便您快速上手体验完整的PaddleRec流程。
 ```bash
 # 使用CPU进行单机训练
 python -m paddlerec.run -m paddlerec.models.rank.dnn  
 ```
-### 启动内置模型的自定配置
-若您复用内置模型，对**yaml**配置文件进行了修改，如更改超参，重新配置数据后，可以直接使用paddlerec运行该yaml文件。
-我们以dnn模型为例，在paddlerec代码目录下:
-```bash
-cd paddlerec
-```
-修改dnn模型的[超参配置](./models/rank/dnn/config.yaml)，例如将迭代训练轮数从10轮修改为5轮:
-```yaml
-runner:
- name: runner1
-  class: single_train
-  epochs: 5 # 10->5
-```
-在Linux环境下，可以使用`vim`等文本编辑工具修改yaml文件：
-```bash
-vim ./models/rank/dnn/config.yaml
-# 键入 i, 进入编辑模式
-# 修改yaml文件配置
-# 完成修改后，点击esc，退出编辑模式
-# 键入 :wq 保存文件并退出 
-```
-完成dnn模型`models/rank/dnn/config.yaml`的配置修改后，运行`dnn`模型：
-```bash
-# 使用自定配置进行训练
-python -m paddlerec.run -m ./models/rank/dnn/config.yaml 
-```
-### 分布式训练
+<h2 align="center">帮助文档</h2>
-分布式训练需要配置`config.yaml`，加入或修改`engine`选项为`cluster`或`local_cluster`，以进行分布式训练，或本地模拟分布式训练。
+### 项目背景
-#### 本地模拟分布式训练
-我们以dnn模型为例，在paddlerec代码目录下，修改dnn模型的`config.yaml`文件:
-```yaml
-runner:
- name: runner1
-  class: local_cluster_train # single_train -> local_cluster_train
-```
-然后启动paddlerec训练：
-```bash
-# 进行本地模拟分布式训练
-python -m paddlerec.run -m ./models/rank/dnn/config.yaml  
-```
-#### 集群分布式训练
-我们以dnn模型为例，在paddlerec代码目录下，首先修改dnn模型`config.yaml`文件:
-```yaml
-runner:
- name: runner1
-  class: cluster_train # single_train -> cluster_train
-```
-再添加分布式启动配置文件`backend.yaml`，具体配置规则在[分布式训练](doc/distributed_train.md)教程中介绍。最后启动paddlerec训练：
-```bash
-# 配置好 mpi/k8s/paddlecloud集群环境后
-python -m paddlerec.run -m ./models/rank/dnn/config.yaml -b backend.yaml
-```
-<h2 align="center">支持模型列表</h2>
-|   方向   |                                   模型                                    | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 |
-| :------: | :-----------------------------------------------------------------------: | :---------: | :---------: | :-----------: |
-| 内容理解 | [Text-Classifcation](models/contentunderstanding/classification/model.py) |      ✓      |      x      |       ✓       |
-| 内容理解 |         [TagSpace](models/contentunderstanding/tagspace/model.py)         |      ✓      |      x      |       ✓       |
-|   召回   |                    [DSSM](models/match/dssm/model.py)                     |      ✓      |      x      |       ✓       |
-|   召回   |        [MultiView-Simnet](models/match/multiview-simnet/model.py)         |      ✓      |      x      |       ✓       |
-|   召回   |                   [TDM](models/treebased/tdm/model.py)                    |      ✓      |      x      |       ✓       |
-|   召回   |                [Word2Vec](models/recall/word2vec/model.py)                |      ✓      |      x      |       ✓       |
-|   召回   |                     [SSR](models/recall/ssr/model.py)                     |      ✓      |      ✓      |       ✓       |
-|   召回   |                 [Gru4Rec](models/recall/gru4rec/model.py)                 |      ✓      |      ✓      |       ✓       |
-|   召回   |             [Youtube_dnn](models/recall/youtube_dnn/model.py)             |      ✓      |      ✓      |       ✓       |
-|   召回   |                     [NCF](models/recall/ncf/model.py)                     |      ✓      |      ✓      |       ✓       |
-|   排序   |                      [Dnn](models/rank/dnn/model.py)                      |      ✓      |      x      |       ✓       |
-|   排序   |                   [DeepFM](models/rank/deepfm/model.py)                   |      ✓      |      x      |       ✓       |
-|   排序   |                  [xDeepFM](models/rank/xdeepfm/model.py)                  |      ✓      |      x      |       ✓       |
-|   排序   |                      [DIN](models/rank/din/model.py)                      |      ✓      |      x      |       ✓       |
-|   排序   |                [Wide&Deep](models/rank/wide_deep/model.py)                |      ✓      |      x      |       ✓       |
-|  多任务  |                  [ESMM](models/multitask/esmm/model.py)                   |      ✓      |      ✓      |       ✓       |
-|  多任务  |                  [MMOE](models/multitask/mmoe/model.py)                   |      ✓      |      ✓      |       ✓       |
-|  多任务  |           [ShareBottom](models/multitask/share-bottom/model.py)           |      ✓      |      ✓      |       ✓       |
-|  重排序  |                [Listwise](models/rerank/listwise/model.py)                |      ✓      |      x      |       ✓       |
-<h2 align="center">文档</h2>
-### 背景介绍
 * [推荐系统介绍](doc/rec_background.md)
 * [分布式深度学习介绍](doc/ps_background.md)
-### 新手教程
+### 快速开始
-* [环境要求](#环境要求)
+* [十分钟上手PaddleRec](doc/quick_start.md)
-* [安装命令](#安装命令)
-* [快速开始](#启动内置模型的默认配置)
+### 入门教程
+* [数据准备](doc/slot_reader.md)
+* [模型调参](doc/model.md)
+* [启动训练](doc/train.md)
+* [启动预测](doc/predict.md)
+* [快速部署](doc/serving.md)
-### 进阶教程
-* [自定义数据集及Reader](doc/custom_dataset_reader.md)
-* [分布式训练](doc/distributed_train.md)
-### 开发者教程
+### 进阶教程
+* [自定义Reader](doc/custom_reader.md)
+* [自定义模型](doc/development.md)
+* [自定义流程](doc/development.md)
+* [yaml配置说明](doc/yaml.md)
 * [PaddleRec设计文档](doc/design.md)
-* [二次开发](doc/development.md)
-### 关于PaddleRec性能
+### Benchmark
 * [Benchmark](doc/benchmark.md)
 ### FAQ
@@ -211,12 +134,25 @@ python -m paddlerec.run -m ./models/rank/dnn/config.yaml -b backend.yaml
 <h2 align="center">社区</h2>
-### 反馈
+<p align="center">
-如有意见、建议及使用中的BUG，欢迎在[GitHub Issue](https://github.com/PaddlePaddle/PaddleRec/issues)提交
+    <br>
+    <img alt="Release" src="https://img.shields.io/badge/Release-0.1.0-yellowgreen">
+    <img alt="License" src="https://img.shields.io/github/license/PaddlePaddle/Serving">
+    <img alt="Slack" src="https://img.shields.io/badge/Join-Slack-green">
+    <br>
+<p>
 ### 版本历史
 - 2020.5.14 - PaddleRec v0.1
 ### 许可证书
 本项目的发布受[Apache 2.0 license](LICENSE)许可认证。
+### 联系我们
+如有意见、建议及使用中的BUG，欢迎在[GitHub Issue](https://github.com/PaddlePaddle/PaddleRec/issues)提交
+亦可通过以下方式与我们沟通交流：
+<p align="center"><img width="200" height="200"  src="doc/imgs/wechet.png"/>&#8194;&#8194;&#8194;&#8194;&#8194;<img width="200" height="200" margin="500" src="./doc/imgs/QQ_group.png"/>&#8194;&#8194;&#8194;&#8194;&#8194<img width="200" height="200"  src="doc/imgs/weixin_supporter.png"/></p>
+<p align="center">  &#8194;&#8194;&#8194;&#8194;&#8194;&#8194;微信公众号&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;PaddleRec交流QQ群&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;&#8194;PaddleRec微信小助手</p>
--- a/doc/custom_dataset_reader.md
+++ b/doc/custom_dataset_reader.md
-# PaddleRec 推荐数据集格式
-当你的数据集格式为[slot:feasign]*这种模式，或者可以预处理为这种格式时，可以直接使用PaddleRec内置的Reader。
-好处是不用自己写Reader了，各个model之间的数据格式也都可以统一成一样的格式。
-## 数据格式说明
-假如你的原始数据格式为
-```bash
-<label> <integer feature 1> ... <integer feature 13> <categorical feature 1> ... <categorical feature 26>
-```
-其中```<label>```表示广告是否被点击，点击用1表示，未点击用0表示。```<integer feature>```代表数值特征（连续特征），共有13个连续特征。
-并且每个特征有一个特征值。
-```<categorical feature>```代表分类特征（离散特征），共有26个离散特征。相邻两个特征用```\t```分隔。
-假设这13个连续特征（dense slot）的name如下：
-```
-D1 D2 D3 D4 D4 D6 D7 D8 D9 D10 D11 D12 D13
-```
-这26个离散特征（sparse slot）的name如下：
-```
-S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12 S13 S14 S15 S16 S17 S18 S19 S20 S21 S22 S23 S24 S25 S26
-```
-那么下面这条样本（1个label + 13个dense值 + 26个feasign）
-```
-1 0.1 0.4 0.2 0.3 0.5 0.8 0.3 0.2 0.1 0.5 0.6 0.3 0.9 60 16 91 50 52 52 28 69 63 33 87 69 48 59 27 12 95 36 37 41 17 3 86 19 88 60
-```
-可以转换成：
-```
-label:1 D1:0.1 D2:0.4 D3:0.2 D4:0.3 D5:0.5 D6:0.8 D7:0.3 D8:0.2 D9:0.1 D10:0.5 D11:0.6 D12:0.3 D13:0.9 S14:60 S15:16 S16:91 S17:50 S18:52 S19:52 S20:28 S21:69 S22:63 S23:33 S24:87 S25:69 S26:48 S27:59 S28:27 S29:12 S30:95 S31:36 S32:37 S33:41 S34:17 S35:3 S36:86 S37:19 S38:88 S39:60
-```
-注意：上面各个slot:feasign字段之间的顺序没有要求，比如```D1:0.1 D2:0.4```改成```D2:0.4 D1:0.1```也可以。
-## 配置
-reader中需要配置```sparse_slots```与```dense_slots```，例如
-```
-  workspace: xxxx
-  reader:
-    batch_size: 2
-    train_data_path: "{workspace}/data/train_data"
-    sparse_slots: "label S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12 S13 S14 S15 S16 S17 S18 S19 S20 S21 S22 S23 S24 S25 S26"
-    dense_slots: "D1:1 D2:1 D3:1 D4:1 D4:1 D6:1 D7:1 D8:1 D9:1 D10:1 D11:1 D12:1 D13:1"
-  model:
-    xxxxx
-```
-sparse_slots表示稀疏特征的列表，以空格分开。
-dense_slots表示稠密特征的列表，以空格分开。每个字段的格式是```[dense_slot_name]:[dim1,dim2,dim3...]```，其中```dim1,dim2,dim3...```表示shape
-配置好了之后，这些slot对应的variable就可以在model中的如下变量啦：
-```
-self._sparse_data_var
-self._dense_data_var
-```
 # PaddleRec 自定义数据集及Reader
 用户自定义数据集及配置异步Reader，需要关注以下几个步骤：

--- a/doc/development.md
+++ b/doc/development.md
-# 二次开发
+# 如何添加自定义模型
-## 如何添加自定义模型
 当您希望开发自定义模型时，需要继承模型的模板基类，并实现三个必要的方法`init_hyper_parameter`,`intput_data`,`net`

--- a/doc/imgs/QQ_group.png
+++ b/doc/imgs/QQ_group.png
--- a/doc/imgs/wechet.png
+++ b/doc/imgs/wechet.png
--- a/doc/imgs/weixin_supporter.png
+++ b/doc/imgs/weixin_supporter.png
--- a/doc/local_train.md
+++ b/doc/local_train.md
-# PaddleRec 单机训练
-> 占位
--- a/doc/model.md
+++ b/doc/model.md
+# 模型调参
+PaddleRec模型调参需要同时关注两个部分
+1. model.py
+2. config.yaml 中 hyper_parameters的部分
+我们以`models/rank/dnn`为例介绍两者的对应情况：
+```yaml
+hyper_parameters:
+  optimizer:
+    class: Adam
+    learning_rate: 0.001
+  sparse_feature_number: 1000001
+  sparse_feature_dim: 9
+  fc_sizes: [512, 256, 128, 32]
+```
+## optimizer
+该参数决定了网络参数训练时使用的优化器，class可选项有：`SGD`/`Adam`/`AdaGrad`，通过learning_rate选项设置学习率。
+在`PaddleRec/core/model.py`中，可以看到该选项是如何生效的：
+```python
+if name == "SGD":
+    reg = envs.get_global_env("hyper_parameters.reg", 0.0001,
+                                self._namespace)
+    optimizer_i = fluid.optimizer.SGD(
+        lr, regularization=fluid.regularizer.L2DecayRegularizer(reg))
+elif name == "ADAM":
+    optimizer_i = fluid.optimizer.Adam(lr, lazy_mode=True)
+elif name == "ADAGRAD":
+    optimizer_i = fluid.optimizer.Adagrad(lr)
+```
+## sparse_feature_number & sparse_feature_dim
+该参数指定了ctr-dnn组网中，Embedding表的维度，在`PaddelRec/models/rank/dnn/model.py`中可以看到该参数是如何生效的：
+```python
+self.sparse_feature_number = envs.get_global_env(
+            "hyper_parameters.sparse_feature_number")
+self.sparse_feature_dim = envs.get_global_env(
+            "hyper_parameters.sparse_feature_dim")
+def embedding_layer(input):
+    emb = fluid.layers.embedding(
+        input=input,
+        is_sparse=True,
+        is_distributed=self.is_distributed,
+        size=[self.sparse_feature_number, self.sparse_feature_dim],
+        param_attr=fluid.ParamAttr(
+            name="SparseFeatFactors",
+            initializer=fluid.initializer.Uniform()), )
+    emb_sum = fluid.layers.sequence_pool(input=emb, pool_type='sum')
+    return emb_sum
+```
+## fc_sizes
+该参数指定了ctr-dnn模型中的dnn共有几层，且每层的维度，在在`PaddelRec/models/rank/dnn/model.py`中可以看到该参数是如何生效的：
+```python
+hidden_layers = envs.get_global_env("hyper_parameters.fc_sizes")
+for size in hidden_layers:
+    output = fluid.layers.fc(
+        input=fcs[-1],
+        size=size,
+        act='relu',
+        param_attr=fluid.ParamAttr(
+            initializer=fluid.initializer.Normal(
+                scale=1.0 / math.sqrt(fcs[-1].shape[1]))))
+    fcs.append(output)
+```
--- a/doc/model_list.md
+++ b/doc/model_list.md
-# 支持模型列表
-|   方向   |          模型          | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 | 大规模稀疏 | 分布式GPU训练 | 自定义数据集 |
-| :------: | :--------------------: | :---------: | :---------: | :-----------: | :--------: | :-----------: | :----------: |
-| 内容理解 | [Text-Classifcation]() |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-| 内容理解 |      [TagSpace]()      |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   召回   |      [Word2Vec]()      |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   召回   |        [TDM]()         |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |      [CTR-Dnn]()       |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |       [DeepFm]()       |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |      [ListWise]()      |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|  多任务  |        [MMOE]()        |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|  多任务  |        [ESMM]()        |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   匹配   |        [DSSM]()        |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   匹配   |  [Multiview-Simnet]()  |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
--- a/doc/optimization_model.md
+++ b/doc/optimization_model.md
-# PaddleRec 模型调参
-> 占位
--- a/doc/predict.md
+++ b/doc/predict.md
 # PaddleRec 离线预测
+## 单机离线预测启动配置
+下面我们开始定义一个单机预测的`runner`:
+```yaml
+mode: runner_infer # 执行名为 runner1 的运行器
+runner:
+- name: runner_infer # 定义 runner 名为 runner1
+  class: single_infer # 执行单机预测 class = single_infer
+  device: cpu # 执行在 cpu 上
+  init_model_path: "init_model" # 指定初始化模型的地址
+  print_interval: 10 # 预测信息的打印间隔，以batch为单位
+```
+再定义具体的执行内容：
+```yaml
+phase:
+- name: phase_infer # 该阶段名为 phase_infer
+  model: "{workspace}/model.py" # 模型文件为workspace下的model.py
+  dataset_name: dataset_infer # reader的名字
+dataset:
+- name: dataset_infer
+  type: DataLoader # 使用DataLoader的数据读取方式
+  batch_size: 2
+  data_path: "{workspace}/test_data" # 数据地址
+  sparse_slots: "click 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26" # sparse 输入的位置定义
+  dense_slots: "dense_var:13"  # dense参数的维度定义
+```
--- a/doc/quick_start.md
+++ b/doc/quick_start.md
+# 十分钟上手PaddleRec
--- a/doc/serving.md
+++ b/doc/serving.md
+# 在线部署
+PaddleRec以飞桨框架为底层，因此训练保存出的inference_model(预测模型)，可以使用飞桨强大的部署能力快速在线部署。
+首先我们在`yaml`配置中，指定inference_model的保存间隔与保存地址：
+```yaml
+mode: runner_train # 执行名为 runner_train 的运行器
+runner:
+- name: runner_train # 定义 runner 名为 runner_train
+  class: single_train # 执行单机训练 class = single_train
+  device: cpu # 执行在 cpu 上
+  epochs: 10 # 训练轮数
+  save_checkpoint_interval: 2 # 每隔2轮保存一次checkpoint
+  save_inference_interval: 4 # 每个4轮保存依次inference model
+  save_checkpoint_path: "increment" # checkpoint 的保存地址
+  save_inference_path: "inference" # inference model 的保存地址
+  save_inference_feed_varnames: [] # inference model 的feed参数的名字
+  save_inference_fetch_varnames: [] # inference model 的fetch参数的名字
+  init_model_path: "" # 如果是加载模型热启，则可以指定初始化模型的地址
+  print_interval: 10 # 训练信息的打印间隔，以batch为单位
+```
+训练完成后，我们便可以在`inference`或`increment`文件夹中看到保存的模型/参数。
+参考以下链接进行模型的不同场景下的部署。
+### [服务器端部署](https://www.paddlepaddle.org.cn/documentation/docs/zh/advanced_guide/inference_deployment/inference/index_cn.html)
+### [移动端部署](https://www.paddlepaddle.org.cn/documentation/docs/zh/advanced_guide/inference_deployment/mobile/index_cn.html)
+### [在线Serving](https://github.com/PaddlePaddle/Serving)
+### [模型压缩](https://www.paddlepaddle.org.cn/documentation/docs/zh/advanced_guide/inference_deployment/paddleslim/paddle_slim.html)
--- a/doc/slot_reader.md
+++ b/doc/slot_reader.md
+# PaddleRec 推荐数据集格式
+当你的数据集格式为`slot:feasign`这种模式，或者可以预处理为这种格式时，可以直接使用PaddleRec内置的Reader。
+> Slot : Feasign 是什么？
+>
+> Slot直译是槽位，在推荐工程中，是指某一个宽泛的特征类别，比如用户ID、性别、年龄就是Slot，Feasign则是具体值，比如：12345，男，20岁。
+> 
+> 在实践过程中，很多特征槽位不是单一属性，或无法量化并且离散稀疏的，比如某用户兴趣爱好有三个：游戏/足球/数码，且每个具体兴趣又有多个特征维度，则在兴趣爱好这个Slot兴趣槽位中，就会有多个Feasign值。
+>
+> PaddleRec在读取数据时，每个Slot ID对应的特征，支持稀疏，且支持变长，可以非常灵活的支持各种场景的推荐模型训练。
+## 数据格式说明
+假如你的原始数据格式为
+```bash
+<label> <integer feature 1> ... <integer feature 13> <categorical feature 1> ... <categorical feature 26>
+```
+其中```<label>```表示广告是否被点击，点击用1表示，未点击用0表示。```<integer feature>```代表数值特征（连续特征），共有13个连续特征。
+并且每个特征有一个特征值。
+```<categorical feature>```代表分类特征（离散特征），共有26个离散特征。相邻两个特征用```\t```分隔。
+假设这13个连续特征（dense slot）的name如下：
+```
+D1 D2 D3 D4 D4 D6 D7 D8 D9 D10 D11 D12 D13
+```
+这26个离散特征（sparse slot）的name如下：
+```
+S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12 S13 S14 S15 S16 S17 S18 S19 S20 S21 S22 S23 S24 S25 S26
+```
+那么下面这条样本（1个label + 13个dense值 + 26个feasign）
+```
+1 0.1 0.4 0.2 0.3 0.5 0.8 0.3 0.2 0.1 0.5 0.6 0.3 0.9 60 16 91 50 52 52 28 69 63 33 87 69 48 59 27 12 95 36 37 41 17 3 86 19 88 60
+```
+可以转换成：
+```
+label:1 D1:0.1 D2:0.4 D3:0.2 D4:0.3 D5:0.5 D6:0.8 D7:0.3 D8:0.2 D9:0.1 D10:0.5 D11:0.6 D12:0.3 D13:0.9 S14:60 S15:16 S16:91 S17:50 S18:52 S19:52 S20:28 S21:69 S22:63 S23:33 S24:87 S25:69 S26:48 S27:59 S28:27 S29:12 S30:95 S31:36 S32:37 S33:41 S34:17 S35:3 S36:86 S37:19 S38:88 S39:60
+```
+注意：上面各个slot:feasign字段之间的顺序没有要求，比如```D1:0.1 D2:0.4```改成```D2:0.4 D1:0.1```也可以。
+## 配置
+reader中需要配置```sparse_slots```与```dense_slots```，例如
+```
+  workspace: xxxx
+  reader:
+    batch_size: 2
+    train_data_path: "{workspace}/data/train_data"
+    sparse_slots: "label S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12 S13 S14 S15 S16 S17 S18 S19 S20 S21 S22 S23 S24 S25 S26"
+    dense_slots: "D1:1 D2:1 D3:1 D4:1 D4:1 D6:1 D7:1 D8:1 D9:1 D10:1 D11:1 D12:1 D13:1"
+  model:
+    xxxxx
+```
+sparse_slots表示稀疏特征的列表，以空格分开，支持lod_level=1的变长数据，变长数据的相关概念可以参考[LodTensor](https://www.paddlepaddle.org.cn/documentation/docs/zh/beginners_guide/basic_concept/lod_tensor.html#lodtensor)
+dense_slots表示稠密特征的列表，以空格分开。每个字段的格式是```[dense_slot_name]:[dim1,dim2,dim3...]```，其中```dim1,dim2,dim3...```表示shape，多维的Dense参数shape为一个list。
+配置好了之后，这些slot对应的variable在model中可以使用如下方式调用：
+```
+self._sparse_data_var
+self._dense_data_var
+```
--- a/doc/train.md
+++ b/doc/train.md
+# PaddleRec 启动训练
+## 启动方法
+### 1. 启动内置模型的默认配置训练
+在安装好`paddlepaddle`及`paddlerec`后，可以直接使用一行命令快速启动内置模型的默认配置训练，命令如下;
+```shell
+python -m paddlerec.run -m paddlerec.models.xxx.yyy
+```
+注意事项：
+1. 请确保调用的是安装了paddlerec的`python`环境
+2. `xxx`为paddlerec.models下有多个大类，如：`recall`/`rank`/`rerank`等
+3. `yyy`为每个类别下又有多个模型，如`recall`下有：`gnn`/`grup4rec`/`ncf`等
+例如启动`recall`下的`word2vec`模型的默认配置;
+```shell
+python -m paddlerec.run -m paddlerec.models.recall.word2vec
+```
+### 2. 启动内置模型的个性化配置训练
+如果我们修改了默认模型的config.yaml文件，怎么运行修改后的模型呢？
+- **没有改动模型组网**
+假如你将paddlerec代码库克隆在了`/home/PaddleRec`，并修改了`/home/PaddleRec/models/rank/dnn/config.yaml`，则如下启动训练
+```shell
+python -m paddlerec.run -m /home/PaddleRec/models/rank/dnn/config.yaml
+```
+paddlerec 运行的是在paddlerec库安装目录下的组网文件(model.py)
+- **改动了模型组网**
+假如你将paddlerec代码库克隆在了`/home/PaddleRec`，并修改了`/home/PaddleRec/models/rank/dnn/model.py`， 以及`/home/PaddleRec/models/rank/dnn/config.yaml`，则首先需要更改`yaml`中的`workspace`的设置：
+```yaml
+workspace: /home/PaddleRec/models/rank/dnn/
+```
+再执行：
+```shell
+python -m paddlerec.run -m /home/PaddleRec/models/rank/dnn/config.yaml
+```
+paddlerec 运行的是绝对路径下的组网文件(model.py)
+### yaml中训练相关的概念
+`config.yaml`中训练流程相关有两个重要的逻辑概念，`runner`与`phase`：
+- **`runner`** : runner是训练的引擎，亦可称之为运行器，在runner中定义执行设备（cpu、gpu），执行的模式（训练、预测、单机、多机等），以及运行的超参，例如训练轮数，模型保存地址等。
+- **`phase`** : phase是训练中的阶段的概念，是引擎具体执行的内容，该内容是指：具体运行哪个模型文件，使用哪个reader。
+PaddleRec每次运行时，只会执行一个运行器，通过`mode`指定`runner`的名字。但每个运行器可以执行多个`phase`，所以PaddleRec支持一键启动多阶段的训练。
+### 单机训练启动配置
+下面我们开始定义一个单机训练的`runner`:
+```yaml
+mode: runner_train # 执行名为 runner_train 的运行器
+runner:
+- name: runner_train # 定义 runner 名为 runner_train
+  class: single_train # 执行单机训练 class = single_train
+  device: cpu # 执行在 cpu 上
+  epochs: 10 # 训练轮数
+  save_checkpoint_interval: 2 # 每隔2轮保存一次checkpoint
+  save_inference_interval: 4 # 每个4轮保存依次inference model
+  save_checkpoint_path: "increment" # checkpoint 的保存地址
+  save_inference_path: "inference" # inference model 的保存地址
+  save_inference_feed_varnames: [] # inference model 的feed参数的名字
+  save_inference_fetch_varnames: [] # inference model 的fetch参数的名字
+  init_model_path: "" # 如果是加载模型热启，则可以指定初始化模型的地址
+  print_interval: 10 # 训练信息的打印间隔，以batch为单位
+```
+再定义具体的执行内容：
+```yaml
+phase:
+- name: phase_train # 该阶段名为 phase1 
+  model: "{workspace}/model.py" # 模型文件为workspace下的model.py
+  dataset_name: dataset_train # reader的名字
+dataset:
+- name: dataset_train
+  type: DataLoader # 使用DataLoader的数据读取方式
+  batch_size: 2
+  data_path: "{workspace}/train_data" # 数据地址
+  sparse_slots: "click 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26" # sparse 输入的位置定义
+  dense_slots: "dense_var:13"  # dense参数的维度定义
+```
--- a/doc/yaml.md
+++ b/doc/yaml.md
-```yaml
+# PaddleRec yaml配置说明
-# 全局配置
-# Debug 模式开关，Debug模式下，会打印OP的耗时及IO占比
+## 全局变量
-debug: false
+ |   名称    |  类型  |                 取值                  | 是否必须 |                      作用描述                      |
-# 工作区目录
+ | :-------: | :----: | :-----------------------------------: | :------: | :------------------------------------------------: |
-# 使用文件夹路径，则会在该目录下寻找超参配置，组网，数据等必须文件
+ | workspace | string | 路径 / paddlerec.models.{方向}.{模型} |    是    |           指定model/reader/data所在位置            |
-workspace: "/home/demo_model/"
+ |   mode    | string |              runner名称               |    是    |             指定当次运行使用哪个runner             |
-# 若 workspace: paddlerec.models.rank.dnn
+ |   debug   |  bool  |             True / False              |    否    | 当dataset.mode=QueueDataset时，开启op耗时debug功能 |
-# 则会使用官方默认配置与组网
-# 用户可以指定多个dataset(数据读取配置)
+## runner变量
-# 运行的不同阶段可以使用不同的dataset
-dataset:
+|             名称              |     类型     |               取值                | 是否必须 |                    作用描述                     |
-  # dataloader 示例
+| :---------------------------: | :----------: | :-------------------------------: | :------: | :---------------------------------------------: |
-  - name: dataset_1
+|             name              |    string    |               任意                |    是    |                 指定runner名称                  |
-    type: DataLoader 
+|             class             |    string    | single_train(默认) / single_infer |    是    | 指定运行runner的类别（单机/分布式， 训练/预测） |
-    batch_size: 5
+|            device             |    string    |          cpu(默认) / gpu          |    否    |                  程序执行设备                   |
-    data_path: "{workspace}/data/train"
+|            epochs             |     int      |               >= 1                |    否    |                模型训练迭代轮数                 |
-    # 指定自定义的reader.py所在路径
+|        init_model_path        |    string    |               路径                |    否    |                 初始化模型地址                  |
-    data_converter: "{workspace}/rsc15_reader.py"
+|   save_checkpoint_interval    |     int      |               >= 1                |    否    |               Save参数的轮数间隔                |
+|     save_checkpoint_path      |    string    |               路径                |    否    |                 Save参数的地址                  |
-  # QueueDataset 示例
+|    save_inference_interval    |     int      |               >= 1                |    否    |             Save预测模型的轮数间隔              |
-  - name: dataset_2
+|      save_inference_path      |    string    |               路径                |    否    |               Save预测模型的地址                |
-    type: QueueDataset 
+| save_inference_feed_varnames  | list[string] |     组网中指定Variable的name      |    否    |             预测模型的入口变量name              |
-    batch_size: 5
+| save_inference_fetch_varnames | list[string] |     组网中指定Variable的name      |    否    |             预测模型的出口变量name              |
-    data_path: "{workspace}/data/train"
+|        print_interval         |     int      |               >= 1                |    否    |              训练指标打印batch间隔              |
-    # 用户可以配置sparse_slots和dense_slots，无需再定义data_converter，使用默认reader
-    sparse_slots: "click ins_weight 6001 6002 6003 6005 6006 6007 6008 6009"
-    dense_slots: "readlist:9"
+## phase变量
-# 自定义超参数，主要涉及网络中的模型超参及优化器
+|     名称     |  类型  |     取值     | 是否必须 |            作用描述             |
-hyper_parameters:
+| :----------: | :----: | :----------: | :------: | :-----------------------------: |
-    #优化器
+|     name     | string |     任意     |    是    |          指定phase名称          |
-    optimizer:
+|    model     | string | model.py路径 |    是    | 指定Model()所在的python文件地址 |
-      class: Adam # 直接配置Optimizer，目前支持sgd/Adam/AdaGrad
+| dataset_name | string | dataset名称  |    是    |       指定使用哪个Reader        |
-      learning_rate: 0.001
+|  thread_num  |  int   |     >= 1     |    否    |         模型训练线程数          |
-      strategy: "{workspace}/conf/config_fleet.py" # 使用大规模稀疏pslib模式的特有配置
-    # 模型超参
+## dataset变量
-    vocab_size: 1000
-    hid_size: 100
+|      名称      |  类型  |           取值            | 是否必须 |            作用描述            |
+| :------------: | :----: | :-----------------------: | :------: | :----------------------------: |
+|      name      | string |           任意            |    是    |        指定dataset名称         |
-# 通过全局参数mode指定当前运行的runner
+|      type      | string | DataLoader / QueueDataset |    是    |        指定数据读取方式        |
-mode: runner_1
+|   batch_size   |  int   |           >= 1            |    否    |       指定批训练样本数量       |
+|   data_path    | string |           路径            |    是    |        指定数据来源地址        |
-# runner主要涉及模型的执行环境，如：单机/分布式，CPU/GPU，迭代轮次，模型加载与保存地址
+| data_converter | string |       reader.py路径       |    是    | 指定Reader()所在python文件地址 |
-runner:
+|  sparse_slots  | string |          string           |    否    |        指定稀疏参数选项        |
-  - name: runner_1 # 配置一个runner，进行单机的训练
+|  dense_slots   | string |          string           |    否    |        指定稠密参数选项        |
-    class: single_train # 配置运行模式的选择，还可以选择：single_infer/local_cluster_train/cluster_train
-    epochs: 10
+## hyper_parameters变量
-    device: cpu
+|          名称           |  类型  |       取值       | 是否必须 |          作用描述           |
-    init_model_path: ""
+| :---------------------: | :----: | :--------------: | :------: | :-------------------------: |
-    save_checkpoint_interval: 2
+|     optimizer.class     | string | SGD/Adam/Adagrad |    是    |       指定优化器类型        |
-    save_inference_interval: 4
+| optimizer.learning_rate | float  |       > 0        |    否    |         指定学习率          |
-    # 下面是保存模型路径配置
+|           reg           | float  |       > 0        |    否    | L2正则化参数，只在SGD下生效 |
-    save_checkpoint_path: "xxxx"
+|         others          |   /    |        /         |    /     |   由各个模型组网独立指定    |
-    save_inference_path: "xxxx"
-  - name: runner_2 # 配置一个runner，进行单机的预测
-    class: single_infer
-    epochs: 1
-    device: cpu
-    init_model_path: "afs:/xxx/xxx"
-# 模型在训练时，可能存在多个阶段，每个阶段的组网与数据读取都可能不尽相同
-# 每个runner都会完整的运行所有阶段
-# phase指定运行时加载的模型及reader
-phase:
- name: phase1
-  model: "{workspace}/model.py"
-  dataset_name: sample_1
-  thread_num: 1
-```