update add_position_encoding_cn and other eight zh docs (#1454)

* update doc/fluid/api_cn/layers_cn/add_position_encoding_cn.rst
update doc/fluid/api_cn/layers_cn/beam_search_cn.rst
update doc/fluid/api_cn/layers_cn/beam_search_decode_cn.rst
update doc/fluid/api_cn/layers_cn/chunk_eval_cn.rst
update doc/fluid/api_cn/layers_cn/dynamic_gru_cn.rst
update doc/fluid/api_cn/layers_cn/gru_unit_cn.rst
update doc/fluid/api_cn/layers_cn/lstm_unit_cn.rst
update doc/fluid/api_cn/nets_cn/scaled_dot_product_attention_cn.rst

* Update format for dynamic_gru_cn, gru_unit_cn and scaled_dot_product_attention_cn.

doc/fluid/api_cn/layers_cn/add_position_encoding_cn.rst

@@ -5,30 +5,28 @@ add_position_encoding
 
 .. py:function:: paddle.fluid.layers.add_position_encoding(input, alpha, beta, name=None)
 
-**添加位置编码层**
+该OP将输入inpu中每个位置（序列中的位置）的特征与对应的位置编码加权求和，位置编码可参考论文: `Attention Is All You Need <http://arxiv.org/pdf/1706.03762.pdf>`_
 
-接受形状为[N×M×P]的三维输入张量，并返回一个形为[N×M×P]的输出张量，且输出张量具有位置编码值。
-
-可参考论文: `Attention Is All You Need <http://arxiv.org/pdf/1706.03762.pdf>`_
+输出的计算公式如下：
 
 .. math::
 
-  PE(pos, 2i) &= \sin{(pos / 10000^{2i / P})}\\
-  PE(pos, 2i + 1) &= \cos{(pos / 10000^{2i / P})}\\
-  Out(:, pos, i) &= \alpha * input(:, pos, i) + \beta * PE(pos, i)
+    PE(pos, 2i) &= \sin{(pos / 10000^{2i / P})}\\
+    PE(pos, 2i + 1) &= \cos{(pos / 10000^{2i / P})}\\
+    Out(:, pos, i) &= \alpha * input(:, pos, i) + \beta * PE(pos, i)
 
 其中:
-    - PE(pos, 2i): 偶数位置上数字的增量
-    - PE(pos, 2i + 1): 奇数位置上数字的增量
+    - PE(pos, 2i): pos位置对应的编码中偶数特征位上的值
+    - PE(pos, 2i + 1): pos位置对应的编码中奇数特征位上的值
 
 参数:
-    - **input**  (Variable) – 形状为[N x M x P]的三维输入张量
-    - **alpha**  (float) – 输入张量的倍数
-    - **beta**  (float) – 位置编码张量Positional Encoding Tensor的倍数
-    - **name**  (string) – 位置编码层的名称
+    - **input**  (Variable) – Tensor或LoD level为1的LoDTensor。Tensor时，其形状为 :math:`[N, M, P]` ，其中 :math:`N` 表示batch size， :math:`M` 表示序列长度， :math:`P` 为特征维度大小；LoDTensor时，其形状为 :math:`[N, P]` ，其中 :math:`N` 表示所有序列长度之和， :math:`P` 为特征维度大小。数据类型为float32或float64。
+    - **alpha**  (float) – 加权求和时输入input的权重系数
+    - **beta**  (float) – 加权求和时位置编码的权重系数
+    - **name**  (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
 
-返回:  具有位置编码的三维形状张量[N×M×P]
+返回:  加上位置编码后的Tensor或LoDTensor，和输入（input）具有相同数据类型和形状及LoD信息。
 
 返回类型: Variable
 

doc/fluid/api_cn/layers_cn/beam_search_cn.rst

@@ -5,36 +5,36 @@ beam_search
 
 .. py:function:: paddle.fluid.layers.beam_search(pre_ids, pre_scores, ids, scores, beam_size, end_id, level=0, is_accumulated=True, name=None, return_parent_idx=False)
 
-在机器翻译任务中，束搜索(Beam search)是选择候选词的一种经典算法
+束搜索(Beam search)是在机器翻译等生成任务中选择候选词的一种经典算法
 
 更多细节参考 `Beam Search <https://en.wikipedia.org/wiki/Beam_search>`_
 
-该层在一时间步中按束进行搜索。具体而言，根据候选词使用于源句子所得的 ``scores`` , 从候选词 ``ids`` 中选择当前步骤的 top-K （最佳K）候选词的id，其中 ``K`` 是 ``beam_size`` ， ``ids`` ， ``scores`` 是计算单元的预测结果。如果没有提供 ``ids`` ，则将会根据 ``scores`` 计算得出。 另外， ``pre_id`` 和 ``pre_scores`` 是上一步中 ``beam_search`` 的输出，用于特殊处理翻译的结束边界。
+**该OP仅支持LoDTensor**，在计算产生得分之后使用，完成单个时间步内的束搜索。具体而言，在计算部分产生 ``ids`` 和 ``scores`` 后，对于每个源句（样本）该OP从 ``ids`` 中根据其对应的 ``scores`` 选择当前时间步 top-K （``K`` 是 ``beam_size``）的候选词id。而 ``pre_id`` 和 ``pre_scores`` 是上一时间步 ``beam_search`` 的输出，加入输入用于特殊处理到达结束的翻译候选。
 
-注意，如果 ``is_accumulated`` 为 True，传入的 ``scores`` 应该是累积分数。反之，``scores`` 会被认为为直接得分(straightforward scores)， 并且会被转化为log值并且在此运算中会被累积到 ``pre_scores`` 中。在计算累积分数之前应该使用额外的 operators 进行长度惩罚。
+注意，如果 ``is_accumulated`` 为 True，传入的 ``scores`` 应该是累积分数。反之，``scores`` 是单步得分，会在该OP内被转化为log值并累积到 ``pre_scores`` 作为最终得分。如需使用长度惩罚，应在计算累积分数前使用其他OP完成。
 
-有关束搜索用法演示，请参阅以下示例：
+束搜索的完整用法请参阅以下示例：
 
      fluid/tests/book/test_machine_translation.py
 
 
 
 参数:
-  - **pre_ids** （Variable） -  LodTensor变量，它是上一步 ``beam_search`` 的输出。在第一步中。它应该是LodTensor，shape为 :math:`(batch\_size，1)` ， :math:`lod [[0,1，...，batch\_size]，[0,1，...，batch\_size]]`
-  - **pre_scores** （Variable） -  LodTensor变量，它是上一步中beam_search的输出
-  - **ids** （Variable） - 包含候选ID的LodTensor变量。shape为 :math:`（batch\_size×beam\_size，K）` ，其中 ``K`` 应该是 ``beam_size``
-  - **scores** （Variable） - 与 ``ids`` 及其shape对应的累积分数的LodTensor变量, 与 ``ids`` 的shape相同。
-  - **beam_size** （int） - 束搜索中的束宽度。
-  - **end_id** （int） - 结束标记的id。
-  - **level** （int，default 0） - **可忽略，当前不能更改** 。它表示lod的源级别，解释如下。 ``ids`` 的 lod 级别应为2.第一级是源级别， 描述每个源句子（beam）的前缀（分支）的数量，第二级是描述这些候选者属于前缀的句子级别的方式。链接前缀和所选候选者的路径信息保存在lod中。
-  - **is_accumulated** （bool，默认为True） - 输入分数是否为累计分数。
-  - **name** （str | None） - 该层的名称（可选）。如果设置为None，则自动命名该层。
-  - **return_parent_idx** （bool） - 是否返回一个额外的Tensor变量，在输出的pre_ids中保留selected_ids的双亲indice，可用于在下一个时间步收集单元状态。
+    - **pre_ids** （Variable） - LoD level为2的LodTensor，表示前一时间步选择的候选id，是前一时间步 ``beam_search`` 的输出。第一步时，其形状应为为 :math:`[batch\_size，1]` ， lod应为 :math:`[[0,1，...，batch\_size]，[0,1，...，batch\_size]]` 。数据类型为int64。
+    - **pre_scores** （Variable） - 维度和LoD均与 ``pre_ids`` 相同的LodTensor，表示前一时间步所选id对应的累积得分，是前一时间步 ``beam_search`` 的输出。数据类型为float32。
+    - **ids** （None|Variable） - 包含候选id的LodTensor。LoD应与 ``pre_ids`` 相同，形状为 :math:`[batch\_size \times beam\_size，K]` ，其中第一维大小与 ``pre_ids`` 相同且``batch_size`` 会随样本到达结束而自动减小， ``K`` 应该大于 ``beam_size`` 。数据类型为int64。可为空，为空时使用 ``scores`` 上的索引作为id。
+    - **scores** （Variable） - 表示 ``ids`` 对应的累积分数的LodTensor变量, 维度和LoD均与 ``ids`` 相同。
+    - **beam_size** （int） - 指明束搜索中的束宽度。
+    - **end_id** （int） - 指明标识序列结束的id。
+    - **level** （int，可选） - **可忽略，当前不能更改** 。知道LoD level为2即可，两层lod的意义如下： 第一级表示每个源句（样本）包含的beam大小，若满足结束条件（达到 ``beam_size`` 个结束）则变为0；第二级是表示每个beam被选择的次数。
+    - **is_accumulated** （bool，可选） - 指明输入分数 ``scores`` 是否为累积分数，默认为True。
+    - **name**  (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+    - **return_parent_idx** （bool，可选） - 指明是否返回一个额外的Tensor，该Tensor保存了选择的id的父节点（beam）在 ``pre_id`` 中索引，可用于通过gather OP更新其他Tensor的内容。默认为False。
 
 
-返回：LodTensor元组。包含所选的id和与其相应的分数。 如果return_parent_idx为True，则包含一个保留selected_ids的双亲indice的额外Tensor变量。
+返回：Variable的二元组或三元组。二元组中包含了当前时间步选择的id和对应的累积得分两个LodTensor，形状相同且均为 :math:`[batch\_size×beam\_size，1]` ，LoD相同且level均为2，数据类型分别为int64和float32；若 ``return_parent_idx`` 为True时为三元组，多返回一个保存了父节点在 ``pre_id`` 中索引的Tensor，形状为 :math:`[batch\_size \times beam\_size]` ，数据类型为int64。
 
-返回类型：Variable
+返回类型：tuple
 
 **代码示例**
 

doc/fluid/api_cn/layers_cn/beam_search_decode_cn.rst

@@ -5,22 +5,32 @@ beam_search_decode
 
 .. py:function:: paddle.fluid.layers.beam_search_decode(ids, scores, beam_size, end_id, name=None)
 
-束搜索层（Beam Search Decode Layer）通过回溯LoDTensorArray ids，为每个源语句构建完整假设，LoDTensorArray ``ids`` 的lod可用于恢复束搜索树中的路径。请参阅下面的demo中的束搜索使用示例：
+该OP用在整个束搜索(Beam search)结束后，通过沿 ``ids`` 中保存的搜索路径回溯，为每个源句（样本）构造完整的beam search结果序列并保存在LoDTensor中。LoDTensor的格式和解析方式如下：
+
+::
+
+
+    若 lod = [[0, 3, 6], [0, 12, 24, 40, 54, 67, 82]]
+    从第一层LoD的内容可以得出：包含两个样本，每个样本均对应了3个（等于束的宽度）生成序列
+    从第二层LoD的内容可以得出：第一个样本对应的三个序列的长度分别为12, 12, 16，第一个样本对应的三个序列的长度分别为14, 13, 15。
+
+
+完整用法请参阅下面的使用示例：
 
     ::
 
         fluid/tests/book/test_machine_translation.py
 
 参数:
-        - **id** (Variable) - LodTensorArray，包含所有回溯步骤重中所需的ids。
-        - **score** (Variable) - LodTensorArra，包含所有回溯步骤对应的score。
-        - **beam_size** (int) - 束搜索中波束的宽度。
-        - **end_id** (int) - 结束token的id。
-        - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名。
+    - **id** (Variable) - 保存了每个时间步选择的id（beam_search OP的输出）的LoDTensorArray。其中每个LoDTensor的数据类型为int64，LoD level为2，LoD中保存了搜索路径信息。
+    - **score** (Variable) - 保存了每个时间步选择的id所对应累积得分（beam_search OP的输出）的LoDTensorArray，和 ``id`` 具有相同大小。其中每个LoDTensor要和 ``id`` 中相应LoDTensor具有相同的形状和LoD，表示其对应的累积得分。数据类型为float32。
+    - **beam_size** (int) - 指示束搜索中波束的宽度。
+    - **end_id** (int) - 指明标识序列结束的id。
+    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
-返回： LodTensor 对（pair）， 由生成的id序列和相应的score序列组成。两个LodTensor的shape和lod是相同的。lod的level=2，这两个level分别表示每个源句有多少个假设，每个假设有多少个id。
+返回： Variable的二元组， 包含了完整id序列和对应的累积得分两个LodTensor，数据类型分别为int64和float32，形状相同且均展开为1维，LoD相同且level均为2。根据两层LoD可分别得到每个源句（样本）有多少个生成序列和每个序列有多少个id。
 
-返回类型: 变量（variable）
+返回类型: tuple
 
 
 **代码示例**
@@ -29,8 +39,8 @@ beam_search_decode
 
        import paddle.fluid as fluid
 
-       # 假设 `ids` 和 `scores` 为 LodTensorArray变量，它们保留了
-       # 选择出的所有时间步的id和score
+       # 假设 `ids` 和 `scores` 为LoDTensorArray类型的Variable，它们保留了
+       # 所有时间步选择出的id和score
        ids = fluid.layers.create_array(dtype='int64')
        scores = fluid.layers.create_array(dtype='float32')
        finished_ids, finished_scores = fluid.layers.beam_search_decode(

doc/fluid/api_cn/layers_cn/chunk_eval_cn.rst

@@ -5,13 +5,11 @@ chunk_eval
 
 .. py:function:: paddle.fluid.layers.chunk_eval(input, label, chunk_scheme, num_chunk_types, excluded_chunk_types=None, sqe_length=None)
 
-块估计（Chunk Evaluator）
+该OP计算语块识别（chunk detection）的准确率、召回率和F1值，常用于命名实体识别（NER，语块识别的一种）等序列标注任务中。
 
-该功能计算并输出块检测（chunk detection）的准确率、召回率和F1值。
+语块识别的基础请参考 `Chunking with Support Vector Machines <https://www.aclweb.org/anthology/N01-1025>`_
 
-chunking的一些基础请参考 `Chunking with Support Vector Machines <https://aclanthology.info/pdf/N/N01/N01-1025.pdf>`_
-
-ChunkEvalOp计算块检测（chunk detection）的准确率、召回率和F1值，并支持IOB，IOE，IOBES和IO标注方案。以下是这些标注方案的命名实体（NER）标注例子：
+该OP支持IOB，IOE，IOBES和IO（plain）的标注方式。以下是这些标注方式在命名实体识别示例中的使用：
 
 ::
 
@@ -25,9 +23,9 @@ ChunkEvalOp计算块检测（chunk detection）的准确率、召回率和F1值
     IOBES  B-PER  E-PER   O      O   I-ORG          I-ORG  I-ORG E-ORG  O   S-LOC
     ====== ====== ======  =====  ==  ============   =====  ===== =====  ==  =========
 
-有三种块类别（命名实体类型），包括PER（人名），ORG（机构名）和LOC（地名），标签形式为标注类型（tag type）-块类型（chunk type）。
+例中有PER（人名），ORG（机构名）和LOC（地名）三种语块类型（命名实体类型）。可以看到，一个完整的标签包括标注类型（tag type）和语块类型（chunk type），形式为 ``标注类型-语块类型（tag type-chunk type）`` 。
 
-由于计算实际上用的是标签id而不是标签，需要额外注意将标签映射到相应的id，这样CheckEvalOp才可运行。关键在于id必须在列出的等式中有效。
+由于该OP在计算实现上使用的是标签id而非标签字符串，为使其能正确运行，标签id要能够转换为相应的标注类型（tag type）和语块类型（chunk type）。该OP使用了下面的方式完成映射转换：
 
 ::
 
@@ -35,7 +33,7 @@ ChunkEvalOp计算块检测（chunk detection）的准确率、召回率和F1值
     tag_type = label % num_tag_type
     chunk_type = label / num_tag_type
 
-num_tag_type是标注规则中的标签类型数，num_chunk_type是块类型数，tag_type从下面的表格中获取值。
+其中num_tag_type是标注方式中的标签类型（tag type）数，各标注方式的tag type取值如下：
 
 ::
 
@@ -46,7 +44,7 @@ num_tag_type是标注规则中的标签类型数，num_chunk_type是块类型数
     IOE     -     0      1     -
     IOBES   0     1      2     3
 
-仍以NER为例，假设标注规则是IOB块类型为ORG，PER和LOC。为了满足以上等式，标签图如下：
+据此，在上面的NER例子中，若标注方式是IOB，语块类型包括ORG、PER和LOC三种，则所有标签及其对应id如下：
 
 ::
 
@@ -59,19 +57,19 @@ num_tag_type是标注规则中的标签类型数，num_chunk_type是块类型数
     I-LOC  5
     O      6
 
-不难证明等式的块类型数为3，IOB规则中的标签类型数为2.例如I-LOC的标签id为5，I-LOC的标签类型id为1，I-LOC的块类型id为2，与等式的结果一致。
+从标签id可以正确的得到其对应的标注类型（tag type）和语块类型（chunk type）。
 
 参数：
-    - **input** (Variable) - 网络的输出预测
-    - **label** (Variable) - 测试数据集的标签
-    - **chunk_scheme** (str) - 标注规则，表示如何解码块。必须数IOB，IOE，IOBES或者plain。详情见描述
-    - **num_chunk_types** (int) - 块类型数。详情见描述
-    - **excluded_chunk_types** (list) - 列表包含块类型id，表示不在计数内的块类型。详情见描述
-    - **seq_length** (Variable) - 当输入和标签是张量时，指定序列长度的一个1维张量
+    - **input** (Variable) - 表示网络预测的标签，为Tensor或LoD level为1的LoDTensor。Tensor时，其形状为 :math:`[N, M, 1]` ，其中 :math:`N` 表示batch size， :math:`M` 表示序列长度；LoDTensor时，其形状为 :math:`[N, 1]` 或 :math:`[N]` ，其中 :math:`N` 表示所有序列长度之和。数据类型为int64。
+    - **label** (Variable) - 表示真实标签（ground-truth）的Tensor或LoDTensor，和 ``input`` 具有相同形状、LoD和数据类型。
+    - **chunk_scheme** (str) - 标注方式，必须是IOB，IOE，IOBES或者plain中的一种。
+    - **num_chunk_types** (int) - 表示标签中的语块类型数。
+    - **excluded_chunk_types** (list，可选) - 表示不计入统计的语块类型，需要为语块类型（int表示）的列表。默认值为空的list。
+    - **seq_length** (Variable，可选) - 当输入 ``input`` 和 ``label`` 是Tensor而非LoDTensor时，用来指示输入中每个序列长度的1-D Tensor。数据类型为int64。可以为空，默认为None。
 
-返回：元组（tuple），包含precision, recall, f1_score, num_infer_chunks, num_label_chunks, num_correct_chunks
+返回：Variable的元组。元组中包含准确率、召回率、F1值，以及识别出的语块数目、标签中的语块数目、正确识别的语块数目。每个均是单个元素的Tensor，准确率、召回率、F1值的数据类型为float32，其他的数据类型为int64。
 
-返回类型：tuple（元组）
+返回类型：tuple
 
 **代码示例**：
 

doc/fluid/api_cn/layers_cn/dynamic_gru_cn.rst

@@ -6,29 +6,22 @@ dynamic_gru
 .. py:function::  paddle.fluid.layers.dynamic_gru(input, size, param_attr=None, bias_attr=None, is_reverse=False, gate_activation='sigmoid', candidate_activation='tanh', h_0=None, origin_mode=False)
 
 
+**注意：该OP的输入只能是LoDTensor，如果您需要处理的输入是Tensor类型，请使用StaticRNN（fluid.layers.** :ref:`cn_api_fluid_layers_StaticRNN` **）。**
 
-**实现了Gated Recurrent Unit层。**
+该OP用于在完整序列上逐个时间步的进行单层Gated Recurrent Unit（GRU）的计算，单个时间步内GRU的计算支持以下两种计算方式：
 
-如果origin_mode为False，那么gru运算公式来自论文 `Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling <https://arxiv.org/abs/1412.3555>`_ 。
+如果origin_mode为True，则使用的运算公式来自论文
+`Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation <https://arxiv.org/pdf/1406.1078.pdf>`_ 。
 
-
-公式如下：
-
-.. math::
-  u_{t}=act_g(W_{ux}x_{t}+W_{uh}h_{t-1}+b_{u})
-.. math::
-  r_{t}=act_g(W_{rx}x_{t}+W_{rh}h_{t-1}+b_{r})
-.. math::
-  \widetilde{h_{t}}=act_{c}(W_{cx}x_{t}+W_{ch}(r_{t}\odot h_{t-1})+b_c)
 .. math::
-  h_t=(1-u_t)\odot h_{t-1}+u_t\odot \widetilde{h_t}
-
-
-
-
-如果origin_mode为True，那么运算公式来自于 `Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation <https://arxiv.org/pdf/1406.1078.pdf>`_
+    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}
 
 
+如果origin_mode为False，则使用的运算公式来自论文
+`Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling  <https://arxiv.org/pdf/1412.3555.pdf>`_ 。
 
 公式如下:
 
@@ -36,35 +29,28 @@ dynamic_gru
     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}
-
-
-
-
-其中， :math:`\odot` 为按元素将向量相乘。 :math:`act_g` 是更新门（update gate）和重置门（reset gate）的激励函数(activation)， 常为 :math:`sigmoid` 函数。 :math:`act_c` 是candidate hidden state(候选隐藏状态)的激励函数，常为 :math:`tanh` 。
+    h_t & = (1-u_t) \odot h_{t-1} + u_t \odot \tilde{h_t}
 
-注意 :math:`W_{ux}x_{t},W_{rx}x_{t},W_{cx}x_{t}` 这些在 input  :math:`x_t` 上的操作不包括在该运算中。用户可以选择性地在GRU层之前使用FC层来进行这一操作。
 
+其中， :math:`x_t` 为当前时间步的输入，这个输入并非 ``input``，该OP不包含 :math:`W_{ux}x_{t}, W_{rx}x_{t}, W_{cx}x_{t}` 的计算， **注意** 要在该OP前使用大小为 ``size`` 的3倍的全连接层并将其输出作为 ``input``；
+:math:`h_{t-1}` 为前一时间步的隐状态 ``hidden``； :math:`u_t` 、 :math:`r_t` 、 :math:`\tilde{h_t}` 和 :math:`h_t` 分别代表了GRU单元中update gate（更新门）、reset gate（重置门）、candidate hidden（候选隐状态）和隐状态输出; :math:`\odot` 为逐个元素相乘；
+:math:`W_{uh}, b_u` 、 :math:`W_{rh}, b_r` 和 :math:`W_{ch}, b_c` 分别代表更新门、重置门和候选隐状态在计算时使用的权重矩阵和偏置。在实现上，三个权重矩阵合并为一个 :math:`[D, D \times 3]` 形状的Tensor存放，三个偏置拼接为一个 :math:`[1, D \times 3]` 形状的Tensor存放，其中 :math:`D` 为隐单元的数目；权重Tensor存放布局为： :math:`W_{uh}` 和 :math:`W_{rh}` 拼接为 :math:`[D, D  \times 2]` 形状位于前半部分，:math:`W_{ch}` 以 :math:`[D, D]` 形状位于后半部分。
 
 
 参数:
-  - **input** (Variable) – dynamic_gru层的输入, 支持variable time length input sequence（可变时长输入序列）。 本变量底层的tensor是一个(T×3D)矩阵， 其中T是该mini-batch中总时间步数， D是隐藏状态的规模（hidden size）。
-  - **size** (int) – GRU cell的维度
-  - **param_attr** (ParamAttr|None)  –  可学习的隐藏层权重矩阵的参数属性。
-    注意：
-                                    - 该矩阵为一个（T X 3D）矩阵。其中D为隐藏状态的规模（hidden size）
-                                    - 该矩阵的所有元素由两部分组成。一是update gate和reset gate的权重，形为（D X 2D)，二是候选隐藏状态（candidate hidden state）的权重，形为 (D X D)
-    如果该函数参数被设为None或者 ``ParamAttr`` 类的属性之一，则会生成一个 ``ParamAttr`` 类的对象作为param_attr。如果param_attr未被初始化（即其构造函数未被设置），Xavier会负责初始化它。 默认值为None。
-  - **bias_attr** (ParamAttr|bool|None) - GRU层bias的参数属性。该（1 X 3D）形的bias变量将会连结（concatenate）在update gate（更新门）、reset gate（重置门）、candidate calculations（候选隐藏状态计算）后。如果值为False，将没有bias会应用到上述三个过程中。如果该函数参数被设为None或者 ``ParamAttr`` 类的属性之一， ``dynamic_gru`` 会生成一个 ``ParamAttr`` 类的对象作为param_attr。如果bias_attr未被初始化（即其构造函数未被设置），则它会被初始化为0。默认值为None。
-  - **is_reverse** (bool) –是否计算反GRU(reversed GRU)，默认为False
-  - **gate_activation** (str) – update gate 和 reset gate的激励函数（activation）。 可选择[“sigmoid”, “tanh”, “relu”, “identity”]其一, 默认为 “sigmoid”
-  - **candidate_activation** (str) – candidate hidden state（候选隐藏状态）计算所需的激励函数（activation）。 可从[“sigmoid”, “tanh”, “relu”, “identity”]中选择, 默认为 “tanh”
-  - **h_0** (Variable) – 该函数参数为初始隐藏状态。若未赋值，则默认为0。它是一个 (N x D) tensor, 其中 N 为输入mini-batch的总时间步数， D 为 隐藏状态规模(hidden size)
-
-
-返回： GRU的隐藏状态(hidden state)。形为（T X D），序列长度和输入相同。
-
-返回类型: 变量（variable）
+    - **input** (Variable) – LoD level为1的LoDTensor，表示经线性变换后的序列输入，形状为 :math:`[T, D \times 3]` ，其中 :math:`T` 表示mini-batch中所有序列长度之和， :math:`D` 为隐状态特征维度的大小。数据类型为float32或float64。
+    - **size** (int) – 隐状态特征维度的大小
+    - **param_attr** (ParamAttr，可选) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **is_reverse** (bool，可选) – 指明是否按照和输入相反的序列顺序计算，默认为False。
+    - **gate_activation** (str，可选) – 公式中 :math:`act_g` 激活函数的类型。支持identity、sigmoid、tanh、relu四种激活函数类型，默认为sigmoid。
+    - **candidate_activation** (str，可选) – 公式中 :math:`act_c` 激活函数的类型。支持identity、sigmoid、tanh、relu四种激活函数类型，默认为tanh。
+    - **h_0** (Variable，可选) – 表示初始隐状态的Tensor，若未提供，则默认为0。其形状为 :math:`[N, D]` , 其中 :math:`N` 为输入mini-batch中序列的数目， :math:`D` 为隐状态特征维度的大小。数据类型与 ``input`` 相同。默认值为None。
+    - **origin_mode** (bool，可选) – 指明要使用的GRU计算方式，两种计算方式具体差异见公式描述，默认值为False。
+
+返回： 形状为 :math:`[T, D]` 、LoD level为1的LoDTensor，其中 :math:`T` 表示mini-batch中所有序列长度之和， :math:`D` 为隐状态特征维度的大小。表示经过GRU变换的输出特征序列，和 ``input`` 具有相同的LoD（序列长度）和数据类型。
+
+返回类型: Variable
 
 
 **代码示例**

doc/fluid/api_cn/layers_cn/gru_unit_cn.rst

@@ -5,63 +5,49 @@ gru_unit
 
 .. py:function:: paddle.fluid.layers.gru_unit(input, hidden, size, param_attr=None, bias_attr=None, activation='tanh', gate_activation='sigmoid', origin_mode=False)
 
-GRU单元层。GRU执行步骤基于如下等式：
+Gated Recurrent Unit（GRU）循环神经网络计算单元。该OP用于完成单个时间步内GRU的计算，支持以下两种计算方式：
+
+如果origin_mode为True，则使用的运算公式来自论文
+`Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation <https://arxiv.org/pdf/1406.1078.pdf>`_ 。
+
+.. 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}
 
 
-如果origin_mode为True，则该运算公式来自论文
+如果origin_mode为False，则使用的运算公式来自论文
 `Empirical Evaluation of Gated Recurrent Neural Networks on Sequence Modeling  <https://arxiv.org/pdf/1412.3555.pdf>`_ 。
 
 公式如下:
 
 .. math::
