Merge branch 'doc_update' into 'develop'

Doc update

See merge request !23

core/trainers/transpiler_trainer.py

@@ -42,7 +42,7 @@ class TranspileTrainer(Trainer):
             namespace = "train.reader"
             class_name = "TrainReader"
         else:
-            dataloader = self.model._infer_data_loader
+            readerdataloader = self.model._infer_data_loader
             namespace = "evaluate.reader"
             class_name = "EvaluateReader"
 
@@ -58,6 +58,16 @@ class TranspileTrainer(Trainer):
             dataloader.set_sample_list_generator(reader)
         else:
             dataloader.set_sample_generator(reader, batch_size)
+
+        debug_mode = envs.get_global_env("reader_debug_mode", False, namespace)
+        if debug_mode:
+            print("--- DataLoader Debug Mode Begin , show pre 10 data ---")
+            for idx, line in enumerate(reader()):
+                print(line)
+                if idx >= 9:
+                    break
+            print("--- DataLoader Debug Mode End , show pre 10 data ---")
+            exit(0)
         return dataloader
 
     def _get_dataset(self, state="TRAIN"):
@@ -98,6 +108,16 @@ class TranspileTrainer(Trainer):
         ]
 
         dataset.set_filelist(file_list)
+
+        debug_mode = envs.get_global_env("reader_debug_mode", False, namespace)
+        if debug_mode:
+            print(
+                "--- Dataset Debug Mode Begin , show pre 10 data of {}---".format(file_list[0]))
+            os.system("cat {} | {} | head -10".format(file_list[0], pipe_cmd))
+            print(
+                "--- Dataset Debug Mode End , show pre 10 data of {}---".format(file_list[0]))
+            exit(0)
+
         return dataset
 
     def save(self, epoch_id, namespace, is_fleet=False):
@@ -116,23 +136,28 @@ class TranspileTrainer(Trainer):
 
             if not need_save(epoch_id, save_interval, False):
                 return
-            
+
           #  print("save inference model is not supported now.")
           #  return
 
-            feed_varnames = envs.get_global_env("save.inference.feed_varnames", None, namespace)
-            fetch_varnames = envs.get_global_env("save.inference.fetch_varnames", None, namespace)
+            feed_varnames = envs.get_global_env(
+                "save.inference.feed_varnames", None, namespace)
+            fetch_varnames = envs.get_global_env(
+                "save.inference.fetch_varnames", None, namespace)
             if feed_varnames is None or fetch_varnames is None:
                 return
 
-            fetch_vars = [fluid.default_main_program().global_block().vars[varname] for varname in fetch_varnames]
-            dirname = envs.get_global_env("save.inference.dirname", None, namespace)
+            fetch_vars = [fluid.default_main_program().global_block().vars[varname]
+                          for varname in fetch_varnames]
+            dirname = envs.get_global_env(
+                "save.inference.dirname", None, namespace)
 
             assert dirname is not None
             dirname = os.path.join(dirname, str(epoch_id))
 
             if is_fleet:
-                fleet.save_inference_model(self._exe, dirname, feed_varnames, fetch_vars)
+                fleet.save_inference_model(
+                    self._exe, dirname, feed_varnames, fetch_vars)
             else:
                 fluid.io.save_inference_model(
                     dirname, feed_varnames, fetch_vars, self._exe)

doc/custom_dataset_reader.md

 # PaddleRec 自定义数据集及Reader
 
-## dataset数据读取
-为了能高速运行CTR模型的训练，我们使用`dataset`API进行高性能的IO，dataset是为多线程及全异步方式量身打造的数据读取方式，每个数据读取线程会与一个训练线程耦合，形成了多生产者-多消费者的模式，会极大的加速我们的模型训练。
+## 数据集及reader配置简介
 
-如何在我们的训练中引入dataset读取方式呢？无需变更数据格式，只需在我们的训练代码中加入以下内容，便可达到媲美二进制读取的高效率，以下是一个比较完整的流程：
+以`ctr-dnn`模型举例：
 
