Merge branch 'develop' of https://github.com/PaddlePaddle/FluidDoc into update-faq

doc/paddle/api/paddle/distributed/fleet/DistributedStrategy_cn.rst

+.. _cn_api_distributed_fleet_DistributedStrategy:
+
+DistributedStrategy
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.DistributedStrategy
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/Fleet_cn.rst

+.. _cn_api_distributed_fleet_Fleet:
+
+Fleet
+-------------------------------
+
+
+.. py:class:: paddle.distributed.fleet.Fleet
+
+
+
+
+.. py:method:: init(role_maker=None, is_collective=False)
+
+
+.. py:method:: is_first_worker()
+
+
+.. py:method:: worker_index()
+
+
+.. py:method:: worker_num()
+
+
+.. py:method:: is_worker()
+
+
+.. py:method:: worker_endpoints(to_string=False)
+
+
+.. py:method:: server_num()
+
+
+.. py:method:: server_index()
+
+
+.. py:method:: server_endpoints(to_string=False)
+
+
+.. py:method:: is_server()
+
+
+.. py:method:: barrier_worker()
+
+
+.. py:method:: init_worker()
+
+
+.. py:method:: init_server(*args, **kwargs)
+
+
+.. py:method:: run_server()
+
+
+.. py:method:: stop_worker()
+
+
+.. py:method:: save_inference_model(executor, dirname, feeded_var_names, target_vars, main_program=None, export_for_deployment=True)
+
+
+.. py:method:: save_persistables(executor, dirname, main_program=None)
+
+
+.. py:method:: distributed_optimizer(optimizer, strategy=None)
+
+
+.. py:method:: distributed_model(model)
+
+
+.. py:method:: state_dict()
+
+
+.. py:method:: set_lr(value)
+
+
+.. py:method:: get_lr()
+
+
+.. py:method:: step()
+
+
+.. py:method:: clear_grad()
+
+
+.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None)
+
+
+.. py:attribute:: util
+
+

doc/paddle/api/paddle/distributed/fleet/PaddleCloudRoleMaker_cn.rst

+.. _cn_api_distributed_fleet_PaddleCloudRoleMaker:
+
+PaddleCloudRoleMaker
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.PaddleCloudRoleMaker
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/UserDefinedRoleMaker_cn.rst

+.. _cn_api_distributed_fleet_UserDefinedRoleMaker:
+
+UserDefinedRoleMaker
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.UserDefinedRoleMaker
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/UtilBase_cn.rst

+.. _cn_api_distributed_fleet_UtilBase:
+
+UtilBase
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.UtilBase
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/ExecuteError_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_ExecuteError:
+
+ExecuteError
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.ExecuteError
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/FSFileExistsError_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_FSFileExistsError:
+
+FSFileExistsError
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.FSFileExistsError
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/FSFileNotExistsError_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_FSFileNotExistsError:
+
+FSFileNotExistsError
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.FSFileNotExistsError
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/FSShellCmdAborted_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_FSShellCmdAborted:
+
+FSShellCmdAborted
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.FSShellCmdAborted
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/FSTimeOut_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_FSTimeOut:
+
+FSTimeOut
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.FSTimeOut
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/FS_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_FS:
+
+FS
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.FS
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/HDFSClient_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_HDFSClient:
+
+HDFSClient
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.HDFSClient
+
+
+
+

doc/paddle/api/paddle/distributed/fleet/utils/fs/LocalFS_cn.rst

+.. _cn_api_distributed_fleet_utils_fs_LocalFS:
+
+LocalFS
+-------------------------------
+
+.. py:class:: paddle.distributed.fleet.utils.fs.LocalFS
+
+
+
+

doc/paddle/api/paddle/fluid/dygraph/jit/set_code_level_cn.rst

@@ -3,7 +3,7 @@
 set_code_level
 -----------------
 
-.. py:function:: paddle.jit.set_code_level(level=100)
+.. py:function:: paddle.jit.set_code_level(level=100, also_to_stdout=False)
 设置代码级别，打印该级别 AST Transformer 转化后的代码。
 
 有两种方法设置代码级别：
