[API Compatibility] Check & Update cn docs: stage 1

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`` 维度相同、数据类型相同。

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。
 
 关键字参数
 :::::::::

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。
 
 关键字参数
 :::::::::

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 来保存输出结果。
+
 
 返回
 ::::::::::::

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`` 相同。

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`` 时，输出的数据类型与输入相同。
 
 代码示例
 :::::::::

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。

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。
 
 代码示例
 ::::::::::::

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，与输入数据类型相同的堆叠张量。

docs/api/paddle/conj_cn.rst

@@ -3,21 +3,17 @@
 conj
 -------------------------------
 
-.. py:function:: paddle.conj(x, name=None, *, out=None)
+.. py:function:: paddle.conj(x, name=None)
 
 
 是逐元素计算 Tensor 的共轭运算。
 
 参数
 ::::::::::::
 
-    - **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``。
-
 返回
 ::::::::::::
 

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``，累乘操作的结果。

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,14 +19,18 @@ 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。
 
     - **optimizer** (paddle.optimizer.Optimizer|None，可选) - 优化器。如果同时设置了 optimizer 和 loss，DistModel 会默认设置为 "train" 模式。默认值：None。
 
     - **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。
 
 **返回**
 

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. 其他需要保持局部计算语义的场景
 
 **注意事项**