Merge branch 'doc_update' into 'develop'

Doc update

See merge request !22

core/engine/local_cluster.py

@@ -22,6 +22,7 @@ import copy
 from paddlerec.core.engine.engine import Engine
 from paddlerec.core.utils import envs
 
+
 class LocalClusterEngine(Engine):
     def start_procs(self):
         worker_num = self.envs["worker_num"]
@@ -36,7 +37,7 @@ class LocalClusterEngine(Engine):
         current_env.pop("https_proxy", None)
         procs = []
         log_fns = []
-       
+
         for i in range(server_num - 1):
             while True:
                 new_port = envs.find_free_port()
@@ -44,8 +45,10 @@ class LocalClusterEngine(Engine):
                     ports.append(new_port)
                     break
         user_endpoints = ",".join(["127.0.0.1:" + str(x) for x in ports])
-        user_endpoints_ips = [x.split(":")[0] for x in user_endpoints.split(",")]
-        user_endpoints_port = [x.split(":")[1] for x in user_endpoints.split(",")]
+        user_endpoints_ips = [x.split(":")[0]
+                              for x in user_endpoints.split(",")]
+        user_endpoints_port = [x.split(":")[1]
+                               for x in user_endpoints.split(",")]
 
         factory = "paddlerec.core.factory"
         cmd = [sys.executable, "-u", "-m", factory, self.trainer]
@@ -62,7 +65,8 @@ class LocalClusterEngine(Engine):
             os.system("mkdir -p {}".format(logs_dir))
             fn = open("%s/server.%d" % (logs_dir, i), "w")
             log_fns.append(fn)
-            proc = subprocess.Popen(cmd, env=current_env, stdout=fn, stderr=fn, cwd=os.getcwd())
+            proc = subprocess.Popen(
+                cmd, env=current_env, stdout=fn, stderr=fn, cwd=os.getcwd())
             procs.append(proc)
 
         for i in range(worker_num):
@@ -76,7 +80,8 @@ class LocalClusterEngine(Engine):
             os.system("mkdir -p {}".format(logs_dir))
             fn = open("%s/worker.%d" % (logs_dir, i), "w")
             log_fns.append(fn)
-            proc = subprocess.Popen(cmd, env=current_env, stdout=fn, stderr=fn, cwd=os.getcwd())
+            proc = subprocess.Popen(
+                cmd, env=current_env, stdout=fn, stderr=fn, cwd=os.getcwd())
             procs.append(proc)
 
         # only wait worker to finish here

core/utils/envs.py

@@ -79,7 +79,8 @@ def get_global_env(env_name, default_value=None, namespace=None):
     """
     get os environment value
     """
-    _env_name = env_name if namespace is None else ".".join([namespace, env_name])
+    _env_name = env_name if namespace is None else ".".join(
+        [namespace, env_name])
     return global_envs.get(_env_name, default_value)
 
 
@@ -147,7 +148,8 @@ def pretty_print_envs(envs, header=None):
 
 def lazy_instance_by_package(package, class_name):
     models = get_global_env("train.model.models")
-    model_package = __import__(package, globals(), locals(), package.split("."))
+    model_package = __import__(
+        package, globals(), locals(), package.split("."))
     instance = getattr(model_package, class_name)
     return instance
 
@@ -157,7 +159,8 @@ def lazy_instance_by_fliename(abs, class_name):
     sys.path.append(dirname)
     package = os.path.splitext(os.path.basename(abs))[0]
 
-    model_package = __import__(package, globals(), locals(), package.split("."))
+    model_package = __import__(
+        package, globals(), locals(), package.split("."))
     instance = getattr(model_package, class_name)
     return instance
 
@@ -172,6 +175,13 @@ def get_platform():
     if 'Windows' in plats:
         return "WINDOWS"
 