-### 引入dataset
+```yaml
+reader:
+    batch_size: 2
+    class: "{workspace}/../criteo_reader.py"
+    train_data_path: "{workspace}/data/train"
+    reader_debug_mode: False
+```
+有以上4个需要重点关注的配置选项：
+
+- batch_size: 网络进行小批量训练的一组数据的大小
+- class: 指定数据处理及读取的`reader` python文件
+- train_data_path: 训练数据所在地址
+- reader_debug_mode: 测试reader语法，及输出是否符合预期的debug模式的开关
+
+## 自定义数据集
+
+PaddleRec支持模型自定义数据集，在model.config.yaml文件中的reader部分，通过`train_data_path`指定数据读取路径。
+
+关于数据的tips
+
+- PaddleRec 面向的是推荐与搜索领域，数据以文本格式为主
+- Dataset模式支持读取文本数据压缩后的`.gz`格式
+- Dataset模式下，训练线程与数据读取线程的关系强相关，为了多线程充分利用，`强烈建议将文件拆成多个小文件`，尤其是在分布式训练场景下，可以均衡各个节点的数据量。
+
+## 自定义Reader
+
+数据集准备就绪后，需要适当修改或重写一个新的reader以适配数据集或新组网。
+
+我们以`ctr-dnn`网络举例`reader`的正确打开方式，网络文件位于`models/rank/dnn`。
+
+### Criteo数据集格式
+
+CTR-DNN训练及测试数据集选用[Display Advertising Challenge](https://www.kaggle.com/c/criteo-display-ad-challenge/)所用的Criteo数据集。该数据集包括两部分：训练集和测试集。训练集包含一段时间内Criteo的部分流量，测试集则对应训练数据后一天的广告点击流量。
+每一行数据格式如下所示：
+```bash
+<label> <integer feature 1> ... <integer feature 13> <categorical feature 1> ... <categorical feature 26>
+```
+其中```<label>```表示广告是否被点击，点击用1表示，未点击用0表示。```<integer feature>```代表数值特征（连续特征），共有13个连续特征。```<categorical feature>```代表分类特征（离散特征），共有26个离散特征。相邻两个特征用```\t```分隔，缺失特征用空格表示。测试集中```<label>```特征已被移除。
 
-1. 通过工厂类`fluid.DatasetFactory()`创建一个dataset对象。
-2. 将我们定义好的数据输入格式传给dataset，通过`dataset.set_use_var(inputs)`实现。
-3. 指定我们的数据读取方式，由`dataset_generator.py`实现数据读取的规则，后面将会介绍读取规则的实现。
-4. 指定数据读取的batch_size。
-5. 指定数据读取的线程数，该线程数和训练线程应保持一致，两者为耦合的关系。
-6. 指定dataset读取的训练文件的列表。
+### Criteo数据集的预处理
 
+数据预处理共包括两步：
+- 将原始训练集按9:1划分为训练集和验证集
+- 数值特征（连续特征）需进行归一化处理，但需要注意的是，对每一个特征```<integer feature i>```，归一化时用到的最大值并不是用全局最大值，而是取排序后95%位置处的特征值作为最大值，同时保留极值。
 
+### CTR网络输入的定义
+
+正如前所述，Criteo数据集中，分为连续数据与离散（稀疏）数据，所以整体而言，CTR-DNN模型的数据输入层包括三个，分别是：`dense_input`用于输入连续数据，维度由超参数`dense_feature_dim`指定，数据类型是归一化后的浮点型数据。`sparse_input_ids`用于记录离散数据，在Criteo数据集中，共有26个slot，所以我们创建了名为`C1~C26`的26个稀疏参数输入，并设置`lod_level=1`，代表其为变长数据，数据类型为整数；最后是每条样本的`label`，代表了是否被点击，数据类型是整数，0代表负样例，1代表正样例。
+
+在Paddle中数据输入的声明使用`paddle.fluid.layers.data()`，会创建指定类型的占位符，数据IO会依据此定义进行数据的输入。
+
+稀疏参数输入的定义:
 ```python
-def get_dataset(inputs, args)
-    dataset = fluid.DatasetFactory().create_dataset()
-    dataset.set_use_var(inputs)
-    dataset.set_pipe_command("python dataset_generator.py")
-    dataset.set_batch_size(args.batch_size)
-    dataset.set_thread(int(args.cpu_num))
-    file_list = [
-        str(args.train_files_path) + "/%s" % x
-        for x in os.listdir(args.train_files_path)
+def sparse_inputs():
+    ids = envs.get_global_env("hyper_parameters.sparse_inputs_slots", None, self._namespace)
+
+    sparse_input_ids = [
+        fluid.layers.data(name="S" + str(i),
+                            shape=[1],
+                            lod_level=1,
+                            dtype="int64") for i in range(1, ids)
     ]
-    logger.info("file list: {}".format(file_list))
-    return dataset, file_list
+    return sparse_input_ids
 ```
 
-### 如何指定数据读取规则
+稠密参数输入的定义：
+```python
+def dense_input():
+    dim = envs.get_global_env("hyper_parameters.dense_input_dim", None, self._namespace)
 
-在上文我们提到了由`dataset_generator.py`实现具体的数据读取规则，那么，怎样为dataset创建数据读取的规则呢？
-以下是`dataset_generator.py`的全部代码，具体流程如下：
-1. 首先我们需要引入dataset的库，位于`paddle.fluid.incubate.data_generator`。
-2. 声明一些在数据读取中会用到的变量，如示例代码中的`cont_min_`、`categorical_range_`等。
-3. 创建一个子类，继承dataset的基类，基类有多种选择，如果是多种数据类型混合，并且需要转化为数值进行预处理的，建议使用`MultiSlotDataGenerator`；若已经完成了预处理并保存为数据文件，可以直接以`string`的方式进行读取，使用`MultiSlotStringDataGenerator`，能够进一步加速。在示例代码，我们继承并实现了名为`CriteoDataset`的dataset子类，使用`MultiSlotDataGenerator`方法。
-4. 继承并实现基类中的`generate_sample`函数，逐行读取数据。该函数应返回一个可以迭代的reader方法(带有yield的函数不再是一个普通的函数，而是一个生成器generator，成为了可以迭代的对象，等价于一个数组、链表、文件、字符串etc.)
-5. 在这个可以迭代的函数中，如示例代码中的`def reader()`，我们定义数据读取的逻辑。例如对以行为单位的数据进行截取，转换及预处理。
-6. 最后，我们需要将数据整理为特定的格式，才能够被dataset正确读取，并灌入的训练的网络中。简单来说，数据的输出顺序与我们在网络中创建的`inputs`必须是严格一一对应的，并转换为类似字典的形式。在示例代码中，我们使用`zip`的方法将参数名与数值构成的元组组成了一个list，并将其yield输出。如果展开来看，我们输出的数据形如`[('dense_feature',[value]),('C1',[value]),('C2',[value]),...,('C26',[value]),('label',[value])]`
+    dense_input_var = fluid.layers.data(name="D",
+                                        shape=[dim],
+                                        dtype="float32")
+    return dense_input_var
+```
 
+标签的定义：
+```python
+def label_input():
+    label = fluid.layers.data(name="click", shape=[1], dtype="int64")
+    return label
+```
 
+组合起来，正确的声明他们：
 ```python
-import paddle.fluid.incubate.data_generator as dg
+self.sparse_inputs = sparse_inputs()
+self.dense_input = dense_input()
+self.label_input = label_input()
+
+self._data_var.append(self.dense_input)
+
+for input in self.sparse_inputs:
+    self._data_var.append(input)
+
+self._data_var.append(self.label_input)
+
+if self._platform != "LINUX":
+    self._data_loader = fluid.io.DataLoader.from_generator(
+        feed_list=self._data_var, capacity=64, use_double_buffer=False, iterable=False)
+```
+若运行于**Linux**环境下，默认使用**dataset**模式读取数据集；若运行于**windows**或**mac**下，默认使用**dataloader**模式读取数据集。以上两种方法是paddle.io中提供的不同模式，`dataset`运行速度更快，但依赖于linux的环境，因此会有该逻辑判断。
+
+> Paddle的组网中不支持数据输入为`str`类型，`强烈不建议使用明文保存和读取数据`
 
-cont_min_ = [0, -3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
-cont_max_ = [20, 600, 100, 50, 64000, 500, 100, 50, 500, 10, 10, 10, 50]
-cont_diff_ = [20, 603, 100, 50, 64000, 500, 100, 50, 500, 10, 10, 10, 50]
-hash_dim_ = 1000001
-continuous_range_ = range(1, 14)
-categorical_range_ = range(14, 40)
+### Criteo Reader写法
 
-class CriteoDataset(dg.MultiSlotDataGenerator):
-   
+```python
+# 引入PaddleRec的Reader基类
+from paddlerec.core.reader import Reader
+# 引入PaddleRec的读取yaml配置文件的方法
+from paddlerec.core.utils import envs
+
+# 定义TrainReader，需要继承 paddlerec.core.reader.Reader
+class TrainReader(Reader):
+
+    # 数据预处理逻辑，继承自基类
+    # 如果无需处理， 使用pass跳过该函数的执行
+    def init(self):
+        self.cont_min_ = [0, -3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+        self.cont_max_ = [20, 600, 100, 50, 64000, 500, 100, 50, 500, 10, 10, 10, 50]
+        self.cont_diff_ = [20, 603, 100, 50, 64000, 500, 100, 50, 500, 10, 10, 10, 50]
+        self.hash_dim_ = envs.get_global_env("hyper_parameters.sparse_feature_number", None, "train.model")
+        self.continuous_range_ = range(1, 14)
+        self.categorical_range_ = range(14, 40)
+
+    # 读取数据方法，继承自基类
+    # 实现可以迭代的reader函数，逐行处理数据
     def generate_sample(self, line):
-        
+        """
+        Read the data line by line and process it as a dictionary
+        """
+
         def reader():
+            """
+            This function needs to be implemented by the user, based on data format
+            """
             features = line.rstrip('\n').split('\t')
+
             dense_feature = []
             sparse_feature = []
-            for idx in continuous_range_:
+            for idx in self.continuous_range_:
                 if features[idx] == "":
                     dense_feature.append(0.0)
                 else:
                     dense_feature.append(
-                        (float(features[idx]) - cont_min_[idx - 1]) /
-                        cont_diff_[idx - 1])
-            for idx in categorical_range_:
+                        (float(features[idx]) - self.cont_min_[idx - 1]) /
+                        self.cont_diff_[idx - 1])
+
+            for idx in self.categorical_range_:
                 sparse_feature.append(
-                    [hash(str(idx) + features[idx]) % hash_dim_])
+                    [hash(str(idx) + features[idx]) % self.hash_dim_])
             label = [int(features[0])]
-            process_line = dense_feature, sparse_feature, label
-            feature_name = ["dense_feature"]
-            for idx in categorical_range_:
-                feature_name.append("C" + str(idx - 13))
+            feature_name = ["D"]
+            for idx in self.categorical_range_:
+                feature_name.append("S" + str(idx - 13))
             feature_name.append("label")
-
             yield zip(feature_name, [dense_feature] + sparse_feature + [label])
 
         return reader
+```
+
+### 如何自定义数据读取规则
+
+在上文我们看到了由`criteo_reader.py`实现具体的数据读取规则，那么，怎样为自己的数据集写规则呢？
+
+具体流程如下：
+1. 首先我们需要引入Reader基类
+
+    ```python
+    from paddlerec.core.reader import Reader
+    ```
+2. 创建一个子类，继承Reader的基类，训练所需Reader命名为`TrainerReader`
+3. 在`init(self)`函数中声明一些在数据读取中会用到的变量，如示例代码中的`cont_min_`、`categorical_range_`等，必要时可以在`config.yaml`文件中配置变量，通过`env.get_global_env()`拿到。
+4. 继承并实现基类中的`generate_sample(self, line)`函数，逐行读取数据。该函数应返回一个可以迭代的reader方法(带有yield的函数不再是一个普通的函数，而是一个生成器generator，成为了可以迭代的对象，等价于一个数组、链表、文件、字符串etc.)
+5. 在这个可以迭代的函数中，如示例代码中的`def reader()`，我们定义数据读取的逻辑。以行为单位的数据进行截取，转换及预处理。
+6. 最后，我们需要将数据整理为特定的格式，才能够被dataset正确读取，并灌入的训练的网络中。简单来说，数据的输出顺序与我们在网络中创建的`inputs`必须是严格一一对应的，并转换为类似字典的形式。在示例代码中，我们使用`zip`的方法将参数名与数值构成的元组组成了一个list，并将其yield输出。如果展开来看，我们输出的数据形如
+
+    `[('dense_feature',[value]),('C1',[value]),('C2',[value]),...,('C26',[value]),('label',[value])]`
+
+
+### 调试Reader
 
-d = CriteoDataset()
-d.run_from_stdin()
+在Linux下运行时，默认启动`Dataset`模式，在Win/Mac下运行时，默认启动`Dataloader`模式。
+
+通过在`config.yaml`中添加或修改`reader_debug_mode=True`打开debug模式，只会结合组网运行reader的部分，读取10条样本，并print，方便您观察格式是否符合预期或隐藏bug。
+```yaml
+reader:
+    batch_size: 2
+    class: "{workspace}/../criteo_reader.py"
+    train_data_path: "{workspace}/data/train"
+    reader_debug_mode: True
 ```
-### 快速调试Dataset
-我们可以脱离组网架构，单独验证Dataset的输出是否符合我们预期。使用命令
-`cat 数据文件 | python dataset读取python文件`进行dataset代码的调试：
+
+修改后，使用paddlerec.run执行该修改后的yaml文件，可以观察输出。
 ```bash
-cat train_data/part-0 | python dataset_generator.py
+python -m paddlerec.run -m ./models/rank/dnn/config.yaml -e single
 ```
-输出的数据格式如下：
+
+### Dataset调试
+
+dataset输出的数据格式如下：
 ` dense_input:size ; dense_input:value ; sparse_input:size ; sparse_input:value ; ... ; sparse_input:size ; sparse_input:value ; label:size ; label:value `
 
-理想的输出为(截取了一个片段)：
+基本规律是对于每个变量，会先输出其维度大小，再输出其具体值。
+
+直接debug `criteo_reader`理想的输出为(截取了一个片段)：
 ```bash
 ...
-13 0.05 0.00663349917081 0.05 0.0 0.02159375 0.008 0.15 0.04 0.362 0.1 0.2 0.0 0.04 1 715353 1 817085 1 851010 1 833725 1 286835 1 948614 1 881652 1 507110 1 27346 1 646986 1 643076 1 200960 1 18464 1 202774 1 532679 1 729573 1 342789 1 562805 1 880474 1 984402 1 666449 1 26235 1 700326 1 452909 1 884722 1 787527 1 0
+13 0.0 0.00497512437811 0.05 0.08 0.207421875 0.028 0.35 0.08 0.082 0.0 0.4 0.0 0.08 1 737395 1 210498 1 903564 1 286224 1 286835 1 906818 1 90
+6116 1 67180 1 27346 1 51086 1 142177 1 95024 1 157883 1 873363 1 600281 1 812592 1 228085 1 35900 1 880474 1 984402 1 100885 1 26235 1 410878 1 798162 1 499868 1 306163 1 0
 ...
 ```
+可以看到首先输出的是13维的dense参数，随后是分立的sparse参数，最后一个是1维的label，数值为0，输出符合预期。
 
 >使用Dataset的一些注意事项
 > - Dataset的基本原理：将数据print到缓存，再由C++端的代码实现读取，因此，我们不能在dataset的读取代码中，加入与数据读取无关的print信息，会导致C++端拿到错误的数据信息。
-> - dataset目前只支持在`unbuntu`及`CentOS`等标准Linux环境下使用，在`Windows`及`Mac`下使用时，会产生预料之外的错误，请知悉。
\ No newline at end of file
+> - dataset目前只支持在`unbuntu`及`CentOS`等标准Linux环境下使用，在`Windows`及`Mac`下使用时，会产生预料之外的错误，请知悉。
+
+### DataLoader调试
+
+dataloader的输出格式为`list: [ list[var_1], list[var_2], ... , list[var_3]]`，每条样本的数据会被放在一个 **list[list]** 中，list[0]为第一个variable。
+
+直接debug `criteo_reader`理想的输出为(截取了一个片段)：
+```bash
+...
+[[0.0, 0.004975124378109453, 0.05, 0.08, 0.207421875, 0.028, 0.35, 0.08, 0.082, 0.0, 0.4, 0.0, 0.08], [560746], [902436], [262029], [182633], [368411], [735166], [321120], [39572], [185732], [140298], [926671], [81559], [461249], [728372], [915018], [907965], [818961], [850958], [311492], [980340], [254960], [175041], [524857], [764893], [526288], [220126], [0]]
+...
+```
+可以看到首先输出的是13维的dense参数的list，随后是分立的sparse参数，各自在一个list中，最后一个是1维的label的list，数值为0，输出符合预期。

doc/distributed_train.md

 # PaddleRec 分布式训练
-## 分布式原理基本介绍
-> 占位
-
-## 单机代码转分布式代码
-
-> 占位
-### 训练代码准备
-参数服务器架构，有两个重要的组成部分：Server与Worker。为了启动训练，我们是否要准备两套代码分别运行呢？答案是不需要的。Paddle Fleet API将两者运行的逻辑进行了很好的统一，用户只需使用`fleet.init(role)`就可以判断当前启动的程序扮演server还是worker。使用如下的编程范式，只需10行，便可将单机代码转变为分布式代码：
-``` python
-role = role_maker.PaddleCloudRoleMaker()
-fleet.init(role)
-
-# Define your network, choose your optimizer(SGD/Adam/Adagrad etc.)
-strategy = StrategyFactory.create_sync_strategy()
-optimizer = fleet.distributed_optimizer(optimizer, strategy)
-
-if fleet.is_server():
-    fleet.init_server()
-    fleet.run_server()
-if fleet.is_worker():
-    fleet.init_worker()
-    # run training
-    fleet.stop_worker()
-```
-
-### 运行环境准备
-- Paddle参数服务器模式的训练，目前只支持在`Liunx`环境下运行，推荐使用`ubuntu`或`CentOS`
-- Paddle参数服务器模式的前端代码支持`python 2.7`及`python 3.5+`，若使用`Dataset`模式的高性能IO，需使用`python 2.7`
-- 使用多台机器进行分布式训练，请确保各自之间可以通过`ip:port`的方式访问`rpc`服务，使用`http/https`代理会导致通信失败
-- 各个机器之间的通信耗费应尽量少
-
-假设我们有两台机器，想要在每台机器上分别启动一个`server`进程以及一个`worker`进程，完成2x2（2个参数服务器，2个训练节点）的参数服务器模式分布式训练，按照如下步骤操作。
-
-### 启动server
-机器A，IP地址是`10.89.176.11`，通信端口是`36000`，配置如下环境变量后，运行训练的入口程序：
-```bash
-export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
-export TRAINING_ROLE=PSERVER
-export POD_IP=10.89.176.11 # node A：10.89.176.11
-export PADDLE_PORT=36000
-export PADDLE_TRAINERS_NUM=2
-python -u train.py --is_cloud=1
-```
-应能在日志中看到如下输出：
-
-> I0318 21:47:01.298220 188592128 grpc_server.cc:470] Server listening on 127.0.0.1:36000 selected port: 36000
-
-查看系统进程
-> 8624 | ttys000 | 0:02.31 | python -u train.py --is_cloud=1
-
-查看系统进程及端口占用：
-
-> python3.7 | 8624 | paddle | 8u | IPv6 | 0xe149b87d093872e5 | 0t0 | TCP |  localhost:36000 (LISTEN)
-
-也可以看到我们的`server`进程8624的确在`36000`端口开始了监听，等待`worker`的通信。
-
-机器B，IP地址是`10.89.176.12`，通信端口是`36000`，配置如下环境变量后，运行训练的入口程序：
-```bash
-export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
-export TRAINING_ROLE=PSERVER
-export POD_IP=10.89.176.12 # node B: 10.89.176.12
-export PADDLE_PORT=36000
-export PADDLE_TRAINERS_NUM=2
-python -u train.py --is_cloud=1
-```
-也可以看到相似的日志输出与进程状况。（进行验证时，请务必确保IP与端口的正确性）
-
-### 启动worker
-
-接下来我们分别在机器A与B上开启训练进程。配置如下环境变量并开启训练进程：
-
-机器A：
-```bash
-export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
-export TRAINING_ROLE=TRAINER
-export PADDLE_TRAINERS_NUM=2
-export PADDLE_TRAINER_ID=0 # node A：trainer_id = 0
-python -u train.py --is_cloud=1
-```
-
-机器B：
-```bash
-export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
-export TRAINING_ROLE=TRAINER
-export PADDLE_TRAINERS_NUM=2
-export PADDLE_TRAINER_ID=1 # node B: trainer_id = 1
-python -u train.py --is_cloud=1
-```
-
-运行该命令时，若pserver还未就绪，可在日志输出中看到如下信息：
-> server not ready, wait 3 sec to retry...
-> 
-> not ready endpoints:['10.89.176.11:36000', '10.89.176.12:36000']
-
-worker进程将持续等待，直到server开始监听，或等待超时。
-
-当pserver都准备就绪后，可以在日志输出看到如下信息：
-> I0317 11:38:48.099179 16719 communicator.cc:271] Communicator start
-> 
-> I0317 11:38:49.838711 16719 rpc_client.h:107] init rpc client with trainer_id 0
-
-至此，分布式训练启动完毕，将开始训练。
-
 
 ## PaddleRec分布式运行
 > 占位