-    u_t=actGate(xu_t+W_{u}h_{t-1}+b_u)
-.. math::
-    r_t=actGate(xr_t+W_{r}h_{t-1}+b_r)
-.. math::
-    m_t=actNode(xm_t+W_{c}dot(r_t,h_{t-1})+b_m)
-.. math::
-    h_t=dot((1-u_t),m_t)+dot(u_t,h_{t-1})
-
+    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 & = (1-u_t) \odot h_{t-1} + u_t \odot \tilde{h_t}
 
-如果origin_mode为False，则该运算公式来自论文
-`Learning Phrase Representations using RNN Encoder Decoder for Statistical Machine Translation <https://arxiv.org/pdf/1406.1078.pdf>`_ 。
-
-.. math::
-    u_t=actGate(xu_t+W_{u}h_{t-1}+b_u)
-.. math::
-    r_t=actGate(xr_t+W_{r}h_{t-1}+b_r)
-.. math::
-    m_t=actNode(xm_t+W_{c}dot(r_t,h_{t-1})+b_m)
-.. math::
-    h_t=dot(u_t,m_t)+dot((1-u_t),h_{t-1})
 
+其中， :math:`x_t` 为当前时间步的输入，这个输入并非 ``input``，该OP不包含 :math:`W_{ux}x_{t}, W_{rx}x_{t}, W_{cx}x_{t}` 的计算，**注意** 要在该OP前使用大小为 ``size`` 的3倍的全连接层并将其输出作为 ``input``；
+:math:`h_{t-1}` 为前一时间步的隐状态 ``hidden``； :math:`u_t` 、 :math:`r_t` 、 :math:`\tilde{h_t}` 和 :math:`h_t` 分别代表了GRU单元中update gate（更新门）、reset gate（重置门）、candidate hidden（候选隐状态）和隐状态输出; :math:`\odot` 为逐个元素相乘；
+:math:`W_{uh}, b_u` 、 :math:`W_{rh}, b_r` 和 :math:`W_{ch}, b_c` 分别代表更新门、重置门和候选隐状态在计算时使用的权重矩阵和偏置。在实现上，三个权重矩阵合并为一个 :math:`[D, D \times 3]` 形状的Tensor存放，三个偏置拼接为一个 :math:`[1, D \times 3]` 形状的Tensor存放，其中 :math:`D` 为隐单元的数目；权重Tensor存放布局为： :math:`W_{uh}` 和 :math:`W_{rh}` 拼接为 :math:`[D, D  \times 2]` 形状位于前半部分，:math:`W_{ch}` 以 :math:`[D, D]` 形状位于后半部分。
 
