From 37c5dea08c8d27f5e0928f666ef8d362551562e2 Mon Sep 17 00:00:00 2001 From: manfredss Date: Tue, 11 Aug 2026 15:04:23 +0800 Subject: [PATCH 01/18] stage 1 check & update --- docs/api/paddle/abs_cn.rst | 8 ++++++-- docs/api/paddle/addr_cn.rst | 3 +-- docs/api/paddle/bmm_cn.rst | 9 +++++---- docs/api/paddle/gcd_cn.rst | 6 +++++- docs/api/paddle/lcm_cn.rst | 6 +++++- docs/api/paddle/nn/LeakyReLU_cn.rst | 3 ++- docs/api/paddle/nn/ReLU_cn.rst | 3 ++- docs/api/paddle/tanh_cn.rst | 10 +++++++--- docs/api/paddle/uniform_cn.rst | 12 +++++++++--- 9 files changed, 42 insertions(+), 18 deletions(-) diff --git a/docs/api/paddle/abs_cn.rst b/docs/api/paddle/abs_cn.rst index 83fa2c88d48..73f4958f216 100644 --- a/docs/api/paddle/abs_cn.rst +++ b/docs/api/paddle/abs_cn.rst @@ -3,7 +3,7 @@ abs ------------------------------- -.. py:function:: paddle.abs(x, name=None) +.. py:function:: paddle.abs(x, name=None, *, out=None) @@ -15,9 +15,13 @@ abs 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64、complex64、complex128。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: 输出 Tensor，与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/addr_cn.rst b/docs/api/paddle/addr_cn.rst index e7d781d63ec..402d40606d7 100644 --- a/docs/api/paddle/addr_cn.rst +++ b/docs/api/paddle/addr_cn.rst @@ -3,7 +3,7 @@ addr ------------------------------- -.. py:function:: paddle.addr(input, vec1, vec2, beta=1, alpha=1, name=None, *, out=None) +.. py:function:: paddle.addr(input, vec1, vec2, beta=1, alpha=1, *, out=None) 执行向量 ``vec1`` 和向量 ``vec2`` 的外积，并将其加到输入矩阵上。 @@ -16,7 +16,6 @@ addr - **vec2** (Tensor) - 第二个向量。 - **beta** (float，可选) - input 的乘数，默认值为 1。 - **alpha** (float，可选) - 外积的乘数，默认值为 1。 - - **name** (str，可选) - 操作名称，默认值为 None。 关键字参数 ::::::::: diff --git a/docs/api/paddle/bmm_cn.rst b/docs/api/paddle/bmm_cn.rst index f982f6099d9..4b469e8ce60 100644 --- a/docs/api/paddle/bmm_cn.rst +++ b/docs/api/paddle/bmm_cn.rst @@ -3,7 +3,7 @@ bmm ------------------------------- -.. py:function:: paddle.bmm(x, y, name=None, *, out=None) +.. py:function:: paddle.bmm(x, y, out_dtype=None, name=None, *, out=None) @@ -17,8 +17,9 @@ bmm 参数 ::::::::: - - **x** (Tensor) - 输入变量，类型为 Tensor。别名 ``input``。 - - **y** (Tensor) - 输入变量，类型为 Tensor。别名 ``other``。 + - **x** (Tensor) - 第一个输入 Tensor。别名 ``input``。 + - **y** (Tensor) - 第二个输入 Tensor。别名 ``mat2``。 + - **out_dtype** (paddle.dtype|None，可选) - 输出的数据类型。目前仅支持在动态图中将 CUDA 上数据类型为 float16 或 bfloat16 的输入转换为 ``paddle.float32`` 输出，两个输入 Tensor 的数据类型必须相同。为保持向后兼容性，当恰好传入三个位置参数且第三个参数为字符串时，该参数会被视为 ``name``。如需以位置参数传入 ``out_dtype``，请使用 ``paddle.float32`` 等数据类型对象；若使用字符串数据类型，请通过 ``out_dtype="float32"`` 传入。当第 4 个位置参数提供 ``name`` 时，字符串数据类型也可作为第 3 个位置参数传入，例如 ``paddle.bmm(x, y, "float32", "my_name")``。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 @@ -28,7 +29,7 @@ bmm 返回 ::::::::: -Tensor，矩阵相乘后的结果。 +Tensor，批量矩阵相乘后的结果。未指定 ``out_dtype`` 时，输出的数据类型与输入相同。 代码示例 ::::::::: diff --git a/docs/api/paddle/gcd_cn.rst b/docs/api/paddle/gcd_cn.rst index 8dae5949aea..8219e04a348 100644 --- a/docs/api/paddle/gcd_cn.rst +++ b/docs/api/paddle/gcd_cn.rst @@ -3,7 +3,7 @@ gcd ------------------------------- -.. py:function:: paddle.gcd(x, y, name=None) +.. py:function:: paddle.gcd(x, y, name=None, *, out=None) 计算两个输入的按元素绝对值的最大公约数，输入必须是整型。 @@ -23,6 +23,10 @@ gcd - **y** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。支持别名 ``other`` 。 - **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/lcm_cn.rst b/docs/api/paddle/lcm_cn.rst index 04439944401..2698753d80c 100644 --- a/docs/api/paddle/lcm_cn.rst +++ b/docs/api/paddle/lcm_cn.rst @@ -3,7 +3,7 @@ lcm ------------------------------- -.. py:function:: paddle.lcm(x, y, name=None) +.. py:function:: paddle.lcm(x, y, name=None, *, out=None) 计算两个输入的按元素绝对值的最小公倍数，输入必须是整型。 @@ -23,6 +23,10 @@ lcm - **y** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。支持别名 ``other`` 。 - **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/nn/LeakyReLU_cn.rst b/docs/api/paddle/nn/LeakyReLU_cn.rst index 18240efc1db..723d0ffc9b2 100644 --- a/docs/api/paddle/nn/LeakyReLU_cn.rst +++ b/docs/api/paddle/nn/LeakyReLU_cn.rst @@ -2,7 +2,7 @@ LeakyReLU ------------------------------- -.. py:class:: paddle.nn.LeakyReLU(negative_slope=0.01, name=None) +.. py:class:: paddle.nn.LeakyReLU(negative_slope=0.01, inplace=False, name=None) LeakyReLU 激活层，创建一个可调用对象以计算输入 ``x`` 的 ``LeakReLU`` 。 @@ -21,6 +21,7 @@ LeakyReLU 激活层，创建一个可调用对象以计算输入 ``x`` 的 ``Lea 参数 :::::::::: - **negative_slope** (float，可选) - :math:`x < 0` 时的斜率。默认值为 0.01。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/ReLU_cn.rst b/docs/api/paddle/nn/ReLU_cn.rst index f0bd5427dab..f16626748dd 100644 --- a/docs/api/paddle/nn/ReLU_cn.rst +++ b/docs/api/paddle/nn/ReLU_cn.rst @@ -2,7 +2,7 @@ ReLU ------------------------------- -.. py:class:: paddle.nn.ReLU(name=None) +.. py:class:: paddle.nn.ReLU(inplace=False, name=None) ReLU 激活层（Rectified Linear Unit）。计算公式如下： @@ -14,6 +14,7 @@ ReLU 激活层（Rectified Linear Unit）。计算公式如下： 参数 :::::::::: + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/tanh_cn.rst b/docs/api/paddle/tanh_cn.rst index 2c2d25c6a0c..780c0624715 100644 --- a/docs/api/paddle/tanh_cn.rst +++ b/docs/api/paddle/tanh_cn.rst @@ -3,7 +3,7 @@ tanh ------------------------------- -.. py:function:: paddle.tanh(x, name=None) +.. py:function:: paddle.tanh(x, name=None, *, out=None) tanh 激活函数 @@ -15,12 +15,16 @@ tanh 激活函数 ::::::::: - - **x** (Tensor) - Tanh 算子的输入，多维 Tensor，数据类型为 bfloat16，float16，float32 或 float64。 + - **x** (Tensor) - Tanh 算子的输入，多维 Tensor，数据类型为 bfloat16、float16、float32、float64、uint8、int8、int16、int32 或 int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: -tanh 的输出 Tensor，和输入有着相同类型和 shape。 +tanh 的输出 Tensor，和输入具有相同的类型和 shape；整数类型输入会自动转换为 float32。 代码示例 diff --git a/docs/api/paddle/uniform_cn.rst b/docs/api/paddle/uniform_cn.rst index 7cb7a45cf4d..65f5a987f58 100644 --- a/docs/api/paddle/uniform_cn.rst +++ b/docs/api/paddle/uniform_cn.rst @@ -3,7 +3,7 @@ uniform ------------------------------- -.. py:function:: paddle.uniform(shape, dtype=None, min=-1.0, max=1.0, seed=0, name=None) +.. py:function:: paddle.uniform(shape, dtype=None, min=0, max=1.0, seed=0, name=None, *, out=None, device=None, requires_grad=False) @@ -22,12 +22,18 @@ uniform :::::::::::: - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64。默认值为 None。 - - **min** (float|int，可选) - 要生成的随机值范围的下限，min 包含在范围中。支持的数据类型：float、int。默认值为-1.0。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64、complex64、complex128。默认值为 None，此时使用全局默认数据类型，详细信息请参见 :ref:`cn_api_paddle_get_default_dtype` 。 + - **min** (float|int，可选) - 要生成的随机值范围的下限，min 包含在范围中。支持的数据类型：float、int。默认值为 0。 - **max** (float|int，可选) - 要生成的随机值范围的上限，max 不包含在范围中。支持的数据类型：float、int。默认值为 1.0。 - **seed** (int，可选) - 随机种子，用于生成样本。0 表示使用系统生成的种子。注意如果种子不为 0，该操作符每次都生成同样的随机数。支持的数据类型：int。默认为 0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时使用当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::::: From 4570ccc728c1798d1c06d7bd2a95dc8aff6ba383 Mon Sep 17 00:00:00 2001 From: manfredss Date: Tue, 11 Aug 2026 15:24:41 +0800 Subject: [PATCH 02/18] add three log apis --- docs/api/paddle/log10_cn.rst | 8 ++++++-- docs/api/paddle/log1p_cn.rst | 8 ++++++-- docs/api/paddle/log2_cn.rst | 14 +++++++------- 3 files changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/api/paddle/log10_cn.rst b/docs/api/paddle/log10_cn.rst index 9a4a2616e78..94f979347ad 100755 --- a/docs/api/paddle/log10_cn.rst +++ b/docs/api/paddle/log10_cn.rst @@ -3,7 +3,7 @@ log10 ------------------------------- -.. py:function:: paddle.log10(x, name=None) +.. py:function:: paddle.log10(x, name=None, *, out=None) @@ -18,9 +18,13 @@ Log10 激活函数（逐元素计算底为 10 的对数） 参数 :::::::::::: - - **x** (Tensor) – 输入的 Tensor。数据类型为 int32、int64、float16、bfloat16、float32、float64、complex64 或 complex128。 + - **x** (Tensor) – 输入的 Tensor。数据类型为 int32、int64、float16、bfloat16、float32、float64、complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，Log10 算子底为 10 对数输出，数据类型与输入一致。 diff --git a/docs/api/paddle/log1p_cn.rst b/docs/api/paddle/log1p_cn.rst index 0fe64ab7e92..f70b1f0e45e 100644 --- a/docs/api/paddle/log1p_cn.rst +++ b/docs/api/paddle/log1p_cn.rst @@ -3,7 +3,7 @@ log1p ------------------------------- -.. py:function:: paddle.log1p(x, name=None) +.. py:function:: paddle.log1p(x, name=None, *, out=None) 计算 Log1p（自然对数 + 1）结果。 @@ -15,9 +15,13 @@ log1p 参数 :::::::::::: - - **x** (Tensor) – 输入为一个多维的 Tensor，数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。 + - **x** (Tensor) – 输入为一个多维的 Tensor，数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 计算 ``x`` 的自然对数 + 1 后的 Tensor，数据类型，形状与 ``x`` 一致。 diff --git a/docs/api/paddle/log2_cn.rst b/docs/api/paddle/log2_cn.rst index fd13a948956..ecba2c59e45 100755 --- a/docs/api/paddle/log2_cn.rst +++ b/docs/api/paddle/log2_cn.rst @@ -3,7 +3,7 @@ log2 ------------------------------- -.. py:function:: paddle.log2(x, name=None, *, out) +.. py:function:: paddle.log2(x, name=None, *, out=None) @@ -15,15 +15,15 @@ Log2 激活函数（计算底为 2 的对数） \\Out=log_2x\\ -.. note:: - 别名支持: 参数名 ``input`` 可替代 ``x``; - 参数 ::::::::: - - **x** (Tensor) – 该 OP 的输入为 Tensor。数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。 - ``别名：input`` + - **x** (Tensor) – 该 OP 的输入为 Tensor。数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** (Tensor，可选) - 输出的结果。该参数为仅关键字参数，默认值为 None。 + +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor,Log2 算子底为 2 对数输出，数据类型与输入一致。 From 2e6ecac3bcaafa0e1c4fc5f86855ff9aff639161 Mon Sep 17 00:00:00 2001 From: manfredss Date: Tue, 11 Aug 2026 15:46:25 +0800 Subject: [PATCH 03/18] add four more api --- docs/api/paddle/addmv_cn.rst | 3 +-- docs/api/paddle/exp_cn.rst | 8 ++++++-- docs/api/paddle/i0_cn.rst | 6 +++--- docs/api/paddle/i0e_cn.rst | 6 +++--- docs/api/paddle/sum_cn.rst | 14 +++++++++++++- 5 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/api/paddle/addmv_cn.rst b/docs/api/paddle/addmv_cn.rst index 924d005eb91..b05f6bd573b 100644 --- a/docs/api/paddle/addmv_cn.rst +++ b/docs/api/paddle/addmv_cn.rst @@ -3,7 +3,7 @@ addmv ------------------------------- -.. py:function:: paddle.addmv(input, mat, vec, beta=1, alpha=1, name=None, *, out=None) +.. py:function:: paddle.addmv(input, mat, vec, beta=1, alpha=1, *, out=None) 执行矩阵 ``mat`` 和向量 ``vec`` 的矩阵-向量乘法，并将其加到输入 Tensor 上。 @@ -16,7 +16,6 @@ addmv - **vec** (Tensor) - 待乘的向量。 - **beta** (float，可选) - input 的乘数，默认值为 1。 - **alpha** (float，可选) - mat @ vec 的乘数，默认值为 1。 - - **name** (str，可选) - 操作名称，默认值为 None。 关键字参数 ::::::::: diff --git a/docs/api/paddle/exp_cn.rst b/docs/api/paddle/exp_cn.rst index 375ae21b3e2..8ff1a8980dd 100644 --- a/docs/api/paddle/exp_cn.rst +++ b/docs/api/paddle/exp_cn.rst @@ -3,7 +3,7 @@ exp ------------------------------- -.. py:function:: paddle.exp(x, name=None) +.. py:function:: paddle.exp(x, name=None, *, out=None) @@ -16,9 +16,13 @@ exp 参数 :::::::::::: - - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为 int32、int64、bfloat16、float16、float32、float64、complex64、complex128。 + - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为 int32、int64、bfloat16、float16、float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出为 Tensor，与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/i0_cn.rst b/docs/api/paddle/i0_cn.rst index 31f31c1f47d..7a481b190b0 100644 --- a/docs/api/paddle/i0_cn.rst +++ b/docs/api/paddle/i0_cn.rst @@ -3,7 +3,7 @@ i0 ------------------------------- -.. py:function:: paddle.i0(x, name=None) +.. py:function:: paddle.i0(x, name=None, *, out=None) 对于给定 ``x`` 计算其每个元素的第一类零阶修正贝塞尔曲线函数，其中输入 ``x`` 大小无特殊限制。返回一个第一类零阶修正贝塞尔曲线函数上的 Tensor。 @@ -13,7 +13,7 @@ i0 参数 :::::::::: - - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32，float64。 + - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32、float64、uint8、int8、int16、int32、int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 ``None``。 关键字参数 @@ -22,7 +22,7 @@ i0 返回 :::::::::: - - ``Tensor`` (Tensor)：在 x 处的第一类零阶修正贝塞尔曲线函数的值。 + - ``Tensor`` (Tensor)：在 x 处的第一类零阶修正贝塞尔曲线函数的值。整数类型输入会自动转换为 float32。 代码示例 diff --git a/docs/api/paddle/i0e_cn.rst b/docs/api/paddle/i0e_cn.rst index cbdfeb4d7e9..70788f712ae 100644 --- a/docs/api/paddle/i0e_cn.rst +++ b/docs/api/paddle/i0e_cn.rst @@ -3,7 +3,7 @@ i0e ------------------------------- -.. py:function:: paddle.i0e(x, name=None) +.. py:function:: paddle.i0e(x, name=None, *, out=None) 对于给定 ``x`` 计算其每个元素的第一类指数缩放零阶修正贝塞尔曲线函数，其中输入 ``x`` 大小无特殊限制。返回一个第一类指数缩放零阶修正贝塞尔曲线函数上的 Tensor。 @@ -14,7 +14,7 @@ i0e 参数 :::::::::: - - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32，float64。 + - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32、float64、uint8、int8、int16、int32、int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 ``None``。 关键字参数 @@ -23,7 +23,7 @@ i0e 返回 :::::::::: - - ``Tensor`` (Tensor)：在 x 处的第一类指数缩放零阶修正贝塞尔曲线函数的值。 + - ``Tensor`` (Tensor)：在 x 处的第一类指数缩放零阶修正贝塞尔曲线函数的值。整数类型输入会自动转换为 float32。 代码示例 diff --git a/docs/api/paddle/sum_cn.rst b/docs/api/paddle/sum_cn.rst index 7a6892643c9..92aac0e2e07 100644 --- a/docs/api/paddle/sum_cn.rst +++ b/docs/api/paddle/sum_cn.rst @@ -3,7 +3,14 @@ sum ------------------------------- -.. py:function:: paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None) +.. py:function:: paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None, *, out=None) + +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None, *, out=None)`` （Paddle 风格）。 + 2. ``paddle.sum(input, dim=None, keepdim=False, dtype=None, *, out=None)`` （PyTorch 风格）。 对指定维度上的 Tensor 元素进行求和运算，并输出相应的计算结果。 @@ -21,6 +28,11 @@ sum - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出变量的数据类型。若参数为空，则输出变量的数据类型和输入变量相同，默认值为 None。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如 keepdim 为 true，否则结果 Tensor 的维度将比输入 Tensor 小，默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: From d181d50444b30498f8cc6041cf4cd65e09a3cf43 Mon Sep 17 00:00:00 2001 From: manfredss Date: Tue, 11 Aug 2026 16:20:59 +0800 Subject: [PATCH 04/18] add nine more apis --- docs/api/paddle/ceil_cn.rst | 15 +++++++-------- docs/api/paddle/cumprod_cn.rst | 10 +++++++--- docs/api/paddle/dot_cn.rst | 6 +++--- docs/api/paddle/equal_cn.rst | 10 +++++++--- docs/api/paddle/erf_cn.rst | 6 +++++- docs/api/paddle/expm1_cn.rst | 8 ++++++-- docs/api/paddle/less_cn.rst | 10 +++++++--- docs/api/paddle/less_equal_cn.rst | 10 +++++++--- docs/api/paddle/less_than_cn.rst | 10 +++++++--- 9 files changed, 56 insertions(+), 29 deletions(-) diff --git a/docs/api/paddle/ceil_cn.rst b/docs/api/paddle/ceil_cn.rst index 28d2d923e04..cc74d8e40f4 100644 --- a/docs/api/paddle/ceil_cn.rst +++ b/docs/api/paddle/ceil_cn.rst @@ -3,7 +3,7 @@ ceil ------------------------------- -.. py:function:: paddle.ceil(x, name=None) +.. py:function:: paddle.ceil(x, name=None, *, out=None) @@ -14,20 +14,19 @@ ceil out = \left \lceil x \right \rceil -.. note:: - 别名支持: 参数名 ``input`` 可替代 ``x``，如 ``input=tensor_x`` 等价于 ``x=tensor_x``。 - 参数 :::::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型支持 float32, float64, float16, bfloat16, uint8, int8, int16, int32, int64。 - 别名： ``input`` + - **x** (Tensor) - 输入的 Tensor，数据类型支持 float32, float64, float16, bfloat16, uint8, int8, int16, int32, int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** （Tensor，可选） - 指定输出结果的 ``Tensor``，默认值为 None。 + +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: -输出 Tensor，与 ``x`` 维度相同、数据类型相同。 +输出 Tensor，与 ``x`` 维度相同。若 ``x`` 为整数类型，则自动转换为 float32。 代码示例 :::::::::::: diff --git a/docs/api/paddle/cumprod_cn.rst b/docs/api/paddle/cumprod_cn.rst index 28aea6a3ed1..cbad73d6a8f 100644 --- a/docs/api/paddle/cumprod_cn.rst +++ b/docs/api/paddle/cumprod_cn.rst @@ -3,7 +3,7 @@ cumprod ------------------------------- -.. py:function:: paddle.cumprod(x, dim=None, dtype=None, name=None) +.. py:function:: paddle.cumprod(x, dim=None, dtype=None, name=None, *, out=None) @@ -14,11 +14,15 @@ cumprod 参数 ::::::::: - - **x** (Tensor) - 累乘的输入，需要进行累乘操作的 tensor。 - - **dim** (int，可选) - 指明需要累乘的维度，取值范围需在[-x.rank,x.rank)之间，其中 x.rank 表示输入 tensor x 的维度，-1 代表最后一维。 + - **x** (Tensor) - 累乘的输入，需要进行累乘操作的 tensor。别名 ``input``。 + - **dim** (int，可选) - 指明需要累乘的维度，取值范围需在[-x.rank,x.rank)之间或为 None，其中 x.rank 表示输入 tensor x 的维度，-1 代表最后一维。默认值为 None，此时对展平后的数组计算累乘。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 tensor 的数据类型，支持 int32、int64、bfloat16、float16、float32、float64、complex64、complex128。如果指定了，那么在执行操作之前，输入的 tensor 将被转换为 dtype 类型。这对于防止数据类型溢出非常有用。默认为：None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: ``Tensor``，累乘操作的结果。 diff --git a/docs/api/paddle/dot_cn.rst b/docs/api/paddle/dot_cn.rst index 80013b35004..da1b4eb8366 100644 --- a/docs/api/paddle/dot_cn.rst +++ b/docs/api/paddle/dot_cn.rst @@ -3,7 +3,7 @@ dot ------------------------------- -.. py:function:: paddle.dot(x, y, name=None) +.. py:function:: paddle.dot(x, y, name=None, *, out=None) 计算向量的内积 @@ -13,7 +13,7 @@ dot 支持 1 维和 2 维 Tensor。如果是 2 维 Tensor，矩阵的第一个维度是 batch_size，将会在多个样本上进行点积计算。 .. note:: - 别名支持：参数名 ``input`` 可替代 ``x``， ``tensor`` 可替代 ``y``。 + 别名支持：参数名 ``input`` 可替代 ``x``， ``other`` 可替代 ``y``。 参数 ::::::::: @@ -21,7 +21,7 @@ dot - **x** （Tensor） - 1 维或 2 维 ``Tensor``。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 、 ``complex64`` 或 ``complex128`` 。 别名： ``input`` - **y** （Tensor） - 1 维或 2 维 ``Tensor``。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 、 ``complex64`` 或 ``complex128`` 。 - 别名： ``tensor`` + 别名： ``other`` - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 diff --git a/docs/api/paddle/equal_cn.rst b/docs/api/paddle/equal_cn.rst index 39706a5969c..cd4e11ac62e 100644 --- a/docs/api/paddle/equal_cn.rst +++ b/docs/api/paddle/equal_cn.rst @@ -2,7 +2,7 @@ equal ------------------------------- -.. py:function:: paddle.equal(x, y, name=None) +.. py:function:: paddle.equal(x, y, name=None, *, out=None) 返回 :math:`x==y` 逐元素比较 x 和 y 是否相等，相同位置的元素相同则返回 True，否则返回 False。使用重载算子 ``==`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/erf_cn.rst b/docs/api/paddle/erf_cn.rst index 49ed3033f29..0599f87b389 100644 --- a/docs/api/paddle/erf_cn.rst +++ b/docs/api/paddle/erf_cn.rst @@ -3,7 +3,7 @@ erf ------------------------------- -.. py:function:: paddle.erf(x, name=None) +.. py:function:: paddle.erf(x, name=None, *, out=None) 逐元素计算 Erf 激活函数。 @@ -18,6 +18,10 @@ erf - **x** (Tensor) - 输入 Tensor，数据类型为 float32、float64、uint8、int8、int16、int32、int64。别名: ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 ``None``。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/expm1_cn.rst b/docs/api/paddle/expm1_cn.rst index a75876ce6dd..a18949c0219 100644 --- a/docs/api/paddle/expm1_cn.rst +++ b/docs/api/paddle/expm1_cn.rst @@ -3,7 +3,7 @@ expm1 ------------------------------- -.. py:function:: paddle.expm1(x, name=None) +.. py:function:: paddle.expm1(x, name=None, *, out=None) @@ -16,9 +16,13 @@ expm1 参数 ::::::::: - - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为：int32、int64、bfloat16、float16、float32、float64、complex64、complex128。 + - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为：int32、int64、bfloat16、float16、float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/less_cn.rst b/docs/api/paddle/less_cn.rst index 9a7227a1c65..8bbc85ee32c 100644 --- a/docs/api/paddle/less_cn.rst +++ b/docs/api/paddle/less_cn.rst @@ -2,7 +2,7 @@ less ------------------------------- -.. py:function:: paddle.less(x, y, name=None) +.. py:function:: paddle.less(x, y, name=None, *, out=None) 逐元素地返回 :math:`x < y` 的逻辑值，相同位置前者输入小于后者输入则返回 True，否则返回 False。使用重载算子 ``<`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ less 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/less_equal_cn.rst b/docs/api/paddle/less_equal_cn.rst index 199f8151856..3edc77fe874 100644 --- a/docs/api/paddle/less_equal_cn.rst +++ b/docs/api/paddle/less_equal_cn.rst @@ -2,7 +2,7 @@ less_equal ------------------------------- -.. py:function:: paddle.less_equal(x, y, name=None) +.. py:function:: paddle.less_equal(x, y, name=None, *, out=None) 逐元素地返回 :math:`x <= y` 的逻辑值，相同位置前者输入小于等于后者输入则返回 True，否则返回 False。使用重载算子 ``<=`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ less_equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/less_than_cn.rst b/docs/api/paddle/less_than_cn.rst index 082086c3b42..5933119b4e1 100644 --- a/docs/api/paddle/less_than_cn.rst +++ b/docs/api/paddle/less_than_cn.rst @@ -2,7 +2,7 @@ less_than ------------------------------- -.. py:function:: paddle.less_than(x, y, name=None) +.. py:function:: paddle.less_than(x, y, name=None, *, out=None) 逐元素地返回 :math:`x < y` 的逻辑值，相同位置前者输入小于后者输入则返回 True，否则返回 False。使用重载算子 ``<`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ less_than 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 From 05b1ba582e7d572d706f51a3e2049612112308c4 Mon Sep 17 00:00:00 2001 From: manfredss Date: Tue, 11 Aug 2026 17:39:11 +0800 Subject: [PATCH 05/18] add 10 more apis --- docs/api/paddle/conj_cn.rst | 8 ++------ docs/api/paddle/gather_cn.rst | 9 ++++++--- docs/api/paddle/greater_equal_cn.rst | 10 +++++++--- docs/api/paddle/greater_than_cn.rst | 12 ++++++++---- docs/api/paddle/index_add_cn.rst | 28 ++++++++++++++++++++-------- docs/api/paddle/lgamma_cn.rst | 10 +++++++--- docs/api/paddle/permute_cn.rst | 5 ++--- docs/api/paddle/prod_cn.rst | 14 ++++++++------ docs/api/paddle/rand_cn.rst | 13 ++++++++++--- docs/api/paddle/sin_cn.rst | 6 +++--- 10 files changed, 73 insertions(+), 42 deletions(-) diff --git a/docs/api/paddle/conj_cn.rst b/docs/api/paddle/conj_cn.rst index 368784e42d6..a31e0e7adef 100644 --- a/docs/api/paddle/conj_cn.rst +++ b/docs/api/paddle/conj_cn.rst @@ -3,7 +3,7 @@ conj ------------------------------- -.. py:function:: paddle.conj(x, name=None, *, out=None) +.. py:function:: paddle.conj(x, name=None) 是逐元素计算 Tensor 的共轭运算。 @@ -11,13 +11,9 @@ conj 参数 :::::::::::: - - **x** (Tensor) - 输入的复数值的 Tensor，数据类型为：complex64、complex128、bfloat16、float16、float32、float64、int32 或 int64。 + - **x** (Tensor) - 输入的复数值的 Tensor，数据类型为：complex64、complex128、bfloat16、float16、float32、float64、int32 或 int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 ``None``。 -关键字参数 -::::::::: - - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 - 返回 :::::::::::: diff --git a/docs/api/paddle/gather_cn.rst b/docs/api/paddle/gather_cn.rst index 618f8b054be..b1df3abbb57 100644 --- a/docs/api/paddle/gather_cn.rst +++ b/docs/api/paddle/gather_cn.rst @@ -11,7 +11,7 @@ gather ===== -.. py:function:: paddle.gather(x, index, axis=None, name=None) +.. py:function:: paddle.gather(x, index, axis=None, name=None, out=None) 根据索引 index 获取输入 ``x`` 的指定 ``axis`` 维度的条目，并将它们拼接在一起。 @@ -42,8 +42,9 @@ gather :::::::::::: - **x** (Tensor) - 输入 Tensor，秩 ``rank >= 1``，支持的数据类型包括 int32、int64、float32、float64、complex64、complex128 和 uint8 (CPU)、float16（GPU） 。 - **index** (Tensor) - 索引 Tensor，秩 ``rank = 0`` 或者 ``rank = 1``，数据类型为 int32 或 int64。 - - **axis** (Tensor) - 指定 index 获取输入的维度，``axis`` 的类型可以是 int 或者 Tensor，当 ``axis`` 为 Tensor 的时候其数据类型为 int32 或者 int64。默认值为 None，当 ``axis`` 为 None 的时候其值为 0。 + - **axis** (Tensor|int|None) - 指定 index 获取输入的维度，``axis`` 的类型可以是 int 或者 Tensor，当 ``axis`` 为 Tensor 的时候其数据类型为 int32 或者 int64。默认值为 None，当 ``axis`` 为 None 的时候其值为 0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: @@ -68,7 +69,7 @@ PyTorch 兼容的 ``gather`` 操作：根据索引 index 获取输入 ``input`` 参数 :::::::::::: - **input** (Tensor) - 输入 Tensor，支持的数据类型包括 int32、int64、float32、float64、int16、uint8、float16（GPU）以及 bfloat16（GPU） 。 - - **dim** (int) - 指定 index 获取输入的维度，``dim`` 的类型可以是 int 或者。 + - **dim** (int|Tensor) - 指定 index 获取输入的维度，``dim`` 的类型可以是 int 或 Tensor。 - **index** (Tensor) - 索引 Tensor，``index`` 张量的各维度需要小于等于 ``input`` 张量的各维度（除 ``dim`` 维度外），且值需要在 ``input.shape[dim]`` 范围内。数据类型为 int32 或 int64。 - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。 @@ -76,6 +77,8 @@ PyTorch 兼容的 ``gather`` 操作：根据索引 index 获取输入 ``input`` 本接口没有实现 PyTorch 的 ``sparse_grad`` 参数！梯度默认是稠密的，等效于 ``sparse_grad=False``。 + 当前三个参数均为 Tensor 时，两种 ``gather`` 接口之间存在歧义，当前会优先选择原始 ``gather`` 接口。因此建议避免将 Tensor 作为 ``dim`` 传入。 + 返回 :::::::::::: diff --git a/docs/api/paddle/greater_equal_cn.rst b/docs/api/paddle/greater_equal_cn.rst index 2f627039572..a479fdf0986 100644 --- a/docs/api/paddle/greater_equal_cn.rst +++ b/docs/api/paddle/greater_equal_cn.rst @@ -2,7 +2,7 @@ greater_equal ------------------------------- -.. py:function:: paddle.greater_equal(x, y, name=None) +.. py:function:: paddle.greater_equal(x, y, name=None, *, out=None) 逐元素地返回 :math:`x >= y` 的逻辑值，相同位置前者输入大于等于后者输入返回 True，否则返回 False。使用重载算子 ``>=`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ greater_equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，shape 和输入一致，数据类型为 bool。 diff --git a/docs/api/paddle/greater_than_cn.rst b/docs/api/paddle/greater_than_cn.rst index fc4f37fc4e1..c192dc419d8 100644 --- a/docs/api/paddle/greater_than_cn.rst +++ b/docs/api/paddle/greater_than_cn.rst @@ -2,21 +2,25 @@ greater_than ------------------------------- -.. py:function:: paddle.greater_than(x, y, name=None) +.. py:function:: paddle.greater_than(x, y, name=None, *, out=None) -返回 :math:`x>y` 逐元素比较 x 和 y 是否相等，相同位置前者输入大于等于后者输入则返回 True，否则返回 False。使用重载算子 ``>`` 可以有相同的计算函数效果。 +逐元素返回 :math:`x > y` 的真值；对应位置的 ``x`` 大于 ``y`` 时返回 True，否则返回 False。使用重载算子 ``>`` 可以获得相同的计算效果。 .. note:: 输出的结果不返回梯度。 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 用于比较的第一个输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 用于比较的第二个输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，输出结果，shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/index_add_cn.rst b/docs/api/paddle/index_add_cn.rst index a4d17c33f20..df12877019d 100644 --- a/docs/api/paddle/index_add_cn.rst +++ b/docs/api/paddle/index_add_cn.rst @@ -3,11 +3,17 @@ index_add ------------------------------- -.. py:function:: paddle.index_add(x, index, axis, value, name=None) +.. py:function:: paddle.index_add(x, index, axis, value, alpha=1, name=None, *, out=None) +.. note:: + 本 API 支持两种签名： -沿着指定轴 ``axis`` 将 ``index`` 中指定位置的 ``x`` 与 ``value`` 相加，并写入到结果 Tensor 中的对应位置。这里 ``index`` 是一个 ``1-D`` Tensor。除 ``axis`` 轴外，返回的 Tensor 其余维度大小和输入 ``x`` 相等， ``axis`` 维度的大小等于 ``index`` 的大小。 + 1. ``paddle.index_add(x, index, axis, value, alpha=1, name=None, *, out=None)`` （Paddle 风格）。 + 2. ``paddle.index_add(input, dim, index, source, *, alpha=1, out=None)`` （PyTorch 风格）。 + + +沿着指定轴 ``axis`` 将 ``index`` 中指定位置的 ``x`` 与 ``value`` 相加，并写入到结果 Tensor 中的对应位置。这里 ``index`` 是一个 ``1-D`` Tensor。返回 Tensor 与输入 ``x`` 的形状相同。 **示例** @@ -60,7 +66,7 @@ index_add **示例 1 图解说明** - 下图展示了示例 1 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=0 轴上对指定位置的元素进行相加，同时保持了除 ``axis`` 轴外，返回的 Tensor 其余维度大小和输入 ``x`` 相等。 + 下图展示了示例 1 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=0 轴上对指定位置的元素进行相加，返回 Tensor 与输入 ``x`` 的形状相同。 .. figure:: ../../images/api_legend/index_add/index_add-1.png :width: 500 @@ -69,7 +75,7 @@ index_add **示例 2 图解说明** - 下图展示了示例 2 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=1 轴上对指定位置的元素进行相加，同时保持了除 ``axis`` 轴外，返回的 Tensor 其余维度大小和输入 ``x`` 相等。 + 下图展示了示例 2 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=1 轴上对指定位置的元素进行相加，返回 Tensor 与输入 ``x`` 的形状相同。 .. figure:: ../../images/api_legend/index_add/index_add-2.png :width: 500 @@ -79,16 +85,22 @@ index_add 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor。 ``x`` 的数据类型可以是 float16，float32，float64，int32，int64。 + - **x** (Tensor) - 输入 Tensor。 ``x`` 的数据类型可以是 float16，float32，float64，int32，int64。别名 ``input``。 - **index** (Tensor) - 包含索引下标的 1-D Tensor。数据类型为 int32 或者 int64。 - - **axis** (int) - 索引轴。数据类型为 int。 - - **value** (Tensor) - 与 ``x`` 相加的 Tensor。 ``value`` 的数据类型同 ``x`` 。 + - **axis** (int) - 索引轴。数据类型为 int。别名 ``dim``。 + - **value** (Tensor) - 与 ``x`` 相加的 Tensor。 ``value`` 的数据类型同 ``x``。别名 ``source``。 + - **alpha** (Number，可选) - ``value`` 的缩放因子。默认值为 1。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** (Tensor，可选) - 输出 Tensor。默认值为 None。 + 返回 ::::::::: -Tensor，返回一个数据类型同输入的 Tensor。 +Tensor，返回一个形状和数据类型均与输入 ``x`` 相同的 Tensor。 代码示例 diff --git a/docs/api/paddle/lgamma_cn.rst b/docs/api/paddle/lgamma_cn.rst index 51f17ac1c11..dbf77c578ae 100644 --- a/docs/api/paddle/lgamma_cn.rst +++ b/docs/api/paddle/lgamma_cn.rst @@ -3,19 +3,23 @@ lgamma ------------------------------- -.. py:function:: paddle.lgamma(x, name=None) +.. py:function:: paddle.lgamma(x, name=None, *, out=None) 计算输入 x 的 gamma 函数的自然对数并返回。 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。 + - **x** (Tensor) - 输入 Tensor，数据类型为 bfloat16、float16、float32、float64、uint8、int8、int16、int32 或 int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: -输出 Tensor，与 ``x`` 维度相同、数据类型相同。 +输出 Tensor，与 ``x`` 维度相同、数据类型相同；整数类型输入会自动转换为 float32。 代码示例 ::::::::: diff --git a/docs/api/paddle/permute_cn.rst b/docs/api/paddle/permute_cn.rst index 8556dd22de8..514abaa14a4 100644 --- a/docs/api/paddle/permute_cn.rst +++ b/docs/api/paddle/permute_cn.rst @@ -3,7 +3,7 @@ permute ------------------------------- -.. py:function:: paddle.permute(input, dims, name=None) +.. py:function:: paddle.permute(input, *dims) 根据 dims 对输入的多维 Tensor 进行数据重排。返回多维 Tensor 的第 i 维对应输入 Tensor 的 dims[i] 维。 @@ -11,8 +11,7 @@ permute :::::::::::: - **input** (Tensor) - 输入：input:[N_1, N_2, ..., N_k, D]多维 Tensor，可选的数据类型为 bool, float16, bfloat16, float32, float64, int8, int16, int32, int64, uint8, uint16, complex64, complex128。 - - **dims** (list|tuple) - dims 长度必须和 input 的维度相同，并依照 dims 中的数据进行重排。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **dims** (tuple|list|int) - 目标维度顺序。可作为可变长度位置参数传入（如 ``paddle.permute(input, 1, 0, 2)``），也可作为单个 list 或 tuple 传入。dims 的长度必须和 input 的维度相同，并依照 dims 中的数据进行重排。 返回 :::::::::::: diff --git a/docs/api/paddle/prod_cn.rst b/docs/api/paddle/prod_cn.rst index 6ab87c2ef24..fda1e2098c1 100644 --- a/docs/api/paddle/prod_cn.rst +++ b/docs/api/paddle/prod_cn.rst @@ -3,7 +3,7 @@ prod ------------------------------- -.. py:function:: paddle.prod(x, axis=None, keepdim=False, dtype=None, name=None) +.. py:function:: paddle.prod(x, axis=None, keepdim=False, dtype=None, name=None, *, out=None) @@ -15,14 +15,16 @@ prod 参数 :::::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：bfloat16、float16、float32、float64、int32、int64、complex64、complex128。 - 别名： ``input`` - - **axis** (int|list|tuple，可选) - 求乘积运算的维度。如果是 None，则计算所有元素的乘积并返回包含单个元素的 Tensor，否则该参数必须在 :math:`[-x.ndim, x.ndim)` 范围内。如果 :math:`axis[i] < 0`，则维度将变为 :math:`x.ndim + axis[i]`，默认为 None。 - 别名： ``dim`` + - **x** (Tensor) - 输入的 Tensor，数据类型为：bfloat16、float16、float32、float64、int32、int64、complex64、complex128。别名 ``input``。 + - **axis** (int|list|tuple，可选) - 求乘积运算的维度。如果是 None，则计算所有元素的乘积并返回包含单个元素的 Tensor，否则该参数必须在 :math:`[-x.ndim, x.ndim)` 范围内。如果 :math:`axis[i] < 0`，则维度将变为 :math:`x.ndim + axis[i]`，默认为 None。别名 ``dim``。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留输入的维度。除非 keepdim 为 True，否则输出 Tensor 的维度将比输入 Tensor 小一维，默认值为 False。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 int32、int64、float32、float64。如果指定了该参数，那么在执行操作之前，输入 Tensor 将被转换为 dtype 类型。这对于防止数据类型溢出非常有用。若参数为空，则输出变量的数据类型和输入变量相同，默认为：None。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64、int32、int64、complex64、complex128。如果指定了该参数，那么在执行操作之前，输入 Tensor 将被转换为 dtype 类型。这对于防止数据类型溢出非常有用。若参数为空，则输出变量的数据类型和输入变量相同，默认为：None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输入 Tensor 在指定 axis 上的累乘的结果。 diff --git a/docs/api/paddle/rand_cn.rst b/docs/api/paddle/rand_cn.rst index 88ea6315ed3..3e3d1b11a63 100644 --- a/docs/api/paddle/rand_cn.rst +++ b/docs/api/paddle/rand_cn.rst @@ -3,16 +3,23 @@ rand ---------------------- -.. py:function:: paddle.rand(shape, dtype=None, name=None) +.. py:function:: paddle.rand(shape, dtype=None, name=None, *, out=None, device=None, pin_memory=False, requires_grad=False) 返回符合均匀分布的、范围在[0, 1)的 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 :::::::::: - - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64。当该参数值为 None 时，输出 Tensor 的数据类型为 float32。使用全局默认 dtype（详细信息请见 :ref:`get_default_dtype` ）。默认值为 None。 + - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。参数名别名为 ``size``，例如 ``rand(size=[2, 3])`` 等价于 ``rand(shape=[2, 3])``；也可直接以可变长度整数参数传入形状，如 ``rand(2, 3)``。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64。默认值为 None，此时使用全局默认数据类型（详细信息请见 :ref:`cn_api_paddle_get_default_dtype` ）。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。 + - **pin_memory** (bool，可选) - 若为 True，返回 Tensor 分配在锁页内存中。仅对 CPU Tensor 生效。默认值为 False。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：符合均匀分布的范围为[0, 1)的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/sin_cn.rst b/docs/api/paddle/sin_cn.rst index 84ebb5f5ea0..038785b4a4e 100644 --- a/docs/api/paddle/sin_cn.rst +++ b/docs/api/paddle/sin_cn.rst @@ -3,7 +3,7 @@ sin ------------------------------- -.. py:function:: paddle.sin(x, name=None, *, out=out) +.. py:function:: paddle.sin(x, name=None, *, out=None) 计算输入的正弦值。 @@ -15,7 +15,7 @@ sin 参数 :::::::::::: - - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 float32，float64，float16，complex64，complex128。别名 ``input``。 + - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 float32、float64、float16、bfloat16、uint8、int8、int16、int32、int64、complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 @@ -25,7 +25,7 @@ sin 返回 :::::::::::: -返回类型为 Tensor，数据类型同输入一致。 +返回类型为 Tensor，形状与输入相同；整数类型输入会自动转换为 float32。 代码示例 :::::::::::: From 870170d52279aff6235c8d2993312197dd50f572 Mon Sep 17 00:00:00 2001 From: manfredss Date: Wed, 12 Aug 2026 15:02:36 +0800 Subject: [PATCH 06/18] add 13 more apis --- docs/api/paddle/median_cn.rst | 6 +++++- docs/api/paddle/mm_cn.rst | 7 ++++--- docs/api/paddle/normal_cn.rst | 10 +++++++--- docs/api/paddle/not_equal_cn.rst | 10 +++++++--- docs/api/paddle/randint_like_cn.rst | 10 ++++++++-- docs/api/paddle/randn_cn.rst | 4 ++-- docs/api/paddle/randn_like_cn.rst | 9 +++++++-- docs/api/paddle/randperm_cn.rst | 9 ++++++++- docs/api/paddle/scale_cn.rst | 6 +++++- docs/api/paddle/scatter_cn.rst | 5 +++-- docs/api/paddle/strided_slice_cn.rst | 4 ++-- 11 files changed, 58 insertions(+), 22 deletions(-) diff --git a/docs/api/paddle/median_cn.rst b/docs/api/paddle/median_cn.rst index 4d504728abf..bc98436fb21 100644 --- a/docs/api/paddle/median_cn.rst +++ b/docs/api/paddle/median_cn.rst @@ -3,7 +3,7 @@ median ------------------------------- -.. py:function:: paddle.median(x, axis=None, keepdim=False, mode='avg', name=None) +.. py:function:: paddle.median(x, axis=None, keepdim=False, mode='avg', name=None, *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的中位数。 @@ -21,6 +21,10 @@ median - **mode** (str，可选) - 当输入 Tensor ``x`` 在 ``axis`` 轴上有偶数个元素时，可选择按照中间两个数的平均值或最小值确定中位数。可选的值是 'avg' 或 'min'。默认为 'avg'。当出现别名替换时， ``mode`` 设置默认参数为 ``min`` 而不是 ``avg``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::: Tensor 或 (Tensor, Tensor)。 diff --git a/docs/api/paddle/mm_cn.rst b/docs/api/paddle/mm_cn.rst index 12301f206bb..c368807dfe4 100644 --- a/docs/api/paddle/mm_cn.rst +++ b/docs/api/paddle/mm_cn.rst @@ -3,7 +3,7 @@ mm ------------------------------- -.. py:function:: paddle.mm(input, mat2, name=None, *, out=None) +.. py:function:: paddle.mm(input, mat2, name=None, *, out_dtype=None, out=None) @@ -23,12 +23,13 @@ mm 关键字参数 :::::::::::: - - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + - **out_dtype** (paddle.dtype|None，可选) - 期望的输出数据类型。目前仅支持在动态图中将 CUDA 上数据类型为 float16 或 bfloat16 的 2-D 输入转换为 ``paddle.float32`` 输出，两个输入 Tensor 的数据类型必须相同。默认值为 None。 + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中。该 Tensor 的形状和数据类型必须与预期输出相同。默认值为 ``None``。 返回 :::::::::::: - - Tensor，矩阵相乘后的结果。 + - Tensor，矩阵相乘后的结果。未指定 ``out_dtype`` 时，数据类型与 ``input`` 相同。 :: diff --git a/docs/api/paddle/normal_cn.rst b/docs/api/paddle/normal_cn.rst index 0a3b0420f43..829dfcd1a3c 100644 --- a/docs/api/paddle/normal_cn.rst +++ b/docs/api/paddle/normal_cn.rst @@ -3,7 +3,7 @@ normal ------------------------------- -.. py:function:: paddle.normal(mean=0.0, std=1.0, shape=None, name=None) +.. py:function:: paddle.normal(mean=0.0, std=1.0, shape=None, name=None, *, out=None) 返回符合正态分布（均值为 ``mean``，标准差为 ``std`` 的正态随机分布）的随机 Tensor。 @@ -20,10 +20,14 @@ normal 参数 :::::::::: - **mean** (float|complex|Tensor，可选) - 输出 Tensor 的正态分布的平均值。如果 ``mean`` 是 float，则表示输出 Tensor 中所有元素的正态分布的平均值。如果 ``mean`` 是 Tensor (支持的数据类型为 float32、float64、complex64、complex128)，则表示输出 Tensor 中每个元素的正态分布的平均值。默认值为 0.0。 - - **std** (float|Tensor，可选) - 输出 Tensor 的正态分布的标准差。如果 ``std`` 是 float，则表示输出 Tensor 中所有元素的正态分布的标准差。如果 ``std`` 是 Tensor (支持的数据类型为 float32、float64)，则表示输出 Tensor 中每个元素的正态分布的标准差。默认值为 0.0。 - - **shape** (list|tuple|Tensor，可选) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1D Tensor。如果 ``mean`` 或者 ``std`` 是 Tensor，输出 Tensor 的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为 None。 + - **std** (float|Tensor，可选) - 输出 Tensor 的正态分布的标准差。如果 ``std`` 是 float，则表示输出 Tensor 中所有元素的正态分布的标准差。如果 ``std`` 是 Tensor (支持的数据类型为 float32、float64)，则表示输出 Tensor 中每个元素的正态分布的标准差。默认值为 1.0。 + - **shape** (list|tuple|Tensor，可选) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1D Tensor。如果 ``mean`` 或者 ``std`` 是 Tensor，输出 Tensor 的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为 None。参数名别名为 ``size``，例如 ``normal(size=[2, 3], ...)`` 等价于 ``normal(shape=[2, 3], ...)``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中。该 Tensor 的形状和数据类型必须与预期输出相同。默认值为 ``None``。 + 返回 :::::::::: Tensor：符合正态分布（均值为 ``mean``，标准差为 ``std`` 的正态随机分布）的随机 Tensor。 diff --git a/docs/api/paddle/not_equal_cn.rst b/docs/api/paddle/not_equal_cn.rst index 78a246cf9d0..7ef5c07801c 100644 --- a/docs/api/paddle/not_equal_cn.rst +++ b/docs/api/paddle/not_equal_cn.rst @@ -2,7 +2,7 @@ not_equal ------------------------------- -.. py:function:: paddle.not_equal(x, y, name=None) +.. py:function:: paddle.not_equal(x, y, name=None, *, out=None) 返回 :math:`x!=y` 逐元素比较 x 和 y 是否相等，相同位置的元素不相同则返回 True，否则返回 False。使用重载算子 ``!=`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ not_equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，shape 和输入一致，数据类型为 bool。 diff --git a/docs/api/paddle/randint_like_cn.rst b/docs/api/paddle/randint_like_cn.rst index d1068134fae..717ecacb13c 100644 --- a/docs/api/paddle/randint_like_cn.rst +++ b/docs/api/paddle/randint_like_cn.rst @@ -3,18 +3,24 @@ randint_like ------------------------------- -.. py:function:: paddle.randint_like(x, low=0, high=None, dtype=None, name=None) +.. py:function:: paddle.randint_like(x, low=0, high=None, dtype=None, name=None, *, device=None, pin_memory=False, requires_grad=False) 返回服从均匀分布的、范围在[``low``, ``high``)的随机 Tensor，输出的形状与 x 的形状一致，当数据类型 ``dtype`` 为 None 时（默认），输出的数据类型与 x 的数据类型一致，当数据类型 ``dtype`` 不为 None 时，将输出用户指定的数据类型。当 ``high`` 为 None 时（默认），均匀采样的区间为[0, ``low``)。 参数 :::::::::: - - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 bool，int32，int64，float16，float32，float64。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。 + - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 bool，int32，int64，float16，float32，float64。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。别名 ``input``。 - **low** (int，可选) - 要生成的随机值范围的下限，``low`` 包含在范围中。当 ``high`` 为 None 时，均匀采样的区间为[0, ``low``)。默认值为 0。 - **high** (int，可选) - 要生成的随机值范围的上限，``high`` 不包含在范围中。默认值为 None，此时范围是[0, ``low``)。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 bool，int32，int64，float16，float32，float64。当该参数值为 None 时，输出 Tensor 的数据类型与输入 Tensor 的数据类型一致。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，默认使用 ``x`` 所在设备。 + - **pin_memory** (bool，可选) - 若为 True，返回 Tensor 分配在锁页内存中。仅对 CPU Tensor 生效。默认值为 False。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：从区间[``low``，``high``)内均匀分布采样的随机 Tensor，形状为 ``x.shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/randn_cn.rst b/docs/api/paddle/randn_cn.rst index 69b608df4ca..922fd2e40ac 100644 --- a/docs/api/paddle/randn_cn.rst +++ b/docs/api/paddle/randn_cn.rst @@ -3,7 +3,7 @@ randn ------------------------------- -.. py:function:: paddle.randn(shape, dtype=None, name=None, *, out=None, device=None, requires_grad=False, pin_memory=False) +.. py:function:: paddle.randn(shape, dtype=None, name=None, *, out=None, device=None, pin_memory=False, requires_grad=False) 返回符合标准正态分布（均值为 0，标准差为 1 的正态随机分布）的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 @@ -24,8 +24,8 @@ randn :::::::::::: - **out** (Tensor，可选) - 用于保存输出结果的 Tensor。默认值为 None。 - **device** (PlaceLike|None，可选) - 指定返回 Tensor 所在的设备。默认值为 None，表示使用当前全局设备（可通过 ``paddle.device.set_device`` 设置）。 - - **requires_grad** (bool，可选) - 是否在返回的 Tensor 上记录 autograd 的操作。默认值为 False。 - **pin_memory** (bool，可选) - 如果设置为 True，返回的 Tensor 会分配在锁页内存中。默认值为 False。 + - **requires_grad** (bool，可选) - 是否在返回的 Tensor 上记录 autograd 的操作。默认值为 False。 返回 :::::::::: diff --git a/docs/api/paddle/randn_like_cn.rst b/docs/api/paddle/randn_like_cn.rst index 584635d1acd..c4d95e36692 100644 --- a/docs/api/paddle/randn_like_cn.rst +++ b/docs/api/paddle/randn_like_cn.rst @@ -3,16 +3,21 @@ randn_like ------------------------------- -.. py:function:: paddle.randn_like(x, dtype=None, name=None) +.. py:function:: paddle.randn_like(x, dtype=None, name=None, *, device=None, requires_grad=False) 返回一个与输入张量尺寸相同的张量，其元素服从均值为 0、方差为 1 的标准正态分布。 参数 :::::::::: - - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 float16，bfloat16，float32，float64，complex64，complex128。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。 + - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 float16，bfloat16，float32，float64，complex64，complex128。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。别名 ``input``。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16，bfloat16，float32，float64，complex64，complex128。当该参数值为 None 时，输出 Tensor 的数据类型与输入 Tensor 的数据类型一致。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **device** (str|paddle.Place|None，可选) - 创建的 Tensor 所在设备。为 None 时，使用输入 Tensor 所在设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否计算创建 Tensor 的梯度。默认值为 False。 + 返回 :::::::::: Tensor：服从均值为 0、方差为 1 的标准正态分布 Tensor，形状为 ``x.shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/randperm_cn.rst b/docs/api/paddle/randperm_cn.rst index f08e981532e..a216aa1f443 100644 --- a/docs/api/paddle/randperm_cn.rst +++ b/docs/api/paddle/randperm_cn.rst @@ -3,7 +3,7 @@ randperm ------------------------------- -.. py:function:: paddle.randperm(n, dtype="int64", name=None) +.. py:function:: paddle.randperm(n, dtype="int64", name=None, *, out=None, device=None, pin_memory=False, requires_grad=False) 返回一个数值在 0 到 n-1、随机排列的 1-D Tensor，数据类型为 ``dtype``。 @@ -13,6 +13,13 @@ randperm - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 int32、int64、float32、float64。默认值为 int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。 + - **pin_memory** (bool，可选) - 若为 True，返回 Tensor 分配在锁页内存中。仅对 CPU Tensor 生效。默认值为 False。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：一个数值在 0 到 n-1、随机排列的 1-D Tensor，数据类型为 ``dtype`` 。 diff --git a/docs/api/paddle/scale_cn.rst b/docs/api/paddle/scale_cn.rst index 0e54add08ea..e36a49b294a 100644 --- a/docs/api/paddle/scale_cn.rst +++ b/docs/api/paddle/scale_cn.rst @@ -3,7 +3,7 @@ scale ------------------------------- -.. py:function:: paddle.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None) +.. py:function:: paddle.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None, *, out=None) 对输入 Tensor 进行缩放和偏置，其公式如下： @@ -27,6 +27,10 @@ scale - **act** (str，可选) - 应用于输出的激活函数，如 tanh、softmax、sigmoid、relu 等。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，缩放后的计算结果。 diff --git a/docs/api/paddle/scatter_cn.rst b/docs/api/paddle/scatter_cn.rst index 3babaf0ef72..2fd21139019 100644 --- a/docs/api/paddle/scatter_cn.rst +++ b/docs/api/paddle/scatter_cn.rst @@ -12,7 +12,7 @@ scatter ===== -.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None) +.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None, out=None) 通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下： @@ -35,6 +35,7 @@ COPY-FROM: paddle.scatter:scatter-example-1 - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x``。当 ``index`` 为一维 tensor 时，``updates`` 形状应与输入 ``x`` 相同，并且 ``dim>1`` 的 dim 值应与输入 ``x`` 相同。当 ``index`` 为零维 tensor 时，``updates`` 应该是一个 ``(N-1)-D`` 的 Tensor，并且 ``updates`` 的第 i 个维度应该与 ``x`` 的 ``i+1`` 个维度相同。 - **overwrite** （bool，可选）- 指定索引 ``index`` 相同时，更新输出的方式。如果为 True，则使用覆盖模式更新相同索引的输出，如果为 False，则使用累加模式更新相同索引的输出。默认值为 True。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **out** (Tensor，可选) - 用于引用式传入输出值。动态图下 ``out`` 可以是任意 Tensor，默认值为 ``None``。 返回 ::::::::: @@ -49,7 +50,7 @@ COPY-FROM: paddle.scatter:scatter-example-2 ===== -.. py:function:: paddle.scatter(input, dim, index, src, reduce=None, out=None) +.. py:function:: paddle.scatter(input, dim, index, src=None, reduce=None, out=None, value=None) PyTorch 兼容的 scatter 函数。基于 :ref:`cn_api_paddle_put_along_axis` 实现，等效于 ``paddle.put_along_axis(..., broadcast=False)``。详细的用法见 :ref:`cn_api_paddle_put_along_axis`。 diff --git a/docs/api/paddle/strided_slice_cn.rst b/docs/api/paddle/strided_slice_cn.rst index 37623c66a3a..11fa5bcbdde 100644 --- a/docs/api/paddle/strided_slice_cn.rst +++ b/docs/api/paddle/strided_slice_cn.rst @@ -2,7 +2,7 @@ strided_slice ------------------------------- -.. py:function:: paddle.strided_slice(x, axes, starts, ends, strides, name) +.. py:function:: paddle.strided_slice(x, axes, starts, ends, strides, name=None) @@ -48,7 +48,7 @@ strided_slice 算子。 :::::::::::: - - **x** （Tensor）- 多维 ``Tensor``，数据类型为 ``bool``, ``float32``，``float64``，``int32``，或 ``int64``。 + - **x** （Tensor）- 多维 ``Tensor``，数据类型为 ``bool``、``float16``、``float32``、``float64``、``int32`` 或 ``int64``。 - **axes** （list|tuple）- 数据类型是 ``int32``。表示进行切片的轴。 - **starts** （list|tuple|Tensor）- 数据类型是 ``int32``。如果 ``starts`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[]的 ``0-D Tensor``。如果 ``starts`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的起始索引值。 - **ends** （list|tuple|Tensor）- 数据类型是 ``int32``。如果 ``ends`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[]的 ``0-D Tensor``。如果 ``ends`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的结束索引值。 From 3cfd6951b431e1fc345227cb4a63f26905ec1e4f Mon Sep 17 00:00:00 2001 From: manfredss Date: Wed, 12 Aug 2026 16:08:10 +0800 Subject: [PATCH 07/18] add 12 more apis --- docs/api/paddle/bitwise_left_shift_cn.rst | 11 ++++++++--- docs/api/paddle/bitwise_right_shift_cn.rst | 11 ++++++++--- docs/api/paddle/dstack_cn.rst | 8 ++++++-- docs/api/paddle/grad_cn.rst | 11 ++++++++--- docs/api/paddle/imag_cn.rst | 6 +++++- docs/api/paddle/masked_select_cn.rst | 9 ++++++--- docs/api/paddle/mod_cn.rst | 10 +++++++--- docs/api/paddle/mode_cn.rst | 2 +- docs/api/paddle/nanquantile_cn.rst | 5 ++--- docs/api/paddle/quantile_cn.rst | 10 +++++++--- docs/api/paddle/row_stack_cn.rst | 8 ++++++-- 11 files changed, 64 insertions(+), 27 deletions(-) diff --git a/docs/api/paddle/bitwise_left_shift_cn.rst b/docs/api/paddle/bitwise_left_shift_cn.rst index 7d92b7c5ac0..b4e71dcca15 100644 --- a/docs/api/paddle/bitwise_left_shift_cn.rst +++ b/docs/api/paddle/bitwise_left_shift_cn.rst @@ -3,7 +3,7 @@ bitwise_left_shift ------------------------------- -.. py:function:: paddle.bitwise_left_shift(x, y, is_arithmetic=True, out=None, name=None) +.. py:function:: paddle.bitwise_left_shift(x, y, is_arithmetic=True, name=None, *, out=None) 对 Tensor ``x`` 和 ``y`` 逐元素进行 ``按位算术(或逻辑)左移`` 运算。 @@ -45,15 +45,20 @@ bitwise_left_shift ``paddle.bitwise_left_shift`` 遵守 broadcasting，如您想了解更多，请参见 `Tensor 介绍`_ . .. _Tensor 介绍: ../../guides/beginner/tensor_cn.html#id7 + 参数 :::::::::::: - **x** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``input``。 - **y** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``other``。 - - **is_arithmetic** （bool） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **is_arithmetic** （bool，可选） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: diff --git a/docs/api/paddle/bitwise_right_shift_cn.rst b/docs/api/paddle/bitwise_right_shift_cn.rst index c76150d23f6..35db366c70e 100644 --- a/docs/api/paddle/bitwise_right_shift_cn.rst +++ b/docs/api/paddle/bitwise_right_shift_cn.rst @@ -3,7 +3,7 @@ bitwise_right_shift ------------------------------- -.. py:function:: paddle.bitwise_right_shift(x, y, is_arithmetic=True, out=None, name=None) +.. py:function:: paddle.bitwise_right_shift(x, y, is_arithmetic=True, name=None, *, out=None) 对 Tensor ``x`` 和 ``y`` 逐元素进行 ``按位算术(或逻辑)右移`` 运算。 @@ -14,15 +14,20 @@ bitwise_right_shift ``paddle.bitwise_right_shift`` 遵守 broadcasting，如您想了解更多，请参见 `Tensor 介绍`_ . .. _Tensor 介绍: ../../guides/beginner/tensor_cn.html#id7 + 参数 :::::::::::: - **x** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``input``。 - **y** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``other``。 - - **is_arithmetic** （bool） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **is_arithmetic** （bool，可选） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``按位算术(逻辑)右移`` 运算后的结果 ``Tensor``，数据类型与 ``x`` 相同。 diff --git a/docs/api/paddle/dstack_cn.rst b/docs/api/paddle/dstack_cn.rst index 5b458c360fc..cdb2daf49df 100644 --- a/docs/api/paddle/dstack_cn.rst +++ b/docs/api/paddle/dstack_cn.rst @@ -3,16 +3,20 @@ dstack ------------------------------- -.. py:function:: paddle.dstack(x, name=None) +.. py:function:: paddle.dstack(x, name=None, *, out=None) 沿深度轴堆叠输入 ``x`` 中的所有张量。所有张量必须具有相同的数据类型。 参数 :::::::::::: - - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。 + - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int8`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。别名 ``tensors``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与输入数据类型相同的堆叠张量。 diff --git a/docs/api/paddle/grad_cn.rst b/docs/api/paddle/grad_cn.rst index 13ee55a2a09..d1a6d7b79aa 100644 --- a/docs/api/paddle/grad_cn.rst +++ b/docs/api/paddle/grad_cn.rst @@ -4,7 +4,7 @@ grad ------------------------------- -.. py:function:: paddle.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False, no_grad_vars=None) +.. py:function:: paddle.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False, no_grad_vars=None, *, dump_backward_graph_path=None) .. note:: 该 API 仅支持 **动态图模式**。 @@ -20,13 +20,18 @@ grad - **retain_graph** (bool，可选) - 是否保留计算梯度的前向图。若值为 True，则前向图会保留，用户可对同一张图求两次反向。若值为 False，则前向图会释放。默认值为 None，表示值与 ``create_graph`` 相等。 - **create_graph** (bool，可选) - 是否创建计算过程中的反向图。若值为 True，则可支持计算高阶导数。若值为 False，则计算过程中的反向图会释放。默认值为 False。 - **only_inputs** (bool，可选) - 是否只计算 ``inputs`` 的梯度。若值为 False，则图中所有叶节点变量的梯度均会计算，并进行累加。若值为 True，则只会计算 ``inputs`` 的梯度。默认值为 True。only_inputs=False 功能正在开发中，目前尚不支持。 - - **allow_unused** (bool，可选) - 决定当某些 ``inputs`` 变量不在计算图中时抛出错误还是返回 None。若某些 ``inputs`` 变量不在计算图中（即它们的梯度为 None），则当 allowed_unused=False 时会抛出错误，当 allow_unused=True 时会返回 None 作为这些变量的梯度。默认值为 False。 + - **allow_unused** (bool，可选) - 决定当某些 ``inputs`` 变量不在计算图中时抛出错误还是返回 None。若某些 ``inputs`` 变量不在计算图中（即它们的梯度为 None），则当 allow_unused=False 时会抛出错误，当 allow_unused=True 时会返回 None 作为这些变量的梯度。默认值为 False。 - **no_grad_vars** (Tensor|list(Tensor)|tuple(Tensor)|set(Tensor)，可选) - 指明不需要计算梯度的变量。默认值为 None。 +关键字参数 +::::::::: + + - **dump_backward_graph_path** (str，可选) - 用于保存调试文件的目录路径。指定该参数后，会在此目录中生成反向相关图（dot 格式）和调试调用栈信息。默认值为 None。 + 返回 ::::::::: -tuple(Tensor)，其长度等于 ``inputs`` 中的变量个数，且第 i 个返回的变量是所有 ``outputs`` 相对于第 i 个 ``inputs`` 的梯度之和。 +list(Tensor)，其长度等于 ``inputs`` 中的变量个数，且第 i 个返回的变量是所有 ``outputs`` 相对于第 i 个 ``inputs`` 的梯度之和。 代码示例 1 ::::::::: diff --git a/docs/api/paddle/imag_cn.rst b/docs/api/paddle/imag_cn.rst index 5f15f51a4b5..d0f4251d0a3 100644 --- a/docs/api/paddle/imag_cn.rst +++ b/docs/api/paddle/imag_cn.rst @@ -3,7 +3,7 @@ imag ------ -.. py:function:: paddle.imag(x, name=None) +.. py:function:: paddle.imag(x, name=None, *, out=None) 返回一个包含输入复数 Tensor 的虚部数值的新 Tensor。 @@ -13,6 +13,10 @@ imag - **x** (Tensor) - 输入的 Tensor，其数据类型可以为 complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，包含原复数 Tensor 的虚部数值。 diff --git a/docs/api/paddle/masked_select_cn.rst b/docs/api/paddle/masked_select_cn.rst index 551b86a234b..1046190726e 100644 --- a/docs/api/paddle/masked_select_cn.rst +++ b/docs/api/paddle/masked_select_cn.rst @@ -3,7 +3,7 @@ masked_select ------------------------------- -.. py:function:: paddle.masked_select(x, mask, name=None) +.. py:function:: paddle.masked_select(x, mask, name=None, *, out=None) @@ -15,11 +15,14 @@ masked_select 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为 float32，float64，int32 或者 int64。 + - **x** (Tensor) - 输入 Tensor，数据类型为 float16、float32、float64、uint16、int32 或 int64。 别名： ``input`` - **mask** (Tensor) - 用于索引的二进制掩码的 Tensor，数据类型为 bool。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** （Tensor，可选） - 指定输出结果的 ``Tensor``，默认值为 None。 + +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: diff --git a/docs/api/paddle/mod_cn.rst b/docs/api/paddle/mod_cn.rst index f9049f3c6aa..a785947d2de 100644 --- a/docs/api/paddle/mod_cn.rst +++ b/docs/api/paddle/mod_cn.rst @@ -3,7 +3,7 @@ mod ------------------------------- -.. py:function:: paddle.mod(x, y, name=None) +.. py:function:: paddle.mod(x, y, name=None, *, out=None) 逐元素取模算子。公式为： @@ -17,10 +17,14 @@ mod 参数 ::::::::: - - **x** (Tensor) - 多维 Tensor。数据类型为 float16、float32 、float64、int32 或 int64。 - - **y** (Tensor) - 多维 Tensor。数据类型为 float16、float32 、float64、int32 或 int64。 + - **x** (Tensor) - 多维 Tensor。别名 ``input``。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。 + - **y** (Tensor) - 多维 Tensor。别名 ``other``。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: ``Tensor``，存储运算后的结果。如果 x 和 y 有不同的 shape 且是可以广播的，返回 Tensor 的 shape 是 x 和 y 经过广播后的 shape。如果 x 和 y 有相同的 shape，返回 Tensor 的 shape 与 x，y 相同。 diff --git a/docs/api/paddle/mode_cn.rst b/docs/api/paddle/mode_cn.rst index bbb8630525e..74e1ae6a9c4 100644 --- a/docs/api/paddle/mode_cn.rst +++ b/docs/api/paddle/mode_cn.rst @@ -11,7 +11,7 @@ mode ::::::::: - **x** （Tensor） - 输入的多维 ``Tensor``，支持的数据类型：float32、float64、int32、int64。别名 ``input``。 - **axis** （int，可选） - 指定对输入 Tensor 进行运算的轴，``axis`` 的有效范围是[-R, R），R 是输入 ``x`` 的 Rank， ``axis`` 为负时与 ``axis`` + R 等价。默认值为-1。别名 ``dim``。 - - **keepdim** （bool，可选）- 是否保留指定的轴。如果是 True，维度会与输入 x 一致，对应所指定的轴的 size 为 1。否则，由于对应轴被展开，输出的维度会比输入小 1。默认值为 1。 + - **keepdim** （bool，可选）- 是否保留指定的轴。如果是 True，维度会与输入 x 一致，对应所指定的轴的 size 为 1。否则，由于对应轴被展开，输出的维度会比输入小 1。默认值为 False。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 diff --git a/docs/api/paddle/nanquantile_cn.rst b/docs/api/paddle/nanquantile_cn.rst index 54a4982d563..2a3cfa93610 100644 --- a/docs/api/paddle/nanquantile_cn.rst +++ b/docs/api/paddle/nanquantile_cn.rst @@ -3,18 +3,17 @@ nanquantile ------------------------------- -.. py:function:: paddle.nanquantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None, *, out=None) +.. py:function:: paddle.nanquantile(x, q, axis=None, keepdim=False, interpolation='linear', *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的分位数, 忽略元素中的 ``NaN`` 。 参数 :::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：bfloat16、float16、float32、float64、int32、int64。别名：``input``。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。别名：``input``。 - **q** (int|float|list|Tensor) - 待计算的分位数，需要在符合取值范围[0, 1]。如果 ``q`` 是 List 或者 1-D Tensor，其中的每一个 q 分位数都会被计算，并且输出的首维大小与列表或 Tensor 中元素的数量相同。如果 ``q`` 是 0-D Tensor ，则会被当作 float 和 int 对待。 - **axis** (int|list，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 list，对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算分位数。默认值为 None。别名：``dim``。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如果 ``keepdim`` 为 True，则输出 Tensor 和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为 1)。否则，输出 Tensor 的形状会在 ``axis`` 上进行 squeeze 操作。默认值为 False。 - **interpolation** (str，可选) - 计算分位数的插值方法，可以是 ``linear`` , ``lower`` , ``higher`` , ``nearest`` 或者 ``midpoint`` 。 默认值为 ``linear`` 。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 :::::::::: diff --git a/docs/api/paddle/quantile_cn.rst b/docs/api/paddle/quantile_cn.rst index c3f1f328b2d..bf3ac4e220a 100644 --- a/docs/api/paddle/quantile_cn.rst +++ b/docs/api/paddle/quantile_cn.rst @@ -3,19 +3,23 @@ quantile ------------------------------- -.. py:function:: paddle.quantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None) +.. py:function:: paddle.quantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None, *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的分位数。 参数 :::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。别名 ``input``。 - **q** (int|float|list|Tensor) - 待计算的分位数，需要在符合取值范围[0, 1]。如果 ``q`` 是 List 或者 1-D Tensor，其中的每一个 q 分位数都会被计算，并且输出的首维大小与列表或 Tensor 中元素的数量相同。如果 ``q`` 是 0-D Tensor ，则会被当作 float 和 int 对待。 - - **axis** (int|list，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 list，对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算分位数。默认值为 None。 + - **axis** (int|list，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 list，对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算分位数。默认值为 None。别名 ``dim``。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如果 ``keepdim`` 为 True，则输出 Tensor 和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为 1)。否则，输出 Tensor 的形状会在 ``axis`` 上进行 squeeze 操作。默认值为 False。 - **interpolation** (str，可选) - 计算分位数的插值方法，可以是 ``linear`` , ``lower`` , ``higher`` , ``nearest`` 或者 ``midpoint`` 。 默认值为 ``linear`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::: ``Tensor``，沿着 ``axis`` 进行分位数计算的结果。与输入数据类型一致。 diff --git a/docs/api/paddle/row_stack_cn.rst b/docs/api/paddle/row_stack_cn.rst index 9ba489aa91b..ad4637e98c4 100644 --- a/docs/api/paddle/row_stack_cn.rst +++ b/docs/api/paddle/row_stack_cn.rst @@ -3,7 +3,7 @@ row_stack ------------------------------- -.. py:function:: paddle.row_stack(x, name=None) +.. py:function:: paddle.row_stack(x, name=None, *, out=None) :ref:`cn_api_paddle_vstack` 的别名。沿垂直轴堆叠输入 ``x`` 中的所有张量。所有张量必须具有相同的数据类型。 @@ -16,9 +16,13 @@ row_stack 参数 :::::::::::: - - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。 + - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int8`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。别名 ``tensors``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与输入数据类型相同的堆叠张量。 From 234934297e4a1bef4ab743d1eaaa2210e59e13d0 Mon Sep 17 00:00:00 2001 From: manfredss Date: Wed, 12 Aug 2026 17:20:55 +0800 Subject: [PATCH 08/18] add 15 more apis --- docs/api/paddle/bucketize_cn.rst | 10 ++++-- docs/api/paddle/column_stack_cn.rst | 8 +++-- docs/api/paddle/floor_divide_cn.rst | 10 +++--- docs/api/paddle/linspace_cn.rst | 12 +++++-- docs/api/paddle/logical_and_cn.rst | 8 +++-- docs/api/paddle/logical_not_cn.rst | 10 ++++-- docs/api/paddle/logical_or_cn.rst | 8 +++-- docs/api/paddle/logical_xor_cn.rst | 8 +++-- docs/api/paddle/outer_cn.rst | 6 +++- docs/api/paddle/qr_cn.rst | 37 ++++++++++++++++----- docs/api/paddle/random/get_rng_state_cn.rst | 11 ++++-- docs/api/paddle/random/set_rng_state_cn.rst | 7 ++-- docs/api/paddle/searchsorted_cn.rst | 10 ++++-- docs/api/paddle/standard_normal_cn.rst | 10 ++++-- docs/api/paddle/tensordot_cn.rst | 7 ++-- 15 files changed, 116 insertions(+), 46 deletions(-) diff --git a/docs/api/paddle/bucketize_cn.rst b/docs/api/paddle/bucketize_cn.rst index 6edc06694fd..81e174e965e 100644 --- a/docs/api/paddle/bucketize_cn.rst +++ b/docs/api/paddle/bucketize_cn.rst @@ -3,18 +3,22 @@ bucketize ------------------------------- -.. py:function:: paddle.bucketize(x, sorted_sequence, out_int32=False, right=False, name=None) +.. py:function:: paddle.bucketize(x, sorted_sequence, out_int32=False, right=False, name=None, *, out=None) 将根据给定的一维 Tensor ``sorted_sequence`` 返回输入 ``x`` 对应的桶索引。 参数 :::::::::: - - **x** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：int32、int64、float32、float64。 - - **sorted_sequence** (Tensor) - 输入的一维 Tensor，支持的数据类型：int32、int64、float32、float64。该 Tensor 的数值在其最后一个维度递增。 + - **x** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：int32、int64、float32、float64。别名 ``input``。 + - **sorted_sequence** (Tensor) - 输入的一维 Tensor，支持的数据类型：int32、int64、float32、float64。该 Tensor 的数值在其最后一个维度递增。别名 ``boundaries``。 - **out_int32** (bool，可选) - 输出的数据类型支持 int32、int64。默认值为 False，表示默认的输出数据类型为 int64。 - **right** (bool，可选) - 根据给定 ``x`` 在 ``sorted_sequence`` 查找对应的上边界或下边界。如果 ``sorted_sequence`` 的值为 nan 或 inf，则返回最内层维度的大小。默认值为 False，表示在 ``sorted_sequence`` 的查找给定 ``x`` 的下边界。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::: Tensor(与 ``x`` 维度相同)，如果参数 ``out_int32`` 为 False，则返回数据类型为 int64 的 Tensor，否则将返回 int32 的 Tensor。 diff --git a/docs/api/paddle/column_stack_cn.rst b/docs/api/paddle/column_stack_cn.rst index 40b60db1f13..0cf5555d882 100644 --- a/docs/api/paddle/column_stack_cn.rst +++ b/docs/api/paddle/column_stack_cn.rst @@ -3,7 +3,7 @@ column_stack ------------------------------- -.. py:function:: paddle.column_stack(x, name=None) +.. py:function:: paddle.column_stack(x, name=None, *, out=None) 沿水平轴堆叠输入 ``x`` 中的所有张量。 ``x`` 中的每个张量 ``tensor`` 如果在堆叠之前 ``tensor.ndim < 2`` ，则首先被整形为 ``(tensor.numel(), 1)``。所有张量必须具有相同的数据类型。 @@ -16,9 +16,13 @@ column_stack 参数 :::::::::::: - - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。 + - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int8``、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。别名 ``tensors``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与输入数据类型相同的堆叠张量。 diff --git a/docs/api/paddle/floor_divide_cn.rst b/docs/api/paddle/floor_divide_cn.rst index 9edd21e671d..fad3b3699dd 100644 --- a/docs/api/paddle/floor_divide_cn.rst +++ b/docs/api/paddle/floor_divide_cn.rst @@ -3,7 +3,7 @@ floor_divide ------------------------------- -.. py:function:: paddle.floor_divide(x, y, name=None) +.. py:function:: paddle.floor_divide(x, y, name=None, *, out=None) 逐元素整除算子，将输入 ``x`` 与输入 ``y`` 逐元素整除（商被朝 -inf 方向舍入到最接近的整数值），并将各个位置的输出元素保存到返回结果中。 @@ -26,13 +26,15 @@ floor_divide 参数 ::::::::: - - **x** (Tensor) - 多维 Tensor。数据类型为 int8 int16 int32 int64 float32 float64 float16 或 bfloat16。 + - **x** (Tensor) - 多维 Tensor。数据类型为 uint8、int8、int16、int32、int64、float16、bfloat16、float32 或 float64。 别名： ``input`` - - **y** (Tensor) - 多维 Tensor。数据类型为 int8 int16 int32 int64 float32 float64 float16 或 bfloat16。 + - **y** (Tensor|Number) - 多维 Tensor 或数值标量。数据类型为 uint8、int8、int16、int32、int64、float16、bfloat16、float32 或 float64。 别名： ``other`` - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** （Tensor，可选） - 指定输出结果的 ``Tensor``，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 ::::::::: diff --git a/docs/api/paddle/linspace_cn.rst b/docs/api/paddle/linspace_cn.rst index ee8febc1376..db13f988ffc 100644 --- a/docs/api/paddle/linspace_cn.rst +++ b/docs/api/paddle/linspace_cn.rst @@ -3,7 +3,7 @@ linspace ------------------------------- -.. py:function:: paddle.linspace(start, stop, num, dtype=None, name=None) +.. py:function:: paddle.linspace(start, stop, num, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回一个 Tensor，Tensor 的值为在区间 start 和 stop 上均匀间隔的 num 个值，输出 Tensor 的长度为 num。 **注意：不进行梯度计算** @@ -12,11 +12,17 @@ linspace :::::::::::: - **start** (int|float|Tensor) – ``start`` 是区间开始的变量，可以是一个 int、float，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型可以是 int32，int64，float32，float64。 - - **stop** (int|float|Tensor) – ``stop`` 是区间结束的变量，可以是一个 int、float，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型可以是 int32，int64，float32，float64。 - - **num** (int|Tensor) – ``num`` 是给定区间内需要划分的区间数，可以是一个 int，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型需为 int32。 + - **stop** (int|float|Tensor) – ``stop`` 是区间结束的变量，可以是一个 int、float，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型可以是 int32，int64，float32，float64。别名 ``end``。 + - **num** (int|Tensor) – ``num`` 是给定区间内需要划分的区间数，可以是一个 int，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型需为 int32。别名 ``steps``。 - **dtype** (str|paddle.dtype|np.dtype，可选) – 输出 Tensor 的数据类型，可以是 int32，int64，float32，float64。如果 dtype 的数据类型为 None，输出 Tensor 数据类型为 float32。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor|None，可选) - 可选的输出 Tensor。若提供，计算结果将保存在该 Tensor 中；该 Tensor 的形状和数据类型必须正确。默认值为 None。 + - **device** (str|paddle.CUDAPlace|paddle.CPUPlace|None，可选) - 输出 Tensor 所在设备。可以是设备字符串、``paddle.CUDAPlace`` 或 ``paddle.CPUPlace``；为 None 时使用当前设备上下文。默认值为 None。 + - **requires_grad** (bool，可选) - 输出 Tensor 是否启用梯度计算。若为 True，则其 ``stop_gradient`` 属性将设为 False。默认值为 False。 + 返回 :::::::::::: 表示等间隔划分结果的 1-D Tensor，该 Tensor 的 shape 大小为 :math:`[num]`，在 num 为 1 的情况下，仅返回包含 start 元素值的 Tensor。 diff --git a/docs/api/paddle/logical_and_cn.rst b/docs/api/paddle/logical_and_cn.rst index 3e77c477117..d194f4fb649 100644 --- a/docs/api/paddle/logical_and_cn.rst +++ b/docs/api/paddle/logical_and_cn.rst @@ -3,7 +3,7 @@ logical_and ------------------------------- -.. py:function:: paddle.logical_and(x, y, out=None, name=None) +.. py:function:: paddle.logical_and(x, y, name=None, *, out=None) 逐元素的对 ``x`` 和 ``y`` 进行逻辑与运算。 @@ -25,9 +25,13 @@ logical_and 别名： ``input`` - **y** （Tensor） - 输入的 ``Tensor``，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``other`` - - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``Tensor``，维度 ``x`` 维度相同，存储运算后的结果。 diff --git a/docs/api/paddle/logical_not_cn.rst b/docs/api/paddle/logical_not_cn.rst index 1e9341763b1..921893467d1 100644 --- a/docs/api/paddle/logical_not_cn.rst +++ b/docs/api/paddle/logical_not_cn.rst @@ -3,7 +3,7 @@ logical_not ------------------------------- -.. py:function:: paddle.logical_not(x, out=None, name=None) +.. py:function:: paddle.logical_not(x, name=None, *, out=None) @@ -21,12 +21,16 @@ logical_not - **x** （Tensor） - 逻辑非运算的输入，是一个 Tensor，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``input`` - - **out** （Tensor，可选） - 指定算子输出结果的 Tensor，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 Tensor，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: -Tensor，与 ``x`` 维度相同，数据类型相同。 +Tensor，与 ``x`` 维度相同。 代码示例 diff --git a/docs/api/paddle/logical_or_cn.rst b/docs/api/paddle/logical_or_cn.rst index 05199ab5693..191de14006b 100644 --- a/docs/api/paddle/logical_or_cn.rst +++ b/docs/api/paddle/logical_or_cn.rst @@ -3,7 +3,7 @@ logical_or ------------------------------- -.. py:function:: paddle.logical_or(x, y, out=None, name=None) +.. py:function:: paddle.logical_or(x, y, name=None, *, out=None) 逐元素的对 ``X`` 和 ``Y`` 进行逻辑或运算。 @@ -25,9 +25,13 @@ logical_or 别名： ``input`` - **y** （Tensor）- 输入的 ``Tensor``，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``other`` - - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``Tensor``，维度 ``x`` 维度相同，存储运算后的结果。 diff --git a/docs/api/paddle/logical_xor_cn.rst b/docs/api/paddle/logical_xor_cn.rst index 5380f1fcac3..7d502567d49 100644 --- a/docs/api/paddle/logical_xor_cn.rst +++ b/docs/api/paddle/logical_xor_cn.rst @@ -3,7 +3,7 @@ logical_xor ------------------------------- -.. py:function:: paddle.logical_xor(x, y, out=None, name=None) +.. py:function:: paddle.logical_xor(x, y, name=None, *, out=None) 逐元素的对 ``X`` 和 ``Y`` 进行逻辑异或运算。 @@ -25,9 +25,13 @@ logical_xor 别名： ``input`` - **y** （Tensor） - 输入的 ``Tensor``，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``other`` - - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``Tensor``，维度 ``x`` 维度相同，存储运算后的结果。 diff --git a/docs/api/paddle/outer_cn.rst b/docs/api/paddle/outer_cn.rst index f71af5b65a7..95cc1919b1a 100644 --- a/docs/api/paddle/outer_cn.rst +++ b/docs/api/paddle/outer_cn.rst @@ -3,7 +3,7 @@ outer ------------------------------- -.. py:function:: paddle.outer(x, y, name=None) +.. py:function:: paddle.outer(x, y, name=None, *, out=None) 计算两个 Tensor 的外积。 @@ -20,6 +20,10 @@ outer - **y** (Tensor) - 一个 N 维 Tensor 或者标量 Tensor。别名： ``vec2``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/qr_cn.rst b/docs/api/paddle/qr_cn.rst index cef3336d8fc..813a7a68b2c 100644 --- a/docs/api/paddle/qr_cn.rst +++ b/docs/api/paddle/qr_cn.rst @@ -3,27 +3,46 @@ qr ------------------------------- -.. py:function:: paddle.qr(input, some=True, *, out=None) +.. py:function:: paddle.qr(x, mode='reduced', name=None, *, out=None) -计算一个或一批矩阵的 QR 分解。 +.. note:: -该 API 是 ``paddle.linalg.qr`` 的封装，并提供 ``some`` 参数来控制 QR 分解的返回形式。 + 本 API 支持两种签名方式： + + 1. ``paddle.qr(x, mode='reduced', name=None, *, out=None)``（Paddle 风格）：通过 ``mode`` 字符串参数控制 QR 分解。 + 2. ``paddle.qr(input, some=True, *, out=None)``（PyTorch 风格）：通过 ``some`` 布尔参数控制 QR 分解。 + +计算一个或一批矩阵的正交三角分解，也称 QR 分解（暂不支持反向）。 + +记 :math:`X` 为一个矩阵，则计算的结果为 2 个矩阵 :math:`Q` 和 :math:`R`，则满足公式： + +.. math:: + X = Q * R + +其中，:math:`Q` 是正交矩阵，:math:`R` 是上三角矩阵。 参数 :::::::::::: - - **input** (Tensor) - 输入 Tensor，形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度。 - - **some** (bool，可选) - 控制 QR 分解的行为。若为 ``True``（默认），返回 reduced 的 Q 和 R 矩阵， - 即 Q 的形状为 ``[*, M, K]``，R 的形状为 ``[*, K, N]``，其中 ``K = min(M, N)``。 - 若为 ``False``，返回 complete 的 Q 和 R 矩阵，即 Q 的形状为 ``[*, M, M]``，R 的形状为 ``[*, M, N]`` + - **x** (Tensor)：输入进行正交三角分解的一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。别名 ``input``, ``A``。 + - **mode** (str，可选)：控制正交三角分解的行为，默认是 ``reduced``，假设 ``x`` 形状应为 ``[*, M, N]`` 和 ``K = min(M, N)``： + 如果 ``mode = "reduced"``，则 :math:`Q` 形状为 ``[*, M, K]`` 和 :math:`R` 形状为 ``[*, K, N]``； + 如果 ``mode = "complete"``，则 :math:`Q` 形状为 ``[*, M, M]`` 和 :math:`R` 形状为 ``[*, M, N]``； + 如果 ``mode = "r"``，则**只返回**缩减的 :math:`R`，其形状为 ``[*, K, N]``。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 :::::::::::: - - **out** (tuple[Tensor, Tensor]，可选) - 输出 (Q, R) 的元组。默认值为 None。 + - **out** (Tensor|tuple，可选) - 指定输出的张量。 + 当 ``mode = "r"`` 时，为一个 Tensor 用于存储 R； + 否则为一个 ``(Q, R)`` 张量元组，默认值为 None。 返回 :::::::::::: -tuple[Tensor, Tensor]，QR 分解后的 (Q, R) 元组。 + - 如果 ``mode = "r"``，返回 Tensor R，即缩减的上三角矩阵。 + - 否则返回 ``QrRetType(Q, R)`` 具名元组： + - Tensor Q，正交三角分解的 Q 正交矩阵。 + - Tensor R，正交三角分解的 R 上三角矩阵。 代码示例 :::::::::::: diff --git a/docs/api/paddle/random/get_rng_state_cn.rst b/docs/api/paddle/random/get_rng_state_cn.rst index 3618023e306..ff17e8c2a0f 100644 --- a/docs/api/paddle/random/get_rng_state_cn.rst +++ b/docs/api/paddle/random/get_rng_state_cn.rst @@ -3,10 +3,15 @@ get_rng_state ------------------------------- -.. py:function:: paddle.random.get_rng_state() +.. py:function:: paddle.random.get_rng_state(device=None) -``paddle.device.cpu.get_rng_state`` 的别名，请参考 :ref:`cn_api_paddle_get_rng_state`。 +获取默认随机数生成器的随机状态。 + +参数 +::::::::: + + - **device** (_CPUPlaceLike|None，可选) - 要获取随机状态的设备。默认值为 None。 返回 ::::::::: -Tensor：CPU 随机数生成器的初始种子值。 +Tensor：随机状态 Tensor。 diff --git a/docs/api/paddle/random/set_rng_state_cn.rst b/docs/api/paddle/random/set_rng_state_cn.rst index d746f64fbc1..4211244941f 100644 --- a/docs/api/paddle/random/set_rng_state_cn.rst +++ b/docs/api/paddle/random/set_rng_state_cn.rst @@ -3,13 +3,14 @@ set_rng_state ------------------------------- -.. py:function:: paddle.random.set_rng_state(new_state) +.. py:function:: paddle.random.set_rng_state(new_state, device=None) -``paddle.device.cpu.set_rng_state`` 的别名，请参考 :ref:`cn_api_paddle_set_rng_state`。 +设置指定设备的随机数生成器状态。 参数 ::::::::: - - **new_state** (Tensor) - 要设置的 CPU 随机数生成器的初始种子值。通过 ``get_rng_state()`` 获得。 + - **new_state** (core.GeneratorState) - 要设置的随机数生成器状态，应由 ``get_rng_state()`` 获得。 + - **device** (DeviceLike，可选) - 要设置随机状态的设备。未指定时使用当前默认设备；可以是设备对象、整数设备 ID 或设备字符串。默认值为 None。 返回 diff --git a/docs/api/paddle/searchsorted_cn.rst b/docs/api/paddle/searchsorted_cn.rst index 36917323956..9da55def69a 100644 --- a/docs/api/paddle/searchsorted_cn.rst +++ b/docs/api/paddle/searchsorted_cn.rst @@ -3,18 +3,24 @@ searchsorted ------------------------------- -.. py:function:: paddle.searchsorted(sorted_sequence, values, out_int32=False, right=False, name=None) +.. py:function:: paddle.searchsorted(sorted_sequence, values, out_int32=False, right=False, name=None, *, side=None, out=None, sorter=None) 根据给定的 ``values`` 在 ``sorted_sequence`` 的最后一个维度查找合适的索引。 参数 :::::::: - **sorted_sequence** (Tensor) - 输入的 N 维或一维 Tensor，支持的数据类型：bfloat16、float16、float32、float64、int32、int64。该 Tensor 的数值在其最后一个维度递增。 - - **values** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：bfloat16、float16、float32、float64、int32、int64。 + - **values** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：bfloat16、float16、float32、float64、int32、int64。别名 ``input``。 - **out_int32** (bool，可选) - 输出的数据类型支持 int32、int64。默认值为 False，表示默认的输出数据类型为 int64。 - **right** (bool，可选) - 根据给定 ``values`` 在 ``sorted_sequence`` 查找对应的上边界或下边界。如果 ``sorted_sequence`` 的值为 nan 或 inf，则返回最内层维度的大小。默认值为 False，表示在 ``sorted_sequence`` 的查找给定 ``values`` 的下边界。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **side** (str|None，可选) - 与 ``right`` 作用相同，但推荐使用该参数。``"left"`` 对应 ``right=False``，``"right"`` 对应 ``right=True``；若其为 ``"left"`` 且 ``right=True``，会报错。默认值为 None。 + - **out** (Tensor|None，可选) - 输出 Tensor。默认值为 None。 + - **sorter** (Tensor|None，可选) - 可选的索引 Tensor，形状应与未排序的 ``sorted_sequence`` 相同；其索引序列应能在最后一维将 ``sorted_sequence`` 升序排序。 + 返回 :::::::: Tensor(与 ``values`` 维度相同)，如果参数 ``out_int32`` 为 False，则返回数据类型为 int64 的 Tensor，否则将返回 int32 的 Tensor。 diff --git a/docs/api/paddle/standard_normal_cn.rst b/docs/api/paddle/standard_normal_cn.rst index 214886c337a..ad093ee2811 100644 --- a/docs/api/paddle/standard_normal_cn.rst +++ b/docs/api/paddle/standard_normal_cn.rst @@ -3,16 +3,22 @@ standard_normal ------------------------------- -.. py:function:: paddle.standard_normal(shape, dtype=None, name=None) +.. py:function:: paddle.standard_normal(shape, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回符合标准正态分布（均值为 0，标准差为 1 的正态随机分布）的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 :::::::::: - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64、complex64、complex128。当该参数值为 None 时，输出 Tensor 的数据类型为 float32。默认值为 None。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64、complex64、complex128。默认值为 None，此时使用全局默认数据类型（详细信息请见 :ref:`cn_api_paddle_get_default_dtype` ）。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，使用当前默认 Tensor 类型的当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：符合标准正态分布的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/tensordot_cn.rst b/docs/api/paddle/tensordot_cn.rst index 2fba030f78b..5160c8b98f2 100644 --- a/docs/api/paddle/tensordot_cn.rst +++ b/docs/api/paddle/tensordot_cn.rst @@ -3,7 +3,7 @@ tensordot ------------------------------- -.. py:function:: paddle.tensordot(x, y, axes=2, name=None, *, out=None) +.. py:function:: paddle.tensordot(x, y, axes=2, out=None, name=None) Tensor 缩并运算（Tensor Contraction），即沿着 axes 给定的多个轴对两个 Tensor 对应元素的乘积进行加和操作。 @@ -31,11 +31,8 @@ shape = [2,2,3]的 ``res`` 张量为 a,b 两个张量沿着 a 张量的最后一 3. ``axes`` 可以是一个 tuple 或 list，其中包含一个或两个一维的整数 tuple|list|Tensor。如果 ``axes`` 包含一个 tuple|list|Tensor，则对 ``x`` 和 ``y`` 的相同轴做缩并运算，具体轴下标由该 tuple|list|Tensor 中的整数值指定。如果 ``axes`` 包含两个 tuple|list|Tensor，则第一个指定 ``x`` 做缩并运算的轴下标，第二个指定 ``y`` 的对应轴下标。如果 ``axes`` 包含两个以上的 tuple|list|Tensor，只有前两个会被作为轴下标序列使用，其它的将被忽略。 4. ``axes`` 可以是一个 Tensor，这种情况下该 Tensor 会被转换成 list，然后应用前述规则确定做缩并运算的轴。请注意，输入 Tensor 类型的 ``axes`` 只在动态图模式下可用。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - -关键字参数 -:::::::::::: - **out** (Tensor，可选) - 输出 Tensor。默认值为 None。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: From 51c6a21398abc34ea151a9f8b9a5d6f1a982baaf Mon Sep 17 00:00:00 2001 From: manfredss Date: Thu, 13 Aug 2026 15:43:24 +0800 Subject: [PATCH 09/18] add 10 more apis --- docs/api/paddle/optimizer/ASGD_cn.rst | 24 +++++++++----- docs/api/paddle/optimizer/Adadelta_cn.rst | 30 +++++++++-------- docs/api/paddle/optimizer/Adagrad_cn.rst | 11 +++++-- docs/api/paddle/optimizer/AdamW_cn.rst | 38 +++++++++++++++------- docs/api/paddle/optimizer/Adam_cn.rst | 38 +++++++++++++--------- docs/api/paddle/optimizer/Lamb_cn.rst | 34 ++++++++++++------- docs/api/paddle/optimizer/Momentum_cn.rst | 31 ++++++++++++------ docs/api/paddle/optimizer/Optimizer_cn.rst | 27 ++++++++++----- docs/api/paddle/optimizer/Rprop_cn.rst | 27 ++++++++++----- docs/api/paddle/optimizer/SGD_cn.rst | 34 +++++++++++++------ 10 files changed, 193 insertions(+), 101 deletions(-) diff --git a/docs/api/paddle/optimizer/ASGD_cn.rst b/docs/api/paddle/optimizer/ASGD_cn.rst index e5630a4d0e5..3f9a5852d13 100644 --- a/docs/api/paddle/optimizer/ASGD_cn.rst +++ b/docs/api/paddle/optimizer/ASGD_cn.rst @@ -26,10 +26,10 @@ ASGD 算法的优化器。有关详细信息，请参阅： 参数 :::::::::::: - - **learning_rate** (float|_LRScheduleri，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类。默认值为 0.001。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值、浮点类型的 Tensor 或 LRScheduler。默认值为 0.001。 - **batch_num** (int，可选) - 完成一个 epoch 所需迭代的次数。默认值为 1。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 None。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 权重衰减策略。可以是 int 或 float 类型的 L2 正则化系数，或 :ref:`cn_api_paddle_regularizer_L1Decay`、:ref:`cn_api_paddle_regularizer_L2Decay`。若参数已通过 :ref:`cn_api_paddle_ParamAttr` 设置 regularizer，则该参数的设置会被忽略；否则在优化器中生效。默认值为 None，表示不进行正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **multi_precision** (bool，可选) – 在基于 GPU 设备的混合精度训练场景中，该参数主要用于保证梯度更新的数值稳定性。设置为 True 时，优化器会针对 FP16 类型参数保存一份与其值相等的 FP32 类型参数备份。梯度更新时，首先将梯度类型提升到 FP32，然后将其更新到 FP32 类型参数备份中。最后，更新后的 FP32 类型值会先转换为 FP16 类型，再赋值给实际参与计算的 FP16 类型参数。默认为 False。 @@ -44,8 +44,8 @@ COPY-FROM: paddle.optimizer.ASGD 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -53,9 +53,13 @@ step() 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -82,8 +86,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.ASGD.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -92,6 +96,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.ASGD.clear_grad diff --git a/docs/api/paddle/optimizer/Adadelta_cn.rst b/docs/api/paddle/optimizer/Adadelta_cn.rst index eac1566700e..79ef91f78ec 100644 --- a/docs/api/paddle/optimizer/Adadelta_cn.rst +++ b/docs/api/paddle/optimizer/Adadelta_cn.rst @@ -3,7 +3,7 @@ Adadelta ------------------------------- -.. py:class:: paddle.optimizer.Adadelta(learning_rate=0.001, epsilon=1e-06, rho=0.95, parameters=None, weight_decay=0.01, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Adadelta(learning_rate=0.001, epsilon=1e-06, rho=0.95, parameters=None, weight_decay=None, grad_clip=None, name=None) .. note:: @@ -25,19 +25,15 @@ Adadelta 优化器，是对 :ref:`Adagrad ` 的 参数 :::::::::::: - - **learning_rate** (float|_LRScheduleri，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是浮点值、浮点类型的 Tensor 或 LRScheduler。默认值为 0.001。 - **epsilon** (float，可选) - 保持数值稳定性的短浮点类型值，默认值为 1e-06。 - **rho** (float，可选) - 算法中的衰减率，默认值为 0.95。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.01。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Tensor 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、:ref:`cn_api_paddle_regularizer_L2Decay`。如果参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置将被忽略；否则该设置生效。默认值为 None，表示没有正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 -Adadelta 优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION 论文 `_，用来解决 Adam 优化器中 L2 正则化失效的问题。 - - - 代码示例 :::::::::::: @@ -46,17 +42,21 @@ COPY-FROM: paddle.optimizer.Adadelta 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 @@ -83,8 +83,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Adadelta.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -92,6 +92,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Adadelta.clear_grad diff --git a/docs/api/paddle/optimizer/Adagrad_cn.rst b/docs/api/paddle/optimizer/Adagrad_cn.rst index eeeca3350a6..db014937474 100644 --- a/docs/api/paddle/optimizer/Adagrad_cn.rst +++ b/docs/api/paddle/optimizer/Adagrad_cn.rst @@ -3,7 +3,7 @@ Adagrad ------------------------------- -.. py:class:: paddle.optimizer.Adagrad(learning_rate, epsilon=1e-06, parameters=None, weight_decay=None, grad_clip=None, name=None, initial_accumulator_value=0.0) +.. py:class:: paddle.optimizer.Adagrad(learning_rate, epsilon=1e-06, parameters=None, weight_decay=None, grad_clip=None, name=None, initial_accumulator_value=0.0, *, maximize=False) Adaptive Gradient 优化器（自适应梯度优化器，简称 Adagrad）可以针对不同参数样本数不平均的问题，自适应地为各个参数分配不同的学习率。 @@ -27,8 +27,8 @@ Adaptive Gradient 优化器（自适应梯度优化器，简称 Adagrad）可以 - **learning_rate** (float|Tensor) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个值为浮点型的 Tensor。 - **epsilon** (float，可选) - 维持数值稳定性的浮点型值，默认值为 1e-06。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Tensor 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay`。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 @@ -36,6 +36,11 @@ Adaptive Gradient 优化器（自适应梯度优化器，简称 Adagrad）可以 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - **initial_accumulator_value** (float，可选) - moment 累加器的初始值，默认值为 0.0。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 :::::::::::: diff --git a/docs/api/paddle/optimizer/AdamW_cn.rst b/docs/api/paddle/optimizer/AdamW_cn.rst index 29b8a7b993d..522b29ed7e2 100755 --- a/docs/api/paddle/optimizer/AdamW_cn.rst +++ b/docs/api/paddle/optimizer/AdamW_cn.rst @@ -3,7 +3,7 @@ AdamW ------------------------------- -.. py:class:: paddle.optimizer.AdamW(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=0.01, lr_ratio=None, apply_decay_param_fun=None, grad_clip=None, lazy_mode=False, multi_precision=False, amsgrad=False, name=None) +.. py:class:: paddle.optimizer.AdamW(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=0.01, use_lowprecision_moment=False, lr_ratio=None, apply_decay_param_fun=None, grad_clip=None, lazy_mode=False, multi_precision=False, amsgrad=False, name=None, *, maximize=False) @@ -33,12 +33,13 @@ AdamW 优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 @@ -48,6 +49,11 @@ AdamW 优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION `，默认为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 :::::::::::: @@ -56,17 +62,21 @@ COPY-FROM: paddle.optimizer.AdamW 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -94,8 +104,8 @@ tuple(optimize_ops, params_grads)，其中 optimize_ops 为参数优化 OP 列 COPY-FROM: paddle.optimizer.AdamW.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -103,6 +113,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.AdamW.clear_grad diff --git a/docs/api/paddle/optimizer/Adam_cn.rst b/docs/api/paddle/optimizer/Adam_cn.rst index 450995d2207..5c9c81e923b 100755 --- a/docs/api/paddle/optimizer/Adam_cn.rst +++ b/docs/api/paddle/optimizer/Adam_cn.rst @@ -3,7 +3,7 @@ Adam ------------------------------- -.. py:class:: paddle.optimizer.Adam(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, name=None, lazy_mode=False, multi_precision=False, use_multi_tensor=False, amsgrad=False, name=None) +.. py:class:: paddle.optimizer.Adam(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, lazy_mode=False, multi_precision=False, use_multi_tensor=False, amsgrad=False, name=None) @@ -30,20 +30,20 @@ Adam 优化器出自 `Adam 论文 `_ 的第二 参数 :::::::::::: - - **learning_rate** (float|_LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **beta1** (float|Tensor，可选) - 一阶矩估计的指数衰减率，是一个 float 类型或者一个 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.9。 - - **beta2** (float|Tensor，可选) - 二阶矩估计的指数衰减率，是一个 float 类型或者一个 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.999。 - - **epsilon** (float，可选) - 保持数值稳定性的短浮点类型值，默认值为 1e-08。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 + - **learning_rate** (float|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 + - **beta1** (float|Tensor，可选) - 一阶矩估计的指数衰减率，是一个 float 类型或者形状为 ``[]``、数据类型为 float32 的 0-D Tensor。默认值为 0.9。 + - **beta2** (float|Tensor，可选) - 二阶矩估计的指数衰减率，是一个 float 类型或者形状为 ``[]``、数据类型为 float32 的 0-D Tensor。默认值为 0.999。 + - **epsilon** (float|Tensor，可选) - 保持数值稳定性的浮点值，可以是 float 类型或者形状为 ``[]``、数据类型为 float32 的 0-D Tensor。默认值为 1e-08。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Tensor 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay`。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 - - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 + - **grad_clip** (GradientClipBase，可选) - 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **lazy_mode** （bool，可选） - 设为 True 时，仅更新当前具有梯度的元素。官方 Adam 算法有两个移动平均累加器（moving-average accumulators）。累加器在每一步都会更新。在密集模式和稀疏模式下，两条移动平均线的每个元素都会更新。如果参数非常大，那么更新可能很慢。lazy mode 仅更新当前具有梯度的元素，所以它会更快。但是这种模式与原始的算法有不同的描述，可能会导致不同的结果，默认为 False。 - **multi_precision** （bool，可选） - 是否在权重更新期间使用 multi-precision，默认为 False。 - **use_multi_tensor** （bool，可选） - 是否使用 multi-tensor 策略一次性更新所有参数，默认为 False。 - - **amsgrad** （bool，可选） - 是否使用该算法的 AMSGrad 变体 :ref:`On the Convergence of Adam and Beyond `，默认为 False。 + - **amsgrad** （bool，可选） - 是否使用该算法的 AMSGrad 变体，参见论文 `On the Convergence of Adam and Beyond `_ ，默认为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 @@ -56,17 +56,21 @@ COPY-FROM: paddle.optimizer.Adam:code-example2 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -111,8 +115,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Adam.minimize -clear_grad() -'''''''''''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -120,6 +124,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Adam.clear_grad @@ -200,7 +208,7 @@ set_state_dict(state_dict) COPY-FROM: paddle.optimizer.Adam.set_state_dict -state_dict(state_dict) +state_dict() ''''''''''''''''''''''''''' 从优化器中获取 state_dict 信息，其中包含所有优化器所需的值，对于 Adam 优化器，包含 beta1，beta2，momentum 等。 diff --git a/docs/api/paddle/optimizer/Lamb_cn.rst b/docs/api/paddle/optimizer/Lamb_cn.rst index 36f9596f55b..a18899e8b94 100755 --- a/docs/api/paddle/optimizer/Lamb_cn.rst +++ b/docs/api/paddle/optimizer/Lamb_cn.rst @@ -3,7 +3,7 @@ Lamb ------------------------------- -.. py:class:: paddle.optimizer.Lamb(learning_rate=0.001, lamb_weight_decay=0.01, beta1=0.9, beta2=0.999, epsilon=1e-06, parameters=None, grad_clip=None, exclude_from_weight_decay_fn=None, name=None) +.. py:class:: paddle.optimizer.Lamb(learning_rate=0.001, lamb_weight_decay=0.01, beta1=0.9, beta2=0.999, epsilon=1e-06, parameters=None, grad_clip=None, exclude_from_weight_decay_fn=None, multi_precision=False, always_adapt=False, name=None) @@ -29,14 +29,16 @@ LAMB（Layer-wise Adaptive Moments optimizer for Batching training）优化器 参数 :::::::::::: - - **learning_rate** (float|Tensor，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个 Tensor，默认值为 0.001。 + - **learning_rate** (float|Tensor，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者数据类型为 float32 的 Tensor，默认值为 0.001。 - **lamb_weight_decay** (float，可选) – LAMB 权重衰减率。默认值为 0.01。 - - **beta1** (float，可选) - 第一个动量估计的指数衰减率。默认值为 0.9。 - - **beta2** (float，可选) - 第二个动量估计的指数衰减率。默认值为 0.999。 - - **epsilon** (float，可选) - 保持数值稳定性的短浮点类型值，默认值为 1e-06。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **beta1** (float|Tensor，可选) - 第一个动量估计的指数衰减率。默认值为 0.9。 + - **beta2** (float|Tensor，可选) - 第二个动量估计的指数衰减率。默认值为 0.999。 + - **epsilon** (float|Tensor，可选) - 保持数值稳定性的浮点值，默认值为 1e-06。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Variable 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue `。默认值为 None，此时将不进行梯度裁剪。 - - **exclude_from_weight_decay_fn** (function) - 当某个参数作为输入该函数返回值为 True 时，为该参数跳过权重衰减。 + - **exclude_from_weight_decay_fn** (Callable|None，可选) - 当某个参数作为输入该函数返回值为 True 时，为该参数跳过权重衰减。默认值为 None。 + - **multi_precision** (bool，可选) - 是否在参数更新时使用多精度。默认值为 False。 + - **always_adapt** (bool，可选) - 是否始终使用逐层学习率自适应。默认情况下，对被排除权重衰减的参数跳过自适应；若为 True，则始终启用学习率自适应。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 .. note:: @@ -49,17 +51,21 @@ COPY-FROM: paddle.optimizer.Lamb 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -85,8 +91,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Lamb.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -94,6 +100,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Lamb.clear_grad diff --git a/docs/api/paddle/optimizer/Momentum_cn.rst b/docs/api/paddle/optimizer/Momentum_cn.rst index 85dc9598a85..ebadbee7cce 100644 --- a/docs/api/paddle/optimizer/Momentum_cn.rst +++ b/docs/api/paddle/optimizer/Momentum_cn.rst @@ -3,7 +3,7 @@ Momentum ------------------------------- -.. py:class:: paddle.optimizer.Momentum(learning_rate=0.001, momentum=0.9, parameters=None, use_nesterov=False, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Momentum(learning_rate=0.001, momentum=0.9, parameters=None, use_nesterov=False, weight_decay=None, grad_clip=None, multi_precision=False, rescale_grad=1.0, use_multi_tensor=False, name=None) 含有速度状态的 Simple Momentum 优化器。 @@ -23,13 +23,16 @@ Momentum 参数 :::::::::::: - - **learning_rate** (float|_LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **momentum** (float，可选) - 动量因子。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值、浮点类型的 Tensor 或者一个 LRScheduler 类，默认值为 0.001。 + - **momentum** (float，可选) - 动量因子。默认值为 0.9. + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。可通过由 dict 构成的参数组列表为不同参数组指定学习率、权重衰减等选项。 - **use_nesterov** (bool，可选) - 赋能牛顿动量，默认值 False。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.01。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 权重衰减系数，可以是 L2 正则化系数的 int 或 float，也可以是 :ref:`cn_api_paddle_regularizer_L1Decay` 或 :ref:`cn_api_paddle_regularizer_L2Decay`。若参数已通过 :ref:`cn_api_paddle_ParamAttr` 设置正则化器，则忽略优化器中的设置；否则该设置生效。默认值为 None，即不进行正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 + - **multi_precision** (bool，可选) - 是否在参数更新时使用多精度。默认值为 False。 + - **rescale_grad** (float，可选) - 在更新前与梯度相乘的系数。通常可设为 ``1.0 / batch_size``。默认值为 1.0。 + - **use_multi_tensor** (bool，可选) - 是否使用多 Tensor 策略同时更新全部参数。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 @@ -42,17 +45,21 @@ COPY-FROM: paddle.optimizer.Momentum 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -80,8 +87,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Momentum.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -89,6 +96,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Momentum.clear_grad diff --git a/docs/api/paddle/optimizer/Optimizer_cn.rst b/docs/api/paddle/optimizer/Optimizer_cn.rst index 72923ce6957..becfb68497e 100755 --- a/docs/api/paddle/optimizer/Optimizer_cn.rst +++ b/docs/api/paddle/optimizer/Optimizer_cn.rst @@ -3,7 +3,7 @@ Optimizer ------------------------------- -.. py:class:: paddle.optimizer.Optimizer(learning_rate, parameters=None, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Optimizer(learning_rate, parameters=None, weight_decay=None, grad_clip=None, name=None, *, maximize=False) @@ -12,15 +12,20 @@ Optimizer 参数 :::::::::::: - - **learning_rate** (float|_LRSeduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **parameters** (list|tuple，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 + - **learning_rate** (float|LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个 LRScheduler 类。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。也可传入参数组字典列表，为不同参数组设置学习率、权重衰减等选项；参数组中的学习率表示基础学习率的缩放比例。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay`。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 - - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 + - **grad_clip** (GradientClipBase，可选) - 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 :::::::::::: @@ -36,7 +41,7 @@ step(closure=None) 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 - 执行一次优化器并进行参数更新。 +执行一次优化器并进行参数更新。 **参数** @@ -72,15 +77,19 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Optimizer.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 - 清除需要优化的参数的梯度。 +清除需要优化的参数的梯度。 + +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 **代码示例** diff --git a/docs/api/paddle/optimizer/Rprop_cn.rst b/docs/api/paddle/optimizer/Rprop_cn.rst index 75981acfbd4..49dc0d4dc2a 100644 --- a/docs/api/paddle/optimizer/Rprop_cn.rst +++ b/docs/api/paddle/optimizer/Rprop_cn.rst @@ -3,7 +3,7 @@ Rprop ------------------------------- -.. py:class:: paddle.optimizer.Rprop(learning_rate=0.001, learning_rate_range=(1e-5, 50), parameters=None, etas=(0.5, 1.2), grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Rprop(learning_rate=0.001, learning_rate_range=(1e-5, 50), parameters=None, etas=(0.5, 1.2), grad_clip=None, multi_precision=False, name=None) .. note:: @@ -39,12 +39,13 @@ Rprop 算法的优化器。有关详细信息，请参阅： 参数 :::::::::::: - - **learning_rate** (float|_LRScheduleri，可选) - 初始学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类。默认值为 0.001。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 初始学习率，用于参数更新的计算。可以是浮点值、浮点类型的 Tensor 或 LRScheduler。默认值为 0.001。 - **learning_rate_range** (tuple，可选) - 学习率的范围。学习率不能小于元组的第一个元素；学习率不能大于元组的第二个元素。默认值为 (1e-5, 50)。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 - **etas** (tuple，可选) - 用于更新学习率的元组。元组的第一个元素是乘法递减因子；元组的第二个元素是乘法增加因子。默认值为 (0.5, 1.2)。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 + - **multi_precision** (bool，可选) - 在基于 GPU 的混合精度训练中，是否保存与 float16 参数等值的 float32 参数副本以保证梯度更新的数值稳定性。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 @@ -56,8 +57,8 @@ COPY-FROM: paddle.optimizer.Rprop 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -65,9 +66,13 @@ step() 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -94,8 +99,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Rprop.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -104,6 +109,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Rprop.clear_grad @@ -115,7 +124,7 @@ get_lr() 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 -获取当前步骤的学习率。当不使用_LRScheduler 时，每次调用的返回值都相同，否则返回当前步骤的学习率。 +获取当前步骤的学习率。当不使用 LRScheduler 时，每次调用的返回值都相同，否则返回当前步骤的学习率。 **返回** diff --git a/docs/api/paddle/optimizer/SGD_cn.rst b/docs/api/paddle/optimizer/SGD_cn.rst index 5a9ffa6565c..4ef2be340c2 100644 --- a/docs/api/paddle/optimizer/SGD_cn.rst +++ b/docs/api/paddle/optimizer/SGD_cn.rst @@ -3,7 +3,7 @@ SGD ------------------------------- -.. py:class:: paddle.optimizer.SGD(learning_rate=0.001, parameters=None, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.SGD(learning_rate=0.001, parameters=None, weight_decay=None, grad_clip=None, multi_precision=False, name=None, *, maximize=False) 随机梯度下降算法的优化器。 @@ -16,13 +16,19 @@ SGD 参数 :::::::::::: - - **learning_rate** (float|_LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.01。 - - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 + - **learning_rate** (float|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个 LRScheduler 类，默认值为 0.001。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 权重衰减系数，可以是 L2 正则化系数的 int 或 float，也可以是 :ref:`cn_api_paddle_regularizer_L1Decay` 或 :ref:`cn_api_paddle_regularizer_L2Decay`。若参数已通过 :ref:`cn_api_paddle_ParamAttr` 设置正则化器，则忽略优化器中的设置；否则该设置生效。默认值为 None，即不进行正则化。 + - **grad_clip** (GradientClipBase，可选) - 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 + - **multi_precision** (bool，可选) - 是否在参数更新时使用多精度。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 @@ -32,8 +38,8 @@ COPY-FROM: paddle.optimizer.SGD 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -41,9 +47,13 @@ step() 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -70,8 +80,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.SGD.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -80,6 +90,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.SGD.clear_grad From 5484395807b9e8468b087b448d14c7f768c23967 Mon Sep 17 00:00:00 2001 From: manfredss Date: Thu, 13 Aug 2026 16:29:05 +0800 Subject: [PATCH 10/18] add 11 more apis --- docs/api/paddle/linalg/inv_cn.rst | 8 ++++++-- docs/api/paddle/linalg/ormqr_cn.rst | 15 ++++++++------- docs/api/paddle/linalg/pinv_cn.rst | 16 +++++++++++----- docs/api/paddle/linalg/qr_cn.rst | 2 +- docs/api/paddle/linalg/slogdet_cn.rst | 3 ++- docs/api/paddle/linalg/solve_cn.rst | 10 +++++++--- docs/api/paddle/linalg/svd_cn.rst | 10 +++++++--- docs/api/paddle/meshgrid_cn.rst | 7 ++++--- docs/api/paddle/nn/init/xavier_normal__cn.rst | 4 +++- docs/api/paddle/nn/init/xavier_uniform__cn.rst | 4 +++- docs/api/paddle/slice_scatter_cn.rst | 10 +++++----- 11 files changed, 57 insertions(+), 32 deletions(-) diff --git a/docs/api/paddle/linalg/inv_cn.rst b/docs/api/paddle/linalg/inv_cn.rst index 020db048ce6..e2d2c9b828f 100644 --- a/docs/api/paddle/linalg/inv_cn.rst +++ b/docs/api/paddle/linalg/inv_cn.rst @@ -3,16 +3,20 @@ inv ------------------------------- -.. py:function:: paddle.linalg.inv(x, name=None) +.. py:function:: paddle.linalg.inv(x, name=None, *, out=None) 计算方阵的逆。方阵是行数和列数相等的矩阵。输入可以是一个方阵（2-D Tensor），或者是批次方阵（维数大于 2 时）。 参数 ::::::::: - - **x** (Tensor) – 输入 Tensor，最后两维的大小必须相等。如果输入 Tensor 的维数大于 2，则被视为 2-D 矩阵的批次（batch）。支持的数据类型：float32，float64。别名 ``input``。 + - **x** (Tensor) – 输入 Tensor，最后两维的大小必须相等。如果输入 Tensor 的维数大于 2，则被视为 2-D 矩阵的批次（batch）。支持的数据类型：float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::: Tensor，输入方阵的逆。 diff --git a/docs/api/paddle/linalg/ormqr_cn.rst b/docs/api/paddle/linalg/ormqr_cn.rst index 81b2615b01d..bba7614f9a6 100644 --- a/docs/api/paddle/linalg/ormqr_cn.rst +++ b/docs/api/paddle/linalg/ormqr_cn.rst @@ -3,23 +3,24 @@ ormqr ------------------------------- -.. py:function:: paddle.linalg.ormqr(x, tau, other, left=True, transpose=False) +.. py:function:: paddle.linalg.ormqr(x, tau, y, left=True, transpose=False, name=None) -计算维度为(m, n)的矩阵 C（由 :attr:`other` 给出）和一个矩阵 Q 的乘积， +计算维度为(m, n)的矩阵 C（由 :attr:`y` 给出）和一个矩阵 Q 的乘积， 其中 Q 由 Householder 反射系数 (:attr:`x`, :attr:`tau`) 表示。 参数 :::::::::::: - - **x** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, MN, K]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **tau** (Tensor) - 输入一个或一批 Householder 反射系数，类型为 Tensor。 ``tau`` 的形状应为 ``[*, min(MN, K)]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **other** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``other`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **left** (bool， 可选) - 决定了矩阵乘积运算的顺序。如果 left 为 ``True`` ，计算顺序为 op(Q) * other ，否则，计算顺序为 other * op(Q)。默认值： ``True`` 。 + - **x** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, MN, K]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float16、float32、float64、complex64、complex128。 + - **tau** (Tensor) - 输入一个或一批 Householder 反射系数，类型为 Tensor。 ``tau`` 的形状应为 ``[*, min(MN, K)]``，其中 ``*`` 为零或更大的批次维度，数据类型与 ``x`` 相同，支持 float16、float32、float64、complex64、complex128。 + - **y** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``y`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型与 ``x`` 相同，支持 float16、float32、float64、complex64、complex128。 + - **left** (bool， 可选) - 决定了矩阵乘积运算的顺序。如果 left 为 ``True`` ，计算顺序为 op(Q) * y ，否则，计算顺序为 y * op(Q)。默认值： ``True`` 。 - **transpose** (bool， 可选) - 如果为 ``True`` ，对矩阵 Q 进行共轭转置变换，否则，不对矩阵 Q 进行共轭转置变换。默认值： ``False`` 。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: - ``Tensor``，维度和数据类型都与 :attr:`other` 一致。 + ``Tensor``，维度和数据类型都与 :attr:`y` 一致。 代码示例 :::::::::: diff --git a/docs/api/paddle/linalg/pinv_cn.rst b/docs/api/paddle/linalg/pinv_cn.rst index 03939d08c2b..d2805849033 100644 --- a/docs/api/paddle/linalg/pinv_cn.rst +++ b/docs/api/paddle/linalg/pinv_cn.rst @@ -3,7 +3,7 @@ pinv ------------------------------- -.. py:function:: paddle.linalg.pinv(x, rcond=1e-15, hermitian=False, name=None) +.. py:function:: paddle.linalg.pinv(x, rcond=1e-15, hermitian=False, name=None, *, atol=None, rtol=None, out=None) 该 API 通过奇异值分解(``svd``)来计算伪逆矩阵，支持单个矩阵或批量矩阵。 @@ -11,16 +11,22 @@ pinv - 如果 ``hermitian`` 为真，那么该 API 会利用特征值分解(``eigh``)进行伪逆矩阵的求解。同时输入需要满足以下条件：如果数据类型为实数，那么输入需要为对称矩阵；如果数据类型为复数，那么输入需要为 ``hermitian`` 矩阵。 参数 -::::::::: - - **x** (Tensor)：输入变量，类型为 Tensor，数据类型为 float32、float64、complex64、complex12，形状为（M, N）或（B, M, N）。别名 ``input``。 - - **rcond** (float64，可选)：奇异值（特征值）被截断的阈值，奇异值（特征值）小于 rcond * 最大奇异值时会被置为 0，默认值为 1e-15。 +:::::::::::: + - **x** (Tensor)：输入变量，类型为 Tensor，数据类型为 float32、float64、complex64、complex128，形状为 ``[..., M, N]``，其中 ``...`` 为零个或多个批次维度，``M`` 和 ``N`` 为任意正整数。当数据类型为 complex64 或 complex128 时，``hermitian`` 必须设为 True。别名 ``input``、``A``。 + - **rcond** (Tensor|float，可选)：用于确定奇异值是否为零的容差值，保留该参数以兼容 NumPy。推荐使用 ``rtol``；若指定 ``rtol``，则忽略 ``rcond``。默认值为 1e-15。 - **hermitian** (bool，可选)：是否为 ``hermitian`` 矩阵或者实对称矩阵，默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **atol** (float|Tensor|None，可选) - 绝对容差值。为 None 时视为 0。默认值为 None。 + - **rtol** (float|Tensor|None，可选) - 相对容差值。``atol`` 和 ``rtol`` 均为 None 时使用 ``rcond``；若指定 ``rtol``，则忽略 ``rcond``。默认值为 None。 + - **out** (Tensor|None，可选) - 输出 Tensor。若提供，计算结果将写入该 Tensor。默认值为 None。 + 返回 :::::::::::: -Tensor，输入矩阵的伪逆矩阵，数据类型和输入数据类型一致。形状为（N, M）或（B, N, M）。 +Tensor，输入矩阵的伪逆矩阵，数据类型和输入数据类型一致，形状为 ``[..., N, M]``。 代码示例 :::::::::: diff --git a/docs/api/paddle/linalg/qr_cn.rst b/docs/api/paddle/linalg/qr_cn.rst index 5a7cd3ed219..d5c98b161bf 100644 --- a/docs/api/paddle/linalg/qr_cn.rst +++ b/docs/api/paddle/linalg/qr_cn.rst @@ -24,7 +24,7 @@ qr 参数 :::::::::::: - - **x** (Tensor)：输入进行正交三角分解的一个或一批方阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。别名 ``input``, ``A``。 + - **x** (Tensor)：输入进行正交三角分解的一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，``M`` 和 ``N`` 为任意正整数，数据类型支持 float32、float64、complex64、complex128。别名 ``input``, ``A``。 - **mode** (str，可选)：控制正交三角分解的行为，默认是 ``reduced``，假设 ``x`` 形状应为 ``[*, M, N]`` 和 ``K = min(M, N)``： 如果 ``mode = "reduced"``，则 :math:`Q` 形状为 ``[*, M, K]`` 和 :math:`R` 形状为 ``[*, K, N]``； 如果 ``mode = "complete"``，则 :math:`Q` 形状为 ``[*, M, M]`` 和 :math:`R` 形状为 ``[*, M, N]``； diff --git a/docs/api/paddle/linalg/slogdet_cn.rst b/docs/api/paddle/linalg/slogdet_cn.rst index b6bb65344a2..7143fe14125 100644 --- a/docs/api/paddle/linalg/slogdet_cn.rst +++ b/docs/api/paddle/linalg/slogdet_cn.rst @@ -3,7 +3,7 @@ slogdet ------------------------------- -.. py:function:: paddle.linalg.slogdet(x) +.. py:function:: paddle.linalg.slogdet(x, name=None) 计算批量矩阵的行列式值的符号值和行列式值绝对值的自然对数值。 .. note:: @@ -14,6 +14,7 @@ slogdet :::::::::::: - **x** (Tensor)：输入一个或批量矩阵。``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。 + - **name** (str|None，可选) - 输出名称，用于打印开发调试信息。默认值为 None。具体用法请参见 :ref:`api_guide_Name`。 返回 :::::::::::: diff --git a/docs/api/paddle/linalg/solve_cn.rst b/docs/api/paddle/linalg/solve_cn.rst index 6e1a0b9ed49..34e9e1e5329 100644 --- a/docs/api/paddle/linalg/solve_cn.rst +++ b/docs/api/paddle/linalg/solve_cn.rst @@ -3,7 +3,7 @@ solve ------------------------------- -.. py:function:: paddle.linalg.solve(x, y, left=True, name=None) +.. py:function:: paddle.linalg.solve(x, y, left=True, name=None, *, out=None) 计算线性方程组的解。 @@ -25,11 +25,15 @@ solve 参数 ::::::::: - - **x** (Tensor) - 输入的欲进行线性方程组求解的一个或一批方阵（系数矩阵），类型为 Tensor。 ``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型为 float32， float64。 - - **y** (Tensor) - 输入的欲进行线性方程组求解的右值，类型为 Tensor。 ``y`` 的形状应为 ``[*, M, K]``，其中 ``*`` 为零或更大的批次维度，数据类型和 ``x`` 相同。 + - **x** (Tensor) - 输入的欲进行线性方程组求解的一个或一批方阵（系数矩阵），类型为 Tensor。 ``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型为 float32， float64。别名 ``A``。 + - **y** (Tensor) - 输入的欲进行线性方程组求解的右值，类型为 Tensor。 ``y`` 的形状应为 ``[*, M, K]``，其中 ``*`` 为零或更大的批次维度，数据类型和 ``x`` 相同。别名 ``B``。 - **left** (bool，可选) - 设置所求解的线性方程组是 :math:`X * Out = Y` 或 :math:`Out * X = Y`。默认值为 True，表示所求解的线性方程组是 :math:`X * Out = Y`。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/linalg/svd_cn.rst b/docs/api/paddle/linalg/svd_cn.rst index a157b85d9a5..ebabc78734e 100644 --- a/docs/api/paddle/linalg/svd_cn.rst +++ b/docs/api/paddle/linalg/svd_cn.rst @@ -3,7 +3,7 @@ svd ------------------------------- -.. py:function:: paddle.linalg.svd(x, full_matrices=False, name=None) +.. py:function:: paddle.linalg.svd(x, full_matrices=False, name=None, *, out=None) 计算一个或一批矩阵的奇异值分解。 @@ -19,10 +19,14 @@ svd 参数 :::::::::::: - - **x** (Tensor) - 输入的欲进行奇异值分解的一个或一批方阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64， complex64， complex128。 - - **full_matrices** (bool) - 是否计算完整的 U 和 V 矩阵，类型为 bool 默认为 False。这个参数会影响 U 和 V 生成的 Shape。 + - **x** (Tensor) - 输入的欲进行奇异值分解的一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，``M`` 和 ``N`` 为任意正整数，数据类型支持 float32、float64、complex64、complex128。 + - **full_matrices** (bool，可选) - 是否计算完整的 U 和 V 矩阵，类型为 bool 默认为 False。这个参数会影响 U 和 V 生成的 Shape。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (tuple[Tensor, Tensor, Tensor]，可选) - 输出 Tensor 元组，若不为 ``None``，计算结果将保存在该 Tensor 元组中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/meshgrid_cn.rst b/docs/api/paddle/meshgrid_cn.rst index e57f4976ef7..c4d898b0709 100644 --- a/docs/api/paddle/meshgrid_cn.rst +++ b/docs/api/paddle/meshgrid_cn.rst @@ -3,7 +3,7 @@ meshgrid ------------------------------- -.. py:function:: paddle.meshgrid(*args, **kargs) +.. py:function:: paddle.meshgrid(*args, name=None, indexing=None) @@ -13,8 +13,9 @@ meshgrid 参数 :::::::::::: - - **args** (Tensor|Tensor 数组) - 输入变量为 k 个一维 Tensor，形状分别为(N1,), (N2,), ..., (Nk, )。支持数据类型为 bfloat16、float16、float32、float64、int32、int64、complex64 和 complex128。 - - **kargs** (可选) - 目前只接受 name 参数（str），具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **args** (Tensor|Tensor 数组) - 输入变量为 k 个一维 Tensor，形状分别为(N1,), (N2,), ..., (Nk, )。支持数据类型为 bfloat16、float16、float32、float64、uint16、int32、int64、complex64 和 complex128。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **indexing** (str，可选) - 索引模式，可选 ``"xy"`` 或 ``"ij"``。默认值为 ``"ij"``。当选择 ``"xy"`` 时，前两个维度的顺序与前两个输入的基数相反；当选择 ``"ij"`` 时，各维度顺序与输入顺序一致。 diff --git a/docs/api/paddle/nn/init/xavier_normal__cn.rst b/docs/api/paddle/nn/init/xavier_normal__cn.rst index 7af2f55ddc7..138b0dbc5ef 100644 --- a/docs/api/paddle/nn/init/xavier_normal__cn.rst +++ b/docs/api/paddle/nn/init/xavier_normal__cn.rst @@ -3,7 +3,7 @@ xavier_normal\_ ------------------------------- -.. py:class:: paddle.nn.init.xavier_normal_(tensor, gain=1.0) +.. py:function:: paddle.nn.init.xavier_normal_(tensor, gain=1.0, fan_in=None, fan_out=None) 将输入张量的值设置为 Xavier 正常分布的随机数，该操作会直接修改输入张量。 @@ -12,3 +12,5 @@ xavier_normal\_ - **tensor** (Tensor) - 输入张量。 - **gain** (float，可选) - 比例因子，默认值为 1.0。 + - **fan_in** (float|None，可选) - Xavier 初始化的 ``fan_in``。默认从 Tensor 推断。默认值为 None。 + - **fan_out** (float|None，可选) - Xavier 初始化的 ``fan_out``。默认从 Tensor 推断。默认值为 None。 diff --git a/docs/api/paddle/nn/init/xavier_uniform__cn.rst b/docs/api/paddle/nn/init/xavier_uniform__cn.rst index ac8561f3e24..b937d2609b3 100644 --- a/docs/api/paddle/nn/init/xavier_uniform__cn.rst +++ b/docs/api/paddle/nn/init/xavier_uniform__cn.rst @@ -3,7 +3,7 @@ xavier_uniform\_ ------------------------------- -.. py:class:: paddle.nn.init.xavier_uniform_(tensor, gain=1.0) +.. py:function:: paddle.nn.init.xavier_uniform_(tensor, gain=1.0, fan_in=None, fan_out=None) 将输入张量的值设置为 Xavier 均匀分布的随机数，该操作会直接修改输入张量。 @@ -12,3 +12,5 @@ xavier_uniform\_ - **tensor** (Tensor) - 输入张量。 - **gain** (float，可选) - 比例因子，默认值为 1.0。 + - **fan_in** (float|None，可选) - Xavier 初始化的 ``fan_in``。默认从 Tensor 推断。默认值为 None。 + - **fan_out** (float|None，可选) - Xavier 初始化的 ``fan_out``。默认从 Tensor 推断。默认值为 None。 diff --git a/docs/api/paddle/slice_scatter_cn.rst b/docs/api/paddle/slice_scatter_cn.rst index 6a67b0198a0..12cd5af4790 100644 --- a/docs/api/paddle/slice_scatter_cn.rst +++ b/docs/api/paddle/slice_scatter_cn.rst @@ -3,13 +3,13 @@ slice_scatter ------------------------------- -.. py:function:: paddle.slice_scatter(x, value, axes=None, starts=None, ends=None, strides=None) +.. py:function:: paddle.slice_scatter(x, value, axes=[0], starts=[0], ends=None, strides=[1]) 沿着 ``axes`` 将 ``value`` 矩阵的值嵌入到 ``x`` 矩阵。返回一个新的 Tensor 而不是视图。 ``axes`` 需要与 ``starts``, ``ends`` 和 ``strides`` 尺寸一致。 .. note:: 此 API 有两种调用方式： - 1. ``paddle.slice_scatter(x, value, axes=None, starts=None, ends=None, strides=None)`` (Paddle 风格)：沿多个维度嵌入 value 张量 + 1. ``paddle.slice_scatter(x, value, axes=[0], starts=[0], ends=None, strides=[1])`` (Paddle 风格)：沿多个维度嵌入 value 张量 2. ``paddle.slice_scatter(input, src, dim=0, start=None, end=None, step=1)`` (PyTorch 风格)：沿单个维度嵌入 src 张量 图示展示了示例二 ——一个形状为 [3, 9] 的张量 x，在 axis 1 上使用 slice scatter 操作，将 [3, 1] 的 value 张量嵌入到指定的范围内。图中显示了原始张量、value 张量以及操作后的结果。 @@ -23,10 +23,10 @@ slice_scatter ::::::::: - **x** (Tensor) - 输入的 Tensor 作为目标矩阵，数据类型为： ``bool``、 ``float16``、 ``float32``、 ``float64``、 ``uint8``、 ``int8``、 ``int16``、 ``int32``、 ``int64``、 ``bfloat16``、 ``complex64``、 ``complex128``。别名 ``input``。 - **value** (Tensor) - 需要插入的值，数据类型为： ``bool``、 ``float16``、 ``float32``、 ``float64``、 ``uint8``、 ``int8``、 ``int16``、 ``int32``、 ``int64``、 ``bfloat16``、 ``complex64``、 ``complex128``。别名 ``src``。 - - **axes** (list|tuple，可选) - 指定沿着哪几个维度嵌入对应的值。别名 ``dim``。 - - **starts** (list|tuple，可选) - 嵌入的起始索引。别名 ``start``。 + - **axes** (list|tuple，可选) - 指定沿着哪几个维度嵌入对应的值。默认值为 ``[0]``。别名 ``dim``。 + - **starts** (list|tuple，可选) - 嵌入的起始索引。默认值为 ``[0]``。别名 ``start``。 - **ends** (list|tuple，可选) - 嵌入的截止索引。别名 ``end``。 - - **strides** (list|tuple，可选) - 嵌入的步长。别名 ``step``。 + - **strides** (list|tuple，可选) - 嵌入的步长。默认值为 ``[1]``。别名 ``step``。 返回 ::::::::: From 16dab7b9987b7ef7e82c82d783a742226e22b5d1 Mon Sep 17 00:00:00 2001 From: manfredss Date: Thu, 13 Aug 2026 17:45:06 +0800 Subject: [PATCH 11/18] add 23 more apis --- docs/api/paddle/div__cn.rst | 2 +- docs/api/paddle/divide__cn.rst | 4 ++-- docs/api/paddle/erfinv__cn.rst | 2 +- docs/api/paddle/fft/fft2_cn.rst | 11 ++++++++--- docs/api/paddle/fft/fft_cn.rst | 10 +++++++--- docs/api/paddle/fft/fftfreq_cn.rst | 8 +++++++- docs/api/paddle/fft/fftn_cn.rst | 9 +++++++-- docs/api/paddle/fft/hfft2_cn.rst | 9 +++++++-- docs/api/paddle/fft/hfft_cn.rst | 10 +++++++--- docs/api/paddle/fft/hfftn_cn.rst | 9 +++++++-- docs/api/paddle/fft/ifft2_cn.rst | 9 +++++++-- docs/api/paddle/fft/ifft_cn.rst | 10 +++++++--- docs/api/paddle/fft/ifftn_cn.rst | 9 +++++++-- docs/api/paddle/fft/ihfft2_cn.rst | 9 +++++++-- docs/api/paddle/fft/ihfft_cn.rst | 12 ++++++++---- docs/api/paddle/fft/ihfftn_cn.rst | 9 +++++++-- docs/api/paddle/fft/irfft2_cn.rst | 11 ++++++++--- docs/api/paddle/fft/irfft_cn.rst | 10 +++++++--- docs/api/paddle/fft/irfftn_cn.rst | 9 +++++++-- docs/api/paddle/fft/rfft2_cn.rst | 9 +++++++-- docs/api/paddle/fft/rfft_cn.rst | 10 +++++++--- docs/api/paddle/fft/rfftfreq_cn.rst | 8 +++++++- docs/api/paddle/fft/rfftn_cn.rst | 9 +++++++-- 23 files changed, 147 insertions(+), 51 deletions(-) diff --git a/docs/api/paddle/div__cn.rst b/docs/api/paddle/div__cn.rst index 43d49fd89df..f519042f2db 100644 --- a/docs/api/paddle/div__cn.rst +++ b/docs/api/paddle/div__cn.rst @@ -3,6 +3,6 @@ div\_ ------------------------------- -.. py:function:: paddle.div_(x, y, name=None, *, rounding_mode=None, out=None) +.. py:function:: paddle.div_(x, y, name=None, *, rounding_mode=None) 别名函数，功能与 :ref:`cn_api_paddle_divide_` 完全相同，详情请参考 :ref:`cn_api_paddle_divide_` 。 diff --git a/docs/api/paddle/divide__cn.rst b/docs/api/paddle/divide__cn.rst index a2592c07ed6..f1600c3ad89 100644 --- a/docs/api/paddle/divide__cn.rst +++ b/docs/api/paddle/divide__cn.rst @@ -3,8 +3,8 @@ divide\_ ------------------------------- -.. py:function:: paddle.divide_(x, y, name=None, *, rounding_mode=None, out=None) -Inplace 版本的 :ref:`cn_api_paddle_divide` API，对输入 x 采用 Inplace 策略。 +.. py:function:: paddle.divide_(x, y, name=None, *, rounding_mode=None) +Inplace 版本的 :ref:`cn_api_paddle_divide` API，对输入 x 采用 Inplace 策略。参数 ``x`` 和 ``y`` 分别支持别名 ``input`` 和 ``other``。 更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。 diff --git a/docs/api/paddle/erfinv__cn.rst b/docs/api/paddle/erfinv__cn.rst index 72295fa4198..31d30f29cea 100644 --- a/docs/api/paddle/erfinv__cn.rst +++ b/docs/api/paddle/erfinv__cn.rst @@ -3,7 +3,7 @@ erfinv\_ ------------------------------- -.. py:function:: paddle.erfinv_(x) +.. py:function:: paddle.erfinv_(x, name=None) Inplace 版本的 :ref:`cn_api_paddle_erfinv` API，对输入 ``x`` 采用 Inplace 策略。 diff --git a/docs/api/paddle/fft/fft2_cn.rst b/docs/api/paddle/fft/fft2_cn.rst index d297cad6cc3..fa36dcae1f9 100644 --- a/docs/api/paddle/fft/fft2_cn.rst +++ b/docs/api/paddle/fft/fft2_cn.rst @@ -3,7 +3,7 @@ fft2 ------------------------------- -.. py:function:: paddle.fft.fft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.fft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维离散傅里叶变换。 @@ -13,13 +13,14 @@ fft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里 叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度大，则输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各 - 个轴的长度。 + 个轴的长度。默认为 None。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -32,6 +33,10 @@ fft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/fft_cn.rst b/docs/api/paddle/fft/fft_cn.rst index f60692b5d05..7bf8e3f354f 100644 --- a/docs/api/paddle/fft/fft_cn.rst +++ b/docs/api/paddle/fft/fft_cn.rst @@ -3,7 +3,7 @@ fft ------------------------------- -.. py:function:: paddle.fft.fft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.fft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 一维离散傅里叶变换。 @@ -12,9 +12,9 @@ fft 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 中傅里叶变换轴的长度。如果 ``n`` 比输入 Tensor 中对应轴的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -26,6 +26,10 @@ fft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/fftfreq_cn.rst b/docs/api/paddle/fft/fftfreq_cn.rst index 6e0e914b6ce..b79cc5b937d 100644 --- a/docs/api/paddle/fft/fftfreq_cn.rst +++ b/docs/api/paddle/fft/fftfreq_cn.rst @@ -3,7 +3,7 @@ fftfreq ------------------------------- -.. py:function:: paddle.fft.fftfreq(n, d=1.0, dtype=None, name=None) +.. py:function:: paddle.fft.fftfreq(n, d=1.0, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回离散傅里叶变换的频率窗口（frequency bins）中心序列，以 "循环/采样间隔" 为单位。例如，采 样间隔以秒为单位，则频率的单位是 "循环/秒"。 @@ -23,6 +23,12 @@ fftfreq - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，使用当前默认 Tensor 类型的当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/fftn_cn.rst b/docs/api/paddle/fft/fftn_cn.rst index a06cd9eead1..9b6ca1fbcc1 100644 --- a/docs/api/paddle/fft/fftn_cn.rst +++ b/docs/api/paddle/fft/fftn_cn.rst @@ -3,7 +3,7 @@ fftn ------------------------------- -.. py:function:: paddle.fft.fftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.fftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) 计算 N 维离散傅里叶变换。 @@ -12,7 +12,7 @@ fftn 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型可以为实数或复数。 + - **x** (Tensor) - 输入数据，其数据类型可以为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里 叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 @@ -20,6 +20,7 @@ fftn 个轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入 Tensor 的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取 值必须是 "forward", "backward", "ortho"之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -32,6 +33,10 @@ fftn - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: 输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出，数据类型为复数类型。 diff --git a/docs/api/paddle/fft/hfft2_cn.rst b/docs/api/paddle/fft/hfft2_cn.rst index 8f2190f8699..437fa64c7f9 100644 --- a/docs/api/paddle/fft/hfft2_cn.rst +++ b/docs/api/paddle/fft/hfft2_cn.rst @@ -3,7 +3,7 @@ hfft2 ------------------------------- -.. py:function:: paddle.fft.hfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.hfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算二维厄米特(Hermitian)傅里叶变换。 @@ -11,10 +11,11 @@ hfft2 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数类型。 + - **x** (Tensor) - 输入数据，其数据类型为复数类型。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在傅里叶变换轴的长度（类似一维傅里叶变换中 的参数 ``n``）。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -27,6 +28,10 @@ hfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输 diff --git a/docs/api/paddle/fft/hfft_cn.rst b/docs/api/paddle/fft/hfft_cn.rst index 57c949cb20f..2eee2abbb7a 100644 --- a/docs/api/paddle/fft/hfft_cn.rst +++ b/docs/api/paddle/fft/hfft_cn.rst @@ -4,7 +4,7 @@ hfft ------------------------------- -.. py:function:: paddle.fft.hfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.hfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算一维厄米特（Hermitian）傅里叶变换。 @@ -12,9 +12,9 @@ hfft 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 在傅里叶变换轴的长度。输入 Tensor 在该轴的长度必须为 ``n//2+1``，如果输入 Tensor 的长度大于 ``n//2+1``，输入 Tensor 会被截断。如果输入 Tensor 的长度小于 ``n//2+1``，则输入 Tensor 会被补零。如果 ``n`` 没有被指定，则取 ``2*(m-1)``，其中, ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必须是 "forward", "backward", "ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n``； @@ -24,6 +24,10 @@ hfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。如果指定 ``n`` ，则输出 Tensor 在傅立叶变换轴的长度为 ``n`` ，否则为 ``2*(m-1)``，其中 ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 diff --git a/docs/api/paddle/fft/hfftn_cn.rst b/docs/api/paddle/fft/hfftn_cn.rst index 2b1d1375713..63899d5bb78 100644 --- a/docs/api/paddle/fft/hfftn_cn.rst +++ b/docs/api/paddle/fft/hfftn_cn.rst @@ -3,7 +3,7 @@ hfftn ------------------------------- -.. py:function:: paddle.fft.hfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.hfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算 N 维厄米特（Hermitian）傅里叶变换。 @@ -11,7 +11,7 @@ hfftn 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数类型。 + - **x** (Tensor) - 输入数据，其数据类型为复数类型。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里 叶变换中的参数 ``n``）。对于傅里叶变换的最后一个轴，输入长度要求是 ``s[-1]//2+1``，如果 输入 Tensor 的长度大于 ``s[-1]//2+1``，输入 Tensor 会被截断。如果输入 Tensor 的长度 @@ -22,6 +22,7 @@ hfftn - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最 后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取 值必须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的 行为如下： @@ -34,6 +35,10 @@ hfftn - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/ifft2_cn.rst b/docs/api/paddle/fft/ifft2_cn.rst index d51847292c7..4e0f47164ff 100644 --- a/docs/api/paddle/fft/ifft2_cn.rst +++ b/docs/api/paddle/fft/ifft2_cn.rst @@ -3,7 +3,7 @@ ifft2 ------------------------------- -.. py:function:: paddle.fft.ifft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.ifft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维傅里叶变换(``fft2``)的逆变换。在一定的误差范围内，``ifft2(fft2(x)) == x``。 @@ -11,13 +11,14 @@ ifft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维逆向傅 里叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度大，则输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各 个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两维。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值 必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对 应的行为如下： @@ -30,6 +31,10 @@ ifft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/ifft_cn.rst b/docs/api/paddle/fft/ifft_cn.rst index a1c11a45502..1121b1a677a 100644 --- a/docs/api/paddle/fft/ifft_cn.rst +++ b/docs/api/paddle/fft/ifft_cn.rst @@ -3,18 +3,18 @@ ifft ------------------------------- -.. py:function:: paddle.fft.ifft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.ifft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 一维傅里叶变换（``fft``）的逆变换。在一定的误差范围内，``ifft(fft(x)) == x``。 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 中在傅里叶变换轴的长度。如果 ``n`` 比输入 Tensor 中 对应轴的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被 补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int, 可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值 必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对 应的行为如下： @@ -25,6 +25,10 @@ ifft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/ifftn_cn.rst b/docs/api/paddle/fft/ifftn_cn.rst index 5cca64b64b3..28da62fdf30 100644 --- a/docs/api/paddle/fft/ifftn_cn.rst +++ b/docs/api/paddle/fft/ifftn_cn.rst @@ -3,7 +3,7 @@ ifftn ------------------------------- -.. py:function:: paddle.fft.ifftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.ifftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(fftn(x)) == x``。 @@ -11,7 +11,7 @@ N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(f 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维逆向傅 里叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 @@ -19,6 +19,7 @@ N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(f 个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入 Tensor 的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值 必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对 应的行为如下： @@ -31,6 +32,10 @@ N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(f - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/ihfft2_cn.rst b/docs/api/paddle/fft/ihfft2_cn.rst index e9843fd9238..4613bf91ae5 100644 --- a/docs/api/paddle/fft/ihfft2_cn.rst +++ b/docs/api/paddle/fft/ihfft2_cn.rst @@ -3,7 +3,7 @@ ihfft2 ------------------------------- -.. py:function:: paddle.fft.ihfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.ihfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维厄米特（Hermitian）傅里叶变换的逆变换。 @@ -14,12 +14,13 @@ ihfft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必 须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为 如下： @@ -32,6 +33,10 @@ ihfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/ihfft_cn.rst b/docs/api/paddle/fft/ihfft_cn.rst index 15ecbbda982..e617a0ef3a5 100644 --- a/docs/api/paddle/fft/ihfft_cn.rst +++ b/docs/api/paddle/fft/ihfft_cn.rst @@ -3,19 +3,19 @@ ihfft ------------------------------- -.. py:function:: paddle.fft.ihfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.ihfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) -使用快速傅里叶变（FFT）算法计算一维厄米特（Hermitian）傅里叶变换的逆变换。 +使用快速傅里叶变换（FFT）算法计算一维厄米特（Hermitian）傅里叶变换的逆变换。 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **n** (int，可选) - 傅里叶变换点数。如果 ``n`` 比输入 Tensor 中对应轴 的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必 须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为 如下： @@ -27,6 +27,10 @@ ihfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在指定 diff --git a/docs/api/paddle/fft/ihfftn_cn.rst b/docs/api/paddle/fft/ihfftn_cn.rst index 24077788865..c21ef94c1ea 100644 --- a/docs/api/paddle/fft/ihfftn_cn.rst +++ b/docs/api/paddle/fft/ihfftn_cn.rst @@ -3,7 +3,7 @@ ihfftn ------------------------------- -.. py:function:: paddle.fft.ihfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.ihfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) N 维厄米特（Hermitian）傅里叶变换的逆变换。 @@ -14,13 +14,14 @@ N 维厄米特（Hermitian）傅里叶变换的逆变换。 参数 ::::::::: - - **x** (Tensor) - 输入数据，数据类型为实数。 + - **x** (Tensor) - 输入数据，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取值必 须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的行为如下： @@ -32,6 +33,10 @@ N 维厄米特（Hermitian）傅里叶变换的逆变换。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，复数类型，输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。最后一个傅立 diff --git a/docs/api/paddle/fft/irfft2_cn.rst b/docs/api/paddle/fft/irfft2_cn.rst index 1ed7c3b8e41..bfeb60a717a 100644 --- a/docs/api/paddle/fft/irfft2_cn.rst +++ b/docs/api/paddle/fft/irfft2_cn.rst @@ -3,7 +3,7 @@ irfft2 ------------------------------- -.. py:function:: paddle.fft.irfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.irfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算二维实数傅里叶变换 （rfft2）的逆变换。 @@ -11,10 +11,11 @@ irfft2 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在傅里叶变换轴的长度（类似一维傅里叶变换中 的参数 ``n``）。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -27,10 +28,14 @@ irfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 -二维厄米特傅里叶变换为 N 维厄米特傅里（``irfftn``）变换的特例。 +二维厄米特傅里叶变换为 N 维厄米特傅里叶变换（``irfftn``）变换的特例。 代码示例 ::::::::: diff --git a/docs/api/paddle/fft/irfft_cn.rst b/docs/api/paddle/fft/irfft_cn.rst index 3dab940e940..af4cd915c2c 100644 --- a/docs/api/paddle/fft/irfft_cn.rst +++ b/docs/api/paddle/fft/irfft_cn.rst @@ -4,7 +4,7 @@ irfft ------------------------------- -.. py:function:: paddle.fft.irfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.irfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算一维实数傅里叶变换 （rfft）的逆变换。 @@ -12,9 +12,9 @@ irfft 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 在傅里叶变换轴的长度。输入 Tensor 在该轴的长度必须为 ``n//2+1`` ，如果输入 Tensor 的长度大于 ``n//2+1`` ，输入 Tensor 会被截断。如果输入 Tensor 的长度小于 ``n//2+1`` ，则输入 Tensor 会被补零。如果 ``n`` 没有被指定，则取 ``2*(m-1)`` ，其中， ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必须是 "forward"、"backward"、"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n`` ； @@ -24,6 +24,10 @@ irfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。如果指定 ``n`` ，则输出 Tensor 在傅立叶变换轴的长度为 ``n`` ，否则为 ``2*(m-1)`` ，其中 ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 diff --git a/docs/api/paddle/fft/irfftn_cn.rst b/docs/api/paddle/fft/irfftn_cn.rst index dc9bdfea57b..81c9ab72ec9 100644 --- a/docs/api/paddle/fft/irfftn_cn.rst +++ b/docs/api/paddle/fft/irfftn_cn.rst @@ -3,7 +3,7 @@ irfftn ------------------------------- -.. py:function:: paddle.fft.irfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.irfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) 通过快速傅里叶变换(FFT)算法计算 N 维实数傅里叶变换 （rfftn）的逆变换。 @@ -13,7 +13,7 @@ irfftn 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里叶变换中的参数 ``n``）。 - 对于傅里叶变换的最后一个轴，输入长度要求是 ``s[-1]//2+1``，如果输入 Tensor 的长度大于 ``s[-1]//2+1``，输入 Tensor 会被截断。如果输入 Tensor 的长度小于 ``s[-1]//2+1``，则输入 Tensor 会被补零； @@ -21,6 +21,7 @@ irfftn - 如果未指定 ``s``，则 ``s`` 在最后一个傅里叶变换轴取值为 ``2*(m-1)``，其中 ``m`` 是输入 Tensor 在最后一个傅里叶变换轴的长度，其余轴为输入 Tensor 在该轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取值必须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n``； @@ -31,6 +32,10 @@ irfftn - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/rfft2_cn.rst b/docs/api/paddle/fft/rfft2_cn.rst index e08a1e5806b..b793af57acf 100644 --- a/docs/api/paddle/fft/rfft2_cn.rst +++ b/docs/api/paddle/fft/rfft2_cn.rst @@ -3,7 +3,7 @@ rfft2 ------------------------------- -.. py:function:: paddle.fft.rfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.rfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维实数傅里叶变换。 @@ -14,12 +14,13 @@ rfft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必 须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为 如下，其中 ``n`` 为 ``s`` 中每个元素连乘： @@ -31,6 +32,10 @@ rfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/rfft_cn.rst b/docs/api/paddle/fft/rfft_cn.rst index 244fa7faacd..fb447efde55 100644 --- a/docs/api/paddle/fft/rfft_cn.rst +++ b/docs/api/paddle/fft/rfft_cn.rst @@ -3,7 +3,7 @@ rfft ------------------------------- -.. py:function:: paddle.fft.rfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.rfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 通过快速傅里叶变换(FFT)算法计算一维实数傅里叶变换。 @@ -13,11 +13,11 @@ rfft 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **n** (int，可选) - 傅里叶变换点数。如果 ``n`` 比输入 Tensor 中对应轴 的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n``； @@ -27,6 +27,10 @@ rfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。 diff --git a/docs/api/paddle/fft/rfftfreq_cn.rst b/docs/api/paddle/fft/rfftfreq_cn.rst index ad4eee3581b..1bcee46e745 100644 --- a/docs/api/paddle/fft/rfftfreq_cn.rst +++ b/docs/api/paddle/fft/rfftfreq_cn.rst @@ -3,7 +3,7 @@ rfftfreq ------------------------------- -.. py:function:: paddle.fft.rfftfreq(n, d=1.0, dtype=None, name=None) +.. py:function:: paddle.fft.rfftfreq(n, d=1.0, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回离散傅里叶变换的频率窗口(frequency bins)中心，以 "循环/采样间隔" 为单位。例如，采样间 隔以秒为单位，则频谱的单位是 "循环/秒"。用于 ``rfft`` 和 ``irfft``。 @@ -25,6 +25,12 @@ rfftfreq - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，使用当前默认 Tensor 类型的当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/rfftn_cn.rst b/docs/api/paddle/fft/rfftn_cn.rst index 0d648634cfc..63633800e07 100644 --- a/docs/api/paddle/fft/rfftn_cn.rst +++ b/docs/api/paddle/fft/rfftn_cn.rst @@ -3,7 +3,7 @@ rfftn ------------------------------- -.. py:function:: paddle.fft.rfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.rfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) N 维实数傅里叶变换。 @@ -14,13 +14,14 @@ N 维实数傅里叶变换。 参数 ::::::::: - - **x** (Tensor) - 输入数据，数据类型为实数。 + - **x** (Tensor) - 输入数据，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取值必 须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的行为如下： @@ -32,6 +33,10 @@ N 维实数傅里叶变换。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，复数类型，输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。最后一个傅立 From 52ab3f5d9cbf48cb3525c9ec47553f276ac02c29 Mon Sep 17 00:00:00 2001 From: manfredss Date: Fri, 14 Aug 2026 15:35:54 +0800 Subject: [PATCH 12/18] add 18 more apis --- docs/api/paddle/distributed/DistModel_cn.rst | 10 ++++++--- docs/api/paddle/distributed/LocalLayer_cn.rst | 20 ++++++++++------- .../distributed/all_gather_object_cn.rst | 4 ++-- .../distributed/destroy_process_group_cn.rst | 2 +- .../distributed/init_parallel_env_cn.rst | 9 ++++++-- .../paddle/distributed/load_state_dict_cn.rst | 8 +++++-- docs/api/paddle/distributed/new_group_cn.rst | 9 +++++--- .../paddle/distributed/save_state_dict_cn.rst | 10 +++++---- .../distributed/scatter_object_list_cn.rst | 4 ++-- .../distributed/shard_dataloader_cn.rst | 5 +++-- .../paddle/distributed/shard_optimizer_cn.rst | 3 ++- .../paddle/distributed/shard_tensor_cn.rst | 6 ++--- docs/api/paddle/distributed/spawn_cn.rst | 6 ++--- .../paddle/distributed/to_distributed_cn.rst | 6 +++-- docs/api/paddle/distributed/to_static_cn.rst | 19 ++++++++-------- .../distribution/ExponentialFamily_cn.rst | 10 +++++++-- .../paddle/distribution/LKJCholesky_cn.rst | 22 ++++++++++--------- docs/api/paddle/distribution/LogNormal_cn.rst | 13 +++++------ 18 files changed, 99 insertions(+), 67 deletions(-) diff --git a/docs/api/paddle/distributed/DistModel_cn.rst b/docs/api/paddle/distributed/DistModel_cn.rst index 05975372d46..3e9b58650b7 100644 --- a/docs/api/paddle/distributed/DistModel_cn.rst +++ b/docs/api/paddle/distributed/DistModel_cn.rst @@ -3,7 +3,7 @@ DistModel ------------------------------- -.. py:class:: paddle.distributed.DistModel() +.. py:class:: paddle.distributed.DistModel(layer, loader, loss=None, optimizer=None, strategy=None, metrics=None, input_spec=None) .. note:: 不推荐直接使用这个 API 生成实例，建议使用 ``paddle.distributed.to_static``。 @@ -19,7 +19,7 @@ DistModel 通过自身的 ``__call__`` 方法来执行模型训练、评估和 - **layer** (paddle.nn.Layer) - 动态图中所使用的 ``paddle.nn.Layer`` 实例，其参数包含由 ``paddle.distributed.shard_tensor`` 生成的分布式张量。 - - **loader** (paddle.io.DataLoader) - 动态图模式下所使用的 ``paddle.io.DataLoader`` 实例，用于生成静态图训练所需要的 ``DistributedDataloader``。 + - **loader** (ShardDataloader|paddle.io.DataLoader) - 动态图模式下所使用的数据加载器，用于推断输入和标签的规格。 - **loss** (Loss|Callable|None，可选) - 损失函数。可以是 ``paddle.nn.Layer`` 实例或任何可调用函数。如果 loss 不为 None，则 DistModel 会默认设置为 "train"（当 optimizer 不为 None 时）或 "eval" 模式（当 optimizer 为 None 时）。如果 loss 为 None，则 DistModel 会默认设置为 "predict" 模式。默认值：None。 @@ -27,6 +27,10 @@ DistModel 通过自身的 ``__call__`` 方法来执行模型训练、评估和 - **strategy** (paddle.distributed.Strategy|None，可选) - 并行策略和优化策略的配置（例如优化器分片、流水线并行等）。默认值：None。 + - **metrics** (list[Metric]|None，可选) - 评估指标列表。默认值为 None。 + + - **input_spec** (list[list[paddle.distributed.DistributedInputSpec]]|None，可选) - 自定义输入规格，指定模型输入和标签的形状、数据类型及名称信息。非 None 时，由该参数推断输入和标签规格；其应包含两个子列表，第一个表示输入规格，第二个表示标签规格。默认值为 None。 + **代码示例** @@ -104,7 +108,7 @@ serial_startup_program(mode=None) **参数** - - **mode** (str|None，可选) - 指定需要返回的 ``startup_program`` 的模式，可以是 "train "、"eval" 或 "predict"，如果未设置，则使用 DistModel 的当前模式。默认值：None。 + - **mode** (str|None，可选) - 指定需要返回的 ``startup_program`` 的模式，可以是 "train"、"eval" 或 "predict"，如果未设置，则使用 DistModel 的当前模式。默认值：None。 **返回** diff --git a/docs/api/paddle/distributed/LocalLayer_cn.rst b/docs/api/paddle/distributed/LocalLayer_cn.rst index 05bb0963e49..079576fc11e 100644 --- a/docs/api/paddle/distributed/LocalLayer_cn.rst +++ b/docs/api/paddle/distributed/LocalLayer_cn.rst @@ -3,7 +3,7 @@ LocalLayer ------------------------------- -.. py:class:: paddle.distributed.LocalLayer(out_dist_attrs) +.. py:class:: paddle.distributed.LocalLayer(out_dist_attrs, grad_dist_attrs) LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行训练中，某些操作（如带 mask 的 loss 计算、MoE 相关计算等）需要在每张卡上独立进行局部计算，而不是直接在全局分布式张量上计算。LocalLayer 通过自动处理张量转换，使得用户可以像编写单卡代码一样实现这些局部操作。 @@ -15,6 +15,8 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 - ProcessMesh: 计算设备网格,定义计算资源的拓扑结构 - list[Placement]: 张量分布方式的列表,描述如何将局部计算结果转换回分布式张量 + - **grad_dist_attrs** (list[tuple[ProcessMesh, list[Placement]]]) - 指定梯度 Tensor 的分布策略。列表中的元组可为 None，此时对应梯度 Tensor 的分布属性与对应输入 Tensor 相同。 + **代码示例** .. code-block:: python @@ -24,8 +26,8 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 from paddle.distributed import Placement, ProcessMesh, LocalLayer class CustomLayer(dist.LocalLayer): - def __init__(self, out_dist_attrs): - super().__init__(out_dist_attrs) + def __init__(self, out_dist_attrs, grad_dist_attrs): + super().__init__(out_dist_attrs, grad_dist_attrs) self.local_result = paddle.to_tensor(0.0) def forward(self, x): mask = paddle.zeros_like(x) @@ -53,7 +55,7 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 [dist.Shard(0)] ) - custom_layer = CustomLayer(out_dist_attrs) + custom_layer = CustomLayer(out_dist_attrs, out_dist_attrs) output_dist = custom_layer(input_dist) local_value = custom_layer.local_result @@ -71,7 +73,7 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 ::::::::: __call__() -''''''''' +''''''''''' 执行局部计算的核心方法。该方法会: @@ -94,9 +96,11 @@ LocalLayer 可以用于但不限于以下场景： 1. 带 mask 的 loss 计算：需要在每张卡上独立计算 masked token 的 loss 2. MoE（混合专家模型）相关计算： - - aux_loss 计算：基于每张卡上专家分配到的局部 token 数进行计算 - - z_loss 计算：对每张卡上的 logits 独立计算 z_loss - - 张量 reshape 操作：在局部维度上进行 shape 变换 + + - aux_loss 计算：基于每张卡上专家分配到的局部 token 数进行计算 + - z_loss 计算：对每张卡上的 logits 独立计算 z_loss + - 张量 reshape 操作：在局部维度上进行 shape 变换 + 3. 其他需要保持局部计算语义的场景 **注意事项** diff --git a/docs/api/paddle/distributed/all_gather_object_cn.rst b/docs/api/paddle/distributed/all_gather_object_cn.rst index 6a36c57eba6..54dd4024396 100644 --- a/docs/api/paddle/distributed/all_gather_object_cn.rst +++ b/docs/api/paddle/distributed/all_gather_object_cn.rst @@ -14,8 +14,8 @@ all_gather_object 参数 ::::::::: - - **object_list** (List[Any]) - 用于保存聚合结果的列表。 - - **object** (Any) - 待聚合的对象。需要保证该对象是 picklable 的。 + - **object_list** (List[Any]) - 用于保存聚合结果的列表。可传入长度为 world_size、元素均为 ``None`` 的列表（PyTorch 风格），也可传入空列表（Paddle 兼容风格，此时该列表会被原地扩容）。 + - **obj** (Any) - 待聚合的对象。需要保证该对象是 picklable 的。 - **group** (Group，可选) - 执行该操作的进程组实例（通过 ``new_group`` 创建）。默认为 None，即使用全局默认进程组。 返回 diff --git a/docs/api/paddle/distributed/destroy_process_group_cn.rst b/docs/api/paddle/distributed/destroy_process_group_cn.rst index 17140d84d78..71764e50b0d 100644 --- a/docs/api/paddle/distributed/destroy_process_group_cn.rst +++ b/docs/api/paddle/distributed/destroy_process_group_cn.rst @@ -10,7 +10,7 @@ destroy_process_group 参数 ::::::::: - - group (ProcessGroup, 可选): 待销毁的通信组。所有通信组都会被销毁（包括默认的通信组），并且整个分布式环境也会回到未被初始化的状态。 + - **group** (Group，可选): 待销毁的通信组。未指定或指定全局默认通信组时，所有通信组（包括默认通信组）都会被销毁，整个分布式环境会回到未初始化状态；指定非全局通信组时，仅销毁该通信组。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/init_parallel_env_cn.rst b/docs/api/paddle/distributed/init_parallel_env_cn.rst index 495b2fa2803..40bbb8f4529 100644 --- a/docs/api/paddle/distributed/init_parallel_env_cn.rst +++ b/docs/api/paddle/distributed/init_parallel_env_cn.rst @@ -3,16 +3,21 @@ init_parallel_env ----------------- -.. py:function:: paddle.distributed.init_parallel_env() +.. py:function:: paddle.distributed.init_parallel_env(nccl_config=None) 初始化动态图模式下的并行训练环境。 .. note:: 目前同时初始化 ``NCCL`` 和 ``GLOO`` 上下文用于通信。 +参数 +::::::::: + + - **nccl_config** (NCCLConfig|None，可选) - NCCL 配置。默认值为 None。 + 返回 ::::::::: -无 +Group，初始化后的默认进程组实例 代码示例 ::::::::: diff --git a/docs/api/paddle/distributed/load_state_dict_cn.rst b/docs/api/paddle/distributed/load_state_dict_cn.rst index 2923a15e6ab..a60bd9e6114 100644 --- a/docs/api/paddle/distributed/load_state_dict_cn.rst +++ b/docs/api/paddle/distributed/load_state_dict_cn.rst @@ -2,20 +2,24 @@ load_state_dict ------------------------------- -.. py:function:: paddle.distributed.load_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, offload=False, mw_name_compatibility=True) +.. py:function:: paddle.distributed.load_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, offload=False, mw_name_compatibility=True, aoa_config=None, safetensors=False, worker_groups=None, comm_method="broadcast") 将指定路径的 checkpoint 加载到指定 state_dict 中。 参数 ::::::::: - - **state_dict** (dict[str, paddle.Tensor]): 要加载的 state_dict，使用原地加载方式。 + - **state_dict** (dict[str, paddle.Tensor|paddle.distributed.ShardedWeight]): 要加载的 state_dict，使用原地加载方式。 - **path** (str): checkpoint 文件所在目录。 - **process_group** (paddle.distributed.collective.Group，可选): 用于跨 rank 同步的 ProcessGroup。默认值为 None，表示使用包含所有卡的全局 process group。 - **coordinator_rank** (int，可选): 用于协调检查点的 Rank。默认值为 0，表示使用 Rank 0 作为协调检查点。 - **unique_id** (int，可选): checkpoint 的唯一 ID，用于区分不同版本的检查点。默认值为 None，使用指定路径最大值加载最新版本的检查点。 - **offload** (bool，可选): 是否 offload checkpoint 到 CPU。默认值为 False，表示不进行 offload。 - **mw_name_compatibility** (bool，可选): 是否兼容动态图与静态图半自动并行参数的命名。默认值为 True，表示兼容。 + - **aoa_config** (dict[str, list[str]]|None，可选): 用于修改参数的 AOA 配置。默认值为 None。 + - **safetensors** (bool，可选): 是否使用 safetensors 格式。默认值为 False。 + - **worker_groups** (list[paddle.distributed.collective.Group]|None，可选): 用于 Tensor 通信的通信组。提供多个通信组时会选择合适的组；为 None 时使用 process_group。默认值为 None。 + - **comm_method** (str，可选): 重分片的通信方式，可选 ``"send_recv"``、``"broadcast"``、``"multi_group_broadcast"``、``"grouped_send_recv"`` 或 ``"parallel_broadcast"``。默认值为 ``"broadcast"``。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/new_group_cn.rst b/docs/api/paddle/distributed/new_group_cn.rst index 5004d9aaab6..9dead41ea89 100644 --- a/docs/api/paddle/distributed/new_group_cn.rst +++ b/docs/api/paddle/distributed/new_group_cn.rst @@ -4,15 +4,18 @@ new_group ------------------------------- -.. py:function:: paddle.distributed.new_group(ranks=None, backend=None) +.. py:function:: paddle.distributed.new_group(ranks=None, backend=None, timeout=datetime.timedelta(seconds=1800), nccl_comm_init_option=0, nccl_config=None) 创建分布式通信组。 参数 ::::::::: - - **ranks** (list) - 用于新建通信组的全局 rank 列表 - - **backend** (str) - 用于新建通信组的后端支持，目前仅支持 nccl + - **ranks** (list，可选) - 用于新建通信组的全局 rank 列表。默认值为 None。 + - **backend** (str，可选) - 用于新建通信组的后端支持，目前仅支持 nccl。默认值为 None。 + - **timeout** (datetime.timedelta，可选) - 等待 store 相关选项的超时时间。默认值为 30 分钟。 + - **nccl_comm_init_option** (int，可选) - NCCL 通信器初始化选项。默认值为 0。 + - **nccl_config** (NCCLConfig|None，可选) - NCCL 配置。默认值为 None。 返回 diff --git a/docs/api/paddle/distributed/save_state_dict_cn.rst b/docs/api/paddle/distributed/save_state_dict_cn.rst index e41e209191b..30803c7d13f 100644 --- a/docs/api/paddle/distributed/save_state_dict_cn.rst +++ b/docs/api/paddle/distributed/save_state_dict_cn.rst @@ -1,20 +1,22 @@ -.. _cn_api_paddle_distributed_save_state_dict: + .. _cn_api_paddle_distributed_save_state_dict: save_state_dict ------------------------------- -.. py:function:: paddle.distributed.save_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, async_save=False) +.. py:function:: paddle.distributed.save_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, async_save=False, safetensors=False, save_replicas=False) 保存分布式训练的 state_dict 到指定路径。 参数 ::::::::: - - **state_dict** (dict[str, paddle.Tensor]): 要保存的 state_dict。 + - **state_dict** (dict[str, paddle.Tensor|paddle.distributed.ShardedWeight]): 要保存的 state_dict。 - **path** (str): checkpoint 文件所在目录。 - **process_group** (paddle.distributed.collective.Group，可选): 用于跨 rank 同步的 ProcessGroup。默认值为 None，表示使用包含所有卡的全局 process group。 - **coordinator_rank** (int，可选): 用于协调检查点的 Rank。默认值为 0，表示使用 Rank 0 作为协调检查点。 - - **unique_id** (int，可选): checkpoint 的唯一 ID，用于区分不同版本的检查点。默认值为 None，表示使用指定路径最大值加载最新版本的检查点。 + - **unique_id** (int，可选): checkpoint 的唯一 ID，用于区分不同版本的检查点。默认值为 None：首次保存时使用 0，之后在同一路径中每次调用时递增 1；指定的 ID 已存在时会覆盖对应 checkpoint。 - **async_save** (bool，可选): 是否异步保存 state_dict。默认值为 False，表示不使用异步保存。 + - **safetensors** (bool，可选): 是否使用 safetensors 格式保存。默认值为 False。 + - **save_replicas** (bool，可选): 是否保存所有 Tensor 副本（例如来自不同 rank 的副本），而非每个 Tensor 只保存一个去重后的副本。默认值为 False。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/scatter_object_list_cn.rst b/docs/api/paddle/distributed/scatter_object_list_cn.rst index 5e193abd6e9..430f0946966 100644 --- a/docs/api/paddle/distributed/scatter_object_list_cn.rst +++ b/docs/api/paddle/distributed/scatter_object_list_cn.rst @@ -4,7 +4,7 @@ scatter_object_list ------------------------------- -.. py:function:: paddle.distributed.scatter_object_list(out_object_list, in_object_list, src=0, group=None) +.. py:function:: paddle.distributed.scatter_object_list(out_object_list, in_object_list=None, src=0, group=None) 将一组来自指定进程的 picklable 对象分发到每个进程 过程与 ``scatter`` 类似，但可以传入自定义的 python 对象。 @@ -16,7 +16,7 @@ scatter_object_list ::::::::: - **out_object_list** (List[Any]) - 用于接收数据的 object 列表。 - **in_object_list** (List[Any]，可选) - 将被分发的 object 列表。默认为 None，因为 rank != src 的进程上的该参数将被忽略。 - - **src** (int，可选) - 目标进程的 rank，该进程的 object 列表将被分发到其他进程中。默认为 0，即分发 rank=0 的进程上的 object 列表。 + - **src** (int，可选) - 源进程的 rank，该进程的 object 列表将被分发到其他进程中。默认为 0，即分发 rank=0 的进程上的 object 列表。 - **group** (Group，可选) - 执行该操作的进程组实例（通过 ``new_group`` 创建）。默认为 None，即使用全局默认进程组。 返回 diff --git a/docs/api/paddle/distributed/shard_dataloader_cn.rst b/docs/api/paddle/distributed/shard_dataloader_cn.rst index 11146b22238..e5ee8cce03a 100644 --- a/docs/api/paddle/distributed/shard_dataloader_cn.rst +++ b/docs/api/paddle/distributed/shard_dataloader_cn.rst @@ -3,7 +3,7 @@ shard_dataloader ------------------------------- -.. py:function:: paddle.distributed.shard_dataloader(dataloader, meshes, input_keys=None, shard_dims=None, is_dataset_splitted=False) +.. py:function:: paddle.distributed.shard_dataloader(dataloader, meshes, input_keys=None, shard_dims=None, is_dataset_splitted=False, dense_tensor_idx=None) 将单卡视角的数据加载器转变为分布式视角，与普通的 dataloader 相比，其提供了两个能力： 1. 如果 dataloader 的 shard_dim 不为 None，则按 shard_dim 拆分 dataloader 以进行数据并行。 @@ -15,9 +15,10 @@ shard_dataloader - **dataloader** (paddle.io.DataLoader) - 单卡视角的 dataloader。 - **meshes** (ProcessMesh|list|tuple) - 切分 dataloader 使用的 mesh。可以是个 ProcessMesh 或者 list，如果是个 list，则表示不同的输入需要在不同的 mesh 上。 - - **input_keys** (list|tuple，可选) - 如果 dataloader 的迭代结果是一个张量字典，input_keys 是这个字典的键，标识哪个张量位于哪个 mesh 上，与 meshes 一一对应。默认值 None，表示 dataloader 的迭代结果不是 dict。 + - **input_keys** (list[str]|tuple[str]，可选) - 如果 dataloader 的迭代结果是一个张量字典，input_keys 是这个字典的键，标识哪个张量位于哪个 mesh 上，与 meshes 一一对应。默认值 None，表示 dataloader 的迭代结果不是 dict。 - **shard_dims** (str|int|list|tuple，可选) - 对 dataloader 进行分片的 mesh 维度。默认值 None，代表不切分 dataloader，通常使用数据并行的情况下，必须设置此参数。 - **is_dataset_splitted** (bool，可选) - 数据集是否已根据数据并行的 rank 进行了切分。默认值 False。 + - **dense_tensor_idx** (list，可选) - 成对的二维列表，指定 dataloader 输出中 dense Tensor 的索引。每对中的第一个元素指定 dataloader 返回的 dense Tensor，第二个元素指定如何切分该 Tensor：数值表示均匀切分，列表表示非均匀切分。默认值为 None，表示所有输出均为分布式 Tensor。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/shard_optimizer_cn.rst b/docs/api/paddle/distributed/shard_optimizer_cn.rst index c25215d3d16..4aba8a58cc8 100644 --- a/docs/api/paddle/distributed/shard_optimizer_cn.rst +++ b/docs/api/paddle/distributed/shard_optimizer_cn.rst @@ -3,7 +3,7 @@ shard_optimizer ------------------------------- -.. py:function:: paddle.distributed.shard_optimizer(optimizer, shard_fn=None) +.. py:function:: paddle.distributed.shard_optimizer(optimizer, shard_fn=None, gradient_accumulation_steps=1) 将单卡视角的优化器转变为分布式视角。可以通过指定 ``shard_fn`` 来定制化优化器状态的切分方式，否则会将参数的分布式信息传递给对应的优化器状态。 @@ -15,6 +15,7 @@ shard_optimizer - **optimizer** (paddle.optimizer.Optimizer) - 单卡视角的优化器。 - **shard_fn** (Callable，可选) - 用于切分优化器状态函数。如果没有指定，默认地我们将参数的分布式信息传递给对应的优化器状态。 + - **gradient_accumulation_steps** (int，可选) - 梯度累积步数。默认值为 1。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/shard_tensor_cn.rst b/docs/api/paddle/distributed/shard_tensor_cn.rst index a2e61acff26..d1c7f5cb514 100644 --- a/docs/api/paddle/distributed/shard_tensor_cn.rst +++ b/docs/api/paddle/distributed/shard_tensor_cn.rst @@ -3,7 +3,7 @@ shard_tensor ------------------------------- -.. py:function:: paddle.distributed.shard_tensor(data, mesh, placements, dtype=None, place=None, stop_gradient=True) +.. py:function:: paddle.distributed.shard_tensor(data, mesh, placements, dtype=None, place=None, stop_gradient=None) 通过已知的 ``data`` 来创建一个带有分布式信息的 Tensor，Tensor 类型为 ``paddle.Tensor``。 ``data`` 可以是 scalar，tuple，list，numpy\.ndarray，paddle\.Tensor。 @@ -19,8 +19,8 @@ shard_tensor - **placements** (list(Placement)) - 分布式 Tensor 的切分表示列表，描述 Tensor 在 mesh 上如何切分。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 创建 Tensor 的数据类型，可以是 bool、float16、float32、float64、int8、int16、int32、int64、uint8、complex64、complex128。 默认值为 None，如果 ``data`` 为 python 浮点类型，则从 :ref:`cn_api_paddle_get_default_dtype` 获取类型，如果 ``data`` 为其他类型，则会自动推导类型。 - - **place** (CPUPlace|CUDAPinnedPlace|CUDAPlace，可选) - 创建 tensor 的设备位置，可以是 CPUPlace、CUDAPinnedPlace、CUDAPlace。默认值为 None，使用全局的 place。 - - **stop_gradient** (bool，可选) - 是否阻断 Autograd 的梯度传导。默认值为 True，此时不进行梯度传传导。 + - **place** (CPUPlace|CUDAPinnedPlace|CUDAPlace|str，可选) - 创建 Tensor 的设备位置，可以是 CPUPlace、CUDAPinnedPlace、CUDAPlace。默认值为 None，使用全局的 place。若为字符串，可为 ``"cpu"``、``"gpu:x"`` 或 ``"gpu_pinned"``，其中 ``x`` 为 GPU 的索引。 + - **stop_gradient** (bool|None，可选) - 是否阻断 Autograd 的梯度传导。默认值为 None。若为 None，当 ``data`` 具有 ``stop_gradient`` 属性时，返回 Tensor 的 ``stop_gradient`` 与其相同；否则为 True。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/spawn_cn.rst b/docs/api/paddle/distributed/spawn_cn.rst index 6a40feb5a60..c7c773bcb5e 100644 --- a/docs/api/paddle/distributed/spawn_cn.rst +++ b/docs/api/paddle/distributed/spawn_cn.rst @@ -13,11 +13,11 @@ spawn 参数 ::::::::: - **func** (function) - 由 ``spawn`` 方法启动的进程所调用的目标函数。该目标函数需要能够被 ``pickled`` (序列化)，所以目标函数必须定义为模块的一级函数，不能是内部子函数或者类方法。 - - **args** (tuple，可选) - 传入目标函数 ``func`` 的参数。 - - **nprocs** (int，可选) - 启动进程的数目。默认值为-1。当 ``nproc`` 为-1 时，模型执行时将会从环境变量中获取当前可用的所有设备进行使用：如果使用 GPU 执行任务，将会从环境变量 ``CUDA_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID；如果使用 XPU 执行任务，将会从环境变量 ``XPU_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID。 + - **args** (list|tuple，可选) - 传入目标函数 ``func`` 的参数。 + - **nprocs** (int，可选) - 启动进程的数目。默认值为-1。当 ``nprocs`` 为 -1 时，模型执行时将会从环境变量中获取当前可用的所有设备进行使用：如果使用 GPU 执行任务，将会从环境变量 ``CUDA_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID；如果使用 XPU 执行任务，将会从环境变量 ``XPU_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID。 - **join** (bool，可选) - 对所有启动的进程执行阻塞的 ``join``，等待进程执行结束。默认为 True。 - **daemon** (bool，可选) - 配置启动进程的 ``daemon`` 属性。默认为 False。 - - **options (dict，可选) - 其他初始化并行执行环境的配置选项。目前支持以下选项：(1) start_method (string) - 启动子进程的方法。进程的启动方法可以是 ``spawn`` ， ``fork`` , ``forkserver``。因为 CUDA 运行时环境不支持 ``fork`` 方法，当在子进程中使用 CUDA 时，需要使用 ``spawn`` 或者 ``forkserver`` 方法启动进程。默认方法为 ``spawn`` ； (2) gpus (string) - 指定训练使用的 GPU ID，例如 "0,1,2,3"，默认值为 None ； (3) xpus (string) - 指定训练使用的 XPU ID，例如 "0,1,2,3"，默认值为 None ； (4) ips (string) - 运行集群的节点（机器）IP，例如 "192.168.0.16,192.168.0.17"，默认值为 "127.0.0.1" 。 + - **options** (dict，可选) - 其他初始化并行执行环境的配置选项。目前支持以下选项：(1) start_method (string) - 启动子进程的方法。进程的启动方法可以是 ``spawn`` ， ``fork`` , ``forkserver``。因为 CUDA 运行时环境不支持 ``fork`` 方法，当在子进程中使用 CUDA 时，需要使用 ``spawn`` 或者 ``forkserver`` 方法启动进程。默认方法为 ``spawn`` ； (2) gpus (string) - 指定训练使用的 GPU ID，例如 "0,1,2,3"，默认值为 None ； (3) xpus (string) - 指定训练使用的 XPU ID，例如 "0,1,2,3"，默认值为 None ； (4) ips (string) - 运行集群的节点（机器）IP，例如 "192.168.0.16,192.168.0.17"，默认值为 "127.0.0.1" 。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/to_distributed_cn.rst b/docs/api/paddle/distributed/to_distributed_cn.rst index 2b8da82d7fa..edc5bcf4f63 100644 --- a/docs/api/paddle/distributed/to_distributed_cn.rst +++ b/docs/api/paddle/distributed/to_distributed_cn.rst @@ -17,10 +17,12 @@ to_distributed - **model** (paddle.nn.Layer) - 单卡视角的模型，没有包含任何分布式代码。 - **optimizer** (paddle.optimizer.Optimizer) - 单卡视角的优化器，通过常规优化器 API 构造，如 ``paddle.optimizer.Adam``。 - - **dataloader** (paddle.io.DataLoader) - 单卡视角的数据加载器，通过常规方式沟通，如 ``paddle.io.Dataset`` 及 ``paddle.io.Sampler``, 无需使用 ``paddle.io.DistributedBatchSampler``。 + - **dataloader** (paddle.io.DataLoader) - 单卡视角的数据加载器，通过常规方式构造，如 ``paddle.io.Dataset`` 及 ``paddle.io.Sampler``, 无需使用 ``paddle.io.DistributedBatchSampler``。 + - **device_num** (int) - 每个节点或机器上的设备数量。 + - **node_num** (int|None，可选) - 节点或机器数量。默认值为 1。 - **config** (ToDistributedConfig，可选) - 可以用来配置 输入数据信息 和 是否使用序列并行。配置时使用数据类 ``paddle.distributed.auto_parallel.high_level_api.ToDistributedConfig`` 来完成。 - 配置 输入数据信息，是提供模型训练时最有可能输入数据的 shape、dtype 和 stop_gradient 信息，便于更快更准地自动选择最优的分布式策略。 + 配置 输入数据信息，是通过 ``list[paddle.static.InputSpec]`` 提供模型训练时最有可能输入数据的 shape、dtype 和 name 信息，便于更快更准地自动选择最优的分布式策略。 配置 是否使用序列并行，可以指定如果最优的分布式策略中包含模型并行时，是否要使用序列并行。 diff --git a/docs/api/paddle/distributed/to_static_cn.rst b/docs/api/paddle/distributed/to_static_cn.rst index 797a5e840cb..253cda97737 100644 --- a/docs/api/paddle/distributed/to_static_cn.rst +++ b/docs/api/paddle/distributed/to_static_cn.rst @@ -3,27 +3,26 @@ to_static ------------------------------- -.. py:function:: paddle.distributed.to_static(layer, loader, loss=None, optimizer=None, strategy=None) +.. py:function:: paddle.distributed.to_static(layer, loader=None, loss=None, optimizer=None, strategy=None, input_spec=None) -将带有分布式切分信息的动态图 ``layer`` 转换为静态图分布式模型，可在静态图模式下进行分布式训练；同时将动态图下所使用的数据迭代器 ``loader`` 转换为静态图分布式训练所使用的数据迭代器。 +将带有分布式切分信息的动态图 ``layer`` 转换为静态图分布式模型，可在静态图模式下进行分布式训练、评估和预测。 -``paddle.distributed.to_static`` 返回 ``DistModel`` 实例和 ``DistributedDataLoader`` 实例。 ``DistModel`` 实例包含了转换后的静态图模型，同时提供了训练、评估和预测的接口。 ``DistributedDataLoader`` 实例用于在静态图分布式训练中加载数据。 +``paddle.distributed.to_static`` 返回包含转换后静态图模型的 ``DistModel`` 实例，并提供训练、评估和预测接口。 参数 ::::::::: - **layer** (paddle.nn.Layer) - 带有分布式信息，可在动态图模式下进行分布式训练的模型。 - - **loader** (paddle.io.DataLoader) - 动态图训练时所使用的数据迭代器。 - - **loss** (Loss|Callable|None, 可选) - 损失函数。需要训练或者评估模型时，该参数必须设定。 - - **optimizer** (Optimizer|None, 可选) - 优化器。训练模型时，该参数必须设定。 - - **strategy** (Strategy|None, 可选) - 分布式训练的配置，用于设置混合精度训练、分布式优化策略等。 + - **loader** (ShardDataloader|paddle.io.DataLoader|None，可选) - 动态图模式下使用的数据加载器，用于推断 input_spec 和 label_spec。默认值为 None。 + - **loss** (Loss|Callable|None，可选) - 损失函数。需要训练或者评估模型时，该参数必须设定。 + - **optimizer** (Optimizer|_ShardOptimizer|None，可选) - 优化器。可以是 ``paddle.optimizer.Optimizer``，也可以是由 ``shard_optimizer`` 包装的 ``_ShardOptimizer``。训练模型时，该参数必须设定。 + - **strategy** (Strategy|None，可选) - 分布式训练的配置，用于设置混合精度训练、分布式优化策略等。 + - **input_spec** (list[list[paddle.distributed.DistributedInputSpec]]|None，可选) - 自定义输入规格，指定模型输入和标签的形状、数据类型及名称信息。非 None 时，由该参数推断输入和标签规格；其应包含两个子列表，第一个表示输入规格，第二个表示标签规格。默认值为 None。 返回 ::::::::: -DistModel: 用于静态图分布式训练的模型，通过 ``__call__`` 方法进行训练、评估和预测。需要执行训练、评估或预测时，需要先使用 ``DistModel`` 实例的 ``train()/eval()/predict()`` 方法将其转换为对应的模式。 ``DistModel`` 实例的默认模式会根据 ``paddle.distributed.to_static`` 的输入设置，当 ``loss`` 和 ``optimizer`` 均给定时，默认模式为 ``train``；当 ``optimizer`` 为空时，默认模式为 ``eval``；当 ``loss`` 和 ``optimizer`` 均为空时，默认模式为 ``predict``。 - -DistributedDataLoader: 用于静态图分布式训练的数据迭代器，和 ``paddle.io.DataLoader`` 用法一致。 +DistModel: 用于静态图分布式训练的模型，通过 ``__call__`` 方法进行训练、评估和预测。需要执行训练、评估或预测时，需要先使用 ``DistModel`` 实例的 ``train()/eval()/predict()`` 方法将其转换为对应的模式。``DistModel`` 实例的默认模式会根据 ``paddle.distributed.to_static`` 的输入设置：当 ``loss`` 和 ``optimizer`` 均给定时，默认模式为 ``train``；当 ``loss`` 非空且 ``optimizer`` 为空时，默认模式为 ``eval``；当 ``loss`` 为空时，默认模式为 ``predict``。 代码示例 diff --git a/docs/api/paddle/distribution/ExponentialFamily_cn.rst b/docs/api/paddle/distribution/ExponentialFamily_cn.rst index c59365bf14c..51208472899 100644 --- a/docs/api/paddle/distribution/ExponentialFamily_cn.rst +++ b/docs/api/paddle/distribution/ExponentialFamily_cn.rst @@ -3,7 +3,7 @@ ExponentialFamily ------------------------------- -.. py:class:: paddle.distribution.ExponentialFamily() +.. py:class:: paddle.distribution.ExponentialFamily(batch_shape=(), event_shape=(), validate_args=None) 指数型分布族的基类，继承 ``paddle.distribution.Distribution``。概率密度/质量函数满足下述 形式 @@ -13,6 +13,12 @@ ExponentialFamily f_{F}(x; \theta) = \exp(\langle t(x), \theta\rangle - F(\theta) + k(x)) 其中，:math:`\theta` 表示自然参数，:math:`t(x)` 表示充分统计量，:math:`F(\theta)` 为对数 -归一化函数。 +归一化函数，:math:`k(x)` 表示基测度（carrier measure）。 属于指数型分布族的概率分布列表参考 https://en.wikipedia.org/wiki/Exponential_family + +参数 +::::::::: + - **batch_shape** (Sequence[int]，可选) - 独立但不必同分布的采样所对应的形状，即一组分布的形状。默认值为 ``()``。 + - **event_shape** (Sequence[int]，可选) - 单次采样的形状，维度之间可以相关。对于标量分布，事件形状为 ``[]``；对于 n 维多元分布，事件形状为 ``[n]``。默认值为 ``()``。 + - **validate_args** (bool|None，可选) - 是否启用参数校验。默认值为 None，此时使用全局默认设置。 diff --git a/docs/api/paddle/distribution/LKJCholesky_cn.rst b/docs/api/paddle/distribution/LKJCholesky_cn.rst index 258149deaa7..190dbf62ea4 100644 --- a/docs/api/paddle/distribution/LKJCholesky_cn.rst +++ b/docs/api/paddle/distribution/LKJCholesky_cn.rst @@ -2,7 +2,8 @@ LKJCholesky ------------------------------- -.. py:class:: paddle.distribution.LKJCholesky(dim, concentration=1.0, sample_method = 'onion') + +.. py:class:: paddle.distribution.LKJCholesky(dim=2, concentration=1.0, sample_method='onion') @@ -17,14 +18,15 @@ LKJ 分布通常定义为对相关矩阵 :math:`\Omega` 的分布，其密度函 其中，:math:`\Omega` 是一个 :math:`n \times n` 的相关矩阵，:math:`\eta` 是分布的形状参数，:math:`|\Omega|` 是矩阵的行列式。参数 :math:`\eta` 调节矩阵元素的分布集中度。 -相关矩阵的下三角 Choleskey 因子的 LJK 分布支持两种 sample 方法：``onion`` 和 ``cvine``。 +相关矩阵的下三角 Cholesky 因子的 LKJ 分布支持两种 sample 方法：``onion`` 和 ``cvine``。 参数 :::::::::::: - **dim** (int) - 目标相关矩阵的维度。 - **concentration** (float|Tensor) - 集中参数，这个参数控制了生成的相关矩阵的分布，值必须大于 0。concentration 越大，生成的矩阵越接近单位矩阵。 - - **sample_method** (str) - 不同采样策略，可选项有：``onion`` 和 ``cvine``. 这两种 sample 方法都在 `Generating random correlation matrices based on vines and extended onion method `_ 中提出，并且在相关矩阵上提供相同的分布。但是它们在如何生成样本方面是不同的。默认为“onion”。 + - **sample_method** (str) - 不同采样策略，可选项有：``onion`` 和 ``cvine``。这两种 sample 方法都在 `Generating random correlation matrices based on vines and extended onion method `_ 中提出，并且在相关矩阵上提供相同的分布。但是它们在如何生成样本方面是不同的。默认为“onion”。 + 代码示例 :::::::::::: @@ -36,8 +38,8 @@ COPY-FROM: paddle.distribution.LKJCholesky log_prob(value) -''''''''' -卡方分布的对数概率密度函数。 +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +计算给定相关矩阵 Cholesky 因子在 LKJ 分布下的对数概率密度。 **参数** @@ -45,18 +47,18 @@ log_prob(value) **返回** - - **Tensor** - value 对应的对数概率密度。 + - **Tensor** - 给定相关矩阵 Cholesky 因子对应的对数概率密度。 -sample(shape=[]) -''''''''' +sample(sample_shape=[]) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 随机采样，生成指定维度的样本。 **参数** - - **shape** (Sequence[int]，可选) - 采样的样本维度。 + - **sample_shape** (Sequence[int]，可选) - 采样的样本维度。 **返回** - - **Tensor** - 指定维度的样本数据。数据类型为 float32。 + - **Tensor** - 指定维度的样本数据。数据类型与 ``concentration`` 相同。 diff --git a/docs/api/paddle/distribution/LogNormal_cn.rst b/docs/api/paddle/distribution/LogNormal_cn.rst index e722dd8afe9..f28f8a653c3 100644 --- a/docs/api/paddle/distribution/LogNormal_cn.rst +++ b/docs/api/paddle/distribution/LogNormal_cn.rst @@ -3,7 +3,7 @@ LogNormal ------------------------------- -.. py:class:: paddle.distribution.LogNormal(loc, scale, name=None) +.. py:class:: paddle.distribution.LogNormal(loc, scale) 对数正态分布 @@ -33,7 +33,7 @@ LogNormal 参数 :::::::::::: - - **loc** (int|float|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的平均值。 + - **loc** (int|float|complex|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的平均值。数据类型为 float32、float64、complex64 或 complex128。 - **scale** (int|float|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的标准差。 代码示例 @@ -60,15 +60,14 @@ variance 方法 ::::::::: -sample(shape=[], seed=0) -''''''''' +sample(shape=[]) +'''''''''''''''''''''''''''''''''''''''' 生成指定维度的样本。 **参数** - - **shape** (Sequence[int], 可选) - 指定生成样本的维度。 - - **seed** (int) - 长整型数。 + - **shape** (Sequence[int], 可选) - 指定生成样本的维度。别名 ``sample_shape``。 **返回** @@ -81,7 +80,7 @@ rsample(shape=[]) **参数** - - **shape** (Sequence[int], 可选) - 指定生成样本的维度。 + - **shape** (Sequence[int], 可选) - 指定生成样本的维度。别名 ``sample_shape``。 **返回** From b5da76b922642eb010f40e34958af3e7ae6a7708 Mon Sep 17 00:00:00 2001 From: manfredss Date: Fri, 14 Aug 2026 16:38:10 +0800 Subject: [PATCH 13/18] add 13 more apis --- .../FusedBiasDropoutResidualLayerNorm_cn.rst | 4 +++- .../incubate/nn/FusedFeedForward_cn.rst | 16 +++++++++++--- .../nn/FusedMultiHeadAttention_cn.rst | 14 ++++++------- .../nn/functional/fused_feedforward_cn.rst | 13 ++++++++---- .../nn/functional/fused_linear_cn.rst | 13 ++++++------ .../functional/fused_multi_transformer_cn.rst | 15 ++++++++----- .../nn/functional/fused_rms_norm_cn.rst | 12 +++++------ .../fused_rotary_position_embedding_cn.rst | 21 ++++++++++--------- .../masked_multihead_attention_cn.rst | 19 ++++++++++------- .../paddle/incubate/optimizer/LBFGS_cn.rst | 19 ++++++++++------- docs/api/paddle/incubate/segment_max_cn.rst | 6 ++++-- docs/api/paddle/incubate/segment_min_cn.rst | 6 ++++-- docs/api/paddle/incubate/segment_sum_cn.rst | 6 ++++-- 13 files changed, 100 insertions(+), 64 deletions(-) diff --git a/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst b/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst index eaf074f8d56..00c4f069afd 100644 --- a/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst +++ b/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst @@ -1,7 +1,7 @@ .. _cn_api_paddle_incubate_nn_FusedBiasDropoutResidualLayerNorm: FusedBiasDropoutResidualLayerNorm -------------------------------- +---------------------------------- .. py:class:: paddle.incubate.nn.FusedBiasDropoutResidualLayerNorm(embed_dim, dropout_rate=0.5, weight_attr=None, bias_attr=None, epsilon=1e-05, name=None) @@ -11,8 +11,10 @@ FusedBiasDropoutResidualLayerNorm :::::::::::: - **embed_dim** (int) - 输入和输出中预期的特征大小。 - **dropout_rate** (float，可选) - 在注意力权重上使用的 Dropout 概率，用于在注意力后的 Dropout 过程中丢弃一些注意力目标。0 表示无 Dropout。默认为 0.5。 + - **weight_attr** (ParamAttr，可选) - 指定本层可学习权重的属性。默认值为 None，权重初始化为零。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数的属性。默认为 None，意味着使用默认的偏置参数属性。如果设置为 False，则该层不会有可训练的偏置参数。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **epsilon** (float，可选) - 添加到方差中的小值，以防止除零。默认为 1e-05。 + - **name** (str，可选) - 一般无需设置。具体用法请参见 :ref:`api_guide_Name`。 代码示例 :::::::::::: diff --git a/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst b/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst index b8630276734..cf6e51f3a63 100644 --- a/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst +++ b/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst @@ -2,7 +2,7 @@ FusedFeedForward ------------------------------- -.. py:class:: paddle.incubate.nn.FusedFeedForward(d_model, dim_feedforward, dropout_rate=0.1, activation='relu', act_dropout_rate=None, normalize_before=False, weight_attr=None, bias_attr=None) +.. py:class:: paddle.incubate.nn.FusedFeedForward(d_model, dim_feedforward, dropout_rate=0.1, epsilon=1e-05, activation='relu', act_dropout_rate=None, normalize_before=False, linear1_weight_attr=None, linear1_bias_attr=None, linear2_weight_attr=None, linear2_bias_attr=None, ln1_scale_attr=None, ln1_bias_attr=None, ln2_scale_attr=None, ln2_bias_attr=None, nranks=1, ring_id=-1, name=None) 这是一个调用融合算子 fused_feedforward（参考 :ref:`cn_api_paddle_incubate_nn_functional_fused_feedforward` ）。 @@ -12,11 +12,21 @@ FusedFeedForward - **d_model** (int) - 输入输出的维度。 - **dim_feedforward** (int) - 前馈神经网络中隐藏层的大小。 - **dropout_rate** (float，可选) - 对本层的输出进行处理的 dropout 值，置零的概率。默认值：0.1。 + - **epsilon** (float，可选) - 为防止方差除零而加到方差上的小值。默认值为 1e-05。 - **activation** (str，可选) - 激活函数。默认值：``relu``。 - **act_dropout_rate** (float，可选) - 激活函数后的 dropout 置零的概率。如果为 ``None`` 则 ``act_dropout_rate = dropout_rate``。默认值：``None`` 。 - **normalize_before** (bool，可选) - 设置对输入输出的处理。如果为 ``True``，则对输入进行层标准化（Layer Normalization），否则（即为 ``False`` ），则对输入不进行处理，而是在输出前进行标准化。默认值：``False`` 。 - - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性，即使用 0 进行初始化。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。如果该参数值是 ``ParamAttr``，则使用 ``ParamAttr``。如果该参数为 ``bool`` 类型，只支持为 ``False``，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **linear1_weight_attr** (ParamAttr，可选) - 前馈网络第一个线性层权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **linear1_bias_attr** (ParamAttr|bool，可选) - 前馈网络第一个线性层偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **linear2_weight_attr** (ParamAttr，可选) - 前馈网络第二个线性层权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **linear2_bias_attr** (ParamAttr|bool，可选) - 前馈网络第二个线性层偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln1_scale_attr** (ParamAttr，可选) - 前置 LayerNorm 权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln1_bias_attr** (ParamAttr|bool，可选) - 前置 LayerNorm 偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln2_scale_attr** (ParamAttr，可选) - 后置 LayerNorm 权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln2_bias_attr** (ParamAttr|bool，可选) - 后置 LayerNorm 偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **nranks** (int，可选) - 分布式张量模型并行的 rank 数。默认值为 1，表示不使用张量并行。 + - **ring_id** (int，可选) - 用于分布式张量模型并行。默认值为 -1，表示不使用张量并行。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 ::::::::: diff --git a/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst b/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst index a4ccf7d36e2..e86529865da 100644 --- a/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst +++ b/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst @@ -23,22 +23,22 @@ FusedMultiHeadAttention ::::::::: - **embed_dim** (int) - 输入输出的维度。 - **num_heads** (int) - 多头注意力机制的 Head 数量。 - - **dropout_rate** (float，可选) - Multi-Head Attention 后面的 dropout 算子的注意力目标的随机失活率。0 表示进行 dropout 计算。默认值：0.5。 + - **dropout_rate** (float，可选) - Multi-Head Attention 后面的 dropout 算子的注意力目标的随机失活率。0 表示不进行 dropout 计算。默认值：0.5。 - **attn_dropout_rate** (float，可选) - Multi-Head Attention 中的 dropout 算子的注意力目标的随机失活率。0 表示不进行 dropout 计算。默认值：0.5。 - **kdim** (int，可选) - 键值对中 key 的维度。如果为 ``None`` 则 ``kdim = embed_dim``。默认值 ``None`` 。 - **vdim** (int，可选) - 键值对中 value 的维度。如果为 ``None`` 则 ``vdim = embed_dim``。默认值：``None`` 。 - **normalize_before** (bool，可选) - 是 pre_layer_norm 结构（True）还是 post_layer_norm 结构（False）。pre_layer_norm 结构中，``layer_norm`` 算子位于 multi-head attention 和 ffn 的前面，post_layer_norm 结构中，``layer_norm`` 位于两者的后面。默认值：``False`` 。 - - **need_weights** (bool，可选) - 表明是否返回注意力权重。默认值：``False`` 。 + - **need_weights** (bool，可选) - 表明是否返回注意力权重。当前仅支持 ``False``。默认值：``False`` 。 - **qkv_weight_attr** (ParamAttr，可选) - 为 Attention 中计算 q, k, v 时的计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **qkv_bias_attr** (ParamAttr，可选) - 为 Attention 中计算 q, k, v 时的计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **qkv_bias_attr** (ParamAttr|bool|None，可选) - 为 Attention 中计算 q, k, v 时的计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **linear_weight_attr** (ParamAttr，可选) - 为 Multi-Head Attention 之后的线性计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **linear_bias_attr** (ParamAttr，可选) - 为 Multi-Head Attention 之后的线性计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **linear_bias_attr** (ParamAttr|bool|None，可选) - 为 Multi-Head Attention 之后的线性计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **pre_ln_scale_attr** (ParamAttr，可选) - 为 pre_layer_norm 结构的前置 layer norm 计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **pre_ln_bias_attr** (ParamAttr，可选) - 为 pre_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **pre_ln_bias_attr** (ParamAttr|bool|None，可选) - 为 pre_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **ln_scale_attr** (ParamAttr，可选) - 为 post_layer_norm 结构的后置 layer norm 计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **ln_bias_attr** (ParamAttr，可选) - 为 post_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **ln_bias_attr** (ParamAttr|bool|None，可选) - 为 post_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - - **nranks** (int，可选) - 分布式 tensor parallel 运行下该策略的并行度。默认值：-1，表示不使用 tensor parallel。 + - **nranks** (int，可选) - 分布式 tensor parallel 运行下该策略的并行度。默认值：1，表示不使用 tensor parallel。 - **ring_id** (int，可选) - 分布式 tensor parallel 运行下通讯所使用的 NCCL id。默认值：-1，表示不使用 tensor parallel。 - **transpose_qkv_wb** (bool，可选) - 生成 QKV 的映射计算的权重形状为 ``[3, num_heads, head_dim, embed_dim]`` (False) 还是 ``[embed_dim, 3 * embed_dim]`` (True)。仅支持 GPU 运算。默认值：``False``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst index 30c36e8255b..520b8c0fc18 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst @@ -3,7 +3,7 @@ fused_feedforward ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_feedforward(x, linear1_weight, linear2_weight, linear1_bias=None, linear2_bias=None, ln1_scale=None, ln1_bias=None, ln2_scale=None, ln2_bias=None, dropout1_rate=0.5, dropout2_rate=0.5,activation="relu", ln1_epsilon=1e-5, ln2_epsilon=1e-5, pre_layer_norm=False, training=True, mode='upscale_in_train', name=None) +.. py:function:: paddle.incubate.nn.functional.fused_feedforward(x, linear1_weight, linear2_weight, linear1_bias=None, linear2_bias=None, ln1_scale=None, ln1_bias=None, ln2_scale=None, ln2_bias=None, dropout1_rate=0.5, dropout2_rate=0.5, activation="relu", ln1_epsilon=1e-5, ln2_epsilon=1e-5, pre_layer_norm=False, training=True, mode='upscale_in_train', ring_id=-1, add_residual=True, name=None) 这是一个融合算子，该算子是对 transformer 模型中 feed forward 层的多个算子进行融合，该算子只支持在 GPU 下运行，该算子与如下伪代码表达一样的功能： @@ -13,7 +13,10 @@ fused_feedforward if pre_layer_norm: src = layer_norm(src) src = linear(dropout(activation(linear(src)))) - src = residual + dropout(src) + if add_residual: + src = residual + dropout(src) + else: + src = dropout(src) if not pre_layer_norm: src = layer_norm(src) @@ -34,8 +37,8 @@ fused_feedforward - **ln1_epsilon** (float，可选) - 一个很小的浮点数，被第一个 layer_norm 算子加到分母，避免出现除零的情况。默认值是 1e-5。 - **ln2_epsilon** (float，可选) - 一个很小的浮点数，被第二个 layer_norm 算子加到分母，避免出现除零的情况。默认值是 1e-5。 - **pre_layer_norm** (bool，可选) - 在预处理阶段加上 layer_norm，或者在后处理阶段加上 layer_norm。默认值是 False。 - - **training** (bool)：标记是否为训练阶段。默认：True。 - - **mode** (str)：丢弃单元的方式，有两种'upscale_in_train'和'downscale_in_infer'，默认：'upscale_in_train'。计算方法如下： + - **training** (bool。可选) - 标记是否为训练阶段。默认：True。 + - **mode** (str，可选) - 丢弃单元的方式，有两种'upscale_in_train'和'downscale_in_infer'，默认：'upscale_in_train'。计算方法如下： 1. upscale_in_train，在训练时增大输出结果。 @@ -47,6 +50,8 @@ fused_feedforward - train: out = input * mask - inference: out = input * (1.0 - p) + - **ring_id** (int，可选) - 用于张量模型并行中的分布式前向传播，仅支持 NCCL。默认值为 -1，表示不使用张量并行。 + - **add_residual** (bool，可选) - 是否在末尾添加残差。默认值为 True。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst index d5322691d2d..2675ccb0954 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst @@ -3,18 +3,17 @@ fused_linear ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_linear(x, weight, bias=None, trans_x=False, transpose_weight=False, name=None) +.. py:function:: paddle.incubate.nn.functional.fused_linear(x, weight, bias=None, transpose_weight=False, name=None) 全连接线性变换算子。该方法要求 CUDA 版本大于等于 11.6 。 参数 ::::::::: - - **x** (Tensor) – 需要进行乘法运算的输入 Tensor。 - - **weight** (Tensor) – 需要进行乘法运算的权重 Tensor，它的阶数必须为 2。 - - **bias** (Tensor, 可选) – 输入的偏置 Tensor。如果为 None ，则不执行偏置加法。否则，将偏置加到矩阵乘法的结果上。默认值为 None。 - - **trans_x** (bool, 可选) - 是否在乘法之前转置输入 Tensor。默认值：False。 - - **transpose_weight** (bool, 可选) - 是否在乘法之前转置权重。默认值：False。 - - **name** (str, 可选) - 如需详细信息，请参阅 :ref:`api_guide_Name` 。一般无需设置，默认值为 None。 + - **x** (Tensor) - 需要进行乘法运算的输入 Tensor。 + - **weight** (Tensor) - 需要进行乘法运算的权重 Tensor，它的阶数必须为 2。 + - **bias** (Tensor，可选) - 输入的偏置 Tensor。如果为 None ，则不执行偏置加法。否则，将偏置加到矩阵乘法的结果上。默认值为 None。 + - **transpose_weight** (bool，可选) - 是否在乘法之前转置权重。默认值：False。 + - **name** (str，可选) - 如需详细信息，请参阅 :ref:`api_guide_Name` 。一般无需设置，默认值为 None。 返回 ::::::::: diff --git a/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst index a55cdb79d2c..98e5852ed20 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst @@ -3,7 +3,7 @@ fused_multi_transformer ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_multi_transformer(x, ln_scales, ln_biases, qkv_weights, qkv_biases, linear_weights, linear_biases, ffn_ln_scales, ffn_ln_biases, ffn1_weights, ffn1_biases, ffn2_weights, ffn2_biases, pre_layer_norm=True, epsilon=1e-05, cache_kvs=None, pre_caches=None, seq_lens=None, rotary_embs=None, time_step=None, attn_mask=None, dropout_rate=0.0, rotary_emb_dims=0, activation='gelu', training=False, mode='upscale_in_train', trans_qkvw=True, ring_id=- 1, name=None) +.. py:function:: paddle.incubate.nn.functional.fused_multi_transformer(x, ln_scales, ln_biases, qkv_weights, qkv_biases, linear_weights, linear_biases, ffn_ln_scales, ffn_ln_biases, ffn1_weights, ffn1_biases, ffn2_weights, ffn2_biases, pre_layer_norm=True, epsilon=1e-05, residual_alpha=1.0, cache_kvs=None, beam_offset=None, pre_caches=None, seq_lens=None, rotary_embs=None, time_step=None, attn_mask=None, dropout_rate=0.0, rotary_emb_dims=0, activation='gelu', training=False, mode='upscale_in_train', trans_qkvw=True, ring_id=-1, norm_type='layernorm', use_neox_rotary_style=False, gqa_group_size=-1, name=None) 这是一个融合算子，用于计算 Transformer 模型架构中的多个 transformer 层。 @@ -49,27 +49,29 @@ Transformer 层的功能与以下伪代码一致： :::::::::::: - **x** (Tensor) - 输入张量可以是 3-D 张量，输入数据类型可以是 float16 或 float32，形状为 ``[batch\_size, sequence\_length, d\_model]``。 - **ln_scales** (list(Tensor)|tuple(Tensor)) - 注意力机制中层归一化层的权重张量，形状为 ``[d\_model]``。 - - **ln_biases** (list(Tensor)|tuple(Tensor)) - 注意力机制中层归一化层的偏重张量，形状为 ``[d\_model]``。 + - **ln_biases** (list(Tensor)|tuple(Tensor)) - 注意力机制中层归一化层的偏置张量，形状为 ``[d\_model]``。 - **qkv_weights** (list(Tensor)|tuple(Tensor)) - 注意力 qkv 计算的权重张量，形状为 ``[3, num\_head, dim\_head, d\_model]``。 - **qkv_biases** (list(Tensor)|tuple(Tensor)|None) - 注意力 qkv 计算的偏置张量，形状为 ``[3, num\_head, dim\_head]``。 - **linear_weights** (list(Tensor)|tuple(Tensor)) - 注意力机制中线性层的权重张量，形状为 ``[num\_head * dim\_head, d\_model]``。 - - **linear_biases** (list(Tensor)|tuple(Tensor)|None) - 注意力机制中线性层的的偏置张量，形状为 ``[d\_model]``。 + - **linear_biases** (list(Tensor)|tuple(Tensor)|None) - 注意力机制中线性层的偏置张量，形状为 ``[d\_model]``。 - **ffn_ln_scales** (list(Tensor)|tuple(Tensor)) - 前馈层中层归一化层的权重张量，形状为 ``[d\_model]``。 - **ffn_ln_biases** (list(Tensor)|tuple(Tensor)) - 前馈层中层归一化层的偏置张量，形状为 ``[d\_model]``。 - **ffn1_weights** (list(Tensor)|tuple(Tensor)) - 前馈层中第一个线性变换层的权重张量，形状为 ``[d\_model, dim\_feedforward]``。 - **ffn1_biases** (list(Tensor)|tuple(Tensor)|None) - 前馈层中第一个线性变换层的偏置张量，形状为 ``[dim\_feedforward]``。 - **ffn2_weights** (list(Tensor)|tuple(Tensor)) - 前馈层中第二线性变换层的权重张量，形状为 ``[dim\_feedforward, d\_model]``。 - - **ffn2_biases** (list(Tensor)|tuple(Tensor)|None) - 前馈层中第二线性变换层的偏置张量，形状为 ``[d_model]``。 + - **ffn2_biases** (list(Tensor)|tuple(Tensor)|None) - 前馈层中第二线性变换层的偏置张量，形状为 ``[d\_model]``。 - **pre_layer_norm** (bool，可选) - 是否是 pre_layer_norm（True）或 post_layer_norm（False）。默认为 True。 - **epsilon** (float，可选) - 添加到 layer_norm 的分母中的小浮点值，以避免除以零。默认为 1e-5。 + - **residual_alpha** (float，可选) - 残差连接的缩放系数。默认值为 1.0。 - **cache_kvs** (list(Tensor)|tuple(Tensor)，可选) - 生成模型的缓存结构张量。形状为 ``[2, bsz, num\_head, max\_seq\_len, head\_dim]``。默认为 None。 + - **beam_offset** (list(Tensor)|tuple(Tensor)|None，可选) - 生成模型使用的 beam offset。默认值为 None。 - **pre_caches** (list(Tensor)|tuple(Tensor)，可选) - 生成模型的前缀缓存。形状为 ``[2, bsz, num\_head, cache\_len, head\_dim]``。默认为 None。 - **seq_lens** (Tensor，可选) - 此批次的序列长度。形状为 ``[bsz]``。默认为 None。 - **rotary_embs** (Tensor，可选) - 用于旋转计算的 RoPE 嵌入。形状为 ``[2, bsz, 1, seq\_len, head\_dim]``。默认为 None。 - **time_step** (Tensor，可选) - 生成模型的时间步张量。用于解码阶段，表示时间步，即 CacheKV 的实际 seq_len。形状为 ``[1]``，必须位于 CPUPlace。默认为 None。 - **attn_mask** (Tensor，可选) - 用于多头注意力层中防止对某些不需要的位置（通常是填充或后续位置）进行注意。其形状为 ``[batch_size, 1, sequence_length, sequence_length]``。默认为 None。 - **dropout_rate** (float，可选) - 将单元设置为零的 dropout 概率。默认为 0.0。 - - **rotary_emb_dims** (int，可选) - 旋转计算的 rotary_emb_dims，当 rotary_embs 为 None 时为 0，当 rotary_embs 不为 None 且 pos_extra_ids 为 None 时为 1，当 rotary_embs 和 pos_extra_ids 均不为 None 时为 2。默认为 0。 + - **rotary_emb_dims** (int，可选) - 旋转计算的 rotary_emb_dims，当 ``rotary_embs`` 为 None 时为 0；当 ``rotary_embs`` 不为 None 时，该值大于 0 以启用旋转位置编码计算。默认为 0。 - **activation** (str，可选) - 激活函数。默认为"gelu"。 - **training** (bool，可选) - 标志是否处于训练阶段。默认为 False。 - **mode** (str，可选) - ['upscale_in_train'(默认) | 'downscale_in_infer'] @@ -85,6 +87,9 @@ Transformer 层的功能与以下伪代码一致： 如果为 true，则 qkv 的权重形状应为[3, num_head, dim_head, dim_embed]。 否则，qkv 的权重形状应为[dim_embed, 3, num_head, dim_head]。默认为 True。 - **ring_id** (int，可选) - 用于张量模型并行中的分布式前向传播，仅支持 NCCL。默认为-1，表示不使用 mp。 + - **norm_type** (str，可选) - 归一化类型。默认值为 ``"layernorm"``。 + - **use_neox_rotary_style** (bool，可选) - 是否使用 Neox 风格的旋转位置编码。默认值为 False。 + - **gqa_group_size** (int，可选) - GQA（Group Query Attention）组大小。默认值为 -1。 - **name** (str，可选) - 操作的名称（可选，默认为 None）。更多信息，请参阅 :ref:`api_guide_Name`。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst index 1cb6548d0fe..21b26f918dc 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst @@ -3,7 +3,7 @@ fused_rms_norm ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_rms_norm(x, norm_weight, norm_bias, epsilon, begin_norm_axis, bias=None, residual=None, quant_scale=- 1, quant_round_type=0, quant_max_bound=0, quant_min_bound=0) +.. py:function:: paddle.incubate.nn.functional.fused_rms_norm(x, norm_weight, norm_bias, epsilon, begin_norm_axis=1, bias=None, residual=None, quant_scale=-1, quant_round_type=0, quant_max_bound=0, quant_min_bound=0) 应用 Fused RMSNorm 内核，提供了更高的 GPU 利用率。同时，支持模式融合 RMSNorm(bias + residual + x)。 @@ -17,13 +17,13 @@ fused_rms_norm 算子目前只支持在 GPU 下运行。 - **norm_weight** (Tensor) - 用于仿射输出的权重张量。 - **norm_bias** (Tensor) - 用于仿射输出的偏置张量。 - **epsilon** (float) - 一个小的浮点数，用于避免除以零。 - - **begin_norm_axis** (int) - 归一化的起始轴，默认为 1。 + - **begin_norm_axis** (int，可选) - 归一化的起始轴，默认为 1。 - **bias** (Tensor，可选) - 前一层的偏置。 - **residual** (Tensor，可选) - 输入的残差。 - - **quant_scale** (float) - 量化缩放因子。 - - **quant_round_type** (float) - 量化四舍五入类型。 - - **quant_max_bound** (float) - 量化裁剪的最大边界值。 - - **quant_min_bound** (float) - 量化裁剪的最小边界值。 + - **quant_scale** (float，可选) - 量化缩放因子。 + - **quant_round_type** (float，可选) - 量化四舍五入类型。 + - **quant_max_bound** (float，可选) - 量化裁剪的最大边界值。 + - **quant_min_bound** (float，可选) - 量化裁剪的最小边界值。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst index 62f0baa1ccf..3345e05d133 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst @@ -3,21 +3,22 @@ fused_rotary_position_embedding ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_rotary_position_embedding(q, k=None, v=None, sin=None, cos=None, position_ids=None, use_neox_rotary_style=True) +.. py:function:: paddle.incubate.nn.functional.fused_rotary_position_embedding(q, k=None, v=None, sin=None, cos=None, position_ids=None, use_neox_rotary_style=True, time_major=False, rotary_emb_base=10000.0) + 融合旋转位置编码。 参数 :::::::::: - - **q** (Tensor) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 q 的形状必须是 [batch_size, seq_len, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 - - **k** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 k 的形状必须是 [batch_size, seq_len, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 - - **v** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 v 的形状必须是 [batch_size, seq_len, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 - - **sin** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 sin 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 - - **cos** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 cos 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 - - **position_ids** (Tensor, 可选) - 输入张量。 数据类型为 int64. position_ids 的形状为[batch_size, seq_len]。 - - **use_neox_rotary_style** (可选|bool) - 当 use_neox_rotary_style 为 True, 每两个相邻的数字计算一次。 当 use_neox_rotary_style 为 False, 计算与前半段和后半段位置相对应的数字。 默认值为 True。 - - **time_major** (可选|bool) - 指定输入张量的时间维度是否为第一个维度。 如果为 True，则输入张量的形状应为 [seq_len, batch_size, num_heads, head_dim]。 如果为 False，则输入张量的形状应为 [batch_size, seq_len, num_heads, head_dim] 。 默认值为 False。 - - **rotary_emb_base** (可选|float) - 计算旋转角使用的底数。 默认值为 10000.0。 + - **q** (Tensor) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 q 的形状必须是 [batch_size, seq_len, num_heads, head_dim] 或 [seq_len, batch_size, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 + - **k** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 k 的形状必须是 [batch_size, seq_len, num_heads, head_dim] 或 [seq_len, batch_size, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 + - **v** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 v 的形状必须是 [batch_size, seq_len, num_heads, head_dim] 或 [seq_len, batch_size, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 + - **sin** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 sin 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 + - **cos** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 cos 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 + - **position_ids** (Tensor，可选) - 输入张量。 数据类型为 int64。 position_ids 的形状为[batch_size, seq_len]。 + - **use_neox_rotary_style** (bool，可选) - 当 use_neox_rotary_style 为 True, 每两个相邻的数字计算一次。 当 use_neox_rotary_style 为 False, 计算与前半段和后半段位置相对应的数字。 默认值为 True。 + - **time_major** (bool，可选) - 指定输入张量的时间维度是否为第一个维度。 如果为 True，则输入张量的形状应为 [seq_len, batch_size, num_heads, head_dim]。 如果为 False，则输入张量的形状应为 [batch_size, seq_len, num_heads, head_dim] 。 默认值为 False。 + - **rotary_emb_base** (float，可选) - 计算旋转角使用的底数。 默认值为 10000.0。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst b/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst index 1827e0726a8..ede7cd7c152 100644 --- a/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst @@ -3,18 +3,23 @@ masked_multihead_attention ------------------------------- -.. py:function:: paddle.incubate.nn.functional.masked_multihead_attention(x, cache_kv=None, bias=None, src_mask=None, cum_offsets=None, sequence_lengths=None, rotary_tensor=None, beam_cache_offset=None, qkv_out_scale=None, out_shift=None, out_smooth=None, seq_len=1, rotary_emb_dims=0, use_neox_rotary_style=False, compute_dtype='default', out_scale=- 1, quant_round_type=1, quant_max_bound=127.0, quant_min_bound=- 127.0) +.. py:function:: paddle.incubate.nn.functional.masked_multihead_attention(x, cache_kv=None, bias=None, src_mask=None, cum_offsets=None, sequence_lengths=None, rotary_tensor=None, beam_cache_offset=None, qkv_out_scale=None, out_shift=None, out_smooth=None, seq_len=1, rotary_emb_dims=0, use_neox_rotary_style=False, compute_dtype='default', out_scale=-1, quant_round_type=1, quant_max_bound=127.0, quant_min_bound=-127.0) 用于文本摘要的蒙版多头注意力机制。 这是一个融合操作符，用于计算 Transformer 模型架构中的蒙版多头注意力。该操作符仅支持在 GPU 上运行。 +.. warning:: + + 此 API 自 Paddle 3.4.0 起已废弃，未来版本将移除。请改用 ``paddle.nn.functional.scaled_dot_product_attention``。 + 参数 :::::::::::: - **x** (Tensor) - 输入张量可以是 2-D 张量。其形状为 [batch_size, 3 * num_head * head_dim]。 - - **cache_kvs** (list(Tensor)|tuple(Tensor)) - 生成模型的缓存结构张量。其形状为 [2, batch_size, num_head, max_seq_len, head_dim]。 - - **bias** (Tensor，可选) - 偏置张量。其形状为 [3, num_head, head_dim]。 + - **cache_kv** (Tensor，可选) - 生成模型的缓存结构张量。其形状为 [2, batch_size, num_head, max_seq_len, head_dim]。 + - **bias** (Tensor) - 偏置张量。其形状为 [3, num_head, head_dim]。 - **src_mask** (Tensor，可选) - 源掩码张量。其形状为 [batch_size, 1, 1, sequence_length]。 + - **cum_offsets** (Tensor，可选) - 从填充数据到去填充数据的累积偏移量。 - **sequence_lengths** (Tensor，可选) - 序列长度张量，用于索引输入。其形状为 [batch_size, 1]。 - **rotary_tensor** (Tensor，可选) - 旋转张量。其数据类型必须为浮点型。其形状为 [batch_size, 1, 1, sequence_length, head_dim]。 - **beam_cache_offset** (Tensor，可选) - Beam 缓存偏移张量。其形状为 [batch_size, beam_size, max_seq_len + max_dec_len]。 @@ -22,17 +27,17 @@ masked_multihead_attention - **out_shift** (Tensor，可选) - 量化中使用的 out_shift 张量。 - **out_smooth** (Tensor，可选) - 量化中使用的 out_smooth 张量。 - **seq_len** (int，可选) - 序列长度，用于获取输入长度。默认为 1。 - - **rotary_emb_dims** (int，可选) - 旋转嵌入维度。默认为 1。 + - **rotary_emb_dims** (int，可选) - 旋转嵌入维度。默认为 0。 - **use_neox_rotary_style** (bool，可选) - 表示是否需要 neox_rotary_style 的标志。默认为 False。 - - **compute_dtype** (string) - 计算数据类型，用于表示输入数据类型。 - - **out_scale** (float，可选) - 量化中使用的 out_scale。默认为 1.0。 + - **compute_dtype** (string，可选) - 计算数据类型，用于表示输入数据类型。 + - **out_scale** (float，可选) - 量化中使用的 out_scale。默认为 -1。 - **quant_round_type** (int，可选) - 量化中使用的 quant_round_type。默认为 1。 - **quant_max_bound** (float，可选) - 量化中使用的 quant_max_bound。默认为 127.0。 - **quant_min_bound** (float，可选) - 量化中使用的 quant_min_bound。默认为 -127.0。 返回 :::::::::::: - - Tensor|tuple：如果 "beam_cache_offset_out" 不为 None，则返回元组 (output, cache_kvs_out, beam_cache_offset_out)，其中 output 是蒙版多头注意力层的输出，cache_kvs_out 与输入 ``cache_kvs`` 原地更新。如果 "beam_cache_offset_out" 为 None，则返回元组 (output, cache_kvs_out)。 + - Tensor|tuple：如果 ``beam_cache_offset_out`` 不为 None，则返回元组 ``(output, cache_kv_out, beam_cache_offset_out)``，其中 ``output`` 是蒙版多头注意力层的输出，``cache_kv_out`` 与输入 ``cache_kv`` 原地更新。如果 ``beam_cache_offset_out`` 为 None，则返回元组 ``(output, cache_kv_out)``。 形状 :::::::::::: diff --git a/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst b/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst index 0ab658442fe..61bec75d0cf 100644 --- a/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst +++ b/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst @@ -3,7 +3,10 @@ LBFGS ------------------------------- -.. py:class:: paddle.incubate.optimizer.LBFGS(lr=1.0, max_iter=20, max_eval=None, tolerance_grad=1e-07, tolerance_change=1e-09, history_size=100, line_search_fn=None, parameters=None, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.incubate.optimizer.LBFGS(learning_rate=1.0, max_iter=20, max_eval=None, tolerance_grad=1e-07, tolerance_change=1e-09, history_size=100, line_search_fn=None, parameters=None, weight_decay=None, grad_clip=None, name=None) + +.. warning:: + 此 API 自 Paddle 2.5.0 起已废弃，未来版本将移除。请改用 ``paddle.optimizer.LBFGS``。 ``LBFGS`` 使用 L-BFGS 方法对参数进行优化更新，使得 loss 值最小。 @@ -27,14 +30,14 @@ LBFGS 具体原理参考书籍 Jorge Nocedal, Stephen J. Wright, Numerical Optim 参数 ::::::::: - - **lr** (float，可选) - 学习率，用于参数更新的计算，默认值：1.0。 - - **max_iter** (Scalar，可选) - 每个优化单步的最大迭代次数，默认值：20。 - - **max_eval** (Scalar，可选) - 每次优化单步中函数计算的最大数量，默认值：max_iter * 1.25。 - - **tolerance_grad** (float，可选) - 当梯度的范数小于该值时，终止迭代。当前使用正无穷范数。默认值：1e-5。 + - **learning_rate** (float，可选) - 学习率，用于参数更新的计算，默认值：1.0。 + - **max_iter** (int，可选) - 每个优化单步的最大迭代次数，默认值：20。 + - **max_eval** (int，可选) - 每次优化单步中函数计算的最大数量，默认值：max_iter * 1.25。 + - **tolerance_grad** (float，可选) - 当梯度的范数小于该值时，终止迭代。当前使用正无穷范数。默认值：1e-7。 - **tolerance_change** (float，可选) - 当函数值/x 值/其他参数 两次迭代的改变量小于该值时，终止迭代。默认值：1e-9。 - - **history_size** (Scalar，可选) - 指定储存的向量对{si,yi}数量。默认值：100。 - - **line_search_fn** (str，可选) - 指定要使用的线搜索方法，目前支持值为'strong wolfe'方法。默认值：'None'。 - - **parameters** (list，可选) - 指定优化器需要优化的参数，在动态图模式下必须提供该参数。默认值：None。 + - **history_size** (int，可选) - 指定储存的向量对{si,yi}数量。默认值：100。 + - **line_search_fn** (str，可选) - 指定要使用的线搜索方法，目前支持值为'strong wolfe'方法。默认值：None。 + - **parameters** (list|tuple，可选) - 指定优化器需要优化的参数，在动态图模式下必须提供该参数。默认值：None。 - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 diff --git a/docs/api/paddle/incubate/segment_max_cn.rst b/docs/api/paddle/incubate/segment_max_cn.rst index 055880474b7..18f0a7427c5 100644 --- a/docs/api/paddle/incubate/segment_max_cn.rst +++ b/docs/api/paddle/incubate/segment_max_cn.rst @@ -3,8 +3,10 @@ segment_max ------------------------------- -.. py:function:: paddle.incubate.segment_max((data, segment_ids, name=None) +.. py:function:: paddle.incubate.segment_max(data, segment_ids, name=None) +.. warning:: + 此 API 自 Paddle 2.4.0 起已废弃，未来版本将移除。请改用 ``paddle.geometric.segment_max``。 分段求最大值函数。 @@ -20,7 +22,7 @@ segment_max 参数 ::::::::: - - **data** (Tensor) - Tensor，数据类型为 float32、float64。 + - **data** (Tensor) - Tensor，数据类型为 float32、float64、int32、int64。 - **segment_ids** (Tensor) - 一维 Tensor，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/incubate/segment_min_cn.rst b/docs/api/paddle/incubate/segment_min_cn.rst index f550ef2910d..0cd3078b6d8 100644 --- a/docs/api/paddle/incubate/segment_min_cn.rst +++ b/docs/api/paddle/incubate/segment_min_cn.rst @@ -3,8 +3,10 @@ segment_min ------------------------------- -.. py:function:: paddle.incubate.segment_min((data, segment_ids, name=None) +.. py:function:: paddle.incubate.segment_min(data, segment_ids, name=None) +.. warning:: + 此 API 自 Paddle 2.4.0 起已废弃，未来版本将移除。请改用 ``paddle.geometric.segment_min``。 分段求最小值函数。 @@ -20,7 +22,7 @@ segment_min 参数 ::::::::: - - **data** (Tensor) - Tensor，数据类型为 float32、float64。 + - **data** (Tensor) - Tensor，数据类型为 float32、float64、int32、int64。 - **segment_ids** (Tensor) - 一维 Tensor，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/incubate/segment_sum_cn.rst b/docs/api/paddle/incubate/segment_sum_cn.rst index b1d20c8e4f4..5f2e2c45eac 100644 --- a/docs/api/paddle/incubate/segment_sum_cn.rst +++ b/docs/api/paddle/incubate/segment_sum_cn.rst @@ -3,8 +3,10 @@ segment_sum ------------------------------- -.. py:function:: paddle.incubate.segment_sum((data, segment_ids, name=None) +.. py:function:: paddle.incubate.segment_sum(data, segment_ids, name=None) +.. warning:: + 此 API 自 Paddle 2.4.0 起已废弃，未来版本将移除。请改用 ``paddle.geometric.segment_sum``。 分段求和函数。 @@ -21,7 +23,7 @@ segment_sum 参数 ::::::::: - - **data** (Tensor) - Tensor，数据类型为 float32、float64。 + - **data** (Tensor) - Tensor，数据类型为 float32、float64、int32、int64。 - **segment_ids** (Tensor) - 一维 Tensor，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 From c9e8874b2a0e22e5d573ec05536931ffe6c5ffcb Mon Sep 17 00:00:00 2001 From: manfredss Date: Fri, 14 Aug 2026 17:34:14 +0800 Subject: [PATCH 14/18] add 12 more apis --- .../paddle/static/IpuCompiledProgram_cn.rst | 6 ++--- docs/api/paddle/static/append_backward_cn.rst | 13 ++++++---- docs/api/paddle/static/nn/batch_norm_cn.rst | 24 +++++++++---------- .../paddle/static/nn/sparse_embedding_cn.rst | 9 +++---- .../paddle/static/normalize_program_cn.rst | 6 +++-- docs/api/paddle/take_along_axis_cn.rst | 6 ++++- .../cpp_extension/get_build_directory_cn.rst | 9 +++++-- .../paddle/utils/cpp_extension/load_cn.rst | 5 ++-- .../paddle/utils/data/default_collate_cn.rst | 14 +++++++++-- .../api/paddle/utils/data/random_split_cn.rst | 16 +++++++++++-- docs/api/paddle/utils/deprecated_cn.rst | 9 +++---- .../paddle/utils/unique_name/switch_cn.rst | 7 +++--- 12 files changed, 82 insertions(+), 42 deletions(-) diff --git a/docs/api/paddle/static/IpuCompiledProgram_cn.rst b/docs/api/paddle/static/IpuCompiledProgram_cn.rst index 12ba0eb556a..d9450f1275e 100644 --- a/docs/api/paddle/static/IpuCompiledProgram_cn.rst +++ b/docs/api/paddle/static/IpuCompiledProgram_cn.rst @@ -4,7 +4,7 @@ IpuCompiledProgram ------------------------------- -.. py:class:: paddle.static.IpuCompiledProgram(program, scope=None, ipu_strategy=None) +.. py:class:: paddle.static.IpuCompiledProgram(program=None, scope=None, ipu_strategy=None) IpuCompiledProgram 将输入的 Program 转换和优化成 IPU 所需要的形式，例如：前向图提取、计算图转化、无用的 scale 算子删除等。 @@ -26,8 +26,8 @@ COPY-FROM: paddle.static.IpuCompiledProgram 方法 :::::::::::: -compile(self, feed_list, fetch_list) -''''''''' +compile(feed_list, fetch_list) +'''''''''''''''''''''''''''''''''''''' 将 Program 进行编译，以便在 ipu 上运行。用户可以通过 ``feed_list`` 、``fetch_list`` 传入计算图输入和输出的名字。 diff --git a/docs/api/paddle/static/append_backward_cn.rst b/docs/api/paddle/static/append_backward_cn.rst index 6ea55ee1cb7..a2acf222514 100644 --- a/docs/api/paddle/static/append_backward_cn.rst +++ b/docs/api/paddle/static/append_backward_cn.rst @@ -4,7 +4,7 @@ append_backward ------------------------------- -.. py:function:: paddle.static.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None) +.. py:function:: paddle.static.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None, checkpoints=None, distop_context=None) @@ -20,13 +20,16 @@ append_backward :::::::::::: - **loss** (Tensor) - 表示网络损失的 Tensor 。 - - **parameter_list** （list [Tensor|str]，可选）- 指定优化器需要更新的参数或参数名称列表。如果为 ``None``，则将更新所有参数。默认值为 ``None``。 - - **no_grad_set** （set [Tensor|str]，可选）- 在 ``block0`` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 Tensor 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。 - - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度 OP 添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数：:ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。``context`` 是一个映射，其键是梯度 Tensor 名，值是对应的原始 Tensor。除此之外，``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__``，值是刚刚触发可调用对象的梯度 OP 的 ``op_desc``。默认值为 ``None``。 + - **parameter_list** (list[Tensor|str]|tuple[Tensor|str]，可选) - 指定优化器需要更新的参数或参数名称列表。如果为 ``None``，则将更新所有参数。默认值为 ``None``。 + - **no_grad_set** (set[Tensor|str]，可选) - 在 ``block0`` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 名称集合。所有 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的 Tensor 名称都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认集合中。默认值为 ``None``。 + - **callbacks** (list[callable object]|tuple[callable object]，可选) - 回调函数列表或元组。用于在反向传播构建中执行一些自定义作业。每次将新的梯度 OP 添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数：:ref:`api_guide_Block` 和 ``context``。:ref:`api_guide_Block` 是将被添加到新梯度算子的块。``context`` 是一个映射，其键是梯度 Tensor 名，值是对应的原始 Tensor。除此之外，``context`` 还有另一个特殊的键值对：键是字符串 ``__current_op_desc__``，值是刚刚触发可调用对象的梯度 OP 的 ``op_desc``。默认值为 ``None``。该参数在 PIR 模式中已弃用。 + - **checkpoints** (list[Tensor]|None，可选) - 检查点 Tensor 列表。默认值为 None。 + - **distop_context** (DistributedContext|None，可选) - 分布式算子上下文。默认值为 None。 返回 :::::::::::: - list[(Tensor , Tensor)]，参数及其梯度 Tensor 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 Tensor 。 + + 当 ``checkpoints`` 为 None 或空列表时，返回 list[(Tensor, Tensor)]，即参数及其梯度 Tensor 的元组列表。元组的第一个值为参数，第二个值为该参数的梯度 Tensor。当传入非空 ``checkpoints`` 时，返回 ``(params_and_grads, checkpoint_names)``，其中 ``checkpoint_names`` 为检查点名称列表。 代码示例 :::::::::::: diff --git a/docs/api/paddle/static/nn/batch_norm_cn.rst b/docs/api/paddle/static/nn/batch_norm_cn.rst index d018ba31276..c1e0e005de2 100644 --- a/docs/api/paddle/static/nn/batch_norm_cn.rst +++ b/docs/api/paddle/static/nn/batch_norm_cn.rst @@ -4,7 +4,7 @@ batch_norm ------------------------------- -.. py:function:: paddle.static.nn.batch_norm(input, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False, use_global_stats=False) +.. py:function:: paddle.static.nn.batch_norm(input, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=True, use_global_stats=False) @@ -49,19 +49,19 @@ moving_mean 和 moving_var 是训练过程中统计得到的全局均值和方 :::::::::::: - **input** (Tensor) - batch_norm 算子的输入特征，是一个 Tensor 类型，输入维度可以是 2, 3, 4, 5。数据类型：float16, float32, float64。 - - **act** （string）- 激活函数类型，可以是 leaky_realu、relu、prelu 等。默认：None。 - - **is_test** （bool） - 指示它是否在测试阶段，非训练阶段使用训练过程中统计到的全局均值和全局方差。默认：False。 - - **momentum** （float|Tensor）- 此值用于计算 moving_mean 和 moving_var，是一个 float 类型或者一个 shape 为[1]，数据类型为 float32 的 Tensor 类型。更新公式为：:math:`moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)` ， :math:`moving\_var = moving\_var * momentum + new\_var * (1. - momentum)`，默认：0.9。 - - **epsilon** （float）- 加在分母上为了数值稳定的值。默认：1e-5。 + - **act** (string) - 激活函数类型，可以是 linear、relu、prelu 等。默认：None。 + - **is_test** (bool) - 指示它是否在测试阶段，非训练阶段使用训练过程中统计到的全局均值和全局方差。默认：False。 + - **momentum** (float|Tensor) - 此值用于计算 moving_mean 和 moving_var，是一个 float 类型或者一个 shape 为 ``[]`` 的 0-D、数据类型为 float32 的 Tensor。更新公式为：:math:`moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)` ， :math:`moving\_var = moving\_var * momentum + new\_var * (1. - momentum)`，默认：0.9。 + - **epsilon** (float) - 加在分母上为了数值稳定的值。默认：1e-5。 - **param_attr** (ParamAttr|None)：指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。batch_norm 算子默认的权重初始化是 1.0。 - - **bias_attr** （ParamAttr|None）- 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。batch_norm 算子默认的偏置初始化是 0.0。 - - **data_layout** （string) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"。 - - **in_place** （bool）- batch_norm 的输出复用输入的 tensor，可以节省显存。默认：False。 + - **bias_attr** (ParamAttr|None) - 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。batch_norm 算子默认的偏置初始化是 0.0。 + - **data_layout** (string) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"。 + - **in_place** (bool) - batch_norm 的输出复用输入的 tensor，可以节省显存。默认：False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **moving_mean_name** （string）- moving_mean 的名称，存储全局均值。如果将其设置为 None, ``batch_norm`` 将随机命名全局均值；否则，``batch_norm`` 将命名全局均值为 ``moving_mean_name``。默认：None。 - - **moving_variance_name** （string）- moving_variance 的名称，存储全局变量。如果将其设置为 None, ``batch_norm`` 将随机命名全局方差；否则，``batch_norm`` 将命名全局方差为 ``moving_variance_name``。默认：None。 - - **do_model_average_for_mean_and_var** （bool，默认 False）- 是否为 mean 和 variance 做模型均值。 - - **use_global_stats** （bool） – 是否使用全局均值和方差。在预测或测试模式下，将 use_global_stats 设置为 true 或将 is_test 设置为 true，并且行为是等效的。在训练模式中，当设置 use_global_stats 为 True 时，在训练期间也使用全局均值和方差。默认：False。 + - **moving_mean_name** (string) - moving_mean 的名称，存储全局均值。如果将其设置为 None, ``batch_norm`` 将随机命名全局均值；否则，``batch_norm`` 将命名全局均值为 ``moving_mean_name``。默认：None。 + - **moving_variance_name** (string) - moving_variance 的名称，存储全局变量。如果将其设置为 None, ``batch_norm`` 将随机命名全局方差；否则，``batch_norm`` 将命名全局方差为 ``moving_variance_name``。默认：None。 + - **do_model_average_for_mean_and_var** (bool，默认 True) - 是否为 mean 和 variance 做模型均值。 + - **use_global_stats** (bool) - 是否使用全局均值和方差。在预测或测试模式下，将 use_global_stats 设置为 true 或将 is_test 设置为 true，并且行为是等效的。在训练模式中，当设置 use_global_stats 为 True 时，在训练期间也使用全局均值和方差。默认：False。 返回 :::::::::::: diff --git a/docs/api/paddle/static/nn/sparse_embedding_cn.rst b/docs/api/paddle/static/nn/sparse_embedding_cn.rst index 2c684d1ae10..a643a650cff 100644 --- a/docs/api/paddle/static/nn/sparse_embedding_cn.rst +++ b/docs/api/paddle/static/nn/sparse_embedding_cn.rst @@ -4,7 +4,7 @@ sparse_embedding ------------------------------- -.. py:function:: paddle.static.nn.sparse_embedding(input, size, padding_idx=None, is_test=False, entry=None, table_class="CommonSparseTable", param_attr=None, dtype='float32') +.. py:function:: paddle.static.nn.sparse_embedding(input, size, padding_idx=None, is_test=False, entry=None, table_class="MemorySparseTable", param_attr=None, dtype='float32', slot=None) 在飞桨参数服务器模式的大规模稀疏训练中作为 embedding lookup 层的算子，而不是使用 paddle.nn.functional.embedding。 @@ -62,11 +62,12 @@ sparse_embedding - **input** (Variable) - 存储 id 信息的 Tensor，数据类型必须为：int64，输入的 shape 最后一维须为 1。input 中的 id 必须满足 ``0 <= id < size[0]`` 。 - **size** (tuple|list) - embedding 矩阵的维度(vocab_size，emb_size)。必须包含两个元素，第一个元素为 vocab_size(词表大小)，第二个为 emb_size（embedding 层维度）。大规模稀疏场景下，参数规模初始为 0，会随着训练的进行逐步扩展，因此如果 vocab_size 暂时无用，其值可以为任意整数，emb_size 则为词嵌入权重参数的维度配置。 - **padding_idx** (int|long|None，可选) - padding_idx 需在区间 ``[-vocab_size, vocab_size)`` ，否则不生效， ``padding_idx < 0`` 时，padding_idx 会被改成 ``vocab_size + padding_idx`` ，input 中等于 padding_index 的 id 对应的 embedding 信息会被设置为 0，且这部分填充数据在训练时将不会被更新。如果为 None，不作处理，默认为 None。 - - **is_test** (bool，可选) - 表示训练/预测模式。在预测模式(is_test=False)下，遇到不存在的特征，不会初始化及创建，会直接以 0 填充后返回。默认值为 False。 + - **is_test** (bool，可选) - 表示训练/预测模式。在预测模式(is_test=True)下，遇到不存在的特征，不会初始化及创建，会直接以 0 填充后返回。默认值为 False。 - **entry** (str，可选) - 准入策略配置，目前支持概率准入 ProbabilityEntry、频次准入 CountFilterEntry 和曝光点击准入 ShowClickEntry。默认为 None。 - - **table_class** (str，可选) - 稀疏表的类型，其值可以为 CommonSparseTable、SSDSparseTable 和 MemorySparseTable。默认为 CommonSparseTable。 + - **table_class** (str，可选) - 稀疏表的类型，其值可以为 CommonSparseTable、SSDSparseTable 和 MemorySparseTable。默认为 MemorySparseTable。 - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为 numpy 数据格式，且保证本地词向量的 shape 和 embedding 的 ``size`` 参数一致，然后使用 :ref:`cn_api_paddle_to_tensor` 进行初始化，即可实现加载自定义或预训练的词向量。 - - **dtype** (str) - 输出 Tensor 的数据类型，数据类型必须为：float32 或 float64，默认为 float32。 + - **dtype** (str，可选) - 输出 Tensor 的数据类型，数据类型必须为：float32 或 float64，默认为 float32。 + - **slot** (int|None，可选) - 稀疏查找表使用的 slot 属性。为 None 时使用 0。默认值为 None。 返回 :::::::: diff --git a/docs/api/paddle/static/normalize_program_cn.rst b/docs/api/paddle/static/normalize_program_cn.rst index 5f726a4cd3a..e6d83705907 100644 --- a/docs/api/paddle/static/normalize_program_cn.rst +++ b/docs/api/paddle/static/normalize_program_cn.rst @@ -4,7 +4,7 @@ normalize_program ------------------------------- -.. py:function:: paddle.static.normalize_program(program, feed_vars, fetch_vars) +.. py:function:: paddle.static.normalize_program(program, feed_vars, fetch_vars, **kwargs) @@ -14,9 +14,11 @@ normalize_program 参数 :::::::::::: - - **program** - 指定想要优化的 program。 + - **program** (Program) - 指定想要优化的 program。 - **feed_vars** (Variable | list[Variable]) – 模型的输入变量。 - **fetch_vars** (Variable | list[Variable]) – 模型的输出变量。 + - **kwargs** - 支持键 ``skip_prune_program``。 + - **skip_prune_program** (bool，可选) - 是否跳过 program 裁剪。默认值为 False。 返回 :::::::::::: diff --git a/docs/api/paddle/take_along_axis_cn.rst b/docs/api/paddle/take_along_axis_cn.rst index 420f252d370..bd3846a9691 100644 --- a/docs/api/paddle/take_along_axis_cn.rst +++ b/docs/api/paddle/take_along_axis_cn.rst @@ -3,7 +3,7 @@ take_along_axis ------------------------------- -.. py:function:: paddle.take_along_axis(arr, indices, axis, broadcast=True) +.. py:function:: paddle.take_along_axis(arr, indices, axis, broadcast=True, *, out=None) 基于输入索引矩阵，沿着指定 axis 从 arr 矩阵里选取 1d 切片。索引矩阵必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。 @@ -20,6 +20,10 @@ take_along_axis 别名： ``dim`` - **broadcast** (bool，可选) - 是否广播 ``index`` 矩阵，默认为 ``True``。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst b/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst index 693ddb63354..c24f17fe1de 100644 --- a/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst +++ b/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst @@ -3,9 +3,14 @@ get_build_directory ------------------------------- -.. py:function:: paddle.utils.cpp_extension.get_build_directory() +.. py:function:: paddle.utils.cpp_extension.get_build_directory(verbose=False) -此接口返回编译自定义 OP 时生成动态链接库所在的 build 目录路径。此目录可以通过 ``export PADDLE_EXTENSION_DIR=XXX`` 来设置。若未设定，则默认使用 ``~/.cache/paddle_extension`` 作为 build 目录。 +此接口返回编译自定义 OP 时生成动态链接库所在的 build 目录路径。此目录可以通过 ``export PADDLE_EXTENSION_DIR=XXX`` 来设置。若未设定，则默认使用 ``~/.cache/paddle_extensions`` 作为 build 目录。 + +参数 +:::::::::::: + + - **verbose** (bool，可选) - 当未设置 ``PADDLE_EXTENSION_DIR`` 时，是否打印所使用的默认目录信息。默认值为 False。 返回 diff --git a/docs/api/paddle/utils/cpp_extension/load_cn.rst b/docs/api/paddle/utils/cpp_extension/load_cn.rst index e76e16557c4..734f78a0a2f 100644 --- a/docs/api/paddle/utils/cpp_extension/load_cn.rst +++ b/docs/api/paddle/utils/cpp_extension/load_cn.rst @@ -3,7 +3,7 @@ load ------------------------------- -.. py:function:: paddle.utils.cpp_extension.load(name, sources, extra_cxx_cflags=None, extra_cuda_cflags=None, extra_ldflags=None, extra_include_paths=None, build_directory=None, verbose=False) +.. py:function:: paddle.utils.cpp_extension.load(name, sources, extra_cxx_cflags=None, extra_cuda_cflags=None, extra_ldflags=None, extra_include_paths=None, extra_library_paths=None, build_directory=None, verbose=False) 此接口将即时编译（Just-In-Time）传入的自定义 OP 对应的 cpp 和 cuda 源码文件，返回一个包含自定义算子 API 的 ``Module`` 对象。 @@ -49,8 +49,9 @@ load - **extra_cuda_cflags** (list[str]，可选) - 用于指定编译 cuda 源文件时额外的编译选项。默认情况下，Paddle 框架相关的必要选项均已被隐式地包含；``nvcc`` 相关的编译选项请参考：`CUDA Compiler Driver NVCC `_ 。默认值为 None 。 - **extra_ldflags** (list[str]，可选) - 用于指定编译自定义 OP 时额外的链接选项。GCC 支持的链接选项请参考：`GCC Link Options `_ 。默认值为 None 。 - **extra_include_paths** (list[str]，可选) - 用于指定编译 cpp 或 cuda 源文件时，额外的头文件搜索目录。默认情况下，Paddle 框架相关头文件所在目录 ``site-packages/paddle/include`` 已被隐式地包含。默认值为 None 。 + - **extra_library_paths** (list[str]，可选) - 用于指定编译自定义 OP 时额外的库文件搜索目录。默认情况下，Paddle 框架相关库文件所在目录 ``site-packages/paddle/libs`` 已被隐式地包含。默认值为 None 。 - **build_directory** (str，可选) - 用于指定存放生成动态链接库的目录。若为 None，则会使用环境变量 ``PADDLE_EXTENSION_DIR`` 的值作为默认的存放目录。可使用 :ref:`cn_api_paddle_utils_cpp_extension_get_build_directory` 接口查看当前的目录设置。默认值为 None 。 - - **verbose** (str，可选) - 用于指定是否需要输出编译过程中的日志信息，默认为 False。 + - **verbose** (bool，可选) - 用于指定是否需要输出编译过程中的日志信息，默认为 False。 返回 :::::::::::: diff --git a/docs/api/paddle/utils/data/default_collate_cn.rst b/docs/api/paddle/utils/data/default_collate_cn.rst index 2b7c5edadf2..148972290c9 100644 --- a/docs/api/paddle/utils/data/default_collate_cn.rst +++ b/docs/api/paddle/utils/data/default_collate_cn.rst @@ -3,6 +3,16 @@ default_collate ------------------------------- -.. py:function:: paddle.utils.data.default_collate() +.. py:function:: paddle.utils.data.default_collate(batch) -``paddle.io.dataloader.collate.default_collate_fn`` 的别名，请参考 :ref:`cn_api_paddle_io_DataLoader`。 +``paddle.io.dataloader.collate.default_collate_fn`` 的别名。该函数接收样本数据组成的列表，递归处理其中的列表、字典、字符串、数值、NumPy 数组和 Tensor，并沿第 0 维堆叠数值、NumPy 数组和 Tensor。请参考 :ref:`cn_api_paddle_io_DataLoader`。 + +参数 +::::::::: + + - **batch** (list) - 样本数据组成的列表。 + +返回 +::::::::: + +批处理后的数据；输入中的数值、NumPy 数组和 paddle.Tensor 会被堆叠为 batch 数据。 diff --git a/docs/api/paddle/utils/data/random_split_cn.rst b/docs/api/paddle/utils/data/random_split_cn.rst index de45cf0badb..9cda4c97dfd 100644 --- a/docs/api/paddle/utils/data/random_split_cn.rst +++ b/docs/api/paddle/utils/data/random_split_cn.rst @@ -3,6 +3,18 @@ random_split ------------------------------- -.. py:function:: paddle.utils.data.random_split() +.. py:function:: paddle.utils.data.random_split(dataset, lengths, generator=None) -``paddle.io.random_split`` 的别名，请参考 :ref:`cn_api_paddle_io_random_split`。 +``paddle.io.random_split`` 的别名。将数据集随机划分为给定长度的互不重叠的新数据集。 + +参数 +::::::::: + + - **dataset** (Dataset) - 要划分的数据集。 + - **lengths** (Sequence) - 各划分的长度或比例。 + - **generator** (Generator，可选) - 用于随机排列的生成器。默认值为 None，此时使用 ``manual_seed()`` 中的默认生成器。 + +返回 +::::::::: + +list[Subset]，原始数据集的互不重叠子数据集列表。 diff --git a/docs/api/paddle/utils/deprecated_cn.rst b/docs/api/paddle/utils/deprecated_cn.rst index af7dfaab988..ecf405fc96c 100644 --- a/docs/api/paddle/utils/deprecated_cn.rst +++ b/docs/api/paddle/utils/deprecated_cn.rst @@ -3,7 +3,7 @@ deprecated ------------------------------- -.. py:function:: paddle.utils.deprecated(update_to="", since="", reason="") +.. py:function:: paddle.utils.deprecated(update_to="", since="", reason="", level=0) 对于即将废弃的 API 可以加入该装饰器，在调用对应 PaddlePaddle API 时，可以做如下两件事情： @@ -14,9 +14,10 @@ deprecated :::::::::::: - - **since** (str) - 即将废弃相对应的版本号。 - - **update_to** (str) - 新的 API 名称。 - - **reason** (str) - 即将废弃该 API 的原因。 + - **update_to** (str，可选) - 新的 API 名称。 + - **since** (str，可选) - 即将废弃相对应的版本号。 + - **reason** (str，可选) - 即将废弃该 API 的原因。 + - **level** (int，可选) - 废弃警告的日志级别，只能为 0、1 或 2。为 0 时不显示警告信息；为 1 时正常显示警告信息；为 2 时抛出 ``RuntimeError``。默认值为 0。 返回 :::::::::::: diff --git a/docs/api/paddle/utils/unique_name/switch_cn.rst b/docs/api/paddle/utils/unique_name/switch_cn.rst index 8fda0c235be..f31328e7783 100644 --- a/docs/api/paddle/utils/unique_name/switch_cn.rst +++ b/docs/api/paddle/utils/unique_name/switch_cn.rst @@ -3,7 +3,7 @@ switch ------------------------------- -.. py:function:: paddle.utils.unique_name.switch(new_generator=None) +.. py:function:: paddle.utils.unique_name.switch(new_generator=None, new_para_name_checker=None) @@ -13,11 +13,12 @@ switch 参数 :::::::::::: - - **new_generator** (UniqueNameGenerator，可选) - 要切换到的新命名空间，一般无需设置。缺省值为 None，表示切换到一个匿名的新命名空间。 + - **new_generator** (UniqueNameGenerator，可选) - 要切换到的新命名空间，一般无需设置。缺省值为 None，表示切换到一个匿名的新命名空间。 + - **new_para_name_checker** (DygraphParameterNameChecker，可选) - 要切换到的参数名称检查器，一般无需设置。缺省值为 None，表示切换到新的参数名称检查器。 返回 :::::::::::: -UniqueNameGenerator，先前的命名空间，一般无需操作该返回值。 +tuple[UniqueNameGenerator, DygraphParameterNameChecker]，分别为先前的命名空间和参数名称检查器，一般无需操作该返回值。 代码示例 :::::::::::: From 1e7401a6d54ac1cb82f40173e4f32d0c2c46b18c Mon Sep 17 00:00:00 2001 From: manfredss Date: Mon, 17 Aug 2026 16:22:41 +0800 Subject: [PATCH 15/18] add 13 apis --- docs/api/paddle/optimizer/lr/CyclicLR_cn.rst | 4 +- .../paddle/optimizer/lr/LinearWarmup_cn.rst | 4 +- .../optimizer/lr/NaturalExpDecay_cn.rst | 4 +- docs/api/paddle/optimizer/lr/NoamDecay_cn.rst | 2 +- docs/api/paddle/sparse/nn/BatchNorm_cn.rst | 12 +++--- docs/api/paddle/sparse/nn/Conv2D_cn.rst | 10 ++--- docs/api/paddle/sparse/nn/MaxPool3D_cn.rst | 16 +++---- docs/api/paddle/sparse/nn/SubmConv2D_cn.rst | 43 ++++++++----------- docs/api/paddle/sparse/nn/SubmConv3D_cn.rst | 25 +++++------ .../api/paddle/sparse/nn/SyncBatchNorm_cn.rst | 6 +-- .../paddle/sparse/nn/functional/conv3d_cn.rst | 26 +++++------ .../sparse/nn/functional/subm_conv3d_cn.rst | 26 ++++++----- docs/api/paddle/sparse/slice_cn.rst | 13 +++--- 13 files changed, 87 insertions(+), 104 deletions(-) diff --git a/docs/api/paddle/optimizer/lr/CyclicLR_cn.rst b/docs/api/paddle/optimizer/lr/CyclicLR_cn.rst index 65c73a7aff3..518b5aa2f28 100644 --- a/docs/api/paddle/optimizer/lr/CyclicLR_cn.rst +++ b/docs/api/paddle/optimizer/lr/CyclicLR_cn.rst @@ -22,9 +22,9 @@ CyclicLR - **max_learning_rate** (float) - 最大学习率，需要注意的是，实际的学习率由 ``base_learning_rate`` 与初始幅度的缩放求和而来，因此实际学习率可能达不到 ``max_learning_rate`` 。 - **step_size_up** (int) - 学习率从初始学习率增长到最大学习率所需步数。每个循环总的步长 ``step_size`` 由 ``step_size_up + step_size_down`` 定义，论文中建议将 ``step_size`` 设置为单个 epoch 中步长的 3 或 4 倍。 - **step_size_down** (int，可选) - 学习率从最大学习率下降到初始学习率所需步数。若未指定，则其值默认等于 ``step_size_up`` 。 - - **mode** (str，可选) - 可以是 triangular、triangular2 或者 exp_range，对应策略已在上文描述，当 scale_fn 被指定时时，该参数将被忽略。默认值为 triangular。 + - **mode** (str，可选) - 可以是 triangular、triangular2 或者 exp_range，对应策略已在上文描述，当 scale_fn 被指定时，该参数将被忽略。默认值为 triangular。 - **exp_gamma** (float，可选) - exp_range 缩放函数中的常量。默认值为 1.0。 - - **scale_fn** (function，可选) - 一个有且仅有单个参数的函数，且对于任意的输入 x，都必须满足 0 ≤ scale_fn(x) ≤ 1；如果该参数被指定，则会忽略 mode 参数。默认值为 ``False`` 。 + - **scale_fn** (function，可选) - 一个有且仅有单个参数的函数，且对于任意的输入 x，都必须满足 0 ≤ scale_fn(x) ≤ 1；如果该参数被指定，则会忽略 mode 参数。默认值为 ``None`` 。 - **scale_mode** (str，可选) - cycle 或者 iterations，表示缩放函数使用 cycle 数或 iterations 数作为输入。默认值为 cycle。 - **last_epoch** (int，可选) - 上一轮的轮数，重启训练时设置为上一轮的 epoch 数。默认值为 -1，则为初始学习率。 - **verbose** (bool，可选) - 如果是 ``True``，则在每一轮更新时在标准输出 ``stdout`` 输出一条信息。默认值为 ``False`` 。 diff --git a/docs/api/paddle/optimizer/lr/LinearWarmup_cn.rst b/docs/api/paddle/optimizer/lr/LinearWarmup_cn.rst index fbf8754ad37..41c491823fb 100644 --- a/docs/api/paddle/optimizer/lr/LinearWarmup_cn.rst +++ b/docs/api/paddle/optimizer/lr/LinearWarmup_cn.rst @@ -20,12 +20,12 @@ LinearWarmup lr = learning\_rate -其中 learning_rate 为热身之后的学习率，可以是 python 的 float 类型或者 ``_LRScheduler`` 的任意子类。 +其中 learning_rate 为热身之后的学习率，可以是 python 的 float 类型或者 ``LRScheduler`` 的任意子类。 参数 :::::::::::: - - **learning rate** (float|_LRScheduler) - 热启训练之后的学习率，可以是 python 的 float 类型或者 ``_LRScheduler`` 的任意子类。 + - **learning_rate** (float|LRScheduler) - 热启训练之后的学习率，可以是 python 的 float 类型或者 ``LRScheduler`` 的任意子类。 - **warmup_steps** (int) - 进行 warm up 过程的步数。 - **start_lr** (float) - warm up 的起始学习率。 - **end_lr** (float) - warm up 的最终学习率。 diff --git a/docs/api/paddle/optimizer/lr/NaturalExpDecay_cn.rst b/docs/api/paddle/optimizer/lr/NaturalExpDecay_cn.rst index 8b521b501bc..05957c0835b 100644 --- a/docs/api/paddle/optimizer/lr/NaturalExpDecay_cn.rst +++ b/docs/api/paddle/optimizer/lr/NaturalExpDecay_cn.rst @@ -3,7 +3,7 @@ NaturalExpDecay ------------------------------- -.. py:class:: paddle.optimizer.lr.NaturalExpDecay(learning_rate, gama, last_epoch=-1, verbose=False) +.. py:class:: paddle.optimizer.lr.NaturalExpDecay(learning_rate, gamma, last_epoch=-1, verbose=False) 该接口提供按自然指数衰减学习率的策略。 @@ -17,7 +17,7 @@ NaturalExpDecay :::::::::::: - **learning_rate** (float) - 初始学习率，数据类型为 Python float。 - - **gamma** (float) - 衰减率，gamma 应该大于 0.0，才能使学习率衰减。默认值为 0.1。 + - **gamma** (float) - 衰减率，gamma 应该大于 0.0，才能使学习率衰减。 - **last_epoch** (int，可选) - 上一轮的轮数，重启训练时设置为上一轮的 epoch 数。默认值为 -1，则为初始学习率。 - **verbose** (bool，可选) - 如果是 ``True``，则在每一轮更新时在标准输出 ``stdout`` 输出一条信息。默认值为 ``False`` 。 diff --git a/docs/api/paddle/optimizer/lr/NoamDecay_cn.rst b/docs/api/paddle/optimizer/lr/NoamDecay_cn.rst index 375144e0db8..07f4a970416 100644 --- a/docs/api/paddle/optimizer/lr/NoamDecay_cn.rst +++ b/docs/api/paddle/optimizer/lr/NoamDecay_cn.rst @@ -19,7 +19,7 @@ Noam 衰减的计算方式如下： 参数 :::::::::::: - - **d$_{model}$** (int) - 模型的输入、输出向量特征维度，为超参数。数据类型为 Python int。 + - **d_model** (int) - 模型的输入、输出向量特征维度，为超参数。数据类型为 Python int。 - **warmup_steps** (int) - 预热步数，为超参数。数据类型为 Python int。 - **learning_rate** (float) - 初始学习率，数据类型为 Python float。默认值为 1.0。 - **last_epoch** (int，可选) - 上一轮的轮数，重启训练时设置为上一轮的 epoch 数。默认值为 -1，则为初始学习率。 diff --git a/docs/api/paddle/sparse/nn/BatchNorm_cn.rst b/docs/api/paddle/sparse/nn/BatchNorm_cn.rst index b6bb6dc0215..6f50d2a3e0f 100644 --- a/docs/api/paddle/sparse/nn/BatchNorm_cn.rst +++ b/docs/api/paddle/sparse/nn/BatchNorm_cn.rst @@ -6,7 +6,7 @@ BatchNorm .. py:class:: paddle.sparse.nn.BatchNorm(num_features, momentum=0.9, epsilon=1e-05, weight_attr=None, bias_attr=None, data_format="NDHWC", use_global_stats=None, name=None) -构建稀疏 ``BatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。可以处理 4D SparseCooTensor ，实现了批归一化层（Batch Normalization Layer）的功能，可用作卷积和全连接操作的批归一化函数，根据当前批次数据按通道计算的均值和方差进行归一化。更多详情请参考： `Batch Normalization : Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ 。 +构建稀疏 ``BatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。可处理 NHWC 格式的 4-D 或 NDHWC 格式的 5-D SparseCooTensor，实现了批归一化层（Batch Normalization Layer）的功能，可用作卷积和全连接操作的批归一化函数，根据当前批次数据按通道计算的均值和方差进行归一化。更多详情请参考： `Batch Normalization : Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ 。 当 use_global_stats = False 时 :math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 是 minibatch 的统计数据。计算公式如下： @@ -43,9 +43,9 @@ BatchNorm - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - **weight_attr** (ParamAttr|bool，可选) - 指定权重参数属性的对象。如果为 False，则表示每个通道的伸缩固定为 1，不可改变。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。如果为 False，则表示每一个通道的偏移固定为 0，不可改变。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为“NCDHW"。默认值：“NCDHW”。 - - **use_global_stats** (bool，可选) – 指示是否使用全局均值和方差。在预测或测试模式下，将 ``use_global_stats`` 设置为 true 或将 ``is_test`` 设置为 true，这两种行为是等效的。在训练模式中，当设置 ``use_global_stats`` 为 True 时，在训练期间也将使用全局均值和方差。默认值：False。 + - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。如果为 False，则表示每一个通道的偏移固定为 0，不可改变。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为 ``"NDHWC"`` 或 ``"NHWC"``。默认值为 ``"NDHWC"``。 + - **use_global_stats** (bool|None，可选) – 指示是否使用全局均值和方差。若为 False，使用一个 mini-batch 的统计数据；若为 True，使用全局统计数据；若为 None，则在预测阶段使用全局统计数据、在训练阶段使用一个 mini-batch 的统计数据。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 @@ -56,8 +56,8 @@ BatchNorm 形状 :::::::::::: - - input：形状为（批大小，维度，高度，宽度，通道数）的 5-D SparseCooTensor。 - - output：和输入形状一样。 + - input：NDHWC 格式的 5-D 或 NHWC 格式的 4-D SparseCooTensor。 + - output：与输入具有相同形状和布局的 SparseCooTensor。 代码示例 :::::::::::: diff --git a/docs/api/paddle/sparse/nn/Conv2D_cn.rst b/docs/api/paddle/sparse/nn/Conv2D_cn.rst index 4e7dfac3aff..f0000ebe5b4 100644 --- a/docs/api/paddle/sparse/nn/Conv2D_cn.rst +++ b/docs/api/paddle/sparse/nn/Conv2D_cn.rst @@ -33,7 +33,7 @@ Conv2D - **in_channels** (int) - 输入图像的通道数。 - **out_channels** (int) - 由卷积操作产生的输出的通道数。 - **kernel_size** (int|list|tuple) - 卷积核大小。 - - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积沿着深度，高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 + - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积沿着高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 - **padding** (int|str|tuple|list，可选) - 填充大小。填充可以是以下形式之一： 1. 字符串 ['valid', 'same']。 @@ -43,12 +43,12 @@ Conv2D 5. 成对整数的列表或元组。形式为 [[pad_before, pad_after], [pad_before, pad_after], ...]。 注意，批量维度和通道维度也包括在内。每对整数对应输入的一个维度的填充量。批量维度和通道维度的填充应为 [0, 0] 或 (0, 0)。默认值为 0。 - - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值：1。 - - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 - - **padding_mode** (str，可选) - 填充模式。包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'``。默认值：``'zeros'`` 。 + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核中的元素沿着高和宽的空洞。如果为单个整数，表示高和宽的空洞都等于该整数。默认值：1。 + - **groups** (int，可选) - 卷积层的组数。当前仅支持 ``groups=1``。默认值：1。 + - **padding_mode** (str，可选) - 填充模式。当前仅支持 ``'zeros'``。默认值：``'zeros'`` 。 - **weight_attr** (ParamAttr，可选) - conv2d 的可学习参数/权重的参数属性。如果设置为 None 或 ParamAttr 的一个属性，conv2d 将创建 ParamAttr 作为 param_attr。如果设置为 None，则参数初始化为 :math:`Normal(0.0, std)`，:math:`std` 为 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}`。默认值为 None。 - **bias_attr** (ParamAttr|bool，可选) - conv2d 的偏置参数属性。如果设置为 False，则不会在输出单元中添加偏置。如果设置为 None 或 ParamAttr 的一个属性，conv2d 将创建 ParamAttr 作为 bias_attr。如果 bias_attr 的初始化器未设置，则偏置初始化为零。默认值为 None。 - - **data_format** (str，可选) - 指定输入的数据格式。可以是 "NCHW" 或 "NHWC"。目前仅支持 "NHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。默认值："NDHWC"。 当前只支持"NDHWC"。 + - **data_format** (str，可选) - 指定输入的数据格式。当前仅支持 "NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NHWC"。 属性 diff --git a/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst b/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst index 99391a3e7ff..62a0e0d6c8e 100644 --- a/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst +++ b/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst @@ -3,26 +3,26 @@ MaxPool3D ------------------------------- -.. py:class:: paddle.sparse.nn.MaxPool3D(kernel_size, stride=None, padding=0, ceil_mode=False, return_mask=False, data_format="NDHWC", name=None) +.. py:class:: paddle.sparse.nn.MaxPool3D(kernel_size, stride=None, padding=0, return_mask=False, ceil_mode=False, data_format="NDHWC", name=None) 构建 ``MaxPool3D`` 类的一个可调用对象，其将构建一个三维最大池化层，根据输入参数 ``kernel_size``, ``stride``, -``padding`` 等参数对稀疏输入特征做最大池化操作。 输入输出都是 "NDHWC" 格式，其中 N 是批大小， C 是特征的通道数， H 是特征的高， W 是特征的宽。 +``padding`` 等参数对稀疏输入特征做最大池化操作。输入输出都是 "NDHWC" 格式，其中 N 是批大小，C 是特征的通道数，D、H、W 分别是特征的深度、高和宽。 参数 ::::::::: - **kernel_size** (int|list|tuple) - 池化核大小。如果它是一个元组或列表，它必须包含三个整数值，(pool_size_Depth，pool_size_Height, pool_size_Width)。若为一个整数，则表示 D，H 和 W 维度上均为该值，比如若 kernel_size=2，则池化核大小为[2,2,2]。 - **stride** (int|list|tuple，可选) - 池化层的步长。如果它是一个元组或列表，它将包含三个整数，(pool_stride_Depth，pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 D, H 和 W 维度上 stride 均为该值。默认值为 None ，这时会使用 kernel_size 作为 stride 。 - - **padding** (str|int|list|tuple，可选) - 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 3 个整数值：[pad_depth, pad_height, pad_width]；(2)包含 6 个整数值：[pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 5 个二元组：当 data_format 为"NCDHW"时为[[0,0], [0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NDHWC"时为[[0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 D、H 和 W 维度上均为该值。默认值：0 。 - - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出高度和宽度。如果是 True ，则使用 ``ceil`` 计算输出形状的大小。默认为 False 。 - - **return_mask** (bool，可选) - 是否返回最大索引和输出。默认为 False 。 - - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。当前只支持："NDHWC" 。 + - **padding** (str|int|list|tuple，可选) - 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 3 个整数值：[pad_depth, pad_height, pad_width]；(2)包含 6 个整数值：[pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 5 个二元组：``[[0, 0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0, 0]]``。若为一个整数，则表示 D、H 和 W 维度上均为该值。默认值：0 。 + - **return_mask** (bool，可选) - 当前该参数不会传递给底层池化函数，调用时始终返回单个池化结果 Tensor。默认值为 False 。 + - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出深度、高度和宽度。如果是 True ，则使用 ``ceil`` 计算输出形状的大小。默认为 False 。 + - **data_format** (str，可选) - 输入和输出的数据格式。当前仅支持 "NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None 。 形状 ::::::::: - - **x** (Tensor)：默认形状为（批大小，通道数，长度，高度，宽度），即 NCDHW 格式的 5-D Tensor。其数据类型为 float16, float32, float64, int32 或 int64。 - - **output** (Tensor)：默认形状为（批大小，通道数，输出特征长度，输出特征高度，输出特征宽度），即 NCDHW 格式的 5-D Tensor。其数据类型与输入相同。 + - **x** (SparseCooTensor)：形状为 ``[N, D, H, W, C]`` 的 NDHWC 格式 5-D SparseCooTensor。数据类型为 float32 或 float64。 + - **output** (SparseCooTensor)：形状为 ``[N, D_out, H_out, W_out, C]`` 的 NDHWC 格式 5-D SparseCooTensor。其数据类型与输入相同。 返回 diff --git a/docs/api/paddle/sparse/nn/SubmConv2D_cn.rst b/docs/api/paddle/sparse/nn/SubmConv2D_cn.rst index f0e21f4775b..b28f08e33bf 100644 --- a/docs/api/paddle/sparse/nn/SubmConv2D_cn.rst +++ b/docs/api/paddle/sparse/nn/SubmConv2D_cn.rst @@ -3,14 +3,14 @@ SubmConv2D ------------------------------- -.. py:class:: paddle.sparse.nn.SubmConv2D(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', key=None, weight_attr=None, bias_attr=None, data_format='NHWC') +.. py:class:: paddle.sparse.nn.SubmConv2D(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', key=None, weight_attr=None, bias_attr=None, data_format='NHWC', backend=None) **子流形稀疏二维卷积层** 子流形稀疏二维卷积层(submanifold sparse convolution2d layer)根据输入计算输出，卷积核和步长、填充、空洞大小(dilations)一组参数。 输入(input)和输出(Output)是多维的稀疏张量(Sparse Coo Tensor)， 形状为 :math:`[N,H,W,C]` 其中 N 是批尺寸，C 是通道，H 是特征高度，W 是特征宽度。 -如果提供了 bias_attr，则添加偏置项到卷积的输出。 +如果提供了 ``bias_attr``，则添加偏置项到卷积的输出。 对于每一个输入 :math:`X`，方程是： .. math:: @@ -18,35 +18,28 @@ SubmConv2D 其中： - - :math:`X` : 输入值, NDHWC 格式的 Tencer。 - - :math:`W` : 卷积核值, NDHWC 格式的 Tencer。 + - :math:`X` : 输入值, NHWC 格式的 SparseCooTensor。 + - :math:`W` : 卷积核值, HWCM 格式的 Tensor。 - :math:`\\ast` : 子流形卷积运算, 参考论文: `Submanifold Sparse Convolutional Networks `_ 。 - - :math:`b` : 偏置值, 形状为[M]的 1-D Tencer。 + - :math:`b` : 偏置值, 形状为[M]的 1-D Tensor。 - :math:`Out` : 输出值, :math:`Out` 和 :math:`X` 的形状可能不同。 参数 :::::::::::: - - **in_channels** (int): - 输入图像的通道数。 - - **out_channels** (int): - 卷积操作产生的输出通道数。 - - **kernel_size** (int|list|tuple): - 卷积核的大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。 - - **stride** (int|list|tuple, 可选): - 步长大小。如果 stride 是一个列表/元组，它必须包含两个整数，(stride_H, stride_W)。否则, stride_H = stride_W = stride。默认值为 1。 - - **padding** (int|str|tuple|list, 可选): - 填充大小。应为以下几种格式之一； - - - (1) 如果它是一个字符串，可以是 "VALID" 或者 "SAME"，计算细节可参考上述 ``padding`` = "SAME" 或 ``padding`` = "VALID" 时的计算公式。 - - (2) 如果它是一个整数, 则代表它每个 Spartial 维度(depth, height, width) 被 ``padding`` 的大小填充为零。 - - (3) 一个 list[int] 或 tuple[int]，其长度是 Spartial 维度的数目，它包含每个 Spartial 维度每侧的填充量。它的形式为 [pad_d1, pad_d2, ...]。 - - (4) 一个 list[int] 或 tuple[int]，其长度为 2 * 部分维数。对于所有局部维度，它的形式为 [pad_before, pad_after, pad_before, pad_after, ...]。 - - (5) 一个整数对的列表或元组。它的形式为 [[pad_before, pad_after], [pad_before, pad_after], ...]。 - - 请注意，批维度和通道维度也包括在内。每对整数对应于输入维度的填充量。批维度和通道维度中的填充应为[0, 0]或者是(0, 0)默认值为 0。 - - **dilation** (int|list|tuple, 可选): - 空洞大小。如果 dilation 是列表或元组, 则它必须包含两个整数 (dilation_H, dilation_W)。否则, dilation_H = dilation_W = dilation。默认值为 1。 - - **groups** (int, 可选): - 二维卷积层的组号。根据 Alex Krizhevsky 的 Deep CNN 论文中的分组卷积:当 group = 2 时, 卷积核的前半部分仅连接到输入通道的前半部分, 而卷积核的后半部分仅连接到输入通道的后半部分。默认值为 1。 - - **padding_mode** (str, 可选): - ``'zeros'``, ``'reflect'``, ``'replicate'`` 或 ``'circular'``。 目前仅支持 ``'zeros'``。 - - **key** (str, 可选): - key 用于保存或使用相同的规则手册，规则手册的定义和作用是指 https://pdfs.semanticscholar.org/5125/a16039cabc6320c908a4764f32596e018ad3.pdf。默认值为 None。 - - **weight_attr** (ParamAttr, 可选): - conv2d 的可学习参数/权重的参数属性。如果设置为 None 或 ParamAttr 的一个属性，则 conv2d 将创建 ParamAttr 作为 param_attr。 如果设置为 None, 则参数初始化为 :math:`Normal(0.0, std)` , 并且 :math:`std` 是 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}` ,默认值为 None。 - - **bias_attr** (ParamAttr|bool, 可选): - conv2d 偏差的参数属性。如果设置为 False, 则不会向输出单位添加任何偏置。如果设置为 None 或 ParamAttr 的一个属性，则 conv2d 将创建 ParamAttr 作为 bias_attr。如果未设置 bias_attr 的初始值设定项,则偏置初始化为零。默认值为 None。 - - **data_format** (str, 可选): 指定输入布局的数据格式。它可以是 "NCHW" 或 "NHWC"。目前仅支持 "NHWC"。 + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 卷积操作产生的输出通道数。 + - **kernel_size** (int|list|tuple) - 卷积核的大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核的高和宽。如果为单个整数，表示卷积核的高和宽都等于该整数。 + - **stride** (int|list|tuple，可选) - 步长大小。如果 stride 是一个列表/元组，它必须包含两个整数，(stride_H, stride_W)。否则, stride_H = stride_W = stride。默认值为 1。 + - **padding** (int|str|tuple|list，可选) - 填充大小。可以是 ``"VALID"`` 或 ``"SAME"``；也可以是一个整数、包含两个整数的 ``[pad_height, pad_width]``、包含四个整数的 ``[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]``，或四个二元组 ``[[0, 0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0, 0]]``。若为一个整数，则高和宽方向均使用该值。默认值为 0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。如果 dilation 是列表或元组, 则它必须包含两个整数 (dilation_H, dilation_W)。否则, dilation_H = dilation_W = dilation。默认值为 1。 + - **groups** (int，可选) - 卷积层的组数。当前仅支持 ``groups=1``。默认值为 1。 + - **padding_mode** (str，可选) - 当前仅支持 ``'zeros'``。默认值为 ``'zeros'``。 + - **key** (str|None，可选) - key 用于保存或使用相同的规则手册，规则手册的定义和作用是指 https://pdfs.semanticscholar.org/5125/a16039cabc6320c908a4764f32596e018ad3.pdf。默认值为 None。 + - **weight_attr** (ParamAttr，可选) - conv2d 的可学习参数/权重的参数属性。如果设置为 None 或 ParamAttr 的一个属性，则 conv2d 将创建 ParamAttr 作为 param_attr。 如果设置为 None, 则参数初始化为 :math:`Normal(0.0, std)` , 并且 :math:`std` 是 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}` ,默认值为 None。 + - **bias_attr** (ParamAttr|bool，可选) - conv2d 偏差的参数属性。如果设置为 False, 则不会向输出单位添加任何偏置。如果设置为 None 或 ParamAttr 的一个属性，则 conv2d 将创建 ParamAttr 作为 bias_attr。如果未设置 bias_attr 的初始值设定项,则偏置初始化为零。默认值为 None。 + - **data_format** (str，可选) - 指定输入布局的数据格式。当前仅支持 "NHWC"。 + - **backend** (str，可选) - 指定稀疏卷积实现后端。可选值为 ``"igemm"`` 或 ``None``，默认值为 None。 属性 :::::::::::: diff --git a/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst b/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst index 8e761b859ee..74e64d15d89 100644 --- a/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst +++ b/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst @@ -3,12 +3,12 @@ SubmConv3D ------------------------------- -.. py:class:: paddle.sparse.nn.SubmConv3D(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', key=None, weight_attr=None, bias_attr=None, data_format="NDHWC") +.. py:class:: paddle.sparse.nn.SubmConv3D(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', key=None, weight_attr=None, bias_attr=None, data_format="NDHWC", backend=None) **子流形稀疏三维卷积层** 子流形稀疏三维卷积层（submanifold sparse convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 -NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 +NDHWC 格式的 5-D SparseCooTensor，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 对每个输入 X，有等式： @@ -18,11 +18,11 @@ NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 其中： - - :math:`X` ：输入值，NDHWC 格式的 5-D Tensor + - :math:`X` ：输入值，NDHWC 格式的 5-D SparseCooTensor - :math:`W` ：卷积核值，DHWCM 格式的 5-D Tensor - :math:`*` ：子流形稀疏卷积操作的定义参考论文：https://arxiv.org/abs/1706.01307 - :math:`b` ：偏置值，1-D Tensor，形为 ``[M]`` - - :math:`Out` ：输出值，NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + - :math:`Out` ：输出值，NDHWC 格式的 5-D SparseCooTensor，和 ``X`` 的形状可能不同 参数 :::::::::::: @@ -30,20 +30,17 @@ NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H - **in_channels** (int) - 输入图像的通道数。 - **out_channels** (int) - 由卷积操作产生的输出的通道数。 - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。 - - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积沿着深度，高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 - - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是 "VALID" 或者 "SAME" ，表示填充算法，计算细节可参考上述 ``padding`` = "SAME" 或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式： - - - (1)包含 5 个二元组：当 ``data_format`` 为 "NCDHW" 时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为 "NDHWC" 时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]； - - (2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]； - - (3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积沿着深度，高和宽的步长。如果为单个整数，表示沿着深度、高和宽的步长都等于该整数。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是 "VALID" 或者 "SAME"。如果它是一个元组或列表，可以有以下 3 种格式：(1)包含 5 个二元组：``[[0, 0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0, 0]]``；(2)包含 6 个整数值：``[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]``；(3)包含 3 个整数值：``[padding_depth, padding_height, padding_width]``。若为一个整数，则深度、高度和宽度方向均使用该值。默认值：0。 - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值：1。 - - **groups** (int，可选) - 三维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group = n ，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 - - **padding_mode** (str，可选) - 填充模式。包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'`` 。默认值：``'zeros'`` 。 - - **key** (str，可选) - 这个 key 是用来保存或者使用相同的 rulebook ，rulebook 的定义参考论文：https://pdfs.semanticscholar.org/5125/a16039cabc6320c908a4764f32596e018ad3.pdf。 默认是 None。 + - **groups** (int，可选) - 卷积层的组数。当前仅支持 ``groups=1``。默认值：1。 + - **padding_mode** (str，可选) - 填充模式。当前仅支持 ``'zeros'``。默认值：``'zeros'`` 。 + - **key** (str|None，可选) - 这个 key 是用来保存或者使用相同的 rulebook ，rulebook 的定义参考论文：https://pdfs.semanticscholar.org/5125/a16039cabc6320c908a4764f32596e018ad3.pdf。 默认是 None。 - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是 "NCDHW" 和 "NDHWC" 。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。默认值："NDHWC" 。 当前只支持 "NDHWC" 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致。当前仅支持 "NDHWC"，即 ``[batch_size, input_depth, input_height, input_width, input_channels]``。默认值："NDHWC" 。 + - **backend** (str，可选) - 指定稀疏卷积实现后端。可选值为 ``"igemm"`` 或 ``None``，默认值为 None。 属性 diff --git a/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst b/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst index 82b965b6a10..afeed6f7e97 100644 --- a/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst +++ b/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst @@ -3,7 +3,7 @@ SyncBatchNorm ------------------------------- -.. py:class:: paddle.sparse.nn.SyncBatchNorm(num_features, epsilon=1e-5, momentum=0.9, weight_attr=None, bias_attr=None, data_format='NCHW', name=None) +.. py:class:: paddle.sparse.nn.SyncBatchNorm(num_features, momentum=0.9, epsilon=1e-5, weight_attr=None, bias_attr=None, data_format='NCHW', name=None) 构建 ``SyncBatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。实现了跨卡 GPU 同步的批归一化(Cross-GPU Synchronized Batch Normalization Layer)的功能，可用在其他层（类似卷积层和全连接层）之后进行归一化操作。根据所有 GPU 同一批次的数据按照通道计算的均值和方差进行归一化。更多详情请参考：`Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ 。 @@ -42,11 +42,11 @@ SyncBatchNorm :::::::::::: - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 - - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - **weight_attr** (ParamAttr|bool，可选) - 指定权重参数属性的对象。如果设置为 ``False`` ，则表示本层没有可训练的权重参数。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。如果设置为 ``False`` ，则表示本层没有可训练的偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为“NCHW"。默认值：“NCHW”。 + - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为 “NCHW”。默认值：“NCHW”。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst b/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst index 6c8b789e604..626b1067f95 100644 --- a/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst +++ b/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst @@ -5,7 +5,7 @@ conv3d .. py:function:: paddle.sparse.nn.functional.conv3d(x, weight, bias=None, stride=1, padding=0, dilation=1, groups=1, data_format="NDHWC", name=None) -稀疏三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 NCDHW 或 NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 +稀疏三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出均为 NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。若提供 ``bias``，卷积计算会添加偏置项。 对每个输入 X ，有等式： @@ -15,11 +15,11 @@ conv3d 其中： - - :math:`X` ：输入值，NCDHW 或 NDHWC 格式的 5-D Tensor + - :math:`X` ：输入值，NDHWC 格式的 5-D SparseCooTensor - :math:`W` ：卷积核值，MCDHW 格式的 5-D Tensor - :math:`*` ：卷积操作 - :math:`b` ：偏置值，1-D Tensor，形为 ``[M]`` - - :math:`Out` ：输出值，NCDHW 或 NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + - :math:`Out` ：输出值，NDHWC 格式的 5-D SparseCooTensor，和 ``X`` 的形状可能不同 **示例** @@ -37,31 +37,25 @@ conv3d :::::::::::: - **x** (Tensor) - 输入是形状为 :math:`[N, D, H, W, C]` 的 5-D SparseCooTensor，N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度，数据类型为 float16, float32 或 float64 。 - - **weight** (Tensor) - 形状为 :math:`[kD, kH, kW, C/g, M]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kH 是卷积核的高度，kW 是卷积核的宽度。 + - **weight** (Tensor) - 形状为 :math:`[kD, kH, kW, C/g, M]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kD、kH、kW 分别是卷积核的深度、高度和宽度。 - **bias** (Tensor，可选) - 偏置项，形状为：:math:`[M]` 。 - **stride** (int|list|tuple，可选) - 步长大小。卷积核和输入进行卷积计算时滑动的步长。 - 如果它是一个列表或元组，则必须包含三个整型数：（stride_depth, stride_height,stride_width）。 - 若为一个整数，stride_depth = stride_height = stride_width = stride。默认值：1。 - - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式： - - - (1)包含 5 个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]； - - (2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]； - - (3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 - - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 - - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 - - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度。默认值："NCDHW"。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，可以有以下 3 种格式：(1)包含 5 个二元组：``[[0, 0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0, 0]]``；(2)包含 6 个整数值：``[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]``；(3)包含 3 个整数值：``[padding_depth, padding_height, padding_width]``。若为一个整数，则深度、高度和宽度方向均使用该值。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。若为列表或元组，必须包含三个整数 ``(dilation_depth, dilation_height, dilation_width)``；若为一个整数，则深度、高度和宽度方向均使用该值。默认值：1。 + - **groups** (int，可选) - 卷积层的组数。当前仅支持 ``groups=1``。默认值：1。 + - **data_format** (str，可选) - 指定输入和输出的数据格式。当前仅支持 ``"NDHWC"``，即 ``[batch_size, input_depth, input_height, input_width, input_channels]``。默认值：``"NDHWC"``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 返回 :::::::::::: -5-D Tensor ，数据类型与 ``input`` 一致。返回卷积计算的结果。 +5-D SparseCooTensor，数据类型与 ``x`` 一致。返回卷积计算的结果。 返回类型 :::::::::::: -Tensor。 +SparseCooTensor。 代码示例 :::::::::::: diff --git a/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst b/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst index 37f2c547c35..9390db3defe 100644 --- a/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst +++ b/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst @@ -5,7 +5,7 @@ subm_conv3d .. py:function:: paddle.sparse.nn.functional.subm_conv3d(x, weight, bias=None, stride=1, padding=0, dilation=1, groups=1, data_format="NDHWC", key=None, name=None) -子流形稀疏三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 NCDHW 或 NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 +子流形稀疏三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出均为 NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。若提供 ``bias``，卷积计算会添加偏置项。 对每个输入 X，有等式： @@ -15,11 +15,11 @@ subm_conv3d 其中： - - :math:`X` ：输入值，NCDHW 或 NDHWC 格式的 5-D Tensor - - :math:`W` ：卷积核值，MCDHW 格式的 5-D Tensor + - :math:`X` ：输入值，NDHWC 格式的 5-D SparseCooTensor + - :math:`W` ：卷积核值，DHWCM 格式的 5-D Tensor - :math:`*` ：卷积操作 - :math:`b` ：偏置值，1-D Tensor，形为 ``[M]`` - - :math:`Out` ：输出值，NCDHW 或 NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + - :math:`Out` ：输出值，NDHWC 格式的 5-D SparseCooTensor，和 ``X`` 的形状可能不同 **示例** @@ -37,25 +37,23 @@ subm_conv3d :::::::::::: - **x** (Tensor) - 输入是形状为 :math:`[N, D, H, W, C]` 的 5-D SparseCooTensor，N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度，数据类型为 float16, float32 或 float64。 - - **weight** (Tensor) - 形状为 :math:`[kD, kH, kW, C/g, M]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kH 是卷积核的高度，kW 是卷积核的宽度。 + - **weight** (Tensor) - 形状为 :math:`[kD, kH, kW, C/g, M]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kD、kH、kW 分别是卷积核的深度、高度和宽度。 - **bias** (Tensor，可选) - 偏置项，形状为：:math:`[M]` 。 - **stride** (int|list|tuple，可选) - 步长大小。卷积核和输入进行卷积计算时滑动的步长。如果它是一个列表或元组，则必须包含三个整型数：（stride_depth, stride_height,stride_width）。若为一个整数，stride_depth = stride_height = stride_width = stride。默认值：1。 - - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 5 个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 - - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 - - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 - - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 - - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 - - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度。默认值："NCDHW"。 - - **key** (str，可选) - 用来保存和使用相同 rulebook 。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，可以有以下 3 种格式：(1)包含 5 个二元组：``[[0, 0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0, 0]]``；(2)包含 6 个整数值：``[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]``；(3)包含 3 个整数值：``[padding_depth, padding_height, padding_width]``。若为一个整数，则深度、高度和宽度方向均使用该值。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。若为列表或元组，必须包含三个整数 ``(dilation_depth, dilation_height, dilation_width)``；若为一个整数，则深度、高度和宽度方向均使用该值。默认值：1。 + - **groups** (int，可选) - 卷积层的组数。当前仅支持 ``groups=1``。默认值：1。 + - **data_format** (str，可选) - 指定输入和输出的数据格式。当前仅支持 ``"NDHWC"``，即 ``[batch_size, input_depth, input_height, input_width, input_channels]``。默认值：``"NDHWC"``。 + - **key** (str|None，可选) - 用来保存或使用相同的 rulebook。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None 。 返回 :::::::::::: -5-D Tensor，数据类型与 ``input`` 一致。返回卷积计算的结果。 +5-D SparseCooTensor，数据类型与 ``x`` 一致。返回卷积计算的结果。 返回类型 :::::::::::: -Tensor。 +SparseCooTensor。 代码示例 :::::::::::: diff --git a/docs/api/paddle/sparse/slice_cn.rst b/docs/api/paddle/sparse/slice_cn.rst index d239131106d..08d5f9684c2 100644 --- a/docs/api/paddle/sparse/slice_cn.rst +++ b/docs/api/paddle/sparse/slice_cn.rst @@ -3,11 +3,11 @@ slice ------------------------------- -.. py:function:: paddle.sparse.slice(x, axis, starts, ends, name=None) +.. py:function:: paddle.sparse.slice(x, axes, starts, ends, name=None) 沿多个轴生成 ``x`` 的切片。使用 ``axes`` 、 ``starts`` 和 ``ends`` 属性来指定轴列表中每个轴的起点和终点位置，并使用此信息来对 ``x`` 切片。 如果向 ``starts`` 或 ``ends`` 传递负值如 :math:`-i`，则表示该轴的反向第 :math:`i-1` 个位置（这里以 0 为初始位置）。 -如果传递给 ``starts`` 或 ``end`` 的值大于 n (维度中的元素数目)，则表示 n。 +如果传递给 ``starts`` 或 ``ends`` 的值大于 n (维度中的元素数目)，则表示 n。 当切片一个未知数量的维度时，建议传入 ``INT_MAX``。 ``axes`` 、 ``starts`` 和 ``ends`` 三个参数的元素数目必须相等。 @@ -34,10 +34,11 @@ slice 参数 ::::::::: - - **x** (Tensor) - 输入的多维 ``Tensor``，数据类型为 bool、float16、float32、float64、int32 或 int64。 - - **axis** (list|tuple|Tensor) - 数据类型是 ``int32``。如果 ``axes`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[1]的 ``Tensor``。如果 ``axes`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示进行切片的轴。 - - **starts** (list|tuple|Tensor) - 数据类型是 ``int32``。如果 ``starts`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[1]的 ``Tensor``。如果 ``starts`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的起始索引值。 - - **ends** (list|tuple|Tensor) - 数据类型是 ``int32``。如果 ``ends`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[1]的 ``Tensor``。如果 ``ends`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的结束索引值。 + - **x** (Tensor) - 输入的多维 ``Tensor``，数据类型为 bool、float16、float32、float64、int16、int32 或 int64。 + - **axes** (list|tuple|Tensor) - 数据类型是 ``int32``。如果 ``axes`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[]的 0-D ``Tensor``。如果 ``axes`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示进行切片的轴。 + - **starts** (list|tuple|Tensor) - 数据类型是 ``int32``。如果 ``starts`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[]的 0-D ``Tensor``。如果 ``starts`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的起始索引值。 + - **ends** (list|tuple|Tensor) - 数据类型是 ``int32``。如果 ``ends`` 的类型是 list 或 tuple, 它的元素可以是整数或者形状为[]的 0-D ``Tensor``。如果 ``ends`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的结束索引值。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: From 3561d88ef253de59899fcef7cbbe1b98b5a284a6 Mon Sep 17 00:00:00 2001 From: manfredss Date: Mon, 17 Aug 2026 17:26:31 +0800 Subject: [PATCH 16/18] add 16 more apis --- docs/api/paddle/compat/nanmedian_cn.rst | 9 ++++--- docs/api/paddle/compat/nn/Linear_cn.rst | 4 ++-- docs/api/paddle/cuda/Stream_cn.rst | 8 +++---- docs/api/paddle/device/Event_cn.rst | 9 ++++--- docs/api/paddle/device/Stream_cn.rst | 24 ++++--------------- docs/api/paddle/device/XPUPlace_cn.rst | 4 ++-- .../device/cuda/get_device_properties_cn.rst | 4 ++-- docs/api/paddle/device/device_count_cn.rst | 11 +++------ docs/api/paddle/device/get_device_cn.rst | 11 ++++++--- .../is_compiled_with_custom_device_cn.rst | 5 ++++ docs/api/paddle/device/set_stream_cn.rst | 2 +- docs/api/paddle/device/stream_guard_cn.rst | 2 +- docs/api/paddle/io/DataLoader_cn.rst | 6 +++-- .../paddle/io/DistributedBatchSampler_cn.rst | 3 ++- docs/api/paddle/io/SequenceSampler_cn.rst | 4 ++-- docs/api/paddle/io/Subset_cn.rst | 2 +- 16 files changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/api/paddle/compat/nanmedian_cn.rst b/docs/api/paddle/compat/nanmedian_cn.rst index 60290a1703d..27189385350 100644 --- a/docs/api/paddle/compat/nanmedian_cn.rst +++ b/docs/api/paddle/compat/nanmedian_cn.rst @@ -3,7 +3,7 @@ nanmedian ------------------------------- -.. py:function:: paddle.compat.nanmedian(input, *, dim=None, keepdim=False, *, out=None) +.. py:function:: paddle.compat.nanmedian(input, dim=None, keepdim=False, *, out=None) PyTorch 兼容的 :ref:`cn_api_paddle_nanmedian` 版本，提供完全一致的函数签名与行为： - 忽略 NaN 元素计算中位数。 @@ -15,10 +15,13 @@ PyTorch 兼容的 :ref:`cn_api_paddle_nanmedian` 版本，提供完全一致的 参数 :::::::::: -- **input** (Tensor) - 输入 N 维 Tensor，支持 bfloat16、float16、float32、float64 数据类型。 +- **input** (Tensor) - 输入 N 维 Tensor，支持 bfloat16、float16、float32、float64、int32、int64 数据类型。 - **dim** (int，可选) - 指定计算中位数的维度。为 ``None`` 时计算全局中位数。默认 ``None``。 - **keepdim** (bool，可选) - 是否保留被约简的维度。默认 ``False``。 -- **out** (tuple(Tensor, Tensor)|Tensor，可选) - 关键字参数。当指定 ``dim`` 时，可传入二元组 ``(values, indices)`` 用于原位写回中位数与索引；当未指定 ``dim`` 时，可传入单个 ``Tensor`` 用于写回标量结果。默认 ``None``。 + +关键字参数 +:::::::::: +- **out** (tuple(Tensor, Tensor)|Tensor，可选) - 当指定 ``dim`` 时，可传入二元组 ``(values, indices)`` 用于原位写回中位数与索引；当未指定 ``dim`` 时，可传入单个 ``Tensor`` 用于写回标量结果。默认 ``None``。 返回 :::::::::: diff --git a/docs/api/paddle/compat/nn/Linear_cn.rst b/docs/api/paddle/compat/nn/Linear_cn.rst index dfbaae7114f..96010ef4818 100644 --- a/docs/api/paddle/compat/nn/Linear_cn.rst +++ b/docs/api/paddle/compat/nn/Linear_cn.rst @@ -3,7 +3,7 @@ Linear ------------------------------- -.. py:class:: paddle.compat.nn.Linear(in_features, out_features, bias, device=None, dtype=None) +.. py:class:: paddle.compat.nn.Linear(in_features, out_features, bias=True, device=None, dtype=None) PyTorch 兼容的 :ref:`cn_api_paddle_nn_Linear` 版本： @@ -15,7 +15,7 @@ PyTorch 兼容的 :ref:`cn_api_paddle_nn_Linear` 版本： 其中 :math:`W` 是权重张量， :math:`b` 是偏置张量， :math:`X` 是输入张量 - - 与 PyTorch 一致的默认可视化方法： Kaiming normal 用于权重初始化，平均分布用于偏置初始化 + - 与 PyTorch 一致的默认可视化方法：权重与偏置均使用均匀分布初始化 - 支持设定 ``Linear`` 的数据类型以及运行设备 使用前请详细参考：`【仅参数名不一致】torch.nn.Linear`_ 以确定是否使用此模块。 diff --git a/docs/api/paddle/cuda/Stream_cn.rst b/docs/api/paddle/cuda/Stream_cn.rst index 4e12a32dde6..8428f2c3b81 100644 --- a/docs/api/paddle/cuda/Stream_cn.rst +++ b/docs/api/paddle/cuda/Stream_cn.rst @@ -3,15 +3,15 @@ Stream ------ -.. py:class:: paddle.cuda.Stream(device=None, priority=0, blocking=False) +.. py:class:: paddle.cuda.Stream(device=None, priority=2, stream_base=None) CUDA 流类，用于管理异步操作。 参数 :::::::::::: - - **device** (int|paddle.Place|str|int|None) - 设备 ID 或设备对象 - - **priority** (int, 可选) - 流的优先级，默认为 None; 可以是 1 或-1（高优先级）或 0 或 2（低优先级）。默认情况下，流具有优先级 0。 - - **blocking** (bool|None，可选) - stream 是否同步执行。默认值为 False。 + - **device** (int|paddle.Place|str|int|None，可选) - 设备 ID 或设备对象 + - **priority** (int, 可选) - 流的优先级，可以是 1 或 -1（高优先级）或 0 或 2（低优先级）。默认值为 2。 + - **stream_base** (_InitStreamBase|None，可选) - 用于初始化流的底层 StreamBase 对象。默认值为 None。 代码示例 :::::::::::: diff --git a/docs/api/paddle/device/Event_cn.rst b/docs/api/paddle/device/Event_cn.rst index 240e1408b0e..134e57b39c7 100644 --- a/docs/api/paddle/device/Event_cn.rst +++ b/docs/api/paddle/device/Event_cn.rst @@ -3,21 +3,24 @@ Event ------------------------------- -.. py:class:: paddle.device.Event(device=None, enable_timing=False, blocking=False, interprocess=False) +.. py:class:: paddle.device.Event(enable_timing=False, blocking=False, interprocess=False) event 的句柄。 参数 :::::::::::: - - **device** (paddle.CUDAPlace|paddle.CustomPlace|str) - 希望分配 event 的设备或设备类型。如果为 None，则为当前期望的 place。默认值为 None。 - **enable_timing** (bool，可选) - event 是否需要统计时间。默认值为 False。 - **blocking** (bool，可选) - wait()函数是否被阻塞。默认值为 False。 - **interprocess** (bool，可选) - event 是否能在进程间共享。默认值为 False。 返回 :::::::::::: -None +``Event`` 对象。 + +.. note:: + + ``device`` 参数已移除，Event 始终使用当前设备上下文。``paddle.device.Event`` 与 ``paddle.cuda.Event`` 等价。 代码示例 :::::::::::: diff --git a/docs/api/paddle/device/Stream_cn.rst b/docs/api/paddle/device/Stream_cn.rst index f763730ec30..6bb53b40f5d 100644 --- a/docs/api/paddle/device/Stream_cn.rst +++ b/docs/api/paddle/device/Stream_cn.rst @@ -3,16 +3,16 @@ Stream ------------------------------- -.. py:class:: paddle.device.Stream(device=None, priority=None, blocking=False) +.. py:class:: paddle.device.Stream(device=None, priority=2, stream_base=None) -custom device stream 的句柄。 +设备 stream 的句柄。``paddle.cuda.Stream()`` 与 ``paddle.device.Stream()`` 等价。 参数 :::::::::::: - **device** (paddle.CUDAPlace|paddle.CustomPlace|str) - 希望分配 stream 的设备或设备类型。如果为 None，则为当前期望的 place。默认值为 None。 - - **priority** (int|None，可选) - (int, 可选) - 流的优先级，默认为 None; 可以是 1 或-1（高优先级）或 0 或 2（低优先级）。默认情况下，流具有优先级 0。 - - **blocking** (bool|None，可选) - stream 是否同步执行。默认值为 False。 + - **priority** (int，可选) - 流的优先级，可以是 1 或 -1（高优先级）或 0 或 2（低优先级）。默认值为 2。 + - **stream_base** (_InitStreamBase|None，可选) - 用于初始化流的底层 StreamBase 对象。默认值为 None。 代码示例 @@ -67,20 +67,6 @@ wait_stream(stream) COPY-FROM: paddle.device.Stream.wait_stream -record_event(event=None) -''''''''' - -记录给定的 event。 - -**参数** - - - **event** (paddle.device.Event) - 要记录的 event，如果为 None，则新建一个 event。 - - -**代码示例** - -COPY-FROM: paddle.device.Stream.record_event - query() ''''''''' @@ -96,7 +82,7 @@ COPY-FROM: paddle.device.Stream.query synchronize() ''''''''' -等待所有的 stream 的任务完成。 +等待当前 stream 中所有 kernel 完成。 **代码示例** diff --git a/docs/api/paddle/device/XPUPlace_cn.rst b/docs/api/paddle/device/XPUPlace_cn.rst index c266dc587ed..f12088ac549 100644 --- a/docs/api/paddle/device/XPUPlace_cn.rst +++ b/docs/api/paddle/device/XPUPlace_cn.rst @@ -3,7 +3,7 @@ XPUPlace ------------------------------- -.. py:class:: paddle.device.XPUPlace +.. py:class:: paddle.device.XPUPlace(dev_id) @@ -16,7 +16,7 @@ XPUPlace 参数 :::::::::::: - - **id** (int，可选) - XPU 的设备 ID。如果为 ``None``，则默认会使用 id 为 0 的设备。默认值为 ``None``。 + - **dev_id** (int) - XPU 的设备 ID。 代码示例 :::::::::::: diff --git a/docs/api/paddle/device/cuda/get_device_properties_cn.rst b/docs/api/paddle/device/cuda/get_device_properties_cn.rst index e044387783f..e0044bef633 100644 --- a/docs/api/paddle/device/cuda/get_device_properties_cn.rst +++ b/docs/api/paddle/device/cuda/get_device_properties_cn.rst @@ -3,14 +3,14 @@ get_device_properties ------------------------------- -.. py:function:: paddle.device.cuda.get_device_properties(device) +.. py:function:: paddle.device.cuda.get_device_properties(device=None) 返回给定的设备属性。 参数 :::::::: - - **device** (paddle.CUDAPlace or int or str) - 设备、设备 ID 和类似于 ``gpu:x`` 的设备名称。如果 ``device`` 为空，则 ``device`` 为当前的设备。默认值为 None。 + - **device** (paddle.CUDAPlace or int or str，可选) - 设备、设备 ID 和类似于 ``gpu:x`` 的设备名称。如果 ``device`` 为空，则 ``device`` 为当前的设备。默认值为 None。 返回 diff --git a/docs/api/paddle/device/device_count_cn.rst b/docs/api/paddle/device/device_count_cn.rst index 5b459978fc8..0ddaf033572 100644 --- a/docs/api/paddle/device/device_count_cn.rst +++ b/docs/api/paddle/device/device_count_cn.rst @@ -3,19 +3,14 @@ device_count ------------ -.. py:function:: paddle.device.device_count(device=None) +.. py:function:: paddle.device.device_count() -返回指定设备类型的可用设备数量。 - -参数 -:::::::::::: - - - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备类型的可用设备数量。默认值为 None。 +返回当前构建环境中可用设备后端的设备数量。 返回 :::::::::::: - int，指定设备类型的可用设备数量。 + int，可用设备的数量。 代码示例 :::::::::::: diff --git a/docs/api/paddle/device/get_device_cn.rst b/docs/api/paddle/device/get_device_cn.rst index cb2d3f9ff93..3d71979fe4f 100644 --- a/docs/api/paddle/device/get_device_cn.rst +++ b/docs/api/paddle/device/get_device_cn.rst @@ -3,14 +3,19 @@ get_device ------------------------------- -.. py:function:: paddle.device.get_device() +.. py:function:: paddle.device.get_device(input=None) -该功能返回当前程序运行的全局设备，返回的是一个类似于 ``cpu``、 ``gpu:x``、 ``xpu:x``、 ``mlu:x`` 或者 ``npu:x`` 字符串，如果没有设置全局设备，当 cuda 可用的时候返回 ``gpu:0``，当 cuda 不可用的时候返回 ``cpu`` 。 +该功能返回当前程序运行的全局设备。未设置全局设备时，CUDA 可用则返回 ``gpu:0``，否则返回 ``cpu``。若传入 Tensor，则返回该 Tensor 所在设备的设备 ID。 + +参数 +:::::::::::: + + - **input** (paddle.Tensor|None，可选) - 待查询设备的 Tensor。默认值为 None。 返回 :::::::::::: -返回当前程序运行的全局设备。 +当 ``input`` 为 Tensor 时，返回 int：CPU Tensor 返回 -1，GPU Tensor 返回其设备 ID。当 ``input`` 不是 Tensor 时，返回当前程序运行设备的名称字符串。 代码示例 :::::::::::: diff --git a/docs/api/paddle/device/is_compiled_with_custom_device_cn.rst b/docs/api/paddle/device/is_compiled_with_custom_device_cn.rst index 0c072154ace..7c8b3daa5a3 100644 --- a/docs/api/paddle/device/is_compiled_with_custom_device_cn.rst +++ b/docs/api/paddle/device/is_compiled_with_custom_device_cn.rst @@ -7,6 +7,11 @@ is_compiled_with_custom_device 检查 ``whl`` 包是否可以被用来在指定类型的自定义新硬件上运行模型 +参数 +:::::::::::: + + - **device_type** (str) - 待检查的自定义设备类型。 + 返回 :::::::::::: bool，支持指定 device_type 则为 True，否则为 False。 diff --git a/docs/api/paddle/device/set_stream_cn.rst b/docs/api/paddle/device/set_stream_cn.rst index a3d23048840..b050a62f308 100644 --- a/docs/api/paddle/device/set_stream_cn.rst +++ b/docs/api/paddle/device/set_stream_cn.rst @@ -3,7 +3,7 @@ set_stream ------------------------------- -.. py:function:: paddle.device.set_stream(stream=None) +.. py:function:: paddle.device.set_stream(stream) 设置当前的 stream。 diff --git a/docs/api/paddle/device/stream_guard_cn.rst b/docs/api/paddle/device/stream_guard_cn.rst index 08b8ee1c228..5cb2bad940f 100644 --- a/docs/api/paddle/device/stream_guard_cn.rst +++ b/docs/api/paddle/device/stream_guard_cn.rst @@ -3,7 +3,7 @@ stream_guard ------------------------------- -.. py:function:: paddle.device.stream_guard(stream) +.. py:function:: paddle.device.stream_guard(stream=None) 可以切换当前的 stream 为输入指定的 stream。 diff --git a/docs/api/paddle/io/DataLoader_cn.rst b/docs/api/paddle/io/DataLoader_cn.rst index 52d26372f73..d8d726290cd 100644 --- a/docs/api/paddle/io/DataLoader_cn.rst +++ b/docs/api/paddle/io/DataLoader_cn.rst @@ -3,7 +3,7 @@ DataLoader ------------------------------- -.. py:class:: paddle.io.DataLoader(dataset, feed_list=None, places=None, return_list=False, batch_sampler=None, batch_size=1, shuffle=False, drop_last=False, collate_fn=None, num_workers=0, use_buffer_reader=True, use_shared_memory=True, prefetch_factor=2, timeout=0, worker_init_fn=None) +.. py:class:: paddle.io.DataLoader(dataset, feed_list=None, places=None, return_list=True, batch_sampler=None, batch_size=1, shuffle=False, drop_last=False, collate_fn=None, num_workers=0, use_buffer_reader=True, reader_buffer_size=2, prefetch_factor=2, use_shared_memory=True, timeout=0, worker_init_fn=None, persistent_workers=False) DataLoader 返回一个迭代器，该迭代器根据 ``batch_sampler`` 给定的顺序迭代一次给定的 ``dataset`` @@ -30,7 +30,7 @@ DataLoader 当前支持 ``map-style`` 和 ``iterable-style`` 的数据集，``ma - **dataset** (Dataset) - DataLoader 从此参数给定数据集中加载数据，此参数必须是 ``paddle.io.Dataset`` 或 ``paddle.io.IterableDataset`` 的一个子类实例。 - **feed_list** (list(Tensor)|tuple(Tensor)，可选) - feed 变量列表，由 ``paddle.static.data()`` 创建。当 ``return_list`` 为 False 时，此参数必须设置。默认值为 None。 - - **places** (list(Place)|tuple(Place)，可选) - 数据需要放置到的 Place 列表。在静态图和动态图模式中，此参数均必须设置。在动态图模式中，此参数列表长度必须是 1。默认值为 None。 + - **places** (list(Place)|tuple(Place)|list(str)|None，可选) - 数据需要放置到的 Place 列表。该参数可以为 None；为 None 时，使用默认 Place（CPUPlace 或 CUDAPlace(0)）。如果为字符串列表，字符串可以是 ``"cpu"``、``"gpu:x"`` 或 ``"gpu_pinned"``，其中 ``x`` 为 GPU 索引。默认值为 None。 - **return_list** (bool，可选) - 每个设备上的数据是否以 list 形式返回。若 return_list = False，每个设备上的返回数据均是 str -> Tensor 的映射表，其中映射表的 key 是每个输入变量的名称。若 return_list = True，则每个设备上的返回数据均是 list(Tensor)。在动态图模式下，此参数必须为 True。默认值为 True。 - **batch_sampler** (BatchSampler，可选) - ``paddle.io.BatchSampler`` 或其子类的实例，DataLoader 通过 ``batch_sampler`` 产生的 mini-batch 索引列表来 ``dataset`` 中索引样本并组成 mini-batch。默认值为 None。 - **batch_size** (int|None，可选) - 每 mini-batch 中样本个数，为 ``batch_sampler`` 的替代参数，若 ``batch_sampler`` 未设置，会根据 ``batch_size`` ``shuffle`` ``drop_last`` 创建一个 ``paddle.io.BatchSampler``。默认值为 1。 @@ -39,10 +39,12 @@ DataLoader 当前支持 ``map-style`` 和 ``iterable-style`` 的数据集，``ma - **collate_fn** (callable，可选) - 通过此参数指定如何将样本列表组合为 mini-batch 数据，当 ``collate_fn`` 为 None 时，默认为将样本个字段在第 0 维上堆叠(同 ``np.stack(..., axis=0)`` )为 mini-batch 的数据。默认值为 None。 - **num_workers** (int，可选) - 用于加载数据的子进程个数，若为 0 即为不开启子进程，在主进程中进行数据加载。默认值为 0。 - **use_buffer_reader** (bool，可选) - 是否使用缓存读取器。若 ``use_buffer_reader`` 为 True，DataLoader 会异步地预读取一定数量（默认读取下一个）的 mini-batch 的数据，可加速数据读取过程，但同时会占用少量的 CPU/GPU 存储，即一个 batch 输入数据的存储空间。默认值为 True。 + - **reader_buffer_size** (int，可选) - 仅当 ``use_buffer_reader`` 为 True 时生效，指定缓存读取器预读取的 batch 数。增大该值会线性增加 CPU 或 GPU 内存占用。默认值为 2。 - **prefetch_factor** (int，可选) - 缓存的 mini-batch 的个数。若 ``use_buffer_reader`` 为 True，DataLoader 会异步地预读取 ``prefetch_factor`` 个 mini-batch。默认值为 2。 - **use_shared_memory** (bool，可选) - 是否使用共享内存来提升子进程将数据放入进程间队列的速度，该参数仅在多进程模式下有效(即 ``num_workers > 0`` )，请确认机器上有足够的共享内存空间(如 Linux 系统下 ``/dev/shm/`` 目录空间大小)再设置此参数。默认为 True。 - **timeout** (int，可选) - 从子进程输出队列获取 mini-batch 数据的超时时间。默认值为 0。 - **worker_init_fn** (callable，可选) - 子进程初始化函数，此函数会被子进程初始化时被调用，并传递 ``worker id`` 作为参数。默认值为 None。 + - **persistent_workers** (bool，可选) - 是否保留 DataLoader 中的 worker。默认值为 False。 返回 :::::::::::: diff --git a/docs/api/paddle/io/DistributedBatchSampler_cn.rst b/docs/api/paddle/io/DistributedBatchSampler_cn.rst index 799e65fb4c4..d2ad9dc7d39 100644 --- a/docs/api/paddle/io/DistributedBatchSampler_cn.rst +++ b/docs/api/paddle/io/DistributedBatchSampler_cn.rst @@ -3,7 +3,7 @@ DistributedBatchSampler ------------------------------- -.. py:class:: paddle.io.DistributedBatchSampler(dataset, batch_size, num_replicas=None, rank=None, shuffle=False, drop_last=False) +.. py:class:: paddle.io.DistributedBatchSampler(dataset, batch_size, num_replicas=None, rank=None, shuffle=False, drop_last=False, seed=0) 分布式批采样器加载数据的一个子集。每个进程可以传递给 DataLoader 一个 DistributedBatchSampler 的实例，每个进程加载原始数据的一个子集。 @@ -20,6 +20,7 @@ DistributedBatchSampler - **rank** (int，可选) - num_replicas 个进程中的进程序号。如果是 None，会依据 :ref:`cn_api_paddle_distributed_ParallelEnv` 获取值。默认是 None。 - **shuffle** (bool，可选) - 是否需要在生成样本下标时打乱顺序。默认值为 False。 - **drop_last** (bool，可选) - 是否需要丢弃最后无法凑整一个 mini-batch 的样本。默认值为 False。 + - **seed** (int，可选) - 当 ``shuffle=True`` 时用于打乱样本下标的随机种子。该值应在分布式组的所有进程中相同。默认值为 0。 返回 diff --git a/docs/api/paddle/io/SequenceSampler_cn.rst b/docs/api/paddle/io/SequenceSampler_cn.rst index 6b7d131081d..570c3560f77 100644 --- a/docs/api/paddle/io/SequenceSampler_cn.rst +++ b/docs/api/paddle/io/SequenceSampler_cn.rst @@ -3,14 +3,14 @@ SequenceSampler ------------------------------- -.. py:class:: paddle.io.SequenceSampler(data_source=None) +.. py:class:: paddle.io.SequenceSampler(data_source) 顺序迭代 ``data_source`` 返回样本下标，即一次返回 ``0, 1, 2, ..., len(data_source) - 1`` 参数 :::::::::::: - - **data_source** (Dataset) - 此参数必须是 ``paddle.io.Dataset`` 或 ``paddle.io.IterableDataset`` 的一个子类实例或实现了 ``__len__`` 的 Python 对象，用于生成样本下标。默认值为 None。 + - **data_source** (Dataset) - 此参数必须是 ``paddle.io.Dataset`` 或 ``paddle.io.IterableDataset`` 的一个子类实例或实现了 ``__len__`` 的 Python 对象，用于生成样本下标。 返回 :::::::::::: diff --git a/docs/api/paddle/io/Subset_cn.rst b/docs/api/paddle/io/Subset_cn.rst index e6c6615ce9c..a2b184126ce 100644 --- a/docs/api/paddle/io/Subset_cn.rst +++ b/docs/api/paddle/io/Subset_cn.rst @@ -11,7 +11,7 @@ Subset 参数 ::::::::: - - **datasets** (Dataset) - 原数据集。 + - **dataset** (Dataset) - 原数据集的子数据集 - **indices** (sequence) - 用于提取子集的原数据集合指标数组。 返回 From 6d9b30f99d75970d7c524f4dc5fcd533ba8bb643 Mon Sep 17 00:00:00 2001 From: manfredss Date: Mon, 17 Aug 2026 20:13:01 +0800 Subject: [PATCH 17/18] add 26 more apis --- .../nn/AdaptiveLogSoftmaxWithLoss_cn.rst | 4 ++- docs/api/paddle/nn/BatchNorm_cn.rst | 10 +++--- docs/api/paddle/nn/CELU_cn.rst | 3 +- docs/api/paddle/nn/Conv1DTranspose_cn.rst | 33 +++++++++++++------ docs/api/paddle/nn/Conv1D_cn.rst | 10 +++--- docs/api/paddle/nn/Conv2DTranspose_cn.rst | 25 ++++++++++---- docs/api/paddle/nn/Conv3DTranspose_cn.rst | 31 ++++++++++++----- docs/api/paddle/nn/CrossEntropyLoss_cn.rst | 20 +++++------ docs/api/paddle/nn/Dropout_cn.rst | 5 +-- docs/api/paddle/nn/Fold_cn.rst | 12 +++---- docs/api/paddle/nn/GRU_cn.rst | 17 ++++++++-- docs/api/paddle/nn/Hardsigmoid_cn.rst | 7 ++-- docs/api/paddle/nn/LSTMCell_cn.rst | 12 +++++-- docs/api/paddle/nn/LSTM_cn.rst | 15 ++++++--- docs/api/paddle/nn/MarginRankingLoss_cn.rst | 6 ++-- docs/api/paddle/nn/Mish_cn.rst | 3 +- docs/api/paddle/nn/ModuleDict_cn.rst | 24 +++++++------- docs/api/paddle/nn/ModuleList_cn.rst | 24 +++++++------- docs/api/paddle/nn/RReLU_cn.rst | 3 +- docs/api/paddle/nn/SELU_cn.rst | 3 +- docs/api/paddle/nn/Silu_cn.rst | 3 +- docs/api/paddle/nn/SimpleRNN_cn.rst | 7 ++-- docs/api/paddle/nn/SpectralNorm_cn.rst | 5 ++- docs/api/paddle/nn/Swish_cn.rst | 3 +- docs/api/paddle/nn/SyncBatchNorm_cn.rst | 10 +++--- docs/api/paddle/nn/ThresholdedReLU_cn.rst | 2 +- 26 files changed, 188 insertions(+), 109 deletions(-) diff --git a/docs/api/paddle/nn/AdaptiveLogSoftmaxWithLoss_cn.rst b/docs/api/paddle/nn/AdaptiveLogSoftmaxWithLoss_cn.rst index f6f9bf8f5bd..3fc9b53e999 100644 --- a/docs/api/paddle/nn/AdaptiveLogSoftmaxWithLoss_cn.rst +++ b/docs/api/paddle/nn/AdaptiveLogSoftmaxWithLoss_cn.rst @@ -3,7 +3,7 @@ AdaptiveLogSoftmaxWithLoss ------------------------------- -.. py:class:: paddle.nn.AdaptiveLogSoftmaxWithLoss(in_features, n_classes, cutoffs, div_value=4.0, head_bias=False, name=None) +.. py:class:: paddle.nn.AdaptiveLogSoftmaxWithLoss(in_features, n_classes, cutoffs, weight_attr=None, bias_attr=None, div_value=4.0, head_bias=False, name=None) AdaptiveLogSoftmaxWithLoss 是一种高效的策略，通常用于自然语言处理任务中的语言模型训练，尤其是在处理具有大量词汇且标签分布显著不平衡的语料库时。 AdaptiveLogSoftmaxWithLoss 将标签按照频率划分为多个组，每个组包含的目标数量不同，且在频率较低的标签所在的组中会采用较低维度的嵌入，从而显著减少计算量。 @@ -23,6 +23,8 @@ AdaptiveLogSoftmaxWithLoss 将标签按照频率划分为多个组，每个组 - **in_features** (int): 输入 Tensor 的特征数量。 - **n_classes** (int): 数据集中类型的个数。 - **cutoffs** (Sequence): 用于将 label 分配到不同存储组的截断值。 + - **weight_attr** (ParamAttr，可选): 本层可学习权重的属性。默认值为 None；当其 Initializer 未设置时，参数使用 Xavier 初始化。详细信息请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **bias_attr** (ParamAttr|bool|None，可选): 本层可学习偏置的属性。设为 False 时不添加偏置；设为 None 或 ParamAttr 时，根据 ParamAttr 创建偏置参数。默认值为 None，偏置初始化为零。详细信息请参见 :ref:`cn_api_paddle_ParamAttr`。 - **div_value** (float, 可选): 用于计算组大小的指数值。默认值：4.0。 - **head_bias** (bool, 可选): 如果为 ``True``，AdaptiveLogSoftmaxWithLoss 的 ``head`` 添加偏置项。默认值： ``False``. - **name** (str, 可选): 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/nn/BatchNorm_cn.rst b/docs/api/paddle/nn/BatchNorm_cn.rst index 0575779d4c5..1e230d03d49 100644 --- a/docs/api/paddle/nn/BatchNorm_cn.rst +++ b/docs/api/paddle/nn/BatchNorm_cn.rst @@ -3,7 +3,7 @@ BatchNorm ------------------------------- -.. py:class:: paddle.nn.BatchNorm(num_channels, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, dtype='float32', data_layout='NCHW', in_place=False, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False, use_global_stats=False, trainable_statistics=False) +.. py:class:: paddle.nn.BatchNorm(num_channels, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, dtype='float32', data_layout='NCHW', in_place=False, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=True, use_global_stats=False, trainable_statistics=False) @@ -45,15 +45,15 @@ BatchNorm - **is_test** (bool，可选) - 指示是否在测试阶段，非训练阶段使用训练过程中统计到的全局均值和全局方差。默认值：False。 - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var``。默认值：0.9。更新公式如上所示。 - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **param_attr** (ParamAttr|bool|None，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool|None，可选) - 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 指明输入 ``Tensor`` 的数据类型，可以为 float32 或 float64。默认值：float32。 - **data_layout** (str，可选) - 指定输入数据格式，数据格式可以为 ``"NCHW"`` 或 ``"NHWC"``，其中 N 是批大小，C 是通道数，H 是特征高度，W 是特征宽度。默认值为 ``"NCHW"``。 - **in_place** (bool，可选) - 指示 ``batch_norm`` 的输出是否可以复用输入内存。默认值：False。 - **moving_mean_name** (str，可选) - ``moving_mean`` 的名称，存储全局均值。如果将其设置为 None, ``batch_norm`` 将随机命名全局均值；否则，``batch_norm`` 将命名全局均值为 ``moving_mean_name``。默认值：None。 - **moving_variance_name** (string，可选) - ``moving_var`` 的名称，存储全局方差。如果将其设置为 None, ``batch_norm`` 将随机命名全局方差；否则，``batch_norm`` 将命名全局方差为 ``moving_variance_name``。默认值：None。 - - **do_model_average_for_mean_and_var** (bool，可选) - 指示是否为 mean 和 variance 做模型均值。默认值：False。 - - **use_global_stats** (bool，可选) – 指示是否使用全局均值和方差。在预测或测试模式下，将 ``use_global_stats`` 设置为 true 或将 ``is_test`` 设置为 true，这两种行为是等效的。在训练模式中，当设置 ``use_global_stats`` 为 True 时，在训练期间也将使用全局均值和方差。默认值：False。 + - **do_model_average_for_mean_and_var** (bool，可选) - 指示是否为 mean 和 variance 做模型均值。默认值：True。 + - **use_global_stats** (bool，可选) - 指示是否使用全局均值和方差。在预测或测试模式下，将 ``use_global_stats`` 设置为 true 或将 ``is_test`` 设置为 true，这两种行为是等效的。在训练模式中，当设置 ``use_global_stats`` 为 True 时，在训练期间也将使用全局均值和方差。默认值：False。 - **trainable_statistics** (bool，可选) - eval 模式下是否计算 mean 均值和 var 方差。eval 模式下，trainable_statistics 为 True 时，由该批数据计算均值和方差。默认值：False。 返回 diff --git a/docs/api/paddle/nn/CELU_cn.rst b/docs/api/paddle/nn/CELU_cn.rst index c54e7bcaa76..0574ddfe8f4 100644 --- a/docs/api/paddle/nn/CELU_cn.rst +++ b/docs/api/paddle/nn/CELU_cn.rst @@ -2,7 +2,7 @@ CELU ------------------------------- -.. py:class:: paddle.nn.CELU(alpha=1.0, name=None) +.. py:class:: paddle.nn.CELU(alpha=1.0, inplace=False, name=None) CELU 激活层（CELU Activation Operator） @@ -17,6 +17,7 @@ CELU 激活层（CELU Activation Operator） 参数 :::::::::: - **alpha** (float，可选) - CELU 的 alpha 值，默认值为 1.0。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/Conv1DTranspose_cn.rst b/docs/api/paddle/nn/Conv1DTranspose_cn.rst index 0032e682c54..42019120690 100644 --- a/docs/api/paddle/nn/Conv1DTranspose_cn.rst +++ b/docs/api/paddle/nn/Conv1DTranspose_cn.rst @@ -3,26 +3,31 @@ Conv1DTranspose ------------------------------- -.. py:class:: paddle.nn.Conv1DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCL") +.. py:class:: paddle.nn.Conv1DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCL", *, bias=True, padding_mode="zeros", device=None, dtype=None) +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.nn.Conv1DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format='NCL', *, bias=True, padding_mode='zeros', device=None, dtype=None)``（Paddle 风格）：通过 ``weight_attr`` 和 ``bias_attr`` 指定参数。 + 2. ``paddle.nn.Conv1DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, bias=True, dilation=1, padding_mode='zeros', device=None, dtype=None)``（PyTorch 风格）：参数顺序与 ``torch.nn.ConvTranspose1d`` 相同。 一维转置卷积层（Convolution1d transpose layer） -该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征大小或者通过 output_size 指定输出特征层大小。输入(Input)和输出(Output)为 NCL 或 NLC 格式，其中 N 为批尺寸，C 为通道数（channel），L 为特征长度。卷积核是 MCL 格式，M 是输出图像通道数，C 是输入图像通道数，L 是卷积核长度。如果组数大于 1，C 等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 `参考文献 `_。如果参数 bias_attr 不为 False，转置卷积计算会添加偏置项。 +该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征大小或者通过 output_size 指定输出特征层大小。输入(Input)和输出(Output)为 NCL 或 NLC 格式，其中 N 为批尺寸，C 为通道数（channel），L 为特征长度。卷积核是 MCK 格式，M 是输出图像通道数，C 是输入图像通道数，K 是卷积核长度。如果组数大于 1，C 等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 `参考文献 `_。如果参数 bias_attr 不为 False，转置卷积计算会添加偏置项。 输入 :math:`X` 和输出 :math:`Out` 函数关系如下： .. math:: - Out=\sigma (W*X+b)\\ + Out=W*X+b\\ 其中： - :math:`X`：输入，具有 NCL 或 NLC 格式的 3-D Tensor - - :math:`W`：卷积核，具有 NCL 格式的 3-D Tensor + - :math:`W`：卷积核，具有 MCK 格式的 3-D Tensor - :math:`*`：卷积计算（注意：转置卷积本质上的计算还是卷积） - :math:`b`：偏置（bias），1-D Tensor，形状为 ``[M]`` - - :math:`σ`：激活函数 - :math:`Out`：输出值，NCL 或 NLC 格式的 3-D Tensor，和 ``X`` 的形状可能不同 @@ -32,26 +37,34 @@ Conv1DTranspose - **in_channels** (int) - 输入特征的通道数。 - **out_channels** (int) - 卷积核的个数，和输出特征通道数相同。 - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含一个整数的元组或列表，表示卷积核的长度。 - - **stride** (int|tuple，可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含一个整型数，表示滑动步长。默认值：1。 - - **padding** (int|list|tuple|str，可选) - 填充大小。可以是以下三种格式：（1）字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考下述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。（2）整数，表示在输入特征两侧各填充 ``padding`` 大小的 0。（3）包含一个整数的列表或元组，表示在输入特征两侧各填充 ``padding[0]`` 大小的 0。默认值：0。 + - **stride** (int|list|tuple，可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含一个整型数，表示滑动步长。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。可以是以下四种形式：（1）字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考下述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式；（2）整数，表示在输入特征两侧各填充 ``padding`` 大小的 0；（3）包含一个整数的列表或元组 ``[pad]``，表示在输入特征两侧各填充 ``pad`` 大小的 0；（4）包含两个整数的列表或元组 ``[pad_left, pad_right]``，分别表示输入特征左、右两侧的填充大小。默认值：0。 - **output_padding** (int|list|tuple，可选) - 输出特征尾部一侧额外添加的大小。默认值：0。 - **groups** (int，可选) - 一维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的分组卷积：当 group=2，卷积核的前一半仅和输入特征图的前一半连接。卷积核的后一半仅和输入特征图的后一半连接。默认值：1。 - - **dilation** (int|tuple，可选) - 空洞大小。可以为单个整数或包含一个整数的元组或列表，表示卷积核中的空洞。默认值：1。 + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含一个整数的元组或列表，表示卷积核中的空洞。默认值：1。 - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCL"和"NLC"。N 是批尺寸，C 是通道数，L 特征长度。默认值："NCL"。 +关键字参数 +:::::::::::: + + - **bias** (bool，可选) - 是否添加可学习的偏置。当为 False 时，``bias_attr`` 会被强制设为 False。默认值为 True。 + - **padding_mode** (str，可选) - 填充模式，可为 ``"zeros"``、``"reflect"``、``"replicate"`` 或 ``"circular"``。默认值为 ``"zeros"``。 + - **device** (str|paddle.CPUPlace|paddle.CUDAPlace|paddle.CUDAPinnedPlace|None，可选) - 创建层参数的设备。默认值为 None。 + - **dtype** (str|paddle.dtype|None，可选) - 层参数的数据类型。默认值为 None。 + 形状 :::::::::::: - - 输入：:math:`（N，C_{in}， L_{in}）` + - 输入：当 ``data_format`` 为 ``"NCL"`` 时，形状为 :math:`（N，C_{in}，L_{in}）`；当 ``data_format`` 为 ``"NLC"`` 时，形状为 :math:`（N，L_{in}，C_{in}）`。 - 卷积核：:math:`（C_{in}，C_{out}， K）` - 偏置：:math:`（C_{out}）` - - 输出：:math:`（N，C_{out}， L_{out}）` + - 输出：当 ``data_format`` 为 ``"NCL"`` 时，形状为 :math:`（N，C_{out}，L_{out}）`；当 ``data_format`` 为 ``"NLC"`` 时，形状为 :math:`（N，L_{out}，C_{out}）`。 其中 diff --git a/docs/api/paddle/nn/Conv1D_cn.rst b/docs/api/paddle/nn/Conv1D_cn.rst index 25186313b9f..19677244e18 100644 --- a/docs/api/paddle/nn/Conv1D_cn.rst +++ b/docs/api/paddle/nn/Conv1D_cn.rst @@ -9,21 +9,20 @@ Conv1D **一维卷积层** -根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算输出特征层大小。输入和输出是 NCL 或 NLC 格式，其中 N 是批尺寸，C 是通道数，L 是特征长度。卷积核是 MCL 格式，M 是输出特征通道数，C 是输入特征通道数，L 是卷积核长度度。如果组数(groups)大于 1，C 等于输入图像通道数除以组数的结果。详情请参考 UFLDL's : `卷积 `_ 。如果 bias_attr 不为 False，卷积计算会添加偏置项。 +根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算输出特征层大小。输入和输出是 NCL 或 NLC 格式，其中 N 是批尺寸，C 是通道数，L 是特征长度。卷积核是 MCK 格式，M 是输出特征通道数，C 是输入特征通道数，K 是卷积核长度。如果组数(groups)大于 1，C 等于输入图像通道数除以组数的结果。详情请参考 UFLDL's : `卷积 `_ 。如果 bias_attr 不为 False，卷积计算会添加偏置项。 对每个输入 X，有等式： .. math:: - Out = \sigma \left ( W * X + b \right ) + Out = W * X + b 其中： - :math:`X`：输入值，NCL 或 NLC 格式的 3-D Tensor - - :math:`W`：卷积核值，MCL 格式的 3-D Tensor + - :math:`W`：卷积核值，MCK 格式的 3-D Tensor - :math:`*`：卷积操作 - :math:`b`：偏置值，1-D Tensor，形状为 ``[M]`` - - :math:`\sigma`：激活函数 - :math:`Out`：输出值，NCL 或 NLC 格式的 3-D Tensor，和 ``X`` 的形状可能不同 @@ -41,8 +40,9 @@ Conv1D 关键字参数 :::::::::::: - - **bias** (bool，可选) - 是否要学习和添加这一层的偏置。如果设置为 False，则不会创建任何偏差，并且 :attr:'bias_attr' 将被忽略。默认值：True。 + - **bias** (bool，可选) - 是否要学习和添加这一层的偏置。如果设置为 False，则不会创建任何偏差，并且 :attr:``bias_attr`` 将被忽略。默认值：True。 - **padding_mode** (str，可选) - 填充模式。包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'``。默认值：``'zeros'`` 。 + - **device** (PlaceLike，可选) - 执行计算的设备。默认值为 None。 - **dtype** (str|Tensor.dtype，可选) - 指定权重、偏置的参数类型，默认值为 None。 - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 diff --git a/docs/api/paddle/nn/Conv2DTranspose_cn.rst b/docs/api/paddle/nn/Conv2DTranspose_cn.rst index a3101ac22b2..dba627346a5 100644 --- a/docs/api/paddle/nn/Conv2DTranspose_cn.rst +++ b/docs/api/paddle/nn/Conv2DTranspose_cn.rst @@ -3,25 +3,30 @@ Conv2DTranspose ------------------------------- -.. py:class:: paddle.nn.Conv2DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCHW") +.. py:class:: paddle.nn.Conv2DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCHW", *, bias=True, padding_mode="zeros", device=None, dtype=None) +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.nn.Conv2DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format='NCHW', *, bias=True, padding_mode='zeros', device=None, dtype=None)``（Paddle 风格）：通过 ``weight_attr`` 和 ``bias_attr`` 指定参数。 + 2. ``paddle.nn.Conv2DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, bias=True, dilation=1, padding_mode='zeros', device=None, dtype=None)``（PyTorch 风格）：参数顺序与 ``torch.nn.ConvTranspose2d`` 相同。 二维转置卷积层（Convolution2d transpose layer） -该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过 output_size 指定输出特征层大小。输入(Input)和输出(Output)为 NCHW 或 NHWC 格式，其中 N 为批尺寸（batch size），C 为通道数（channel），H 为特征层高度，W 为特征层宽度。卷积核是 MCHW 格式，M 是输出图像通道数，C 是输入图像通道数，H 是卷积核高度，W 是卷积核宽度。如果组数大于 1，C 等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 `参考文献 `_。如果参数 bias_attr 不为 False，转置卷积计算会添加偏置项。 +该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过 output_size 指定输出特征层大小。输入(Input)和输出(Output)为 NCHW 或 NHWC 格式，其中 N 为批尺寸（batch size），C 为通道数（channel），H 为特征层高度，W 为特征层宽度。卷积核是 CMHW 格式，C 是输入图像通道数，M 是输出图像通道数，H 是卷积核高度，W 是卷积核宽度。如果组数大于 1，C 等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 `参考文献 `_。如果参数 bias_attr 不为 False，转置卷积计算会添加偏置项。 输入 :math:`X` 和输出 :math:`Out` 函数关系如下： .. math:: - Out=\sigma (W*X+b)\\ + Out=W*X+b\\ 其中： - :math:`X`：输入，具有 NCHW 或 NHWC 格式的 4-D Tensor - - :math:`W`：卷积核，具有 NCHW 格式的 4-D Tensor + - :math:`W`：卷积核，具有 CMHW 格式的 4-D Tensor - :math:`*`：卷积计算（注意：转置卷积本质上的计算还是卷积） - :math:`b`：偏置（bias），1-D Tensor，形状为 ``[M]`` - - :math:`σ`：激活函数 - :math:`Out`：输出值，NCHW 或 NHWC 格式的 4-D Tensor，和 ``X`` 的形状可能不同 @@ -40,7 +45,7 @@ Conv2DTranspose - **out_channels** (int) - 卷积核的个数，和输出特征图通道数相同。 - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核的高和宽。如果为单个整数，表示卷积核的高和宽都等于该整数。 - **stride** (int|list|tuple，可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含两个整型数，分别表示垂直和水平滑动步长。否则，表示垂直和水平滑动步长均为 ``stride``。默认值：1。 - - **padding** (int|str|tuple|list，可选) - 填充大小。如果 ``padding`` 为元组或列表，则必须包含两个整型数，分别表示竖直和水平边界填充大小。否则，表示竖直和水平边界填充大小均为 ``padding``。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考下方形状 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。默认值：0。 + - **padding** (int|str|tuple|list，可选) - 填充大小。可以是以下五种形式：（1）字符串，可以是 ``"VALID"`` 或 ``"SAME"``，表示填充算法；（2）整数，表示每个空间维度的两侧均填充 ``padding`` 大小的 0；（3）长度为 2 的列表或元组 ``[pad_h, pad_w]``，分别表示高、宽维度每一侧的填充大小；（4）长度为 4 的列表或元组，依次表示各空间维度前、后两侧的填充大小；（5）由整型对组成的列表或元组，形式为 ``[[pad_before, pad_after], ...]``，其中也包含 batch 和通道维度，这两个维度的填充必须为 ``[0, 0]`` 或 ``(0, 0)``。默认值：0。 - **output_padding** (int|list|tuple，可选) - 输出形状上一侧额外添加的大小。默认值：0。 - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的分组卷积：当 group=2，卷积核的前一半仅和输入特征图的前一半连接。卷积核的后一半仅和输入特征图的后一半连接。默认值：1。 - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核中的元素沿着高和宽的空洞。如果为单个整数，表示高和宽的空洞都等于该整数。默认值：1。 @@ -49,6 +54,14 @@ Conv2DTranspose - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"。 +关键字参数 +:::::::::::: + + - **bias** (bool，可选) - 是否添加可学习的偏置。当为 False 时，``bias_attr`` 会被强制设为 False。默认值为 True。 + - **padding_mode** (str，可选) - 填充模式，可为 ``"zeros"``、``"reflect"``、``"replicate"`` 或 ``"circular"``。默认值为 ``"zeros"``。 + - **device** (str|paddle.CPUPlace|paddle.CUDAPlace|paddle.CUDAPinnedPlace|None，可选) - 创建层参数的设备。默认值为 None。 + - **dtype** (str|paddle.dtype|None，可选) - 层参数的数据类型。默认值为 None。 + 形状 :::::::::::: diff --git a/docs/api/paddle/nn/Conv3DTranspose_cn.rst b/docs/api/paddle/nn/Conv3DTranspose_cn.rst index 5c33a963e84..7e193e263d9 100755 --- a/docs/api/paddle/nn/Conv3DTranspose_cn.rst +++ b/docs/api/paddle/nn/Conv3DTranspose_cn.rst @@ -3,8 +3,14 @@ Conv3DTranspose ------------------------------- -.. py:class:: paddle.nn.Conv3DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCDHW") +.. py:class:: paddle.nn.Conv3DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCDHW", *, bias=True, padding_mode="zeros", device=None, dtype=None) +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.nn.Conv3DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format='NCDHW', *, bias=True, padding_mode='zeros', device=None, dtype=None)``（Paddle 风格）：通过 ``weight_attr`` 和 ``bias_attr`` 指定参数。 + 2. ``paddle.nn.Conv3DTranspose(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, bias=True, dilation=1, padding_mode='zeros', device=None, dtype=None)``（PyTorch 风格）：参数顺序与 ``torch.nn.ConvTranspose3d`` 相同。 三维转置卷积层（Convolution3d transpose layer） @@ -15,20 +21,19 @@ Conv3DTranspose 输入 :math:`X` 和输出 :math:`Out` 函数关系如下： .. math:: - \\Out=\sigma (W*X+b)\\ + \\Out=W*X+b\\ 其中： - :math:`X`：输入，具有 NCDHW 或 NDHWC 格式的 5-D Tensor - - :math:`W`：卷积核，具有 NCDHW 格式的 5-D Tensor + - :math:`W`：卷积核，具有 CMDHW 格式的 5-D Tensor - :math:`*`：卷积操作（**注意**：转置卷积本质上的计算还是卷积） - :math:`b`：偏置（bias），1-D Tensor，形状为 ``[M]`` - - :math:`σ`：激活函数 - :math:`Out`：输出值，NCDHW 或 NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 .. note:: - 如果 output_size 为 None，则 :math:`H_{out}` = :math:`H^\prime_{out}` , :math:`W_{out}` = :math:`W^\prime_{out}`；否则，指定的 output_size_height（输出特征层的高） :math:`H_{out}` 应当介于 :math:`H^\prime_{out}` 和 :math:`H^\prime_{out} + strides[0]` 之间（不包含 :math:`H^\prime_{out} + strides[0]` ），并且指定的 output_size_width（输出特征层的宽） :math:`W_{out}` 应当介于 :math:`W^\prime_{out}` 和 :math:`W^\prime_{out} + strides[1]` 之间（不包含 :math:`W^\prime_{out} + strides[1]` ）。 + 如果 output_size 为 None，则 :math:`D_{out}` = :math:`D^\prime_{out}`、:math:`H_{out}` = :math:`H^\prime_{out}`、:math:`W_{out}` = :math:`W^\prime_{out}`；否则，指定的 :math:`D_{out}`、:math:`H_{out}`、:math:`W_{out}` 分别应当介于 :math:`D^\prime_{out}` 和 :math:`D^\prime_{out} + strides[0]`、:math:`H^\prime_{out}` 和 :math:`H^\prime_{out} + strides[1]`、:math:`W^\prime_{out}` 和 :math:`W^\prime_{out} + strides[2]` 之间（均不包含上界）。 由于转置卷积可以当成是卷积的反向计算，而根据卷积的输入输出计算公式来说，不同大小的输入特征层可能对应着相同大小的输出特征层，所以对应到转置卷积来说，固定大小的输入特征层对应的输出特征层大小并不唯一。 @@ -40,15 +45,23 @@ Conv3DTranspose - **in_channels** (int) - 输入图像的通道数。 - **out_channels** (int) - 卷积核的个数，和输出特征图个数相同。 - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。output_size 和 kernel_size 不能同时为 None。 - - **stride** (int|tuple，可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含三个整型数，分别表示深度，垂直和水平滑动步长。否则，表示深度，垂直和水平滑动步长均为 ``stride``。默认值为 1。 - - **padding** (int|tuple，可选) - 填充大小。如果 ``padding`` 为元组或列表，则必须包含三个整型数，分别表示深度，竖直和水平边界填充大小。否则，表示深度，竖直和水平边界填充大小均为 ``padding``。如果它是一个字符串，可以是 "VALID" 或者 "SAME" ，表示填充算法，计算细节可参考下方形状 ``padding`` = "SAME" 或 ``padding`` = "VALID" 时的计算公式。默认值为 0。 + - **stride** (int|list|tuple，可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含三个整型数，分别表示深度、垂直和水平滑动步长。否则，表示深度、垂直和水平滑动步长均为 ``stride``。默认值为 1。 + - **padding** (int|str|tuple|list，可选) - 填充大小。可以是以下五种形式：（1）字符串，可以是 ``"VALID"`` 或 ``"SAME"``，表示填充算法；（2）整数，表示每个空间维度的两侧均填充 ``padding`` 大小的 0；（3）长度为 3 的列表或元组 ``[pad_d, pad_h, pad_w]``，分别表示深度、高、宽维度每一侧的填充大小；（4）长度为 6 的列表或元组，依次表示各空间维度前、后两侧的填充大小；（5）由整型对组成的列表或元组，形式为 ``[[pad_before, pad_after], ...]``，其中也包含 batch 和通道维度，这两个维度的填充必须为 ``[0, 0]`` 或 ``(0, 0)``。默认值为 0。 - **output_padding** (int|list|tuple，可选) - 输出形状上一侧额外添加的大小。默认值为 0。 - - **groups** (int，可选) - 二维卷积层的组数。根据 `Alex Krizhevsky 的 Deep CNN 论文 `_ 中的分组卷积：当 groups = 2，卷积核的前一半仅和输入特征图的前一半连接。卷积核的后一半仅和输入特征图的后一半连接。默认值为 1。 - - **dilation** (int|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值为 1。 + - **groups** (int，可选) - 三维卷积层的组数。根据 `Alex Krizhevsky 的 Deep CNN 论文 `_ 中的分组卷积：当 groups = 2，卷积核的前一半仅和输入特征图的前一半连接。卷积核的后一半仅和输入特征图的后一半连接。默认值为 1。 + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度、高和宽的空洞。如果为单个整数，表示深度、高和宽的空洞都等于该整数。默认值为 1。 - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是 "NCDHW" 和 "NDHWC"。N 是批尺寸，C 是通道数，D 为特征深度，H 是特征高度，W 是特征宽度。默认值为 "NCDHW"。 +关键字参数 +:::::::::::: + + - **bias** (bool，可选) - 是否添加可学习的偏置。当为 False 时，``bias_attr`` 会被强制设为 False。默认值为 True。 + - **padding_mode** (str，可选) - 填充模式，可为 ``"zeros"``、``"reflect"``、``"replicate"`` 或 ``"circular"``。默认值为 ``"zeros"``。 + - **device** (str|paddle.CPUPlace|paddle.CUDAPlace|paddle.CUDAPinnedPlace|None，可选) - 创建层参数的设备。默认值为 None。 + - **dtype** (str|paddle.dtype|None，可选) - 层参数的数据类型。默认值为 None。 + 形状 :::::::::::: diff --git a/docs/api/paddle/nn/CrossEntropyLoss_cn.rst b/docs/api/paddle/nn/CrossEntropyLoss_cn.rst index fc9226d1ee4..c283662ac2b 100644 --- a/docs/api/paddle/nn/CrossEntropyLoss_cn.rst +++ b/docs/api/paddle/nn/CrossEntropyLoss_cn.rst @@ -3,9 +3,9 @@ CrossEntropyLoss ------------------------------- -.. py:class:: paddle.nn.CrossEntropyLoss(weight=None, ignore_index=-100, reduction='mean', soft_label=False, label_smoothing=0.0, axis=-1, use_softmax=True, name=None) +.. py:class:: paddle.nn.CrossEntropyLoss(weight=None, ignore_index=-100, reduction='mean', soft_label=False, axis=-1, use_softmax=True, label_smoothing=0.0, name=None) -默认情况下， CrossEntropyLoss 使用 softmax 实现（即 use_softmax=True ）。该函数结合了 softmax 操作的计算和交叉熵损失函数，以提供更稳定的数值计算。 +默认情况下， CrossEntropyLoss 使用 softmax 实现(即 use_softmax=True )。该函数结合了 softmax 操作的计算和交叉熵损失函数，以提供更稳定的数值计算。 当 use_softmax=False 时，仅计算交叉熵损失函数而不使用 softmax。 @@ -31,7 +31,7 @@ CrossEntropyLoss .. math:: \\loss_j=-\log\left({P}_{label_j}\right) , j = 1,...,N - 其中，N 是样本数，C 是类别数，P 是输入（softmax 的输出）。 + 其中，N 是样本数，C 是类别数，P 是输入(softmax 的输出)。 2. Soft label (每个样本为多个类别分配一定的概率，概率和为 1). @@ -48,7 +48,7 @@ CrossEntropyLoss .. math:: \\loss_j=-\sum_{j=0}^{C}\left({label}_j*\log\left({P}_{label_j}\right)\right) , j = 1,...,N - 其中，N 是样本数，C 是类别数，P 是输入（softmax 的输出）。 + 其中，N 是样本数，C 是类别数，P 是输入(softmax 的输出)。 @@ -111,18 +111,18 @@ CrossEntropyLoss 参数 ::::::::: - - **weight** (Tensor，可选) - 指定每个类别的权重。其默认为 ``None``。如果提供该参数的话，维度必须为 ``C`` （类别数）。数据类型为 float32 或 float64。 - - **ignore_index** (int64，可选) - 指定一个忽略的标签值，此标签值不参与计算，负值表示无需忽略任何标签值。仅在 soft_label=False 时有效。默认值为-100。数据类型为 int64。 + - **weight** (Tensor，可选) - 指定每个类别的权重。其默认为 ``None``。如果提供该参数的话，维度必须为 ``C`` (类别数)。数据类型为 float32 或 float64。 + - **ignore_index** (int，可选) - 指定一个忽略的标签值，此标签值不参与计算，负值表示无需忽略任何标签值。仅在 soft_label=False 时有效。默认值为-100。 - **reduction** (str，可选) - 指定应用于输出结果的计算方式，数据类型为 string，可选值有：``none``, ``mean``, ``sum``。默认为 ``mean``，计算 ``mini-batch`` loss 均值。设置为 ``sum`` 时，计算 ``mini-batch`` loss 的总和。设置为 ``none`` 时，则返回 loss Tensor。 - - **soft_label** (bool，可选) – 指明 label 是否为软标签。默认为 False，表示 label 为硬标签；若 soft_label=True 则表示软标签。 - - **label_smoothing** （float，可选）- 指定计算损失时的标签平滑度，它应该在 :math:`[0.0，1.0]` 范围内。其中 0.0 表示无平滑。使得平滑后的标签变成原始真实标签和均匀分布的混合，默认值： 0.0。 - - **axis** (int，可选) - 进行 softmax 计算的维度索引。它应该在 :math:`[-1，dim-1]` 范围内，而 ``dim`` 是输入 logits 的维度。默认值：-1。 + - **soft_label** (bool，可选) - 指明 label 是否为软标签。默认为 False，表示 label 为硬标签；若 soft_label=True 则表示软标签。 + - **axis** (int，可选) - 进行 softmax 计算的维度索引。它应该在 :math:`[-1, dim-1]` 范围内，而 ``dim`` 是输入 logits 的维度。默认值：-1。 - **use_softmax** (bool，可选) - 指定是否对 input 进行 softmax 归一化。默认值：True。 + - **label_smoothing** (float，可选)- 指定计算损失时的标签平滑度，它应该在 :math:`[0.0, 1.0]` 范围内。其中 0.0 表示无平滑。使得平滑后的标签变成原始真实标签和均匀分布的混合，默认值： 0.0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 ::::::::: - **input** (Tensor): 输入 ``Tensor``，数据类型为 float32 或 float64。其形状为 :math:`[N, C]`，其中 ``C`` 为类别数。对于多维度的情形下，它的形状为 :math:`[N, d_1, d_2, ..., d_k, C]` ，k >= 1。 - - **label** (Tensor): 当 soft_label=False 时，输入 input 对应的标签值，数据类型为 int64。其形状为 :math:`[N]`，每个元素符合条件：0 <= label[i] <= C-1。对于多维度的情形下，它的形状为 :math:`[N, d_1, d_2, ..., d_k]` ，k >= 1；当 soft_label=True 且没有指定 label_smoothing 时，要求 label 的维度、数据类型与 input 相同，每个样本的各标签概率和应为 1；当指定了 label_smoothing (label_smoothing > 0.0) 时， 无论 soft_label 是什么值， label 的维度和数据类型可以是前面两种情况中的任意一种。换句话说，如果 label_smoothing > 0.0， label 可以是独热标签或整数标签。 + - **label** (Tensor): 当 soft_label=False 时，输入 input 对应的标签值，数据类型为 int32、int64、float32 或 float64。其形状为 :math:`[N]`，每个元素符合条件：0 <= label[i] <= C-1。对于多维度的情形下，它的形状为 :math:`[N, d_1, d_2, ..., d_k]` ，k >= 1；当 soft_label=True 且没有指定 label_smoothing 时，要求 label 的维度、数据类型与 input 相同，每个样本的各标签概率和应为 1；当指定了 label_smoothing (label_smoothing > 0.0) 时， 无论 soft_label 是什么值， label 的维度和数据类型可以是前面两种情况中的任意一种。换句话说，如果 label_smoothing > 0.0， label 可以是独热标签或整数标签。 - **output** (Tensor): 计算 ``CrossEntropyLoss`` 交叉熵后的损失值。 diff --git a/docs/api/paddle/nn/Dropout_cn.rst b/docs/api/paddle/nn/Dropout_cn.rst index 824c3f7359f..5e8707db45f 100644 --- a/docs/api/paddle/nn/Dropout_cn.rst +++ b/docs/api/paddle/nn/Dropout_cn.rst @@ -3,7 +3,7 @@ Dropout ------------------------------- -.. py:class:: paddle.nn.Dropout(p=0.5, axis=None, mode="upscale_in_train", name=None) +.. py:class:: paddle.nn.Dropout(p=0.5, inplace=False, axis=None, mode="upscale_in_train", name=None) Dropout 是一种正则化手段，根据给定的丢弃概率 ``p``，在训练过程中随机将一些神经元输出设置为 0，通过阻止神经元节点间的相关性来减少过拟合。论文请参考：`Improving neural networks by preventing co-adaptation of feature detectors `_ @@ -14,7 +14,8 @@ Dropout 是一种正则化手段，根据给定的丢弃概率 ``p``，在训练 参数 ::::::::: - - **p** (float，可选) - 将输入节点置为 0 的概率，即丢弃概率。默认值为 0.5。 + - **p** (float|int，可选) - 将输入节点置为 0 的概率，即丢弃概率。默认值为 0.5。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **axis** (int|list|tuple，可选) - 指定对输入 ``Tensor`` 进行 Dropout 操作的轴。默认值为 None。 - **mode** (str，可选) - 丢弃单元的方式，有 'upscale_in_train' 和 'downscale_in_infer' 两种可供选择，默认值为 'upscale_in_train'。计算方法如下： diff --git a/docs/api/paddle/nn/Fold_cn.rst b/docs/api/paddle/nn/Fold_cn.rst index 7aa0ee95bbd..beda4cacbe8 100644 --- a/docs/api/paddle/nn/Fold_cn.rst +++ b/docs/api/paddle/nn/Fold_cn.rst @@ -22,17 +22,17 @@ Fold 参数 ::::::::: - - **output_sizes** (int|list|tuple) – 输出尺寸，整数或者整型列表。如为列表类型应包含两个元素 ``[output_size_h, output_size_w]``。如果为整数 o，则输出形状会被认为 ``[o, o]``。 - - **kernel_size** (int|list|tuple) - 卷积核大小，整数或者整型列表。如为列表类型应包含两个元素 ``[k_h, k_w]``。如果为整数 k，则输出形状会被认为 ``[k, k]``。 - - **strides** (int|list|tuple，可选) - 步长大小，整数或者整型列表。如为列表类型应包含两个元素 ``[stride_h, stride_w]``。如果为整数 stride，则输出形状会被认为 ``[sride, stride]``。默认为[1,1]。 - - **paddings** (int|list|tuple，可选) – 每个维度的扩展，整数或者整型列表。如果为整型列表，长度应该为 4 或者 2；长度为 4 对应的 padding 参数是：[padding_top, padding_left，padding_bottom, padding_right]，长度为 2 对应的 padding 参数是[padding_h, padding_w]，会被当作[padding_h, padding_w, padding_h, padding_w]处理。如果为整数 padding，则会被当作[padding, padding, padding, padding]处理。默认值为 0。 - - **dilations** (int|list|tuple，可选) – 卷积膨胀，整型列表或者整数。如果为整型列表，应该包含两个元素[dilation_h, dilation_w]。如果是整数 dilation，会被当作整型列表[dilation, dilation]处理。默认值为 1。 + - **output_sizes** (int|list|tuple) – 输出尺寸，整数或者整型列表。如为列表类型应包含两个元素 ``[output_size_h, output_size_w]``。如果为整数 o，则输出形状会被认为 ``[o, o]``。别名 ``output_size``。 + - **kernel_sizes** (int|list|tuple) - 卷积核大小，整数或者整型列表。如为列表类型应包含两个元素 ``[k_h, k_w]``。如果为整数 k，则输出形状会被认为 ``[k, k]``。别名 ``kernel_size``。 + - **dilations** (int|list|tuple，可选) – 卷积膨胀，整型列表或者整数。如果为整型列表，应该包含两个元素[dilation_h, dilation_w]。如果是整数 dilation，会被当作整型列表[dilation, dilation]处理。默认值为 1。别名 ``dilation``。 + - **paddings** (int|list|tuple，可选) – 每个维度的扩展，整数或者整型列表。如果为整型列表，长度应该为 4 或者 2；长度为 4 对应的 padding 参数是：[padding_top, padding_left，padding_bottom, padding_right]，长度为 2 对应的 padding 参数是[padding_h, padding_w]，会被当作[padding_h, padding_w, padding_h, padding_w]处理。如果为整数 padding，则会被当作[padding, padding, padding, padding]处理。默认值为 0。别名 ``padding``。 + - **strides** (int|list|tuple，可选) - 步长大小，整数或者整型列表。如为列表类型应包含两个元素 ``[stride_h, stride_w]``。如果为整数 stride，则输出形状会被认为 ``[stride, stride]``。默认为[1,1]。别名 ``stride``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 ::::::::: - - **输入** ：4-D Tensor，形状为[N, C_in, L]，数据类型为 float32 或者 float64 + - **输入** ：3-D Tensor，形状为[N, C_in, L]，数据类型为 float32、float64、complex64 或 complex128。 - **输出** ：形状如上面所描述的[N, Cout, H, W]，数据类型与 ``x`` 相同 diff --git a/docs/api/paddle/nn/GRU_cn.rst b/docs/api/paddle/nn/GRU_cn.rst index c9de9ccf304..23b772bb850 100644 --- a/docs/api/paddle/nn/GRU_cn.rst +++ b/docs/api/paddle/nn/GRU_cn.rst @@ -3,7 +3,14 @@ GRU ------------------------------- -.. py:class:: paddle.nn.GRU(input_size, hidden_size, num_layers=1, direction="forward", time_major=False, dropout=0.0, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, name=None) +.. py:class:: paddle.nn.GRU(input_size, hidden_size, num_layers=1, direction="forward", time_major=False, dropout=0.0, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, *, bias=True, device=None, dtype=None) + +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.nn.GRU(input_size, hidden_size, num_layers=1, direction='forward', time_major=False, dropout=0.0, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, *, bias=True, device=None, dtype=None)`` （Paddle 风格）。 + 2. ``paddle.nn.GRU(input_size, hidden_size, num_layers, bias, batch_first, dropout=0.0, bidirectional=False, device=None, dtype=None)`` （PyTorch 风格）。 @@ -42,7 +49,13 @@ GRU - **weight_hh_attr** (ParamAttr，可选) - weight_hh 的参数。默认为 None。 - **bias_ih_attr** (ParamAttr，可选) - bias_ih 的参数。默认为 None。 - **bias_hh_attr** (ParamAttr，可选) - bias_hh 的参数。默认为 None。 - - **name** (str，可选) - 操作的名称(可选，默认为 None)。欲了解更多信息，请参考 :ref:`api_guide_Name` + +关键字参数 +:::::::::::: + + - **bias** (bool，可选) - 若为 False，层不使用偏置权重 ``bias_ih`` 和 ``bias_hh``。默认值为 True。 + - **device** (str，可选) - 层参数所在设备。默认值为 None。 + - **dtype** (str，可选) - 层参数的数据类型。默认值为 None。 输入 :::::::::::: diff --git a/docs/api/paddle/nn/Hardsigmoid_cn.rst b/docs/api/paddle/nn/Hardsigmoid_cn.rst index bae3b0144ce..15ab10021f5 100644 --- a/docs/api/paddle/nn/Hardsigmoid_cn.rst +++ b/docs/api/paddle/nn/Hardsigmoid_cn.rst @@ -3,7 +3,7 @@ Hardsigmoid ------------------------------- -.. py:class:: paddle.nn.Hardsigmoid(name=None) +.. py:class:: paddle.nn.Hardsigmoid(inplace=False, name=None) Hardsigmoid 激活层，用于创建一个 ``Hardsigmoid`` 类的可调用对象。sigmoid 的分段线性逼近激活函数，速度比 sigmoid 快，详细解释参见 `Noisy Activation Functions `_ 。 @@ -23,12 +23,13 @@ Hardsigmoid 激活层，用于创建一个 ``Hardsigmoid`` 类的可调用对象 参数 :::::::::: + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 :::::::::: - - input：任意形状的 Tensor。 - - output：和 input 具有相同形状的 Tensor。 + - input：任意形状、数据类型为 float32 或 float64 的 Tensor。 + - output：和 input 具有相同形状和数据类型的 Tensor。 代码示例 :::::::::: diff --git a/docs/api/paddle/nn/LSTMCell_cn.rst b/docs/api/paddle/nn/LSTMCell_cn.rst index 8e352cf7e41..3717270bb2c 100644 --- a/docs/api/paddle/nn/LSTMCell_cn.rst +++ b/docs/api/paddle/nn/LSTMCell_cn.rst @@ -3,7 +3,7 @@ LSTMCell ------------------------------- -.. py:class:: paddle.nn.LSTMCell(input_size, hidden_size, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, proj_size=0, name=None) +.. py:class:: paddle.nn.LSTMCell(input_size, hidden_size, *, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, proj_size=0, bias=True, device=None, dtype=None, name=None) @@ -41,11 +41,18 @@ LSTMCell - **input_size** (int) - 输入的大小。 - **hidden_size** (int) - 隐藏状态大小。 + +关键字参数 +:::::::::::: + - **weight_ih_attr** (ParamAttr，可选) - weight_ih 的参数。默认为 None。 - **weight_hh_attr** (ParamAttr，可选) - weight_hh 的参数。默认为 None。 - **bias_ih_attr** (ParamAttr，可选) - bias_ih 的参数。默认为 None。 - **bias_hh_attr** (ParamAttr，可选) - bias_hh 的参数。默认为 None。 - **proj_size** (int，可选) - 若大于 0，则会使用投影层将隐状态隐射到指定大小，其值必须小于 ``hidden_size`` 。默认为 0。 + - **bias** (bool，可选) - 是否使用偏置权重 ``bias_ih`` 和 ``bias_hh``。若为 False，则不使用偏置权重。默认值为 True。 + - **device** (str，可选) - 层参数所在设备。默认值为 None。 + - **dtype** (str，可选) - 层参数的数据类型。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 变量 @@ -53,6 +60,7 @@ LSTMCell - **weight_ih** (Parameter) - input 到 hidden 的变换矩阵的权重。形状为（4 * hidden_size, input_size）。对应公式中的 :math:`W_{ii}, W_{if}, W_{ig}, W_{io}`。 - **weight_hh** (Parameter) - hidden 到 hidden 的变换矩阵的权重。形状为（4 * hidden_size, hidden_size）。对应公式中的 :math:`W_{hi}, W_{hf}, W_{hg}, W_{ho}`。 + - **weight_ho** (Parameter) - hidden 到 output 的变换矩阵的权重。 - **bias_ih** (Parameter) - input 到 hidden 的变换矩阵的偏置。形状为（4 * hidden_size, ）。对应公式中的 :math:`b_{ii}, b_{if}, b_{ig}, b_{io}`。 - **bias_hh** (Parameter) - hidden 到 hidden 的变换矩阵的偏置。形状为（4 * hidden_size, ）。对应公式中的 :math:`b_{hi}, b_{hf}, b_{hg}, b_{ho}`。 @@ -60,7 +68,7 @@ LSTMCell :::::::::::: - **inputs** (Tensor) - 输入。形状为[batch_size, input_size]，对应公式中的 :math:`x_t`。 - - **states** (tuple，可选) - 一个包含两个 Tensor 的元组，每个 Tensor 的形状都为[batch_size, hidden_size]，上一轮的隐藏状态。对应公式中的 :math:`h_{t-1}，c_{t-1}`。当 state 为 None 的时候，初始状态为全 0 矩阵。默认为 None。 + - **states** (tuple，可选) - 一个包含两个 Tensor 的元组，每个 Tensor 的形状都为[batch_size, hidden_size]，上一轮的隐藏状态。对应公式中的 :math:`h_{t-1}，c_{t-1}`。当 states 为 None 的时候，初始状态为全 0 矩阵。默认为 None。 输出 :::::::::::: diff --git a/docs/api/paddle/nn/LSTM_cn.rst b/docs/api/paddle/nn/LSTM_cn.rst index d5bc6695858..ed05fa88e06 100644 --- a/docs/api/paddle/nn/LSTM_cn.rst +++ b/docs/api/paddle/nn/LSTM_cn.rst @@ -3,7 +3,7 @@ LSTM ------------------------------- -.. py:class:: paddle.nn.LSTM(input_size, hidden_size, num_layers=1, direction="forward", dropout=0., time_major=False, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, proj_size=0, name=None) +.. py:class:: paddle.nn.LSTM(input_size, hidden_size, num_layers=1, *, direction="forward", time_major=False, dropout=0., weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, proj_size=0, bias=True, device=None, dtype=None, name=None) @@ -42,8 +42,12 @@ LSTM - **input_size** (int) - 输入 :math:`x` 的大小。 - **hidden_size** (int) - 隐藏状态 :math:`h` 大小。 - - **num_layers** (int，可选) - 循环网络的层数。例如，将层数设为 2，会将两层 GRU 网络堆叠在一起，第二层的输入来自第一层的输出。默认为 1。 - - **direction** (str，可选) - 网络迭代方向，可设置为 forward 或 bidirect（或 bidirectional）。forward 指从序列开始到序列结束的单向 GRU 网络方向，bidirectional 指从序列开始到序列结束，又从序列结束到开始的双向 GRU 网络方向。默认为 forward。 + - **num_layers** (int，可选) - 循环网络的层数。例如，将层数设为 2，会将两层 LSTM 网络堆叠在一起，第二层的输入来自第一层的输出。默认为 1。 + +关键字参数 +:::::::::::: + + - **direction** (str，可选) - 网络迭代方向，可设置为 forward 或 bidirect（或 bidirectional）。forward 指从序列开始到序列结束的单向 LSTM 网络方向，bidirectional 指从序列开始到序列结束，又从序列结束到开始的双向 LSTM 网络方向。默认为 forward。 - **time_major** (bool，可选) - 指定 input 的第一个维度是否是 time steps。如果 time_major 为 True，则 Tensor 的形状为[time_steps, batch_size, input_size]，否则为[batch_size, time_steps, input_size]。``time_steps`` 指输入序列的长度。默认为 False。 - **dropout** (float，可选) - dropout 概率，指的是除第一层外每层输入时的 dropout 概率。范围为[0, 1]。默认为 0。 - **weight_ih_attr** (ParamAttr，可选) - weight_ih 的参数。默认为 None。 @@ -51,13 +55,16 @@ LSTM - **bias_ih_attr** (ParamAttr，可选) - bias_ih 的参数。默认为 None。 - **bias_hh_attr** (ParamAttr，可选) - bias_hh 的参数。默认为 None。 - **proj_size** (int，可选) - 若大于 0，则会使用投影层将隐状态隐射到指定大小，其值必须小于 ``hidden_size`` 。默认为 0。 + - **bias** (bool，可选) - 是否使用偏置权重 ``bias_ih`` 和 ``bias_hh``。若为 False，则不使用偏置权重。默认值为 True。 + - **device** (str，可选) - 层参数所在设备。默认值为 None。 + - **dtype** (str，可选) - 层参数的数据类型。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 输入 :::::::::::: - **inputs** (Tensor) - 网络输入。如果 time_major 为 True，则 Tensor 的形状为[time_steps,batch_size,input_size]，如果 time_major 为 False，则 Tensor 的形状为[batch_size,time_steps,input_size]。``time_steps`` 指输入序列的长度。 - - **initial_states** (tuple，可选) - 网络的初始状态，一个包含 h 和 c 的元组，形状为[num_layers * num_directions, batch_size, hidden_size]。如果没有给出则会以全零初始化。 + - **initial_states** (list|tuple，可选) - 网络的初始状态，一个包含 h 和 c 的列表或元组，形状为[num_layers * num_directions, batch_size, hidden_size]。如果没有给出则会以全零初始化。 - **sequence_length** (Tensor，可选) - 指定输入序列的实际长度，形状为[batch_size]，数据类型为 int64 或 int32。在输入序列中所有 time step 不小于 sequence_length 的元素都会被当作填充元素处理（状态不再更新）。 输出 diff --git a/docs/api/paddle/nn/MarginRankingLoss_cn.rst b/docs/api/paddle/nn/MarginRankingLoss_cn.rst index 9c0631c0ddb..e1371f5185a 100644 --- a/docs/api/paddle/nn/MarginRankingLoss_cn.rst +++ b/docs/api/paddle/nn/MarginRankingLoss_cn.rst @@ -26,13 +26,13 @@ MarginRankingLoss 参数 :::::::: - - **margin** （float，可选） - 用于加和的 margin 值，默认值为 0。 - - **reduction** （string，可选） - 指定应用于输出结果的计算方式，可选值有：``none`` 、 ``mean`` 、 ``sum``。如果设置为 ``none``，则直接返回 最原始的 ``margin_rank_loss``。如果设置为 ``sum``，则返回 ``margin_rank_loss`` 的总和。如果设置为 ``mean``，则返回 ``margin_rank_loss`` 的平均值。默认值为 ``none`` 。 + - **margin** (float，可选) - 用于加和的 margin 值，默认值为 0。 + - **reduction** (string，可选) - 指定应用于输出结果的计算方式，可选值有：``none`` 、 ``mean`` 、 ``sum``。如果设置为 ``none``，则直接返回 最原始的 ``margin_rank_loss``。如果设置为 ``sum``，则返回 ``margin_rank_loss`` 的总和。如果设置为 ``mean``，则返回 ``margin_rank_loss`` 的平均值。默认值为 ``mean`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 :::::::: - - **input** ：N-D Tensor，维度是[N，*] 其中 N 是 batch size，``*`` 是任意数量的额外维度，数据类型为 float32 或 float64。 + - **input** ：N-D Tensor，维度是[N, \*] 其中 N 是 batch size，``*`` 是任意数量的额外维度，数据类型为 float32 或 float64。 - **other** ：与 input 的形状、数据类型相同。 - **label** ：与 input 的形状、数据类型相同。 - **output** ：如果 :attr:`reduction` 为 ``'sum'`` 或者是 ``'mean'``，则形状为 :math:`[]`，否则 shape 和输入 ``input`` 保持一致。数据类型与 ``input``、 ``other`` 相同。 diff --git a/docs/api/paddle/nn/Mish_cn.rst b/docs/api/paddle/nn/Mish_cn.rst index 79d99a846aa..3c7c48d583b 100644 --- a/docs/api/paddle/nn/Mish_cn.rst +++ b/docs/api/paddle/nn/Mish_cn.rst @@ -2,7 +2,7 @@ Mish ------------------------------- -.. py:class:: paddle.nn.Mish(name=None) +.. py:class:: paddle.nn.Mish(inplace=False, name=None) Mish 激活层 @@ -18,6 +18,7 @@ Mish 激活层 参数 :::::::::: + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/ModuleDict_cn.rst b/docs/api/paddle/nn/ModuleDict_cn.rst index 3b62ffe8f2b..60c9ebc513a 100644 --- a/docs/api/paddle/nn/ModuleDict_cn.rst +++ b/docs/api/paddle/nn/ModuleDict_cn.rst @@ -3,7 +3,7 @@ ModuleDict ------------------------------- -.. py:class:: paddle.nn.ModuleDict(modules=None) +.. py:class:: paddle.nn.ModuleDict(sublayers=None) @@ -11,12 +11,12 @@ ModuleDict ModuleDict 用于保存子层到有序字典中，它包含的子层将被正确地注册和添加。列表中的子层可以像常规 python 有序字典一样被访问。 .. note:: - ``LayerDict`` 是 ``ModuleDict`` 的别名，两者在使用和功能上完全等价。 + ``ModuleDict`` 是 ``LayerDict`` 的别名，两者在使用和功能上完全等价。 参数 :::::::::::: - - **modules** (ModuleDict|OrderedDict|list[(key, Module)]，可选) - 键值对的可迭代对象，值的类型为 ``paddle.nn.Module`` 。 + - **sublayers** (ModuleDict|OrderedDict|list[(key, Module)]，可选) - 键值对的可迭代对象，值的类型为 ``paddle.nn.Module`` 。 代码示例 @@ -27,7 +27,7 @@ COPY-FROM: paddle.nn.ModuleDict 方法 :::::::::::: clear() -''''''''' +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 清除 ModuleDict 中所有的子层。 @@ -39,8 +39,8 @@ clear() COPY-FROM: paddle.nn.ModuleDict.clear -pop() -''''''''' +pop(key) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 移除 ModuleDict 中的键 并且返回该键对应的子层。 @@ -53,7 +53,7 @@ pop() COPY-FROM: paddle.nn.ModuleDict.pop keys() -''''''''' +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 返回 ModuleDict 中键的可迭代对象。 @@ -66,7 +66,7 @@ keys() COPY-FROM: paddle.nn.ModuleDict.keys items() -''''''''' +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 返回 ModuleDict 中键/值对的可迭代对象。 @@ -80,7 +80,7 @@ COPY-FROM: paddle.nn.ModuleDict.items values() -''''''''' +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 返回 ModuleDict 中值的可迭代对象。 @@ -93,14 +93,14 @@ values() COPY-FROM: paddle.nn.ModuleDict.values -update() -''''''''' +update(sublayers) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 更新子层中的键/值对到 ModuleDict 中，会覆盖已经存在的键。 **参数** - - **modules** (ModuleDict|OrderedDict|list[(key, Module)]) - 键值对的可迭代对象，值的类型为 ``paddle.nn.Module`` 。 + - **sublayers** (ModuleDict|OrderedDict|list[(key, Module)]) - 键值对的可迭代对象，值的类型为 ``paddle.nn.Module``。别名 ``modules``。 **代码示例** diff --git a/docs/api/paddle/nn/ModuleList_cn.rst b/docs/api/paddle/nn/ModuleList_cn.rst index e23b73ea74f..011933b63fb 100644 --- a/docs/api/paddle/nn/ModuleList_cn.rst +++ b/docs/api/paddle/nn/ModuleList_cn.rst @@ -3,7 +3,7 @@ ModuleList ------------------------------- -.. py:class:: paddle.nn.ModuleList(modules=None) +.. py:class:: paddle.nn.ModuleList(sublayers=None) @@ -11,12 +11,12 @@ ModuleList ModuleList 用于保存子层列表，它包含的子层将被正确地注册和添加。列表中的子层可以像常规 python 列表一样被索引。 .. note:: - ``LayerList`` 是 ``ModuleList`` 的别名，两者在使用和功能上完全等价。 + ``ModuleList`` 是 ``LayerList`` 的别名，两者在使用和功能上完全等价。 参数 :::::::::::: - - **modules** (iterable，可选) - 要保存的子层。 + - **sublayers** (iterable，可选) - 要保存的子层。 代码示例 @@ -26,41 +26,41 @@ COPY-FROM: paddle.nn.ModuleList 方法 :::::::::::: -append() -''''''''' +append(sublayer) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 添加一个子层到整个 list 的最后。 **参数** - - **modules** (Module) - 要添加的子层。 + - **sublayer** (Module) - 要添加的子层。别名 ``module``。 **代码示例** COPY-FROM: paddle.nn.ModuleList.append -insert() -''''''''' +insert(index, sublayer) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 向 list 中插入一个子层，到给定的 index 前面。 **参数** - **index** (int) - 要插入的位置。 - - **module** (Module) - 要插入的子层。 + - **sublayer** (Module) - 要插入的子层。别名 ``module``。 **代码示例** COPY-FROM: paddle.nn.ModuleList.insert -extend() -''''''''' +extend(sublayers) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 添加多个子层到整个 list 的最后。 **参数** - - **modules** (iterable of Module) - 要添加的所有子层。 + - **sublayers** (iterable of Module) - 要添加的所有子层。别名 ``modules``。 **代码示例** diff --git a/docs/api/paddle/nn/RReLU_cn.rst b/docs/api/paddle/nn/RReLU_cn.rst index 7ccebed62f4..14dd464101b 100644 --- a/docs/api/paddle/nn/RReLU_cn.rst +++ b/docs/api/paddle/nn/RReLU_cn.rst @@ -2,7 +2,7 @@ RReLU ------------------------------- -.. py:class:: paddle.nn.RReLU(lower=0.125, upper=0.3333333333333333, name=None) +.. py:class:: paddle.nn.RReLU(lower=0.125, upper=0.3333333333333333, inplace=False, name=None) RReLU 激活层，应用随机纠正线性单元对神经元激活，参考论文： `Empirical Evaluation of Rectified Activations in Convolutional Network `_ 。 @@ -39,6 +39,7 @@ RReLU 激活层，应用随机纠正线性单元对神经元激活，参考论 :::::::::: - **lower** (float，可选) - 负值斜率的随机值范围下限，``lower`` 包含在范围中。支持的数据类型：float。默认值为 0.125。 - **upper** (float，可选) - 负值斜率的随机值范围上限，``upper`` 包含在范围中。支持的数据类型：float。默认值为 0.3333333333333333。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/SELU_cn.rst b/docs/api/paddle/nn/SELU_cn.rst index f579917fc67..f4d8f9ff59c 100644 --- a/docs/api/paddle/nn/SELU_cn.rst +++ b/docs/api/paddle/nn/SELU_cn.rst @@ -2,7 +2,7 @@ SELU ------------------------------- -.. py:class:: paddle.nn.SELU(scale=1.0507009873554804934193349852946, alpha=1.6732632423543772848170429916717, name=None) +.. py:class:: paddle.nn.SELU(scale=1.0507009873554804934193349852946, alpha=1.6732632423543772848170429916717, inplace=False, name=None) SELU 激活层 @@ -20,6 +20,7 @@ SELU 激活层 :::::::::: - **scale** (float，可选) - SELU 激活计算公式中的 scale 值，必须大于 1.0。默认值为 1.0507009873554804934193349852946。 - **alpha** (float，可选) - SELU 激活计算公式中的 alpha 值，必须大于等于零。默认值为 1.6732632423543772848170429916717。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/Silu_cn.rst b/docs/api/paddle/nn/Silu_cn.rst index 7c7d29a2895..20f246dd186 100644 --- a/docs/api/paddle/nn/Silu_cn.rst +++ b/docs/api/paddle/nn/Silu_cn.rst @@ -2,7 +2,7 @@ Silu ------------------------------- -.. py:class:: paddle.nn.Silu(name=None) +.. py:class:: paddle.nn.Silu(inplace=False, name=None) Silu 激活层。计算公式如下： @@ -15,6 +15,7 @@ Silu 激活层。计算公式如下： 参数 :::::::::: + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/SimpleRNN_cn.rst b/docs/api/paddle/nn/SimpleRNN_cn.rst index 5b352292448..d8f6dacdebd 100644 --- a/docs/api/paddle/nn/SimpleRNN_cn.rst +++ b/docs/api/paddle/nn/SimpleRNN_cn.rst @@ -3,7 +3,7 @@ SimpleRNN ------------------------------- -.. py:class:: paddle.nn.SimpleRNN(input_size, hidden_size, num_layers=1, activation="tanh", direction="forward", dropout=0., time_major=False, weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None) +.. py:class:: paddle.nn.SimpleRNN(input_size, hidden_size, num_layers=1, direction="forward", time_major=False, dropout=0., activation="tanh", weight_ih_attr=None, weight_hh_attr=None, bias_ih_attr=None, bias_hh_attr=None, name=None) @@ -25,14 +25,15 @@ SimpleRNN - **input_size** (int) - 输入 :math:`x` 的大小。 - **hidden_size** (int) - 隐藏状态 :math:`h` 大小。 - **num_layers** (int，可选) - 循环网络的层数。例如，将层数设为 2，会将两层 GRU 网络堆叠在一起，第二层的输入来自第一层的输出。默认为 1。 - - **direction** (str，可选) - 网络迭代方向，可设置为 forward 或 bidirect（或 bidirectional）。forward 指从序列开始到序列结束的单向 GRU 网络方向，bidirectional 指从序列开始到序列结束，又从序列结束到开始的双向 GRU 网络方向。默认为 forward。 + - **direction** (str，可选) - 网络迭代方向，可设置为 forward 或 bidirect（或 bidirectional）。forward 指从序列开始到序列结束的单向 SimpleRNN 网络方向，bidirectional 指从序列开始到序列结束，又从序列结束到开始的双向 SimpleRNN 网络方向。默认为 forward。 - **time_major** (bool，可选) - 指定 input 的第一个维度是否是 time steps。如果 time_major 为 True，则 Tensor 的形状为[time_steps,batch_size,input_size]，否则为[batch_size,time_steps,input_size]。``time_steps`` 指输入序列的长度。默认为 False。 - - **dropout** (float，可选) - dropout 概率，指的是出第一层外每层输入时的 dropout 概率。范围为[0, 1]。默认为 0。 + - **dropout** (float，可选) - dropout 概率，指的是除第一层外每层输入时的 dropout 概率。范围为[0, 1]。默认为 0。 - **activation** (str，可选) - 网络中每个单元的激活函数。可以是 tanh 或 relu。默认为 tanh。 - **weight_ih_attr** (ParamAttr，可选) - weight_ih 的参数。默认为 None。 - **weight_hh_attr** (ParamAttr，可选) - weight_hh 的参数。默认为 None。 - **bias_ih_attr** (ParamAttr，可选) - bias_ih 的参数。默认为 None。 - **bias_hh_attr** (ParamAttr，可选) - bias_hh 的参数。默认为 None。 + - **name** (str，可选) - 操作名称。默认值为 None。具体用法请参见 :ref:`api_guide_Name`。 输入 :::::::::::: diff --git a/docs/api/paddle/nn/SpectralNorm_cn.rst b/docs/api/paddle/nn/SpectralNorm_cn.rst index 0421a9c00b3..8d5d5cacc95 100644 --- a/docs/api/paddle/nn/SpectralNorm_cn.rst +++ b/docs/api/paddle/nn/SpectralNorm_cn.rst @@ -3,7 +3,7 @@ SpectralNorm ------------------------------- -.. py:class:: paddle.nn.SpectralNorm(weight_shape, dim=0, power_iters=1, eps=1e-12, name=None, dtype="float32") +.. py:class:: paddle.nn.SpectralNorm(weight_shape, dim=0, power_iters=1, eps=1e-12, dtype="float32") 构建 ``SpectralNorm`` 类的一个可调用对象，具体用法参照 ``代码示例``。其中实现了谱归一化层的功能，用于计算 fc、conv1d、conv2d、conv3d 层的权重参数的谱正则值，输入权重参数应分别为 2-D, 3-D, 4-D, 5-D Tensor，输出 Tensor 与输入 Tensor 维度相同。谱特征值计算方式如下： @@ -17,7 +17,7 @@ SpectralNorm \mathbf{v} &:= \frac{\mathbf{W}^{T} \mathbf{u}}{\|\mathbf{W}^{T} \mathbf{u}\|_2}\\ \mathbf{u} &:= \frac{\mathbf{W}^{T} \mathbf{v}}{\|\mathbf{W}^{T} \mathbf{v}\|_2} -步骤 3：计算 :math:`\sigma(\mathbf{W})` 并特征值值归一化。 +步骤 3：计算 :math:`\sigma(\mathbf{W})` 并特征值归一化。 .. math:: \sigma(\mathbf{W}) &= \mathbf{u}^{T} \mathbf{W} \mathbf{v}\\ @@ -32,7 +32,6 @@ SpectralNorm - **dim** (int，可选) - 将输入（weight）重塑为矩阵之前应排列到第一个的维度索引，如果 input（weight）是 fc 层的权重，则应设置为 0；如果 input（weight）是 conv 层的权重，则应设置为 1。默认值：0。 - **power_iters** (int，可选) - 将用于计算的 ``SpectralNorm`` 功率迭代次数，默认值：1。 - **eps** (float，可选) - ``eps`` 用于保证计算规范中的数值稳定性，分母会加上 ``eps`` 防止除零。默认值：1e-12。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 数据类型，可以为"float32"或"float64"。默认值为"float32"。 形状 diff --git a/docs/api/paddle/nn/Swish_cn.rst b/docs/api/paddle/nn/Swish_cn.rst index 84728d0fa7c..132a510c4e4 100644 --- a/docs/api/paddle/nn/Swish_cn.rst +++ b/docs/api/paddle/nn/Swish_cn.rst @@ -2,7 +2,7 @@ Swish ------------------------------- -.. py:class:: paddle.nn.Swish(name=None) +.. py:class:: paddle.nn.Swish(inplace=False, name=None) Swish 激活层 @@ -14,6 +14,7 @@ Swish 激活层 参数 :::::::::: + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/SyncBatchNorm_cn.rst b/docs/api/paddle/nn/SyncBatchNorm_cn.rst index 494cd1ddb63..16a169bbec6 100644 --- a/docs/api/paddle/nn/SyncBatchNorm_cn.rst +++ b/docs/api/paddle/nn/SyncBatchNorm_cn.rst @@ -3,7 +3,7 @@ SyncBatchNorm ------------------------------- -.. py:class:: paddle.nn.SyncBatchNorm(num_features, epsilon=1e-5, momentum=0.9, weight_attr=None, bias_attr=None, data_format='NCHW', name=None) +.. py:class:: paddle.nn.SyncBatchNorm(num_features, momentum=0.9, epsilon=1e-5, weight_attr=None, bias_attr=None, data_format='NCHW', name=None) 构建 ``SyncBatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例``。实现了跨卡 GPU 同步的批归一化(Cross-GPU Synchronized Batch Normalization Layer)的功能，可用在其他层（类似卷积层和全连接层）之后进行归一化操作。根据所有 GPU 同一批次的数据按照通道计算的均值和方差进行归一化。更多详情请参考：`Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ @@ -42,10 +42,12 @@ SyncBatchNorm :::::::::::: - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 - - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var``。默认值：0.9。更新公式如上所示。 - - **weight_attr** (ParamAttr|bool，可选) - 指定权重参数属性的对象。如果设置为 ``False``，则表示本层没有可训练的权重参数。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。如果设置为 ``False``，则表示本层没有可训练的偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **weight_attr** (ParamAttr|bool|None，可选) - 指定权重参数属性的对象。如果设置为 ``False``，则表示本层没有可训练的权重参数。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool|None，可选) - 指定偏置参数属性的对象。如果设置为 ``False``，则表示本层没有可训练的偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入数据格式，可选值为 ``"NCHW"`` 或 ``"NHWC"``。其中 N 为批尺寸，C 为特征图的通道数，H 为特征图高度，W 为特征图宽度。默认值为 ``"NCHW"``。 + - **name** (str，可选) - BatchNorm 的名称，默认值为 None。具体用法请参见 :ref:`api_guide_Name`。 形状 :::::::::::: diff --git a/docs/api/paddle/nn/ThresholdedReLU_cn.rst b/docs/api/paddle/nn/ThresholdedReLU_cn.rst index df16432fdbf..b9a5ff203ae 100644 --- a/docs/api/paddle/nn/ThresholdedReLU_cn.rst +++ b/docs/api/paddle/nn/ThresholdedReLU_cn.rst @@ -2,7 +2,7 @@ ThresholdedReLU ------------------------------- -.. py:class:: paddle.nn.ThresholdedReLU(threshold=1.0, name=None) +.. py:class:: paddle.nn.ThresholdedReLU(threshold=1.0, value=0.0, name=None) Thresholded ReLU 激活层 From 190417e1e352dd1f0e064aacb1c6d61f29d41c4d Mon Sep 17 00:00:00 2001 From: manfredss Date: Mon, 17 Aug 2026 21:03:28 +0800 Subject: [PATCH 18/18] add 15 more apis --- .../paddle/nn/functional/avg_pool2d_cn.rst | 4 +-- .../paddle/nn/functional/avg_pool3d_cn.rst | 6 ++-- docs/api/paddle/nn/functional/celu_cn.rst | 5 +-- .../nn/functional/conv2d_transpose_cn.rst | 19 +++++------ .../paddle/nn/functional/cross_entropy_cn.rst | 34 ++++++++++++++----- .../api/paddle/nn/functional/dropout1d_cn.rst | 6 ++-- .../api/paddle/nn/functional/dropout3d_cn.rst | 3 +- docs/api/paddle/nn/functional/fold_cn.rst | 12 +++---- .../paddle/nn/functional/hardsigmoid_cn.rst | 5 +-- .../api/paddle/nn/functional/lp_pool2d_cn.rst | 12 +++++-- .../nn/functional/margin_cross_entropy_cn.rst | 10 +++--- .../nn/functional/margin_ranking_loss_cn.rst | 8 ++--- docs/api/paddle/nn/functional/mish_cn.rst | 3 +- .../api/paddle/nn/functional/normalize_cn.rst | 9 ++--- docs/api/paddle/nn/functional/one_hot_cn.rst | 7 ++-- 15 files changed, 86 insertions(+), 57 deletions(-) diff --git a/docs/api/paddle/nn/functional/avg_pool2d_cn.rst b/docs/api/paddle/nn/functional/avg_pool2d_cn.rst index 5833c6bab95..22d02d95f6e 100644 --- a/docs/api/paddle/nn/functional/avg_pool2d_cn.rst +++ b/docs/api/paddle/nn/functional/avg_pool2d_cn.rst @@ -23,11 +23,11 @@ avg_pool2d 参数 ::::::::: - - **x** (Tensor)：形状为 ``[N,C,H,W]`` 或 ``[N,H,W,C]`` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float32 或 float64。 + - **x** (Tensor)：形状为 ``[N,C,H,W]`` 或 ``[N,H,W,C]`` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float16、float32、float64 或 uint16。 - **kernel_size** (int|list|tuple)：池化核大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_size_Height, pool_size_Width)。若为一个整数，则它的平方值将作为池化核大小，比如若 pool_size=2，则池化核大小为 2x2。 - **stride** (int|list|tuple)：池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 kernel_size。 - **padding** (str|int|list|tuple，可选) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。 - - **ceil_mode** (bool)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 ``ceil`` 计算输出形状的大小。默认为 None + - **ceil_mode** (bool)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 ``ceil`` 计算输出形状的大小。默认为 False。 - **exclusive** (bool)：是否在平均池化模式忽略填充值，默认是 ``True``。 - **divisor_override** (int|float)：如果指定，它将用作除数，否则根据 ``kernel_size`` 计算除数。默认 ``None``。 - **data_format** (str)：输入和输出的数据格式，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW" diff --git a/docs/api/paddle/nn/functional/avg_pool3d_cn.rst b/docs/api/paddle/nn/functional/avg_pool3d_cn.rst index d71c85d179e..1cb0047a492 100644 --- a/docs/api/paddle/nn/functional/avg_pool3d_cn.rst +++ b/docs/api/paddle/nn/functional/avg_pool3d_cn.rst @@ -16,7 +16,7 @@ avg_pool3d kernel_size: :math:`[KD, KH, KW]` stride: :math:`stride` 输出： - Out 形状：:math:`\left ( N,C, D_{in}, H_{out},W_{out} \right )` + Out 形状：:math:`\left ( N,C, D_{out}, H_{out},W_{out} \right )` .. math:: \text{out}(N_i, C_j, d, h, w) ={} & \sum_{k=0}^{kD-1} \sum_{m=0}^{kH-1} \sum_{n=0}^{kW-1} \\ & \frac{\text{input}(N_i, C_j, \text{stride}[0] \times d + k, @@ -28,12 +28,12 @@ avg_pool3d ::::::::: - **x** (Tensor)：形状为 [N,C,D,H,W] 或 [N,D,H,W,C] 的 5-D Tensor，N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度，数据类型为 float16、float32 或 float64。 - **kernel_size** (int|list|tuple)：池化核大小。如果它是一个元组或列表，它必须包含三个整数值，(pool_size_Depth, pool_size_Height, pool_size_Width)。若为一个整数，则表示 D，H 和 W 维度上均为该值，比如若 pool_size=2，则池化核大小为[2,2,2]。 - - **stride** (int|list|tuple)：池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 kernel_size。 + - **stride** (int|list|tuple)：池化层的步长。如果它是一个元组或列表，它将包含三个整数，(stride_Depth, stride_Height, stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 kernel_size。 - **padding** (string|int|list|tuple) 池化填充。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 3 个整数值：[pad_depth, pad_height, pad_width]；(2)包含 6 个整数值：[pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 5 个二元组：当 data_format 为"NCDHW"时为[[0,0], [0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NDHWC"时为[[0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 D、H 和 W 维度上均为该值。默认值：0。 - **ceil_mode** (bool)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 ``ceil`` 计算输出形状的大小。默认为 False - **exclusive** (bool)：是否在平均池化模式忽略填充值，默认是 ``True``。 - **divisor_override** (int|float)：如果指定，它将用作除数，否则根据 ``kernel_size`` 计算除数。默认 ``None``。 - - **data_format** (str)：输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。默认值："NDCHW"。 + - **data_format** (str)：输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。默认值："NCDHW"。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/nn/functional/celu_cn.rst b/docs/api/paddle/nn/functional/celu_cn.rst index 75e477dfaa6..8dd186a25ca 100644 --- a/docs/api/paddle/nn/functional/celu_cn.rst +++ b/docs/api/paddle/nn/functional/celu_cn.rst @@ -3,7 +3,7 @@ celu ------------------------------- -.. py:function:: paddle.nn.functional.celu(x, alpha=1.0, name=None) +.. py:function:: paddle.nn.functional.celu(x, alpha=1.0, inplace=False, name=None) celu 激活层（CELU Activation Operator） @@ -11,7 +11,7 @@ celu 激活层（CELU Activation Operator） .. math:: - celu(x) = max(0, x) + min(0, \alpha * (e^{x/\alpha} − 1)) + celu(x) = max(0, x) + min(0, \alpha * (e^{x/\alpha} - 1)) 其中，:math:`x` 为输入的 Tensor。 @@ -19,6 +19,7 @@ celu 激活层（CELU Activation Operator） :::::::::: - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float16、float32、float64。 - **alpha** (float，可选) - celu 的 alpha 值，默认值为 1.0。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/conv2d_transpose_cn.rst b/docs/api/paddle/nn/functional/conv2d_transpose_cn.rst index df16f00c23b..b8625ef6747 100644 --- a/docs/api/paddle/nn/functional/conv2d_transpose_cn.rst +++ b/docs/api/paddle/nn/functional/conv2d_transpose_cn.rst @@ -4,13 +4,13 @@ conv2d_transpose ------------------------------- -.. py:function:: paddle.nn.functional.conv2d_transpose(x, weight, bias=None, stride=1, padding=0, output_padding=0, groups=1, dilation=1, data_format='NCHW', output_size=None, name=None) +.. py:function:: paddle.nn.functional.conv2d_transpose(x, weight, bias=None, stride=1, padding=0, output_padding=0, groups=1, dilation=1, output_size=None, data_format='NCHW', name=None) 二维转置卷积层（Convolution2D transpose layer） -该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过 output_size 指定输出特征层大小。输入(Input)和输出(Output)为 NCHW 或 NHWC 格式，其中 N 为批尺寸，C 为通道数（channel），H 为特征层高度，W 为特征层宽度。卷积核是 MCHW 格式，M 是输出图像通道数，C 是输入图像通道数，H 是卷积核高度，W 是卷积核宽度。如果组数大于 1，C 等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 参考文献_。如果参数 bias_attr 不为 False，转置卷积计算会添加偏置项。如果 act 不为 None，则转置卷积计算之后添加相应的激活函数。 +该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过 output_size 指定输出特征层大小。输入(Input)和输出(Output)为 NCHW 或 NHWC 格式，其中 N 为批尺寸，C 为通道数（channel），H 为特征层高度，W 为特征层宽度。卷积核是 CMHW 格式，M 是输出图像通道数，C 是输入图像通道数，H 是卷积核高度，W 是卷积核宽度。如果组数大于 1，C 等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 参考文献_。如果参数 bias_attr 不为 False，转置卷积计算会添加偏置项。 .. _参考文献: https://arxiv.org/pdf/1603.07285.pdf @@ -18,15 +18,14 @@ conv2d_transpose 输入 :math:`X` 和输出 :math:`Out` 函数关系如下： .. math:: - Out=\sigma (W*X+b)\\ + Out=W*X+b\\ 其中： - :math:`X`：输入，具有 NCHW 或 NHWC 格式的 4-D Tensor - - :math:`W`：卷积核，具有 NCHW 格式的 4-D Tensor + - :math:`W`：卷积核，具有 CMHW 格式的 4-D Tensor - :math:`*`：卷积计算（注意：转置卷积本质上的计算还是卷积） - - :math:`b`：偏置（bias），2-D Tensor，形状为 ``[M,1]`` - - :math:`σ`：激活函数 + - :math:`b`：偏置（bias），1-D Tensor，形状为 ``[M]`` - :math:`Out`：输出值，NCHW 或 NHWC 格式的 4-D Tensor，和 ``X`` 的形状可能不同 **示例** @@ -71,9 +70,9 @@ conv2d_transpose 参数 :::::::::::: - - **x** (Tensor) - 输入是形状为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float16, float32 或 float64。 + - **x** (Tensor) - 输入是形状为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float16, float32 或 float64。别名 ``input``。 - **weight** (Tensor) - 形状为 :math:`[C, M/g, kH, kW]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kH 是卷积核的高度，kW 是卷积核的宽度。 - - **bias** (int|list|tuple，可选) - 偏置项，形状为：:math:`[M,]` 。 + - **bias** (Tensor|None，可选) - 偏置项，形状为：:math:`[M,]` 。 - **stride** (int|list|tuple，可选) - 步长大小。如果 ``stride`` 为元组，则必须包含两个整型数，分别表示垂直和水平滑动步长。否则，表示垂直和水平滑动步长均为 ``stride``。默认值：1。 - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是 "VALID" 或者 "SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME" 或 ``padding`` = "VALID" 时的计算公式。 如果它是一个元组或列表，可以有以下 3 种格式： @@ -104,10 +103,10 @@ conv2d_transpose 默认值：0。 - **output_padding** (int|list|tuple，可选) - 输出形状上一侧额外添加的大小。默认值：0。 - - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **output_size** (int|list|tuple，可选) - 输出尺寸，整数或包含两个整数 ``(image_height, image_width)`` 的列表或元组。如果为 ``None``，则会用 filter_size (``weight`` 的 shape)、``padding`` 和 ``stride`` 计算出输出特征图的尺寸。默认值：None。 - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"。 - - **output_size** (int|list|tuple，可选) - 输出尺寸，整数或包含一个整数的列表或元组。如果为 ``None``，则会用 filter_size (``weight`` 的 shape)、``padding`` 和 ``stride`` 计算出输出特征图的尺寸。默认值：None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/nn/functional/cross_entropy_cn.rst b/docs/api/paddle/nn/functional/cross_entropy_cn.rst index c990e0b6d6c..3f268424330 100644 --- a/docs/api/paddle/nn/functional/cross_entropy_cn.rst +++ b/docs/api/paddle/nn/functional/cross_entropy_cn.rst @@ -3,13 +3,15 @@ cross_entropy ------------------------------- -.. py:function:: paddle.nn.functional.cross_entropy(input, label, weight=None, ignore_index=-100, reduction="mean", soft_label=False, label_smoothing=0.0, axis=-1, name=None) +.. py:function:: paddle.nn.functional.cross_entropy(input, label, weight=None, ignore_index=-100, reduction="mean", soft_label=False, axis=-1, use_softmax=True, label_smoothing=0.0, name=None) -实现了 softmax 交叉熵损失函数。该函数会将 softmax 操作、交叉熵损失函数的计算过程进行合并，从而提供了数值上更稳定的计算。 +默认情况下，实现了 softmax 交叉熵损失函数。该函数会将 softmax 操作、交叉熵损失函数的计算过程进行合并，从而提供了数值上更稳定的计算。 + +当 ``use_softmax=False`` 时，该函数直接计算交叉熵损失，不进行 softmax 操作。 默认会对结果进行求 mean 计算，您也可以影响该默认行为，具体参考 reduction 参数说明。 -可用于计算硬标签或软标签的交叉熵。其中，硬标签是指实际 label 值，例如：0, 1, 2...，软标签是指实际 label 的概率，例如：0.6, 0,8, 0,2... +可用于计算硬标签或软标签的交叉熵。其中，硬标签是指实际 label 值，例如：0, 1, 2...，软标签是指实际 label 的概率，例如：0.6、0.8、0.2... 计算包括以下两个步骤： @@ -17,16 +19,32 @@ cross_entropy 1. 硬标签（每个样本仅可分到一个类别） + 1.1 当 ``use_softmax=True`` 时 + .. math:: \\loss_j=-\text{logits}_{label_j}+\log\left(\sum_{i=0}^{C}\exp(\text{logits}_i)\right) , j = 1,...,N, N 为样本数，C 为类别数 + 1.2 当 ``use_softmax=False`` 时 + + .. math:: + \\loss_j=-\log\left({P}_{label_j}\right) + , j = 1,...,N, N 为样本数，C 为类别数，P 为 input（softmax 的输出） + 2. 软标签（每个样本以一定的概率被分配至多个类别中，概率和为 1） + 2.1 当 ``use_softmax=True`` 时 + .. math:: \\loss_j=-\sum_{i=0}^{C}\text{label}_i\left(\text{logits}_i-\log\left(\sum_{i=0}^{C}\exp(\text{logits}_i)\right)\right) , j = 1,...,N, N 为样本数，C 为类别数 + 2.2 当 ``use_softmax=False`` 时 + + .. math:: + \\loss_j=-\sum_{j=0}^{C}\left({label}_j*\log\left({P}_{label_j}\right)\right) + , j = 1,...,N, N 为样本数，C 为类别数，P 为 input（softmax 的输出） + - **二、weight 及 reduction 处理** 1. weight 情况 @@ -81,15 +99,15 @@ cross_entropy 参数 ::::::::: - - **input** (Tensor) - 维度为 :math:`[N_1, N_2, ..., N_k, C]` 的多维 Tensor，其中最后一维 C 是类别数目。数据类型为 float32 或 float64。它需要未缩放的 ``input``。该 OP 不应该对 softmax 运算的输出进行操作，否则会产生错误的结果。 + - **input** (Tensor) - 维度为 :math:`[N_1, N_2, ..., N_k, C]` 的多维 Tensor，其中最后一维 C 是类别数目。数据类型为 float32 或 float64。当 ``use_softmax=True`` 时，需要输入未缩放的 logits，且不应输入 softmax 运算的输出；当 ``use_softmax=False`` 时，需要输入 softmax 运算的输出。 - **label** (Tensor) - 输入 input 对应的标签值。若 soft_label=False，要求 label 维度为 :math:`[N_1, N_2, ..., N_k]` 或 :math:`[N_1, N_2, ..., N_k, 1]`，数据类型为'int32', 'int64', 'float32', 'float64'，且值必须大于等于 0 且小于 C；若 soft_label=True 且没有指定 label_smoothing ，要求 label 的维度、数据类型与 input 相同，且每个样本各软标签的总和为 1；若指定了 label_smoothing (label_smoothing > 0.0) 时，无论 soft_label 是什么值，label 的维度和数据类型可以是前面两种情况中的任意一种。换句话说，如果 label_smoothing > 0.0，label 可以是独热标签或整数标签。``target`` 为 ``label`` 的别名，行为完全一致。 - **weight** (Tensor，可选) - 权重 Tensor，需要手动给每个类调整权重，形状是（C）。它的维度与类别相同，数据类型为 float32，float64。默认值为 None。 - - **ignore_index** (int) - 指定一个忽略的标签值，此标签值不参与计算，负值表示无需忽略任何标签值。仅在 soft_label=False 时有效。默认值为-100。 - - **reduction** (str，可选) - 指示如何按批次大小平均损失，可选值为"none","mean","sum"，如果选择是"mean"，则返回 reduce 后的平均损失；如果选择是"sum"，则返回 reduce 后的总损失。如果选择是"none"，则返回没有 reduce 的损失。默认值是“mean”。 + - **ignore_index** (int，可选) - 指定一个忽略的标签值，此标签值不参与计算，负值表示无需忽略任何标签值。仅在 soft_label=False 时有效。默认值为-100。 + - **reduction** (str，可选) - 指示如何按批次大小平均损失，可选值为"none","mean","sum"，如果选择是"mean"，则返回 reduce 后的平均损失；如果选择是"sum"，则返回 reduce 后的总损失。如果选择是"none"，则返回没有 reduce 的损失。默认值是"mean"。 - **soft_label** (bool，可选) - 指明 label 是否为软标签。默认为 False，表示 label 为硬标签；若 soft_label=True 则表示软标签。 - - **label_smoothing** （float，可选）- 指定计算损失时的标签平滑度，它应该在 :math:`[0.0，1.0]` 范围内。其中 0.0 表示无平滑。使得平滑后的标签变成原始真实标签和均匀分布的混合，默认值： 0.0。 - - **axis** (int，可选) - 进行 softmax 计算的维度索引。它应该在 :math:`[-1，dim-1]` 范围内，而 ``dim`` 是输入 logits 的维度。默认值：-1。 + - **axis** (int，可选) - 进行 softmax 计算的维度索引。它应该在 :math:`[-1, dim-1]` 范围内，而 ``dim`` 是输入 logits 的维度。默认值：-1。 - **use_softmax** (bool，可选) - 指定是否对 input 进行 softmax 归一化。默认值：True。 + - **label_smoothing** (float，可选) - 指定计算损失时的标签平滑度，它应该在 :math:`[0.0, 1.0]` 范围内。其中 0.0 表示无平滑。使得平滑后的标签变成原始真实标签和均匀分布的混合，默认值： 0.0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/dropout1d_cn.rst b/docs/api/paddle/nn/functional/dropout1d_cn.rst index 89a340fb9a1..a978b602171 100644 --- a/docs/api/paddle/nn/functional/dropout1d_cn.rst +++ b/docs/api/paddle/nn/functional/dropout1d_cn.rst @@ -3,7 +3,7 @@ dropout1d ------------------------------- -.. py:function:: paddle.nn.functional.dropout1d(x, p=0.5, training=True, inplace=False) +.. py:function:: paddle.nn.functional.dropout1d(input, p=0.5, training=True, inplace=False) 根据丢弃概率 ``p``，在训练过程中随机将某些 1D 通道置 0(对一个形状为 ``[N, C, L]`` 的 3D Tensor 或 ``[C, L]`` 的 2D Tensor，1D 通道指的是其中的形状为 ``L`` 的 1 维特征图)。 @@ -11,14 +11,14 @@ dropout1d 参数 ::::::::: - - **x** (Tensor) - 形状为 ``[N, C, L]`` 的 3D Tensor 或 ``[C, L]`` 的 2D Tensor，数据类型为 float16、float32 或 float64。 + - **input** (Tensor) - 形状为 ``[N, C, L]`` 的 3D Tensor 或 ``[C, L]`` 的 2D Tensor，数据类型为 float16、float32 或 float64。 - **p** (float，可选) - 将输入通道置 0 的概率，即丢弃概率，默认值为 0.5。 - **training** (bool，可选) - 标记是否为训练阶段，默认值为 True。 - **inplace** (bool，可选) - 是否原地操作。当前版本暂未实现(行为等同于 False)，未来版本将支持，默认值为 False。 返回 ::::::::: -经过 dropout1d 之后的结果，与输入 ``x`` 形状相同的 ``Tensor``。 +经过 dropout1d 之后的结果，与输入 ``input`` 形状相同的 ``Tensor``。 代码示例 ::::::::: diff --git a/docs/api/paddle/nn/functional/dropout3d_cn.rst b/docs/api/paddle/nn/functional/dropout3d_cn.rst index 955e5b6121a..e74dbc6d503 100644 --- a/docs/api/paddle/nn/functional/dropout3d_cn.rst +++ b/docs/api/paddle/nn/functional/dropout3d_cn.rst @@ -3,7 +3,7 @@ dropout3d ------------------------------- -.. py:function:: paddle.nn.functional.dropout3d(x, p=0.5, training=True, name=None) +.. py:function:: paddle.nn.functional.dropout3d(x, p=0.5, training=True, data_format="NCDHW", name=None) 根据丢弃概率 ``p``，在训练过程中随机将某些通道特征图置 0 (对一个形状为 ``NCDHW`` 的 5 维 Tensor，通道指的是其中的形状为 ``DHW`` 的 3 维特征图)。 @@ -15,6 +15,7 @@ dropout3d - **x** (Tensor) - 形状为 [N, C, D, H, W] 或 [N, D, H, W, C] 的 5D ``Tensor``，其中 N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度，数据类型只能为 float32 或 float64。 - **p** (float，可选) - 将输入通道置 0 的概率，即丢弃概率。默认值为 0.5。 - **training** (bool，可选) - 标记是否为训练阶段。默认值为 True。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式与输入一致。可选值为 ``"NCDHW"`` 或 ``"NDHWC"``。当其为 ``"NCDHW"`` 时，数据按 [batch_size, input_channels, input_depth, input_height, input_width] 的顺序存储。默认值为 ``"NCDHW"``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/fold_cn.rst b/docs/api/paddle/nn/functional/fold_cn.rst index fe80191c0a4..45105762a26 100644 --- a/docs/api/paddle/nn/functional/fold_cn.rst +++ b/docs/api/paddle/nn/functional/fold_cn.rst @@ -20,12 +20,12 @@ fold 参数 ::::::::: - - **x** (Tensor) – 输入 3-D Tensor，形状为[N, C, L]，数据类型为 float32 、 float64 、 complex64 或 complex128 - - **output_sizes** (int|list|tuple) – 输出尺寸，整数或者整型列表。如为列表类型应包含两个元素 ``[output_size_h, output_size_w]``。如果为整数 o，则输出形状会被认为 ``[o, o]``。 - - **kernel_size** (int|list|tuple) - 卷积核大小，整数或者整型列表。如为列表类型应包含两个元素 ``[k_h, k_w]``。如果为整数 k，则输出形状会被认为 ``[k, k]``。 - - **strides** (int|list|tuple，可选) - 步长大小，整数或者整型列表。如为列表类型应包含两个元素 ``[stride_h, stride_w]``。如果为整数 stride，则输出形状会被认为 ``[sride, stride]``。默认为[1,1]。 - - **paddings** (int|list|tuple，可选) – 每个维度的扩展，整数或者整型列表。如果为整型列表，长度应该为 4 或者 2；长度为 4 对应的 padding 参数是：[padding_top, padding_left，padding_bottom, padding_right]，长度为 2 对应的 padding 参数是[padding_h, padding_w]，会被当作[padding_h, padding_w, padding_h, padding_w]处理。如果为整数 padding，则会被当作[padding, padding, padding, padding]处理。默认值为 0。 - - **dilations** (int|list|tuple，可选) – 卷积膨胀，整型列表或者整数。如果为整型列表，应该包含两个元素[dilation_h, dilation_w]。如果是整数 dilation，会被当作整型列表[dilation, dilation]处理。默认值为 1。 + - **x** (Tensor) - 输入 3-D Tensor，形状为[N, C, L]，数据类型为 float32 、 float64 、 complex64 或 complex128。别名 ``input``。 + - **output_sizes** (int|list|tuple) - 输出尺寸，整数或者整型列表。如为列表类型应包含两个元素 ``[output_size_h, output_size_w]``。如果为整数 o，则输出形状会被认为 ``[o, o]``。别名 ``output_size``。 + - **kernel_sizes** (int|list|tuple) - 卷积核大小，整数或者整型列表。如为列表类型应包含两个元素 ``[k_h, k_w]``。如果为整数 k，则输出形状会被认为 ``[k, k]``。别名 ``kernel_size``。 + - **strides** (int|list|tuple，可选) - 步长大小，整数或者整型列表。如为列表类型应包含两个元素 ``[stride_h, stride_w]``。如果为整数 stride，则输出形状会被认为 ``[stride, stride]``。默认为[1,1]。别名 ``stride``。 + - **paddings** (int|list|tuple，可选) - 每个维度的扩展，整数或者整型列表。如果为整型列表，长度应该为 4 或者 2；长度为 4 对应的 padding 参数是：[padding_top, padding_left, padding_bottom, padding_right]，长度为 2 对应的 padding 参数是[padding_h, padding_w]，会被当作[padding_h, padding_w, padding_h, padding_w]处理。如果为整数 padding，则会被当作[padding, padding, padding, padding]处理。默认值为 0。别名 ``padding``。 + - **dilations** (int|list|tuple，可选) - 卷积膨胀，整型列表或者整数。如果为整型列表，应该包含两个元素[dilation_h, dilation_w]。如果是整数 dilation，会被当作整型列表[dilation, dilation]处理。默认值为 1。别名 ``dilation``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/nn/functional/hardsigmoid_cn.rst b/docs/api/paddle/nn/functional/hardsigmoid_cn.rst index eeae34cef34..f6fa5526430 100644 --- a/docs/api/paddle/nn/functional/hardsigmoid_cn.rst +++ b/docs/api/paddle/nn/functional/hardsigmoid_cn.rst @@ -3,7 +3,7 @@ hardsigmoid ------------------------------- -.. py:function:: paddle.nn.functional.hardsigmoid(x, slope=0.1666667, offset=0.5, name=None) +.. py:function:: paddle.nn.functional.hardsigmoid(x, slope=0.1666667, offset=0.5, inplace=False, name=None) hardsigmoid 激活层。sigmoid 的分段线性逼近激活函数，速度比 sigmoid 快，详细解释参见 `Noisy Activation Functions `_。 @@ -22,9 +22,10 @@ hardsigmoid 激活层。sigmoid 的分段线性逼近激活函数，速度比 si 参数 :::::::::: - - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。 + - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float16、float32、float64、uint16。 - **slope** (float，可选) - hardsigmoid 的斜率。默认值为 0.1666667。 - **offset** (float，可选) - hardsigmoid 的截距。默认值为 0.5。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/lp_pool2d_cn.rst b/docs/api/paddle/nn/functional/lp_pool2d_cn.rst index 8c07594242d..48405b9afa7 100644 --- a/docs/api/paddle/nn/functional/lp_pool2d_cn.rst +++ b/docs/api/paddle/nn/functional/lp_pool2d_cn.rst @@ -4,6 +4,14 @@ lp_pool2d ------------------------------- .. py:function:: paddle.nn.functional.lp_pool2d(x, norm_type, kernel_size, stride=None, padding=0, ceil_mode=False, data_format="NCHW", name=None) + +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.nn.functional.lp_pool2d(x, norm_type, kernel_size, stride=None, padding=0, ceil_mode=False, data_format='NCHW', name=None)`` （Paddle 风格）。 + 2. ``paddle.nn.functional.lp_pool2d(input, norm_type, kernel_size, stride=None, ceil_mode=False)`` （PyTorch 风格）。 + 该函数是一个二维幂平均池化函数，其将构建一个二维幂平均池化层，根据输入参数 ``kernel_size``, ``stride``, ``padding`` 等参数对输入做平均池化操作。 @@ -30,12 +38,12 @@ lp_pool2d 参数 ::::::::: - - **x** (Tensor)：形状为 ``[N,C,H,W]`` 或 ``[N,H,W,C]`` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float32 或 float64。 + - **x** (Tensor)：形状为 ``[N,C,H,W]`` 或 ``[N,H,W,C]`` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float32 或 float64。别名 ``input``。 - **norm_type** (int|float)：幂平均池化的指数，不可以为 0。 - **kernel_size** (int|list|tuple)：池化核大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_size_Height, pool_size_Width)。若为一个整数，则它的平方值将作为池化核大小，比如若 pool_size=2，则池化核大小为 2x2。 - **stride** (int|list|tuple)：池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 kernel_size。 - **padding** (string|int|list|tuple) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。 - - **ceil_mode** (bool)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 ``ceil`` 计算输出形状的大小。默认为 None + - **ceil_mode** (bool)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 ``ceil`` 计算输出形状的大小。默认为 False。 - **data_format** (str)：输入和输出的数据格式，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW" - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/nn/functional/margin_cross_entropy_cn.rst b/docs/api/paddle/nn/functional/margin_cross_entropy_cn.rst index e8bc2ec984c..d2de2ded508 100644 --- a/docs/api/paddle/nn/functional/margin_cross_entropy_cn.rst +++ b/docs/api/paddle/nn/functional/margin_cross_entropy_cn.rst @@ -12,25 +12,25 @@ margin_cross_entropy 提示： - 这个 API 支持单卡，也支持多卡（模型并行），使用模型并行时，``logits.shape[-1]`` 在每张卡上可以不同。 + 这个 API 支持单卡，也支持多卡（模型并行），使用模型并行时，``logits.shape[-1]`` 在每张卡上可以不同。不支持 CPU。 参数 :::::::::::: - - **logits** (Tensor) - 2-D Tensor，维度为 ``[N, local_num_classes]``，``logits`` 为归一化后的 ``X`` 与归一化后的 ``W`` 矩阵乘得到，数据类型为 float16，float32 或者 float64。如果用了模型并行，则 ``logits == sahrd_logits``。 + - **logits** (Tensor) - 2-D Tensor，维度为 ``[N, local_num_classes]``，``logits`` 为归一化后的 ``X`` 与归一化后的 ``W`` 矩阵乘得到，数据类型为 float16，float32 或者 float64。如果用了模型并行，则 ``logits == shard_logits``。 - **label** (Tensor) - 维度为 ``[N]`` 或者 ``[N, 1]`` 的标签。 - **margin1** (float，可选) - 公式中的 ``m1``。默认值为 ``1.0``。 - **margin2** (float，可选) - 公式中的 ``m2``。默认值为 ``0.5``。 - **margin3** (float，可选) - 公式中的 ``m3``。默认值为 ``0.0``。 - **scale** (float，可选) - 公式中的 ``s``。默认值为 ``64.0``。 - **group** (Group，可选) - 通信组的抽象描述，具体可以参考 ``paddle.distributed.collective.Group``。默认值为 ``None``。 - - **return_softmax** (bool，可选) - 是否返回 ``softmax`` 概率值。默认值为 ``None``。 - - **reduction** （str，可选）- 是否对 ``loss`` 进行归约。可选值为 ``'none'`` | ``'mean'`` | ``'sum'``。如果 ``reduction='mean'``，则对 ``loss`` 进行平均，如果 ``reduction='sum'``，则对 ``loss`` 进行求和，``reduction='None'``，则直接返回 ``loss``。默认值为 ``'mean'``。 + - **return_softmax** (bool，可选) - 是否返回 ``softmax`` 概率值。默认值为 ``False``。 + - **reduction** (str，可选) - 是否对 ``loss`` 进行归约。可选值为 ``'none'`` | ``'mean'`` | ``'sum'``。如果 ``reduction='mean'``，则对 ``loss`` 进行平均，如果 ``reduction='sum'``，则对 ``loss`` 进行求和，``reduction='none'``，则直接返回 ``loss``。默认值为 ``'mean'``。 返回 :::::::::::: - - ``Tensor`` (``loss``) 或者 ``Tensor`` 二元组 (``loss``, ``softmax``) - 如果 ``return_softmax=False`` 返回 ``loss``，否则返回 (``loss``, ``softmax``)。当使用模型并行时 ``softmax == shard_softmax``，否则 ``softmax`` 的维度与 ``logits`` 相同。如果 ``reduction == None``，``loss`` 的维度为 ``[N, 1]``，否则为 ``[]``。 + - ``Tensor`` (``loss``) 或者 ``Tensor`` 二元组 (``loss``, ``softmax``) - 如果 ``return_softmax=False`` 返回 ``loss``，否则返回 (``loss``, ``softmax``)。当使用模型并行时 ``softmax == shard_softmax``，否则 ``softmax`` 的维度与 ``logits`` 相同。如果 ``reduction == 'none'``，``loss`` 的维度为 ``[N, 1]``，否则为 ``[]``。 代码示例 :::::::::::: diff --git a/docs/api/paddle/nn/functional/margin_ranking_loss_cn.rst b/docs/api/paddle/nn/functional/margin_ranking_loss_cn.rst index 08073d103a5..3496ad1086b 100644 --- a/docs/api/paddle/nn/functional/margin_ranking_loss_cn.rst +++ b/docs/api/paddle/nn/functional/margin_ranking_loss_cn.rst @@ -24,11 +24,11 @@ margin_ranking_loss 参数 :::::::: - - **input** (Tensor) - 第一个输入的 ``Tensor``，数据类型为：float32、float64。 - - **other** (Tensor) - 第二个输入的 ``Tensor``，数据类型为：float32、float64。 - - **label** (Tensor) - 训练数据的标签，数据类型为：float32、float64。 + - **input** (Tensor) - 第一个输入的 ``Tensor``，数据类型为：float32、float64。别名 ``input1``。 + - **other** (Tensor) - 第二个输入的 ``Tensor``，数据类型为：float32、float64。别名 ``input2``。 + - **label** (Tensor) - 训练数据的标签，数据类型为：float32、float64。别名 ``target``。 - **margin** (float，可选) - 用于加和的 margin 值，默认值为 0。 - - **reduction** (string，可选) - 指定应用于输出结果的计算方式，可选值有：``'none'`` 、 ``'mean'`` 、 ``'sum'``。如果设置为 ``'none'``，则直接返回 最原始的 ``margin_rank_loss``。如果设置为 ``'sum'``，则返回 ``margin_rank_loss`` 的总和。如果设置为 ``'mean'``，则返回 ``margin_rank_loss`` 的平均值。默认值为 ``'none'`` 。 + - **reduction** (string，可选) - 指定应用于输出结果的计算方式，可选值有：``'none'`` 、 ``'mean'`` 、 ``'sum'``。如果设置为 ``'none'``，则直接返回 最原始的 ``margin_rank_loss``。如果设置为 ``'sum'``，则返回 ``margin_rank_loss`` 的总和。如果设置为 ``'mean'``，则返回 ``margin_rank_loss`` 的平均值。默认值为 ``'mean'`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/mish_cn.rst b/docs/api/paddle/nn/functional/mish_cn.rst index 815c14ea6fd..1901d1141cc 100644 --- a/docs/api/paddle/nn/functional/mish_cn.rst +++ b/docs/api/paddle/nn/functional/mish_cn.rst @@ -3,7 +3,7 @@ mish ------------------------------- -.. py:function:: paddle.nn.functional.mish(x, name=None) +.. py:function:: paddle.nn.functional.mish(x, inplace=False, name=None) mish 激活层。计算公式如下： @@ -20,6 +20,7 @@ mish 激活层。计算公式如下： 参数 :::::::::: - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。别名 ``input``。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/normalize_cn.rst b/docs/api/paddle/nn/functional/normalize_cn.rst index 143772bd63f..dd0193d43b3 100644 --- a/docs/api/paddle/nn/functional/normalize_cn.rst +++ b/docs/api/paddle/nn/functional/normalize_cn.rst @@ -3,7 +3,7 @@ normalize ------------------------------- -.. py:function:: paddle.nn.functional.normalize(x, p=2, axis=1, epsilon=1e-12, name=None) +.. py:function:: paddle.nn.functional.normalize(x, p=2, axis=1, epsilon=1e-12, out=None, name=None) 使用 :math:`L_p` 范数沿维度 ``axis`` 对 ``x`` 进行归一化。计算公式如下： @@ -19,10 +19,11 @@ normalize 参数 ::::::::: - - **x** (Tensor) - 输入可以是 N-D Tensor。数据类型为：float32、float64。 + - **x** (Tensor) - 输入可以是 N-D Tensor。数据类型为：float32、float64。别名 ``input``。 - **p** (float|int，可选) - 范数公式中的指数值。默认值：2 - - **axis** (int，可选）- 要进行归一化的轴。如果 ``x`` 是 1-D Tensor，轴固定为 0。如果 ``axis < 0``，轴为 ``x.ndim + axis``。-1 表示最后一维。 - - **epsilon** (float，可选) - 添加到分母上的值以防止分母为 0。默认值为 1e-12。 + - **axis** (int，可选) - 要进行归一化的轴。如果 ``x`` 是 1-D Tensor，轴固定为 0。如果 ``axis < 0``，轴为 ``x.ndim + axis``。-1 表示最后一维。别名 ``dim``。 + - **epsilon** (float，可选) - 添加到分母上的值以防止分母为 0。默认值为 1e-12。别名 ``eps``。 + - **out** (Tensor，可选) - 输出 Tensor。默认值为 ``None``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/one_hot_cn.rst b/docs/api/paddle/nn/functional/one_hot_cn.rst index a00b7dbf774..3e4f99b4331 100644 --- a/docs/api/paddle/nn/functional/one_hot_cn.rst +++ b/docs/api/paddle/nn/functional/one_hot_cn.rst @@ -3,7 +3,7 @@ one_hot ------------------------------- -.. py:function:: paddle.nn.functional.one_hot(x, num_classes, name=None) +.. py:function:: paddle.nn.functional.one_hot(x, num_classes=-1, name=None) 将输入'x'中的每个 id 转换为一个 one-hot 向量，其长度为 ``num_classes``，该 id 对应的向量维度上的值为 1，其余维度的值为 0。 输出的 Tensor 的 shape 是在输入 shape 的最后一维后面添加了 num_classes 的维度。 @@ -42,9 +42,8 @@ one_hot 参数 :::::::::::: - - **x** (Tensor) - 维度为 :math:`[N_1, ..., N_n]` 的多维 Tensor，维度至少 1 维。数据类型为 int32 或 int64。 - ``别名: input`` - - **num_classes** (int) - 用于定义一个 one-hot 向量的长度。若输入为词 id，则 ``num_classes`` 通常取值为词典大小，默认值为-1。 + - **x** (Tensor) - 维度为 :math:`[N_1, ..., N_n]` 的多维 Tensor，维度至少 1 维。数据类型为 int32 或 int64。别名: ``input`` + - **num_classes** (int，可选) - 用于定义一个 one-hot 向量的长度。若输入为词 id，则 ``num_classes`` 通常取值为词典大小，默认值为-1。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回