doc/ps_background.md

+# 参数服务器训练简介
+
+
+如图1所示，参数服务器是分布式训练领域普遍采用的编程架构，主要包含Server和Worker两个部分，其中Server负责参数的存储和更新，而Worker负责训练。飞桨的参数服务器功能也是基于这种经典的架构进行设计和开发的，同时在这基础上进行了SGD（Stochastic Gradient Descent）算法的创新（Geometric Stochastic Gradient Descent）。当前经过大量的实验验证，最佳的方案是每台机器上启动Server和Worker两个进程，而一个Worker进程中可以包含多个用于训练的线程。
+<p align="center">
+<img align="center" src="imgs/ps-overview.png">
+<p>
+
+参数服务器是主要解决两类问题：
+
+- 模型参数过大：单机内存空间不足，需要采用分布式存储。
+- 训练数据过多：单机训练太慢，需要加大训练节点,来提高并发训练速度。 设想，当训练数据过多，一个Worker训练太慢时，可以引入多个Worker同时训练，这时Worker之间需要同步模型参数。直观想法是，引入一个Server，Server充当Worker间参数交换的媒介。但当模型参数过大以至于单机存储空间不足时或Worker过多导致一个Server是瓶颈时，就需要引入多个Server。
+
+
+具体训练流程：
+
+- 将训练数据均匀的分配给不同的Worker。
+- 将模型参数分片，存储在不同的Server上。
+- Worker端：读取一个minibatch训练数据，从Server端拉取最新的参数，计算梯度，并根据分片上传给不同的Server。
+- Server端：接收Worker端上传的梯度，根据优化算法更新参数。根据Server端每次参数更新是否需要等待所有Worker端的梯度，分为同步训练和异步训练两种机制。
+
+
+飞桨的参数服务器框架也是基于这种经典的参数服务器模式进行设计和开发的，同时在这基础上进行了SGD(Stochastic Gradient Descent）算法的创新（GEO-SGD）。目前飞桨支持3种模式，分别是同步训练模式、异步训练模式、GEO异步训练模式，如图2所示。
+
+<p align="center">
+<img align="center" src="imgs/fleet-ps.png">
+<p>
+
+## 同步训练
+
+Worker在训练一个batch的数据后，会合并所有线程的梯度发给Server, Server在收到所有节点的梯度后，会统一进行梯度合并及参数更新。同步训练的优势在于Loss可以比较稳定的下降，缺点是整个训练速度较慢，这是典型的木桶原理，速度的快慢取决于最慢的那个线程的训练计算时间，因此在训练较为复杂的模型时，即模型训练过程中神经网络训练耗时远大于节点间通信耗时的场景下，推荐使用同步训练模式。
+
+## 异步训练
+
+在训练一个batch的数据后，Worker的每个线程会发送梯度给Server。而Server不会等待接收所有节点的梯度，而是直接基于已收到的梯度进行参数更新。异步训练去除了训练过程中的等待机制，训练速度得到了极大的提升，但是缺点也很明显，那就是Loss下降不稳定，容易发生抖动。建议在个性化推荐（召回、排序）、语义匹配等数据量大的场景使用。 尤其是推荐领域的点击率预估场景，该场景可能会出现千亿甚至万亿规模的稀疏特征，而稀疏参数也可以达到万亿数量级，且需要小时级或分钟级流式增量训练。如果使用异步训练模式，可以很好的满足该场景的online-learning需求。
+
+## GEO异步训练
+
+GEO(Geometric Stochastic Gradient Descent)异步训练是飞桨自研的异步训练模式，其最大的特点是将参数的更新从Server转移到Worker上。每个Worker在本地训练过程中会使用SGD优化算法更新本地模型参数，在训练若干个batch的数据后，Worker将发送参数更新信息给Server。Server在接收后会通过加和方式更新保存的参数信息。所以显而易见，在GEO异步训练模式下，Worker不用再等待Server发来新的参数即可执行训练，在训练效果和训练速度上有了极大的提升。但是此模式比较适合可以在单机内能完整保存的模型，在搜索、NLP等类型的业务上应用广泛，推荐在词向量、语义匹配等场景中使用。
+
+> 运行策略的详细描述可以参考文档：[PaddlePaddle Fluid CPU分布式训练(Trainspiler)使用指南](https://www.paddlepaddle.org.cn/tutorials/projectdetail/454253)
+
+## 单机代码转分布式
+
+### 训练代码准备
+参数服务器架构，有两个重要的组成部分：Server与Worker。为了启动训练，我们是否要准备两套代码分别运行呢？答案是不需要的。Paddle Fleet API将两者运行的逻辑进行了很好的统一，用户只需使用`fleet.init(role)`就可以判断当前启动的程序扮演server还是worker。使用如下的编程范式，只需10行，便可将单机代码转变为分布式代码：
+``` python
+role = role_maker.PaddleCloudRoleMaker()
+fleet.init(role)
+
+# Define your network, choose your optimizer(SGD/Adam/Adagrad etc.)
+strategy = StrategyFactory.create_sync_strategy()
+optimizer = fleet.distributed_optimizer(optimizer, strategy)
+
+if fleet.is_server():
+    fleet.init_server()
+    fleet.run_server()
+if fleet.is_worker():
+    fleet.init_worker()
+    # run training
+    fleet.stop_worker()
+```
+
+### 运行环境准备
+- Paddle参数服务器模式的训练，目前只支持在`Liunx`环境下运行，推荐使用`ubuntu`或`CentOS`
+- Paddle参数服务器模式的前端代码支持`python 2.7`及`python 3.5+`，若使用`Dataset`模式的高性能IO，需使用`python 2.7`
+- 使用多台机器进行分布式训练，请确保各自之间可以通过`ip:port`的方式访问`rpc`服务，使用`http/https`代理会导致通信失败
+- 各个机器之间的通信耗费应尽量少
+
+假设我们有两台机器，想要在每台机器上分别启动一个`server`进程以及一个`worker`进程，完成2x2（2个参数服务器，2个训练节点）的参数服务器模式分布式训练，按照如下步骤操作。
+
+### 启动server
+机器A，IP地址是`10.89.176.11`，通信端口是`36000`，配置如下环境变量后，运行训练的入口程序：
+```bash
+export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
+export TRAINING_ROLE=PSERVER
+export POD_IP=10.89.176.11 # node A：10.89.176.11
+export PADDLE_PORT=36000
+export PADDLE_TRAINERS_NUM=2
+python -u train.py --is_cloud=1
+```
+应能在日志中看到如下输出：
+
+> I0318 21:47:01.298220 188592128 grpc_server.cc:470] Server listening on 127.0.0.1:36000 selected port: 36000
+
+查看系统进程
+> 8624 | ttys000 | 0:02.31 | python -u train.py --is_cloud=1
+
+查看系统进程及端口占用：
+
+> python3.7 | 8624 | paddle | 8u | IPv6 | 0xe149b87d093872e5 | 0t0 | TCP |  localhost:36000 (LISTEN)
+
+也可以看到我们的`server`进程8624的确在`36000`端口开始了监听，等待`worker`的通信。
+
+机器B，IP地址是`10.89.176.12`，通信端口是`36000`，配置如下环境变量后，运行训练的入口程序：
+```bash
+export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
+export TRAINING_ROLE=PSERVER
+export POD_IP=10.89.176.12 # node B: 10.89.176.12
+export PADDLE_PORT=36000
+export PADDLE_TRAINERS_NUM=2
+python -u train.py --is_cloud=1
+```
+也可以看到相似的日志输出与进程状况。（进行验证时，请务必确保IP与端口的正确性）
+
+### 启动worker
+
+接下来我们分别在机器A与B上开启训练进程。配置如下环境变量并开启训练进程：
+
+机器A：
+```bash
+export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
+export TRAINING_ROLE=TRAINER
+export PADDLE_TRAINERS_NUM=2
+export PADDLE_TRAINER_ID=0 # node A：trainer_id = 0
+python -u train.py --is_cloud=1
+```
+
+机器B：
+```bash
+export PADDLE_PSERVERS_IP_PORT_LIST="10.89.176.11:36000,10.89.176.12:36000"
+export TRAINING_ROLE=TRAINER
+export PADDLE_TRAINERS_NUM=2
+export PADDLE_TRAINER_ID=1 # node B: trainer_id = 1
+python -u train.py --is_cloud=1
+```
+
+运行该命令时，若pserver还未就绪，可在日志输出中看到如下信息：
+> server not ready, wait 3 sec to retry...
+> 
+> not ready endpoints:['10.89.176.11:36000', '10.89.176.12:36000']
+
+worker进程将持续等待，直到server开始监听，或等待超时。
+
+当pserver都准备就绪后，可以在日志输出看到如下信息：
+> I0317 11:38:48.099179 16719 communicator.cc:271] Communicator start
+> 
+> I0317 11:38:49.838711 16719 rpc_client.h:107] init rpc client with trainer_id 0
+
+至此，分布式训练启动完毕，将开始训练。
\ No newline at end of file

