From a36df60a1ce7532aa15fec336512a98bbb79a5d5 Mon Sep 17 00:00:00 2001 From: Luo Tao Date: Tue, 29 Nov 2016 13:59:21 +0800 Subject: [PATCH] refine dataprovider rst based on comments --- doc_cn/ui/data_provider/dataprovider.rst | 14 ++++---- doc_cn/ui/data_provider/pydataprovider2.rst | 39 +++++++++++---------- 2 files changed, 27 insertions(+), 26 deletions(-) diff --git a/doc_cn/ui/data_provider/dataprovider.rst b/doc_cn/ui/data_provider/dataprovider.rst index e1ad330c29a..e6796429a78 100644 --- a/doc_cn/ui/data_provider/dataprovider.rst +++ b/doc_cn/ui/data_provider/dataprovider.rst @@ -1,15 +1,13 @@ DataProvider的介绍 ================== -DataProvider是PaddlePaddle负责提供数据的模块。其作用是将数据传入内存或显存，让神经网络可以进行训练或预测。有两种使用方式： - -- 简单使用：使用Python接口 `PyDataProvider2 `_ 来自定义传数据的过程。 -- 高级使用：如果用户有更复杂的使用，或者需要更高的效率，可以在C++端自定义一个 ``DataProvider`` 。 +DataProvider是PaddlePaddle负责提供数据的模块。其作用是将数据传入内存或显存，让神经网络可以进行训练或预测。用户可以通过简单使用Python接口 `PyDataProvider2 `_ ，来自定义传数据的过程。如果有更复杂的使用，或者需要更高的效率，用户也可以在C++端自定义一个 ``DataProvider`` 。 PaddlePaddle需要用户在网络配置（trainer_config.py）中定义使用哪种DataProvider，并且在DataProvider中实现如何访问训练文件列表（train.list）或测试文件列表（test.list）。 -- train.list和test.list存放在本地（推荐直接存放到训练目录，以相对路径引用)。一般情况下，两者均为纯文本文件，其中每一行对应一个数据文件地址： - - - 如果数据文件存于本地磁盘，则将这些文件的绝对路径或相对路径(相对于PaddlePaddle程序运行时的路径)写在train.list和test.list中。 - - 地址也可以为hdfs文件路径，或者数据库连接地址等。 +- train.list和test.list存放在本地（推荐直接存放到训练目录，以相对路径引用)。一般情况下，两者均为纯文本文件，其中每一行对应一个数据文件地址： + + - 如果数据文件存于本地磁盘，这个地址则为它的绝对路径或相对路径(相对于PaddlePaddle程序运行时的路径)。 + - 地址也可以为hdfs文件路径，或者数据库连接路径等。 + - 由于这个地址会被DataProvider使用，因此，如何解析该地址也是用户自定义DataProvider时需要考虑的地方。 - 如果没有设置test.list，或设置为None，那么在训练过程中不会执行测试操作；否则，会根据命令行参数指定的测试方式，在训练过程中进行测试，从而防止过拟合。 diff --git a/doc_cn/ui/data_provider/pydataprovider2.rst b/doc_cn/ui/data_provider/pydataprovider2.rst index 3455e331da0..c0b3286ad52 100644 --- a/doc_cn/ui/data_provider/pydataprovider2.rst +++ b/doc_cn/ui/data_provider/pydataprovider2.rst @@ -1,14 +1,14 @@ PyDataProvider2的使用 ===================== -PyDataProvider2是PaddlePaddle使用Python提供数据的接口。该接口使用多线程读取数据，并提供了简单的Cache功能；同时可以使用户只关注如何从文件中读取每一条数据，而不用关心数据如何传输，如何存储等等。 +PyDataProvider2是PaddlePaddle使用Python提供数据的推荐接口。该接口使用多线程读取数据，并提供了简单的Cache功能；同时可以使用户只关注如何从文件中读取每一条数据，而不用关心数据如何传输，如何存储等等。 .. contents:: MNIST的使用场景 --------------- -我们以MNIST手写识别为例，来说明如何使用最简单的PyDataProvider2。 +我们以MNIST手写识别为例，来说明PyDataProvider2的简单使用场景。 样例数据 ++++++++ @@ -17,7 +17,7 @@ MNIST是一个包含有70,000张灰度图片的数字分类数据集。样例数 .. literalinclude:: mnist_train.txt -其中每行数据代表一张图片，行内使用 ``;`` 分成两部分。第一部分是图片的标签，为0-9中的一个数字；第二部分是28*28的图片像素灰度值。 对应的 ``train.list`` 为： +其中每行数据代表一张图片，行内使用 ``;`` 分成两部分。第一部分是图片的标签，为0-9中的一个数字；第二部分是28*28的图片像素灰度值。 对应的 ``train.list`` 即为这个数据文件的名字： .. literalinclude:: train.list @@ -40,7 +40,8 @@ dataprovider的使用 - 该函数的功能是：打开文本文件，读取每一行，将行中的数据转换成与input_types一致的格式，然后返回给PaddlePaddle进程。注意， - 返回的顺序需要和input_types中定义的顺序一致。 - - 返回时，必须使用关键词 ``yield`` 。一次yield调用，即返回一条完整的样本。如果想为一个数据文件返回多条样本，只需要在函数中调用多次yield即可（本例中使用for循环进行多次调用）。 + - 返回时，必须使用Python关键词 ``yield`` ，相关概念是 ``generator`` 。 + - 一次yield调用，返回一条完整的样本。如果想为一个数据文件返回多条样本，只需要在函数中调用多次yield即可（本例中使用for循环进行多次调用）。 - 该函数具有两个参数： @@ -55,7 +56,20 @@ dataprovider的使用 .. literalinclude:: mnist_config.py :lines: 1-7 -训练数据是 ``train.list`` ，测试数据没有，调用的PyDataProvider2是 ``mnist_provider`` 模块中的 ``process`` 函数。 +训练数据是 ``train.list`` ，没有测试数据，调用的PyDataProvider2是 ``mnist_provider`` 模块中的 ``process`` 函数。 + +小结 ++++++ + +至此，简单的PyDataProvider2样例就说明完毕了。对用户来说，仅需要知道如何从 **一个文件** 中读取 **一条样本** ，就可以将数据传送给PaddlePaddle了。而PaddlePaddle则会帮用户做以下工作： + +* 将数据组合成Batch进行训练 +* 对训练数据进行Shuffle +* 多线程的数据读取 +* 缓存训练数据到内存(可选) +* CPU->GPU双缓存 + +是不是很简单呢？ 时序模型的使用场景 ------------------ @@ -89,19 +103,6 @@ dataprovider的使用 .. literalinclude:: sentimental_config.py :emphasize-lines: 12-14 -小结 ------ - -至此，两个PyDataProvider2的样例就说明完毕了。对用户来说，仅需要知道如何从 **一个文件** 中读取 **一条样本** ，就可以将数据传送给PaddlePaddle了。而PaddlePaddle则会帮用户做以下工作： - -* 将数据组合成Batch进行训练 -* 对训练数据进行Shuffle -* 多线程的数据读取 -* 缓存训练数据到内存(可选) -* CPU->GPU双缓存 - -是不是很简单呢？ - 参考(Reference) --------------- @@ -167,6 +168,8 @@ init_hook可以传入一个函数。该函数在初始化的时候会被调用 * PaddlePaddle定义的参数: 1）is_train：bool型参数，表示用于训练或预测；2）file_list：所有文件列表。 * 用户定义的参数：使用args在网络配置中设置。 +注意：PaddlePaddle保留添加参数的权力，因此init_hook尽量使用 ``**kwargs`` 来接受不使用的函数以保证兼容性。 + cache +++++ -- GitLab