-GRU单元的输入包括 :math:`z_t` ， :math:`h_{t-1}` 。在上述等式中， :math:`z_t` 会被分割成三部分： :math:`xu_t` 、 :math:`xr_t` 和 :math:`xm_t`  。
-这意味着要为一批输入实现一个全GRU层，我们需要采用一个全连接层，才能得到 :math:`z_t=W_{fc}x_t` 。
-:math:`u_t` 和 :math:`r_t` 分别代表了GRU神经元的update gates（更新门）和reset gates(重置门)。
-和LSTM不同，GRU少了一个门（它没有LSTM的forget gate）。但是它有一个叫做中间候选隐藏状态（intermediate candidate hidden output）的输出，
-记为 :math:`m_t` 。 该层有三个输出： :math:`h_t, dot(r_t,h_{t-1})` 以及 :math:`u_t，r_t，m_t` 的连结(concatenation)。
 
+参数:
+    - **input** (Variable) – 表示经线性变换后当前时间步的输入，是形状为 :math:`[N, D \times 3]` 的二维Tensor，其中 :math:`N` 为batch_size， :math:`D` 为隐单元的数目。数据类型为float32或float64。
+    - **hidden** (Variable) –  表示上一时间步产生的隐状态，是形状为 :math:`[N, D]` 的二维Tensor，其中 :math:`N` 为batch_size， :math:`D` 为隐单元的数目。数据类型与 ``input`` 相同。
+    - **size** (integer) – 输入数据 ``input`` 特征维度的大小，需要是隐单元数目的3倍。
+    - **param_attr** (ParamAttr，可选) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **activation** (string) –  公式中 :math:`act_c` 激活函数的类型。支持identity、sigmoid、tanh、relu四种激活函数类型，默认为tanh。
+    - **gate_activation** (string) – 公式中 :math:`act_g` 激活函数的类型。支持identity、sigmoid、tanh、relu四种激活函数类型，默认为sigmoid。
+    - **origin_mode** (bool) – 指明要使用的GRU计算方式，两种计算方式具体差异见公式描述，默认值为False。
 
 
+返回：Variable的三元组，包含三个与 ``input`` 相同数据类型的Tensor，分别表示下一时间步的隐状态（ :math:`h_t` ）、重置的前一时间步的隐状态（ :math:`r_t \odot h_{t-1}` ）和 :math:`h_t, r_t, \tilde{h_t}` 的拼接，形状分别为 :math:`[N, D]` 、 :math:`[N, D]` 和 :math:`[N, D \times 3]` 。通常只有下一时间步的隐状态（ :math:`h_t` ）作为GRU的输出和隐状态使用，其他内容只是中间计算结果。
 