@@ -17,6 +17,8 @@ set_code_level
 
 参数：
   - **level** (int) - 打印的代码级别。默认值为100，这意味着打印的是所有 AST Transformer 转化后的代码。
+  - **also_to_stdout** (bool) - 表示是否也将代码输出到 ``sys.stdout``。默认值 False，表示仅输出到 ``sys.stderr``。
+
 
 **示例代码**
 

doc/paddle/api/paddle/fluid/dygraph/jit/set_verbosity_cn.rst

@@ -3,7 +3,7 @@
 set_verbosity
 -----------------
 
-.. py:function:: paddle.jit.set_verbosity(level=0)
+.. py:function:: paddle.jit.set_verbosity(level=0, also_to_stdout=False)
 设置动态图转静态图的日志详细级别。
 
 有两种方法设置日志详细级别：
@@ -17,6 +17,7 @@ set_verbosity
 
 参数：
     - **level** (int) - 日志详细级别。值越大，表示越详细。默认值为0，表示不显示日志。
+    - **also_to_stdout** (bool) - 表示是否也将日志信息输出到 ``sys.stdout``。默认值 False，表示仅输出到 ``sys.stderr``。
 
 **示例代码**
 

doc/paddle/faq/train_cn.md

@@ -3,74 +3,73 @@
 
 ## 数据处理
 
-##### 问题：如何处理图片小但数量很大的数据集？
+##### 问题：如何在训练过程中高效读取数量很大的数据集？
 