doc/rec_background.md

+# 推荐系统背景知识
+
+本文代码目录在[book/recommender_system](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system),初次使用请您参考[Book文档使用说明](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。
+
+更多教程及背景知识可以查阅[深度学习实践应用：个性化推荐](https://www.paddlepaddle.org.cn/tutorials/projectdetail/443958)
+
+## 背景介绍
+
+在网络技术不断发展和电子商务规模不断扩大的背景下，商品数量和种类快速增长，用户需要花费大量时间才能找到自己想买的商品，这就是信息超载问题。为了解决这个难题，个性化推荐系统（Recommender System）应运而生。
+
+个性化推荐系统是信息过滤系统（Information Filtering System）的子集，它可以用在很多领域，如电影、音乐、电商和 Feed 流推荐等。个性化推荐系统通过分析、挖掘用户行为，发现用户的个性化需求与兴趣特点，将用户可能感兴趣的信息或商品推荐给用户。与搜索引擎不同，个性化推荐系统不需要用户准确地描述出自己的需求，而是根据用户的历史行为进行建模，主动提供满足用户兴趣和需求的信息。
+
+1994年明尼苏达大学推出的GroupLens系统[[1](#参考文献)]一般被认为是个性化推荐系统成为一个相对独立的研究方向的标志。该系统首次提出了基于协同过滤来完成推荐任务的思想，此后，基于该模型的协同过滤推荐引领了个性化推荐系统十几年的发展方向。
+
+传统的个性化推荐系统方法主要有：
+
+- 协同过滤推荐（Collaborative Filtering Recommendation）：该方法是应用最广泛的技术之一，需要收集和分析用户的历史行为、活动和偏好。它通常可以分为两个子类：基于用户 （User-Based）的推荐[[1](#参考文献)] 和基于物品（Item-Based）的推荐[[2](#参考文献)]。该方法的一个关键优势是它不依赖于机器去分析物品的内容特征，因此它无需理解物品本身也能够准确地推荐诸如电影之类的复杂物品；缺点是对于没有任何行为的新用户存在冷启动的问题，同时也存在用户与商品之间的交互数据不够多造成的稀疏问题。值得一提的是，社交网络[[3](#参考文献)]或地理位置等上下文信息都可以结合到协同过滤中去。
+- 基于内容过滤推荐[[4](#参考文献)]（Content-based Filtering Recommendation）：该方法利用商品的内容描述，抽象出有意义的特征，通过计算用户的兴趣和商品描述之间的相似度，来给用户做推荐。优点是简单直接，不需要依据其他用户对商品的评价，而是通过商品属性进行商品相似度度量，从而推荐给用户所感兴趣商品的相似商品；缺点是对于没有任何行为的新用户同样存在冷启动的问题。
+- 组合推荐[[5](#参考文献)]（Hybrid Recommendation）：运用不同的输入和技术共同进行推荐，以弥补各自推荐技术的缺点。
+
+近些年来，深度学习在很多领域都取得了巨大的成功。学术界和工业界都在尝试将深度学习应用于个性化推荐系统领域中。深度学习具有优秀的自动提取特征的能力，能够学习多层次的抽象特征表示，并对异质或跨域的内容信息进行学习，可以一定程度上处理个性化推荐系统冷启动问题[[6](#参考文献)]。
+
+### YouTube的深度神经网络个性化推荐系统
+
+YouTube是世界上最大的视频上传、分享和发现网站，YouTube个性化推荐系统为超过10亿用户从不断增长的视频库中推荐个性化的内容。整个系统由两个神经网络组成：候选生成网络和排序网络。候选生成网络从百万量级的视频库中生成上百个候选，排序网络对候选进行打分排序，输出排名最高的数十个结果。系统结构如图1所示：
+
+<p align="center">
+<img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/YouTube_Overview.png?raw=true" width="70%" ><br/>
+图1. YouTube 个性化推荐系统结构
+</p>
+
+#### 候选生成网络（Candidate Generation Network）
+
+候选生成网络将推荐问题建模为一个类别数极大的多类分类问题：对于一个Youtube用户，使用其观看历史（视频ID）、搜索词记录（search tokens）、人口学信息（如地理位置、用户登录设备）、二值特征（如性别，是否登录）和连续特征（如用户年龄）等，对视频库中所有视频进行多分类，得到每一类别的分类结果（即每一个视频的推荐概率），最终输出概率较高的几百个视频。
+
+首先，将观看历史及搜索词记录这类历史信息，映射为向量后取平均值得到定长表示；同时，输入人口学特征以优化新用户的推荐效果，并将二值特征和连续特征归一化处理到[0, 1]范围。接下来，将所有特征表示拼接为一个向量，并输入给非线形多层感知器（MLP，详见[识别数字](https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/README.cn.md)教程）处理。最后，训练时将MLP的输出给softmax做分类，预测时计算用户的综合特征（MLP的输出）与所有视频的相似度，取得分最高的K个作为候选生成网络的筛选结果。
+
+#### 排序网络（Ranking Network）
+排序网络的结构类似于候选生成网络，但是它的目标是对候选进行更细致的打分排序。和传统广告排序中的特征抽取方法类似，这里也构造了大量的用于视频排序的相关特征（如视频 ID、上次观看时间等）。这些特征的处理方式和候选生成网络类似，不同之处是排序网络的顶部是一个加权逻辑回归（weighted logistic regression），它对所有候选视频进行打分，从高到底排序后将分数较高的一些视频返回给用户。
+
+### 融合推荐模型
+本节会使用卷积神经网络（Convolutional Neural Networks）来学习电影名称的表示。下面会依次介绍文本卷积神经网络以及融合推荐模型。
+
+#### 文本卷积神经网络（CNN）
+
+卷积神经网络经常用来处理具有类似网格拓扑结构（grid-like topology）的数据。例如，图像可以视为二维网格的像素点，自然语言可以视为一维的词序列。卷积神经网络可以提取多种局部特征，并对其进行组合抽象得到更高级的特征表示。实验表明，卷积神经网络能高效地对图像及文本问题进行建模处理。
+
+卷积神经网络主要由卷积（convolution）和池化（pooling）操作构成，其应用及组合方式灵活多变，种类繁多。
+
+
+<a name="参考文献"></a>
+## 参考文献
+
+1. P. Resnick, N. Iacovou, etc. “[GroupLens: An Open Architecture for Collaborative Filtering of Netnews](http://ccs.mit.edu/papers/CCSWP165.html)”, Proceedings of ACM Conference on Computer Supported Cooperative Work, CSCW 1994. pp.175-186.
+2. Sarwar, Badrul, et al. "[Item-based collaborative filtering recommendation algorithms.](http://files.grouplens.org/papers/www10_sarwar.pdf)" *Proceedings of the 10th international conference on World Wide Web*. ACM, 2001.
+3. Kautz, Henry, Bart Selman, and Mehul Shah. "[Referral Web: combining social networks and collaborative filtering.](http://www.cs.cornell.edu/selman/papers/pdf/97.cacm.refweb.pdf)" Communications of the ACM 40.3 (1997): 63-65. APA
+4. [Peter Brusilovsky](https://en.wikipedia.org/wiki/Peter_Brusilovsky) (2007). *The Adaptive Web*. p. 325.
+5. Robin Burke , [Hybrid Web Recommender Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.435.7538&rep=rep1&type=pdf), pp. 377-408, The Adaptive Web, Peter Brusilovsky, Alfred Kobsa, Wolfgang Nejdl (Ed.), Lecture Notes in Computer Science, Springer-Verlag, Berlin, Germany, Lecture Notes in Computer Science, Vol. 4321, May 2007, 978-3-540-72078-2.
+6. Yuan, Jianbo, et al. ["Solving Cold-Start Problem in Large-scale Recommendation Engines: A Deep Learning Approach."](https://arxiv.org/pdf/1611.05480v1.pdf) *arXiv preprint arXiv:1611.05480* (2016).
+
+
+<br/>
+<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="知识共享许可协议" style="border-width:0" src="https://paddlepaddleimage.cdn.bcebos.com/bookimage/camo.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">本教程</span> 由 <a xmlns:cc="http://creativecommons.org/ns#" href="http://book.paddlepaddle.org" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a> 创作，采用 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">知识共享 署名-相同方式共享 4.0 国际 许可协议</a>进行许可。

models/rank/dnn/config.yaml

@@ -24,6 +24,7 @@ train:
     batch_size: 2
     class: "{workspace}/../criteo_reader.py"
     train_data_path: "{workspace}/data/train"
+    reader_debug_mode: False
 
   model:
     models: "{workspace}/model.py"

models/recall/tdm/config.yaml

@@ -25,6 +25,7 @@ train:
     class: "{workspace}/tdm_reader.py"
     train_data_path: "{workspace}/data/train"
     test_data_path: "{workspace}/data/test"
+    reader_debug_mode: False
 
   model:
     models: "{workspace}/model.py"

models/recall/tdm/tdm_evaluate_reader.py

@@ -33,7 +33,8 @@ class EvaluateReader(Reader):
             This function needs to be implemented by the user, based on data format
             """
             features = (line.strip('\n')).split('\t')
-            input_emb = map(float, features[0].split(' '))
+            input_emb = features[0].split(' ')
+            input_emb = [float(i) for i in input_emb]
 
             feature_name = ["input_emb"]
             yield zip(feature_name, [input_emb])

models/recall/tdm/tdm_reader.py

@@ -33,7 +33,8 @@ class TrainReader(Reader):
             This function needs to be implemented by the user, based on data format
             """
             features = (line.strip('\n')).split('\t')
-            input_emb = map(float, features[0].split(' '))
+            input_emb = features[0].split(' ')
+            input_emb = [float(i) for i in input_emb]
             item_label = [int(features[1])]
 
             feature_name = ["input_emb", "item_label"]

readme.md

@@ -21,10 +21,10 @@
 <img align="center" src="doc/imgs/structure.png">
 <p>
 
-- PaddleRec是源于飞桨生态的搜索推荐模型一站式开箱即用工具，无论您是初学者，开发者，研究者均可便捷的使用PaddleRec完成调研，训练到预测部署的全流程工作。
-- PaddleRec提供了搜索推荐任务中语义理解、召回、粗排、精排、多任务学习的全流程解决方案，包含的算法模型均在百度各个业务的实际场景中得到了验证。
-- PaddleRec将各个模型及其训练预测流程规范化整理，进行易用性封装，用户只需自定义yaml文件即可快速上手使用。
-- PaddleRec以飞桨深度学习框架为核心，融合了大规模分布式训练框架Fleet，以及一键式推理部署框架PaddleServing，支持推荐搜索算法的工业化应用。
+- 源于飞桨生态的搜索推荐模型**一站式开箱即用工具** 
+- 适合初学者，开发者，研究者从调研，训练到预测部署的全流程解决方案
+- 包含语义理解、召回、粗排、精排、多任务学习、融合等多个任务的推荐搜索算法库
+- 配置**yaml**自定义选项，即可快速上手使用单机训练、大规模分布式训练、离线预测、在线部署
 
 
 <h2 align="center">PadlleRec概览</h2>
@@ -37,8 +37,8 @@
 <h2 align="center">便捷安装</h2>
 
 ### 环境要求
-* Python >= 2.7
-* PaddlePaddle >= 1.7.2
+* Python 2.7/ 3.5 / 3.6 / 3.7
+* PaddlePaddle  >= 1.7.2
 * 操作系统: Windows/Mac/Linux
   
 ### 安装命令
@@ -57,7 +57,7 @@
     python -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
     ```
 
-  2. 源码安装Fleet-Rec
+  2. 源码安装PaddleRec
 
     ```
     git clone https://github.com/PaddlePaddle/PaddleRec/
@@ -68,97 +68,92 @@
 
 <h2 align="center">快速启动</h2>
 
+### 启动内置模型的默认配置
 
 目前框架内置了多个模型，简单的命令即可使用内置模型开始单机训练和本地1*1模拟训练，我们以`ctr-dnn`为例介绍PaddleRec的简单使用。
 
-### 一行命令启动训练
-
 <h3 align="center">单机训练</h3>
 
 ```bash
 # 使用CPU进行单机训练
-python -m fleetrec.run -m fleetrec.models.rank.dnn -d cpu -e single 
+python -m paddlerec.run -m paddlerec.models.rank.dnn -d cpu -e single 
 
 # 使用GPU进行单机训练
-python -m fleetrec.run -m fleetrec.models.rank.dnn -d gpu -e single
+python -m paddlerec.run -m paddlerec.models.rank.dnn -d gpu -e single
 ```
 
 <h3 align="center">本地模拟分布式训练</h3>
 
 ```bash
 # 使用CPU资源进行本地模拟分布式训练
-python -m fleetrec.run -m fleetrec.models.rank.dnn -d cpu -e local_cluster
+python -m paddlerec.run -m paddlerec.models.rank.dnn -e local_cluster
 ```
 
 <h3 align="center">集群分布式训练</h3>
 
 ```bash
 # 配置好 mpi/k8s/paddlecloud集群环境后
-python -m fleetrec.run -m fleetrec.models.rank.dnn -d cpu -e cluster
+python -m paddlerec.run -m paddlerec.models.rank.dnn -e cluster
 ```
 
-<h2 align="center">支持模型列表</h2>
+### 启动内置模型的自定配置
+
+若您复用内置模型，对**yaml**配置文件进行了修改，如更改超参，重新配置数据后，可以直接使用paddlerec运行该yaml文件。
 
-> 部分表格占位待改（大规模稀疏）
+例如在paddlerec代码目录下，修改了dnn模型`config.yaml`的配置后，运行`ctr-dnn`模型：
+```bash
+python -m paddlerec.run -m ./models/rank/dnn/config.yaml -e single
+```
 
-|   方向   |                                      模型                                      | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 | 大规模稀疏 | 分布式GPU训练 | 自定义数据集 |
-| :------: | :----------------------------------------------------------------------------: | :---------: | :---------: | :-----------: | :--------: | :-----------: | :----------: |
-| 内容理解 | [Text-Classifcation](models/contentunderstanding/text_classification/model.py) |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-| 内容理解 |           [TagSpace](models/contentunderstanding/tagspace/model.py)            |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   召回   |                  [Word2Vec](models/recall/word2vec/model.py)                   |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   召回   |                       [TDM](models/recall/tdm/model.py)                        |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   召回   |                       [SSR](models/recall/ssr/model.py)                        |      ✓      |      ✓      |       ✓       |     x      |       ✓       |      ✓       |
-|   召回   |                   [Gru4Rec](models/recall/gru4rec/model.py)                    |      ✓      |      ✓      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |                      [CTR-Dnn](models/rank/dnn/model.py)                       |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |                     [DeepFm](models/rank/deepfm/model.py)                      |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |                    [xDeepFm](models/rank/xdeepfm/model.py)                     |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |                        [DIN](models/rank/din/model.py)                         |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |                  [Wide&Deep](models/rank/wide_deep/model.py)                   |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|  多任务  |                     [ESMM](models/multitask/essm/model.py)                     |      ✓      |      ✓      |       ✓       |     x      |       ✓       |      ✓       |
-|  多任务  |                     [MMOE](models/multitask/mmoe/model.py)                     |      ✓      |      ✓      |       ✓       |     x      |       ✓       |      ✓       |
-|   排序   |             [ShareBottom](models/multitask/share-bottom/model.py)              |      ✓      |      ✓      |       ✓       |     x      |       ✓       |      ✓       |
-|   匹配   |                       [DSSM](models/match/dssm/model.py)                       |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
-|   匹配   |                [Simnet](models/match/multiview-simnet/model.py)                |      ✓      |      x      |       ✓       |     x      |       ✓       |      ✓       |
 
+<h2 align="center">支持模型列表</h2>
 
 
+|   方向   |                                      模型                                      | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 | 分布式GPU训练 |
+| :------: | :----------------------------------------------------------------------------: | :---------: | :---------: | :-----------: | :-----------: |
+| 内容理解 | [Text-Classifcation](models/contentunderstanding/text_classification/model.py) |      ✓      |      x      |       ✓       |       x       |
+| 内容理解 |           [TagSpace](models/contentunderstanding/tagspace/model.py)            |      ✓      |      x      |       ✓       |       x       |
+|   召回   |                  [Word2Vec](models/recall/word2vec/model.py)                   |      ✓      |      x      |       ✓       |       x       |
+|   召回   |                       [TDM](models/recall/tdm/model.py)                        |      ✓      |      x      |       ✓       |       x       |
+|   召回   |                       [SSR](models/recall/ssr/model.py)                        |      ✓      |      ✓      |       ✓       |       x       |
+|   召回   |                   [Gru4Rec](models/recall/gru4rec/model.py)                    |      ✓      |      ✓      |       ✓       |       x       |
+|   排序   |                      [CTR-Dnn](models/rank/dnn/model.py)                       |      ✓      |      x      |       ✓       |       x       |
+|   排序   |                     [DeepFm](models/rank/deepfm/model.py)                      |      ✓      |      x      |       ✓       |       x       |
+|   排序   |                    [xDeepFm](models/rank/xdeepfm/model.py)                     |      ✓      |      x      |       ✓       |       x       |
+|   排序   |                        [DIN](models/rank/din/model.py)                         |      ✓      |      x      |       ✓       |       x       |
+|   排序   |                  [Wide&Deep](models/rank/wide_deep/model.py)                   |      ✓      |      x      |       ✓       |       x       |
+|  多任务  |                     [ESMM](models/multitask/essm/model.py)                     |      ✓      |      ✓      |       ✓       |       x       |
+|  多任务  |                     [MMOE](models/multitask/mmoe/model.py)                     |      ✓      |      ✓      |       ✓       |       x       |
+|   排序   |             [ShareBottom](models/multitask/share-bottom/model.py)              |      ✓      |      ✓      |       ✓       |       x       |
+|   匹配   |                       [DSSM](models/match/dssm/model.py)                       |      ✓      |      x      |       ✓       |       x       |
+|   匹配   |                [Simnet](models/match/multiview-simnet/model.py)                |      ✓      |      x      |       ✓       |       x       |
+
 
 
 <h2 align="center">文档</h2>
 
 ### 新手教程
-* [环境要求](#环境要求)
-* [安装命令](#安装命令)
-* [快速开始](#一行命令启动训练)
-  
+* [推荐系统背景介绍](doc/rec_background.md)
+* [分布式-参数服务器背景介绍](doc/ps_background.md)
+
 ### 进阶教程
 * [自定义数据集及Reader](doc/custom_dataset_reader.md)
-* [模型调参](doc/optimization_model.md)
-* [单机训练](doc/local_train.md)
 * [分布式训练](doc/distributed_train.md)
-* [离线预测](doc/predict.md)
 
 ### 关于PaddleRec性能
-* [Benchamrk](doc/benchmark.md)
+* [Benchmark](doc/benchmark.md)
 
 ### FAQ
 * [常见问题FAQ](doc/faq.md)
 
-### 设计文档
-* [PaddleRec设计文档](doc/design.md)
-
 
 <h2 align="center">社区</h2>
 
-### 贡献代码
-* [优化PaddleRec框架](doc/contribute.md)
-* [新增模型到PaddleRec](doc/contribute.md)
-
 ### 反馈
 如有意见、建议及使用中的BUG，欢迎在`GitHub Issue`提交
 
 ### 版本历史
-* [版本更新](#版本更新)
+- 2020.5.14 - PaddleRec v0.1
   
 ### 许可证书
 本项目的发布受[Apache 2.0 license](LICENSE)许可认证。

run.py

@@ -152,7 +152,8 @@ def cluster_engine(args):
         cluster_envs["train.trainer.engine"] = "cluster"
         cluster_envs["train.trainer.device"] = args.device
         cluster_envs["train.trainer.platform"] = envs.get_platform()
-        print("launch {} engine with cluster to with model: {}".format(trainer, args.model))
+        print("launch {} engine with cluster to with model: {}".format(
+            trainer, args.model))
         set_runtime_envs(cluster_envs, args.model)
 
         trainer = TrainerFactory.create(args.model)
@@ -245,9 +246,11 @@ if __name__ == "__main__":
                         choices=["single", "local_cluster", "cluster",
                                  "tdm_single", "tdm_local_cluster", "tdm_cluster"])
 
-    parser.add_argument("-d", "--device", type=str, choices=["cpu", "gpu"], default="cpu")
+    parser.add_argument("-d", "--device", type=str,
+                        choices=["cpu", "gpu"], default="cpu")
     parser.add_argument("-b", "--backend", type=str, default=None)
-    parser.add_argument("-r", "--role", type=str, choices=["master", "worker"], default="master")
+    parser.add_argument("-r", "--role", type=str,
+                        choices=["master", "worker"], default="master")
 
     abs_dir = os.path.dirname(os.path.abspath(__file__))
     envs.set_runtime_environs({"PACKAGE_BASE": abs_dir})