README.md 7.6 KB
Newer Older
T
tangwei 已提交
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 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
<p align="center">
<img align="center" src="doc/imgs/logo.png">
<p>

<p align="center">
    <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>


<h2 align="center">什么是PaddleRec</h2>

<p align="center">
<img align="center" src="doc/imgs/structure.png">
<p>

- 源于飞桨生态的搜索推荐模型**一站式开箱即用工具** 
- 适合初学者,开发者,研究者从调研,训练到预测部署的全流程解决方案
- 包含语义理解、召回、粗排、精排、多任务学习、融合等多个任务的推荐搜索算法库
- 配置**yaml**自定义选项,即可快速上手使用单机训练、大规模分布式训练、离线预测、在线部署


<h2 align="center">PadlleRec概览</h2>

<p align="center">
<img align="center" src="doc/imgs/overview.png">
<p>


<h2 align="center">推荐系统-流程概览</h2>

<p align="center">
<img align="center" src="doc/imgs/rec-overview.png">
<p>

<h2 align="center">便捷安装</h2>

### 环境要求
* Python 2.7/ 3.5 / 3.6 / 3.7
* PaddlePaddle  >= 1.7.2
* 操作系统: Windows/Mac/Linux
C
chengmo 已提交
45

C
fix  
chengmo 已提交
46
  > Windows下目前仅提供单机训练,建议使用Linux
T
tangwei 已提交
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
  
### 安装命令

- 安装方法一<PIP源直接安装>
  ```bash
  python -m pip install paddle-rec
  ```

- 安装方法二

  源码编译安装
  1. 安装飞桨  **注:需要用户安装版本 >1.7.2 的飞桨**

    ```shell
    python -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
    ```

  2. 源码安装PaddleRec

    ```
    git clone https://github.com/PaddlePaddle/PaddleRec/
    cd PaddleRec
    python setup.py install
    ```


<h2 align="center">快速启动</h2>

### 启动内置模型的默认配置

C
fix  
chengmo 已提交
77 78
目前框架内置了多个模型,一行命令即可使用内置模型开始单机训练和本地模拟分布式训练。
  > 本地模拟分布式(`local_cluster`)为`1个server + 1个trainer`的参数服务器模式
C
chengmo 已提交
79

T
tangwei 已提交
80

