From bed22608aa10979943f12f26c3a309f2f97e2672 Mon Sep 17 00:00:00 2001 From: Zeng Jinle <32832641+sneaxiy@users.noreply.github.com> Date: Wed, 13 Mar 2019 13:08:42 +0800 Subject: [PATCH] refine reader doc (#686) --- .../howto/prepare_data/feeding_data.rst | 8 +-- .../user_guides/howto/prepare_data/index.rst | 49 ++++++++++++------- .../howto/prepare_data/reader_cn.md | 13 +---- .../howto/prepare_data/use_py_reader.rst | 2 +- 4 files changed, 38 insertions(+), 34 deletions(-) diff --git a/doc/fluid/user_guides/howto/prepare_data/feeding_data.rst b/doc/fluid/user_guides/howto/prepare_data/feeding_data.rst index c3bf033bb..a0ac8602c 100644 --- a/doc/fluid/user_guides/howto/prepare_data/feeding_data.rst +++ b/doc/fluid/user_guides/howto/prepare_data/feeding_data.rst @@ -1,8 +1,8 @@ .. _user_guide_use_numpy_array_as_train_data: -########################### -使用Numpy Array作为训练数据 -########################### +############################ +使用同步Feed方式读取训练和测试数据 +############################ PaddlePaddle Fluid支持使用 :code:`fluid.layers.data()` 配置数据层； 再使用 Numpy Array 或者直接使用Python创建C++的 @@ -84,7 +84,7 @@ PaddlePaddle Fluid支持使用 :code:`fluid.layers.data()` 配置数据层； exe.run(feed={ "sentence": create_lod_tensor( data=numpy.array([1, 3, 4, 5, 3, 6, 8], dtype='int64').reshape(-1, 1), - lod=[4, 1, 2], + lod=[[4, 1, 2]], place=fluid.CPUPlace() ) }) diff --git a/doc/fluid/user_guides/howto/prepare_data/index.rst b/doc/fluid/user_guides/howto/prepare_data/index.rst index 3dcc2fe17..2435d0b32 100644 --- a/doc/fluid/user_guides/howto/prepare_data/index.rst +++ b/doc/fluid/user_guides/howto/prepare_data/index.rst @@ -4,54 +4,69 @@ 准备数据 ######## -PaddlePaddle Fluid支持两种传入数据的方式: +使用PaddlePaddle Fluid准备数据分为两个步骤： -1. Python Reader同步方式：用户需要使用 :code:`fluid.layers.data` +- 自定义Reader生成训练/预测数据，生成的数据类型可以为Numpy Array或LoDTensor。根据Reader返回的数据形式的不同，可分为Batch级的Reader（每次返回一个batch的数据）和样本级的Reader（每次返回单个样本的数据）。 + +- 使用同步Feed方式或异步py_reader接口方式将数据送入网络进行训练/预测。 + +同步Feed方式和异步py_reader接口方式的比较 +###################################### + +同步Feed方式和异步py_reader接口方式的不同体现于： + +1. 同步Feed方式：用户需使用 :code:`fluid.layers.data` 配置数据输入层，并在 :code:`fluid.Executor` 或 :code:`fluid.ParallelExecutor` -中，使用 :code:`executor.run(feed=...)` 传入训练数据。 +中使用 :code:`executor.run(feed=...)` 传入训练数据。数据准备和模型训练/预测的过程是同步进行的， +效率较低。 -2. py_reader接口异步方式：用户需要先使用 :code:`fluid.layers.py_reader` 配置数据输入层，然后使用 +2. 异步py_reader接口方式：用户需要先使用 :code:`fluid.layers.py_reader` 配置数据输入层，然后使用 :code:`py_reader` 的 :code:`decorate_paddle_reader` 或 :code:`decorate_tensor_provider` -方法配置数据源，再通过 :code:`fluid.layers.read_file` 读取数据。 +方法配置数据源，再通过 :code:`fluid.layers.read_file` 读取数据。数据传入与模型训练/预测过程是异步进行的， +效率较高。 这两种准备数据方法的比较如下: ======== ================================= ===================================== -对比项 Python Reader同步方式 py_reader接口异步方式 +对比项 同步Feed方式 异步py_reader接口方式 ======== ================================= ===================================== API接口 :code:`executor.run(feed=...)` :code:`fluid.layers.py_reader` -数据格式 Numpy Array Numpy Array或LoDTensor +数据格式 Numpy Array或LoDTensor Numpy Array或LoDTensor 数据增强 Python端使用其他库完成 Python端使用其他库完成 速度 慢 快 推荐用途 调试模型 工业训练 ======== ================================= ===================================== -Python Reader同步方式 -##################### +读取Batch级Reader数据 +####################### -Fluid提供Python Reader方式传入数据。 -Python Reader是纯的Python端接口，数据传入与模型训练/预测过程是同步的。用户可通过Numpy Array传入 -数据，具体请参考: +若使用同步Feed方式送入数据，具体请参见: .. toctree:: :maxdepth: 1 feeding_data.rst -Python Reader支持组batch、shuffle等高级功能，具体请参考： +若使用异步py_reader接口方式送入数据，请调用py_reader的 :code:`decorate_tensor_provider` 接口完成，具体方式请参见: .. toctree:: :maxdepth: 1 - reader_cn.md + use_py_reader.rst -py_reader接口异步方式 +读取样本级Reader数据 ##################### -Fluid提供PyReader异步数据传入方式，数据传入与模型训练/预测过程是异步的，效率较高。具体请参考： +若自定义的Reader每次返回单个样本的数据，用户需通过以下步骤完成数据送入： + +1.调用Fluid提供的Reader相关接口完成组batch和部分的数据预处理功能，具体请参见： .. toctree:: :maxdepth: 1 - use_py_reader.rst + reader_cn.md + +2.若使用同步Feed方式送入数据，请使用DataFeeder接口将Reader数据转换为LoDTensor格式后送入网络，具体请参见 :ref:`cn_api_fluid_DataFeeder` 。若使用异步py_reader接口方式送入数据，请调用 :code:`decorate_paddle_reader` 接口完成，具体请参见： + +- :ref:`user_guides_use_py_reader` diff --git a/doc/fluid/user_guides/howto/prepare_data/reader_cn.md b/doc/fluid/user_guides/howto/prepare_data/reader_cn.md index 30e169395..840c9beba 100644 --- a/doc/fluid/user_guides/howto/prepare_data/reader_cn.md +++ b/doc/fluid/user_guides/howto/prepare_data/reader_cn.md @@ -1,7 +1,7 @@ # Python Reader 在模型训练和预测阶段，PaddlePaddle程序需要读取训练或预测数据。为了帮助用户编写数据读取的代码，我们提供了如下接口： -- *reader*: 用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个数据项。 +- *reader*: 样本级的reader，用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个样本数据项。 - *reader creator*: 接受一个或多个reader作为参数、返回一个新reader的函数。 - *reader decorator*: 一个函数，接受一个或多个reader，并返回一个reader。 - *batch reader*: 用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个batch大小的数据项。 @@ -185,15 +185,4 @@ def image_reader_creator(image_path, label_path, n): # images_reader_creator创建一个reader reader = image_reader_creator("/path/to/image_file", "/path/to/label_file", 1024) -paddle.train(paddle.batch(reader, 128), {"image":0, "label":1}, ...) -``` - -### `paddle.train`实现原理 -实现`paddle.train`的示例如下： - -```python -def train(batch_reader, mapping, batch_size, total_pass): - for pass_idx in range(total_pass): - for mini_batch in batch_reader(): # this loop will never end in online learning. - do_forward_backward(mini_batch, mapping) ``` diff --git a/doc/fluid/user_guides/howto/prepare_data/use_py_reader.rst b/doc/fluid/user_guides/howto/prepare_data/use_py_reader.rst index f44ea7891..0b48a907a 100644 --- a/doc/fluid/user_guides/howto/prepare_data/use_py_reader.rst +++ b/doc/fluid/user_guides/howto/prepare_data/use_py_reader.rst @@ -4,7 +4,7 @@ 使用PyReader读取训练和测试数据 ############################ -除Python Reader方法外，我们提供了PyReader。PyReader的性能比 :ref:`user_guide_use_numpy_array_as_train_data` 更好，因为PyReader的数据读取和模型训练过程是异步进行的，且能与 :code:`double_buffer_reader` 配合以进一步提高数据读取性能。此外， :code:`double_buffer_reader` 负责异步完成CPU Tensor到GPU Tensor的转换，一定程度上提升了数据读取效率。 +除同步Feed方式外，我们提供了PyReader。PyReader的性能比 :ref:`user_guide_use_numpy_array_as_train_data` 更好，因为PyReader的数据读取和模型训练过程是异步进行的，且能与 :code:`double_buffer_reader` 配合以进一步提高数据读取性能。此外， :code:`double_buffer_reader` 负责异步完成CPU Tensor到GPU Tensor的转换，一定程度上提升了数据读取效率。 创建PyReader对象 ################################ -- GitLab