-参数:
-  - **input** (Variable) – 经FC层变换后的当前步骤的输入值
-  - **hidden** (Variable) –  从上一步而来的gru unit 隐藏状态值(hidden value)
-  - **size** (integer) – 输入数据的维度
-  - **param_attr** (ParamAttr|None) – 可学习的隐藏层权重矩阵的参数属性。
-    注意：
-      - 该权重矩阵形为 :math:`(T×3D)` ， :math:`D` 是隐藏状态的规模（hidden size）
-      - 该权重矩阵的所有元素由两部分组成， 一是update gate和reset gate的权重，形为 :math:`(D×2D)` ；二是候选隐藏状态（candidate hidden state）的权重矩阵，形为 :math:`(D×D)`
-    如果该函数参数值为None或者 ``ParamAttr`` 类中的属性之一，gru_unit则会创建一个 ``ParamAttr`` 类的对象作为 param_attr。如果param_attr没有被初始化，那么会由Xavier来初始化它。默认值为None
-  - **bias_attr** (ParamAttr|bool|None) - GRU的bias变量的参数属性。形为 :math:`(1x3D)` 的bias连结（concatenate）在update gates（更新门），reset gates(重置门)以及candidate calculations（候选隐藏状态计算）中的bias。如果值为False，那么上述三者将没有bias参与运算。若值为None或者 ``ParamAttr`` 类中的属性之一，gru_unit则会创建一个 ``ParamAttr`` 类的对象作为 bias_attr。如果bias_attr没有被初始化，那它会被默认初始化为0。默认值为None。
-  - **activation** (string) –  神经元 “actNode” 的激励函数（activation）类型。默认类型为‘tanh’
-  - **gate_activation** (string) – 门 “actGate” 的激励函数（activation）类型。 默认类型为 ‘sigmoid’
-
-
-返回：  hidden value（隐藏状态的值），reset-hidden value(重置隐藏状态值)，gate values(门值)
-
-返回类型:  元组（tuple）
+返回类型: tuple
 
 
 **代码示例**