+
+<< << << < HEAD: fleet_rec/core/utils/envs.py
+
+== == == =
+>>>>>> > upstream/develop: core/utils/envs.py
+
+
 def find_free_port():
     def __free_port():
         with closing(socket.socket(socket.AF_INET,

doc/benchmark.md

+# PaddleRec Benchmark
+> 占位
\ No newline at end of file

doc/contribute.md

+# PaddleRec 贡献代码
+> 占位
\ No newline at end of file

doc/custom_dataset_reader.md

+# PaddleRec 自定义数据集及Reader
+
+## dataset数据读取
+为了能高速运行CTR模型的训练，我们使用`dataset`API进行高性能的IO，dataset是为多线程及全异步方式量身打造的数据读取方式，每个数据读取线程会与一个训练线程耦合，形成了多生产者-多消费者的模式，会极大的加速我们的模型训练。
+
+如何在我们的训练中引入dataset读取方式呢？无需变更数据格式，只需在我们的训练代码中加入以下内容，便可达到媲美二进制读取的高效率，以下是一个比较完整的流程：
+
+### 引入dataset
+
+1. 通过工厂类`fluid.DatasetFactory()`创建一个dataset对象。
+2. 将我们定义好的数据输入格式传给dataset，通过`dataset.set_use_var(inputs)`实现。
+3. 指定我们的数据读取方式，由`dataset_generator.py`实现数据读取的规则，后面将会介绍读取规则的实现。
+4. 指定数据读取的batch_size。
+5. 指定数据读取的线程数，该线程数和训练线程应保持一致，两者为耦合的关系。
+6. 指定dataset读取的训练文件的列表。
+
+
+```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)
+    ]
+    logger.info("file list: {}".format(file_list))
+    return dataset, file_list
+```
+
+### 如何指定数据读取规则
+
+在上文我们提到了由`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])]`
+
+
+```python
+import paddle.fluid.incubate.data_generator as dg
+
+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)
+
+class CriteoDataset(dg.MultiSlotDataGenerator):
+   
+    def generate_sample(self, line):
+        
+        def reader():
+            features = line.rstrip('\n').split('\t')
+            dense_feature = []
+            sparse_feature = []
+            for idx in 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_:
+                sparse_feature.append(
+                    [hash(str(idx) + features[idx]) % 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.append("label")
+
+            yield zip(feature_name, [dense_feature] + sparse_feature + [label])
+
+        return reader
+
+d = CriteoDataset()
+d.run_from_stdin()
+```
+### 快速调试Dataset
+我们可以脱离组网架构，单独验证Dataset的输出是否符合我们预期。使用命令
+`cat 数据文件 | python dataset读取python文件`进行dataset代码的调试：
+```bash
+cat train_data/part-0 | python dataset_generator.py
+```
+输出的数据格式如下：
+` dense_input:size ; dense_input:value ; sparse_input:size ; sparse_input:value ; ... ; sparse_input:size ; sparse_input:value ; label:size ; label:value `
+
+理想的输出为(截取了一个片段)：
+```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
+...
+```
+
+>使用Dataset的一些注意事项
+> - Dataset的基本原理：将数据print到缓存，再由C++端的代码实现读取，因此，我们不能在dataset的读取代码中，加入与数据读取无关的print信息，会导致C++端拿到错误的数据信息。
+> - dataset目前只支持在`unbuntu`及`CentOS`等标准Linux环境下使用，在`Windows`及`Mac`下使用时，会产生预料之外的错误，请知悉。
\ No newline at end of file

doc/design.md

+# PaddleRec 设计
+> 占位
\ No newline at end of file

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分布式运行
+> 占位
+### 本地模拟分布式
+> 占位
+### MPI集群运行分布式
+> 占位
+### PaddleCloud集群运行分布式
+> 占位
+### K8S集群运行分布式
+> 占位
+
+

doc/faq.md

+# 常见问题FAQ
+> 占位
\ No newline at end of file

doc/local_train.md

+# PaddleRec 单机训练
+> 占位
\ No newline at end of file

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      |       ✓       |      ✓       |
+

doc/optimization_model.md

+# PaddleRec 模型调参
+> 占位
\ No newline at end of file

doc/predict.md

+# PaddleRec 离线预测
\ No newline at end of file

models/rank/dnn/README.md

+# 基于DNN模型的点击率预估模型
+
+## 介绍
+`CTR(Click Through Rate)`，即点击率，是“推荐系统/计算广告”等领域的重要指标，对其进行预估是商品推送/广告投放等决策的基础。简单来说，CTR预估对每次广告的点击情况做出预测，预测用户是点击还是不点击。CTR预估模型综合考虑各种因素、特征，在大量历史数据上训练，最终对商业决策提供帮助。本模型实现了下述论文中提出的DNN模型：
+
+```text
+@inproceedings{guo2017deepfm,
+  title={DeepFM: A Factorization-Machine based Neural Network for CTR Prediction},
+  author={Huifeng Guo, Ruiming Tang, Yunming Ye, Zhenguo Li and Xiuqiang He},
+  booktitle={the Twenty-Sixth International Joint Conference on Artificial Intelligence (IJCAI)},
+  pages={1725--1731},
+  year={2017}
+}
+```
+
+#
+## 数据准备
+### 数据来源
+训练及测试数据集选用[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>```特征已被移除。
+
+### 数据预处理
+数据预处理共包括两步：
+- 将原始训练集按9:1划分为训练集和验证集
+- 数值特征（连续特征）需进行归一化处理，但需要注意的是，对每一个特征```<integer feature i>```，归一化时用到的最大值并不是用全局最大值，而是取排序后95%位置处的特征值作为最大值，同时保留极值。
+
+### 一键下载训练及测试数据
+```bash
+sh download_data.sh
+```
+执行该脚本，会从国内源的服务器上下载Criteo数据集，并解压到指定文件夹。全量训练数据放置于`./train_data_full/`，全量测试数据放置于`./test_data_full/`，用于快速验证的训练数据与测试数据放置于`./train_data/`与`./test_data/`。
+
+执行该脚本的理想输出为：
+```bash
+> sh download_data.sh
+--2019-11-26 06:31:33--  https://fleet.bj.bcebos.com/ctr_data.tar.gz
+Resolving fleet.bj.bcebos.com... 10.180.112.31
+Connecting to fleet.bj.bcebos.com|10.180.112.31|:443... connected.
+HTTP request sent, awaiting response... 200 OK
+Length: 4041125592 (3.8G) [application/x-gzip]
+Saving to: “ctr_data.tar.gz”
+
+100%[==================================================================================================================>] 4,041,125,592  120M/s   in 32s
+
+2019-11-26 06:32:05 (120 MB/s) - “ctr_data.tar.gz” saved [4041125592/4041125592]
+
+raw_data/
+raw_data/part-55
+raw_data/part-113
+...
+test_data/part-227
+test_data/part-222
+Complete data download.
+Full Train data stored in ./train_data_full
+Full Test data stored in ./test_data_full
+Rapid Verification train data stored in ./train_data
+Rapid Verification test data stored in ./test_data
+```
+至此，我们已完成数据准备的全部工作。
+
+## 数据读取
+为了能高速运行CTR模型的训练，`PaddleRec`封装了`dataset`与`dataloader`API进行高性能的数据读取。
+
+如何在我们的训练中引入dataset读取方式呢？无需变更数据格式，只需在我们的训练代码中加入以下内容，便可达到媲美二进制读取的高效率，以下是一个比较完整的流程：
+
+### 引入dataset
+
+1. 通过工厂类`fluid.DatasetFactory()`创建一个dataset对象。
+2. 将我们定义好的数据输入格式传给dataset，通过`dataset.set_use_var(inputs)`实现。
+3. 指定我们的数据读取方式，由`dataset_generator.py`实现数据读取的规则，后面将会介绍读取规则的实现。
+4. 指定数据读取的batch_size。
+5. 指定数据读取的线程数，该线程数和训练线程应保持一致，两者为耦合的关系。
+6. 指定dataset读取的训练文件的列表。
+
+```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)
+    ]
+    logger.info("file list: {}".format(file_list))
+    return dataset, file_list
+```
+
+### 如何指定数据读取规则
+
+在上文我们提到了由`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])]`
+
+
+```python
+import paddle.fluid.incubate.data_generator as dg
+
+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)
+
+class CriteoDataset(dg.MultiSlotDataGenerator):
+   
+    def generate_sample(self, line):
+        
+        def reader():
+            features = line.rstrip('\n').split('\t')
+            dense_feature = []
+            sparse_feature = []
+            for idx in 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_:
+                sparse_feature.append(
+                    [hash(str(idx) + features[idx]) % 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.append("label")
+
+            yield zip(feature_name, [dense_feature] + sparse_feature + [label])
+
+        return reader
+
+d = CriteoDataset()
+d.run_from_stdin()
+```
+### 快速调试Dataset
+我们可以脱离组网架构，单独验证Dataset的输出是否符合我们预期。使用命令
+`cat 数据文件 | python dataset读取python文件`进行dataset代码的调试：
+```bash
+cat train_data/part-0 | python dataset_generator.py
+```
+输出的数据格式如下：
+` dense_input:size ; dense_input:value ; sparse_input:size ; sparse_input:value ; ... ; sparse_input:size ; sparse_input:value ; label:size ; label:value `
+
+理想的输出为(截取了一个片段)：
+```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
+...
+```
+
+#
+## 模型组网
+### 数据输入声明
+正如数据准备章节所介绍，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.data()`，会创建指定类型的占位符，数据IO会依据此定义进行数据的输入。
+```python
+dense_input = fluid.data(name="dense_input",
+                                 shape=[-1, args.dense_feature_dim],
+                                 dtype="float32")
+
+sparse_input_ids = [
+    fluid.data(name="C" + str(i),
+                shape=[-1, 1],
+                lod_level=1,
+                dtype="int64") for i in range(1, 27)
+]
+
+label = fluid.data(name="label", shape=[-1, 1], dtype="int64")
+inputs = [dense_input] + sparse_input_ids + [label]
+```
+
+### CTR-DNN模型组网
+
+CTR-DNN模型的组网比较直观，本质是一个二分类任务，代码参考`network_conf.py`。模型主要组成是一个`Embedding`层，三个`FC`层，以及相应的分类任务的loss计算和auc计算。
+
+#### Embedding层
+首先介绍Embedding层的搭建方式：`Embedding`层的输入是`sparse_input`，shape由超参的`sparse_feature_dim`和`embedding_size`定义。需要特别解释的是`is_sparse`参数，当我们指定`is_sprase=True`后，计算图会将该参数视为稀疏参数，反向更新以及分布式通信时，都以稀疏的方式进行，会极大的提升运行效率，同时保证效果一致。
+
+各个稀疏的输入通过Embedding层后，将其合并起来，置于一个list内，以方便进行concat的操作。
+
+```python
+def embedding_layer(input):
+   return fluid.layers.embedding(
+            input=input,
+            is_sparse=True,
+            size=[args.sparse_feature_dim, 
+                  args.embedding_size],
+            param_attr=fluid.ParamAttr(
+            name="SparseFeatFactors",
+            initializer=fluid.initializer.Uniform()),
+   )
+
+sparse_embed_seq = list(map(embedding_layer, inputs[1:-1])) # [C1~C26]
+```
+
+#### FC层
+将离散数据通过embedding查表得到的值，与连续数据的输入进行`concat`操作，合为一个整体输入，作为全链接层的原始输入。我们共设计了3层FC，每层FC的输出维度都为400，每层FC都后接一个`relu`激活函数，每层FC的初始化方式为符合正态分布的随机初始化，标准差与上一层的输出维度的平方根成反比。
+```python
+concated = fluid.layers.concat(sparse_embed_seq + inputs[0:1], axis=1)
+        
+fc1 = fluid.layers.fc(
+   input=concated,
+   size=400,
+   act="relu",
+   param_attr=fluid.ParamAttr(initializer=fluid.initializer.Normal(
+         scale=1 / math.sqrt(concated.shape[1]))),
+)
+fc2 = fluid.layers.fc(
+   input=fc1,
+   size=400,
+   act="relu",
+   param_attr=fluid.ParamAttr(initializer=fluid.initializer.Normal(
+         scale=1 / math.sqrt(fc1.shape[1]))),
+)
+fc3 = fluid.layers.fc(
+   input=fc2,
+   size=400,
+   act="relu",
+   param_attr=fluid.ParamAttr(initializer=fluid.initializer.Normal(
+         scale=1 / math.sqrt(fc2.shape[1]))),
+)
+```
+#### Loss及Auc计算
+- 预测的结果通过一个输出shape为2的FC层给出，该FC层的激活函数时softmax，会给出每条样本分属于正负样本的概率。
+- 每条样本的损失由交叉熵给出，交叉熵的输入维度为[batch_size,2]，数据类型为float，label的输入维度为[batch_size,1]，数据类型为int。
+- 该batch的损失`avg_cost`是各条样本的损失之和
+- 我们同时还会计算预测的auc，auc的结果由`fluid.layers.auc()`给出，该层的返回值有三个，分别是全局auc: `auc_var`，当前batch的auc: `batch_auc_var`，以及auc_states: `auc_states`，auc_states包含了`batch_stat_pos, batch_stat_neg, stat_pos, stat_neg`信息。`batch_auc`我们取近20个batch的平均，由参数`slide_steps=20`指定，roc曲线的离散化的临界数值设置为4096，由`num_thresholds=2**12`指定。
+```
+predict = fluid.layers.fc(
+            input=fc3,
+            size=2,
+            act="softmax",
+            param_attr=fluid.ParamAttr(initializer=fluid.initializer.Normal(
+                scale=1 / math.sqrt(fc3.shape[1]))),
+        )
+
+cost = fluid.layers.cross_entropy(input=predict, label=inputs[-1])
+avg_cost = fluid.layers.reduce_sum(cost)
+accuracy = fluid.layers.accuracy(input=predict, label=inputs[-1])
+auc_var, batch_auc_var, auc_states = fluid.layers.auc(
+                                          input=predict,
+                                          label=inputs[-1],
+                                          num_thresholds=2**12,
+                                          slide_steps=20)
+```
+
+完成上述组网后，我们最终可以通过训练拿到`avg_cost`与`auc`两个重要指标。
+
+
+# 训练
+## 单机训练
+## 分布式训练
+### 本地模拟分布式
+### 百度云分布式训练
+
+# 预测

models/recall/tdm/README.md

+# 基于DNN模型的TDM召回模型
+
+## 论文介绍
+## 目录
+* [数据准备](#数据准备)
+    * [数据来源](#数据来源)
+    * [数据预处理](#数据预处理)
+    * [一键下载训练及测试数据](#一键下载训练及测试数据)
+    * [数据读取](#数据读取)
+* [模型组网](#模型组网)
+    * [输入定义](#输入定义)
+    * [模型组网](#模型组网)
+    * [Loss定义](#loss定义)
+* [训练](#训练)
+    * [单机训练](#单机训练)
+    * [分布式训练](#分布式训练)
+    * [本地模拟分布式](#本地模拟分布式)
+    * [百度云分布式训练](#百度云分布式训练)
+* [预测](#预测)
+    * [本地预测](#本地预测)
+    * [Benchmark](#benchmark)
+* [调优](#调优)
+    * [效果调优](#效果调优)
+    * [性能调优](#性能调优)
+* [模型产出与部署](#模型产出与部署)
+
+#
+## 数据准备
+### 数据来源
+### 数据预处理
+### 一键下载训练及测试数据
+### 数据读取
+
+
+#
+## 模型组网
+### 输入定义
+### 模型组网
+### Loss定义
+
+#
+## 训练
+### 单机训练
+### 分布式训练
+#### 本地模拟分布式
+#### 百度云分布式训练
+
+#
+## 预测
+### 预测组网
+### 本地预测
+### Benchmark
+
+#
+## 调优
+### 效果调优
+### 性能调优
+
+#
+## 模型产出与部署
+

readme.md

@@ -2,69 +2,40 @@
 <img align="center" src="doc/imgs/logo.png">
 <p>
 
-[![License](https://img.shields.io/badge/license-Apache%202-red.svg)](LICENSE)
-[![Version](https://img.shields.io/github/v/release/PaddlePaddle/Paddle.svg)](https://github.com/PaddlePaddle/PaddleRec/releases)
+<p align="center">
+    <br>
+    <a href="https://travis-ci.com/PaddlePaddle/Serving">
+        <img alt="Build Status" src="https://img.shields.io/travis/com/PaddlePaddle/Serving/develop">
+    </a>
+    <img alt="Release" src="https://img.shields.io/badge/Release-0.0.3-yellowgreen">
+    <img alt="Issues" src="https://img.shields.io/github/issues/PaddlePaddle/Serving">
+    <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>
+
+
+<h2 align="center">什么是PaddleRec</h2>
+
+<p align="center">
+<img align="center" src="doc/imgs/structure.png">
+<p>
+
+- PaddleRec是源于飞桨生态的搜索推荐模型一站式开箱即用工具，无论您是初学者，开发者，研究者均可便捷的使用PaddleRec完成调研，训练到预测部署的全流程工作。
+- PaddleRec提供了搜索推荐任务中语义理解、召回、粗排、精排、多任务学习的全流程解决方案，包含的算法模型均在百度各个业务的实际场景中得到了验证。
+- PaddleRec将各个模型及其训练预测流程规范化整理，进行易用性封装，用户只需自定义yaml文件即可快速上手使用。
+- PaddleRec以飞桨深度学习框架为核心，融合了大规模分布式训练框架Fleet，以及一键式推理部署框架PaddleServing，支持推荐搜索算法的工业化应用。
 
-PaddleRec是源于飞桨生态的搜索推荐模型一站式开箱即用工具，无论您是初学者，开发者，研究者均可便捷的使用PaddleRec完成调研，训练到预测部署的全流程工作。PaddleRec提供了搜索推荐任务中语义理解、召回、粗排、精排、多任务学习的全流程解决方案。
 
-PadlleRec以预置模型为核心,具备以下特点：
-- [易于上手，开箱即用](https://www.paddlepaddle.org.cn)
-- [灵活配置，个性调参](https://www.paddlepaddle.org.cn)
-- [分布式训练，大规模稀疏](https://www.paddlepaddle.org.cn)
-- [快速部署，一键上线](https://www.paddlepaddle.org.cn)
+<h2 align="center">PadlleRec概览</h2>
 
 <p align="center">
-<img align="center" src="doc/imgs/coding-gif.png">
+<img align="center" src="doc/imgs/overview.png">
 <p>
 
-# 目录
-* [特性](#特性)
-* [支持模型列表](#支持模型列表)
-* [文档教程](#文档教程)
-  * [入门教程](#入门教程)
-     * [环境要求](#环境要求)
-     * [安装命令](#安装命令)
-     * [快速开始](#快速开始)
-     * [常见问题FAQ](#常见问题faq)
-  * [进阶教程](#进阶教程)
-     * [自定义数据集及Reader](#自定义数据集及reader)
-     * [模型调参](#模型调参)
-     * [单机训练](#单机训练)
-     * [分布式训练](#分布式训练)
-     * [预测部署](#预测部署)
-* [版本历史](#版本历史)
-  * [版本更新](#版本更新)
-  * [Benchamrk](#benchamrk)
-* [许可证书](#许可证书)
-* [如何贡献代码](#如何贡献代码)
-  * [优化PaddleRec框架](#优化paddlerec框架)
-  * [新增模型到PaddleRec](#新增模型到paddlerec)
-
-
-
-# 特性
-- 易于上手，开箱即用
-- 灵活配置，个性调参
-- 分布式训练，大规模稀疏
-- 快速部署，一键上线
-
-# 支持模型列表
-|         方向         |          模型          | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 | 分布式GPU训练 | 自定义数据集 | 服务器部署 |
-| :------------------: | :--------------------: | :---------: | :---------: | :-----------: | :-----------: | :----------: | :--------: |
-| ContentUnderstanding | [Text-Classifcation]() |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-| ContentUnderstanding |      [TagSpace]()      |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|        Recall        |      [Word2Vec]()      |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|        Recall        |        [TDM]()         |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|         Rank         |      [CTR-Dnn]()       |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|         Rank         |       [DeepFm]()       |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|        Rerank        |      [ListWise]()      |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|      MultiTask       |        [MMOE]()        |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|      MultiTask       |        [ESSM]()        |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|        Match         |        [DSSM]()        |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-|        Match         |  [Multiview-Simnet]()  |      ✓      |      x      |       ✓       |       x       |      ✓       |     ✓      |
-
-# 文档教程
-## 入门教程
+
+<h2 align="center">便捷安装</h2>
+
 ### 环境要求
 * Python >= 2.7
 * PaddlePaddle >= 1.7.2
@@ -79,13 +50,14 @@ PadlleRec以预置模型为核心,具备以下特点：
 
 - 安装方法二
 
-  * 安装飞桨  **注：需要用户安装最新版本的飞桨<当前只支持Linux系统>。**
+  源码编译安装
+  1. 安装飞桨  **注：需要用户安装版本 >1.7.2 的飞桨**
 
-    ```bash
+    ```shell
     python -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
     ```
 
-  * 源码安装Fleet-Rec
+  2. 源码安装Fleet-Rec
 
     ```
     git clone https://github.com/PaddlePaddle/PaddleRec/
@@ -93,63 +65,101 @@ PadlleRec以预置模型为核心,具备以下特点：
     python setup.py install
     ```
 
-### 快速开始
-#### ctr-dnn示例使用
-目前框架内置了多个模型，简单的命令即可使用内置模型开始单机训练和本地1*1模拟训练
 
-##### 单机训练
+<h2 align="center">快速启动</h2>
+
+
+目前框架内置了多个模型，简单的命令即可使用内置模型开始单机训练和本地1*1模拟训练，我们以`ctr-dnn`为例介绍PaddleRec的简单使用。
+
+### 一行命令启动训练
+
+<h3 align="center">单机训练</h3>
+
 ```bash
-cd PaddleRec
-
-python -m paddlerec.run \
-       -m paddlerec.models.rank.dnn \
-       -d cpu \
-       -e single 
-
-# 使用GPU资源进行训练
-python -m paddlerec.run \
-       -m paddlerec.models.rank.dnn \
-       -d gpu \
-       -e single
+# 使用CPU进行单机训练
+python -m fleetrec.run -m fleetrec.models.rank.dnn -d cpu -e single 
+
+# 使用GPU进行单机训练
+python -m fleetrec.run -m fleetrec.models.rank.dnn -d gpu -e single
 ```
 
-##### 本地模拟分布式训练
+<h3 align="center">本地模拟分布式训练</h3>
 
 ```bash
-cd PaddleRec
-# 使用CPU资源进行训练
-python -m paddlerec.run \
-       -m paddlerec.models.rank.dnn \
-       -d cpu \
-       -e local_cluster
+# 使用CPU资源进行本地模拟分布式训练
+python -m fleetrec.run -m fleetrec.models.rank.dnn -d cpu -e local_cluster
 ```
 
-##### 集群提交分布式训练<需要用户预先配置好集群环境，本提交命令不包含提交客户端>
+<h3 align="center">集群分布式训练</h3>
 
 ```bash
-cd PaddleRec
-
-python -m paddlerec.run \
-       -m paddlerec.models.rank.dnn \
-       -d cpu \
-       -e cluster
+# 配置好 mpi/k8s/paddlecloud集群环境后
+python -m fleetrec.run -m fleetrec.models.rank.dnn -d cpu -e cluster
 ```
 
-### 常见问题FAQ
+<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>
 
-## 进阶教程
-### 自定义数据集及Reader
-### 模型调参
-### 单机训练
-### 分布式训练
-### 预测部署
+### 新手教程
+* [环境要求](#环境要求)
+* [安装命令](#安装命令)
+* [快速开始](#一行命令启动训练)
+  
+### 进阶教程
+* [自定义数据集及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)
+
+### FAQ
+* [常见问题FAQ](doc/faq.md)
+
+### 设计文档
+* [PaddleRec设计文档](doc/design.md)
 
-# 版本历史
-## 版本更新
-## Benchamrk
 
-# 许可证书
+<h2 align="center">社区</h2>
+
+### 贡献代码
+* [优化PaddleRec框架](doc/contribute.md)
+* [新增模型到PaddleRec](doc/contribute.md)
+
+### 反馈
+如有意见、建议及使用中的BUG，欢迎在`GitHub Issue`提交
+
+### 版本历史
+* [版本更新](#版本更新)
+  
+### 许可证书
 本项目的发布受[Apache 2.0 license](LICENSE)许可认证。
-# 如何贡献代码
-## 优化PaddleRec框架
-## 新增模型到PaddleRec
+  
\ No newline at end of file