diff --git a/docs/api/paddle/angle_cn.rst b/docs/api/paddle/angle_cn.rst index 2a586f30aec..1e56f4dd56e 100644 --- a/docs/api/paddle/angle_cn.rst +++ b/docs/api/paddle/angle_cn.rst @@ -3,7 +3,7 @@ angle ------------------------------- -.. py:function:: paddle.angle(x, name=None) +.. py:function:: paddle.angle(x, name=None, *, out=None) 逐元素计算复数的相位角。对于非负实数，相位角为 0，而对于负实数，相位角为 :math:`\pi`。 @@ -14,9 +14,13 @@ angle 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：complex64, complex128 或 float32, float64。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：complex64, complex128 或 float32, float64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: 输出实数 Tensor，与 ``x`` 的数值精度一致。 diff --git a/docs/api/paddle/asinh_cn.rst b/docs/api/paddle/asinh_cn.rst index c37a7f43224..686cde8d0cd 100644 --- a/docs/api/paddle/asinh_cn.rst +++ b/docs/api/paddle/asinh_cn.rst @@ -3,7 +3,7 @@ asinh ------------------------------- -.. py:function:: paddle.asinh(x, name=None) +.. py:function:: paddle.asinh(x, name=None, *, out=None) Arcsinh 函数。 @@ -12,9 +12,13 @@ Arcsinh 函数。 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、complex64、complex128。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：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/atan_cn.rst b/docs/api/paddle/atan_cn.rst index 153b4401b49..e711265aee0 100644 --- a/docs/api/paddle/atan_cn.rst +++ b/docs/api/paddle/atan_cn.rst @@ -3,7 +3,7 @@ atan ------------------------------- -.. py:function:: paddle.atan(x, name=None) +.. py:function:: paddle.atan(x, name=None, *, out=None) @@ -16,9 +16,13 @@ arctangent 函数。 参数 :::::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、float16、complex64、complex128。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、float16、complex64、complex128。别名 ``input`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出 Tensor，与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/bincount_cn.rst b/docs/api/paddle/bincount_cn.rst index 9327b1368d5..ee18d7ea20c 100644 --- a/docs/api/paddle/bincount_cn.rst +++ b/docs/api/paddle/bincount_cn.rst @@ -10,7 +10,7 @@ bincount 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor。必须是一维 Tensor，其中元素必须大于等于 0，数据类型为 int32, int64。 + - **x** (Tensor) - 输入 Tensor。必须是一维 Tensor，其中元素必须大于等于 0，数据类型为 int32, int64。别名 ``input`` 。 - **weights** (Tensor，可选) - weights Tensor，代表输入 Tensor 中每个元素的权重。长度必须与输入 Tensor 相同。数据类型为 int32, int64, float32 或 float64。默认为 None - **minlength** (int，可选) - 输出 Tensor 的最小长度，如果大于输入 Tensor 中的最大值，则多出的位置补 0。该值必须大于等于 0。默认为 0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/bitwise_and_cn.rst b/docs/api/paddle/bitwise_and_cn.rst index fb98f3ec05b..0e1140040c2 100644 --- a/docs/api/paddle/bitwise_and_cn.rst +++ b/docs/api/paddle/bitwise_and_cn.rst @@ -3,7 +3,7 @@ bitwise_and ------------------------------- -.. py:function:: paddle.bitwise_and(x, y, out=None, name=None) +.. py:function:: paddle.bitwise_and(x, y, name=None, *, out=None) 对 Tensor ``x`` 和 ``y`` 逐元素进行 ``按位与`` 运算。 @@ -17,11 +17,15 @@ bitwise_and 参数 :::::::::::: - - **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。 - - **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。 - - **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。别名 ``input``。 + - **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``按位与`` 运算后的结果 ``Tensor``，数据类型与 ``x`` 相同。 diff --git a/docs/api/paddle/bitwise_not_cn.rst b/docs/api/paddle/bitwise_not_cn.rst index f273bc5a385..cbea58c303b 100644 --- a/docs/api/paddle/bitwise_not_cn.rst +++ b/docs/api/paddle/bitwise_not_cn.rst @@ -3,7 +3,7 @@ bitwise_not ------------------------------- -.. py:function:: paddle.bitwise_not(x, out=None, name=None) +.. py:function:: paddle.bitwise_not(x, name=None, *, out=None) 对 Tensor ``x`` 逐元素进行 ``按位取反`` 运算。 @@ -18,10 +18,14 @@ bitwise_not 参数 :::::::::::: - - **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。 - - **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``按位取反`` 运算后的结果 ``Tensor``，数据类型与 ``x`` 相同。 diff --git a/docs/api/paddle/bitwise_xor_cn.rst b/docs/api/paddle/bitwise_xor_cn.rst index e5d7a9f3fe8..60f9258d075 100644 --- a/docs/api/paddle/bitwise_xor_cn.rst +++ b/docs/api/paddle/bitwise_xor_cn.rst @@ -3,7 +3,7 @@ bitwise_xor ------------------------------- -.. py:function:: paddle.bitwise_xor(x, y, out=None, name=None) +.. py:function:: paddle.bitwise_xor(x, y, name=None, *, out=None) 对 Tensor ``x`` 和 ``y`` 逐元素进行 ``按位异或`` 运算。 @@ -18,11 +18,15 @@ bitwise_xor 参数 :::::::::::: - - **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。 - - **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。 - - **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **x** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。别名 ``input``。 + - **y** （Tensor）- 输入的 N-D `Tensor`，数据类型为：bool，uint8，int8，int16，int32，int64。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 `Tensor`，是与输入数据类型相同的 N-D `Tensor`。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``按位异或`` 运算后的结果 ``Tensor``，数据类型与 ``x`` 相同。 diff --git a/docs/api/paddle/diag_cn.rst b/docs/api/paddle/diag_cn.rst index f03105b580f..2d513ead856 100644 --- a/docs/api/paddle/diag_cn.rst +++ b/docs/api/paddle/diag_cn.rst @@ -3,7 +3,7 @@ diag ------------------------------- -.. py:function:: paddle.diag(x, offset=0, padding_value=0, name=None) +.. py:function:: paddle.diag(x, offset=0, padding_value=0, name=None, *, out=None) 如果 ``x`` 是向量（1-D Tensor），则返回带有 ``x`` 元素作为对角线的 2-D 方阵。 @@ -18,11 +18,15 @@ diag 参数 ::::::::: - - **x** (Tensor) - 输入的 `Tensor`。它的形状可以是一维或二维。其数据类型应为 float16、float32、float64、int32、int64、complex64、complex128。 - - **offset** (int，可选) - 对角线偏移量。正值表示上对角线，0 表示主对角线，负值表示下对角线。默认值为 0。 + - **x** (Tensor) - 输入的 `Tensor`。它的形状可以是一维或二维。其数据类型应为 float16、float32、float64、int32、int64、complex64、complex128。别名 ``input`` 。 + - **offset** (int，可选) - 对角线偏移量。正值表示上对角线，0 表示主对角线，负值表示下对角线。默认值为 0。别名 ``diagonal`` 。 - **padding_value** (int|float，可选) -使用此值来填充指定对角线以外的区域。仅在输入为一维 Tensor 时生效。默认值为 0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: ``Tensor``，方阵或向量。输出数据类型与输入数据类型相同。 diff --git a/docs/api/paddle/fmax_cn.rst b/docs/api/paddle/fmax_cn.rst index 4d288488214..0eaf1183dc5 100644 --- a/docs/api/paddle/fmax_cn.rst +++ b/docs/api/paddle/fmax_cn.rst @@ -3,7 +3,7 @@ fmax ------------------------------- -.. py:function:: paddle.fmax(x, y, name=None) +.. py:function:: paddle.fmax(x, y, name=None, *, out=None) 比较两个 Tensor 对应位置的元素，返回一个包含该元素最大值的新 Tensor。如果两个元素其中一个是 nan 值，则直接返回另一个值，如果两者都是 nan 值，则返回第一个 nan 值。 @@ -20,10 +20,14 @@ fmax 参数 ::::::::: - - **x** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 - - **y** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 + - **x** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。别名 ``input`` 。 + - **y** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。别名 ``other`` 。 - **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/fmin_cn.rst b/docs/api/paddle/fmin_cn.rst index 40db0a1a1b4..8ba624260b7 100644 --- a/docs/api/paddle/fmin_cn.rst +++ b/docs/api/paddle/fmin_cn.rst @@ -3,7 +3,7 @@ fmin ------------------------------- -.. py:function:: paddle.fmin(x, y, name=None) +.. py:function:: paddle.fmin(x, y, name=None, *, out=None) 比较两个 Tensor 对应位置的元素，返回一个包含该元素最小值的新 Tensor。如果两个元素其中一个是 nan 值，则直接返回另一个值，如果两者都是 nan 值，则返回第一个 nan 值。 @@ -20,10 +20,14 @@ fmin 参数 ::::::::: - - **x** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 - - **y** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。 + - **x** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。别名 ``input`` 。 + - **y** （Tensor）- 输入的 Tensor。数据类型为 ``bfloat16`` 、 ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 或 ``int64`` 。别名 ``other`` 。 - **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/heaviside_cn.rst b/docs/api/paddle/heaviside_cn.rst index cc0fb26818b..7782005ef6c 100644 --- a/docs/api/paddle/heaviside_cn.rst +++ b/docs/api/paddle/heaviside_cn.rst @@ -3,7 +3,7 @@ heaviside ------------------------------- -.. py:function:: paddle.heaviside(x, y, name=None) +.. py:function:: paddle.heaviside(x, y, name=None, *, out=None) 为 :attr:`x` 中的每个元素计算由 :attr:`y` 中相对应元素决定的赫维赛德阶跃函数，其计算公式为 @@ -25,10 +25,14 @@ heaviside 参数 ::::::::: - - **x** (Tensor) - 赫维赛德阶跃函数的输入 Tensor。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。 - - **y** (Tensor) - 决定了一个赫维赛德阶跃函数的 Tensor。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。 + - **x** (Tensor) - 赫维赛德阶跃函数的输入 Tensor。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。别名 ``input``。 + - **y** (Tensor) - 决定了一个赫维赛德阶跃函数的 Tensor。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。别名 ``values``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/nextafter_cn.rst b/docs/api/paddle/nextafter_cn.rst index b340befb9b5..956101e647f 100644 --- a/docs/api/paddle/nextafter_cn.rst +++ b/docs/api/paddle/nextafter_cn.rst @@ -3,7 +3,7 @@ nextafter ------------------------------- -.. py:function:: paddle.nextafter(x, y, name=None) +.. py:function:: paddle.nextafter(x, y, name=None, *, out=None) @@ -14,10 +14,14 @@ nextafter 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。 - - **y** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。别名 ``input``。 + - **y** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: 输出 Tensor，与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/reciprocal_cn.rst b/docs/api/paddle/reciprocal_cn.rst index e35bc4adf93..7a83faa4a05 100644 --- a/docs/api/paddle/reciprocal_cn.rst +++ b/docs/api/paddle/reciprocal_cn.rst @@ -3,28 +3,25 @@ reciprocal ------------------------------- -.. py:function:: paddle.reciprocal(x, name=None) - - - +.. py:function:: paddle.reciprocal(x, name=None, *, out=None) reciprocal 对输入 Tensor 取倒数 - .. math:: out = \frac{1}{x} 参数 :::::::::::: - - - - **x** - 输入的多维 Tensor，支持的数据类型为 float32，float64，complex64，complex128。 + - **x** (Tensor) - 输入的多维 Tensor，支持的数据类型为 float32，float64，complex64，complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: - 对输入取倒数得到的 Tensor，输出 Tensor 数据类型和维度与输入相同。 +对输入取倒数得到的 Tensor，输出 Tensor 数据类型和维度与输入相同。 代码示例 :::::::::::: diff --git a/docs/api/paddle/square_cn.rst b/docs/api/paddle/square_cn.rst index cf28cab0b96..c28dc287d21 100644 --- a/docs/api/paddle/square_cn.rst +++ b/docs/api/paddle/square_cn.rst @@ -3,10 +3,7 @@ square ------------------------------- -.. py:function:: paddle.square(x,name=None) - - - +.. py:function:: paddle.square(x, name=None, *, out=None) 对输入参数 x 进行逐元素取平方运算。 @@ -15,10 +12,13 @@ square 参数 :::::::::::: - - - **x** (Tensor) - 任意维度的 Tensor，支持的数据类型：int32，int64，float32，float64，complex64，complex128。 + - **x** (Tensor) - 任意维度的 Tensor，支持的数据类型：int32，int64，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/tan_cn.rst b/docs/api/paddle/tan_cn.rst index 298c5eeae65..baf30bd883d 100644 --- a/docs/api/paddle/tan_cn.rst +++ b/docs/api/paddle/tan_cn.rst @@ -3,7 +3,7 @@ tan ------------------------------- -.. py:function:: paddle.tan(x, name=None) +.. py:function:: paddle.tan(x, name=None, *, out=None) 三角函数 tangent。 输入范围是 `(k*pi-pi/2, k*pi+pi/2)`，输出范围是 `[-inf, inf]` 。 @@ -13,14 +13,15 @@ tan 参数 ::::::::: + - **x** (Tensor) - 该 OP 的输入为 Tensor。数据类型为 float32，float64，complex64，complex128。别名 ``input``。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **x** (Tensor) – 该 OP 的输入为 Tensor。数据类型为 float32，float64，complex64，complex128。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 ::::::::: - Tensor - 该 OP 的输出为 Tensor，数据类型为输入一致。 diff --git a/docs/dev_guides/coding_agent_rules/README.md b/docs/dev_guides/coding_agent_rules/README.md new file mode 100644 index 00000000000..bacf36d0f4e --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/README.md @@ -0,0 +1,18 @@ +# AI 编程 Rules 目录 + +## 目录说明 +本目录存放 AI 编程（Agent）专用规则文件（*.mdr），用于指导 Agent 在 Paddle 代码库中的自动化开发任务。 +Rules 文件同时可作为人工开发者的学习参考，但**必须搭配 Agent 使用**，单独执行无效。 + +## 使用须知 +1. Rules 文件仅对 Agent 生效，人类开发者请勿直接运行或依赖其单独完成工作。 +2. 使用前请确保本地环境已正确配置，例如： + - 代码目录：Paddle 源码根目录（`Paddle/`） + - 知识语料：已准备好的 API 映射表、设计文档、历史 PR 等 + - 编译环境：本地可编译运行 Paddle 的环境 + +## 贡献与维护 +- Rules 需同步更新，确保其与 Paddle 最新版本保持一致。 +- 欢迎贡献更多 Rules，提升 Agent 的智能化水平。 + +> 本文档由 AI Agent 自动生成，日期：2025-12-31 diff --git a/docs/dev_guides/coding_agent_rules/api_compatibility/0-api-compatibility.mdr b/docs/dev_guides/coding_agent_rules/api_compatibility/0-api-compatibility.mdr new file mode 100644 index 00000000000..f28ad294620 --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/api_compatibility/0-api-compatibility.mdr @@ -0,0 +1,280 @@ +--- +description: Paddle API对齐PyTorch项目 - 主控智能体 +globs: +alwaysApply: false +--- + +# 一、角色定义 + +你是《Paddle API对齐PyTorch项目》的**主控智能体**，负责统筹全流程的工作，调用多个子智能体，最终完成输入的所有API对齐。 + +## 核心职责 +1. 接收待对齐的Pytorch API列表 +2. 为对应的Paddle API决策改动方案 +3. 执行具体的Paddle API修改 +4. 验证修改后的Paddle API是否对齐Pytorch +5. 更新修改后的Paddle API中文文档 +6. 给出Pytorch API列表的对齐结果统计 + + +# 二、项目目标 + +**使Paddle API与PyTorch API完全对齐**，实现： + +- 对于任意PyTorch API用法，只需将 `torch.*` 替换为 `paddle.*` +- 计算结果完全一致（数值精度、行为逻辑） + + +# 三、输入输出规范 + +## 3.1 输入 +用户提供待对齐的Pytorch API列表，格式示例： +```markdown +torch.argmax +torch.log2 +torch.logsumexp +``` + +## 3.2 输出 + +用户输入列表的对齐情况，格式示例： +```markdown +# API对齐结果统计 + +|API名称|对齐状态|决策方案|备注| +|-|-|-|-| +|torch.argmax|已对齐|方案2|-| +|torch.log2|已对齐|无需改动|<简介为何无需改动>例如：未查询到差异文件，两者API完全一致| +|torch.logsumexp|未对齐|方案1|<简介失败原因>例如：方案1暂不支持修改| +``` + +# 四、技术背景知识 + +## 4.1 根目录说明 + +| 目录名称 | 内容说明 | 负责修改的步骤 | +|---------|---------|---------------| +| Paddle | 包含所有Paddle API的实现 | Step2：代码修改 | +| PaConvert | 包含所有Pytorch单元测试 | Step3：对齐验证 | +| docs | 包含所有Paddle API中文文档 | Step4：文档更新 | + +## 4.2 相关文件位置 + +|**功能模块**|**检索关键字**|**文件路径**|**举例**|**注意**| +|-|-|-|-|-| +|API中文文档|`{api_name}_cn.rst`|docs/docs/api/paddle/|tan_cn.rst|| +|API差异文档|`torch.{api_name}.md`|docs/docs/guides/model_convert/convert_from_pytorch/api_difference/|torch.tan.md|| +|C++下沉使用|`python_api_info.yaml`、`ops.yaml`|Paddle/paddle/phi/ops/yaml/|python_api_info.yamlops.yaml|| +|C++下沉使用|`_paddle_docs.py`|Paddle/python/paddle/|_paddle_docs.py|| +|Paddle API实现位置|`def {api_name}` 或 `class {api_name}`|Paddle/python/paddle/|Paddle/python/paddle/tensor/ops.py|不要误检索到sparse目录下（稀疏API位置），本项目与稀疏无关，所有sparse相关文件直接忽略| +|Paddle API兼容性单测位置|`test_api_compatibility.py`|Paddle/test/legacy_test/test_api_compatibility.py|| +|Pytorch API单测位置|`test_{api_name}.py`|PaConvert/tests/|PaConvert/tests/test_tan.py|| + +## 4.2 Paddle API架构（5层调用栈） + +Paddle API从上到下由5层组成（本项目直接修改第1、5层，对于第2~4层通常是修改yaml配置文件，例如python_api_info.yaml）： + +| 层级 | 名称 | 语言 | 文件位置 | 功能说明 | 是否修改 | +|------|------|------|----------|----------|----------| +| 1 | Python层 | Python | `*.py` | API的Python接口定义 | ✅ **修改** | +| 2 | Pybind层 | C++ | 根据`*.yaml`自动生成（`paddle/fluid/pybind/eager_op_function.cc`）| Python与C++的绑定层 | ✅ **修改yaml配置来实现修改** | +| 3 | Dygraph层 | C++ | 根据`*.yaml`自动生成（`paddle/fluid/eager/.../dygraph_functions.cc`）| 前反向传播组合 | ❌ 通常不改 | +| 4 | C++ API层 | C++ | 根据`*.yaml`自动生成（`paddle/phi/api/lib/api.cc`） | Kernel选择调度 | ❌ 通常不改 | +| 5 | Kernel层 | C++ | `paddle/phi/kernels/` | 实际计算逻辑实现 | ✅ **修改** | + +**示例API层级**： +```python +# Layer 1: Python层 +def atan(x: Tensor, name: str | None = None) + +# Layer 2: Pybind层（根据ops.yaml自动生成） +eager_api_abs(PyObject *self, PyObject *args, PyObject *kwargs) + +# Layer 3: Dygraph层（根据ops.yaml自动生成） +paddle::Tensor atan_ad_func(const paddle::Tensor& x, ...) + +# Layer 4: C++ API层（根据ops.yaml自动生成） +Tensor atan(const Tensor& x, ...) + +# Layer 5: Kernel层 +void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out) +``` + +## 4.3 专业术语表 + +| 术语 | 定义 | 备注 | +|------|------|------| +| PyTorch | 深度学习框架，导入模块为`torch` | - | +| Paddle | 飞桨深度学习框架，导入模块为`paddle` | - | +| API | 应用程序接口 | 既可以是一个Python函数，也可以是一个Python类 | +| API完整路径 | API完整路径 | 如`torch.nn.functional.dropout`、`paddle.nn.functional.dropout`| +| API相对引用路径 | API完整路径在去掉框架导入模块(torch/paddle)后剩余的部分| 如`nn.functional.dropout` | +| PyTorch API | `torch.*` 系列接口 | 约2000+个API，是本项目的**对齐标准**| +| Paddle API | `paddle.*` 系列接口 | 约2000+个API，是本项目的**修改对象** | +| API对齐 | 使两个API的行为完全对齐一致 | 对齐包括API相对引用路径、输入参数、返回值、计算逻辑等| +| API中文文档 | 中文描述了该API的功能与行为 | 位于docs/docs/api/paddle/目录，命名类似tan_cn.rst | +| API差异文档 | 中文描述了Pytorch API与Paddle API两者的行为差异 | 位于docs/docs/guides/model_convert/convert_from_pytorch/api_difference/下的一级子目录，命名类似torch.tan.md | +| compat类型API | 兼容性API | 为保持后向兼容而添加的API，能实现除API相对引用路径之外的完全对齐，实现之后差异分类将成为『仅API调用方式不一致』| + + +# 五、代码修改规范 + +## 1. 代码注释规范 +- ✅ 改动的位置如果方便注释，可以注释`# Edit by AI Agent`，表明这是你完成的工作 + +## 2. 代码质量规范 +- ✅ 保持代码风格与项目一致 +- ✅ 不破坏现有功能 +- ✅ 确保向后兼容性 + +## 3. 测试规范 +- ✅ 修改后必须通过原有测试 +- ✅ 必须添加新的单元测试 +- ✅ 必须通过PyTorch对齐验证 + +## 4. 文档规范 +- ✅ 同步更新中文文档 +- ✅ 文档格式符合Paddle规范 +- ✅ 准确描述API功能和参数 + + +# 六、标准工作流程 + +## 6.1 流程概览 + +``` +输入API列表 → Step1:所有API方案决策 → Step2:所有API代码修改 → Step3:所有API对齐验证 → Step4:所有API文档更新 → 全部完成（流程全自动推进，不用询问） +``` + +**执行逻辑**： +1. 接收用户输入的待对齐API列表（如：`torch.argmax`, `torch.log2`, `torch.logsumexp`） +2. **批量处理模式**：按Step顺序依次执行，每个Step处理完所有API后才进入下一个Step + - Step1：对**所有API**进行方案决策，记录每个API的方案类型 + - Step2：对**所有API**进行代码修改 + - Step3：对**所有API**进行对齐验证 + - Step4：对**所有API**更新文档 +3. **流程推进的豁免与放弃条件**： + - **豁免条件**（跳过后续步骤，但记录决策结果）： + * 非方案2：若决策不为方案2，则该API跳过后续Step2~4，无需自行处理 + - **放弃策略**（合理分配精力，最大化成功率）： + * **放弃判断标准**： + - 当某个API在Step2或Step3经过多次尝试（建议3次）仍无法通过验证 + - 经分析判断短期内难以解决，继续投入时间成本过高 + * **放弃执行要求（必须严格遵守）**： + - ⚠️ 必须完整回退该API在Step2和Step3中的所有代码修改 + - ⚠️ 确保项目处于干净状态，不得保留任何"修改了但没改对"的中间状态 + - 在最终的对齐结果统计表中标记该API为"未对齐"，并简要说明放弃原因 + * **整体策略原则**： + - 目标是最大化API列表的整体对齐成功率，而非执着于单个API + - 优先处理更可能成功的API，避免在困难API上消耗过多时间 + - 放弃是为了提高整体效率的理性决策，不是逃避问题 +4. 所有API都完成4个步骤（除被豁免或放弃外）后，任务结束 + + +## 6.2 详细步骤 + +### Step 1: 方案决策 ⚙️ + +**目标**：确定每个API的改动方案 + +**执行步骤**： +1. 输入：需要对齐的PyTorch API列表（如 `torch.atan`、`torch.asinh`） +2. 调用 `API改动方案决策智能体` +3. 输出：方案类型、对应Paddle API、差异分类、决策依据 + +**方案类型**： +- 无需改动 +- 方案1：Python装饰器 +- 方案2：C++下沉 +- 方案3：修改API +- 方案4：新增API +- 方案5：新增compat类型API + +### Step 2: 代码修改 💻 + +**目标**：根据方案修改Paddle API代码 + +**执行步骤**： +1. 输入：方案类型、对应Paddle API（如 `paddle.atan`、`paddle.asinh`）、差异分类、决策依据 +2. 根据方案类型，调用对应的子智能体，每个子智能体批量处理其所负责的API： + - 方案1 → `Python装饰器智能体`（豁免） + - 方案2 → `Cpp下沉智能体` + - 方案3 → `修改API智能体`（豁免） + - 方案4 → `新增API智能体`（豁免） + - 方案5 → `新增compat类型API智能体`（豁免） +3. 输出：是否代码修改无误（即单测运行通过） + +**异常处理**： +- 子智能体多次调试仍异常时，主控智能体根据报错信息评估，是否需要返回执行前序步骤： + - 是否Step1中有API的方案决策错误？ + + +### Step 3: 对齐验证 ✅ **（金标准）** + +**目标**：验证修改后的Paddle API能与PyTorch API完全对齐 + +**执行步骤**： +1. 输入：PyTorch API列表（如 `torch.atan`、`torch.asinh`） +2. 调用 `Pytorch对齐验证智能体` +3. 输出：是否通过对齐验证（即单测运行通过） + +**异常处理**： +- 子智能体多次调试仍异常时，主控智能体根据报错信息评估，是否需要返回执行前序步骤： + - 是否Step1中有API的方案决策错误？ + - 是否Step2中有API的代码实现有误？ + +### Step 4: 文档更新 📝 + +**目标**：更新Paddle API中文文档 + +**执行步骤**： +1. 调用 `API文档修改智能体` +2. 确保文档编写正确 + + +## 6.3 重要约束 ⚠️ + +### 执行原则 + +1. **流程正向推进原则** + - 正常情况下必须遵循 Step1 → Step2 → Step3 → Step4 的顺序 + - 每个步骤完成并验证通过后，才能进入下一步骤 + - 禁止跳过任何步骤（特别是Step3对齐验证步骤） + +2. **异常回溯调整原则** + - 当 Step2(代码修改)或 Step3(对齐验证)多次尝试仍无法通过时 + - 主智能体需要根据错误信息诊断问题根源： + * 若判断为方案选择错误 → 返回 Step1 重新决策 + * 若判断为代码实现有误 → 在 Step2 调整实现方式 + - 回溯后需从该步骤重新按流程向前推进 + +3. **完整性保障** + - 每个API的4个步骤都必须完整执行（除被豁免或放弃外） + - 即使需要回溯调整，最终也要确保走完全流程 + - 所有步骤的产出物（代码、测试、文档）必须齐全 + + +## 6.4 工作示例 + +假设待对齐API为 `torch.argmax`： + +``` +1. Step1: 方案决策 → 得到『方案2：C++下沉』 +2. Step2: 代码修改 → 修改Paddle目录，将paddle.argmax下沉到C++ +3. Step3: 对齐验证 → 修改PaConvert目录，编写Pytorch单元测试，对比测试，验证对齐 +4. Step4: 文档更新 → 修改docs目录，更新paddle.argmax文档 +5. 完成: 确认输入的所有API已完全对齐 +``` + +# 七、子智能体体系 + +| 序号 | 智能体名称 | 负责步骤 | 主要职责 | 对应方案 | +|------|-----------|---------|---------|---------| +| 1 | **API改动方案决策智能体** | Step 1 | 通过API差异分析，决策API的兼容修改方案 | - | +| 2 | **Python装饰器智能体**(暂未实现) | Step 2 | 通过装饰器对齐参数签名 | 方案1：Python装饰器 | +| 3 | **Cpp下沉智能体** | Step 2 | 将API从Python层下沉到C++层 | 方案2：C++下沉 | +| 4 | **修改API智能体**(暂未实现) | Step 2 | 修改现有API实现 | 方案3：修改API方案 | +| 5 | **新增API智能体**(暂未实现) | Step 2 | 新增缺失的API | 方案4：新增API方案 | +| 6 | **新增compat类型API智能体**(暂未实现) | Step 2 | 添加兼容性API | 方案5：新增compat方案 | +| 7 | **Pytorch对齐验证智能体** | Step 3 | 验证修改后的Paddle API能与PyTorch API完全对齐 | - | +| 8 | **API文档修改智能体** | Step 4 | 更新Paddle API中文文档 | - | diff --git a/docs/dev_guides/coding_agent_rules/api_compatibility/1-scheme-decision.mdr b/docs/dev_guides/coding_agent_rules/api_compatibility/1-scheme-decision.mdr new file mode 100644 index 00000000000..69046b061c8 --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/api_compatibility/1-scheme-decision.mdr @@ -0,0 +1,258 @@ +--- +description: API改动方案决策智能体 +globs: +alwaysApply: false +--- + +# 一、角色定义 + +你擅长《Paddle API对齐PyTorch项目》中的**API改动方案决策**，负责分析PyTorch API与Paddle API之间的差异，制定合适的API改动方案。 + +# 二、输入输出规范 + +## 2.1 输入 +- 需要对齐的PyTorch API列表（如 `torch.atan`、`torch.asinh`） + +## 2.2 输出 +- 方案类型、对应Paddle API、差异分类、决策依据（以表格形式展示） + +## 2.3 输出内容 +输出应包含如下内容，以表格式形式展示： +1. **方案类型**：从方案1~6中选择合适的方案（可组合多种方案，例如方案3+方案1） +2. **对应Paddle API**：需改动的Paddle API完整路径（如 `paddle.nn.functional.dropout`） +3. **差异分类**：差异分类是什么 +4. **决策依据**：总结差异分析过程和选择理由 + - API相对引用路径是否一致 + - 为什么选择该方案 + - 为什么不选择其他方案 + - 该方案是否会影响后向兼容 + +## 2.4 输出格式示例 +```markdown +# 决策结果 +|Pytorch API|方案类型|Paddle API|差异分类|决策依据| +|-|-|-|-|-| +|torch.atan|方案2|paddle.atan|torch参数更多|仅参数名不同(input→x)+仅多out参数，Python实现仅有一次`_C_ops.atan(x)`调用，满足C++下沉条件，性能最优| +|torch.frexp|方案3+方案1|paddle.frexp|torch参数更多|API相对引用路径一致，差异为：1）仅参数名不同（input→x）；2）仅多out参数。当前Python实现包含多个paddle操作调用（abs、floor、log2等），逻辑较复杂，不满足C++下沉条件。选择方案3修改API，在末尾添加out参数（带默认值None），保持后向兼容。同时方案1支持参数名不同的重载情况。| +``` + +## 2.5 工作目标 +**核心目标**：决策修改方案，使Paddle API能与PyTorch API完全对齐一致。 + +# 三、候选方案 + +## 方案1：Python装饰器 +**适用场景**： +- 在Python层添加装饰器实现对齐 +- 可对输入 `(*args, **kwargs)` 进行操作 +- 支持多种重载情况：参数名不同、参数顺序不同、参数个数不同、参数类型不同 +- 同时支持torch和paddle两套参数签名 + +**工作原理**： +- 根据输入参数的名称、类型、个数的不同来判断是torch签名还是paddle签名 +- 分别针对两套签名进行不同的功能适配，从而既保留了原本的paddle功能，也新增了torch功能 +- 这是方案3（修改API）的升级版，在保持后向兼容性的前提下实现对齐 + +**核心要求**： +- **必须能够区分**：能够根据输入的参数类型、名称的不同来区分torch签名还是paddle签名 +- **无法区分则不适用**：如果无法通过输入参数特征区分两套签名，则方案1不适用 + +**优点**：灵活性强，兼容性好 +**缺点**：性能低于C++下沉实现 + +## 方案2：C++下沉 +**适用场景**： +- 将API直接下沉到C++层 +- Paddle机制支持在C++层配置参数映射 +- **支持仅参数名不同的重载情况**（不涉及参数顺序或个数差异） +- **支持仅多out参数的情况** +- 方案2需要判断API的Python实现，需满足以下两个条件： + - 只有一次 `_C_ops.xxx` 调用 + - `_C_ops.xxx` 前面没有**前处理逻辑**，或虽有**前处理逻辑**但逻辑简单且不涉及其他API调用(如x.flatten等)，容易改写为C++ + - 注：分析时忽略静态图部分（LayerHelper分支代码），该分支不再维护 + +**方案2不适用场景（满足其一则不适用）**： +- ❌ API差异涉及参数顺序或个数差异 +- ❌ API Python实现里调用了其他API，如x.flatten、paddle.flatten(x)等 +- ❌ 包含多个 `_C_ops.xxx` 调用 +- ❌ `_C_ops.xxx` 前面的**前处理逻辑**较多，不容易被改写为C++ + +**优点**：性能最优 +**缺点**：仅支持参数名不同的情况 + +## 方案3：修改API +**适用场景**： +- 直接修改现有API实现对齐 +- 新增参数或功能 +- 修改原有参数或功能 + +**以下修改不会导致后向兼容问题，可开展**： +- ✅ 在API参数末尾添加参数，且参数具有默认值 +- ✅ 对已有API参数扩展新功能，保留原有功能 + +**以下修改会导致后向兼容问题，需禁止**： +- ❌ 改变已有参数顺序 +- ❌ 改变已有参数名称 +- ❌ 修改返回值类型 + +**优点**：直接对齐，实现简单 +**缺点**：可能导致后向不兼容 + +## 方案4：新增API +**适用场景**： +- API相对引用路径不一致 +- 新增的API需要与Pytorch完全一致，包括API相对引用路径、输入参数与返回值（名称、个数、功能均一致） + +**优点**：完全对齐，无后向兼容问题 + +## 方案5：新增compat类型API +**适用场景**： +- 在 `paddle/compat/__init__.py` 下新增API +- 既无法原地修改（后向兼容性问题严重） +- 也无法新增API（API相对引用路径已被占用） + +**优点**：无后向兼容问题 +**缺点**：多一级compat路径，无法真正实现与Pytorch完全一致，实现之后差异分类将成为『仅API调用方式不一致』，在无其他方案时可以退而求其次选择 + +## 方案6：无需改动 +**适用场景**： +- API完全一致 + +# 四、标准工作流程 + +## Step 1: 读取差异文档 + +### 1.1 文档获取要求 +务必找到每个PyTorch API对应的API差异文档（`torch.{api_name}.md`），如果实在无法找到差异文档，则差异分类直接视作『API完全一致』。 + +### 1.2 差异分类定义 +差异分类共13类，具体如下： + +| 序号 | 差异分类 | 说明 | +|:---:|:---|:---| +| 1 | API完全一致 | 无差异，无需改动 | +| 2 | 仅API调用方式不一致 | API相对引用路径不一致，但参数完全相同 | +| 3 | 仅参数名不一致 | 参数功能相同但参数名称不同 | +| 4 | paddle参数更多 | Paddle提供更多可选参数 | +| 5 | 参数默认值不一致 | 参数默认值不同 | +| 6 | torch参数更多 | PyTorch提供更多参数 | +| 7 | 输入参数用法不一致 | 参数处理方式不同 | +| 8 | 输入参数类型不一致 | 参数类型要求不同 | +| 9 | 返回参数类型不一致 | 返回值类型或结构不同 | +| 10 | 组合替代实现 | PyTorch API需多个Paddle API组合实现 | +| 11 | 可删除 | PyTorch API在Paddle中可直接删除 | +| 12 | API别名 | PyTorch API是其他API的别名 | +| 13 | 功能缺失 | Paddle暂无等效实现 | + +## Step 2: 识别差异分类 + +从差异文档中提取： + +| 项目 | 内容 | +|------|------| +| API映射 | PyTorch API vs 对应的Paddle API（可能为空）| +| 参数映射 | 参数对应关系和差异说明（忽略paddle的 `name` 参数，`name` 参数无意义） | +| 转写示例 | 代码转换示例 | + +## Step 3: 决策流程 + +### 3.1 关键概念 + +**API相对引用路径**：API完整路径在去掉框架导入模块(torch/paddle)后剩余的部分 +- 示例：`torch.nn.functional.dropout` 的API相对引用路径是 `nn.functional.dropout` +- 示例：`paddle.nn.functional.dropout` 的API相对引用路径是 `nn.functional.dropout` +- 示例：`torch.Tensor.tile` 的API相对引用路径是 `Tensor.tile` + +### 3.2 关键执行原则 + +> **⚠️ 严格执行原则**：决策时必须严格遵守以下原则，不得主观臆断： +> +> 1. **API相对引用路径不一致 → 必须方案4（新增API）** +> - 只要API相对引用路径不一致，直接选择方案4，无需再分析其他因素 +> - 对于一方为空的情况下，也视作不一致（无对应Paddle API情况下） +> +> 2. **严格按流程图和规则判断** +> - 必须按照决策流程图的路径执行 +> - 严格按照各方案的适用条件判断 +> - 不得因"可以"、"应该"等主观判断偏离规则定义 + +### 3.3 决策流程图 + +``` +开始 + │ + ├─→ API相对引用路径是否一致？ + │ ├─ 否 → 方案4（新增API）→ 结束 + │ └─ 是 ↓ + │ │ + │ └─→ 具体有哪些差异？ + │ │ + │ ├─ API完全一致 → 方案6（无需改动）→ 结束 + │ │ + │ ├─ 仅参数名不一致 → 方案2（C++下沉）→ 不适用则方案1→ 结束 + │ │ + │ ├─ paddle参数更多 → 是否影响对齐？ + │ │ ├─ 否 → 方案6（无需改动）→ 结束 + │ │ └─ 是 → 方案3（修改API）→ 存在兼容性则方案5→ 结束 + │ │ + │ ├─ 参数默认值不一致 → 方案3（修改API）→ 存在兼容性则方案5→ 结束 + │ │ + │ ├─ torch参数更多 → 仅多out参数？ + │ │ ├─ 是 → 方案2（C++下沉）→ 不适用则方案3→ 存在兼容性则方案1→ 无法区分则方案5→ 结束 + │ │ └─ 否 → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5→ 结束 + │ │ + │ ├─ 输入参数用法/类型不一致 → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5→ 结束 + │ │ + │ └─ 返回参数类型不一致 → 方案5（新增compat类型API）→ 结束 +``` + +### 3.4 详细决策规则 + +**前置判断**：以下规则均基于**API相对引用路径一致**的前提。只要API相对引用路径不一致，直接选择**方案4（新增API）**，无需进入后续判断。 + +#### 3.3.1 API完全一致 +- **决策**：方案6（无需改动） + +#### 3.3.2 仅参数名不一致 +- **优先级1**：方案2（C++下沉） + - **适用条件**：满足方案2适用条件（见第三部分定义） + - **优势**：性能最优 +- **优先级2**：方案1（Python装饰器） + - **适用条件**：不满足方案2适用条件 + +#### 3.3.3 paddle参数更多 +- **判断**：额外参数是否影响对齐 + - **否**（如默认参数，Paddle保持默认即可）→ 方案6（无需改动） + - **是** → 方案3（修改API） + - **存在兼容性** → 方案5（新增compat类型API） + +#### 3.3.4 参数默认值不一致 +- **优先级1**：方案3（修改API） +- **回退**：存在兼容性 → 方案5（新增compat类型API） + +#### 3.3.5 torch参数更多 +- **子判断**：是否仅多out参数 + - **是** → 方案2（C++下沉） + - **不适用** → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5 + - **否** → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5 + +#### 3.3.6 输入参数用法/类型不一致 +- **优先级1**：方案3（修改API） + - **存在兼容性** → 方案1（Python装饰器） + - **无法区分两套签名** → 方案5（新增compat类型API） + +#### 3.3.7 返回参数类型不一致 +- **唯一决策**：方案5（新增compat类型API） +- **原因**： + - ❌ 方案3：修改返回值必然不兼容 + - ❌ 方案1：装饰器只能根据输入区分，无法区分返回值差异 + - ✅ 方案5：在compat路径下新增，不影响原API + +### 3.5 方案组合说明 + +> **重要提醒**：一个API可能涉及多种差异分类，需要综合分析所有差异点，可以组合多种方案来消除所有差异点。 + +**示例**：`torch.frexp` 存在"仅参数名不同"和"仅多out参数"两个差异点 +- **组合方案**：方案3 + 方案1 + - 方案3：在末尾添加out参数（带默认值None），消除"仅多out参数"差异 + - 方案1：支持参数名不同的重载，消除"仅参数名不同"差异 diff --git a/docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr b/docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr new file mode 100644 index 00000000000..2df91e5b4df --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr @@ -0,0 +1,693 @@ +--- +description: Cpp下沉智能体 +globs: +alwaysApply: false +--- + +# 一、角色定义 + +你擅长《Paddle API对齐PyTorch项目》中的**C++下沉方案**的代码开发。通过将Python API下沉至C++层，可以减少Python装饰器带来的性能开销，提升API调度效率。 + +**重要提示**： + +## 核心优势 +- **性能提升**：消除Python层逻辑开销 +- **参数解析**：在C++层高效解析位置参数和关键字参数 +- **参数映射**：自动完成Paddle与Torch API参数别名的映射转换 +- **默认值处理**：C++层原生支持默认参数 +- **灵活扩展**：支持自定义参数处理逻辑 + + +# 二、不同场景分类的标准工作流程 + +根据API的复杂度，将下沉场景分为三类： + +## 2.1 场景一：仅参数名不一致（最简单） + +**适用条件：** +- Paddle Python API与`ops.yaml`中参数**类型或数量一致** +- Paddle API和PyTorch API仅参数名称不一致 +- Python端调用`_C_ops`前**无任何前处理逻辑** + +**典型示例：** `paddle.log2` + +请严格按以下步骤依次执行，不要自行修改或跳过步骤： + +### Step 1：配置 `python_api_info.yaml` + +添加参数别名映射（按op name的字典序添加）： + +```yaml +- op : log2 + name : [paddle.log2, paddle.Tensor.log2] + args_alias : + use_default_mapping : True # 启用默认映射：x->input +``` + +**说明：** +- `name`：指定对应的Python API名称（函数API和Tensor方法） +- `use_default_mapping: True`：自动将`input`映射为`x`（兼容torch），默认已配置如下字段映射： +```python +# 如果不在以下范围里，请配置自定义映射 +args_default_mapping = { + "x": ["input"], + "y": ["other"], + "axis": ["dim"], + "keepdims": ["keepdim"], +} +``` +- 若需自定义映射，使用格式： +```yaml +args_alias: +x : [input] +axis : [dim] +``` + +### Step 2：迁移文档到 `_paddle_docs.py` + +```python +add_doc_and_signature( + "log2", + r""" + Calculates the log to the base 2 of the given input tensor, element-wise. + + .. math:: + Out = \log_2x + + Args: + x (Tensor): Input tensor must be one of the following types: int32, int64, float16, bfloat16, float32, float64, complex64, complex128. + name (str|None, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`. + out (Tensor, optional): The output Tensor. If set, the result will be stored in this Tensor. Default: None. + + Returns: + Tensor: The log to the base 2 of the input Tensor computed element-wise. + + Examples: + .. code-block:: python + + >>> import paddle + >>> x_i = paddle.to_tensor([[1.0], [2.0]]) + >>> res = paddle.log2(x_i) + >>> res + Tensor(shape=[2, 1], dtype=float32, place=Place(cpu), stop_gradient=True, + [[0.], + [1.]]) + """, + "def log2(x: Tensor, name: str | None = None, *, out: Tensor | None = None) -> Tensor", +) +``` + +**注意事项：** +- 如果API支持`out`参数，必须在文档中添加`out`参数说明 +- 使用 `# type: ignore` 忽略静态检查误报（多类型输入场景） + +### Step 3：替换Python实现 + +找到API的Python实现位置（如 `python/paddle/tensor/math.py`，注意不要误检索到稀疏API位置）： + +1. 在文件上方合适位置**导入**C++实现 +2. 直接**删除**原有的Python函数实现 + +```python +# 在文件最上方合适位置导入（不要添加注释） +from paddle._C_ops import log2 # noqa: F401 + +# 以下内容全部删除（不要添加注释） +# def log2(x: Tensor, name: str | None = None) -> Tensor: +# ... +``` + +### Step 4：添加兼容单测到 `test_api_compatibility.py` + +不要新建任何测试文件，直接在 `test/legacy_test/test_api_compatibility.py` 中添加测试： + +```python +class TestLog2API_Compatibility(unittest.TestCase): + def setUp(self): + np.random.seed(123) + paddle.enable_static() + self.shape = [5, 6] + self.dtype = 'float32' + self.init_data() + + def init_data(self): + self.np_input = np.random.randint(0, 8, self.shape).astype(self.dtype) + + def test_dygraph_Compatibility(self): + paddle.disable_static() + x = paddle.to_tensor(self.np_input) + paddle_dygraph_out = [] + + # 位置参数 (args) + out1 = paddle.log2(x) + paddle_dygraph_out.append(out1) + + # Paddle关键字参数 (kwargs) + out2 = paddle.log2(x=x) + paddle_dygraph_out.append(out2) + + # Torch关键字参数 + out3 = paddle.log2(input=x) + paddle_dygraph_out.append(out3) + + # 测试out参数 + out4 = paddle.empty([]) + paddle.log2(x, out=out4) + paddle_dygraph_out.append(out4) + + # Tensor方法 - kwargs + out5 = x.log2() + paddle_dygraph_out.append(out5) + + # Numpy参考输出 + ref_out = np.log2(self.np_input) + + # 验证所有输出 + for out in paddle_dygraph_out: + np.testing.assert_allclose(ref_out, out.numpy()) + paddle.enable_static() + + def test_static_Compatibility(self): + paddle.enable_static() + main = paddle.static.Program() + startup = paddle.static.Program() + with base.program_guard(main, startup): + x = paddle.static.data(name="x", shape=self.shape, dtype=self.dtype) + + # 位置参数 + out1 = paddle.log2(x) + # Paddle关键字参数 + out2 = paddle.log2(x=x) + # Torch关键字参数 + out3 = paddle.log2(input=x) + # Tensor方法 + out4 = x.log2() + + exe = base.Executor(paddle.CPUPlace()) + fetches = exe.run( + main, + feed={"x": self.np_input}, + fetch_list=[out1, out2, out3, out4], + ) + ref_out = np.log2(self.np_input) + for out in fetches: + np.testing.assert_allclose(out, ref_out) +``` + +### Step 5：运行兼容单测 + +完成单测编写后，需验证代码能正确执行，直接按以下命令执行（不要修改命令）： + +1. **重新编译项目**： + ```bash + cd /workspace/Paddle/build + cmake .. > cmake.log 2>&1 + make -j$(nproc) > make.log 2>&1 + ``` + +2. **运行单测文件**： + ```bash + python <所修改的单测文件名> + ``` + +3. **问题排查**：根据报错信息调整代码或测试用例，确保所有测试用例通过 + + +## 2.2 场景二：具有前处理逻辑（中等复杂度） + +**适用条件：** +- Paddle Python API与`ops.yaml`中参数**类型或数量一致** +- Paddle API和PyTorch API仅参数名称不一致 +- Python端在调用`_C_ops`前**有前处理逻辑**需要下沉 + +**典型示例：** `paddle.logsumexp` + +请严格按以下步骤依次执行，不要自行修改或跳过步骤： + +### Step 1：配置 `python_api_info.yaml` + +```yaml +- op : logsumexp + name : [paddle.logsumexp, paddle.Tensor.logsumexp] + args_alias: + use_default_mapping : True # x->input, axis->dim + pre_process: + func : LogsumexpPreProcess(x, axis, reduce_all) # 前处理函数 +``` + +**关键点：** +- `name`：指定对应的Python API名称 +- `args_alias.use_default_mapping`：启用默认参数映射 +- `pre_process.func`：指定前处理函数名称及其参数列表 + + +### Step 2：实现前处理函数 + +在 `paddle/fluid/pybind/arg_pre_process.h` 声明： + +```cpp +namespace paddle { +namespace pybind { + +// 动态图版本 +void LogsumexpPreProcess(Tensor *x, std::vector *axis, bool *reduce_all); + +// 静态图版本 +void LogsumexpPreProcess(pir::Value *x, std::vector *axis, bool *reduce_all); + +} // namespace pybind +} // namespace paddle +``` + +在 `paddle/fluid/pybind/arg_pre_process.cc` 实现： + +```cpp +#include "paddle/fluid/pybind/arg_pre_process.h" +#include "paddle/fluid/eager/utils.h" +#include "paddle/fluid/pir/utils/general_functions.h" + +namespace paddle { +namespace pybind { + +// 动态图实现 +void LogsumexpPreProcess(Tensor *x, std::vector *axis, bool *reduce_all) { + // Python原逻辑： + // if axis == [] or len(axis) == len(x.shape): + // reduce_all = True + // else: + // reduce_all = False + + if (axis->empty() || axis->size() == x->dims().size()) { + *reduce_all = true; + } else { + *reduce_all = false; + } +} + +// 静态图实现 +void LogsumexpPreProcess(pir::Value *x, std::vector *axis, bool *reduce_all) { + std::vector x_shape = pir::GetShapeFromValue(*x); + if (axis->empty() || axis->size() == x_shape.size()) { + *reduce_all = true; + } else { + *reduce_all = false; + } +} + +} // namespace pybind +} // namespace paddle +``` + +**注意事项：** +- 必须同时实现动态图和静态图版本 +- 函数通过指针修改参数值 +- 直接翻译Python前处理逻辑到C++ + +### Step 3~6：参考场景一的Step 2~5 + + +## 2.3 场景三：复杂参数映射（最复杂） + +**适用条件：** +- Paddle Python API与`ops.yaml`中参数**类型或数量不一致** +- 需要复杂的自定义参数解析逻辑，来匹配Paddle Python API与`ops.yaml`的参数差异 + +**典型示例：** `paddle.argmax`/`paddle.argmin` + +请严格按以下步骤依次执行，不要自行修改或跳过步骤： + +### Step 1：配置 `python_api_info.yaml` + +```yaml +- op : argmax + name : [paddle.argmax, paddle.Tensor.argmax] + args_mapper : + func : ArgMaxMinMapper # 自定义参数映射函数 +``` + +**关键点：** +- `name`：指定对应的Python API名称 +- `args_mapper.func`：指定自定义Mapper函数名称 +- 当使用`args_mapper`时，**不会生成默认参数解析代码** +- Mapper需要手动解析所有参数，包括参数别名支持 + +### Step 2：实现自定义Mapper + +在 `paddle/fluid/pybind/args_mapper.h` 声明： + +```cpp +namespace paddle { +namespace pybind { + +// 动态图版本 +void ArgMaxMinMapper(PyObject* args, + PyObject* kwargs, + Tensor* x, + paddle::experimental::Scalar* axis, + bool* keepdims, + bool* flatten, + phi::DataType* dtype); + +// 静态图版本 +void ArgMaxMinMapper(PyObject* args, + PyObject* kwargs, + pir::Value* x, + pir::Value* axis, + bool* keepdims, + bool* flatten, + phi::DataType* dtype); + +} // namespace pybind +} // namespace paddle +``` + +在 `paddle/fluid/pybind/args_mapper.cc` 实现： + +```cpp +#include "paddle/fluid/pybind/args_mapper.h" +#include "paddle/fluid/eager/utils.h" +#include "paddle/fluid/pir/dialect/operator/ir/pd_api.h" +#include "paddle/fluid/pybind/eager_utils.h" +#include "paddle/fluid/pybind/op_function_common.h" + +namespace paddle { +namespace pybind { + +// 动态图实现 +void ArgMaxMinMapper(PyObject* args, + PyObject* kwargs, + Tensor* x, + paddle::experimental::Scalar* axis, + bool* keepdims, + bool* flatten, + phi::DataType* dtype) { + // Python参数：(x, axis, keepdim, dtype, name) + // C++ _C_ops参数：(x, axis, keepdim, flatten, dtype) + + int nargs = args ? static_cast(PyTuple_Size(args)) : 0; + int remaining_kwargs = kwargs ? static_cast(PyDict_Size(kwargs)) : 0; + const int max_args = 4; // 不包括name参数 + CheckParamsCount(nargs, remaining_kwargs, max_args); + + // 1. 解析x参数（支持多个别名） + *x = GetTensorFromArgsOrKWArgs("argmax", + "x", + args, + 0, + kwargs, + {"x", "input"}, // 别名列表 + nargs, + &remaining_kwargs, + false); + + // 2. 解析axis参数并处理特殊逻辑 + PyObject* axis_obj = GetItemFromArgsOrKWArgs( + args, 1, kwargs, {"axis", "dim"}, nargs, &remaining_kwargs); + + // Python逻辑： + // flatten = False + // if axis is None: + // flatten = True + // axis = 0 + *flatten = false; + if (axis_obj == Py_None || axis_obj == nullptr) { + *flatten = true; + *axis = 0; + } else { + *axis = CastPyArg2Scalar(axis_obj, "argmax", 1); + } + + // 3. 解析keepdims参数（支持多个别名） + PyObject* keepdims_obj = GetItemFromArgsOrKWArgs( + args, 2, kwargs, {"keepdim", "keepdims"}, nargs, &remaining_kwargs); + *keepdims = CastPyArg2Boolean(keepdims_obj, "argmax", 2, false); + + // 4. 解析dtype参数并验证 + PyObject* dtype_obj = GetItemFromArgsOrKWArgs( + args, 3, kwargs, {"dtype"}, nargs, &remaining_kwargs); + + PADDLE_ENFORCE_NE( + dtype_obj, + Py_None, + phi::errors::InvalidArgument("the value of 'dtype' in argmax and argmin " + "could not be None, but received None")); + *dtype = CastPyArg2DataType(dtype_obj, "argmax", 3, phi::DataType::INT64); + + // 5. 检查剩余参数有效性 + CheckRemainingParamsValidity(args, kwargs, remaining_kwargs, nargs); +} + +// 静态图实现 +void ArgMaxMinMapper(PyObject* args, + PyObject* kwargs, + pir::Value* x, + pir::Value* axis, + bool* keepdims, + bool* flatten, + phi::DataType* dtype) { + int nargs = args ? static_cast(PyTuple_Size(args)) : 0; + int remaining_kwargs = kwargs ? static_cast(PyDict_Size(kwargs)) : 0; + const int max_args = 4; + CheckParamsCount(nargs, remaining_kwargs, max_args); + + // 1. 解析Value类型的x + PyObject* x_obj = GetItemFromArgsOrKWArgs( + args, 0, kwargs, {"x", "input"}, nargs, &remaining_kwargs); + *x = CastPyArg2Value(x_obj, "argmax", 0, false); + + // 2. 解析axis并转换为Value类型 + PyObject* axis_obj = GetItemFromArgsOrKWArgs( + args, 1, kwargs, {"axis", "dim"}, nargs, &remaining_kwargs); + + *flatten = false; + if (axis_obj == Py_None || axis_obj == nullptr) { + *flatten = true; + // 静态图中axis需要是Value类型 + *axis = paddle::dialect::full( + std::vector{1}, 0, phi::DataType::INT64, phi::CPUPlace()); + } else if (PyObject_CheckIRValue(axis_obj)) { + *axis = CastPyArg2Value(axis_obj, "argmax", 1); + } else { + int64_t axis_tmp = CastPyArg2Long(axis_obj, "argmax", 1); + *axis = paddle::dialect::full(std::vector{1}, + axis_tmp, + phi::DataType::INT64, + phi::CPUPlace()); + } + + // 3-5. 解析其他参数（同动态图） + PyObject* keepdims_obj = GetItemFromArgsOrKWArgs( + args, 2, kwargs, {"keepdim", "keepdims"}, nargs, &remaining_kwargs); + *keepdims = CastPyArg2Boolean(keepdims_obj, "argmax", 2, false); + + PyObject* dtype_obj = GetItemFromArgsOrKWArgs( + args, 3, kwargs, {"dtype"}, nargs, &remaining_kwargs); + + PADDLE_ENFORCE_NE( + dtype_obj, + Py_None, + phi::errors::InvalidArgument("the value of 'dtype' in argmax and argmin " + "could not be None, but received None")); + *dtype = CastPyArg2DataType(dtype_obj, "argmax", 3, phi::DataType::INT64); + + CheckRemainingParamsValidity(args, kwargs, remaining_kwargs, nargs); +} + +} // namespace pybind +} // namespace paddle +``` + +**关键技术点：** + +1. **参数解析工具函数：** + - `GetTensorFromArgsOrKWArgs`：解析Tensor参数，支持多个别名 + - `GetItemFromArgsOrKWArgs`：获取通用Python对象 + - `CastPyArg2Scalar`：转换为Scalar类型 + - `CastPyArg2Boolean`：转换为bool类型 + - `CastPyArg2DataType`：转换为DataType枚举 + - `CheckParamsCount`：检查参数数量 + - `CheckRemainingParamsValidity`：检查是否有未处理参数 + +2. **静态图特殊处理：** + - 使用`pir::Value`代替`Tensor` + - 常量值需转换为`Value`类型：使用`paddle::dialect::full` + +3. **参数别名支持：** + - 通过传入别名列表`{"x", "input"}`同时支持Paddle和Torch风格 + +### Step 3~6：参考场景一的Step 2~5 + +## 2.4 不同场景对比 + +| 项目 | 场景一：仅参数名不同 | 场景二：有前处理逻辑 | 场景三：复杂参数映射 | +|------|---------------------|---------------------|---------------------| +| **YAML配置** | `args_alias` + `use_default_mapping` | `args_alias` + `pre_process` | `args_mapper` | +| **C++实现** | 无需额外C++代码 | `arg_pre_process.h/cc` | `args_mapper.h/cc` | +| **实现难度** | ⭐ 简单 | ⭐⭐ 中等 | ⭐⭐⭐ 复杂 | +| **参数解析** | 自动生成 | 自动生成 + 前处理 | 完全手动 | +| **适用情况** | 仅参数名不一致 | 仅参数名不一致+前处理逻辑 | 参数类型/数量不一致 | +| **示例API** | log2 | logsumexp | argmax, argmin | + + +# 三、通用注意事项 + +## 3.1 文档相关 + +### 支持out参数的文档修改 +若API需支持`out`参数，必须： +- **英文文档**：直接修改`add_doc_and_signature`中的字符串，增加out参数 + +### 静态检查误报 +示例代码若涉及多种数据类型，可能触发类型检查误报，添加注释忽略： +```python +.. code-block:: python + >>> # type: ignore + >>> import paddle + >>> x = paddle.to_tensor([1.0, 2.0]) +``` + +## 3.2 参数顺序特殊情况 +若Python API参数顺序与`_C_ops` API不同，属于特殊情况，Cpp下沉方案无法实现，需要使用Python装饰器方案。 + +## 3.3 注意事项 +- **静态图代码生成**：cmake阶段 +- **动态图代码生成**：make阶段 +- **重要**：修改YAML后需重新执行`cmake`和`make` + + +# 四、单元测试规范 + +## 4.1 传参方式兼容性测试 +```python +# 位置参数 +out1 = paddle.api(x, arg1, arg2) + +# Paddle关键字参数 +out2 = paddle.api(x=x, axis=arg1, keepdim=arg2) + +# Torch关键字参数 +out3 = paddle.api(input=x, dim=arg1, keepdim=arg2) + +# 混合参数 +out4 = paddle.api(x, dim=arg1, keepdim=arg2) +``` + +## 4.2 Tensor方法测试 +```python +# 方法调用 - 位置参数 +out5 = x.api(arg1, arg2) + +# 方法调用 - 关键字参数 +out6 = x.api(dim=arg1, keepdim=arg2) +``` + +## 4.3 异常参数测试 +```python +# 参数缺失 +with self.assertRaises(ValueError): + paddle.api(x) # 缺少必需参数 + +# 参数类型错误 +with self.assertRaises(TypeError): + paddle.api(x, "invalid_type") + +# 关键字名错误 +with self.assertRaises(TypeError): + paddle.api(x, wrong_key=value) +``` + +## 4.4 文档绑定测试 +```python +def test_docstring(self): + self.assertIsNotNone(paddle.api.__doc__) + self.assertIn("Args:", paddle.api.__doc__) +``` + +## 4.5 动态图和静态图测试 +必须分别测试动态图（eager mode）和静态图（static graph）两种模式。 + +# 五、异常处理 + +## 5.1 处理流程 +当遇到错误时，建议按照以下步骤处理，确保代码能运行通过： +1. **定位错误**：仔细阅读错误信息，确定错误类型和位置 +2. **分析原因**：根据错误信息分析具体问题，例如参数错误、类型不匹配 +3. **修改代码**：根据错误信息与分析结果，调整代码 +4. **验证修复**：重新运行测试确认问题解决 + +## 5.2 常见错误及解决方案 + +### 5.2.1 静态图兼容性问题 +**错误现象**： +```python +TypeError: (InvalidType) all(): argument (position 1) must be Value, but got Variable +``` + +**问题原因**： +API下沉后使用了新的Value类型系统，但测试代码仍在使用旧的Variable类型 + +**解决方法**： +1. 删除过时的测试文件： + ```bash + rm -rf test/deprecated/test_xxx.py + ``` +2. 删除`CMakeLists.txt`中涉及的单测配置： + ```cmake + # 删除相关单测配置 + # set_tests_properties(test_lbfgs_deprecated PROPERTIES TIMEOUT 100) + ``` +3. 检查并更新所有引用这些测试的代码 + +### 5.2.2 参数解析错误 +**错误现象**： +```python +TypeError: argmax() got an unexpected keyword argument 'invalid_param' +``` + +**解决方法**： +1. 检查参数名称拼写 +2. 确认是否支持该参数 + +### 5.2.3 类型转换错误 +**错误现象**： +```python +TypeError: expected Tensor as argument, got numpy.ndarray +``` + +**解决方法**： +1. 确保输入数据是Tensor类型： + ```python + tensor_input = paddle.to_tensor(numpy_input) + ``` +2. 检查数据类型是否匹配 + + +# 六、技术背景知识 + +## 6.1 工具函数速查 + +```cpp +// 获取Tensor参数（支持别名） +Tensor GetTensorFromArgsOrKWArgs( + const std::string& op_name, + const std::string& param_name, + PyObject* args, int arg_idx, + PyObject* kwargs, const std::vector& aliases, + int nargs, int* remaining_kwargs, bool required); + +// 获取通用Python对象 +PyObject* GetItemFromArgsOrKWArgs( + PyObject* args, int arg_idx, + PyObject* kwargs, const std::vector& aliases, + int nargs, int* remaining_kwargs); + +// 类型转换 +paddle::experimental::Scalar CastPyArg2Scalar(PyObject* obj, const std::string& op_name, int arg_idx); +bool CastPyArg2Boolean(PyObject* obj, const std::string& op_name, int arg_idx, bool default_value); +phi::DataType CastPyArg2DataType(PyObject* obj, const std::string& op_name, int arg_idx, phi::DataType default_value); +std::vector CastPyArg2Ints(PyObject* obj, const std::string& op_name, int arg_idx); + +// 检查函数 +void CheckParamsCount(int nargs, int remaining_kwargs, int max_args); +void CheckRemainingParamsValidity(PyObject* args, PyObject* kwargs, int remaining_kwargs, int nargs); +``` diff --git a/docs/dev_guides/coding_agent_rules/api_compatibility/3-paconvert-test.mdr b/docs/dev_guides/coding_agent_rules/api_compatibility/3-paconvert-test.mdr new file mode 100644 index 00000000000..adb18321a5f --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/api_compatibility/3-paconvert-test.mdr @@ -0,0 +1,211 @@ +--- +description: Pytorch对齐验证智能体 +globs: +alwaysApply: false +--- + +# 一、角色定义 + +你擅长《Paddle API对齐PyTorch项目》中的**Pytorch对齐验证**，负责借助PaConvert工具验证Paddle API与PyTorch API是否完全对齐一致。通过运行PyTorch单元测试发现并修复不一致的地方，确保实现完全一致的效果。 + +> **PaConvert简介**：一个代码转换工具，可以搭建起Pytorch-Paddle API之间的桥梁。 + +# 二、标准工作流程 + +请严格按以下Step依次执行，不要自行修改或跳过Step： + +## Step 1: 标记已对齐的API +**目的：** 将已对齐的 PyTorch API 全部添加到白名单。注意torch.atan与torch.Tensor.atan是不同API。 + +**操作Step：** +1. 定位文件：`PaConvert/paconvert/global_var.py` +2. 找到 `NO_NEED_CONVERT_LIST` 列表（约在第80行附近） +3. 在列表中添加已对齐的 PyTorch API 完整路径，例如： + ```python + # Edit by AI Agent (放到该行下面) + "torch.complex", + "torch.atan", + "torch.asinh", + ``` + +## Step 2: 补充测试用例 +**目的：** 补充测试用例，确保覆盖该Pytorch API的所有用法 + +**判断是否需要补充：** +- 检查现有测试是否符合用例设计原则，如不符合，则需要修改 +- 注意新增的测试case需要放到文件最后面 + +**文件位置：** +- Pytorch单测路径： `PaConvert/tests/` +- Pytorch单测文件名： `test_.py` +- API名称使用下划线命名法，例如`torch.argmax`对应的文件为`test_argmax.py` + +**测试用例设计原则：** + +1. **参数覆盖要全面** + 测试所有可能的参数组合方式： + - 全部位置参数：`func(a, b, c)` + - 全部关键字参数：`func(x=a, y=b, z=c)` + - 混合参数：`func(a, y=b, z=c)` + - 乱序关键字：`func(z=c, x=a, y=b)` + - 指定所有默认参数：`func(a, dim=0，offset=1)` + - 缺省所有默认参数：`func(a)` + - 变量传参：`args=(a,b); func(*args)` + - 参数别名：`func(input=a, other=b)` + +2. **输入数据要有效** + - 不能使用全零张量等无效输入 + - 需要包含不同维度的输入（1D、2D、3D等） + - 覆盖不同数据类型（float32、float64、int等） + +3. **测试数量要充分** + - 涉及 N 个新参数时，包含各种排列组合的用法 + - 测试用例越多越好，充分验证功能正确性 + +**测试用例模板：** +```python +import textwrap +import pytest +from apibase import APIBase + +obj = APIBase("torch.target_api") + +def test_case_1(): + """基础用法""" + pytorch_code = textwrap.dedent(""" + import torch + result = torch.target_api(torch.tensor([1, 2, 3])) + """) + obj.run(pytorch_code, ["result"]) + +def test_case_2(): + """位置参数测试""" + pytorch_code = textwrap.dedent(""" + import torch + x = torch.tensor([1.0, 2.0]) + result = torch.target_api(x, 2, 1) + """) + obj.run(pytorch_code, ["result"]) + +def test_case_3(): + """关键字参数测试""" + pytorch_code = textwrap.dedent(""" + import torch + x = torch.tensor([1.0, 2.0]) + result = torch.target_api(input=x, dim=1, dtype=torch.float32) + """) + obj.run(pytorch_code, ["result"]) + +def test_case_4(): + """关键字参数乱序测试""" + pytorch_code = textwrap.dedent(""" + import torch + x = torch.tensor([1.0, 2.0]) + result = torch.target_api(dtype=torch.float32, dim=1, input=x) + """) + obj.run(pytorch_code, ["result"]) + +def test_case_5(): + """梯度计算测试""" + pytorch_code = textwrap.dedent(""" + import torch + x = torch.tensor([1., 2.], requires_grad=True) + y = torch.target_api(x) + y.sum().backward() + x_grad = x.grad + """) + # 跳过梯度属性检查，因为Paddle的grad.stop_gradient行为与PyTorch不一致，框架机制问题可忽略 + obj.run(pytorch_code, ["y", "x_grad"], check_stop_gradient=False) + + +def test_case_6(): + """边界条件测试""" + pytorch_code = textwrap.dedent(""" + import torch + result = torch.target_api(torch.empty(0)) + """) + obj.run(pytorch_code, ["result"]) + +def test_case_7(): + """表达式参数测试""" + pytorch_code = textwrap.dedent(""" + import torch + result = torch.target_api(torch.tensor([1, 2, 3]), 1 + 1) + """) + obj.run(pytorch_code, ["result"]) +``` + +**特殊场景处理：** + +1. **GPU 环境测试**： +```python +import paddle +import pytest + +should_skip = not paddle.device.is_compiled_with_cuda() +skip_reason = "Test requires CUDA" + +@pytest.mark.skipif(condition=should_skip, reason=skip_reason) +def test_case_with_cuda(): + ... +``` + +2. **不支持功能标记**： +```python +@pytest.mark.skip(reason="Not supported") +def test_unsupported_case(): + ... +``` + +3. **自定义比较逻辑**（通常不需要）： +```python +class CustomAPIBase(APIBase): + def compare(self, name, pytorch_result, paddle_result, ...): + # 自定义比较逻辑 + pytorch_str = str(pytorch_result).removeprefix("torch.") + assert pytorch_str == paddle_result +``` + +## Step 3: 运行单元测试 +**目的：** 在补充完测试用例后，确保能通过所有用例，运行通过则表明完全对齐一致 + +**操作Step：** +1. 本地执行以下命令： + ```bash + cd /workspace/PaConvert/ + python -m pytest tests/test_.py + ``` +2. 确保所有测试用例通过 + + +# 三、异常处理 + +在 PyTorch 对齐验证过程中，需要对不同异常情况进行分类处理。以下是异常处理策略： + +## 1. PyTorch 代码执行失败 +- **错误标识**：`Failed to execute pytorch code` +- **根本原因**：PyTorch 单元测试代码存在问题，无法正常执行 +- **处理策略**：修改 PyTorch 单元测试代码，确保能正确执行 Pytorch 代码 +- **验证标准**：测试代码应该能够在标准的 PyTorch 环境中正常运行 + +## 2. Paddle 代码执行失败 +- **错误标识**：`Failed to execute paddle code` +- **根本原因**：Pytorch单测正确，但修改后的 Paddle API 实现存在问题，导致代码无法执行 +- **处理策略**：需要返回到前序Step修改，因此结束本Step，将报错信息返回给主控智能体分析 +- **关联任务**：Paddle API需要进一步修改以兼容 PyTorch 接口 + +## 3. 计算结果不一致 +- **错误标识**：`Unable to align results` +- **根本原因**：Pytorch单测正确，但Paddle API 与 PyTorch API 计算结果存在差异 +- **处理策略**：需要返回到前序Step修改，因此结束本Step，将报错信息返回给主控智能体分析 +- **验证要求**：Paddle API需要进一步修改以兼容 PyTorch 接口，确保数值精度、数据类型、形状等完全一致 + + +**常见问题处理：** +- 如果 Paddle 不支持类型提升或标量输入（已知问题），可以禁用对应测试用例，其他情况不允许禁用单测： + ```python + # 将 def test_case_x(): 改为 def _test_case_x(): + # 并添加注释说明原因 + def _test_case_2(): # Paddle does not support scalar input + ... + ``` diff --git a/docs/dev_guides/coding_agent_rules/api_compatibility/4-modify-docs.mdr b/docs/dev_guides/coding_agent_rules/api_compatibility/4-modify-docs.mdr new file mode 100644 index 00000000000..68bae6a223f --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/api_compatibility/4-modify-docs.mdr @@ -0,0 +1,300 @@ +--- +description: API文档修改智能体 +globs: +alwaysApply: false +--- + +# 一、角色定义 + +你擅长《Paddle API对齐PyTorch项目》中的**API文档修改**，负责在API代码修改完成后，同步更新API中文文档，确保文档准确反映API的最新行为。 + +## 核心职责 +1. 根据Paddle仓库的git diff分析API代码变更 +2. 更新对应的API中文文档（.rst文件） +3. 删除已对齐API的差异文档（.md文件） +4. 确保文档格式符合Paddle规范 + + +# 二、工作目录说明 + +## 2.1 文档路径规范 + +### 2.1.1 API概览文档 +- **位置**：`docs/api/paddle/Overview_cn.rst` +- **作用**：API索引目录，新增API时需要更新 + +### 2.1.2 API中文文档 +- **文件命名规则**：`{api_name}_cn.rst` + +### 2.1.3 API差异文档（需删除） +- **文件命名规则**：`torch.{api_name}.md` + + +# 三、标准工作流程 + +## 步骤 1: 获取代码变更信息 🔍 + +**目标**：分析Paddle仓库的API代码变更，明确需要同步到文档的修改点 + +**执行步骤**： +1. 切换到Paddle目录：`cd /workspace/Paddle/` +2. 获取git diff：`git diff | head -1000` +3. 分析代码变更信息中的API签名变更内容： + - 新增API签名 + - 修改API签名：新增参数、删除参数、支持参数别名 + +## 步骤 2: 更新API中文文档 📝 + +**目标**：根据代码变更同步更新`{api_name}_cn.rst`文档 + +### 1. 常见修改模式 + +#### 模式1：添加参数别名说明 + +**适用场景**：API参数新增别名（常见于C++下沉方案） + +**修改位置**：参数说明部分 + +**修改示例**： +```rst +参数 +::::::::: + - **x** (Tensor) - 输入的 Tensor。别名 ``input``。 + - **axis** (int，可选) - 指定轴。别名 ``dim``。 +``` + +**常见别名对应**： +- `x` → `input` +- `y` → `other` +- `axis` → `dim` +- `keepdim` → `keepdims` + +#### 模式2：新增关键字参数 + +**适用场景**：新增 `out` 参数支持 + +**修改位置**：函数签名 + 新增"关键字参数"小节 + +**修改示例**： +```rst +.. py:function:: paddle.cos(x, name=None, *, out=None) + +参数 +::::::::: + - **x** (Tensor) - 输入的 Tensor。别名 ``input``。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`。 + +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 +``` + +#### 模式3：新增别名API + +**适用场景**：为已有API添加别名（如 `cat` → `concat`） + +**文件操作**：创建新的.rst文件 + +**文档内容**： +```rst +.. _cn_api_paddle_cat: + +cat +------------------------------- + +.. py:function:: paddle.cat(x, axis=0, name=None, *, out=None) + +``concat`` 的别名，请参考 :ref:`cn_api_paddle_concat`。 +``` + +**同时更新**：`Overview_cn.rst` 添加索引项 + +#### 模式4：新增完整API中文文档 + +**适用场景**：全新API（如 `broadcast_shapes`） + +**文件操作**：创建新的.rst文件 + +**文档结构**： +```rst +.. _cn_api_paddle_api_name: + +api_name +------------------------------- + +.. py:function:: paddle.api_name(...) + +[API功能描述] + +参数 +:::::::::::: + - **param1** (...) - [参数说明] + +关键字参数 +::::::::: + - **out** (...) - [可选] + +返回 +:::::::::::: +[返回值说明] + +代码示例 +:::::::::::: + +COPY-FROM: paddle.api_name +``` + +### 2. 文档格式规范 + +**必须遵守的规范**： +1. ✅ 使用rst格式，严格遵循缩进规则 +2. ✅ 参数说明使用 `- **参数名** (类型) - 说明。别名 ``alias``。` 格式 +3. ✅ 关键字参数单独一个小节，使用 `关键字参数` 标题 +4. ✅ 函数签名中 `*` 后的参数为关键字参数 +5. ✅ 交叉引用使用 `:ref:` 语法 +6. ✅ 代码示例使用 `COPY-FROM:` 自动生成 + +**代码注释规范**： +- ✅ 修改文档无需添加 `# Edit by AI Agent` 注释 + + +## 步骤 3: 删除API差异文档 🗑️ + +**目标**：删除已完全对齐API的差异文档 + +**执行步骤**： +1. 定位API差异文档路径（通常在 `api_difference/` 子目录） +2. 确认API已完全对齐，获取Pytorch单测验证步骤的结论即可 +3. 删除对应的 `torch.{api_name}.md` 文件 + + +# 四、修改示例参考 + +## 4.1 示例1：C++下沉 - 添加参数别名 + +**API**：`paddle.cos` + +**代码变更**：参数 `x` 新增别名 `input`，新增关键字参数 `out` + +**文档修改**： +```diff +-.. py:function:: paddle.cos(x, name=None) ++.. py:function:: paddle.cos(x, name=None, *, out=None) + + 参数 + :::::::::::: +- - **x** (Tensor) - 输入的 Tensor。 ++ - **x** (Tensor) - 输入的 Tensor。别名 ``input``。 + - **name** (str，可选) - 具体用法请参见... + ++关键字参数 ++::::::::: ++ - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 +``` + +## 4.2 示例2：新增别名API + +**API**：`paddle.cat` → `paddle.concat` 的别名 + +**文档修改**：创建 `docs/docs/api/paddle/cat_cn.rst` +```rst +.. _cn_api_paddle_cat: + +cat +------------------------------- + +.. py:function:: paddle.cat(x, axis=0, name=None, *, out=None) + +``concat`` 的别名，请参考 :ref:`cn_api_paddle_concat`。 +``` + +**同时更新** `Overview_cn.rst`： +```diff ++" :ref:`paddle.cat ` ", "对输入沿 axis 轴进行联结" + " :ref:`paddle.concat ` ", "对输入沿 axis 轴进行联结" +``` + +## 4.3 示例3：新增完整API + +**API**：`paddle.broadcast_shapes` + +**文档修改**：创建 `docs/docs/api/paddle/broadcast_shapes_cn.rst` +```rst +.. _cn_api_paddle_broadcast_shapes: + +broadcast_shapes +------------------------------- + +.. py:function:: paddle.broadcast_shapes(*shapes: Sequence[int]) + +计算多个 Tensor shape 经过广播（broadcasting）之后的结果 shape。 + +参数 +:::::::::::: + - **shapes** (Sequence[int]) - 一个或多个 Tensor 的 shape。 + +返回 +:::::::::::: +list[int]，广播后的结果 shape。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.broadcast_shapes +``` + + + + +# 五、常见问题处理 + +## 5.1 如何判断是否需要删除差异文档？ + +**判断标准**： +- ✅ API行为逻辑已完全对齐 +- ✅ PyTorch单测验证已通过 +- ✅ 差异文档中描述的所有差异已消除 + +## 5.2 新增API是否需要创建差异文档？ + +**答案**：不需要。新增的API与PyTorch完全对齐，不存在差异，无需创建差异文档。 + +## 5.3 修改文档时如何处理特殊格式？ + +**处理方式**： +- 代码块使用 `::` +- 列表项使用 `-` 开头 +- 参数类型用 `()` 包裹 +- 别名用反引号包裹：\`\`input\`\` + +## 5.4 关键字参数 `out` 的标准说明？ + +**标准模板**： +```rst +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 +``` + +# 六、重要约束 ⚠️ + +## 6.1 必须遵守 +1. **先看代码后写文档**：必须先获取Paddle的git diff，基于实际代码变更修改文档 +2. **保持文档同步**：文档修改必须与代码修改完全一致 +3. **格式严格规范**：严格遵循rst格式和Paddle文档规范 +4. **完整性检查**：所有新增参数、别名都必须在文档中说明 + +## 6.2 禁止行为 +1. ❌ 不要凭空编造API功能或参数 +2. ❌ 不要遗漏新增的参数别名 +3. ❌ 不要破坏文档的交叉引用结构 +4. ❌ 不要在API未完全对齐时删除差异文档 + +# 七、总结 + +作为文档修改智能体，你需要： +1. ✅ 获取Paddle仓库的git diff，分析代码变更 +2. ✅ 根据变更类型，选择对应的文档修改模式 +3. ✅ 更新API中文文档，确保格式规范、内容准确 +4. ✅ 删除已对齐API的差异文档 +5. ✅ 验证文档修改的正确性和完整性 diff --git a/docs/dev_guides/coding_agent_rules/api_compatibility/README.md b/docs/dev_guides/coding_agent_rules/api_compatibility/README.md new file mode 100644 index 00000000000..a1531880b35 --- /dev/null +++ b/docs/dev_guides/coding_agent_rules/api_compatibility/README.md @@ -0,0 +1,75 @@ +# 《Paddle API 兼容性》 智能体规则体系 + +## 一、目录概述 + +本目录为《Paddle API 对齐 PyTorch 项目》的 AI 编程规则文件。这些规则文件定义了 AI 智能体在执行 API 对齐任务时的行为准则、工作流程和技术规范。 + +## 二、设计目标 + +本规则体系旨在实现以下目标： + +1. **自动化 API 对齐**：通过 AI 智能体自动完成 PyTorch API 到 Paddle API 的对齐工作 +2. **标准化工作流程**：建立统一、可复用的 API 对齐流程，确保每次对齐的质量一致性 +3. **知识沉淀与复用**：将人工经验转化为可执行的规则，降低人工干预成本 +4. **可追溯的决策过程**：每个 API 的改动方案都有明确的决策依据，便于审查和优化 + +## 三、规则文件说明 + +本目录包含以下规则文件： + +| 文件名称 | 角色 | 职责 | 适用阶段 | +|---------|------|------|---------| +| `0-api-compatibility.mdr` | 主控智能体 | 统筹全流程，调度子智能体 | 全流程 | +| `1-scheme-decision.mdr` | 方案决策智能体 | 分析 API 差异，决策改动方案 | Step1 | +| `2-2-sink-to-cpp.mdr` | Cpp 下沉智能体 | 实施 C++下沉方案 | Step2 | +| `3-paconvert-test.mdr` | Pytorch 对齐验证智能体 | 验证 API 对齐一致性 | Step3 | +| `4-modify-docs.mdr` | API 文档修改智能体 | 同步更新 API 中文文档 | Step4 | + +## 四、工作流程 + +规则体系遵循以下标准工作流程，采用**主控智能体调度 + 子智能体执行**的协作模式： + +``` +主控智能体：接收 PyTorch API 列表 + ↓ +主控智能体 → 调用方案决策智能体 (1-scheme-decision.mdr) + ↓ +[决策结果分发，若需 C++下沉] 主控智能体 → 调用 Cpp 下沉智能体 (2-2-sink-to-cpp.mdr) + ↓ +主控智能体 → 调用 Pytorch 对齐验证智能体 (3-paconvert-test.mdr) + ↓ +[验证通过] 主控智能体 → 调用 API 文档修改智能体 (4-modify-docs.mdr) + ↓ +主控智能体：输出对齐结果统计 +``` + +**协作说明**： +- **主控智能体**：负责任务分解、流程调度、结果汇总和异常处理，确保全流程有序推进 +- **子智能体**：专注各自领域的专业工作（方案决策、代码修改、对齐验证、文档修改），执行具体任务后返回结果 +- **交互方式**：主控智能体通过 subtask 工具调用子智能体，传递必要上下文，接收执行结果并做出下一步决策 + +## 五、设计原则 + +本规则体系采用**主控智能体 + 子智能体**的协作模式，主控智能体负责任务分解、流程控制和异常处理，子智能体专注具体领域的专业工作。通过决策驱动选择最优改动方案，强调对齐验证的金标准，并要求文档与代码同步更新，确保 API 对齐的高质量和高效率。 + +## 六、使用方式 + +本规则文件**不能单独使用**，需要搭配 AI 智能体使用，作为 Agent 的指令。AI 智能体读取规则文件中的角色定义、工作流程、技术规范，根据步骤执行具体任务，并按规则处理异常情况。 + +同时，规则文件也可作为**人工学习的参考资料**，帮助开发者了解 API 对齐的标准流程，包含技术背景知识、代码示例和最佳实践。 + +## 七、环境配置要求 + +使用本规则体系需配置好代码目录（Paddle、PaConvert、Docs）、知识语料（API 中文文档和差异文档）以及本地已编译好的 Paddle 环境。 + +## 八、扩展性设计 + +本规则体系支持扩展，可新增改动方案的规则文件（如 Python 装饰器、修改 API、新增 API 等）、新增其他专业领域的子智能体（如性能优化、兼容性测试、代码审查等）、以及新增其他验证方法（如静态代码分析、性能对比、边界条件验证等）。 + +## 九、维护规范 + +规则文件遵循命名规范（主控智能体：`0-{功能}.mdr`，子智能体：`{序号}-{功能}.mdr`），内容需包含角色定义、输入输出规范、技术背景知识、标准工作流程和异常处理等章节。发现规则不完善或有误时，需及时更新，保持一致性和兼容性，重大修改需经评审和测试。 + +--- + +> 本文档由 AI Agent 自动生成，日期：2025-12-31，提交：zhwesky2010 diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_and.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_and.md deleted file mode 100644 index 077dd1a0cdd..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_and.md +++ /dev/null @@ -1,18 +0,0 @@ -## [ 仅参数名不一致 ]torch.Tensor.bitwise_and -### [torch.Tensor.bitwise_and](https://pytorch.org/docs/stable/generated/torch.Tensor.bitwise_and.html) -```python -torch.Tensor.bitwise_and(other) -``` - -### [paddle.Tensor.bitwise_and]() -```python -paddle.Tensor.bitwise_and(y) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_and_.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_and_.md deleted file mode 100644 index eb0c3870404..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_and_.md +++ /dev/null @@ -1,18 +0,0 @@ -## [ 仅参数名不一致 ]torch.Tensor.bitwise_and_ -### [torch.Tensor.bitwise_and_](https://pytorch.org/docs/stable/generated/torch.Tensor.bitwise_and_.html) -```python -torch.Tensor.bitwise_and_(other) -``` - -### [paddle.Tensor.bitwise_and_]() -```python -paddle.Tensor.bitwise_and_(y) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_xor.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_xor.md deleted file mode 100644 index 7e558f1249a..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_xor.md +++ /dev/null @@ -1,18 +0,0 @@ -## [ 仅参数名不一致 ]torch.Tensor.bitwise_xor -### [torch.Tensor.bitwise_xor](https://pytorch.org/docs/stable/generated/torch.Tensor.bitwise_xor.html) -```python -torch.Tensor.bitwise_xor(other) -``` - -### [paddle.Tensor.bitwise_xor]() -```python -paddle.Tensor.bitwise_xor(y) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_xor_.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_xor_.md deleted file mode 100644 index bf5b546c31b..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.Tensor.bitwise_xor_.md +++ /dev/null @@ -1,18 +0,0 @@ -## [ 仅参数名不一致 ]torch.Tensor.bitwise_xor_ -### [torch.Tensor.bitwise_xor_](https://pytorch.org/docs/stable/generated/torch.Tensor.bitwise_xor_.html) -```python -torch.Tensor.bitwise_xor_(other) -``` - -### [paddle.Tensor.bitwise_xor_]() -```python -paddle.Tensor.bitwise_xor_(y) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bincount.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bincount.md deleted file mode 100644 index 3c4486ab9a5..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bincount.md +++ /dev/null @@ -1,24 +0,0 @@ -## [ 仅参数名不一致 ]torch.bincount -### [torch.bincount](https://pytorch.org/docs/stable/generated/torch.bincount.html?highlight=bincount#torch.bincount) -```python -torch.bincount(input, - weights=None, - minlength=0) -``` - -### [paddle.bincount](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/bincount_cn.html#bincount) -```python -paddle.bincount(x, - weights=None, - minlength=0, - name=None) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input| x | 表示输入的 Tensor ，仅参数名不一致。 | -| weights | weights | 表示输入 Tensor 中每个元素的权重。 | -| minlength | minlength | 表示输出 Tensor 的最小长度。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_and.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_and.md deleted file mode 100644 index 7ecaaebb894..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_and.md +++ /dev/null @@ -1,25 +0,0 @@ -## [ 仅参数名不一致 ]torch.bitwise_and -### [torch.bitwise_and](https://pytorch.org/docs/stable/generated/torch.bitwise_and.html#torch.bitwise_and) -```python -torch.bitwise_and(input, - other, - *, - out=None) -``` - -### [paddle.bitwise_and](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/bitwise_and_cn.html#bitwise-and) -```python -paddle.bitwise_and(x, - y, - out=None, - name=None) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | -| out | out | 表示输出的 Tensor。| diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_not.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_not.md deleted file mode 100644 index f71a3e75acb..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_not.md +++ /dev/null @@ -1,23 +0,0 @@ -## [ 仅参数名不一致 ]torch.bitwise_not -### [torch.bitwise_not](https://pytorch.org/docs/stable/generated/torch.bitwise_not.html?highlight=bitwise_not#torch.bitwise_not) -```python -torch.bitwise_not(input, - *, - out=None) -``` - -### [paddle.bitwise_not](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/bitwise_not_cn.html) -```python -paddle.bitwise_not(x, - out=None, - name=None) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 输入的 Tensor ，仅参数名不一致。 | -| out | out | 表示输出的 Tensor，参数名一致。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_xor.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_xor.md deleted file mode 100644 index 42c0e0a97bd..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.bitwise_xor.md +++ /dev/null @@ -1,25 +0,0 @@ -## [ 仅参数名不一致 ]torch.bitwise_xor -### [torch.bitwise_xor](https://pytorch.org/docs/stable/generated/torch.bitwise_xor.html) -```python -torch.bitwise_xor(input, - other, - *, - out=None) -``` - -### [paddle.bitwise_xor](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/bitwise_xor_cn.html) -```python -paddle.bitwise_xor(x, - y, - out=None, - name=None) -``` - -两者功能一致且参数用法一致，仅参数名不一致，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | -| out | out | 表示输出的 Tensor。| diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.tan.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.tan.md deleted file mode 100644 index fcfb03d8af1..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/args_name_diff/torch.tan.md +++ /dev/null @@ -1,19 +0,0 @@ -## [ 仅参数名不一致 ]torch.tan -### [torch.tan](https://pytorch.org/docs/stable/generated/torch.tan.html) -```python -torch.tan(input, *, out=None) -``` - -### [paddle.tan](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/tan_cn.html#tan) -```python -paddle.tan(x, name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------- | ------------ | -- | -| input | x | 输入 Tensor，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ，Paddle 无此参数，需要转写。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.angle.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.angle.md deleted file mode 100644 index 8d6dd8d2527..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.angle.md +++ /dev/null @@ -1,29 +0,0 @@ -## [ torch 参数更多 ]torch.angle -### [torch.angle](https://pytorch.org/docs/stable/generated/torch.angle.html) -```python -torch.angle(input, *, out=None) -``` - -### [paddle.angle](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/angle_cn.html#angle) -```python -paddle.angle(x, name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------- | ------------ | -- | -| input | x | 输入 Tensor，仅参数名不一致。 | -| out | - | 输出 Tensor，Paddle 无此参数，需要转写。 | - -### 转写示例 -#### out： 指定输出 -```python -# PyTorch 写法 -torch.angle(x, out=y) - -# Paddle 写法 -paddle.assign(paddle.angle(x), y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.asinh.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.asinh.md deleted file mode 100644 index 7f8a59c0bae..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.asinh.md +++ /dev/null @@ -1,32 +0,0 @@ -## [ torch 参数更多 ]torch.asinh -### [torch.asinh](https://pytorch.org/docs/stable/generated/torch.asinh.html#torch.asinh) -```python -torch.asinh(input, - *, - out=None) -``` - -### [paddle.asinh](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/asinh_cn.html) -```python -paddle.asinh(x, - name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.asinh(torch.tensor([-0.5962, 0.4985]), out=y) - -# Paddle 写法 -paddle.assign(paddle.asinh(paddle.to_tensor([-0.5962, 0.4985])), y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.atan.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.atan.md deleted file mode 100644 index 2da329d75de..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.atan.md +++ /dev/null @@ -1,33 +0,0 @@ -## [ torch 参数更多 ]torch.atan -### [torch.atan](https://pytorch.org/docs/stable/generated/torch.atan.html#torch.atan) -```python -torch.atan(input, - *, - out=None) -``` - -### [paddle.atan](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/atan_cn.html#atan) -```python -paddle.atan(x, - name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.atan(torch.tensor([ 0.2341, 0.2539]), out=y) - -# Paddle 写法 -paddle.assign(paddle.atan(paddle.to_tensor([ 0.2341, 0.2539])), y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.diag.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.diag.md deleted file mode 100644 index 6d5e08f6dc6..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.diag.md +++ /dev/null @@ -1,38 +0,0 @@ -## [ torch 参数更多 ]torch.diag - -### [torch.diag](https://pytorch.org/docs/stable/generated/torch.diag.html?highlight=diag#torch.diag) -```python -torch.diag(input, - diagonal=0, - *, - out=None) -``` - -### [paddle.diag](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/diag_cn.html) -```python -paddle.diag(x, - offset=0, - padding_value=0, - name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| diagonal | offset | 对角线偏移量。正值表示上对角线，0 表示主对角线，负值表示下对角线。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | -| - | padding_value | 表示填充指定对角线以外的区域， PyTorch 无此参数， Paddle 保持默认即可 。 | - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.diag(x, out=y) - -# Paddle 写法 -paddle.assign(paddle.diag(x), y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.fmax.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.fmax.md deleted file mode 100644 index 8edc055acad..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.fmax.md +++ /dev/null @@ -1,30 +0,0 @@ -## [ torch 参数更多 ]torch.fmax -### [torch.fmax](https://pytorch.org/docs/stable/generated/torch.fmax.html#torch.fmax) -```python -torch.fmax(input, other, *, out=None) -``` - -### [paddle.fmax](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/fmax_cn.html) -```python -paddle.fmax(x, y, name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.fmax(x, y, out=output) - -# Paddle 写法 -paddle.assign(paddle.fmax(x,y), output) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.fmin.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.fmin.md deleted file mode 100644 index 425f0a68110..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.fmin.md +++ /dev/null @@ -1,30 +0,0 @@ -## [ torch 参数更多 ]torch.fmin -### [torch.fmin](https://pytorch.org/docs/stable/generated/torch.fmin.html#torch.fmin) -```python -torch.fmin(input, other, *, out=None) -``` - -### [paddle.fmin](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/fmin_cn.html) -```python -paddle.fmin(x, y, name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| other | y | 表示输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.fmin(x, y, out=output) - -# Paddle 写法 -paddle.assign(paddle.fmin(x,y), output) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.heaviside.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.heaviside.md deleted file mode 100644 index 90c881b5303..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.heaviside.md +++ /dev/null @@ -1,30 +0,0 @@ -## [ torch 参数更多 ]torch.heaviside -### [torch.heaviside](https://pytorch.org/docs/stable/generated/torch.heaviside.html#torch.heaviside) -```python -torch.heaviside(input, values, *, out=None) -``` - -### [paddle.heaviside](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/heaviside_cn.html#heaviside) -```python -paddle.heaviside(x, y, name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| values | y | 表示输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.heaviside(x, y, out=z) - -# Paddle 写法 -z = paddle.heaviside(x, y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.nextafter.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.nextafter.md deleted file mode 100644 index 4b7bb84d1be..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.nextafter.md +++ /dev/null @@ -1,35 +0,0 @@ -## [ torch 参数更多 ]torch.nextafter -### [torch.nextafter](https://pytorch.org/docs/stable/generated/torch.nextafter.html?highlight=nextafter#torch.nextafter) -```python -torch.nextafter(input, - other, - *, - out=None) -``` - -### [paddle.nextafter](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/nextafter_cn.html) -```python -paddle.nextafter(x, - y, - name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor，仅参数名不一致。 | -| other | y | 表示输入的 Tensor，仅参数名不一致。 | -| out | - | 表示输出的 Tensor，Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.nextafter(torch.tensor([1.0, 2.0]), torch.tensor([2.0, 1.0]), out=y) - -# Paddle 写法 -paddle.assign(paddle.nextafter(paddle.to_tensor([1.0, 2.0]),paddle.to_tensor([2.0, 1.0])), y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.reciprocal.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.reciprocal.md deleted file mode 100644 index 5ad604a5ca3..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.reciprocal.md +++ /dev/null @@ -1,32 +0,0 @@ -## [ torch 参数更多 ]torch.reciprocal -### [torch.reciprocal](https://pytorch.org/docs/stable/generated/torch.reciprocal.html?highlight=torch+reciprocal#torch.reciprocal) -```python -torch.reciprocal(input, - *, - out=None) -``` - -### [paddle.reciprocal](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/reciprocal_cn.html) -```python -paddle.reciprocal(x, - name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor，Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.reciprocal([3, 5], out=y) - -# Paddle 写法 -paddle.assign(paddle.reciprocal([3, 5]), y) -``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.square.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.square.md deleted file mode 100644 index ea94074fbf8..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.square.md +++ /dev/null @@ -1,32 +0,0 @@ -## [ torch 参数更多 ]torch.square -### [torch.square](https://pytorch.org/docs/stable/generated/torch.square.html?highlight=square#torch.square) -```python -torch.square(input, - *, - out=None) -``` - -### [paddle.square](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/square_cn.html) -```python -paddle.square(x, - name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入的 Tensor ，仅参数名不一致。 | -| out | - | 表示输出的 Tensor ， Paddle 无此参数，需要转写。 | - - -### 转写示例 -#### out：指定输出 -```python -# PyTorch 写法 -torch.square([0.1, 0.2], out=y) - -# Paddle 写法 -paddle.assign(paddle.square([0.1, 0.2]), y) -```