diff --git a/doc/fluid/api_cn/layers_cn.rst b/doc/fluid/api_cn/layers_cn.rst index 73fc9c1f1869000be1834309c51bc8abe7a58c5d..6cbc07ca696359e347948afbe3772f20c7b27ae2 100644 --- a/doc/fluid/api_cn/layers_cn.rst +++ b/doc/fluid/api_cn/layers_cn.rst @@ -20,11 +20,12 @@ array_length 此功能用于查找输入数组LOD_TENSOR_ARRAY的长度。 相关API: - - :ref:`api_fluid_layers_array_read` - - :ref:`api_fluid_layers_array_write` - - :ref:`api_fluid_layers_While` + - :ref:`cn_api_fluid_layers_array_read` + - :ref:`cn_api_fluid_layers_array_write` + - :ref:`cn_api_fluid_layers_While` -参数：**array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度 +参数： + - **array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度 返回：输入数组LoDTensorArray的长度 @@ -201,6 +202,9 @@ memory用于缓存分段数据。memory的初始值可以是零，也可以是 动态RNN可以将多个变量标记为其输出。使用drnn()获得输出序列。 +.. note:: + 目前不支持在DynamicRNN中任何层上配置 is_sparse = True + .. py:method:: step_input(x) 将序列标记为动态RNN输入。 @@ -396,12 +400,15 @@ increment .. py:function:: paddle.fluid.layers.increment(x, value=1.0, in_place=True) -该函数为输入 ``x`` 中的每一个值增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。 - +该函数为输入 ``x`` 增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。 + +.. note:: + ``x`` 中元素个数必须为1 + 参数: - **x** (Variable|list) – 含有输入值的张量(tensor) - **value** (float) – 需要增加在 ``x`` 变量上的值 - - **in_place** (bool) – 是否在 ``x`` 变量本身进行增加操作，而非返回其增加后的一个副本而本身不改变。默认为True, 即在其本身进行操作。 + - **in_place** (bool) – 判断是否在x变量本身执行操作，True原地执行，False时，返回增加后的副本 返回： 每个元素增加后的对象 @@ -411,7 +418,8 @@ increment .. code-block:: python - data = fluid.layers.data(name='data', shape=[32, 32], dtype='float32') + data = fluid.layers.data(name='data', shape=[1], dtype='float32', + append_batch_size=False) data = fluid.layers.increment(x=data, value=3.0, in_place=True) @@ -850,7 +858,7 @@ data 2.如果维度shape包含-1，比如shape=[-1,1], “append_batch_size则为False（表示无效）” - - **dtype** (int|float)-数据类型：float32,float_16,int等 + - **dtype** (basestring)-数据类型：float32,float_16,int等 - **type** (VarType)-输出类型。默认为LOD_TENSOR - **lod_level** (int)-LoD层。0表示输入数据不是一个序列 - **stop_gradient** (bool)-布尔类型，提示是否应该停止计算梯度 @@ -1214,7 +1222,7 @@ read_file reader也是变量。可以为由fluid.layers.open_files()生成的原始reader或者由fluid.layers.double_buffer()生成的装饰变量，等等。 参数： - **reader** (Variable)-将要执行的reader + - **reader** (Variable)-将要执行的reader 返回：从给定的reader中读取数据 @@ -1246,13 +1254,14 @@ shuffle .. py:function:: paddle.fluid.layers.shuffle(reader, buffer_size) -使用python装饰器用shuffle 装饰 reader +创建一个特殊的数据读取器，它的输出数据会被重洗(shuffle)。由原始读取器创建的迭代器得到的输出将会被暂存到shuffle缓存区，其后 +会对其进行重洗运算。shuffle缓存区的大小由参数 ``buffer_size`` 决定。 参数: - **reader** (Variable) – 用shuffle装饰的reader - **buffer_size** (int) – reader中buffer的大小 -返回:用shuffle装饰后的reader +返回:其输出会被重洗的一个reader（读取器） 返回类型:Variable @@ -2484,16 +2493,15 @@ ctc_greedy_decoder .. py:function:: paddle.fluid.layers.ctc_greedy_decoder(input, blank, name=None) 此op用于贪婪策略解码序列，步骤如下: - - 1. 获取输入中的每一行的最大值索引。又名numpy.argmax(input, axis=0)。 - 2. 对于step1结果中的每个序列，在两个空格之间合并重复token并删除所有空格。 + 1. 获取输入中的每一行的最大值索引，也就是numpy.argmax(input, axis=0)。 + 2. 对于step1结果中的每个序列，在两个空格之间合并重复部分（即合并重复的上一步中的到的索引值）并删除所有空格。 -A simple example as below: +简单举一个例子， - :: +:: - Given: + 已知： input.data = [[0.6, 0.1, 0.3, 0.1], [0.3, 0.2, 0.4, 0.1], @@ -2507,7 +2515,14 @@ A simple example as below: input.lod = [[4, 4]] - Then: + 计算过程： + + 1. 将argmax的运算结果应用于输入的第一个序列，即 input.data[0:4] 。 + 则得出的结果为[[0], [2], [1], [0]] + 2. 合并重复的索引值部分，删除空格，即为0的值。 + 则第一个输入序列对应的输出为：[[2], [1]] + + 最后 output.data = [[2], [1], @@ -2521,7 +2536,7 @@ A simple example as below: - **blank** (int) — Connectionist Temporal Classification (CTC) loss空白标签索引, 属于半开区间[0,num_classes + 1）。 - **name** (str) — 此层的名称。可选。 -返回： CTC贪婪解码结果。如果结果中的所有序列都为空，则LoDTensor 为[-1]，其中LoD[[]] dims[1,1]。 +返回： CTC贪婪解码结果是一个形为(Lp,1)的二维张量，其中Lp是所有输出序列的长度之和。如果结果中的所有序列都为空，则输出LoDTensor 为[-1]，其中LoD[[]] 形为[1,1]。 返回类型： 变量（Variable） @@ -2598,23 +2613,30 @@ dropout操作 丢弃或者保持x的每个元素独立。Dropout是一种正则化技术，通过在训练过程中阻止神经元节点间的联合适应性来减少过拟合。根据给定的丢弃概率dropout操作符随机将一些神经元输出设置为0，其他的仍保持不变。 参数： - - **x** Variable）-输入张量 + - **x** (Variable)-输入张量 - **dropout_prob** (float)-设置为0的单元的概率 - **is_test** (bool)-显示是否进行测试用语的标记 - **seed** (int)-Python整型，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。 - **name** (str|None)-该层名称（可选）。如果设置为None,则自动为该层命名 - - **dropout_implementation** (string)-[‘downgrade_in_infer’(defauld)|’upscale_in_train’] - 1.downgrade_in_infer(default), 在预测时减小输出结果 - train: out = input * mask - - inference: out = input * dropout_prob - (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为dropout_prob) - 2.upscale_in_train, 增加训练时的结果 - train: out = input * mask / ( 1.0 - dropout_prob ) - - inference: out = input - (make是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为dropout_prob） - dropout操作符可以从程序中移除，程序变得高效。 + - **dropout_implementation** (string) - [‘downgrade_in_infer’(defauld)|’upscale_in_train’] + 其中: + 1.downgrade_in_infer(default), 在预测时减小输出结果 + + train: out = input * mask + + inference: out = input * dropout_prob + + (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ) + + 2.upscale_in_train, 增加训练时的结果 + + train: out = input * mask / ( 1.0 - dropout_prob ) + + inference: out = input + + (make是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ） + +dropout操作符可以从程序中移除，程序变得高效。 返回：带有x维的张量 @@ -2698,7 +2720,7 @@ dynamic_gru emb = fluid.layers.embedding(input=data, size=[dict_dim, emb_dim]) hidden_dim = 512 x = fluid.layers.fc(input=emb, size=hidden_dim * 3) - hidden = fluid.layers.dynamic_gru(input=x, dim=hidden_dim) + hidden = fluid.layers.dynamic_gru(input=x, size=hidden_dim) @@ -2951,8 +2973,8 @@ edit_distance .. code-block:: python - x = fluid.layers.data(name='x', shape=[8], dtype='float32') - y = fluid.layers.data(name='y', shape=[7], dtype='float32') + x = fluid.layers.data(name='x', shape=[1], dtype='float32') + y = fluid.layers.data(name='y', shape=[1], dtype='float32') cost = fluid.layers.edit_distance(input=x,label=y) @@ -4038,23 +4060,41 @@ hash hsigmoid ------------------------------- -.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None) +.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None, path_table=None, path_code=None, is_custom=False, is_sparse=False) -层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完整的二叉树，每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。 +层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完全二叉树，也可以使用 ``is_custom`` 参数来传入自定义的树结构来实现层次化。 + +树中每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。 + +hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。 + +使用默认树结构，请参考 `Hierarchical Probabilistic Neural Network Language Model `_ 。 + +若要使用自定义树结构，请设置 ``is_custom`` 值为True。但在此之前，请完成以下几步部署： + +1.使用自定义词典来建立二叉树，每个叶结点都应该是词典中的单词 + +2.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径** 的映射，称之为路径表 ``path_table`` 参数 + +3.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径的编码(code)** 的映射。 编码code是指每次二分类的标签，1为真，0为假 + +4.现在我们的每个单词都已经有自己的路径和路径编码，当对于同一批输入进行操作时，你可以同时传入一批路径和路径编码进行运算。 -`请参考 Hierarchical Probabilistic Neural Network Language Model `_ - 参数: - **input** (Variable) - 输入张量，shape为 ``[N×D]`` ,其中 ``N`` 是minibatch的大小，D是特征大小。 - **label** (Variable) - 训练数据的标签。该tensor的shape为 ``[N×1]`` - - **num_classes** (int) - 类别的数量不能少于2 + - **num_classes** (int) - 类别的数量不能少于2。若使用默认树结构，该参数必须用户设置。当 ``is_custom=False`` 时，该项绝不能为None。反之，如果 ``is_custom=True`` ，它取值应为非叶节点的个数，来指明二分类实用的类别数目。 - **param_attr** (ParamAttr|None) - 可学习参数/ hsigmoid权重的参数属性。如果将其设置为ParamAttr的一个属性或None，则将ParamAttr设置为param_attr。如果没有设置param_attr的初始化器，那么使用用Xavier初始化。默认值:没None。 - **bias_attr** (ParamAttr|bool|None) - hsigmoid偏置的参数属性。如果设置为False，则不会向输出添加偏置。如果将其设置ParamAttr的一个属性或None，则将ParamAttr设置为bias_attr。如果没有设置bias_attr的初始化器，偏置将初始化为零。默认值:None。 - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名。默认值:None。 + - **path_table** (Variable|None) – 存储每一批样本从词到根节点的路径。路径应为从叶至根方向。 ``path_table`` 和 ``path_code`` 应具有相同的形, 对于每个样本 i ，path_table[i]为一个类似np.array的结构，该数组内的每个元素都是其双亲结点权重矩阵的索引 + - **path_code** (Variable|None) – 存储每批样本的路径编码，仍然是按从叶至根方向。各样本路径编码批都由其各祖先结点的路径编码组成 + - **is_custom** (bool|False) – 使用用户自定义二叉树取代默认二叉树结构，如果该项为真， 请务必设置 ``path_table`` , ``path_code`` , ``num_classes`` , 否则就需要设置 num_classes + - **is_sparse** (bool|False) – 使用稀疏更新方式，而非密集更新。如果为真， W的梯度和输入梯度将会变得稀疏 + +返回: (LoDTensor) 层次sigmod（ hierarchical sigmoid） 。shape[N, 1] - 返回: (Tensor) 层次sigmod（ hierarchical sigmoid） 。shape[N, 1] - - 返回类型: Out +返回类型: Out **代码示例** @@ -4065,7 +4105,7 @@ hsigmoid y = fluid.layers.data(name='y', shape=[1], dtype='int64') out = fluid.layers.hsigmoid(input=x, label=y, num_classes=6) - + @@ -5320,7 +5360,7 @@ multiplex **代码示例** .. code-block:: python - + import paddle.fluid as fluid x1 = fluid.layers.data(name='x1', shape=[4], dtype='float32') @@ -5342,7 +5382,7 @@ multiplex nce ------------------------------- -.. py:function:: paddle.fluid.layers.nce(input, label, num_total_functiones, sample_weight=None, param_attr=None, bias_attr=None, num_neg_samples=None, name=None) +.. py:function:: paddle.fluid.layers.nce(input, label, num_total_functiones, sample_weight=None, param_attr=None, bias_attr=None, num_neg_samples=None, name=None, sampler='uniform', custom_dist=None, seed=0, is_sparse=False) 计算并返回噪音对比估计（ noise-contrastive estimation training loss）。 `请参考 See Noise-contrastive estimation: A new estimation principle for unnormalized statistical models @@ -5350,14 +5390,18 @@ nce 该operator默认使用均匀分布进行抽样。 参数: - - **input** (Variable) - 特征 - - **label** (Variable) - 标签 - - **num_total_classes** (int) - 所有样本中的类别的总数 - - **sample_weight** (Variable|None) - 存储每个样本权重，shape为[batch_size, 1]存储每个样本的权重。每个样本的默认权重为1.0 - - **param_attr** (ParamAttr|None) - 可学习参数/ nce权重的参数属性。如果它没有被设置为ParamAttr的一个属性，nce将创建ParamAttr为param_attr。如没有设置param_attr的初始化器，那么参数将用Xavier初始化。默认值:None - - **bias_attr** (ParamAttr|bool|None) - nce偏置的参数属性。如果设置为False，则不会向输出添加偏置（bias）。如果值为None或ParamAttr的一个属性，则bias_attr=ParamAtt。如果没有设置bias_attr的初始化器，偏置将被初始化为零。默认值:None - - **num_neg_samples** (int) - 负样例的数量。默认值是10 - - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名 + - **input** (Variable) - 输入变量 + - **label** (Variable) - 标签 + - **num_total_classes** (int) - 所有样本中的类别的总数 + - **sample_weight** (Variable|None) - 存储每个样本权重，shape为[batch_size, 1]存储每个样本的权重。每个样本的默认权重为1.0 + - **param_attr** (ParamAttr|None) - :math:`可学习参数/nce权重` 的参数属性。如果它没有被设置为ParamAttr的一个属性，nce将创建ParamAttr为param_attr。如没有设置param_attr的初始化器，那么参数将用Xavier初始化。默认值:None + - **bias_attr** (ParamAttr|bool|None) - nce偏置的参数属性。如果设置为False，则不会向输出添加偏置（bias）。如果值为None或ParamAttr的一个属性，则bias_attr=ParamAtt。如果没有设置bias_attr的初始化器，偏置将被初始化为零。默认值:None + - **num_neg_samples** (int) - 负样例的数量。默认值是10 + - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名 + - **sampler** (str) – 取样器，用于从负类别中进行取样。可以是 ‘uniform’, ‘log_uniform’ 或 ‘custom_dist’。 默认 ‘uniform’ + - **custom_dist** (float[]) – 一个 float[] 并且它的长度为 ``num_total_classes`` 。 如果取样器类别为‘custom_dist’，则使用此参数。 custom_dist[i] 是第i个类别被取样的概率。默认为 None + - **seed** (int) – 取样器使用的seed。默认为0 + - **is_sparse** (bool) – 标志位，指明是否使用稀疏更新, :math:`weight@GRAD` 和 :math:`bias@GRAD` 会变为 SelectedRows 返回： nce loss @@ -5368,28 +5412,37 @@ nce .. code-block:: python - window_size = 5 - words = [] - for i in xrange(window_size): - words.append(layers.data( - name='word_{0}'.format(i), shape=[1], dtype='int64')) + window_size = 5 + words = [] + for i in xrange(window_size): + words.append(layers.data( + name='word_{0}'.format(i), shape=[1], dtype='int64')) + + dict_size = 10000 + label_word = int(window_size / 2) + 1 - dict_size = 10000 - label_word = int(window_size / 2) + 1 + embs = [] + for i in xrange(window_size): + if i == label_word: + continue - embs = [] - for i in xrange(window_size): - if i == label_word: - continue + emb = layers.embedding(input=words[i], size=[dict_size, 32], + param_attr='emb.w', is_sparse=True) + embs.append(emb) - emb = layers.embedding(input=words[i], size=[dict_size, 32], - param_attr='emb.w', is_sparse=True) - embs.append(emb) + embs = layers.concat(input=embs, axis=1) + loss = layers.nce(input=embs, label=words[label_word], + num_total_classes=dict_size, param_attr='nce.w', + bias_attr='nce.b') - embs = layers.concat(input=embs, axis=1) - loss = layers.nce(input=embs, label=words[label_word], - num_total_classes=dict_size, param_attr='nce.w', - bias_attr='nce.b') + #使用custom distribution + dist = fluid.layers.assign(input=np.array([0.05,0.5,0.1,0.3,0.05]).astype("float32")) + loss = layers.nce(input=embs, label=words[label_word], + num_total_classes=5, param_attr='nce.w', + bias_attr='nce.b', + num_neg_samples=3, + sampler="custom_dist", + custom_dist=dist) @@ -5625,7 +5678,7 @@ pad_constant_like pool2d ------------------------------- -.. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None) +.. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None, exclusive=True) pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` , 步长 ``pool_stride`` ，填充 ``pool_padding`` 这些参数得到输出。 @@ -5636,10 +5689,10 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核 例如： 输入： - X shape：:math:`\left ( N,C_{in},H_{in},W_{in} \right )` + X shape：:math:`\left ( N,C,H_{in},W_{in} \right )` 输出： - Out shape：:math:`\left ( N,C_{out},H_{out},W_{out} \right )` + Out shape：:math:`\left ( N,C,H_{out},W_{out} \right )` 如果 ``ceil_mode`` = false： @@ -5672,21 +5725,22 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核 hstart &= max(0, i * strides[0] - paddings[0])\\ hend &= min(H, hstart + ksize[0]) \\ wstart &= max(0, j * strides[1] - paddings[1]) \\ - wend & = min(W, wstart + ksize[1]) Output(i ,j) \\ - & = \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)} + wend & = min(W, wstart + ksize[1]) \\ + Output(i ,j) & = \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)} 参数： - **input** (Variable) - 池化操作的输入张量。输入张量格式为NCHW，N为批尺寸，C是通道数，H是特征高度，W是特征宽度 - - **pool_size** (int) - 池化窗口的边长。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。 + - **pool_size** (int|list|tuple) - 池化窗口的大小。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。 - **pool_type** (string) - 池化类型，可以是“max”对应max-pooling，“avg”对应average-pooling - - **pool_stride** (int) - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。 - - **pool_padding** (int) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。 - - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true，ksize和填充（padding）则被忽略 + - **pool_stride** (int|list|tuple) - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。 + - **pool_padding** (int|list|tuple) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。 + - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true， ``pool_size`` 和 ``pool_padding`` 将被忽略。 - **use_cudnn** （bool，默认false）- 只在cudnn核中用，需要下载cudnn - **ceil_mode** （bool，默认false）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数 - **name** （str|None） - 该层名称（可选）。若设为None，则自动为该层命名。 + - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。 返回：池化结果 @@ -5723,20 +5777,21 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核 pool3d ------------------------------- -.. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None) +.. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None， exclusive=True) 函数使用上述输入参数的池化配置，为三维空间添加池化操作 参数： - - **input** (Vairable) - 池化的输入张量。输入张量的格式为NCHW, N是批尺寸，C是通道数，N是特征高度，W是特征宽度。 - - **pool_size** (int) - 池化窗口的边长。所有对池化窗口都是正方形，边长为pool_size。 - - **pool_type** (str) - 池化类型，``ma``对应max-pooling,``avg``对应average-pooling。 - - **pool_stride** (int) - 跨越步长 - - **pool_padding** (int) - 填充大小 - - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true,ksize and paddings将被忽略。 - - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效 + - **input** (Vairable) - 池化运算的输入张量。输入张量的格式为NCDHW, N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。 + - **pool_size** (int|list|tuple) - 池化窗口的大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 + - **pool_type** (str) - 池化类型， "max" 对应max-pooling, "avg" 对应average-pooling。 + - **pool_stride** (int|list|tuple) - 池化跨越步长。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 + - **pool_padding** (int|list|tuple) - 填充大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。 + - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true, ``pool_size`` 和 ``pool_padding`` 将被忽略。 + - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效。 - **ceil_mode** (bool) - 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。 - **name** (str) - 该层名称（可选）。若为空，则自动为该层命名。 + - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。 返回：pool3d层的输出 @@ -5880,7 +5935,7 @@ P 的取值可为： {0, 1} 或 {0, 0.5, 1}, 其中，0.5表示输入的两文 **代码示例** .. code-block:: python - + theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32") out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32") data = fluid.layers.affine_grid(theta, out_shape) @@ -6412,7 +6467,7 @@ Faster-RCNN.使用了roi池化。roi关于roi池化请参考 https://stackoverfl **代码示例** .. code-block:: python - + pool_out = fluid.layers。roi_pool(输入=x, rois=rois, 7,7,1.0) @@ -7002,7 +7057,7 @@ sequence_mask sequence_pad ------------------------------- -.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=None) +.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=None,name=None) 序列填充操作符（Sequence Pad Operator） @@ -7012,7 +7067,6 @@ sequence_pad :: - 例1: 给定 1-level LoDTensor @@ -7029,6 +7083,8 @@ sequence_pad Out.data = [[a,b,0,0],[c,d,e,0]] Length.data = [[2],[3]] +:: + 例2: 给定 1-level LoDTensor @@ -7045,6 +7101,9 @@ sequence_pad Out.data = [[[a1,a2],[b1,b2],[0,0]],[[c1,c2],[d1,d2],[e1,e2]]] Length.data = [[2],[3]] + +:: + 例3: 给定 1-level LoDTensor @@ -7061,12 +7120,14 @@ sequence_pad Out.data = [[[a1,a2],[b1,b2],[p1,p2]],[[c1,c2],[d1,d2],[e1,e2]]] Length.data = [[2],[3]] + 参数： - **x** (Vairable) - 输入变量，应包含lod信息 - **pad_value** (Variable) - 变量，存有放入填充步的值。可以是标量或tensor,维度和序列的时间步长相等。如果是标量,则自动广播到时间步长的维度 - **maxlen** (int,默认None) - 填充序列的长度。可以为空或者任意正整数。当为空时，以序列中最长序列的长度为准，其他所有序列填充至该长度。当是某个特定的正整数，最大长度必须大于最长初始序列的长度 + - **name** (str|None) – 该层的命名(可选项)。 如果为 None, 则自动命名 -返回：填充序列批（batch）和填充前的初始长度。所有序列的长度相等 +返回：填充序列批（batch）和填充前的初始长度。所有输出序列的长度相等 返回类型：变量（Variable） @@ -7077,8 +7138,9 @@ sequence_pad import numpy x = fluid.layers.data(name='y', shape=[10, 5], - dtype='float32', lod_level=1) - pad_value = fluid.layers.assign(input=numpy.array([0])) + dtype='float32', lod_level=1) + pad_value = fluid.layers.assign( + input=numpy.array([0.0], dtype=numpy.float32)) out = fluid.layers.sequence_pad(x=x, pad_value=pad_value) @@ -7094,7 +7156,7 @@ sequence_pad sequence_pool ------------------------------- -.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type) +.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type, is_test=False) 该函数为序列的池化添加操作符。将每个实例的所有时间步数特征池化，并用参数中提到的pool_type将特征运用到输入到首部。 @@ -7127,6 +7189,7 @@ sequence_pool 参数： - **input** (variable) - 输入变量，为LoDTensor - **pool_type** (string) - 池化类型。支持average,sum,sqrt和max + - **is_test** (bool, 默认为 False) - 用于区分训练模式和测试评分模式 返回：sequence pooling 变量，类型为张量（Tensor) @@ -7215,7 +7278,7 @@ sequence_reverse 在第0维上将输入 ``x`` 的各序列倒序。 :: - + 假设 ``x`` 是一个形为 (5,4) 的LoDTensor， lod信息为 [[0, 2, 5]]，其中， @@ -7226,7 +7289,7 @@ sequence_reverse 输出 ``Y`` 与 ``x`` 具有同样的维数和LoD信息。 于是有： :: - + Y.data() = [ [5, 6, 7, 8], [1, 2, 3, 4], # 索引为0，长度为2的逆序列 [17, 18, 19, 20], [13, 14, 15, 16], [9, 10, 11, 12] # 索引为1，长度为3的逆序列 @@ -7816,7 +7879,7 @@ softmax操作符计算k维向量输入中所有其他维的指数和指数值的 softmax_with_cross_entropy ------------------------------- -.. py:function:: paddle.fluid.layers.softmax_with_cross_entropy(logits, label, soft_label=False, ignore_index=-100) +.. py:function:: paddle.fluid.layers.softmax_with_cross_entropy(logits, label, soft_label=False, ignore_index=-100, numeric_stable_mode=False, return_softmax=False) 使用softmax的交叉熵在输出层已被广泛使用。该函数计算输入张量每一行的softmax标准化值，而后计算交叉熵。通过此种方式，可以得到更具数字稳定性的梯度值。 @@ -7835,17 +7898,28 @@ softmax_with_cross_entropy .. math:: loss_j = -\sum_{i=0}^{K}\text{label}_i\left(\text{logit}_i - \log\left(\sum_{i=0}^{K}\exp(\text{logit}_i)\right)\right), j = 1,...,K - - + +3.如果 ``numeric_stable_mode`` 为真，在通过softmax和标签计算交叉熵损失前， softmax 首先经由下式计算得出： + +.. math:: + max_j &= \max_{i=0}^{K}{\text{logit}_i} \\ + log\_max\_sum_j &= \log\sum_{i=0}^{K}\exp(logit_i - max_j)\\ + softmax_j &= \exp(logit_j - max_j - {log\_max\_sum}_j) + + 参数: - **logits** (Variable) - 未标准化(unscaled)的log概率,一个形为 N X K 的二维张量。 N是batch大小，K是类别总数 - **label** (Variable) - 2-D 张量，代表了正确标注（ground truth）, 如果 ``soft_label`` 为 False，则该参数是一个形为 N X 1 的Tensor 。如果 ``soft_label`` 为 True，它是 Tensor ，形为 N X K - **soft_label** (bool) - 是否将输入标签当作软标签。默认为False - **ignore_index** (int) - 指明要无视的目标值，使之不对输入梯度有贡献。仅在 ``soft_label`` 为False时有效，默认为-100 + - **numeric_stable_mode** (bool) – 标志位，指明是否使用一个具有更佳数学稳定性的算法。仅在 ``soft_label`` 为 False的GPU模式下生效. 若 ``soft_label`` 为 True 或者执行场所为CPU, 算法一直具有数学稳定性。 注意使用稳定算法时速度可能会变慢。默认为 False + - **return_softmax** (bool) – 标志位，指明是否额外返回一个softmax值， 同时返回交叉熵计算结果。默认为False -返回： 交叉熵，一个形为[N x 1]的二维张量 +返回: + - 如果 ``return_softmax`` 为 False， 则返回交叉熵，一个形为[N x 1]的二维张量 + - 如果 ``return_softmax`` 为 True，则返回元组 (loss, softmax) ，其中交叉熵loss为形为[N x 1]的二维张量，softmax为[N x K]的二维张量 -返回类型: Variable +返回类型:变量或者两个变量组成的元组 **代码示例** @@ -8260,7 +8334,10 @@ transpose .. code-block:: python - x = fluid.layers.data(name='x', shape=[5, 10, 15], dtype='float32') + # 请使用 append_batch_size=False 来避免 + # 在数据张量中添加多余的batch大小维度 + x = fluid.layers.data(name='x', shape=[5, 10, 15], + dtype='float32', append_batch_size=False) x_transposed = layers.transpose(x, perm=[1, 0, 2]) @@ -9489,22 +9566,22 @@ reverse ------------------------------- .. py:function:: paddle.fluid.layers.reverse(x,axis) - - **reverse** - - 该功能将给定轴上的输入‘x’逆序 - 参数： - - **x** (Variable)-预逆序到输入 - - **axis** (int|tuple|list)-其上元素逆序排列的轴。 - - 返回：逆序的张量 +**reverse** - 返回类型：变量（Variable） +该功能将给定轴上的输入‘x’逆序 - **代码示例**： +参数： + - **x** (Variable)-预逆序到输入 + - **axis** (int|tuple|list)-其上元素逆序排列的轴。 - .. code-block:: python +返回：逆序的张量 + +返回类型：变量（Variable） + +**代码示例**： + +.. code-block:: python out = fluid.layers.reverse(x=in, axis=0) # or: @@ -9634,6 +9711,7 @@ zeros **代码示例**： .. code-block:: python + data = fluid.layers.zeros(shape=[1], dtype='int64') @@ -9660,12 +9738,7 @@ append_LARS 对每一层的学习率运用LARS(LAYER-WISE ADAPTIVE RATE SCALING) -.. code-block python - - .. math:: - learning_rate*=local_gw_ratio * sqrt(sumsq(param)) - / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param))) 参数： - **learning_rate** -变量学习率。LARS的全局学习率。 @@ -9673,7 +9746,12 @@ append_LARS 返回： 衰减的学习率 +**代码示例** : +.. code-block:: python + + learning_rate*=local_gw_ratio * sqrt(sumsq(param)) + / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param))) @@ -10355,9 +10433,9 @@ generate_proposals .. py:function:: paddle.fluid.layers.generate_proposals(scores, bbox_deltas, im_info, anchors, variances, pre_nms_top_n=6000, post_nms_top_n=1000, nms_thresh=0.5, min_size=0.1, eta=1.0, name=None) -生成proposal标签的Faster-RCNN +生成proposal的Faster-RCNN -该操作根据每个框的概率为foreground对象，并且可以通过锚（anchors）来计算框来产生RoI。Bbox_deltais和一个objects的分数作为是RPN的输出。最终 ``proposals`` 可用于训练检测网络。 +该操作根据每个框为foreground（前景）对象的概率，并且通过锚（anchors）来计算这些框，进而提出RoI。Bbox_deltais和一个objects的分数作为是RPN的输出。最终 ``proposals`` 可用于训练检测网络。 为了生成 ``proposals`` ，此操作执行以下步骤： @@ -10406,7 +10484,6 @@ iou_similarity 计算两个框列表的intersection-over-union(IOU)。框列表‘X’应为LoDTensor，‘Y’是普通张量，X成批输入的所有实例共享‘Y’中的框。给定框A和框B，IOU的运算如下： .. math:: - IOU(A, B) = \frac{area(A\cap B)}{area(A)+area(B)-area(A\cap B)} 参数： @@ -10629,11 +10706,11 @@ rpn_target_assign 对于给定anchors和真实框之间的IoU重叠，该层可以为每个anchors做分类和回归，这些target labels用于训练RPN。classification targets是二进制的类标签（是或不是对象）。根据Faster-RCNN的论文，positive labels有两种anchors： - （i）anchor/anchors与真实框具有最高IoU重叠； - - （ii）具有IoU重叠的anchors高于带有任何真实框（ground-truth box）的rpn_positive_overlap0（0.7）。 - - 请注意，单个真实框（ground-truth box）可以为多个anchors分配正标签。对于所有真实框（ground-truth box），非正向锚是指其IoU比率低于rpn_negative_overlap（0.3）。既不是正也不是负的anchors对训练目标没有价值。回归目标是与positive anchors相关联而编码的图片真实框。 +(i) anchor/anchors与真实框具有最高IoU重叠； + +(ii) 具有IoU重叠的anchors高于带有任何真实框（ground-truth box）的rpn_positive_overlap0（0.7）。 + +请注意，单个真实框（ground-truth box）可以为多个anchors分配正标签。对于所有真实框（ground-truth box），非正向锚是指其IoU比率低于rpn_negative_overlap（0.3）。既不是正也不是负的anchors对训练目标没有价值。回归目标是与positive anchors相关联而编码的图片真实框。 参数： - **bbox_pred** （Variable）- 是一个shape为[N，M，4]的3-D Tensor，表示M个边界框的预测位置。N是批量大小，每个边界框有四个坐标值，即[xmin，ymin，xmax，ymax]。 @@ -10649,7 +10726,13 @@ rpn_target_assign - **rpn_positive_overlap** （float）- 对于一个正例的（anchor, gt box）对，是允许anchors和所有真实框之间最小重叠的。 - **rpn_negative_overlap** （float）- 对于一个反例的（anchor, gt box）对，是允许anchors和所有真实框之间最大重叠的。 -返回： 返回元组（predict_scores，predict_location，target_label，target_bbox）。predict_scores和predict_location是RPN的预测结果。 target_label和target_bbox分别是ground-truth。 predict_location是一个shape为[F，4]的2D Tensor， ``target_bbox`` 的shape与 ``predict_location`` 的shape相同，F是foreground anchors的数量。 ``predict_scores`` 是一个shape为[F + B，1]的2D Tensor， ``target_label`` 的shape与 ``predict_scores`` 的shape相同，B是background anchors的数量，F和B取决于此算子的输入。 +返回: + +返回元组 (predicted_scores, predicted_location, target_label, target_bbox, bbox_inside_weight) : + - **predicted_scores** 和 **predicted_location** 是RPN的预测结果。 **target_label** 和 **target_bbox** 分别是真实准确数据(ground-truth)。 + - **predicted_location** 是一个形为[F，4]的2D Tensor， **target_bbox** 的形与 **predicted_location** 相同，F是foreground anchors的数量。 + - **predicted_scores** 是一个shape为[F + B，1]的2D Tensor， **target_label** 的形与 **predict_scores** 的形相同，B是background anchors的数量，F和B取决于此算子的输入。 + - **Bbox_inside_weight** 标志着predicted_loction是否为fake_fg（假前景），其形为[F,4]。 返回类型： 元组(tuple) @@ -10666,7 +10749,7 @@ rpn_target_assign append_batch_size=False, dtype=’float32’) gt_boxes = layers.data(name=’gt_boxes’, shape=[10, 4], append_batch_size=False, dtype=’float32’) - loc_pred, score_pred, loc_target, score_target = + loc_pred, score_pred, loc_target, score_target, bbox_inside_weight= fluid.layers.rpn_target_assign(bbox_pred=bbox_pred, cls_logits=cls_logits, anchor_box=anchor_box, gt_boxes=gt_boxes) @@ -10900,8 +10983,9 @@ auc 有两种可能的曲线： - 1. ROC:受试者工作特征曲线 - 2. PR:准确率召回率曲线 +1. ROC:受试者工作特征曲线 + +2. PR:准确率召回率曲线 参数： - **input** (Variable) - 浮点二维变量，值的范围为[0,1]。每一行降序排列。输入应为topk的输出。该变量显示了每个标签的概率。 @@ -10919,7 +11003,7 @@ auc .. code-block:: python - # network is a binary classification model and label the ground truth + # network为二分类模型, label为ground truth（正确标记） prediction = network(image, is_infer=True) auc_out=fluid.layers.auc(input=prediction, label=label)