新增MultiLabelMarginLoss (#7331)

Author: Qin-sx

docs/api/paddle/nn/MultiLabelMarginLoss_cn

@@ -0,0 +1,41 @@
+.. _cn_api_paddle_nn_MultiLabelMarginLoss:
+
+MultiLabelMarginLoss
+-------------------------------
+
+.. py:class:: paddle.nn.MultiLabelMarginLoss(reduction='mean', name=None)
+
+创建一个 MultiLabelMarginLoss 的可调用类。通过计算输入 `input` 和 `label` 间的多类别多分类问题的 `hinge loss (margin-based loss)` 损失。
+
+损失函数计算每一个 mini-batch 的 loss 按照下列公式计算
+
+.. math::
+    \text{loss}(input_i, label_i) = \frac{\sum_{j \in \text{valid_labels}} \sum_{k \neq \text{valid_labels}} \max(0, 1 - (input_i[\text{valid_labels}[j]] - input_i[k]))}{C}
+
+其中 :math:`C` 是类别数量， :math:`\text{valid_labels}` 包含样本 :math:`i` 所有非负的标签索引（遇到第一个 -1 时停止），:math:`k` 遍历除了 :math:`\text{valid_labels}` 之外的所有类别索引。
+
+该损失函数只考虑前面的非负标签值，允许不同样本具有不同数量的目标类别。
+
+参数
+:::::::::
+    - **reduction** (str，可选) - 指定应用于输出结果的计算方式，可选值有：``'none'``、``'mean'``、``'sum'``。默认为 ``'mean'``，计算 Loss 的均值；设置为 ``'sum'`` 时，计算 Loss 的总和；设置为 ``'none'`` 时，则返回原始 Loss。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+调用参数
+:::::::::
+    - **input** (Tensor) - 数据类型是 float32、float64。
+    - **label** (Tensor) - 标签的数据类型为 int32、int64。标签值应该是类别索引（非负值）和 -1 值。-1 值会被忽略并停止处理每个样本。
+
+形状
+:::::::::
+    - **input** (Tensor) - :math:`[N, C]`，其中 N 是 batch_size， C 是类别数量。
+    - **label** (Tensor) - :math:`[N, C]`，与 input 形状相同。
+    - **output** (Tensor) - 输出的 Tensor。如果 :attr:`reduction` 是 ``'none'``，则输出的维度为 :math:`[N]`。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``，则输出的维度为 :math:`[]` 。
+
+返回
+:::::::::
+   返回计算 MultiLabelMarginLoss 的可调用对象。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.MultiLabelMarginLoss

docs/api/paddle/nn/Overview_cn.rst

@@ -281,6 +281,7 @@ Loss 层
     " :ref:`paddle.nn.TripletMarginWithDistanceLoss <cn_api_paddle_nn_TripletMarginWithDistanceLoss>` ", "TripletMarginWithDistanceLoss 层"
     " :ref:`paddle.nn.MultiLabelSoftMarginLoss <cn_api_paddle_nn_MultiLabelSoftMarginLoss>` ", "多标签 Hinge 损失层"
     " :ref:`paddle.nn.MultiMarginLoss <cn_api_paddle_nn_MultiMarginLoss>` ", "MultiMarginLoss 层"
+    " :ref:`paddle.nn.MultiLabelMarginLoss <cn_api_paddle_nn_MultiLabelMarginLoss>` ", "MultiLabelMarginLoss 层"
     " :ref:`paddle.nn.AdaptiveLogSoftmaxWithLoss <cn_api_paddle_nn_AdaptiveLogSoftmaxWithLoss>` ", "自适应 logsoftmax 损失类"
 
 
@@ -523,6 +524,7 @@ Embedding 相关函数
     " :ref:`paddle.nn.functional.hinge_embedding_loss <cn_api_paddle_nn_functional_hinge_embedding_loss>` ", "计算输入 input 和标签 label（包含 1 和 -1） 间的 `hinge embedding loss` 损失"
     " :ref:`paddle.nn.functional.rnnt_loss <cn_api_paddle_nn_functional_rnnt_loss>` ", "计算 RNNT loss，也可以叫做 softmax with RNNT"
     " :ref:`paddle.nn.functional.multi_margin_loss <cn_api_paddle_nn_functional_multi_margin_loss>` ", "用于计算 multi margin loss 损失函数"
+    " :ref:`paddle.nn.functional.multi_label_margin_loss <cn_api_paddle_nn_functional_multi_label_margin_loss>` ", "用于计算 multi label margin loss 损失函数"
     " :ref:`paddle.nn.functional.adaptive_log_softmax_with_loss <cn_api_paddle_nn_functional_adaptive_log_softmax_with_loss>` ", "自适应 logsoftmax 损失函数"
 
 

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

@@ -0,0 +1,38 @@
+.. _cn_api_paddle_nn_functional_multi_label_margin_loss:
+
+multi_label_margin_loss
+-------------------------------
+
+.. py:function:: paddle.nn.functional.multi_label_margin_loss(input, label, reduction='mean', name=None)
+
+计算输入 `input` 和 `label` 间的多类别多分类问题的 `hinge loss` 损失。
+
+损失函数计算每一个 mini-batch 的 loss 按照下列公式计算
+
+.. math::
+    \text{loss}(input_i, label_i) = \frac{\sum_{j \in \text{valid_labels}} \sum_{k \neq \text{valid_labels}} \max(0, 1 - (input_i[\text{valid_labels}[j]] - input_i[k]))}{C}
+
+其中 :math:`C` 是类别数量， :math:`\text{valid_labels}` 包含样本 :math:`i` 所有非负的标签索引（遇到第一个 -1 时停止），:math:`k` 遍历除了 :math:`\text{valid_labels}` 之外的所有类别索引。
+
+该损失函数只考虑前面的非负标签值，允许不同样本具有不同数量的目标类别。
+
+参数
+:::::::::
+    - **input** (Tensor) - :math:`[N, C]`，其中 N 是 batch_size， `C` 是类别数量。数据类型是 float32、float64。
+    - **label** (Tensor) - :math:`[N, C]`，与 input 形状相同。标签 ``label`` 的数据类型为 int32、int64。标签值应该是类别索引（非负值）和 -1 值。-1 值会被忽略并停止处理每个样本。
+    - **reduction** (str，可选) - 指定应用于输出结果的计算方式，可选值有：``'none'``， ``'mean'``， ``'sum'``。默认为 ``'mean'``，计算 Loss 的均值；设置为 ``'sum'`` 时，计算 Loss 的总和；设置为 ``'none'`` 时，则返回原始 Loss。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+形状
+:::::::::
+    - **input** (Tensor) - :math:`[N, C]`，其中 N 是 batch_size，`C` 是类别数量。数据类型是 float32、float64。
+    - **label** (Tensor) - :math:`[N, C]`，与 input 形状相同，标签 ``label`` 的数据类型为 int32、int64。
+    - **output** (Tensor) - 输出的 Tensor。如果 :attr:`reduction` 是 ``'none'``，则输出的维度为 :math:`[N]`，与 batch_size 相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``，则输出的维度为 :math:`[]` 。
+
+返回
+:::::::::
+   返回计算的 Loss。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.functional.multi_label_margin_loss

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.multilabel_margin_loss.md

@@ -0,0 +1,43 @@
+## [ torch 参数更多 ]torch.nn.functional.multilabel_margin_loss
+
+### [torch.nn.functional.multilabel\_margin\_loss](https://pytorch.org/docs/stable/generated/torch.nn.functional.multilabel_margin_loss.html)
+
+```python
+torch.nn.functional.multilabel_margin_loss(input, target, size_average=None, reduce=None, reduction='mean')
+```
+
+### [paddle.nn.functional.multi\_label\_margin\_loss](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/multi_label_margin_loss_cn.html#multi-label-margin-loss)
+
+```python
+paddle.nn.functional.multi_label_margin_loss(input, label, reduction='mean', name=None)
+```
+
+PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+
+### 参数映射
+
+| PyTorch      | PaddlePaddle | 备注 |
+| ------------ | ------------ | -- |
+| input        | input        | 输入 Tensor。 |
+| target       | label        | 标签 Tensor，仅参数名不一致。 |
+| size_average | -            | PyTorch 已弃用， Paddle 无此参数，需要转写。                  |
+| reduce       | -            | PyTorch 已弃用， Paddle 无此参数，需要转写。                  |
+| reduction    | reduction    | 指定应用于输出结果的计算方式。 |
+
+### 转写示例
+
+#### size_average、reduce
+```python
+# PyTorch 的 size_average、reduce 参数转为 Paddle 的 reduction 参数
+if size_average is None:
+    size_average = True
+if reduce is None:
+    reduce = True
+
+if size_average and reduce:
+    reduction = 'mean'
+elif reduce:
+    reduction = 'sum'
+else:
+    reduction = 'none'
+```

docs/guides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.MultiLabelMarginLoss.md

@@ -0,0 +1,40 @@
+## [torch 参数更多]torch.nn.MultiLabelMarginLoss
+
+### [torch.nn.MultiLabelMarginLoss](https://pytorch.org/docs/stable/generated/torch.nn.MultiLabelMarginLoss.html#torch.nn.MultiLabelMarginLoss)
+
+```python
+torch.nn.MultiLabelMarginLoss(size_average=None, reduce=None, reduction='mean')
+```
+
+### [paddle.nn.MultiLabelMarginLoss](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/nn/MultiLabelMarginLoss_cn.html)
+
+```python
+paddle.nn.MultiLabelMarginLoss(reduction='mean', name=None)
+```
+
+PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+
+### 参数映射
+
+| PyTorch      | PaddlePaddle | 备注                                           |
+| ------------ | ------------ | ---------------------------------------------- |
+| size_average | -            | 已废弃，和 reduce 组合决定损失计算方式。       |
+| reduce       | -            | 已废弃，和 size_average 组合决定损失计算方式。 |
+| reduction    | reduction    | 指定应用于输出结果的计算方式。                 |
+
+### 转写示例
+
+```python
+# PyTorch 的 size_average、reduce 参数转为 Paddle 的 reduction 参数
+if size_average is None:
+    size_average = True
+if reduce is None:
+    reduce = True
+
+if size_average and reduce:
+    reduction = 'mean'
+elif reduce:
+    reduction = 'sum'
+else:
+    reduction = 'none'
+```

docs/guides/model_convert/convert_from_pytorch/pytorch_api_mapping_cn.md

@@ -622,8 +622,6 @@
 | NOT-IMPLEMENTED-ITEM(`torch.special.zeta`, https://pytorch.org/docs/stable/special.html#torch.special.zeta, 可新增，且框架底层有相关设计，成本低) |
 | NOT-IMPLEMENTED-ITEM(`torch.xpu.current_device`, https://pytorch.org/docs/stable/generated/torch.xpu.current_device.html#torch-xpu-current-device, 有对应相近功能但设计差异大无法映射，一般无需新增) |
 | NOT-IMPLEMENTED-ITEM(`torch.xpu.get_device_properties`, https://pytorch.org/docs/stable/generated/torch.xpu.get_device_properties.html#torch-xpu-get-device-properties, 有对应相近功能但设计差异大无法映射，一般无需新增) |
-| NOT-IMPLEMENTED-ITEM(`torch.nn.functional.multilabel_margin_loss`, https://pytorch.org/docs/stable/generated/torch.nn.functional.multilabel_margin_loss.html#torch-nn-functional-multilabel-margin-loss, 可新增，且框架底层有相关设计，成本低) |
-| NOT-IMPLEMENTED-ITEM(`torch.nn.functional.MultiLabelMarginLoss`, https://pytorch.org/docs/stable/generated/torch.nn.MultiLabelMarginLoss.html#torch.nn.MultiLabelMarginLoss, 可新增，且框架底层有相关设计，成本低) |
 | NOT-IMPLEMENTED-ITEM(`torch.gradient`, https://pytorch.org/docs/stable/generated/torch.gradient.html#torch-gradient, 可新增，且框架底层有相关设计，成本低) |
 | NOT-IMPLEMENTED-ITEM(`torch.Tensor.sparse_resize_`, https://pytorch.org/docs/stable/generated/torch.Tensor.sparse_resize_.html#torch-tensor-sparse-resize, 可新增，且框架底层有相关设计，成本低) |
 | NOT-IMPLEMENTED-ITEM(`torch.autograd.profiler.profile`, https://pytorch.org/docs/stable/autograd.html#torch.autograd.profiler.profile, 可新增，但框架底层无相关设计，成本高) |