nn.Embedding/F.embedding support scale_grad_by_freq 易用性提升

docs/api/paddle/nn/Embedding_cn.rst

@@ -3,7 +3,7 @@
 Embedding
 -------------------------------
 
-.. py:class:: paddle.nn.Embedding(num_embeddings, embedding_dim, padding_idx=None, sparse=False, weight_attr=None, name=None)
+.. py:class:: paddle.nn.Embedding(num_embeddings, embedding_dim, padding_idx=None, sparse=False, weight_attr=None, scale_grad_by_freq=False, name=None)
 
 嵌入层(Embedding Layer)，用于构建 ``Embedding`` 的一个可调用对象，具体用法参照 ``代码示例``。其根据 ``x`` 中的 id 信息从 embedding 矩阵中查询对应 embedding 信息，并会根据输入的 size (num_embeddings, embedding_dim)和 weight_attr 自动构造一个二维 embedding 矩阵。
 
@@ -42,6 +42,7 @@ Embedding
     - **norm_type** (float) - 应用 ``max_norm`` 时所计算的 p 阶范数的 p 值。默认值 2.0。
     - **sparse** (bool，可选) - 是否使用稀疏更新，在词嵌入权重较大的情况下，使用稀疏更新能够获得更快的训练速度及更小的内存/显存占用。
     - **weight_attr** (ParamAttr|None，可选) - 指定嵌入向量的配置，包括初始化方法，具体用法请参见 :ref:`api_guide_ParamAttr`，一般无需设置，默认值为 None。
+    - **scale_grad_by_freq** (bool，可选) - 是否根据单词在 mini-batch 中出现频率的倒数缩放梯度。默认值 False。
     - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 

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

@@ -3,7 +3,7 @@
 embedding
 -------------------------------
 
-.. py:function:: paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, name=None)
+.. py:function:: paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, scale_grad_by_freq=False, name=None)
 
 
 
@@ -45,6 +45,7 @@ embedding
     - **max_norm** (float，可选) - 若声明，会将范数大于此值的词嵌入向量重新归一化，使其范数等于此值。在动态图模式下会对 ``weight`` 产生 inplace 修改。默认值为 None。
     - **norm_type** (float) - 应用 ``max_norm`` 时所计算的 p 阶范数的 p 值。默认值 2.0。
     - **sparse** (bool，可选) - 是否使用稀疏更新，在词嵌入权重较大的情况下，使用稀疏更新（即设置为 True）能够获得更快的训练速度及更小的内存/显存占用。但是一些优化器不支持稀疏更新，例如 :ref:`cn_api_paddle_optimizer_Adadelta` ， :ref:`cn_api_paddle_optimizer_Adamax` ， :ref:`cn_api_paddle_optimizer_Lamb` 。在这些情况下，稀疏必须为 False。默认值：False。
+    - **scale_grad_by_freq** (bool，可选) - 是否根据单词在 mini-batch 中出现频率的倒数缩放梯度。默认值 False。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 

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

@@ -1,4 +1,4 @@
-## [torch 参数更多]torch.nn.functional.embedding
+## [ 仅参数名不一致 ]torch.nn.functional.embedding
 
 ### [torch.nn.functional.embedding](https://pytorch.org/docs/stable/generated/torch.nn.functional.embedding.html)
 
@@ -9,10 +9,10 @@ torch.nn.functional.embedding(input, weight, padding_idx=None, max_norm=None, no
 ### [paddle.nn.functional.embedding](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/embedding_cn.html#embedding)
 
 ```python
-paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, name=None)
+paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, scale_grad_by_freq=False, name=None)
 ```
 
-PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+两者功能一致且参数用法一致，仅参数名不一致，具体如下：
 
 ### 参数映射
 
@@ -23,5 +23,5 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 | padding_idx        | padding_idx        | 视为填充的下标，参数完全一致。 |
 | max_norm           | max_norm           | 如果给定，Embeddding 向量的范数（范数的计算方式由 norm_type 决定）超过了 max_norm 这个界限，就要再进行归一化。        |
 | norm_type          | norm_type          | 应用 max_norm 时所计算的 p 阶范数的 p 值。               |
-| scale_grad_by_freq | -                  | 按词频进行梯度缩放的比例，参数不一致，暂无转写方式。 |
+| scale_grad_by_freq | scale_grad_by_freq  | 是否根据单词在 mini-batch 中出现频率的倒数缩放梯度。 |
 | sparse             | sparse             | 是否使用稀疏更新。            |

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

@@ -1,4 +1,4 @@
-## [ torch 参数更多 ]torch.nn.Embedding
+## [ paddle 参数更多 ]torch.nn.Embedding
 ### [torch.nn.Embedding](https://pytorch.org/docs/stable/generated/torch.nn.Embedding.html?highlight=embedding#torch.nn.Embedding)
 
 ```python
@@ -20,10 +20,11 @@ paddle.nn.Embedding(num_embeddings,
                     norm_type=2.0,
                     sparse=False,
                     weight_attr=None,
+                    scale_grad_by_freq=False,
                     name=None)
 ```
 
-PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+Paddle 相比 PyTorch 支持更多其他参数，具体如下：
 ### 参数映射
 
 | PyTorch       | PaddlePaddle | 备注                                                   |
@@ -33,6 +34,6 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 | padding_idx     | padding_idx            | 在此区间内的参数及对应的梯度将会以 0 进行填充  |
 | max_norm      | max_norm        | 如果给定，Embeddding 向量的范数（范数的计算方式由 norm_type 决定）超过了 max_norm 这个界限，就要再进行归一化。  |
 | norm_type     | norm_type    | 为 maxnorm 选项计算 p-范数的 p。默认值 2.0。  |
-| scale_grad_by_freq | -       | 是否根据单词在 mini-batch 中出现的频率，对梯度进行放缩，Paddle 无此参数，暂无转写方式。  |
+| scale_grad_by_freq | scale_grad_by_freq  | 是否根据单词在 mini-batch 中出现频率的倒数缩放梯度。  |
 | sparse     | sparse            | 表示是否使用稀疏更新。  |
 | -             | weight_attr  | 指定权重参数属性的对象，PyTorch 无此参数，Paddle 保持默认即可。  |