C
fix  
chengmo 已提交
81
我们以排序模型中的`dnn`模型为例介绍PaddleRec的简单使用。训练数据来源为[Criteo数据集](https://www.kaggle.com/c/criteo-display-ad-challenge/),我们从中截取了100条方便您快速上手体验完整的PaddleRec流程。
T
tangwei 已提交
82 83 84

```bash
# 使用CPU进行单机训练
C
chengmo 已提交
85
python -m paddlerec.run -m paddlerec.models.rank.dnn  
T
tangwei 已提交
86 87
```

C
chengmo 已提交
88
### 启动内置模型的自定配置
T
tangwei 已提交
89

C
chengmo 已提交
90 91
若您复用内置模型,对**yaml**配置文件进行了修改,如更改超参,重新配置数据后,可以直接使用paddlerec运行该yaml文件。

C
chengmo 已提交
92
我们以dnn模型为例,在paddlerec代码目录下:
T
tangwei 已提交
93
```bash
C
chengmo 已提交
94
cd paddlerec
T
tangwei 已提交
95 96
```

C
fix  
chengmo 已提交
97
修改dnn模型的[超参配置](./models/rank/dnn/config.yaml),例如将迭代训练轮数从10轮修改为5轮:
C
chengmo 已提交
98 99 100 101 102 103
```yaml
train:
  # epochs: 10
  epochs: 5
```

C
fix  
chengmo 已提交
104
在Linux环境下,可以使用`vim`等文本编辑工具修改yaml文件:
C
chengmo 已提交
105 106 107 108 109 110 111 112 113 114

```bash
vim ./models/rank/dnn/config.yaml
# 键入 i, 进入编辑模式
# 修改yaml文件配置
# 完成修改后,点击esc,退出编辑模式
# 键入 :wq 保存文件并退出 
```

完成dnn模型`models/rank/dnn/config.yaml`的配置修改后,运行`dnn`模型:
C
chengmo 已提交
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
```bash
# 使用自定配置进行训练
python -m paddlerec.run -m ./models/rank/dnn/config.yaml 
```

### 分布式训练

分布式训练需要配置`config.yaml`,加入或修改`engine`选项为`cluster``local_cluster`,以进行分布式训练,或本地模拟分布式训练。

#### 本地模拟分布式训练

我们以dnn模型为例,在paddlerec代码目录下,修改dnn模型的`config.yaml`文件:

```yaml
train:
  #engine: single
  engine: local_cluster
```
然后启动paddlerec训练:
T
tangwei 已提交
134 135

```bash
C
chengmo 已提交
136 137
# 进行本地模拟分布式训练
python -m paddlerec.run -m ./models/rank/dnn/config.yaml  
T
tangwei 已提交
138 139
```

C
chengmo 已提交
140
#### 集群分布式训练
T
tangwei 已提交
141

C
chengmo 已提交
142 143 144 145 146 147 148 149
我们以dnn模型为例,在paddlerec代码目录下,首先修改dnn模型`config.yaml`文件:

```yaml
train:
  #engine: single
  engine: cluster
```
再添加分布式启动配置文件`backend.yaml`,具体配置规则在[分布式训练](doc/distributed_train.md)教程中介绍。最后启动paddlerec训练:
T
tangwei 已提交
150 151

```bash
C
chengmo 已提交
152 153
# 配置好 mpi/k8s/paddlecloud集群环境后
python -m paddlerec.run -m ./models/rank/dnn/config.yaml -b backend.yaml
T
tangwei 已提交
154 155 156 157 158 159
```


<h2 align="center">支持模型列表</h2>


C
chengmo 已提交
160 161
|   方向   |                                   模型                                    | 单机CPU训练 | 单机GPU训练 | 分布式CPU训练 |
| :------: | :-----------------------------------------------------------------------: | :---------: | :---------: | :-----------: |
T
tangwei 已提交
162
| 内容理解 | [Text-Classifcation](models/contentunderstanding/classification/model.py) |      ✓      |      x      |       ✓       |
C
chengmo 已提交
163
| 内容理解 |         [TagSpace](models/contentunderstanding/tagspace/model.py)         |      ✓      |      x      |       ✓       |
C
chengmo 已提交
164 165
|   召回   |                    [DSSM](models/match/dssm/model.py)                     |      ✓      |      x      |       ✓       |
|   召回   |        [MultiView-Simnet](models/match/multiview-simnet/model.py)         |      ✓      |      x      |       ✓       |
C
chengmo 已提交
166 167 168 169 170 171 172 173 174 175 176 177
|   召回   |                   [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)                 |      ✓      |      ✓      |       ✓       |
|   排序   |                      [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)           |      ✓      |      ✓      |       ✓       |
C
chengmo 已提交
178

T
tangwei 已提交
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217



<h2 align="center">文档</h2>

### 背景介绍
* [推荐系统介绍](doc/rec_background.md)
* [分布式深度学习介绍](doc/ps_background.md)

### 新手教程
* [环境要求](#环境要求)
* [安装命令](#安装命令)
* [快速开始](#启动内置模型的默认配置)

### 进阶教程
* [自定义数据集及Reader](doc/custom_dataset_reader.md)
* [分布式训练](doc/distributed_train.md)

### 开发者教程
* [PaddleRec设计文档](doc/design.md)

### 关于PaddleRec性能
* [Benchmark](doc/benchmark.md)

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


<h2 align="center">社区</h2>

### 反馈
如有意见、建议及使用中的BUG,欢迎在`GitHub Issue`提交

### 版本历史
- 2020.5.14 - PaddleRec v0.1
  
### 许可证书
本项目的发布受[Apache 2.0 license](LICENSE)许可认证。