[API Compatibility] Update and add cn docs for aligned 19 apis -part

.gitignore

@@ -3,6 +3,7 @@
 .vscode
 .comate
 .idea
+.claude
 
 # virtualenv
 venv/

docs/api/paddle/Overview_cn.rst

@@ -463,6 +463,7 @@ tensor 线性代数相关
     " :ref:`paddle.histogram_bin_edges <cn_api_paddle_histogram_bin_edges>` ", "返回计算 input 的直方图时所使用的 bins 的边界值 bin_edges"
     " :ref:`paddle.histogram <cn_api_paddle_histogram>` ", "计算输入 Tensor 的直方图"
     " :ref:`paddle.histogramdd <cn_api_paddle_histogramdd>` ", "计算输入多维 Tensor 的直方图"
+    " :ref:`paddle.inverse <cn_api_paddle_inverse>` ", "计算方阵的逆矩阵"
     " :ref:`paddle.matmul <cn_api_paddle_matmul>` ", "计算两个 Tensor 的乘积，遵循完整的广播规则"
     " :ref:`paddle.mv <cn_api_paddle_mv>` ", "计算矩阵 x 和向量 vec 的乘积"
     " :ref:`paddle.rank <cn_api_paddle_rank>` ", "计算输入 Tensor 的维度（秩）"
@@ -607,6 +608,7 @@ framework 相关
     :header: "API 名称", "API 功能"
     :widths: 10, 30
 
+    " :ref:`paddle._assert <cn_api_paddle__assert>` ", "对 Python assert 的封装，支持符号追踪"
     " :ref:`paddle.CPUPlace <cn_api_paddle_CPUPlace>` ", "一个设备描述符，指定 CPUPlace 则 Tensor 将被自动分配在该设备上，并且模型将会运行在该设备上"
     " :ref:`paddle.CUDAPinnedPlace <cn_api_paddle_CUDAPinnedPlace>` ", "一个设备描述符，它所指代的页锁定内存由 CUDA 函数 cudaHostAlloc() 在主机内存上分配，主机的操作系统将不会对这块内存进行分页和交换操作，可以通过直接内存访问技术访问，加速主机和 GPU 之间的数据拷贝"
     " :ref:`paddle.CUDAPlace <cn_api_paddle_CUDAPlace>` ", "一个设备描述符，表示一个分配或将要分配 Tensor 的 GPU 设备"

docs/api/paddle/_assert_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_paddle__assert:
+
+_assert
+-------------------------------
+
+.. py:function:: paddle._assert(condition, message="")
+
+对 Python assert 的封装，支持符号追踪。
+
+在动态图模式下，该函数的行为与 Python 的 assert 语句一致。在静态图模式下，当 condition 是 Tensor 时，会在计算图中创建一个 Assert 算子。
+
+参数
+::::::::::::
+    - **condition** (bool|Tensor) - 断言的条件。如果是 Tensor，必须是布尔标量（numel=1）。
+    - **message** (str，可选) - 断言失败时显示的错误信息。默认值为 ""。
+
+代码示例
+::::::::::::
+
+.. code-block:: pycon
+
+    >>> import paddle
+    >>> # Non-tensor condition
+    >>> paddle._assert(1 == 1, "This should pass")
+
+    >>> # Tensor condition
+    >>> x = paddle.to_tensor([True])
+    >>> paddle._assert(x, "Tensor assertion")

docs/api/paddle/allclose_cn.rst

@@ -15,8 +15,8 @@ allclose
 参数
 ::::::::::::
 
-    - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float16、float32、float64。
-    - **y** (Tensor) - 输入的 ``Tensor``，数据类型为：float16、float32、float64。
+    - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float16、float32、float64。别名 ``input``。
+    - **y** (Tensor) - 输入的 ``Tensor``，数据类型为：float16、float32、float64。别名 ``other``。
     - **rtol** (float，可选) - 相对容忍误差，默认值为 1e-5。
     - **atol** (float，可选) - 绝对容忍误差，默认值为 1e-8。
     - **equal_nan** (bool，可选) - 如果设置为 True，则两个 NaN 数值将被视为相等，默认值为 False。

docs/api/paddle/amp/GradScaler_cn.rst

@@ -17,14 +17,21 @@ GradScaler 用于动态图模式下的"自动混合精度"的训练。它控制
 
 通常，GradScaler 和 ``paddle.amp.auto_cast`` 一起使用，来实现动态图模式下的"自动混合精度"。
 