doc/fluid/api_cn/layers_cn/lstm_unit_cn.rst

@@ -5,47 +5,43 @@ lstm_unit
 
 .. py:function:: paddle.fluid.layers.lstm_unit(x_t, hidden_t_prev, cell_t_prev, forget_bias=0.0, param_attr=None, bias_attr=None, name=None)
 
-Lstm unit layer
 
-lstm步的等式：
+Long-Short Term Memory（LSTM）循环神经网络计算单元。该OP用于完成单个时间步内LSTM的计算，基于论文 `RECURRENT NEURAL NETWORK REGULARIZATION <http://arxiv.org/abs/1409.2329>`_ 中的描述实现，
+
+并在forget gate（遗忘门）中增加了 ``forget_bias`` 来控制遗忘力度，公式如下：
 
 .. math::
 
     i_{t} &= \sigma \left ( W_{x_{i}}x_{t}+W_{h_{i}}h_{t-1}+b_{i} \right ) \\
-    f_{t} &= \sigma \left ( W_{x_{f}}x_{t}+W_{h_{f}}h_{t-1}+b_{f} \right ) \\
+    f_{t} &= \sigma \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}tanh\left ( W_{x_{c}}x_{t} +W_{h_{c}}h_{t-1}+b_{c}\right ) \\
     o_{t} &= \sigma \left ( W_{x_{o}}x_{t}+W_{h_{o}}h_{t-1}+b_{o} \right ) \\
     h_{t} &= o_{t}tanh \left ( c_{t} \right )
 
