From 736bb7ce0ee3e77e2a32bd11f0cb4f44dce1b016 Mon Sep 17 00:00:00 2001
From: Qiao Longfei <qiaolongfei@baidu.com>
Date: Tue, 4 Dec 2018 00:17:46 +0800
Subject: [PATCH] Add async train doc (#400)

* add async_training.rst

* add cpu_train_best_practice.rst

* clean code

* add doc for large_scale_sparse_feature_training

* add index for distribute train api guide

* follow_comments

* fix_link_format

* fix_link_format

* follow_comments_large_scale

* follow_comments

fix https://github.com/PaddlePaddle/FluidDoc/pull/400#discussion_r237335307
---
 doc/fluid/api/api_guides/index.rst            |  1 +
 .../low_level/distributed/async_training.rst  | 33 +++++++++++
 .../distributed/cpu_train_best_practice.rst   | 58 +++++++++++++++++++
 .../low_level/distributed/index.rst           | 11 ++++
 .../large_scale_sparse_feature_training.rst   | 42 ++++++++++++++
 5 files changed, 145 insertions(+)
 create mode 100644 doc/fluid/api/api_guides/low_level/distributed/async_training.rst
 create mode 100644 doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst
 create mode 100644 doc/fluid/api/api_guides/low_level/distributed/index.rst
 create mode 100644 doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst

diff --git a/doc/fluid/api/api_guides/index.rst b/doc/fluid/api/api_guides/index.rst
index acf79f8b2..fe96d6e91 100755
--- a/doc/fluid/api/api_guides/index.rst
+++ b/doc/fluid/api/api_guides/index.rst
@@ -12,3 +12,4 @@ API使用指南
     low_level/metrics.rst
     low_level/model_save_reader.rst
     low_level/inference.rst
+    low_level/distributed/index.rst
diff --git a/doc/fluid/api/api_guides/low_level/distributed/async_training.rst b/doc/fluid/api/api_guides/low_level/distributed/async_training.rst
new file mode 100644
index 000000000..a36fd2cd1
--- /dev/null
+++ b/doc/fluid/api/api_guides/low_level/distributed/async_training.rst
@@ -0,0 +1,33 @@
+.. _api_guide_async_training:
+
+############
+分布式异步训练
+############
+
+Fluid支持数据并行的分布式异步训练，API使用 :code:`DistributedTranspiler` 将单机网络配置转换成可以多机执行的
+:code:`pserver` 端程序和 :code:`trainer` 端程序。用户在不同的节点执行相同的一段代码，根据环境变量或启动参数，
+可以执行对应的 :code:`pserver` 或 :code:`trainer` 角色。Fluid异步训练只支持pserver模式，异步训练和 `同步训练 <../distributed/sync_training.html>`_ 的主要差异在于：异步训练每个trainer的梯度是单独更新到参数上的，
+而同步训练是所有trainer的梯度合并之后统一更新到参数上，因此，同步训练和异步训练的超参数需要分别调节。
+
+pserver模式分布式异步训练
+======================
+
+API详细使用方法参考 :ref: `api_fluid_DistributeTranspiler` ，简单示例用法：
+
+.. code-block:: python
+
+    config = fluid.DistributedTranspilerConfig()
+    # 配置策略config
+    config.slice_var_up = False
+    t = fluid.DistributedTranspiler(config=config)
+    t.transpile(trainer_id, 
+                program=main_program,
+                pservers="192.168.0.1:6174,192.168.0.2:6174",
+                trainers=1,
+                sync_mode=False)
+
+以上参数说明请参考`同步训练 <../distributed/sync_training.html>`_ 
+
+需要注意的是：进行异步训练时，请修改 :code:`sync_mode` 的值
+
+- :code:`sync_mode` ： 是否是同步训练模式，默认为True，不传此参数也默认是同步训练模式，设置为False则为异步训练
diff --git a/doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst b/doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst
new file mode 100644
index 000000000..b6b510263
--- /dev/null
+++ b/doc/fluid/api/api_guides/low_level/distributed/cpu_train_best_practice.rst
@@ -0,0 +1,58 @@
+.. _api_guide_cpu_training_best_practice:
+
+##################
+分布式CPU训练最佳实践
+##################
+
+提高CPU分布式训练的训练速度，主要要从两个方面来考虑：
+1）提高训练速度，主要是提高CPU的使用率；2）提高通信速度，主要是减少通信传输的数据量。
+
+提高CPU的使用率
+=============
+
+提高CPU使用率主要依赖 :code:`ParallelExecutor`，可以充分利用多个CPU的计算能力来加速计算。
+
+API详细使用方法参考 :ref:`api_fluid_ParallelExecutor` ，简单实例用法：
+
+.. code-block:: python
+
+    # 配置执行策略，主要是设置线程数
+    exec_strategy = fluid.ExecutionStrategy()
+    exec_strategy.num_threads = 8
+
+    # 配置构图策略，对于CPU训练而言，应该使用Reduce模式进行训练
+    build_strategy = fluid.BuildStrategy()
+    if int(os.getenv("CPU_NUM")) > 1:
+        build_strategy.reduce_strategy = fluid.BuildStrategy.ReduceStrategy.Reduce
+
+    pe = fluid.ParallelExecutor(
+        use_cuda=False,
+        loss_name=avg_cost.name,
+        main_program=main_program,
+        build_strategy=build_strategy,
+        exec_strategy=exec_strategy)
+
+以上参数中：
+
+- :code:`num_threads` ： 模型训练使用的线程数，最好和训练所在机器的物理CPU核数接近
+- :code:`reduce_strategy` ： 对于CPU训练而言，应该选择 fluid.BuildStrategy.ReduceStrategy.Reduce
+
+
+通用环境变量配置：
+
+- :code:`CPU_NUM` ：模型副本replica的个数，最好和num_threads一致
+
+
+提高通信速度
+==========
+
+要减少通信数据量，提高通信速度，主要是使用稀疏更新 ，目前支持 `稀疏更新 <../distributed/sparse_update.html>`_  的主要是  :ref:`api_fluid_layers_embedding` 。
+
+.. code-block:: python
+
+    data = fluid.layers.data(name='ids', shape=[1], dtype='int64')
+    fc = fluid.layers.embedding(input=data, size=[dict_size, 16], is_sparse=True)
+
+以上参数中：
+
+- :code:`is_sparse` ： 配置embedding使用稀疏更新，如果embedding的dict_size很大，而每次数据data很少，建议使用sparse更新方式。
diff --git a/doc/fluid/api/api_guides/low_level/distributed/index.rst b/doc/fluid/api/api_guides/low_level/distributed/index.rst
new file mode 100644
index 000000000..5a570461e
--- /dev/null
+++ b/doc/fluid/api/api_guides/low_level/distributed/index.rst
@@ -0,0 +1,11 @@
+=============
+分布式训练
+=============
+
+..  toctree::
+    :maxdepth: 1
+
+    async_training.rst
+    cpu_train_best_practice.rst
+    large_scale_sparse_feature_training.rst
+
diff --git a/doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst b/doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst
new file mode 100644
index 000000000..7b2994f15
--- /dev/null
+++ b/doc/fluid/api/api_guides/low_level/distributed/large_scale_sparse_feature_training.rst
@@ -0,0 +1,42 @@
+.. _api_guide_large_scale_sparse_feature_training:
+
+###################
+大规模稀疏特征模型训练
+###################
+
+
+模型配置和训练
+=============
+
+embedding被广泛应用在各种网络结构中，尤其是文本处理相关的模型。在某些场景，例如推荐系统或者搜索引擎中，
+embedding的feature id可能会非常多，当feature id达到一定数量时，embedding参数会变得很大，
+会带来两个问题：
+1）单机内存由于无法存放如此巨大的embedding参数，导致无法训练；
+2）普通的训练模式每一轮迭代都需要同步完整的参数，参数太大会让通信变得非常慢，进而影响训练速度。
+
+Fluid支持千亿量级超大规模稀疏特征embedding的训练，embedding参数只会保存在parameter server上，通过
+参数prefetch和梯度稀疏更新的方法，大大减少通信量，提高通信速度。
+
+该功能只对分布式训练有效，单机无法使用。
+需要配合 `稀疏更新 <../distributed/sparse_update.html>`_ 一起使用。
+
+使用方法：在配置embedding的时候，加上参数 :code:`is_distributed=True` 以及 :code:`is_sparse=True` 即可。
+参数 :code:`dict_size` 定义数据中总的id的数量，id可以是int64范围内的任意值，只要总id个数小于等于dict_size就可以支持。
+所以配置之前需要预估一下数据中总的feature id的数量。
+
+.. code-block:: python
+
+  emb = fluid.layers.embedding(
+      is_distributed=True,
+      input=input,
+      size=[dict_size, embedding_width],
+      is_sparse=True,
+      is_distributed=True)
+
+
+模型存储和预测
+=============
+
+当特征数量达到千亿的时候，参数量很大，单机已经无法存下，所以模型的存储和加载都和普通模式不同：
+1）普通模式下，参数是在trainer端保存和加载的；
+2）分布式模式下，参数的保存和加载，都是在pserver端进行，每个pserver只保存和加载该pserver自身对应部分的参数
-- 
GitLab