From 45d28cd22b1aaec0e7ad9ccb4aecfa52b4b970ce Mon Sep 17 00:00:00 2001 From: Diego Zhang Date: Fri, 11 Oct 2019 11:27:23 +0800 Subject: [PATCH] revision sequence_expand cn doc (#1335) * revision sequence_expand cn doc * only surpport LoDTensor * change name's text * add input output shape * add code example * add code example * test=document_fix --- .../api_cn/layers_cn/sequence_expand_cn.rst | 111 ++++++++++++------ .../api_cn/layers_cn/sequence_mask_cn.rst | 31 +++-- 2 files changed, 97 insertions(+), 45 deletions(-) diff --git a/doc/fluid/api_cn/layers_cn/sequence_expand_cn.rst b/doc/fluid/api_cn/layers_cn/sequence_expand_cn.rst index ba8981575..5b301b1fc 100644 --- a/doc/fluid/api_cn/layers_cn/sequence_expand_cn.rst +++ b/doc/fluid/api_cn/layers_cn/sequence_expand_cn.rst @@ -5,53 +5,56 @@ sequence_expand .. py:function:: paddle.fluid.layers.sequence_expand(x, y, ref_level=-1, name=None) -序列扩张层（Sequence Expand Layer) +序列扩张层（Sequence Expand Layer)，根据输入 ``y`` 的第 ``ref_level`` 层lod对输入 ``x`` 进行扩展。 ``x`` 的lod level最多为1，若 ``x`` 的lod level为1，则 ``x`` 的lod大小必须与 ``y`` 的第 ``ref_level`` 层lod大小相等；若 ``x`` 的lod level为0，则 ``x`` 的第一维大小必须与 ``y`` 第 ``ref_level`` 层大小相等。 ``x`` 的秩最少为2，当 ``x`` 的秩大于2时，将被当作是一个二维张量处理。 -将根据指定 y 的 level lod 展开输入变量x，请注意 x 的 lod level 最多为1，而 x 的秩最少为2。当 x 的秩大于2时，它就被看作是一个二维张量。下面的例子将解释 sequence_expand 是如何工作的: +注意，该OP的输入 ``x`` 可以是Tensor或LodTensor， ``y`` 只能是LodTensor。 -:: - - - * 例1 - x is a LoDTensor: - x.lod = [[2, 2]] - x.data = [[a], [b], [c], [d]] - x.dims = [4, 1] - - y is a LoDTensor: - y.lod = [[2, 2], - [3, 3, 1, 1]] +范例解释如下： - ref_level: 0 - - then output is a 1-level LoDTensor: - out.lod = [[2, 2, 2, 2]] - out.data = [[a], [b], [a], [b], [c], [d], [c], [d]] - out.dims = [8, 1] +:: - * 例2 - x is a Tensor: - x.data = [[a], [b], [c]] - x.dims = [3, 1] + 例1： + 假设两个长度为2的序列[a][b]和[c][d]，欲将其扩展为4个长度为2的序列[a][b]、[a][b]、[c][d]、[c][d]。 + 序列[a][b]扩展2次，[c][d]扩展2次，扩展所需依据的lod为[2, 2]，则： + 给定输入一维LoDTensor x + x.lod = [[2, 2]] #表示两个序列的长度为2，为了便于理解这里用基于长度lod表示 + x.data = [[a], [b], [c], [d]] + x.dims = [4, 1] + 和输入 y + y.lod = [[2, 2], #第0层lod，指定按该层扩展，表示分别扩展2次，为了便于理解这里用基于长度lod表示 + [3, 3, 1, 1]] #第1层lod，注意，因为指定ref_level为0，所以这一层与运算无关 + 指定 ref_level = 0，依据y的第0层lod进行扩展， + + 经过sequence_expand，输出为1级LoDTensor out + out.lod = [[0, 2, 4, 6, 8]] #基于偏移的lod，等价于基于长度的[[2, 2, 2, 2]] + out.data = [[a], [b], [a], [b], [c], [d], [c], [d]] + out.dims = [8, 1] - y is a LoDTensor: - y.lod = [[2, 0, 3]] +:: - ref_level: -1 + 例2： + 假设有3个长度维1的序列[a]、[b]、[c]，现在要将其扩展为长度是2、0、3的序列[a][a]、[c][c][c]。 + 显然，扩展后的序列lod为[2, 0, 3]，则： + 给定输入一维LoDTensor x + x.data = [[a], [b], [c]] + x.dims = [3, 1] + 和输入 y + y.lod = [[2, 0, 3]] + 默认 ref_level = -1 - then output is a Tensor: - out.data = [[a], [a], [c], [c], [c]] - out.dims = [5, 1] + 经过sequence_expand，输出为1级LoDTensor out + out.data = [[a], [a], [c], [c], [c]] + out.dims = [5, 1] 参数： - - **x** (Variable) - 输入变量，张量或LoDTensor - - **y** (Variable) - 输入变量，为LoDTensor - - **ref_level** (int) - x表示的y的Lod层。若设为-1，表示lod的最后一层 - - **name** (str|None) - 该层名称（可选）。如果设为空，则自动为该层命名 + - **x** (Variable) - 输入变量，维度为 :math:`[M, K]` ，lod level至多1的二维Tensor或LoDTensor。数据类型支持int32，int64，float32或float64。 + - **y** (Variable) - 输入变量，lod level至少为1的LoDTensor。数据类型不限。 + - **ref_level** (int，可选) - 扩展 ``x`` 所依据的 ``y`` 的lod层。默认值-1，表示lod的最后一层。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -返回：扩展变量，LoDTensor +返回：扩展变量，维度为 :math:`[N, K]` 的LoDTensor，N由输入 ``x`` 和 ``y`` 的lod共同决定。数据类型与输入 ``x`` 一致。 -返回类型：变量（Variable） +返回类型：Variable **代码示例**： @@ -59,11 +62,43 @@ sequence_expand import paddle.fluid as fluid import paddle.fluid.layers as layers - x = fluid.layers.data(name='x', shape=[10], dtype='float32') - y = fluid.layers.data(name='y', shape=[10, 20], + import numpy as np + + x = fluid.data(name='x', shape=[1], dtype='float32') + y = fluid.data(name='y', shape=[1], dtype='float32', lod_level=1) out = layers.sequence_expand(x=x, y=y, ref_level=0) + exe = fluid.Executor(fluid.CPUPlace()) + place = fluid.CPUPlace() + + np_data = np.array([[1], [2], [3], [4]]).astype('float32') + x_lod_tensor = fluid.create_lod_tensor(np_data, [[2, 2]], place) + print(x_lod_tensor) + #lod: [[0, 2, 4]] + # dim: 4, 1 + # layout: NCHW + # dtype: float + # data: [1 2 3 4] + + y_lod_tensor = fluid.create_random_int_lodtensor([[2, 2], [3,3,1,1]], [1], + place, low=0, high=1) + print(y_lod_tensor) + #lod: [[0, 2, 4][0, 3, 6, 7, 8]] + # dim: 8, 1 + # layout: NCHW + # dtype: int64_t + # data: [0 0 1 1 1 1 1 0] + + out_main = exe.run(fluid.default_main_program(), + feed={'x': x_lod_tensor, 'y': y_lod_tensor}, + fetch_list=[out], return_numpy=False) + print(out_main[0]) + #lod: [[0, 2, 4, 6, 8]] + # dim: 8, 1 + # layout: NCHW + # dtype: float + # data: [1 2 1 2 3 4 3 4] diff --git a/doc/fluid/api_cn/layers_cn/sequence_mask_cn.rst b/doc/fluid/api_cn/layers_cn/sequence_mask_cn.rst index 0134b0371..d9b941ab9 100644 --- a/doc/fluid/api_cn/layers_cn/sequence_mask_cn.rst +++ b/doc/fluid/api_cn/layers_cn/sequence_mask_cn.rst @@ -5,21 +5,38 @@ sequence_mask .. py:function:: paddle.fluid.layers.sequence_mask(x, maxlen=None, dtype='int64', name=None) -该层根据输入 ``x`` 和 ``maxlen`` 输出一个掩码，数据类型为dtype。 +该层根据输入 ``x`` 和 ``maxlen`` 输出一个掩码，数据类型为 ``dtype`` 。 -假设x是一个形状为[d_1, d_2，…, d_n]的张量。， y是一个形为[d_1, d_2，… ，d_n, maxlen]的掩码，其中: +假设 x 是一个形状为 ``[d_1, d_2，…, d_n]`` 的张量， 则输出 y 是一个形为 ``[d_1, d_2，… ，d_n, maxlen]`` 的掩码，其中: .. math:: y(i_1, i_2,..., i_n, j) = (j < x(i_1, i_2,..., i_n)) +范例如下： + +:: + + 给定输入： + x = [3, 1, 1, 0] maxlen = 4 + + 得到输出张量： + mask = [[1, 1, 1, 0], + [1, 0, 0, 0], + [1, 0, 0, 0], + [0, 0, 0, 0]] + + + + + 参数： - - **x** (Variable) - sequence_mask层的输入张量，其元素是小于maxlen的整数。 - - **maxlen** (int|None) - 序列的最大长度。如果maxlen为空，则用max(x)替换。 - - **dtype** (np.dtype|core.VarDesc.VarType|str) - 输出的数据类型 - - **name** (str|None) - 此层的名称(可选)。如果没有设置，该层将被自动命名。 + - **x** (Variable) - 输入张量，其元素是小于等于 ``maxlen`` 的整数，Tensor或LoDTensor。 + - **maxlen** (int，可选) - 序列的最大长度。默认为空，此时 ``maxlen`` 取 ``x`` 中所有元素的最大值。 + - **dtype** (np.dtype|core.VarDesc.VarType|str，可选) - 输出的数据类型，默认为 ``int64`` 。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -返回： sequence mask 的输出 +返回： mask张量，Tensor或LoDTensor。 返回类型： Variable -- GitLab