+本 API 支持三种调用方式：
+
+1. ``GradScaler(enable=True, init_loss_scaling=2.0**16, incr_ratio=2.0, decr_ratio=0.5, incr_every_n_steps=2000, decr_every_n_nan_or_inf=1, use_dynamic_loss_scaling=True)``
+
+2. ``GradScaler(device, init_scale=2.0**16, growth_factor=2.0, backoff_factor=0.5, growth_interval=2000, enabled=True)``
+
+3. ``GradScaler(init_scale=2.0**16, growth_factor=2.0, backoff_factor=0.5, growth_interval=2000, enabled=True)``
 
 参数
 :::::::::
-    - **enable** (bool，可选) - 是否使用 loss scaling。默认值为 True。
-    - **init_loss_scaling** (float，可选) - 初始 loss scaling 因子。默认值为 65536.0。
-    - **incr_ratio** (float，可选) - 增大 loss scaling 时使用的乘数。默认值为 2.0。
-    - **decr_ratio** (float，可选) - 减小 loss scaling 时使用的小于 1 的乘数。默认值为 0.5。
-    - **incr_every_n_steps** (int，可选) - 连续 n 个 steps 的梯度都是有限值时，增加 loss scaling。默认值为 2000。
+    - **enable** (bool，可选) - 是否使用 loss scaling。默认值为 True。别名 ``enabled``。
+    - **init_loss_scaling** (float，可选) - 初始 loss scaling 因子。默认值为 65536.0。别名 ``init_scale``。
+    - **incr_ratio** (float，可选) - 增大 loss scaling 时使用的乘数。默认值为 2.0。别名 ``growth_factor``。
+    - **decr_ratio** (float，可选) - 减小 loss scaling 时使用的小于 1 的乘数。默认值为 0.5。别名 ``backoff_factor``。
+    - **incr_every_n_steps** (int，可选) - 连续 n 个 steps 的梯度都是有限值时，增加 loss scaling。默认值为 2000。别名 ``growth_interval``。
     - **decr_every_n_nan_or_inf** (int，可选) - 累计出现 n 个 steps 的梯度为 nan 或者 inf 时，减小 loss scaling。默认值为 1。
     - **use_dynamic_loss_scaling** (bool，可选) - 是否使用动态的 loss scaling。如果不使用，则使用固定的 loss scaling；如果使用，则会动态更新 loss scaling。默认值为 True。
 

docs/api/paddle/deg2rad_cn.rst

@@ -3,7 +3,7 @@
 deg2rad
 -------------------------------
 
-.. py:function:: paddle.deg2rad(x, name=None)
+.. py:function:: paddle.deg2rad(x, name=None, *, out=None)
 
 将元素从度转换为弧度
 
