易用性提升已修改的58个API核对 - part2 (PaddlePaddle#6849)

* update * update * add histogram_bin_edges * update histogram_bin_edges tensor method * update torch.Tensor.histogram api_convert * update * update * fix * update * update * update torch.embedding
HydrogenSulfate · Sep 13, 2024 · f62dbc5 · f62dbc5
1 parent 92eae9f
commit f62dbc5
Show file tree

Hide file tree

Showing 15 changed files with 112 additions and 36 deletions.
diff --git a/docs/api/paddle/Overview_cn.rst b/docs/api/paddle/Overview_cn.rst
@@ -373,6 +373,7 @@ tensor 线性代数相关
     " :ref:`paddle.cross <cn_api_paddle_cross>` ", "计算 Tensor x 和 y 在 axis 维度上的向量积（叉积）"
     " :ref:`paddle.dist <cn_api_paddle_dist>` ", "计算 (x-y) 的 p 范数（p-norm）"
     " :ref:`paddle.dot <cn_api_paddle_dot>` ", "计算向量的内积"
+    " :ref:`paddle.histogram_bin_edges <cn_api_paddle_histogram_bin_edges>` ", "返回计算 input 的直方图时所使用的 bins 的边界值 bin_edges"
     " :ref:`paddle.histogram <cn_api_paddle_histogram>` ", "计算输入 Tensor 的直方图"
     " :ref:`paddle.histogramdd <cn_api_paddle_histogramdd>` ", "计算输入多维 Tensor 的直方图"
     " :ref:`paddle.matmul <cn_api_paddle_matmul>` ", "计算两个 Tensor 的乘积，遵循完整的广播规则"

diff --git a/docs/api/paddle/Tensor/Overview_en.rst b/docs/api/paddle/Tensor/Overview_en.rst
@@ -143,6 +143,7 @@ Methods
     gradient
     greater_equal
     greater_than
+    histogram_bin_edges
     histogram
     imag
     increment

diff --git a/docs/api/paddle/Tensor_cn.rst b/docs/api/paddle/Tensor_cn.rst
@@ -1371,6 +1371,15 @@ heaviside(y, name=None)
 
 请参考 :ref:`cn_api_paddle_heaviside`
 
+histogram_bin_edges(bins=100, min=0, max=0)
+:::::::::
+
+返回：计算后的 Tensor
+
+返回类型：Tensor
+
+请参考 :ref:`cn_api_paddle_histogram_bin_edges`
+
 histogram(bins=100, min=0, max=0)
 :::::::::
 

diff --git a/docs/api/paddle/histogram_bin_edges_cn.rst b/docs/api/paddle/histogram_bin_edges_cn.rst
@@ -0,0 +1,26 @@
+.. _cn_api_paddle_histogram_bin_edges:
+
+histogram_bin_edges
+-------------------------------
+
+.. py:function:: paddle.histogram_bin_edges(input, bins=100, min=0, max=0, name=None)
+
+只返回在计算 ``input`` 的直方图时所使用的 bins 的边界值 bin_edges。如果 min 和 max 都为 0，则利用数据中的最大最小值作为边界。
+
+参数
+::::::::::::
+
+    - **input** (Tensor) - 输入 Tensor。维度为多维，数据类型为 int32、int64、float32 或 float64。
+    - **bins** (int，可选) - 直方图 bins(直条)的个数，默认为 100。
+    - **min** (int，可选) - range 的下边界(包含)，默认为 0。
+    - **max** (int，可选) - range 的上边界(包含)，默认为 0。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+::::::::::::
+Tensor，计算直方图时所使用的边界值 bin_edges，返回的数据类型为 float32。
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.histogram_bin_edges
diff --git a/docs/api/paddle/nn/Embedding_cn.rst b/docs/api/paddle/nn/Embedding_cn.rst
@@ -38,6 +38,8 @@ Embedding
     - **num_embeddings** (int) - 嵌入字典的大小，input 中的 id 必须满足 ``0 <= id < num_embeddings`` 。
     - **embedding_dim** (int) - 每个嵌入向量的维度。
     - **padding_idx** (int|long|None，可选) - padding_idx 的配置区间为 ``[-weight.shape[0], weight.shape[0])``，如果配置了 padding_idx，那么在训练过程中遇到此 id 时，其参数及对应的梯度将会以 0 进行填充。
+    - **max_norm** (float，可选) - 若声明，会将范数大于此值的词嵌入向量重新归一化，使其范数等于此值。在动态图模式下会对 ``weight`` 产生 inplace 修改。默认值为 None。
+    - **norm_type** (float) - 应用 ``max_norm`` 时所计算的 p 阶范数的 p 值。默认值 2.0。
     - **sparse** (bool，可选) - 是否使用稀疏更新，在词嵌入权重较大的情况下，使用稀疏更新能够获得更快的训练速度及更小的内存/显存占用。
     - **weight_attr** (ParamAttr|None，可选) - 指定嵌入向量的配置，包括初始化方法，具体用法请参见 :ref:`api_guide_ParamAttr`，一般无需设置，默认值为 None。
     - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。

diff --git a/docs/api/paddle/nn/ThresholdedReLU_cn.rst b/docs/api/paddle/nn/ThresholdedReLU_cn.rst
@@ -8,16 +8,20 @@ Thresholded ReLU 激活层
 
 .. math::
 
-    ThresholdedReLU(x) = \begin{cases}
-                          x, \text{if } x > threshold \\
-                          0, \text{otherwise}
-                         \end{cases}
+    ThresholdedReLU(x) =
+        \left\{
+            \begin{array}{rl}
+            x,& \text{if } \ x > threshold \\
+            value,& \text{otherwise}
+            \end{array}
+        \right.
 
 其中，:math:`x` 为输入的 Tensor。
 
 参数
 ::::::::::
     - **threshold** (float，可选) - ThresholdedReLU 激活计算公式中的 threshold 值。默认值为 1.0。
+    - **value** (float，可选) - 当 ``x`` 小于 ``threshold`` 时的替换值。默认值为 0.0。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 形状

diff --git a/docs/api/paddle/nn/functional/embedding_cn.rst b/docs/api/paddle/nn/functional/embedding_cn.rst
@@ -3,7 +3,7 @@
 embedding
 -------------------------------
 
-.. py:function:: paddle.nn.functional.embedding(x, weight, padding_idx=None, sparse=False, name=None)
+.. py:function:: paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, name=None)
 
 
 
@@ -41,8 +41,10 @@ embedding
 
     - **input** (Tensor) - 存储 id 信息的 Tensor，数据类型必须为：int32/int64。input 中的 id 必须满足 ``0 =< id < size[0]`` 。
     - **weight** (Tensor) - 存储词嵌入权重参数的 Tensor，形状为(num_embeddings, embedding_dim)。
-    - **sparse** (bool，可选) - 是否使用稀疏更新，在词嵌入权重较大的情况下，使用稀疏更新（即设置为 True）能够获得更快的训练速度及更小的内存/显存占用。但是一些优化器不支持稀疏更新，例如 :ref:`cn_api_paddle_optimizer_Adadelta` ， :ref:`cn_api_paddle_optimizer_Adamax` ， :ref:`cn_api_paddle_optimizer_Lamb` 。在这些情况下，稀疏必须为 False。默认值：False。
     - **padding_idx** (int|long|None，可选) - padding_idx 的配置区间为 ``[-weight.shape[0], weight.shape[0]``，如果配置了 padding_idx，那么在训练过程中遇到此 id 时，其参数及对应的梯度将会以 0 进行填充。如果 padding_idx < 0 ，则 padding_idx 将自动转换到 ``weight.shape[0] + padding_idx`` 。如果设置为 "None"，则不会对输出产生影响。默认值：None。
+    - **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。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 

diff --git a/docs/api/paddle/nn/functional/thresholded_relu__cn.rst b/docs/api/paddle/nn/functional/thresholded_relu__cn.rst
@@ -3,7 +3,7 @@
 thresholded_relu\_
 -------------------------------
 
-.. py:function:: paddle.nn.functional.thresholded_relu_(x, threshold=1.0, name=None)
+.. py:function:: paddle.nn.functional.thresholded_relu_(x, threshold=1.0, value=0.0, name=None)
 Inplace 版本的 :ref:`cn_api_paddle_nn_functional_thresholded_relu` API，对输入 x 采用 Inplace 策略。
 
 更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。

diff --git a/docs/api/paddle/nn/functional/thresholded_relu_cn.rst b/docs/api/paddle/nn/functional/thresholded_relu_cn.rst
@@ -3,16 +3,19 @@
 thresholded_relu
 -------------------------------
 
-.. py:function:: paddle.nn.functional.thresholded_relu(x, threshold=1.0, name=None)
+.. py:function:: paddle.nn.functional.thresholded_relu(x, threshold=1.0, value=0.0, name=None)
 
 thresholded relu 激活层。计算公式如下：
 
 .. math::
 
-    thresholded\_relu(x) = \begin{cases}
-                            x, \text{if } x > threshold \\
-                            0, \text{otherwise}
-                           \end{cases}
+    thresholded\_relu(x) =
+        \left\{
+            \begin{array}{rl}
+            x,& \text{if } \ x > threshold \\
+            value,& \text{otherwise}
+            \end{array}
+        \right.
 
 其中，:math:`x` 为输入的 Tensor。
 
@@ -21,6 +24,7 @@ thresholded relu 激活层。计算公式如下：
 ::::::::::
     - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。
     - **threshold** (float，可选) - thresholded_relu 激活计算公式中的 threshold 值。默认值为 1.0。
+    - **value** (float，可选) - 当 ``x`` 小于 ``threshold`` 时的替换值。默认值为 0.0。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 返回

diff --git a/...el_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.histogram.md b/...el_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.histogram.md
@@ -1,4 +1,4 @@
-## [torch 参数更多]torch.Tensor.histogram
+## [ 组合替代实现 ]torch.Tensor.histogram
 
 ### [torch.Tensor.histogram](https://pytorch.org/docs/stable/generated/torch.Tensor.histogram.html#torch.Tensor.histogram)
 
@@ -9,19 +9,20 @@ torch.Tensor.histogram(bins, *, range=None, weight=None, density=False)
 ### [paddle.Tensor.histogram](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/Tensor_cn.html#histogram-bins-100-min-0-max-0)
 
 ```python
-paddle.Tensor.histogram(bins=100, min=0, max=0)
+paddle.Tensor.histogram(bins=100, min=0, max=0, weight=None, density=False)
 ```
 
-PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+其中 PyTorch 的 `range` 与 Paddle 用法不一致，需要转写；且返回参数 Tensor 数量不一致，需要通过 paddle.Tensor.histogram 和 paddle.Tensor.histogram_bin_edges 组合实现。具体如下：
 
 ### 参数映射
 
 | PyTorch | PaddlePaddle | 备注                                                                                               |
 | ------- | ------------ | -------------------------------------------------------------------------------------------------- |
 | bins    | bins         | 直方图 bins(直条)的个数。                                                                          |
 | range   | min, max     | PyTorch 为 bins 的范围，类型为 float，Paddle 为 range 的下边界，上边界，类型为 int，需要转写。 |
-| weight  | -            | 权重，Paddle 无此参数，暂无转写方式。   |
-| density | -            | 结果中每个 bin 是否包含权重数，Paddle 无此参数，暂无转写方式。   |
+| weight  | weight       | 权重 Tensor，维度和 input 相同。    |
+| density | density      | 表示直方图返回值是 count 还是归一化的频率，默认值 False 表示返回的是 count。  |
+| 返回值  | 返回值       | PyTorch 返回 hist 和 bin_edges，paddle.Tensor.histogram 返回 hist，paddle.Tensor.histogram_bin_edges 返回 bin_edges，需要转写。                                 |
 
 ### 转写示例
 
@@ -30,9 +31,21 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 ```python
 # PyTorch 写法:
 x = torch.tensor([1., 2, 1])
-y = x.histogram(bins=5, range=(0., 3.))
+hist, _ = x.histogram(bins=5, range=(0., 3.))
 
 # Paddle 写法:
 x = paddle.to_tensor([1, 2, 1])
-y = x.histogram(bins=5, min=0, max=3)
+hist = x.histogram(bins=5, min=0, max=3)
+```
+
+#### 返回值
+
+```python
+# PyTorch 写法:
+x = torch.tensor([1., 2, 1])
+hist, bin_edges = x.histogram(x, bins=5)
+
+# Paddle 写法:
+x = paddle.to_tensor([1, 2, 1])
+hist, bin_edges = x.histogram(x, bins=5), x.histogram_bin_edges(x, bins=5)
 ```
diff --git a/...convert_from_pytorch/api_difference/functional/torch.nn.functional.embedding.md b/...convert_from_pytorch/api_difference/functional/torch.nn.functional.embedding.md
@@ -9,7 +9,7 @@ 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, sparse=False, name=None)
+paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, name=None)
 ```
 
 PyTorch 相比 Paddle 支持更多其他参数，具体如下：
@@ -21,7 +21,7 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 | input              | x                  | 输入 Tensor，仅参数名不同。   |
 | weight             | weight             | 嵌入矩阵权重。                |
 | padding_idx        | padding_idx        | 视为填充的下标，参数完全一致。 |
-| max_norm           | -                  | 重新归一化的最大范数，参数不一致，暂无转写方式。        |
-| norm_type          | -                  | Paddle 无此参数，参数不一致，暂无转写方式。                  |
+| max_norm           | max_norm           | 如果给定，Embeddding 向量的范数（范数的计算方式由 norm_type 决定）超过了 max_norm 这个界限，就要再进行归一化。        |
+| norm_type          | norm_type          | 应用 max_norm 时所计算的 p 阶范数的 p 值。               |
 | scale_grad_by_freq | -                  | 按词频进行梯度缩放的比例，参数不一致，暂无转写方式。 |
 | sparse             | sparse             | 是否使用稀疏更新。            |
diff --git a/...convert_from_pytorch/api_difference/functional/torch.nn.functional.threshold.md b/...convert_from_pytorch/api_difference/functional/torch.nn.functional.threshold.md
@@ -9,7 +9,7 @@ torch.nn.functional.threshold(input, threshold, value, inplace=False)
 ### [paddle.nn.functional.thresholded_relu](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/nn/functional/thresholded_relu_cn.html)
 
 ```python
-paddle.nn.functional.thresholded_relu(x, threshold=1.0, name=None)
+paddle.nn.functional.thresholded_relu(x, threshold=1.0, value=0.0, name=None)
 ```
 
 PyTorch 相比 Paddle 支持更多其他参数，具体如下：
@@ -20,5 +20,5 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 | --------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
 | input     | x            | 输入的 Tensor，仅参数名不一致。                                                                                 |
 | threshold | threshold    | thresholded_relu 激活计算公式中的 threshold 值。                                                                |
-| value     | -            | 不在指定 threshold 范围时的值，Paddle 取值为 0，暂无转写方式。                                                  |
+| value     | value        | 不在指定 threshold 范围时的值。                                                  |
 | inplace   | -            | 表示在不更改变量的内存地址的情况下，直接修改变量的值，Paddle 无此参数，一般对网络训练结果影响不大，可直接删除。 |
diff --git a/...ides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.Embedding.md b/...ides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.Embedding.md
@@ -16,6 +16,8 @@ torch.nn.Embedding(num_embeddings,
 paddle.nn.Embedding(num_embeddings,
                     embedding_dim,
                     padding_idx=None,
+                    max_norm=None,
+                    norm_type=2.0,
                     sparse=False,
                     weight_attr=None,
                     name=None)
@@ -29,8 +31,8 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 | num_embeddings     | num_embeddings            | 表示嵌入字典的大小。  |
 | embedding_dim     | embedding_dim            | 表示每个嵌入向量的维度。  |
 | padding_idx     | padding_idx            | 在此区间内的参数及对应的梯度将会以 0 进行填充  |
-| max_norm      | -            | 如果给定，Embeddding 向量的范数（范数的计算方式由 norm_type 决定）超过了 max_norm 这个界限，就要再进行归一化，Paddle 无此参数，暂无转写方式。  |
-| norm_type     | -            | 为 maxnorm 选项计算 p-范数的 p。默认值 2，Paddle 无此参数，暂无转写方式。  |
+| 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 无此参数，暂无转写方式。  |
 | sparse     | sparse            | 表示是否使用稀疏更新。  |
 | -             | weight_attr  | 指定权重参数属性的对象，PyTorch 无此参数，Paddle 保持默认即可。  |
diff --git a/...ides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.Threshold.md b/...ides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.Threshold.md
@@ -9,7 +9,7 @@ torch.nn.Threshold(threshold, value, inplace=False)
 ### [paddle.nn.ThresholdedReLU](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/nn/ThresholdedReLU_cn.html)
 
 ```python
-paddle.nn.ThresholdedReLU(threshold=1.0, name=None)
+paddle.nn.ThresholdedReLU(threshold=1.0, value=0.0, name=None)
 ```
 
 PyTorch 相比 Paddle 支持更多其他参数，具体如下：
@@ -19,5 +19,5 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
 | PyTorch   | PaddlePaddle | 备注                                                                                                            |
 | --------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
 | threshold | threshold    | ThresholdedReLU 激活计算公式中的 threshold 值。                                                                 |
-| value     | -            | 不在指定 threshold 范围时的值，Paddle 无此参数，暂无转写方式。   |
+| value     | value        | 不在指定 threshold 范围时的值。   |
 | inplace   | -            | 表示在不更改变量的内存地址的情况下，直接修改变量的值，Paddle 无此参数，一般对网络训练结果影响不大，可直接删除。 |