add cluster train doc (#139)

* add cluster train doc

* fix

README.md

@@ -134,7 +134,8 @@ python -m paddlerec.run -m paddlerec.models.rank.dnn
 ### Introductory tutorial
 * [Data](doc/slot_reader.md)
 * [Model](doc/model.md)
-* [Train](doc/train.md)
+* [Loacl Train](doc/train.md)
+* [Distributed Train](doc/distributed_train.md)
 * [Predict](doc/predict.md)
 * [Serving](doc/serving.md)
 

README_CN.md

@@ -139,7 +139,8 @@ python -m paddlerec.run -m paddlerec.models.rank.dnn
 ### 入门教程
 * [数据准备](doc/slot_reader.md)
 * [模型调参](doc/model.md)
-* [启动训练](doc/train.md)
+* [启动单机训练](doc/train.md)
+* [启动分布式训练](doc/distributed_train.md)
 * [启动预测](doc/predict.md)
 * [快速部署](doc/serving.md)
 

doc/distributed_train.md

-# PaddleRec 分布式训练
+目录
+=================
 
-## PaddleRec分布式运行
-> 占位
-### 本地模拟分布式
-> 占位
+- [目录](#目录)
+- [基于PaddleCloud的分布式训练启动方法](#基于paddlecloud的分布式训练启动方法)
+  - [使用PaddleRec提交](#使用paddlerec提交)
+    - [第一步：运行环境下安装PaddleCloud的Client](#第一步运行环境下安装paddlecloud的client)
+    - [第二步：更改模型运行`config.yaml`配置](#第二步更改模型运行configyaml配置)
+    - [第三步：增加集群运行`backend.yaml`配置](#第三步增加集群运行backendyaml配置)
+      - [MPI集群的Parameter Server模式配置](#mpi集群的parameter-server模式配置)
+      - [K8S集群的Collective模式配置](#k8s集群的collective模式配置)
+    - [第四步：任务提交](#第四步任务提交)
+  - [使用PaddleCloud Client提交](#使用paddlecloud-client提交)
+    - [第一步：在`before_hook.sh`里手动安装PaddleRec](#第一步在before_hooksh里手动安装paddlerec)
+    - [第二步：在`config.ini`中调整超参](#第二步在configini中调整超参)
+    - [第三步：在`job.sh`中上传文件及修改启动命令](#第三步在jobsh中上传文件及修改启动命令)
+    - [第四步: 提交任务](#第四步-提交任务)
 
-### K8S集群运行分布式
-> 占位
+# 基于PaddleCloud的分布式训练启动方法
+
+> PaddleCloud目前处于百度内部测试推广阶段，将适时推出面向广大用户的公有云版本，欢迎持续关注
+
+## 使用PaddleRec提交
+
+### 第一步：运行环境下安装PaddleCloud的Client
+
+- 环境要求：python > 2.7.5
+- 首先在PaddleCloud平台申请`group`的权限，获得计算资源
+- 然后在[PaddleCloud client使用手册](http://wiki.baidu.com/pages/viewpage.action?pageId=1017488941#1.%20安装PaddleCloud客户端)下载安装`PaddleCloud-Cli`
+- 在PaddleCloud的个人中心获取`AK`及`SK`
+
+
+### 第二步：更改模型运行`config.yaml`配置
+
+分布式运行首先需要更改`config.yaml`，主要调整以下内容：
+
+- workspace: 调整为在节点运行时的工作目录
+- runner_class: 从单机的"train"调整为"cluster_train"
+- fleet_mode: 选则参数服务器模式，抑或GPU Collective模式
+- distribute_strategy: 可选项，选择分布式训练的策略
+
+配置选项具体参数，可以参考[yaml配置说明](./yaml.md)
+
+以Rank/dnn模型为例
+
+单机训练配置：
+
+```yaml
+# workspace
+workspace: "paddlerec.models.rank.dnn"
+
+mode: [single_cpu_train]
+# config of each runner.
+# runner is a kind of paddle training class, which wraps the train/infer process.
+runner:
+- name: single_cpu_train
+  class: train
+  # num of epochs
+  epochs: 4
+  # device to run training or infer
+  device: cpu
+  save_checkpoint_interval: 2 # save model interval of epochs
+  save_checkpoint_path: "increment_dnn" # save checkpoint path
+  init_model_path: "" # load model path
+  print_interval: 10
+  phases: [phase1]
+```
+
+分布式的训练配置可以改为：
+```yaml
+# workspace
+# 改变一：代码上传至节点后，与运行shell同在一个默认目录下
+workspace: "./" 
+
+mode: [ps_cluster]
+# config of each runner.
+# runner is a kind of paddle training class, which wraps the train/infer process.
+runner:
+- name: ps_cluster
+  # 改变二：调整runner的class
+  class: cluster_train
+  # num of epochs
+  epochs: 4
+  # device to run training or infer
+  device: cpu
+  # 改变三 & 四： 指定fleet_mode 与 distribute_strategy
+  fleet_mode: ps
+  distribute_strategy: async
+  save_checkpoint_interval: 2 # save model interval of epochs
+  save_checkpoint_path: "increment_dnn" # save checkpoint path
+  init_model_path: "" # load model path
+  print_interval: 10
+  phases: [phase1]
+```
+
+除此之外，还需关注数据及模型加载的路径，一般而言：
+- PaddleCloud MPI集群下，训练数据会下载到节点运行目录的`./train_data/`，测试数据位于`./test_data/`，其他数据及文件可以通过上传到hdfs配置的`thirdparty`后，自动下载到节点运行目录的`./thirdparty/`文件夹下。
+- PaddleCloud K8S集群下，hdfs的指定目录会挂载到节点工作目录的`./afs/`
+
+### 第三步：增加集群运行`backend.yaml`配置
+
+分布式训练除了模型的部分调整外，更重要的是加入集群的配置选项，我们通过另一个yaml文件来指定分布式的运行配置，将分布式配置与模型超参解耦。
+
+下面给出一个完整的`backend.yaml`示例：
+
+```yaml
+backend: "PaddleCloud"
+cluster_type: mpi # k8s 可选
+
+config:
+  # 填写任务运行的paddle官方版本号 >= 1.7.2， 默认1.7.2
+  paddle_version: "1.7.2" 
+
+  # hdfs/afs的配置信息填写
+  fs_name: "afs://xxx.com"
+  fs_ugi: "usr,pwd"
+
+  # 填任务输出目录的远程地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  output_path: "" 
+  
+  # for mpi
+  # 填远程数据及地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  train_data_path: ""
+  test_data_path: "" 
+  thirdparty_path: "" 
+  
+  # for k8s
+  # 填远程挂载地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  afs_remote_mount_point: "" 
+
+  # paddle参数服务器分布式底层超参，无特殊需求不理不改
+  communicator:
+    FLAGS_communicator_is_sgd_optimizer: 0
+    FLAGS_communicator_send_queue_size: 5
+    FLAGS_communicator_thread_pool_size: 32
+    FLAGS_communicator_max_merge_var_num: 5
+    FLAGS_communicator_max_send_grad_num_before_recv: 5
+    FLAGS_communicator_fake_rpc: 0
+    FLAGS_rpc_retry_times: 3
+  
+submit:
+  # PaddleCloud 个人信息 AK 及 SK
+  ak: ""
+  sk: ""
+  
+  # 任务运行优先级，默认high
+  priority: "high"
+  
+  # 任务名称
+  job_name: "PaddleRec_CTR"
+
+  # 训练资源所在组
+  group: ""
+
+  # 节点上的任务启动命令
+  start_cmd: "python -m paddlerec.run -m ./config.yaml"
+  
+  # 本地需要上传到节点工作目录的文件
+  files: ./*.py ./*.yaml
+
+  # for mpi ps-cpu
+  # mpi 参数服务器模式下，任务的节点数
+  nodes: 2
+  
+  # for k8s gpu        
+  # k8s gpu 模式下，训练节点数，及每个节点上的GPU卡数
+  k8s_trainers: 2
+  k8s_gpu_card: 1
+  
+```
+
+更多backend.yaml配置选项信息，可以查看[yaml配置说明](./yaml.md)
+
+除此之外，我们还需要关注上传到工作目录的文件(`files选项`)的路径问题，在示例中是`./*.py`，说明我们执行任务提交时，与这些py文件在同一目录。若不在同一目录，则需要适当调整files路径，或改为这些文件的绝对路径。
+
+不建议利用`files`上传数据文件，可以通过指定`train_data_path`自动下载，或指定`afs_remote_mount_point`挂载实现数据到节点的转移。
+
+#### MPI集群的Parameter Server模式配置
+
+下面是一个利用PaddleCloud提交MPI参数服务器模式任务的`backend.yaml`示例
+
+```yaml
+backend: "PaddleCloud"
+cluster_type: mpi # k8s 可选
+
+config:
+  # 填写任务运行的paddle官方版本号 >= 1.7.2， 默认1.7.2
+  paddle_version: "1.7.2" 
+
+  # hdfs/afs的配置信息填写
+  fs_name: "afs://xxx.com"
+  fs_ugi: "usr,pwd"
+
+  # 填任务输出目录的远程地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  output_path: "" 
+  
+  # for mpi
+  # 填远程数据及地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  train_data_path: ""
+  test_data_path: "" 
+  thirdparty_path: "" 
+
+submit:
+  # PaddleCloud 个人信息 AK 及 SK
+  ak: ""
+  sk: ""
+  
+  # 任务运行优先级，默认high
+  priority: "high"
+  
+  # 任务名称
+  job_name: "PaddleRec_CTR"
+
+  # 训练资源所在组
+  group: ""
+
+  # 节点上的任务启动命令
+  start_cmd: "python -m paddlerec.run -m ./config.yaml"
+  
+  # 本地需要上传到节点工作目录的文件
+  files: ./*.py ./*.yaml
+
+  # for mpi ps-cpu
+  # mpi 参数服务器模式下，任务的节点数
+  nodes: 2
+```
+
+#### K8S集群的Collective模式配置
+
+下面是一个利用PaddleCloud提交K8S集群进行GPU训练的`backend.yaml`示例
+
+```yaml
+backend: "PaddleCloud"
+cluster_type: mpi # k8s 可选
+
+config:
+  # 填写任务运行的paddle官方版本号 >= 1.7.2， 默认1.7.2
+  paddle_version: "1.7.2" 
+
+  # hdfs/afs的配置信息填写
+  fs_name: "afs://xxx.com"
+  fs_ugi: "usr,pwd"
+
+  # 填任务输出目录的远程地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  output_path: "" 
+  
+  # for k8s
+  # 填远程挂载地址，如afs:/user/your/path/ 则此处填 /user/your/path
+  afs_remote_mount_point: "" 
+  
+submit:
+  # PaddleCloud 个人信息 AK 及 SK
+  ak: ""
+  sk: ""
+  
+  # 任务运行优先级，默认high
+  priority: "high"
+  
+  # 任务名称
+  job_name: "PaddleRec_CTR"
+
+  # 训练资源所在组
+  group: ""
+
+  # 节点上的任务启动命令
+  start_cmd: "python -m paddlerec.run -m ./config.yaml"
+  
+  # 本地需要上传到节点工作目录的文件
+  files: ./*.py ./*.yaml
+  
+  # for k8s gpu        
+  # k8s gpu 模式下，训练节点数，及每个节点上的GPU卡数
+  k8s_trainers: 2
+  k8s_gpu_card: 1
+```
+
+### 第四步：任务提交
+
+当我们准备好`config.yaml`与`backend.yaml`，便可以进行一键任务提交，命令为：
+
+```shell
+python -m paddlerec.run -m config.yaml -b backend.yaml
+```
+
+执行过程中会进行配置的若干check，并给出错误提示。键入提交命令后，会有以下提交信息打印在屏幕上：
+
+```shell
+The task submission folder is generated at /home/PaddleRec/models/rank/dnn/PaddleRec_CTR_202007091308
+before_submit
+gen gpu before_hook.sh
+gen k8s_config.ini
+gen k8s_job.sh
+gen end_hook.sh
+Start checking your job configuration, please be patient.
+Congratulations! Job configuration check passed!
+Congratulations! The new job is ready for training.
+{
+    "groupName": "xxxxxxx",
+    "jobId": "job-xxxxxx",
+    "userId": "x-x-x-x-x"
+}
+end submit
+```
+
+则代表任务已顺利提交PaddleCloud，恭喜。
+
+同时，我们还可以进入`/home/PaddleRec/models/rank/dnn/PaddleRec_CTR_202007091308`这个目录检查我们的提交环境，该目录下有以下文件：
+
+```shell
+.
+├── backend.yaml         # 用户定义的分布式配置backend.yaml
+├── config.yaml          # 用户定义的模型执行config.yaml
+├── before_hook.sh       # PaddleRec生成的训练前执行的脚本
+├── config.ini           # PaddleRec生成的PaddleCloud环境配置
+├── end_hook.sh          # PaddleRec生成的训练后执行的脚本
+├── job.sh               # PaddleRec生成的PaddleCloud任务提交脚本
+└── model.py             # CTR模型的组网.py文件
+```
+
+该目录下的文件会被打平上传到节点的工作目录，用户可以复查PaddleRec生成的配置文件是否符合预期，如不符合预期，既可以调整backend.yaml，亦可以直接修改生成的文件，并执行：
+
+```shell
+sh job.sh
+```
+再次提交任务。
+
+
+## 使用PaddleCloud Client提交
+
+假如你已经很熟悉PaddleCloud的使用，并且之前是用PaddleCloud-Client提交过任务，熟悉`before_hook.sh`、`config.ini`、`job.sh`，希望通过之前的方式提交PaddleCloud任务，PaddleRec也支持。
+
+
+我们可以不添加`backend.yaml`，直接用PaddleCloud-Client的提交要求提交任务，除了为分布式训练[修改config.yaml](#第二步更改模型运行configyaml配置)以外，有以下几个额外的步骤：
+
+### 第一步：在`before_hook.sh`里手动安装PaddleRec
+
+```shell
+# before_hook.sh
+echo "Run before_hook.sh ..."
+
+wget https://paddlerec.bj.bcebos.com/whl/PaddleRec.tar.gz
+
+tar -xf PaddleRec.tar.gz
+
+cd PaddleRec
+
+python setup.py install
+
+echo "End before_hook.sh ..."
+```
+
+### 第二步：在`config.ini`中调整超参
+
+```shell
+# config.ini
+# 设置PADDLE_PADDLEREC_ROLE环境变量为WORKER
+# 告诉PaddleRec当前运行环境在节点中，无需执行提交流程，直接执行分布式训练
+PADDLE_PADDLEREC_ROLE=WORKER
+```
+
+### 第三步：在`job.sh`中上传文件及修改启动命令
+
+我们需要在`job.sh`中上传运行PaddleRec所需的必要文件，如运行该模型的`model.py`、`config.yaml`以及`reader.py`等，PaddleRec的框架代码无需上传，已在before_hook中安装。
+
+同时还需调整启动命令(start_cmd)，调整为
+```shell
+python -m paddlerec.run -m config.yaml
+```
+
+### 第四步: 提交任务
+
+直接运行:
+
+```shell
+sh job.sh
+```
+
+复用之前的提交脚本执行任务的提交。