From 90d697708ea1e040bedb8e0e2cb1dd447d5dd8fc Mon Sep 17 00:00:00 2001 From: Xing Wu <1160386409@qq.com> Date: Wed, 16 Oct 2019 14:09:53 +0800 Subject: [PATCH] add new seq2seq api_cn, test=document_preview (#1489) * add new seq2seq api_cn, test=document_preview * add seq2seq api_cn, test=document_preview * add seq2seq api_cn, test=document_preview --- doc/fluid/api_cn/layers_cn.rst | 7 + .../api_cn/layers_cn/BeamSearchDecoder_cn.rst | 174 ++++++++++++++++++ doc/fluid/api_cn/layers_cn/Decoder_cn.rst | 47 +++++ doc/fluid/api_cn/layers_cn/GRUCell_cn.rst | 61 ++++++ doc/fluid/api_cn/layers_cn/LSTMCell_cn.rst | 62 +++++++ doc/fluid/api_cn/layers_cn/RNNCell_cn.rst | 44 +++++ .../api_cn/layers_cn/dynamic_decode_cn.rst | 50 +++++ doc/fluid/api_cn/layers_cn/rnn_cn.rst | 35 ++++ 8 files changed, 480 insertions(+) create mode 100644 doc/fluid/api_cn/layers_cn/BeamSearchDecoder_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn/Decoder_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn/GRUCell_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn/LSTMCell_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn/RNNCell_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn/dynamic_decode_cn.rst create mode 100644 doc/fluid/api_cn/layers_cn/rnn_cn.rst diff --git a/doc/fluid/api_cn/layers_cn.rst b/doc/fluid/api_cn/layers_cn.rst index 989f6560d..44df24262 100644 --- a/doc/fluid/api_cn/layers_cn.rst +++ b/doc/fluid/api_cn/layers_cn.rst @@ -40,6 +40,7 @@ fluid.layers layers_cn/box_decoder_and_assign_cn.rst layers_cn/bpr_loss_cn.rst layers_cn/brelu_cn.rst + layers_cn/BeamSearchDecoder_cn.rst layers_cn/cast_cn.rst layers_cn/ceil_cn.rst layers_cn/center_loss_cn.rst @@ -82,6 +83,8 @@ fluid.layers layers_cn/dynamic_gru_cn.rst layers_cn/dynamic_lstm_cn.rst layers_cn/dynamic_lstmp_cn.rst + layers_cn/dynamic_decode_cn.rst + layers_cn/Decoder_cn.rst layers_cn/DynamicRNN_cn.rst layers_cn/edit_distance_cn.rst layers_cn/elementwise_add_cn.rst @@ -120,6 +123,7 @@ fluid.layers layers_cn/grid_sampler_cn.rst layers_cn/group_norm_cn.rst layers_cn/gru_unit_cn.rst + layers_cn/GRUCell_cn.rst layers_cn/hard_shrink_cn.rst layers_cn/hard_sigmoid_cn.rst layers_cn/hard_swish_cn.rst @@ -161,6 +165,7 @@ fluid.layers layers_cn/lrn_cn.rst layers_cn/lstm_cn.rst layers_cn/lstm_unit_cn.rst + layers_cn/LSTMCell_cn.rst layers_cn/margin_rank_loss_cn.rst layers_cn/matmul_cn.rst layers_cn/maxout_cn.rst @@ -219,6 +224,7 @@ fluid.layers layers_cn/retinanet_detection_output_cn.rst layers_cn/retinanet_target_assign_cn.rst layers_cn/reverse_cn.rst + layers_cn/rnn_cn.rst layers_cn/roi_align_cn.rst layers_cn/roi_perspective_transform_cn.rst layers_cn/roi_pool_cn.rst @@ -226,6 +232,7 @@ fluid.layers layers_cn/row_conv_cn.rst layers_cn/rpn_target_assign_cn.rst layers_cn/rsqrt_cn.rst + layers_cn/RNNCell_cn.rst layers_cn/sampled_softmax_with_cross_entropy_cn.rst layers_cn/sampling_id_cn.rst layers_cn/scale_cn.rst diff --git a/doc/fluid/api_cn/layers_cn/BeamSearchDecoder_cn.rst b/doc/fluid/api_cn/layers_cn/BeamSearchDecoder_cn.rst new file mode 100644 index 000000000..43c9dd6cf --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/BeamSearchDecoder_cn.rst @@ -0,0 +1,174 @@ +.. _cn_api_fluid_layers_BeamSearchDecoder: + +BeamSearchDecoder +------------------------------- + + +.. py:class:: paddle.fluid.layers.BeamSearchDecoder(cell, start_token, end_token, beam_size, embedding_fn=None, output_fn=None) + +带beam search解码策略的解码器。该接口包装一个cell来计算概率，然后执行一个beam search步骤计算得分，并为每个解码步骤选择候选输出。更多详细信息请参阅 `Beam search `_ + +**注意** 在使用beam search解码时，cell的输入和状态将被扩展到 :math:`beam\_size` ，得到 :math:`[batch\_size * beam\_size, ...]` 一样的形状，这个操作在BeamSearchDecoder中自动完成，因此，其他任何在 :code:`cell.call` 中使用的tensor，如果形状为 :math:`[batch\_size, ...]` ，都必须先手动使用 :code:`BeamSearchDecoder.tile_beam_merge_with_batch` 接口扩展。最常见的情况是带注意机制的编码器输出。 + +参数： + - **cell** (RNNCell) - RNNCell的实例或者具有相同接口定义的对象。 + - **start_token** (int) - 起始标记id。 + - **end_token** (int) - 结束标记id。 + - **beam_size** (int) - 在beam search中使用的beam宽度。 + - **embedding_fn** (可选) - 处理选中的候选id的接口。通常，它是一个将词id转换为词嵌入的嵌入层，函数的返回值作为 :code:`cell.call` 接口的 :code:`input` 参数。如果 :code:`embedding_fn` 未提供，则必须在 :code:`cell.call` 中实现词嵌入转换。默认值None。 + - **output_fn** (可选) - 处理cell输出的接口，在计算得分和选择候选标记id之前使用。默认值None。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + from paddle.fluid.layers import GRUCell, BeamSearchDecoder + trg_embeder = lambda x: fluid.embedding( + x, size=[10000, 128], param_attr=fluid.ParamAttr(name="trg_embedding")) + output_layer = lambda x: layers.fc(x, + size=10000, + num_flatten_dims=len(x.shape) - 1, + param_attr=fluid.ParamAttr(name= + "output_w"), + bias_attr=False) + decoder_cell = GRUCell(hidden_size=128) + decoder = BeamSearchDecoder(decoder_cell, + start_token=0, + end_token=1, + beam_size=4, + embedding_fn=trg_embeder, + output_fn=output_layer) + + +.. py:method:: tile_beam_merge_with_batch(x, beam_size) + +扩展tensor的batch维度。此函数的输入是形状为 :math:`[batch\_size, s_0, s_1, ...]` 的tensor t，由minibatch中的样本 :math:`t[0], ..., t[batch\_size - 1]` 组成。将其扩展为形状是 :math:`[batch\_size * beam\_size, s_0, s_1, ...]` 的tensor，由 :math:`t[0], t[0], ..., t[1], t[1], ...` 组成, 每个minibatch中的样本重复 :math:`beam\_size` 次。 + +参数： + - **x** (Variable) - 形状为 :math:`[batch\_size, ...]` 的tenosr。数据类型应为float32，float64，int32，int64或bool。 + - **beam_size** (int) - 在beam search中使用的beam宽度。 + +返回：形状为 :math:`[batch\_size * beam\_size, ...]` 的tensor，其数据类型与 :code:`x` 相同。 + +返回类型：Variable + +.. py:method:: _split_batch_beams(x) + +将形状为 :math:`[batch\_size * beam\_size, ...]` 的tensor变换为形状为 :math:`[batch\_size, beam\_size, ...]` 的新tensor。 + +参数： + - **x** (Variable) - 形状为 :math:`[batch\_size * beam\_size, ...]` 的tenosr。数据类型应为float32，float64，int32，int64或bool。 + +返回：形状为 :math:`[batch\_size, beam\_size, ...]` 的tensor，其数据类型与 :code:`x` 相同。 + +返回类型：Variable + +.. py:method:: _merge_batch_beams(x) + +将形状为 :math:`[batch\_size, beam\_size, ...]` 的tensor变换为形状为 :math:`[batch\_size * beam\_size,...]` 的新tensor。 + +参数： + - **x** (Variable) - 形状为 :math:`[batch\_size, beam_size,...]` 的tenosr。数据类型应为float32，float64，int32，int64或bool。 + +返回：形状为 :math:`[batch\_size * beam\_size, ...]` 的tensor，其数据类型与 :code:`x` 相同。 + +返回类型：Variable + +.. py:method:: _expand_to_beam_size(x) + +此函数输入形状为 :math:`[batch\_size,s_0，s_1，...]` 的tensor t，由minibatch中的样本 :math:`t[0]，...，t[batch\_size-1]` 组成。将其扩展为形状 :math:`[ batch\_size,beam\_size,s_0，s_1，...]` 的tensor，由 :math:`t[0]，t[0]，...，t[1]，t[1]，...` 组成，其中每个minibatch中的样本重复 :math:`beam\_size` 次。 + +参数： + - **probs** (Variable) - 形状为 :math:`[batch\_size,beam\_size,vocab\_size]` 的tensor，表示对数概率。其数据类型应为float32。 + - **finish** (Variable) - 形状为 :math:`[batch\_size,beam\_size]` 的tensor，表示所有beam的完成状态。其数据类型应为bool。 + +返回：具有与 :code:`x` 相同的形状和数据类型的tensor，其中未完成的beam保持不变，而已完成的beam被替换成特殊的tensor(tensor中所有概率质量被分配给EOS标记)。 + +返回类型：Variable + +.. py:method:: _mask_probs(probs, finished) + +屏蔽对数概率。该函数使已完成的beam将所有概率质量分配给EOS标记，而未完成的beam保持不变。 + +参数： + - **probs** (Variable) - 形状为 :math:`[batch\_size,beam\_size,vocab\_size]` 的tensor，表示对数概率。其数据类型应为float32。 + - **finish** (Variable) - 形状为 :math:`[batch\_size,beam\_size]` 的tensor，表示所有beam的完成状态。其数据类型应为bool。 + +返回：具有与 :code:`x` 相同的形状和数据类型的tensor，其中未完成的beam保持不变，而已完成的beam被替换成特殊的tensor(tensor中所有概率质量被分配给EOS标记)。 + +返回类型：Variable + +.. py:method:: _gather(x, indices, batch_size) + +对tensor :code:`x` 根据索引 :code:`indices` 收集。 + +参数： + - **x** (Variable) - 形状为 :math:`[batch\_size, beam\_size,...]` 的tensor。 + - **index** (Variable) - 一个形状为 :math:`[batch\_size, beam\_size]` 的int64 tensor，表示我们用来收集的索引。 + - **batch_size** (Variable) - 形状为 :math:`[1]` 的tensor。其数据类型应为int32或int64。 + +返回：具有与 :code:``x` 相同的形状和数据类型的tensor，表示收集后的tensor。 + +返回类型：Variable + +.. py:method:: initialize(initial_cell_states) + +初始化BeamSearchDecoder。 + +参数： + - **initial_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。调用者提供的参数。 + +返回：一个元组 :code:`(initial_inputs, initial_states, finished)`。:code:`initial_inputs` 是一个tensor，当 :code:`embedding_fn` 为None时，由 :code:`start_token` 填充，形状为 :math:`[batch\_size,beam\_size,1]` ；否则使用 :code:`embedding_fn(t)` 返回的值。:code:`initial_states` 是tensor变量的嵌套结构(命名元组，字段包括 :code:`cell_states，log_probs，finished，lengths`)，其中 :code:`log_probs，finished，lengths` 都含有一个tensor，形状为 :math:`[batch\_size, beam\_size]`，数据类型为float32，bool，int64。:code:`cell_states` 具有与输入参数 :code:`initial_cell_states` 相同结构的值，但形状扩展为 :math:`[batch\_size,beam\_size,...]`。 :code:`finished` 是一个布尔型tensor，由False填充，形状为 :math:`[batch\_size,beam\_size]`。 + +返回类型：tuple + +.. py:method:: _beam_search_step(time, logits, next_cell_states, beam_state) + +计算得分并选择候选id。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的tensor，表示当前解码的时间步长。其数据类型为int64。 + - **logits** (Variable) - 形状为 :math:`[batch\_size,beam\_size,vocab\_size]` 的tensor，表示当前时间步的logits。其数据类型为float32。 + - **next_cell_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。它的结构，形状和数据类型与 :code:`initialize()` 的返回值 :code:`initial_states` 中的 :code:`cell_states` 相同。它代表该cell的下一个状态。 + - **beam_state** (Variable) - tensor变量的结构。在第一个解码步骤与 :code:`initialize()` 返回的 :code:`initial_states` 同，其他步骤与 :code:`initialize()` 返回的 :code:`beam_search_state` 相同。 + +返回：一个元组 :code:`(beam_search_output, beam_search_state)`。:code:`beam_search_output` 是tensor变量的命名元组，字段为 :code:`scores，predicted_ids parent_ids`。其中 :code:`scores，predicted_ids，parent_ids` 都含有一个tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为float32 ，int64，int64。:code:`beam_search_state` 具有与输入参数 :code:`beam_state` 相同的结构，形状和数据类型。 + +返回类型：tuple + +.. py:method:: step(time, inputs, states, **kwargs) + +执行beam search解码步骤，该步骤使用 :code:`cell` 来计算概率，然后执行beam search步骤以计算得分并选择候选标记ID。 + +参数： + - **time** (Variable) - 调用者提供的形状为[1]的int64tensor，表示当前解码的时间步长。 + - **inputs** (Variable) - tensor变量。在第一个解码时间步时与由 :code:`initialize()` 返回的 :code:`initial_inputs` 相同，其他时间步与由 :code:`step()` 返回的 :code:`next_inputs` 相同。 + - **States** (Variable) - tensor变量的结构。在第一个解码时间步时与 :code:`initialize()` 返回的 :code:`initial_states` 相同，其他时间步与由 :code:`step()` 返回的 :code:`beam_search_state` 相同。 + - **kwargs** - 附加的关键字参数，由调用者提供。 + +返回：一个元组 :code:`(beam_search_output，beam_search_state，next_inputs，finish)` 。:code:`beam_search_state` 和参数 :code:`states` 具有相同的结构，形状和数据类型。 :code:`next_inputs` 与输入参数 :code:`inputs` 具有相同的结构，形状和数据类型。 :code:`beam_search_output` 是tensor变量的命名元组(字段包括 :code:`scores，predicted_ids，parent_ids` )，其中 :code:`scores，predicted_ids，parent_ids` 都含有一个tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为float32 ，int64，int64。:code:`finished` 是一个bool类型的tensor，形状为 :math:`[batch\_size,beam\_size]`。 + +返回类型：tuple + +.. py:method:: finalize(outputs, final_states, sequence_lengths) + +使用 :code:`gather_tree` 沿beam search树回溯并构建完整的预测序列。 + +参数： + - **outputs** (Variable) - tensor变量组成的结构(命名元组)，该结构和数据类型与 :code:`output_dtype` 相同。tensor将所有时间步的输出堆叠，因此具有形状 :math:`[time\_step，batch\_size,...]`。 + - **final_states** (Variable) - tensor变量组成的结构(命名元组)。它是 :code:`decoder.step` 在最后一个解码步骤返回的 :code:`next_states`，因此具有与任何时间步的 :code:`state` 相同的结构、形状和数据类型。 + - **sequence_lengths** (Variable) - tensor，形状为 :math:`[batch\_size,beam\_size]`，数据类型为int64。它包含解码期间确定的每个beam的序列长度。 + +返回：一个元组 :code:`(predicted_ids, final_states)`。:code:`predicted_ids` 是一个tensor，形状为 :math:`[time\_step，batch\_size,beam\_size]`，数据类型为int64。:code:`final_states` 与输入参数 :code:`final_states` 相同。 + +返回类型：tuple + +.. py:method:: output_dtype() + +用于beam search输出的数据类型的嵌套结构。它是一个命名元组，字段包括 :code:`scores, predicted_ids, parent_ids`。 + +参数：无。 + +返回：用于beam search输出的数据类型的命名元组。 + diff --git a/doc/fluid/api_cn/layers_cn/Decoder_cn.rst b/doc/fluid/api_cn/layers_cn/Decoder_cn.rst new file mode 100644 index 000000000..feb0c4452 --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/Decoder_cn.rst @@ -0,0 +1,47 @@ +.. _cn_api_fluid_layers_Decoder: + +Decoder +------------------------------- + + +.. py:class:: paddle.fluid.layers.Decoder() + + +Decoder是dynamic_decode中使用的任何decoder实例的基类。它提供了为每一个时间步生成输出的接口，可用于生成序列。 + +Decoder提供的主要抽象为： + +1. :code:`(initial_input, initial_state, finished) = initialize(inits)`， +为第一个解码步生成输入和状态，并给出指示batch中的每个序列是否结束的初始标识。 + +2. :code:`(output, next_state, next_input, finished) = step(time, input, state)`， +将输入和状态转换为输出和新的状态，为下一个解码步生成输入，并给出指示batch中的每个序列是否结束的标识。 + +3. :code:`(final_outputs, final_state) = finalize(outputs, final_state, sequence_lengths)`， +修改输出（所有时间步输出的堆叠）和最后的状态以做特殊用途。若无需修改堆叠得到的输出和来自最后一个时间步的状态，则无需实现。 + +与RNNCell相比，Decoder更为通用，因为返回的 :code:`next_input` 和 :code:`finished` 使它可以自行决定输入以及结束时机。 + + +.. py:method:: initialize(inits) + +在解码迭代之前调用一次。 + +参数： + - **inits** - 调用方提供的参数。 + +返回：一个元组 :code:`(initial_inputs, initial_states, finished)` 。:code:`initial_inputs` 和 :code:`initial_states` 都是单个tensor变量或tensor变量组成的嵌套结构， :code:`finished` 是具有bool数据类型的tensor。 + +返回类型：tuple + +.. py:method:: step(time, inputs, states) + +在解码的每个时间步中被调用的接口 + +参数： + - **outputs** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。 结构和数据类型与 :code:`output_dtype` 相同。 tensor堆叠所有时间步长的输出从而具有shape :math:`[time\_step，batch\_size，...]` ，由调用者完成。 + - **final_states** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。 它是 :code:`decoder.step` 在最后一个解码步返回的 :code:`next_states`， 因此具有与任何时间步长的状态相同的结构，形状和数据类型。 + +返回：一个元组 :code:`(final_outputs, final_states)` 。:code:`final_outputs` 和 :code:`final_states` 都是单个tensor变量或tensor变量组成的嵌套结构。 + +返回类型：tuple \ No newline at end of file diff --git a/doc/fluid/api_cn/layers_cn/GRUCell_cn.rst b/doc/fluid/api_cn/layers_cn/GRUCell_cn.rst new file mode 100644 index 000000000..f00800cc4 --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/GRUCell_cn.rst @@ -0,0 +1,61 @@ +.. _cn_api_fluid_layers_GRUCell: + +GRUCell +------------------------------- + +.. py:class:: paddle.fluid.layers.GRUCell(hidden_size, param_attr=None, bias_attr=None, gate_activation=None, activation=None, dtype="float32", name="GRUCell") + +门控循环单元（Gated Recurrent Unit）。通过对 :code:`fluid.contrib.layers.rnn_impl.BasicGRUUnit` 包装，来让它可以应用于RNNCell。 + +公式如下： + +.. math:: + u_t & = act_g(W_{ux}x_{t} + W_{uh}h_{t-1} + b_u)\\ + r_t & = act_g(W_{rx}x_{t} + W_{rh}h_{t-1} + b_r)\\ + \tilde{h_t} & = act_c(W_{cx}x_{t} + W_{ch}(r_t \odot h_{t-1}) + b_c)\\ + h_t & = u_t \odot h_{t-1} + (1-u_t) \odot \tilde{h_t} + +更多细节可以参考 `Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation `_ + +参数： + - **hidden_size** (int) - GRUCell中的隐藏层大小。 + - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 + - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **gate_activation** (function，可选) - :math:`act_g` 的激活函数。 默认值为 :code:`fluid.layers.sigmoid`。 + - **activation** (function，可选) - :math:`act_c` 的激活函数。 默认值为 :code:`fluid.layers.tanh` + - **dtype** (string，可选) - 此cell中使用的数据类型。 默认为"float32"。 + - **name** (string，可选) - 用于标识参数和偏差的名称域。 + +返回：GRUCell类的实例对象。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid.layers as layers + cell = layers.rnn.GRUCell(hidden_size=256) + + +.. py:method:: call(inputs, states) + +执行GRU的计算。 + +参数： + - **input** (Variable) - 输入，形状为 :math:`[batch\_size，input\_size]` 的tensor，对应于公式中的 :math:`x_t` 。数据类型应为float32。 + - **states** (Variable) - 状态，形状为 :math:`[batch\_size，hidden\_size]` 的tensor。 对应于公式中的 :math:`h_{t-1}` 。数据类型应为float32。 + +返回：一个元组 :code:`(outputs, new_states)` ，其中 :code:`outputs` 和 :code:`new_states` 是同一个tensor，其形状为 :math:`[batch\_size，hidden\_size]`，数据类型和 :code:`state` 的数据类型相同，对应于公式中的 :math:`h_t`。 + +返回类型：tuple + +.. py:method:: state_shape() + +GRUCell的 :code:`state_shape` 是形状 :math:`[hidden\_size]` （batch大小为-1，自动插入到形状中），对应于 :math:`h_{t-1}` 的形状。 + +参数：无。 + +返回：GRUCell的 :code:`state_shape`。 + +返回类型：Variable + + diff --git a/doc/fluid/api_cn/layers_cn/LSTMCell_cn.rst b/doc/fluid/api_cn/layers_cn/LSTMCell_cn.rst new file mode 100644 index 000000000..324bf4a19 --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/LSTMCell_cn.rst @@ -0,0 +1,62 @@ +.. _cn_api_fluid_layers_LSTMCell: + +LSTMCell +------------------------------- + + +.. py:class:: paddle.fluid.layers.LSTMCell(hidden_size, param_attr=None, bias_attr=None, gate_activation=None, activation=None, forget_bias=1.0, dtype="float32", name="LSTMCell") + +长短期记忆单元（Long-Short Term Memory）。通过对 :code:`fluid.contrib.layers.rnn_impl.BasicLSTMUnit` 包装，来让它可以应用于RNNCell。 + +公式如下： + +.. math:: + i_{t} &= act_g \left ( W_{x_{i}}x_{t}+W_{h_{i}}h_{t-1}+b_{i} \right ) \\ + f_{t} &= act_g \left ( W_{x_{f}}x_{t}+W_{h_{f}}h_{t-1}+b_{f}+forget\_bias \right ) \\ + c_{t} &= f_{t}c_{t-1}+i_{t}act_h\left ( W_{x_{c}}x_{t} +W_{h_{c}}h_{t-1}+b_{c}\right ) \\ + o_{t} &= act_g\left ( W_{x_{o}}x_{t}+W_{h_{o}}h_{t-1}+b_{o} \right ) \\ + h_{t} &= o_{t}act_h \left ( c_{t} \right ) + +更多细节可以参考 `RECURRENT NEURAL NETWORK REGULARIZATION `_ + +参数： + - **hidden_size** (int) - LSTMCell中的隐藏层大小。 + - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 + - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **gate_activation** (function，可选) - :math:`act_g` 的激活函数。 默认值为 :code:`fluid.layers.sigmoid`。 + - **activation** (function，可选) - :math:`act_c` 的激活函数。 默认值为 :code:`fluid.layers.tanh`。 + - **forget_bias** (float，可选) - 计算遗忘们时使用的遗忘偏置。默认值为 1.0。 + - **dtype** (string，可选) - 此Cell中使用的数据类型。 默认值为 `float32`。 + - **name** (string，可选) - 用于标识参数和偏差的名称域。 + +返回：LSTMCell类的实例对象。 + +**示例代码** + +.. code-block:: python + + import paddle.fluid.layers as layers + cell = layers.rnn.LSTMCell(hidden_size=256) + + +.. py:method:: call(inputs, states) + +执行GRU的计算。 + +参数： + - **input** (Variable) - 输入，形状为 :math:`[batch\_size，input\_size]` 的tensor，对应于公式中的 :math:`x_t`。数据类型应为float32。 + - **states** (Variable) - 状态，包含两个tensor的列表，每个tensor形状为 :math:`[batch\_size，hidden\_size]`。 对应于公式中的 :math:`h_{t-1}, c_{t-1}`。数据类型应为float32。 + +返回：一个元组 :code:`(outputs, new_states)`，其中 :code:`outputs` 是形状为 :math:`[batch\_size，hidden\_size]` 的tensor，对应于公式中的 :math:`h_{t}`；:code:`new_states` 是一个列表，包含形状为 :math:`[batch_size，hidden_size]` 的两个tensor变量，它们对应于公式中的 :math:`h_{t}, c_{t}`。这些tensor的数据类型都与 :code:`state` 的数据类型相同。 + +返回类型：tuple + +.. py:method:: state_shape() + +LSTMCell的 :code:`state_shape` 是一个具有两个形状的列表：:math:`[[hidden\_size], [hidden\_size]]` （batch大小为-1，自动插入到形状中）。 这两个形状分别对应于公式中的 :math:`h_{t-1}` and :math:`c_{t-1}`。 + +参数：无。 + +返回：LSTMCell的 :code:`state_shape` + +返回类型：list \ No newline at end of file diff --git a/doc/fluid/api_cn/layers_cn/RNNCell_cn.rst b/doc/fluid/api_cn/layers_cn/RNNCell_cn.rst new file mode 100644 index 000000000..2cb3900eb --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/RNNCell_cn.rst @@ -0,0 +1,44 @@ +.. _cn_api_fluid_layers_RNNCell: + +RNNCell +------------------------------- + + +.. py:class:: paddle.fluid.layers.RNNCell(name=None) +RNNCell是抽象的基类，代表将输入和状态映射到输出和新状态的计算，主要用于RNN。 + +.. py:method:: call(inputs, states, **kwargs) + +每个cell都必须实现此接口，将（输入和状态）映射到（输出和新状态）。为了更灵活，输入和状态都可以是单个tensor变量或嵌套结构的tensor变量（列表 | 元组 | 命名元组 | 字典）。 + +参数： + - **inputs** - 输入，为单个tensor变量或tensor变量组成的嵌套结构。 + - **states** - 状态，单个tensor变量或tensor变量组成的嵌套结构。 + - **kwargs** - 附加的关键字参数，由调用者提供。 +         +返回：输出和新状态。输出和新状态都可以是嵌套的tensor变量。新状态必须具有与状态相同的结构。 + +返回类型：tuple + +.. py:method:: get_initial_states(batch_ref, shape=None, dtype=None, init_value=0) + +该接口根据提供的形状，数据类型和初始值来初始化状态。 + +参数： + - **batch_ref** - 单个tensor变量或tensor组成的嵌套结构。 tensor的第一维将用作初始化状态的batch大小。 + - **shape** - 单个形状或形状组成的嵌套结构，单个形状是整数的列表或元组。 如果形状的第一维不是batch大小，则自动插入-1作为batch大小。 如果该项为None，将使用属性 :code:`state_shape`。默认值为None。 + - **dtype** - 单个数据类型或由数据类型组成的嵌套结构。该结构必须与shape的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 如果是None并且属性 :code:`cell.state_shape` 不可用，则float32将用作数据类型。 默认值为None。 + - **init_value** - 用于初始化状态的浮点值。 + +返回：和shape具有相同结构的tensor变量，代表初始状态。 + +返回类型：Variable + +.. py:method:: state_shape() + +该接口用于初始化cell的状态。 单个形状或由形状组成的嵌套结构，单个形状可以是整数的列表或元组(如果形状的第一维不是batch大小，则自动插入-1作为batch大小)。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`shape` 参数的时候，不用实现该方法。 + + +.. py:method:: state_dtype() + +该接口用于初始化cell的状态。 单个数据类型或由数据类型组成的嵌套结构，该结构必须与 :code:`shape` 的结构相同，例外是当状态中的所有tensor都具有相同的数据类型，这时可以使用单个数据类型。 当没有使用 :code:`get_initial_states` 初始化状态或 :code:`get_initial_states` 没有提供 :code:`dtype` 参数的时候，不用实现该方法。 diff --git a/doc/fluid/api_cn/layers_cn/dynamic_decode_cn.rst b/doc/fluid/api_cn/layers_cn/dynamic_decode_cn.rst new file mode 100644 index 000000000..8b0c8aa9f --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/dynamic_decode_cn.rst @@ -0,0 +1,50 @@ +.. _cn_api_fluid_layers_dynamic_decode: + +dynamic_decode +------------------------------- + + +.. py:method:: dynamic_decode(decoder, inits=None, max_step_num=None, output_time_major=False, **kwargs): + +该接口重复执行 :code:`decoder.step()` 直到 其返回的表示完成状态的Tensor中的值全部为True或解码步骤达到 :code:`max_step_num`。 + +:code:`decode.initialize()` 会在解码循环之前被调用一次。如果 :code:`decoder` 实现了 :code:`finalize` 方法，则 :code:`decoder.finalize()` 在解码循环后将被调用一次。 + +参数: + - **decoder** (Decoder) - 解码器的实例。 + - **inits** (object，可选) - 传递给 :code:`decoder.initialize` 的参数。默认为None。 + - **max_step_num** (int，可选) - 最大步数。如果未提供，解码直到解码过程完成（ :code:`decode.step()` 返回的表示完成状态的Tensor中的值全部为True）。默认为None。 + - **output_time_major** (bool，可选) - 指明最终输出(此方法的第一个返回值)中包含的Tensor的数据布局。如果为False，其将使用batch优先的数据布局, 此时的形状为 :math:`[batch\_size，seq\_len，...]`。如果为True，其将使用time优先的数据布局，此时的形状为 :math:`[seq\_len，batch\_size，...]`。默认值为False。 + - **kwargs** - 其他命名关键字参数。这些参数将传递给 :code:`decoder.step`。 + +返回:一个二元组 :code:`(final_outputs，final_states)`, 其包含了最终的输出和状态，这两者都是Tensor或Tensor的嵌套结构。:code:`final_outputs` 具有与 :code:`decoder.output_dtype` 相同的结构和数据类型， 其中的每个tensor都是对所有解码时间步对应输出的堆叠。 这些tensor也可能会通过 :code:`decoder.finalize` 进行修改。:code:`final_states` 是最后时间步的状态，和 :code:`decoder.initialize` 返回的初始状态具有相同的结构，其中的tensor也具有相同的形状 和数据类型。 + +返回类型：tuple + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + import paddle.fluid.layers as layers + from paddle.fluid.layers import GRUCell, BeamSearchDecoder, dynamic_decode + encoder_output = fluid.data(name="encoder_output", + shape=[-1, 32, 128], + dtype="float32") + trg_embeder = lambda x: fluid.embedding( + x, size=[10000, 128], param_attr=fluid.ParamAttr(name="trg_embedding")) + output_layer = lambda x: layers.fc(x, + size=10000, + num_flatten_dims=len(x.shape) - 1, + param_attr=fluid.ParamAttr(name= + "output_w"), + bias_attr=False) + decoder_cell = GRUCell(hidden_size=128) + decoder = BeamSearchDecoder(decoder_cell, + start_token=0, + end_token=1, + beam_size=4, + embedding_fn=trg_embeder, + output_fn=output_layer) + outputs = dynamic_decode( + decoder=decoder, inits=decoder_cell.get_initial_states(encoder_output)) diff --git a/doc/fluid/api_cn/layers_cn/rnn_cn.rst b/doc/fluid/api_cn/layers_cn/rnn_cn.rst new file mode 100644 index 000000000..2766f2c23 --- /dev/null +++ b/doc/fluid/api_cn/layers_cn/rnn_cn.rst @@ -0,0 +1,35 @@ +.. _cn_api_fluid_layers_rnn: + +rnn +------------------------------- + + +.. py:method:: paddle.fluid.layers.rnn(inputs, initial_states=None, sequence_length=None, time_major=False, is_reverse=False, **kwargs) + + +rnn创建一个由RNNCell :code:`cell` 指定的递归神经网络，该神经网络重复执行 :code:`cell.call()` 直至达到 :code:`inputs` 的最大长度。 + +参数： + - **cell** (RNNCell) - RNNCell的实例。 + - **inputs** (Variable) - 单个tensor变量或tensor变量组成的嵌套结构。当 :code:`time_major == False` 时，tensor的形状应为 :math:`[batch\_size, sequence\_length, ...]`；当 :code:`time_major == True` 时，tensor的形状应为 :math:`[sequence\_length, batch\_size, ...]`。它表示要在RNN中展开的输入。 + - **initial_states** (Variable，可选) - 初始状态，单个tensor变量或tensor变量组成的嵌套结构，表示RNN的初始状态。如果未提供，将使用 :code:`cell.get_initial_states` 产生初始状态。默认值None。 + - **sequence_length** (Variable，可选) - 序列长度，形状为 :math:`[batch\_size]` 的tensor。它存储每个实例的实际长度，从而使用户能够在批处理的时候，提取最后一个有效状态，以确保正确性。如果未提供，则不区分填充和非填充输入。默认值None。 + - **time_major** (bool，可选) - 指示输入tensor和输出tensor中包含的tensor的数据组织。如果为False，则数据组织为batch为主，形状为 :math:`[batch\_size，sequence\_length，...]`。如果为True，则数据组织为time为主，形状为 :math:`[sequence\_length，batch\_size，...]`。默认值：False。 + - **is_reverse** (bool，可选) - 指示是否以输入序列的相反顺序进行计算。默认值：False。 + - **kwargs** - 其他关键字参数。参数传递给 :code:`cell.call`。 + +返回:一个元组 :code:`(final_outputs, final_states)` ，包括 :code:`final_outputs` 和 :code:`final_states`，均为单个tensor变量或tensor变量的嵌套结构。:code:`final_outputs` 具有与 :code:`cell.call` 返回的 :code:`outputs` 相同的结构和数据类型，并且 :code:`final_outputs` 中的每个tensor是将所有时间步的 :code:`outputs` 中对应内容堆叠产生，因此其形状为 :math:`[batch\_size，sequence\_length，...]` （:code:`time_major == False` 时）或 :math:`[sequence\_length，batch\_size，...]` （:code:`time_major == True` 时）。:code:`final_states` 是最后一步的状态，因此具有和 :code:`initial_states` 相同的结构，形状和数据类型。 + +返回类型：tuple + +**示例代码** + +.. code-block:: python + + import paddle.fluid as fluid + inputs = fluid.data(name="inputs", + shape=[-1, 32, 128], + dtype="float32") + cell = fluid.layers.GRUCell(hidden_size=128) + outputs = fluid.layers.rnn(cell=cell, inputs=inputs) + -- GitLab