From 8a8b7730a15ee86331c26c282f699ebd24c153bc Mon Sep 17 00:00:00 2001 From: Aurelius84 Date: Wed, 25 Sep 2019 11:43:00 +0800 Subject: [PATCH] improve seq_pool api cn doc (#1175) * improve seq_pool api cn doc test=document_preview * refine sequence last and first pool doc test=document_preview * refine sequence_pool dataType test=document_preview * fix input dtype * add dataType * fix datatype --- .../layers_cn/sequence_first_step_cn.rst | 55 +++++++++----- .../layers_cn/sequence_last_step_cn.rst | 44 +++++++---- .../api_cn/layers_cn/sequence_pool_cn.rst | 76 +++++++++++++------ 3 files changed, 117 insertions(+), 58 deletions(-) diff --git a/doc/fluid/api_cn/layers_cn/sequence_first_step_cn.rst b/doc/fluid/api_cn/layers_cn/sequence_first_step_cn.rst index 2e06cd014..399909f45 100644 --- a/doc/fluid/api_cn/layers_cn/sequence_first_step_cn.rst +++ b/doc/fluid/api_cn/layers_cn/sequence_first_step_cn.rst @@ -5,34 +5,51 @@ sequence_first_step .. py:function:: paddle.fluid.layers.sequence_first_step(input) -该功能获取序列的第一步 +该OP **仅支持LoDTensor类型的输入** ，将对输入的LoDTensor，在最后一层lod_level上，选取其每个序列（sequence）的第一个时间步（time_step）的特征向量作为池化后的输出向量。 :: - x是1-level LoDTensor: - - x.lod = [[2, 3, 2]] - - x.data = [1, 3, 2, 4, 6, 5, 1] - - x.dims = [7, 1] - - 输出为张量: - - out.dim = [3, 1] - with condition len(x.lod[-1]) == out.dims[0] - out.data = [1, 2, 5], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) - -参数：**input** (variable)-输入变量，为LoDTensor - -返回：序列第一步，为张量 + Case 1: + + input是1-level LoDTensor: + input.lod = [[0, 2, 5, 7]] + input.data = [[1.], [3.], [2.], [4.], [6.], [5.], [1.]] + input.shape = [7, 1] + + 输出为LoDTensor: + out.shape = [3, 1] + 且 out.shape[0] == len(x.lod[-1]) == 3 + out.data = [[1.], [2.], [5.]], where 1.=first(1., 3.), 2.=first(2., 4., 6.), 5.=first(5., 1.) + + Case 2: + + input是2-level的LoDTensor, 包含3个长度分别为[2, 0, 3]的序列，其中中间的0表示序列为空。 + 第一个长度为2的序列包含2个长度分别为[1, 2]的子序列； + 最后一个长度为3的序列包含3个长度分别为[1, 0, 3]的子序列。 + input.lod = [[0, 2, 2, 5], [0, 1, 3, 4, 4, 7]] + input.data = [[1.], [3.], [2.], [4.], [6.], [5.], [1.]] + input.shape = [7, 1] + + 将根据最后一层的lod信息[0, 1, 3, 4, 4, 7]进行池化操作，且pad_value = 0.0 + 输出为LoDTensor： + out.shape= [5, 1] + out.lod = [[0, 2, 2, 5]] + 其中 out.shape[0] == len(x.lod[-1]) == 5 + out.data = [[1.], [3.], [4.], [0.0], [6.]] + where 1.=first(1.), 3.=first(3., 2.), 4.=first(4.), 0.0 = pad_value, 6.=first(6., 5., 1.) + +参数：**input** (Variable)- 类型为LoDTensor的输入序列，仅支持lod_level不超过2的LoDTensor，数据类型为float32。 + +返回：每个输入序列中的第一个step的特征向量组成的LoDTensor，数据类型为float32。 + +返回类型：Variable **代码示例**： .. code-block:: python import paddle.fluid as fluid - x = fluid.layers.data(name='x', shape=[7, 1], + x = fluid.layers.data(name='x', shape=[7, 1], append_batch_size=False, dtype='float32', lod_level=1) x_first_step = fluid.layers.sequence_first_step(input=x) diff --git a/doc/fluid/api_cn/layers_cn/sequence_last_step_cn.rst b/doc/fluid/api_cn/layers_cn/sequence_last_step_cn.rst index 579117599..5684964a0 100644 --- a/doc/fluid/api_cn/layers_cn/sequence_last_step_cn.rst +++ b/doc/fluid/api_cn/layers_cn/sequence_last_step_cn.rst @@ -5,36 +5,52 @@ sequence_last_step .. py:function:: paddle.fluid.layers.sequence_last_step(input) -该API可以获取序列的最后一步 +该OP **仅支持LoDTensor类型的输入** ，将对输入的LoDTensor，在最后一层lod_level上，选取其每个序列（sequence）的最后一个时间步（time-step）的特征向量作为池化后的输出向量。 :: - x是level-1的LoDTensor: + Case 1: - x.lod = [[2, 3, 2]] + input是1-level的LoDTensor: + input.lod = [[0, 2, 5, 7]] + input.data = [[1.], [3.], [2.], [4.], [6.], [5.], [1.]] + input.shape = [7, 1] - x.data = [1, 3, 2, 4, 6, 5, 1] + 输出为LoDTensor: + out.shape = [3, 1] + 且 out.shape[0] == len(x.lod[-1]) == 3 - x.dims = [7, 1] + out.data = [[3.], [6.], [1.]], where 3.=last(1., 3.), 6.=last(2., 4., 6.), 1.=last(5., 1.) - 输出为Tensor: + Case 2: + + input是2-level的LoDTensor, 包含3个长度分别为[2, 0, 3]的序列，其中中间的0表示序列为空。 + 第一个长度为2的序列包含2个长度分别为[1, 2]的子序列； + 最后一个长度为3的序列包含3个长度分别为[1, 0, 3]的子序列。 + input.lod = [[0, 2, 2, 5], [0, 1, 3, 4, 4, 7]] + input.data = [[1.], [3.], [2.], [4.], [6.], [5.], [1.]] + input.shape = [7, 1] + + 将根据最后一层的lod信息[0, 1, 3, 4, 4, 7]进行池化操作，且pad_value = 0.0 + 输出为LoDTensor： + out.shape= [5, 1] + out.lod = [[0, 2, 2, 5]] + 其中 out.shape[0] == len(x.lod[-1]) == 5 + out.data = [[1.], [2.], [4.], [0.0], [1.]] + where 1.=last(1.), 2.=last(3., 2.), 4.=last(4.), 0.0 = pad_value, 1=last(6., 5., 1.) - out.dim = [3, 1] +参数：**input** (Variable)- 类型为LoDTensor的输入序列，仅支持lod_level不超过2的LoDTensor，数据类型为float32。 - 且 len(x.lod[-1]) == out.dims[0] +返回：每个输入序列中的最后一步特征向量组成的LoDTensor，数据类型为float32。 - out.data = [3, 6, 1], where 3=last(1,3), 6=last(2,4,6), 1=last(5,1) - -参数：**input** (variable)-输入变量，为LoDTensor - -返回：序列的最后一步，为张量 +返回类型：Variable **代码示例**： .. code-block:: python import paddle.fluid as fluid - x = fluid.layers.data(name='x', shape=[7, 1], + x = fluid.layers.data(name='x', shape=[7, 1], append_batch_size=False, dtype='float32', lod_level=1) x_last_step = fluid.layers.sequence_last_step(input=x) diff --git a/doc/fluid/api_cn/layers_cn/sequence_pool_cn.rst b/doc/fluid/api_cn/layers_cn/sequence_pool_cn.rst index 799cedbe4..84f890c0c 100644 --- a/doc/fluid/api_cn/layers_cn/sequence_pool_cn.rst +++ b/doc/fluid/api_cn/layers_cn/sequence_pool_cn.rst @@ -5,43 +5,69 @@ sequence_pool .. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type, is_test=False, pad_value=0.0) -该函数为序列的池化添加操作符。将每个实例的所有时间步数特征池化，并用参数中提到的pool_type将特征运用到输入到首部。 +**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用pool2d函数（fluid.layers.** :ref:`cn_api_fluid_layers_pool2d` **）。** -支持四种pool_type: +该OP **仅支持LoDTensor类型的输入** ，将对输入的LoDTensor进行指定方式的池化（pooling）操作。通过指定pool_type参数，将输入的每个序列（sequence）在最后一层lod_level上或时间步（time-step）上对特征进行诸如sum、average、sqrt等池化操作。 + +支持六种pool_type: - **average**: :math:`Out[i] = \frac{\sum_{i}X_{i}}{N}` - **sum**: :math:`Out[i] = \sum _{j}X_{ij}` - **sqrt**: :math:`Out[i] = \frac{ \sum _{j}X_{ij}}{\sqrt{len(\sqrt{X_{i}})}}` - **max**: :math:`Out[i] = max(X_{i})` +- **last**: :math:`Out[i] = X_{N\_i}` +- **first**: :math:`Out[i] = X_{0}` -:: +其中 ``N_i`` 为待池化第i个输入序列的长度。 +:: - x是一级LoDTensor且**pad_value** = 0.0: - x.lod = [[2, 3, 2, 0]] - x.data = [1, 3, 2, 4, 6, 5, 1] - x.dims = [7, 1] - 输出为张量（Tensor）： - out.dim = [4, 1] - with condition len(x.lod[-1]) == out.dims[0] - 对于不同的pool_type： - average: out.data = [2, 4, 3, 0.0], where 2=(1+3)/2, 4=(2+4+6)/3, 3=(5+1)/2 - sum : out.data = [4, 12, 6, 0.0], where 4=1+3, 12=2+4+6, 6=5+1 - sqrt : out.data = [2.82, 6.93, 4.24, 0.0], where 2.82=(1+3)/sqrt(2), - 6.93=(2+4+6)/sqrt(3), 4.24=(5+1)/sqrt(2) - max : out.data = [3, 6, 5, 0.0], where 3=max(1,3), 6=max(2,4,6), 5=max(5,1) - last : out.data = [3, 6, 1, 0.0], where 3=last(1,3), 6=last(2,4,6), 1=last(5,1) - first : out.data = [1, 2, 5, 0.0], where 1=first(1,3), 2=first(2,4,6), 5=first(5,1) + Case 1: + + input是1-level的LoDTensor, 且pad_value = 0.0: + input.lod = [[0, 2, 5, 7, 7]] + input.data = [[1.], [3.], [2.], [4.], [6.], [5.], [1.]] + input.shape = [7, 1] + 输出为LoDTensor： + out.shape = [4, 1] + 其中 out.shape[0] == len(x.lod[-1]) == 4 + 对于不同的pool_type： + average: out.data = [[2.], [4.], [3.], [0.0]], where 2.=(1. + 3.)/2, 4.=(2. + 4. + 6.)/3, 3.=(5. + 1.)/2 + sum : out.data = [[4.], [12.], [6.], [0.0]], where 4.=1. + 3., 12.=2. + 4. + 6., 6.=5. + 1. + sqrt : out.data = [[2.82], [6.93], [4.24], [0.0]], where 2.82=(1. + 3.)/sqrt(2), 6.93=(2. + 4. + 6.)/sqrt(3), 4.24=(5. + 1.)/sqrt(2) + max : out.data = [[3.], [6.], [5.], [0.0]], where 3.=max(1., 3.), 6.=max(2., 4., 6.), 5.=max(5., 1.) + last : out.data = [[3.], [6.], [1.], [0.0]], where 3.=last(1., 3.), 6.=last(2., 4., 6.), 1.=last(5., 1.) + first : out.data = [[1.], [2.], [5.], [0.0]], where 1.=first(1., 3.), 2.=first(2., 4., 6.), 5.=first(5., 1.) - 且以上所有均满足0.0 = **pad_value** + 上述out.data中的最后一个[0.0]均为填充的数据。 + + Case 2: + + input是2-level的LoDTensor, 包含3个长度分别为[2, 0, 3]的序列，其中中间的0表示序列为空。 + 第一个长度为2的序列包含2个长度分别为[1, 2]的子序列； + 最后一个长度为3的序列包含3个长度分别为[1, 0, 3]的子序列。 + input.lod = [[0, 2, 2, 5], [0, 1, 3, 4, 4, 7]] + input.data = [[1.], [3.], [2.], [4.], [6.], [5.], [1.]] + input.shape = [7, 1] + + 以pool_type取值为sum为例，将根据最后一层的lod信息[0, 1, 3, 4, 4, 7]进行池化操作，且pad_value = 0.0 + 输出为LoDTensor： + out.shape= [5, 1] + out.lod = [[0, 2, 2, 5]] + 其中 out.shape[0] == len(x.lod[-1]) == 5 + sum: out.data = [[1.], [5.], [4.], [0.0], [12.]] + where 1.=1., 5.=3. + 2., 4.=4., 0.0=pad_value, 12.=6. + 5. + 1. + 参数： - - **input** (variable) - 输入变量，为LoDTensor - - **pool_type** (string) - 池化类型。支持average,sum,sqrt和max - - **is_test** (bool, 默认为 False) - 用于区分训练模式和测试评分模式。默认为False。 - - **pad_value** (float) - 用于填充空输入序列的池化结果。 + - **input** (Variable) - 类型为LoDTensor的输入序列，仅支持lod_level不超过2的LoDTensor，数据类型为float32。 + - **pool_type** (str) - 池化类型，支持average，sum，sqrt，max，last和first池化操作。 + - **is_test** (bool) - 仅在pool_type取值为max时生效。当is_test为False时，则在池化操作过程中会创建maxIndex临时Tenosr，以记录最大特征值对应的索引信息，用于训练阶段的反向梯度计算。默认为False。 + - **pad_value** (float) - 用于填充输入序列为空时的池化结果，默认为0.0。 + +返回：经过指定类型池化后的LoDTensor，数据类型为float32。 -返回：sequence pooling 变量，类型为张量（Tensor) +返回类型：Variable **代码示例**: @@ -49,7 +75,7 @@ sequence_pool import paddle.fluid as fluid - x = fluid.layers.data(name='x', shape=[7, 1], + x = fluid.layers.data(name='x', shape=[7, 1], append_batch_size=False, dtype='float32', lod_level=1) avg_x = fluid.layers.sequence_pool(input=x, pool_type='average') sum_x = fluid.layers.sequence_pool(input=x, pool_type='sum') -- GitLab