@@ -17,6 +17,10 @@ deg2rad
     - **x**  (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float32、float64。
     - **name**  (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
 
+关键字参数
+:::::::::
+    - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。
+
 返回
 :::::::::
 

docs/api/paddle/inverse_cn.rst

@@ -0,0 +1,35 @@
+.. _cn_api_paddle_inverse:
+
+inverse
+-------------------------------
+
+.. py:function:: paddle.inverse(x, name=None, *, out=None)
+
+计算方阵的逆矩阵。方阵是行数和列数相同的矩阵。输入可以是一个方阵（2-D Tensor）或者多个方阵组成的 batch（batch of square matrices）。
+
+参数
+::::::::::::
+    - **x** (Tensor) - 输入 Tensor，最后两个维度应相等。当维度大于 2 时，视为方阵的 batch。数据类型为 float32、float64、complex64、complex128。别名 ``input``。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+关键字参数
+::::::::::::
+    - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。
+
+返回
+::::::::::::
+Tensor，``x`` 的逆矩阵，维度和数据类型与 ``x`` 相同。
+
+代码示例
+::::::::::::
+
+.. code-block:: pycon
+
+    >>> import paddle
+
+    >>> mat = paddle.to_tensor([[2, 0], [0, 2]], dtype='float32')
+    >>> inv = paddle.inverse(mat)
+    >>> print(inv)
+    Tensor(shape=[2, 2], dtype=float32, place=Place(cpu), stop_gradient=True,
+    [[0.50000000, 0.        ],
+     [0.        , 0.50000000]])

docs/api/paddle/lerp_cn.rst

@@ -3,19 +3,23 @@
 lerp
 -------------------------------
 
-.. py:function:: paddle.lerp(x, y, weight, name=None)
+.. py:function:: paddle.lerp(x, y, weight, name=None, *, out=None)
 基于给定的 weight 计算 x 与 y 的线性插值
 
 .. math::
     lerp(x, y, weight) = x + weight * (y - x)
 参数
 :::::::::
 
-    - **x**  (Tensor) - 输入的 Tensor，作为线性插值开始的点，数据类型为：bfloat16、float16、float32、float64。
-    - **y**  (Tensor) - 输入的 Tensor，作为线性插值结束的点，数据类型为：bfloat16、float16、float32、float64。
+    - **x**  (Tensor) - 输入的 Tensor，作为线性插值开始的点，数据类型为：bfloat16、float16、float32、float64。别名 ``input``。
+    - **y**  (Tensor) - 输入的 Tensor，作为线性插值结束的点，数据类型为：bfloat16、float16、float32、float64。别名 ``end``。
     - **weight**  (float|Tensor) - 给定的权重值，weight 为 Tensor 时数据类型为：bfloat16、float16、float32、float64。
     - **name**  (str，可选） - 操作的名称(可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。
 
+关键字参数
+:::::::::
+    - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。
+
 返回
 :::::::::
 

docs/api/paddle/logit_cn.rst

@@ -3,7 +3,7 @@
 logit
 -------------------------------
 
-.. py:function:: paddle.logit(x, eps=None, name=None)
+.. py:function:: paddle.logit(x, eps=None, name=None, *, out=None)
 
 实现了 logit 层。若 eps 为默认值 None，并且 ``x`` < 0 或者 ``x`` > 1，该函数将返回 NaN，计算公式如下：
 
@@ -25,13 +25,17 @@ logit
 
 参数
 ::::::::::::
-    - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。
+    - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。别名 ``input``。
     - **eps** (float，可选) - 传入该参数后可将 ``x`` 的范围控制在 :math:`[eps, 1-eps]`，默认值为 None。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
+关键字参数
+::::::::::::
+    - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。
+
 返回
 ::::::::::
-    ``Tensor``，数据类型和形状同 ``x`` 一致。
+    ``Tensor``，形状同 ``x`` 一致（整数类型会自动转换为 float32）。
 
 代码示例
 ::::::::::

docs/api/paddle/mm_cn.rst

@@ -3,7 +3,7 @@
 mm
 -------------------------------
 
-.. py:function:: paddle.mm(input, mat2, name=None)
+.. py:function:: paddle.mm(input, mat2, name=None, *, out=None)
 
 
 
@@ -17,10 +17,14 @@ mm
 参数
 ::::::::::::
 
-    - **input** (Tensor)：输入变量，类型为 Tensor。
-    - **mat2** (Tensor)：输入变量，类型为 Tensor。
+    - **input** (Tensor) - 输入变量，类型为 Tensor。支持的数据类型：bfloat16、float16、float32、float64、int8、int32、int64、complex64、complex128。
+    - **mat2** (Tensor) - 输入变量，类型为 Tensor。支持的数据类型：bfloat16、float16、float32、float64、int8、int32、int64、complex64、complex128。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
+关键字参数
+::::::::::::
+    - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。
+
 返回
 ::::::::::::
 

docs/api/paddle/nn/Layer_cn.rst

@@ -27,13 +27,17 @@ COPY-FROM: paddle.nn.Layer
 ::::::::::::
 
 
-train()
+train(mode=True)
 '''''''''
 
 将此层及其所有子层设置为训练模式。这只会影响某些模块，如 Dropout 和 BatchNorm。
 
+**参数**
+
+    - **mode** (bool，可选) - 是否设置为训练模式。默认值为 True。
+
 **返回**
-Layer (返回网络层)， self (返回自身)
+Layer (返回网络层)，self (返回自身)
 
 **代码示例**
 
@@ -426,16 +430,37 @@ set_state_dict(state_dict, use_structured_name=True)
 
 COPY-FROM: paddle.nn.Layer.set_state_dict
 
-to(device=None, dtype=None, blocking=None)
+to(device=None, dtype=None, blocking=True, \*, non_blocking=False)
 '''''''''
 
-根据给定的 device、dtype 和 blocking 转换 Layer 中的 parameters 和 buffers。
+移动和/或转换 parameters 和 buffers。
+
+本 API 支持三种调用方式：
+
+1. ``to(device=None, dtype=None, blocking=True, *, non_blocking=False)``：
+    移动和/或转换 parameters 和 buffers。
+
+2. ``to(dtype, blocking=True, *, non_blocking=False)``：
+    等价于 ``self.to(device=None, dtype=dtype, ...)``。
+
+3. ``to(tensor, blocking=True, *, non_blocking=False)``：
+    等价于 ``self.to(device=tensor.place, dtype=tensor.dtype, ...)``。
+
+.. note::
+    此方法为就地（in-place）操作。
 
 **参数**
 
-    - **device** （str|paddle.CPUPlace()|paddle.CUDAPlace()|paddle.CUDAPinnedPlace()|paddle.XPUPlace()|None，可选) - 希望存储 Layer 的设备位置。如果为 None，设备位置和原始的 Tensor 的设备位置一致。如果设备位置是 string 类型，取值可为 ``cpu``, ``gpu:x`` and ``xpu:x``，这里的 ``x`` 是 GPUs 或者 XPUs 的编号。默认值：None。
-    - **dtype** (str|paddle.dtype|np.dtype，可选)- 数据的类型。如果为 None，数据类型和原始的 Tensor 一致。默认值：None。
-    - **blocking** （bool|None，可选）- 如果为 False 并且当前 Tensor 处于固定内存上，将会发生主机到设备端的异步拷贝。否则，会发生同步拷贝。如果为 None，blocking 会被设置为 True。默认为 False。
+    - **device** （str|paddle.CPUPlace()|paddle.CUDAPlace()|paddle.CUDAPinnedPlace()|paddle.XPUPlace()|None，可选) - 希望存储 Layer 的设备位置。如果为 None，设备位置和原始的 Tensor 的设备位置一致。如果设备位置是 string 类型，取值可为 ``cpu``, ``gpu:x`` 和 ``xpu:x``，这里的 ``x`` 是 GPUs 或者 XPUs 的编号。默认值：None。
+    - **dtype** (str|paddle.dtype|np.dtype|None，可选) - 数据的类型。如果为 None，数据类型和原始的 Tensor 一致。默认值：None。
+    - **blocking** （bool，可选）- 如果为 False 并且当前 Tensor 处于固定内存上，将会发生主机到设备端的异步拷贝。否则，会发生同步拷贝。默认值为 True。
+
+**关键字参数**
+
+    - **non_blocking** (bool，可选) - 如果为 True 并且当前 Tensor 处于固定内存上，将会发生主机到设备端的异步拷贝。默认值为 False。``non_blocking`` 和 ``blocking`` 互斥，不能同时设置。
+
+**返回**
+self
 
 **代码示例**
 

docs/api/paddle/nn/ParameterDict_cn.rst

@@ -13,7 +13,7 @@ ParameterDict
 参数
 :::::::::
 
-    - **parameters** (ParameterDict | Mapping[str, Tensor] | Sequence[tuple[str, Tensor]]，可选) - 可迭代的 Parameters，默认值为 None。
+    - **parameters** (ParameterDict | Mapping[str, Tensor] | Sequence[tuple[str, Tensor]]，可选) - 可迭代的 Parameters，默认值为 None。别名 ``values``。
 
 返回
 :::::::::

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

@@ -5,7 +5,11 @@ interpolate
 
 .. py:function:: paddle.nn.functional.interpolate(x, size=None, scale_factor=None, mode='nearest', align_corners=False, align_mode=0, data_format=None, recompute_scale_factor=None, antialias=False, name=None)
 
+本函数有两种功能，取决于传入的参数组合（其中 ``input`` 是 ``x`` 的别名，两者等价）：
 
+1. **PyTorch 兼容方式**： ``interpolate(x, size, scale_factor, mode, align_corners, recompute_scale_factor, antialias)``
+
+2. **PaddlePaddle 原始方式**： ``interpolate(x, size, scale_factor, mode, align_corners, align_mode, data_format, recompute_scale_factor, name)``
 
 调整一个 batch 中图片的大小。
 
@@ -141,7 +145,7 @@ https://en.wikipedia.org/wiki/Bicubic_interpolation
 参数
 ::::::::::::
 
-    - **x** (Tensor) - 3-D，4-D 或 5-D Tensor，数据类型为 float32、float64 或 uint8，其数据格式由参数 ``data_format`` 指定。如果没有指定 ``data_format`` 参数，其数据格式将由维度决定，具体请参照 ``data_format`` 参数。
+    - **x** (Tensor) - 3-D，4-D 或 5-D Tensor，数据类型为 float32、float64 或 uint8，其数据格式由参数 ``data_format`` 指定。如果没有指定 ``data_format`` 参数，其数据格式将由维度决定，具体请参照 ``data_format`` 参数。别名 ``input``。
     - **size** (list|tuple|Tensor|None) - 输出 Tensor，输入为 4D Tensor 时，形状为为(out_h, out_w)的 2-D Tensor。输入为 5-D Tensor 时，形状为(out_d, out_h, out_w)的 3-D Tensor。如果 :code:`out_shape` 是列表，每一个元素可以是整数或者形状为[]的 Tensor。如果 :code:`out_shape` 是 Tensor，则其为 1D Tensor。默认值为 None。
     - **scale_factor** (float|Tensor|list|tuple|None)-输入的高度或宽度的乘数因子。out_shape 和 scale 至少要设置一个。out_shape 的优先级高于 scale。默认值为 None。如果 scale_factor 是一个 list 或 tuple，它必须与输入的 shape 匹配。
     - **mode** (str，可选) - 插值方法。支持"bilinear"或"trilinear"或"nearest"或"bicubic"或"linear"或"area"。默认值为"nearest"。

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

@@ -2,7 +2,7 @@
 
 leaky_relu
 -------------------------------
-.. py:function:: paddle.nn.functional.leaky_relu(x, negative_slope=0.01, name=None)
+.. py:function:: paddle.nn.functional.leaky_relu(x, negative_slope=0.01, inplace=False, name=None)
 
 leaky_relu 激活层。计算公式如下：
 
@@ -20,8 +20,9 @@ leaky_relu 激活层。计算公式如下：
 
 参数
 ::::::::::
-    - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。
+    - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。别名 ``input``。
     - **negative_slope** (float，可选) - :math:`x < 0` 时的斜率。默认值为 0.01。
+    - **inplace** (bool，可选) - 是否使用 inplace 操作。默认值为 False。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 返回

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

@@ -2,7 +2,7 @@
 
 log_softmax
 -------------------------------
-.. py:function:: paddle.nn.functional.log_softmax(x, axis=-1, dtype=None, name=None)
+.. py:function:: paddle.nn.functional.log_softmax(x, axis=-1, dtype=None, name=None, *, out=None)
 
 实现了 log_softmax 层。计算公式如下：
 
@@ -15,11 +15,15 @@ log_softmax
 
 参数
 ::::::::::
-    - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。
-    - **axis** (int，可选) - 指定对输入 ``x`` 进行运算的轴。``axis`` 的有效范围是[-D, D)，D 是输入 ``x`` 的维度，``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。
+    - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。别名 ``input``。
+    - **axis** (int，可选) - 指定对输入 ``x`` 进行运算的轴。``axis`` 的有效范围是[-D, D)，D 是输入 ``x`` 的维度，``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。别名 ``dim``。
     - **dtype** (str|np.dtype|core.VarDesc.VarType，可选) - 输入 Tensor 的数据类型。如果指定了 ``dtype``，则输入 Tensor 的数据类型会在计算前转换到 ``dtype`` 。 ``dtype``  可以用来避免数据溢出。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型和 ``x`` 相同。默认值为 None。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
+关键字参数
+::::::::::
+    - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。
+
 返回
 ::::::::::
     ``Tensor``，形状和 ``x`` 相同，数据类型为 ``dtype`` 或者和 ``x`` 相同。

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

@@ -12,7 +12,7 @@ pixel_shuffle
 
 参数
 :::::::::
-    - **x** (Tensor) - 当前算子的输入，其是一个形状为 ``[N, C, H, W]`` 的 4-D Tensor。其中 ``N`` 是 batch size, ``C`` 是通道数，``H`` 是输入特征的高度，``W`` 是输入特征的宽度。其数据类型为 float16，float32，float64。
+    - **x** (Tensor) - 当前算子的输入，其是一个形状为 ``[N, C, H, W]`` 的 4-D Tensor。其中 ``N`` 是 batch size，``C`` 是通道数，``H`` 是输入特征的高度，``W`` 是输入特征的宽度。其数据类型为 float16，float32，float64。别名 ``input``。
     - **upscale_factor** （int) - 增大空间分辨率的增大因子
     - **data_format** (str，可选) - 数据格式，可选："NCHW"或"NHWC"，默认："NCHW"
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。