【PaddlePaddle Hackathon 】No.17 add docs for API CosineEmbeddingLoss

docs/api/paddle/nn/CosineEmbeddingLoss_cn.rst

@@ -0,0 +1,40 @@
+.. _cn_api_paddle_nn_CosineEmbeddingLoss:
+
+CosineEmbeddingLoss
+-------------------------------
+
+.. py:function:: paddle.nn.CosineEmbeddingLoss(margin=0, reduction='mean', name=None)
+
+该函数计算给定的输入input1, input2和label之间的 `CosineEmbedding` 损失，通常用于学习非线性嵌入或半监督学习
+
+如果label=1，则该损失函数的数学计算公式如下：
+
+    .. math::
+        Out = 1 - cos(input1, input2)
+
+如果label=-1，则该损失函数的数学计算公式如下：
+
+    .. math::
+        Out = max(0, cos(input1, input2)) - margin
+
+其中cos计算公式如下：
+
+    .. math::
+        cos(x1, x2) = \frac{x1 \cdot{} x2}{\Vert x1 \Vert_2 * \Vert x2 \Vert_2}
+
+参数
+:::::::::
+    - **margin** (float, 可选): - 可以设置的范围为[-1, 1]，建议设置的范围为[0, 0.5]。其默认为 `0` 。数据类型为int。
+    - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `CosineEmbeddingLoss` 的均值；设置为 ``'sum'`` 时，计算 `CosineEmbeddingLoss` 的总和；设置为 ``'none'`` 时，则返回 `CosineEmbeddingLoss`。数据类型为string。
+    - **name** (str，可选): - 操作的名称(可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
+
+形状
+:::::::::
+    - **input1** (Tensor): - 输入的Tensor，维度是[N, M], 其中N是batch size，可为0，M是数组长度。数据类型为：float32、float64。
+    - **input2** (Tensor): - 输入的Tensor，维度是[N, M], 其中N是batch size，可为0，M是数组长度。数据类型为：float32、float64。
+    - **label** (Tensor): - 标签，维度是[N]，N是数组长度，数据类型为：float32、float64、int32、int64。
+    - **output** (Tensor): - 输入 ``input1`` 、 ``input2`` 和标签 ``label`` 间的 `CosineEmbeddingLoss` 损失。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N], 与输入 ``input1`` 和 ``input2`` 相同。如果 `reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.CosineEmbeddingLoss:code-example1

docs/api/paddle/nn/Overview_cn.rst

@@ -248,6 +248,7 @@ Loss层
 
     " :ref:`paddle.nn.BCELoss <cn_api_paddle_nn_BCELoss>` ", "BCELoss层"
     " :ref:`paddle.nn.BCEWithLogitsLoss <cn_api_paddle_nn_BCEWithLogitsLoss>` ", "BCEWithLogitsLoss层"
+    " :ref:`paddle.nn.CosineEmbeddingLoss <cn_api_nn_loss_CosineEmbeddingLoss>` ", "CosineEmbeddingLoss层"
     " :ref:`paddle.nn.CrossEntropyLoss <cn_api_nn_loss_CrossEntropyLoss>` ", "交叉熵损失层"
     " :ref:`paddle.nn.CTCLoss <cn_api_paddle_nn_CTCLoss>` ", "CTCLoss层"
     " :ref:`paddle.nn.HSigmoidLoss <cn_api_paddle_nn_HSigmoidLoss>` ", "层次sigmoid损失层"
@@ -463,6 +464,7 @@ Embedding相关函数
 
     " :ref:`paddle.nn.functional.binary_cross_entropy <cn_api_nn_functional_binary_cross_entropy>` ", "二值交叉熵损失值"
     " :ref:`paddle.nn.functional.binary_cross_entropy_with_logits <cn_api_paddle_nn_functional_binary_cross_entropy_with_logits>` ", "logits二值交叉熵损失值"
+    " :ref:`paddle.nn.functional.cosine_embedding_loss <cn_paddle_nn_functional_cosine_embedding_loss>` ", "用于计算余弦相似度损失"
     " :ref:`paddle.nn.functional.ctc_loss <cn_paddle_nn_functional_loss_ctc>` ", "用于计算ctc损失"
     " :ref:`paddle.nn.functional.dice_loss <cn_api_fluid_layers_dice_loss>` ", "用于比较预测结果跟标签之间的相似度"
     " :ref:`paddle.nn.functional.hsigmoid_loss <cn_api_nn_functional_hsigmoid_loss>` ", "层次sigmoid损失函数"

docs/api/paddle/nn/functional/cosine_embedding_loss_cn.rst

@@ -0,0 +1,42 @@
+.. _cn_paddle_nn_functional_loss_cosine_embedding_loss:
+
+cosine_embedding_loss
+-------------------------------
+
+.. py:function:: paddle.nn.functional.cosine_embedding_loss(input1, input2, label, margin=0, reduction='mean', name=None)
+
+该函数计算输入input1, input2和label之间的 `CosineEmbedding` 损失
+
+如果label=1，则该损失函数的数学计算公式如下：
+
+    .. math::
+        Out = 1 - cos(input1, input2)
+
+如果label=-1，则该损失函数的数学计算公式如下：
+
+    .. math::
+        Out = max(0, cos(input1, input2)) - margin
+
+其中cos计算公式如下：
+
+    .. math::
+        cos(x1, x2) = \frac{x1 \cdot{} x2}{\Vert x1 \Vert_2 * \Vert x2 \Vert_2}
+
+参数
+:::::::::
+    - **input1** (Tensor): - 输入的Tensor，维度是[N, M], 其中N是batch size，可为0，M是数组长度。数据类型为：float32、float64。
+    - **input2** (Tensor): - 输入的Tensor，维度是[N, M], 其中N是batch size，可为0，M是数组长度。数据类型为：float32、float64。
+    - **label** (Tensor): - 标签，维度是[N]，N是数组长度，数据类型为：float32、float64、int32、int64。
+    - **margin** (float, 可选): - 可以设置的范围为[-1, 1]，建议设置的范围为[0, 0.5]。其默认为 `0` 。数据类型为float。
+    - **reduction** (string, 可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `CosineEmbeddingLoss` 的均值；设置为 ``'sum'`` 时，计算 `CosineEmbeddingLoss` 的总和；设置为 ``'none'`` 时，则返回 `CosineEmbeddingLoss`。数据类型为string。
+    - **name** (str，可选): - 操作的名称(可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
+
+返回
+:::::::::
+``Tensor``，输入 ``input1`` 、 ``input2`` 和标签 ``label`` 间的 `CosineEmbeddingLoss` 损失。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N], 与输入 ``input1`` 和 ``input2`` 相同。如果 `reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。
+
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.functional.cosine_embedding_loss:code-example1
+