-+ 答复：`multiprocess_reader`可以解决该问题，具体可参考[Github示例](https://github.com/PaddlePaddle/Paddle/issues/16592)。
++ 答复：当训练时使用的数据集数据量较大或者预处理逻辑复杂时，如果串行地进行数据读取，数据读取往往会成为训练效率的瓶颈。这种情况下通常需要利用多线程或者多进程的方法异步地进行数据载入，从而提高数据读取和整体训练效率。
 
-----------
+paddle1.8中推荐使用两个异步数据加载的API：
 
-##### 问题：使用`py_reader`读取数据时，如何给变量命名？
+1. DataLoader.from_generator，有限的异步加载
 
-+ 答复：可以通过设置里面的name变量。具体方法请参考飞桨[create_py_reader_by_data](https://www.paddlepaddle.org.cn/documentation/docs/zh/1.3/api_cn/layers_cn.html#create-py-reader-by-data) API。
+该API提供了单线程和单进程的异步加载支持。但由于线程和进程数目不可配置，所以异步加速能力是有限的，适用于数据读取负载适中的场景。
 
-----------
+具体使用方法及示例请参考API文档：[fluid.io.DataLoader.from_generator](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/io_cn/DataLoader_cn.html#id1)。
+
+2. DataLoader，灵活的异步加载
 
-##### 问题：使用多卡或多GPU进行数据并行时，如何设置异步数据读取？
+该API提供了多进程的异步加载支持，也是paddle后续主推的数据读取方式。用户可通过配置num_workers指定异步加载数据的进程数目从而满足不同规模数据集的读取需求。
 
-+ 答复：使用多卡或多GPU进行数据并行时，需要设置：`places = fluid.cuda_places() if USE_CUDA else fluid.cpu_places(CPU_NUM)`，具体内容可以参考文档：[异步数据读取](https://www.paddlepaddle.org.cn/documentation/docs/zh/1.5/user_guides/howto/prepare_data/use_py_reader.html) 。
+具体使用方法及示例请参考API文档：[fluid.io.DataLLoader](https://www.paddlepaddle.org.cn/documentation/docs/en/api/io/DataLoader.html#dataloader)
 
 ----------
 
-##### 问题：使用`paddle.dataset.mnist.train()`获得数据后，如何转换为可操作的Tensor？
+##### 问题：使用多卡进行并行训练时，如何配置DataLoader进行异步数据读取？
 
-+ 答复：执行`fluid.dygraph.to_varibale()`，将data数据转化为可以操作的动态图Tensor。
++ 答复：paddle1.8中多卡训练时设置异步读取和单卡场景并无太大差别，动态图模式下，由于目前仅支持多进程多卡，每个进程将仅使用一个设备，比如一张GPU卡，这种情况下，与单卡训练无异，只需要确保每个进程使用的是正确的卡即可。
+
+具体示例请参考飞桨API [fluid.io.DataLoader.from_generator](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/io_cn/DataLoader_cn.html#id1) 和 [fluid.io.DataLLoader](https://www.paddlepaddle.org.cn/documentation/docs/en/api/io/DataLoader.html#dataloader) 中的示例。
 
 ----------
 
-##### 问题：如何给图片添加一个通道数，并进行训练？
+##### 问题：在动态图使用`paddle.dataset.mnist.train()`获得数据后，如何转换为可操作的Tensor？
 
-+ 答复：执行`np.expand_dims`增加维度后再reshape。如果需要通道合并，可以执行`fluid.layers.concat()`。
++ 答复：调用`fluid.dygraph.to_varibale(data)`，即可将data数据转化为可以操作的动态图Tensor。
 
 ----------
 
-##### 问题：`paddle.fluid.layers.py_reader`和`fluid.io.PyReader`有什么区别？
+##### 问题：如何给图片添加一个通道数，并进行训练？
+
++ 答复：如果是在进入paddle计算流程之前，数据仍然是numpy.array的形式，使用numpy接口`numpy.expand_dims`为图片数据增加维度后，再通过`numpy.reshape`进行操作即可，具体使用方法可查阅numpy的官方文档。
 
-+ 答复：两个都是异步的。推荐使用`fluid.io.PyReader`。
+如果是希望在模型训练或预测流程中完成通道的操作，可以使用paddle对应的API [paddle.fluid.layers.unsqueeze](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/layers_cn/unsqueeze_cn.html#unsqueeze) 和 [paddle.fluid.layers.reshape](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/layers_cn/reshape_cn.html#reshape)。
 
 ----------
 
 ##### 问题：有拓展Tensor维度的Op吗？
 
-+ 答复：有的，操作方法请参考[unsqueeze op](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/layers_cn/unsqueeze_cn.html) 。
++ 答复：有，请参考API [paddle.fluid.layers.unsqueeze](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/layers_cn/unsqueeze_cn.html)。
 
 ----------
 
-##### 问题：是否支持两维以上的变长tensor，如：shape[-1, -1, 128]？
+##### 问题：如何从numpy.array生成一个具有shape和dtype的Tensor?
 
-+ 答复：配置网络时`shape`可以设置为：[-1，*任意整数*，128]，输入时`shape`可以设置为：[*任意整数，**任意整数*，128]。维度只是个占位，网络运行时的实际维度是从输入数据中推导出来的。两个"任意整数" 在输入和配置时可以不相等，但是配置网络时，第一维度必须为-1。
++ 答复：在动态图模式下，可以参考如下示例：
 
-----------
+```
+import paddle.fluid as fluid
 
-##### 问题：如何从np.array生成一个具有Shape和DType的Tensor?
+with fluid.dygraph.guard(fluid.CPUPlace()):
+    x = np.ones([2, 2], np.float32)
+    y = fluid.dygraph.to_variable(x)
+```
 
-+ 答复：具体方法可参考文档 [LoD-Tensor使用说明]( https://www.paddlepaddle.org.cn/documentation/docs/zh/1.5/user_guides/howto/basic_concept/lod_tensor.html) 。
+具体请参考API [paddle.fluid.dygraph.to_variable](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/dygraph_cn/to_variable_cn.html#to-variable)
 
 ----------
 
 ##### 问题：如何初始化一个随机数的Tensor？
 
-+ 答复：
-
-
-
-  ta = fluid.create_lod_tensor(np.random.randn(10, 5), [], fluid.CPUPlace())
-
-  tb = fluid.create_lod_tensor(np.ones([5, 10]), [], place)
-
-  print(np.array(ta))
-
-  print(np.array(tb))
-
++ 答复：使用`numpy.random`生成随机的numpy.array，再参考上一个问题中的示例创建随机数Tensor即可。
 
 
 ## 模型搭建