PyDataProvider2的使用 ===================== PyDataProvider2是PaddlePaddle使用Python提供数据的推荐接口。该接口使用多线程读取数据,并提供了简单的Cache功能;同时可以使用户只关注如何从文件中读取每一条数据,而不用关心数据如何传输,如何存储等等。 .. contents:: MNIST的使用场景 --------------- 我们以MNIST手写识别为例,来说明PyDataProvider2的简单使用场景。 样例数据 ++++++++ MNIST是一个包含有70,000张灰度图片的数字分类数据集。样例数据 ``mnist_train.txt`` 如下: .. literalinclude:: src/mnist_train.txt 其中每行数据代表一张图片,行内使用 ``;`` 分成两部分。第一部分是图片的标签,为0-9中的一个数字;第二部分是28*28的图片像素灰度值。 对应的 ``train.list`` 即为这个数据文件的名字: .. literalinclude:: src/train.list dataprovider的使用 ++++++++++++++++++ .. literalinclude:: src/mnist_provider.dict.py - 首先,引入PaddlePaddle的PyDataProvider2包。 - 其次,定义一个Python的 `Decorator `_ `@provider`_ 。用于将下一行的数据输入函数标记成一个PyDataProvider2,同时设置它的input_types属性。 - `input_types`_:设置这个PyDataProvider2返回什么样的数据。本例根据网络配置中 ``data_layer`` 的名字,显式指定返回的是一个28*28维的稠密浮点数向量和一个[0-9]的10维整数标签。 .. literalinclude:: src/mnist_config.py :lines: 9-10 - 注意:如果用户不显示指定返回数据的对应关系,那么PaddlePaddle会根据layer的声明顺序,来确定对应关系。但这个关系可能不正确,所以推荐使用显式指定的方式来设置input_types。 - 最后,实现数据输入函数(如本例的 ``process`` 函数)。 - 该函数的功能是:打开文本文件,读取每一行,将行中的数据转换成与input_types一致的格式,然后返回给PaddlePaddle进程。注意, - 返回的顺序需要和input_types中定义的顺序一致。 - 返回时,必须使用Python关键词 ``yield`` ,相关概念是 ``generator`` 。 - 一次yield调用,返回一条完整的样本。如果想为一个数据文件返回多条样本,只需要在函数中调用多次yield即可(本例中使用for循环进行多次调用)。 - 该函数具有两个参数: - settings:在本例中没有使用,具体可以参考 `init_hook`_ 中的说明。 - filename:为 ``train.list`` 或 ``test.list`` 中的一行,即若干数据文件路径的某一个。 网络配置中的调用 ++++++++++++++++ 在网络配置里,只需要一行代码就可以调用这个PyDataProvider2,如, .. literalinclude:: src/mnist_config.py :lines: 1-7 训练数据是 ``train.list`` ,没有测试数据,调用的PyDataProvider2是 ``mnist_provider`` 模块中的 ``process`` 函数。 小结 +++++ 至此,简单的PyDataProvider2样例就说明完毕了。对用户来说,仅需要知道如何从 **一个文件** 中读取 **一条样本** ,就可以将数据传送给PaddlePaddle了。而PaddlePaddle则会帮用户做以下工作: * 将数据组合成Batch进行训练 * 对训练数据进行Shuffle * 多线程的数据读取 * 缓存训练数据到内存(可选) * CPU->GPU双缓存 是不是很简单呢? 时序模型的使用场景 ------------------ 样例数据 ++++++++ 时序模型是指数据的某一维度是一个序列形式,即包含时间步信息。所谓时间步信息,不一定和时间有关系,只是说明数据的顺序是重要的。例如,文本信息就是一个序列数据。 本例采用英文情感分类的数据,即将一段英文文本数据,分类成正面情绪和负面情绪两类(用0和1表示)。样例数据 ``sentimental_train.txt`` 如下: .. literalinclude:: src/sentimental_train.txt dataprovider的使用 ++++++++++++++++++ 相对MNIST而言,这个dataprovider较复杂,主要原因是增加了初始化机制 `init_hook`_。本例的 ``on_init`` 函数就是根据该机制配置的,它会在dataprovider创建的时候执行。 - 其中 ``input_types`` 和在 `@provider`_ 中配置的效果一致。本例中的输入特征是词ID的序列,因此使用 ``integer_value_sequence`` 类型来设置。 - 将 ``dictionary`` 存入settings对象,在 ``process`` 函数中使用。 dictionary是从网络配置中传入的dict对象,即一个将单词字符串映射到单词ID的字典。 .. literalinclude:: src/sentimental_provider.py 网络配置中的调用 ++++++++++++++++ 调用这个PyDataProvider2的方法,基本上和MNIST样例一致,除了 * 在配置中需要读取外部字典。 * 在声明DataProvider的时候传入dictionary作为参数。 .. literalinclude:: src/sentimental_config.py :emphasize-lines: 12-14 参考(Reference) --------------- @provider +++++++++ ``@provider`` 是一个Python的 `Decorator`_ ,可以将某一个函数标记成一个PyDataProvider2。如果不了解 `Decorator`_ 是什么也没关系,只需知道这是一个标记属性的方法就可以了。它包含的属性参数如下: * input_types:数据输入格式。具体的格式说明,请参考 `input_types`_ 。 * should_shuffle:是不是要对数据做Shuffle。训练时默认shuffle,测试时默认不shuffle。 * min_pool_size:设置内存中最小暂存的数据条数,也是PaddlePaddle所能够保证的shuffle粒度。如果为-1,则会预先读取全部数据到内存中。 * pool_size: 设置内存中暂存的数据条数。如果为-1(默认),则不在乎内存暂存多少条数据。如果设置,则推荐大于训练时batch size的值,并且在内存足够的情况下越大越好。 * can_over_batch_size:是否允许暂存略微多余pool_size的数据。由于这样做可以避免很多死锁问题,一般推荐设置成True。 * calc_batch_size:可以传入一个函数,用于自定义每条数据的batch size(默认为1)。 * cache: 数据缓存的策略,具体请参考 `cache`_ 。 * init_hook:初始化时调用的函数,具体请参考 `init_hook`_ 。 * check:如果为true,会根据input_types检查数据的合法性。 * check_fail_continue:如果为true,那么当check出数据不合法时,会扔到这条数据,继续训练或预测。(对check=false的情况,没有作用) input_types +++++++++++ PaddlePaddle的数据包括四种主要类型,和三种序列模式。 四种数据类型: * dense_vector:稠密的浮点数向量。 * sparse_binary_vector:稀疏的01向量,即大部分值为0,但有值的地方必须为1。 * sparse_float_vector:稀疏的向量,即大部分值为0,但有值的部分可以是任何浮点数。 * integer:整数标签。 三种序列模式: * SequenceType.NO_SEQUENCE:不是一条序列 * SequenceType.SEQUENCE:是一条时间序列 * SequenceType.SUB_SEQUENCE: 是一条时间序列,且序列的每一个元素还是一个时间序列。 不同的数据类型和序列模式返回的格式不同,列表如下: +----------------------+---------------------+-----------------------------------+------------------------------------------------+ | | NO_SEQUENCE | SEQUENCE | SUB_SEQUENCE | +======================+=====================+===================================+================================================+ | dense_vector | [f, f, ...] | [[f, ...], [f, ...], ...] | [[[f, ...], ...], [[f, ...], ...],...] | +----------------------+---------------------+-----------------------------------+------------------------------------------------+ | sparse_binary_vector | [i, i, ...] | [[i, ...], [i, ...], ...] | [[[i, ...], ...], [[i, ...], ...],...] | +----------------------+---------------------+-----------------------------------+------------------------------------------------+ | sparse_float_vector | [(i,f), (i,f), ...] | [[(i,f), ...], [(i,f), ...], ...] | [[[(i,f), ...], ...], [[(i,f), ...], ...],...] | +----------------------+---------------------+-----------------------------------+------------------------------------------------+ | integer_value | i | [i, i, ...] | [[i, ...], [i, ...], ...] | +----------------------+---------------------+-----------------------------------+------------------------------------------------+ 其中,f代表一个浮点数,i代表一个整数。 注意:对sparse_binary_vector和sparse_float_vector,PaddlePaddle存的是有值位置的索引。例如, - 对一个5维非序列的稀疏01向量 ``[0, 1, 1, 0, 0]`` ,类型是sparse_binary_vector,返回的是 ``[1, 2]`` 。 - 对一个5维非序列的稀疏浮点向量 ``[0, 0.5, 0.7, 0, 0]`` ,类型是sparse_float_vector,返回的是 ``[(1, 0.5), (2, 0.7)]`` 。 init_hook +++++++++ init_hook可以传入一个函数。该函数在初始化的时候会被调用,其参数如下: * 第一个参数是settings对象,它和数据传入函数的第一个参数(如本例中 ``process`` 函数的 ``settings`` 参数)必须一致。该对象具有以下两个属性: * settings.input_types:数据输入格式,具体请参考 `input_types`_ 。 * settings.logger:一个logging对象。 * 其他参数使用 ``kwargs`` (key word arguments)传入,包括以下两种: * PaddlePaddle定义的参数: 1)is_train:bool型参数,表示用于训练或预测;2)file_list:所有文件列表。 * 用户定义的参数:使用args在网络配置中设置。 注意:PaddlePaddle保留添加参数的权力,因此init_hook尽量使用 ``**kwargs`` 来接受不使用的函数以保证兼容性。 cache +++++ PyDataProvider2提供了两种简单的Cache策略: * CacheType.NO_CACHE:不缓存任何数据,每次都会从python端读取数据 * CacheType.CACHE_PASS_IN_MEM:第一个pass会从python端读取数据,剩下的pass会直接从内存里 读取数据。 注意事项 -------- 可能的内存泄露问题 ++++++++++++++++++ PaddlePaddle将train.list中的每一行都传递给process函数,从而生成多个generator。当训练数据非常多时,就会生成非常多的generator。 虽然每个generator在没有调用的时候,是几乎不占内存的;但当调用过一次后,generator便会存下当前的上下文(Context),而这个Context可能会非常大。并且,generator至少需要调用两次才会知道是否停止。所以,即使process函数里面只有一个yield,也需要两次随机选择到相同generator的时候,才会释放该段内存。 .. code-block:: python def func(): yield 0 f = func() # 创建generator tmp = next(f) # 调用一次,返回0 tmp = next(f) # 调用第二次的时候,才会Stop Iteration 由于顺序调用这些generator不会出现上述问题,因此有两种解决方案: 1. **最佳推荐**:将样本的地址放入另一个文本文件,train.list写入那个文本文件的地址。即不要将每一个样本都放入train.list。 2. 在generator的上下文中尽量留下非常少的变量引用,例如 .. code-block:: python def real_process(fn): # ... read from fn return result # 当函数返回的时候,python可以解除掉内部变量的引用。 def process(fn): yield real_process(fn) 注意:这个问题是PyDataProvider读数据时候的逻辑问题,很难整体修正。 内存不够用的情况 ++++++++++++++++ PyDataProvider2会尽可能多的使用内存。因此,对于内存较小的机器,推荐使用 ``pool_size`` 变量来设置内存中暂存的数据条。具体请参考 `@provider`_ 中的说明。