-lstm单元的输入包括 :math:`x_{t}` ， :math:`h_{t-1}` 和 :math:`c_{t-1}` 。:math:`h_{t-1}` 和 :math:`c_{t-1}` 的第二维应当相同。在此实现过程中，线性转换和非线性转换分离。以 :math:`i_{t}` 为例。线性转换运用到fc层，等式为：
-
-.. math::
+其中， :math:`x_{t}` 对应 ``x_t``， 表示当前时间步的输入； :math:`h_{t-1}` 和 :math:`c_{t-1}` 对应 ``hidden_t_prev`` 和 ``cell_t_prev``，表示上一时间步的hidden和cell输出；
+:math:`i_{t}, f_{t}, c_{t}, o_{t}, h_{t}` 分别为input gate（输入门）、forget gate（遗忘门）、cell、output gate（输出门）和hidden的计算。
 
-    L_{i_{t}} = W_{x_{i}}x_{t} + W_{h_{i}}h_{t-1} + b_{i}
-
-非线性转换运用到lstm_unit运算，方程如下：
-
-.. math::
-
-    i_{t} = \sigma \left ( L_{i_{t}} \right )
-
-该层有 :math:`h_{t}` 和 :math:`c_{t}` 两个输出。
 
 参数：
-    - **x_t** (Variable) - 当前步的输入值，二维张量，shape为 M x N ，M是批尺寸，N是输入尺寸
-    - **hidden_t_prev** (Variable) - lstm单元的隐藏状态值，二维张量，shape为 M x S，M是批尺寸，S是lstm单元的大小
-    - **cell_t_prev** (Variable) - lstm单元的cell值，二维张量，shape为 M x S ，M是批尺寸，S是lstm单元的大小
-    - **forget_bias** (Variable) - lstm单元的遗忘bias
-    - **param_attr** (ParamAttr|None) - 可学习hidden-hidden权重的擦参数属性。如果设为None或者 ``ParamAttr`` 的一个属性，lstm_unit创建 ``ParamAttr`` 为param_attr。如果param_attr的初始化函数未设置，参数初始化为Xavier。默认：None
-    - **bias_attr** (ParamAttr|None) - 可学习bias权重的bias属性。如果设为False，输出单元中则不添加bias。如果设为None或者 ``ParamAttr`` 的一个属性，lstm_unit创建 ``ParamAttr`` 为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认：None
-    - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名
+    - **x_t** (Variable) - 表示当前时间步的输入的Tensor，形状为 :math:`[N, M]` ，其中 :math:`N` 为batch_size， :math:`M` 为输入的特征维度大小。数据类型为float32或float64。
+    - **hidden_t_prev** (Variable) - 表示前一时间步hidden输出的Tensor，形状为 :math:`[N, D]`，其中 :math:`N` 为batch_size， :math:`D` 为LSTM中隐单元的数目。数据类型与 ``x_t`` 相同。
+    - **cell_t_prev** (Variable) - 表示前一时间步cell输出的Tensor，和  ``hidden_t_prev`` 具有相同形状和数据类型。
+    - **forget_bias** (float，可选) - 额外添加在遗忘门中的偏置项(参见公式)。默认值为0。
+    - **param_attr** (ParamAttr，可选) – 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **name**  (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
-返回：lstm单元的hidden(隐藏状态)值和cell值
+返回：Variable的二元组，包含了两个形状均为 :math:`[N, D]` 的Tensor，分别表示hiddel和cell输出，即公式中的 :math:`h_{t}` 和 :math:`c_{t}` 。数据类型与输入 ``x_t`` 相同。
 
-返回类型：tuple（元组）
+返回类型：tuple
 
 抛出异常:
-  - ``ValueError`` - ``x_t``，``hidden_t_prev`` 和 ``cell_t_prev`` 的阶不为2，或者 ``x_t`` ，``hidden_t_prev`` 和 ``cell_t_prev`` 的第一维不一致，或者 ``hidden_t_prev`` 和 ``cell_t_prev`` 的第二维不一致
+    - :code:`ValueError`： ``x_t`` 的阶不为2
+    - :code:`ValueError`： ``hidden_t_prev`` 的阶不为2
+    - :code:`ValueError`： ``cell_t_prev`` 的阶不为2
+    - :code:`ValueError`： ``x_t`` 、``hidden_t_prev`` 和 ``cell_t_prev`` 的第一维大小必须相同
+    - :code:`ValueError`： ``hidden_t_prev`` 和 ``cell_t_prev`` 的第二维大小必须相同
+
 
 **代码示例**：
 

doc/fluid/api_cn/nets_cn/scaled_dot_product_attention_cn.rst

@@ -5,34 +5,37 @@ scaled_dot_product_attention
 
 .. py:function:: paddle.fluid.nets.scaled_dot_product_attention(queries, keys, values, num_heads=1, dropout_rate=0.0)
 
-点乘attention运算。
+该接口实现了的基于点积（并进行了缩放）的多头注意力（Multi-Head Attention）机制。attention可以表述为将一个查询（query）和一组键值对（key-value pair）映射为一个输出；Multi-Head Attention则是使用多路进行attention，而且对attention的输入进行了线性变换。公式如下：
 
-attention运算机制可以被视为将查询和一组键值对映射到输出。 将输出计算为值的加权和，其中分配给每个值的权重由查询的兼容性函数（此处的点积）与对应的密钥计算。
-
-可以通过（batch）矩阵乘法实现点积attention运算，如下所示：
 
 .. math::
-      Attention(Q, K, V)= softmax(QK^\mathrm{T})V
+    
+    MultiHead(Q, K, V ) & = Concat(head_1, ..., head_h)\\
+    where \  head_i & = Attention(QW_i^Q , KW_i^K , VW_i^V )\\
+    Attention(Q, K, V) & = softmax(\frac{QK^\mathrm{T}}{\sqrt{d_k}})V\\
+
+其中， :math:`Q, K, V` 分别对应 ``queries``、 ``keys`` 和 ``values`` ，详细内容请参阅 `Attention Is All You Need <https://arxiv.org/pdf/1706.03762.pdf>`_ 
 
-请参阅 `Attention Is All You Need <https://arxiv.org/pdf/1706.03762.pdf>`_ 
+要注意该接口实现支持的是batch形式， :math:`Attention(Q, K, V)` 中使用的矩阵乘是batch形式的矩阵乘法，参考 fluid.layers. :ref:`cn_api_fluid_layers_matmul` 。
 
 参数：
-         - **queries** （Variable） - 输入变量，应为3-D Tensor。
-         - **keys** （Variable） - 输入变量，应为3-D Tensor。
-         - **values** （Variable） - 输入变量，应为3-D Tensor。
-         - **num_heads** （int） - 计算缩放点积attention运算的head数。默认值：1。
-         - **dropout_rate** （float） - 降低attention的dropout率。默认值：0.0。
+    - **queries** （Variable） - 形状为 :math:`[N, L_q, d_k \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_q` 为查询序列长度， :math:`d_k \times h` 为查询的特征维度大小，:math:`h` 为head数。数据类型为float32或float64。
+    - **keys** （Variable） - 形状为 :math:`[N, L_k, d_k \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_k` 为键值序列长度， :math:`d_k \times h` 为键的特征维度大小，:math:`h` 为head数。数据类型与 ``queries`` 相同。
+    - **values** （Variable） - 形状为 :math:`[N, L_k, d_v \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_v` 为键值序列长度， :math:`d_v \times h` 为值的特征维度大小，:math:`h` 为head数。数据类型与 ``queries`` 相同。
+    - **num_heads** （int） - 指明所使用的head数。head数为1时不对输入进行线性变换。默认值为1。
+    - **dropout_rate** （float） - 以指定的概率对要attention到的内容进行dropout。默认值为0，即不使用dropout。
 
-返回：   通过multi-head来缩放点积attention运算的三维张量。
+返回： 形状为 :math:`[N, L_q, d_v * h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_q` 为查询序列长度， :math:`d_v * h` 为值的特征维度大小。与输入具有相同的数据类型。表示。
 
-返回类型：  变量（Variable）。
+返回类型： Variable
 
 抛出异常:    
-    - ``ValueError`` - 如果输入查询键，值不是3-D Tensor会报错。
+    - :code:`ValueError`： ``queries`` 、 ``keys`` 和 ``values`` 必须都是三维。
+    - :code:`ValueError`： ``queries`` 和 ``keys`` 的最后一维（特征维度）大小必须相同。
+    - :code:`ValueError`： ``keys`` 和 ``values`` 的第二维（长度维度）大小必须相同。
+    - :code:`ValueError`： ``keys`` 的最后一维（特征维度）大小必须是 ``num_heads`` 的整数倍。
+    - :code:`ValueError`： ``values`` 的最后一维（特征维度）大小必须是 ``num_heads`` 的整数倍。
 
-.. note::
-    当num_heads> 1时，分别学习三个线性投影，以将输入查询，键和值映射到查询'，键'和值'。 查询'，键'和值'与查询，键和值具有相同的形状。
-    当num_heads == 1时，scaled_dot_product_attention没有可学习的参数。
 
 **代码示例**