【Hackathon 6th No.1】Add AdaptiveLogSoftmaxWithLoss docs API to Paddle

docs/api/paddle/nn/AdaptiveLogSoftmaxWithLoss_cn.rst

@@ -0,0 +1,43 @@
+.. _cn_api_paddle_nn_AdaptiveLogSoftmaxWithLoss:
+
+AdaptiveLogSoftmaxWithLoss
+-------------------------------
+
+.. py:class:: paddle.nn.AdaptiveLogSoftmaxWithLoss(in_features, n_classes, cutoffs, div_value=4.0, head_bias=False, name=None)
+AdaptiveLogSoftmaxWithLoss 是一种高效的策略，通常用于自然语言处理任务中的语言模型训练，尤其是在处理具有大量词汇且标签分布显著不平衡的语料库时。
+
+AdaptiveLogSoftmaxWithLoss 将标签按照频率划分为多个组，每个组包含的目标数量不同，且在频率较低的标签所在的组中会采用较低维度的嵌入，从而显著减少计算量。
+
+在每个训练的小批量中，只有当至少有一个目标标签出现时，相应的组才会被计算。这种方法的设计理念是，频繁访问的组（如包含最常见标签的初始组）应该具有较低的计算成本。
+
+对于参数 ``cutoffs``，按升序排序的整数序列。它控制组的数量和目标分配到组的方式。例如，设置 ``cutoffs = [10, 100, 1000]`` 意味着前 10 个目标将分配到 AdaptiveLogSoftmaxWithLoss 的 ``head``，目标 11, 12, ..., 100 将分配到第一个组，而目标 101, 102, ..., 1000 将分配到第二个组，而目标 1001, 1002, ..., n_classes - 1 将分配到第三个组。
+
+对于参数 ``div_value``，用于计算每个附加组的大小，其值为 :math:`\left\lfloor \frac{\text{in\_features}}{\text{div\_value}^{\text{idx}}} \right\rfloor`，其中 ``idx`` 是组索引（对于较不频繁的单词，组索引较大，索引从 :math:`1` 开始）。
+
+对于参数 ``head_bias``，如果设置为 True，将在 AdaptiveLogSoftmaxWithLoss 的 ``head`` 上添加偏置项。详细信息请参阅论文：https://arxiv.org/abs/1609.04309 。
+
+
+
+参数
+:::::::::
+    - **in_features** (int): 输入 Tensor 的特征数量。
+    - **n_classes** (int): 数据集中类型的个数。
+    - **cutoffs** (Sequence): 用于将 label 分配到不同存储组的截断值。
+    - **div_value** (float, 可选): 用于计算组大小的指数值。默认值：4.0。
+    - **head_bias** (bool, 可选): 如果为 ``True``，AdaptiveLogSoftmaxWithLoss 的 ``head`` 添加偏置项。默认值： ``False``.
+    - **name** (str, 可选): 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+形状
+:::::::::
+    - **input** (Tensor): - 输入 Tensor，形状为 ``[N, in_features]``， ``N`` 是批尺寸。
+    - **label** (Tensor): - 目标值，形状为 ``[N]``。
+    - **output1** (Tensor): - 形状为 ``[N]``。
+    - **output2** (Scalar): - 标量，无形状
+
+返回
+:::::::::
+用于计算自适应 softmax 的可调用对象。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.AdaptiveLogSoftmaxWithLoss

docs/api/paddle/nn/Overview_cn.rst

@@ -272,6 +272,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.AdaptiveLogSoftmaxWithLoss <_cn_api_paddle_nn_AdaptiveLogSoftmaxWithLoss>` ", "自适应 logsoftmax 损失类"
 
 
 .. _vision_layers:
@@ -508,6 +509,7 @@ Embedding 相关函数
     " :ref:`paddle.nn.functional.triplet_margin_with_distance_loss <cn_api_paddle_nn_functional_triplet_margin_with_distance_loss>` ", "用户自定义距离函数用于计算 triplet margin loss 损失"
     " :ref:`paddle.nn.functional.multi_label_soft_margin_loss <cn_api_paddle_nn_functional_multi_label_soft_margin_loss>` ", "用于计算多分类的 hinge loss 损失函数"
     " :ref:`paddle.nn.functional.multi_margin_loss <cn_api_paddle_nn_functional_multi_margin_loss>` ", "用于计算 multi margin loss 损失函数"
+    " :ref:`paddle.nn.functional.adaptive_log_softmax_with_loss <cn_api_paddle_nn_functional_adaptive_log_softmax_with_loss>` ", "自适应 logsoftmax 损失函数"
 
 
 .. _common_functional:

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

@@ -0,0 +1,29 @@
+.. _cn_api_paddle_nn_functional_adaptive_log_softmax_with_loss:
+
+adaptive_log_softmax_with_loss
+-------------------------------
+
+.. py:function:: paddle.nn.functional.adaptive_log_softmax_with_loss(input, label, head_weight, tail_weights, cutoffs, head_bias=None, name=None)
+
+计算自适应 logsoftmax 结果以及 input 和 label 之间的负对数似然。参数 `head_weight`、`tail_weights`、`cutoffs`和 `head_bias` 是 `AdaptiveLogSoftmaxWithLoss` 的内部成员。
+请参考：:ref:`cn_api_paddle_nn_AdaptiveLogSoftmaxWithLoss`
+
+
+参数
+:::::::::
+    - **input** (Tensor): 输入张量，数据类型为 float32 或 float64。
+    - **label** (Tensor): 标签张量，数据类型为 float32 或 float64。
+    - **head_weight** (Tensor): 用于线性计算的权重矩阵，数据类型为 float32 或 float64。
+    - **tail_weights** (Tensor): 用于线性计算的权重矩阵，数据类型为 float32 或 float64。
+    - **cutoffs** (Sequence): 用于将 label 分配到不同存储桶的截断值。
+    - **head_bias** (Tensor, 可选): 用于线性计算的偏置矩阵，数据类型为 float32 或 float64。
+    - **name** (str, 可选): 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+:::::::::
+    - **output** (Tensor): - 自适应 logsoftmax 计算结果，形状为[N]。
+    - **loss** (Tensor): - input 和 label 之间的 logsoftmax 损失值。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.functional.adaptive_log_softmax_with_loss