api-compatibility

name	api-compatibility
description	开展《Paddle API 对齐 PyTorch 项目》，负责项目整体统筹规划，调用多个 skill，完成输入的 API 对齐
allowed-tools	Read Write Edit Bash Glob Grep Agent Skill WebFetch WebSearch

一、项目目标

用户提供待对齐的 Pytorch API 列表 $ARGUMENTS，通过调用多个 skill，使 Paddle API 与 PyTorch API 完全对齐，实现：

• 对于任意 PyTorch API 用法，只需将 torch.* 替换为 paddle.*
• 计算结果完全一致（数值精度、行为逻辑）

二、背景知识

类方法 API 实现原理

概念：类方法 API（如 torch.Tensor.abs）和普通 API（如 torch.abs）是不同 API，但实现一致，合并处理即可。Paddle 通过 patch 机制将方法动态添加到 Tensor 类上。

实现方式选择：

场景	方式	操作
数学运算类方法，直接转发到普通函数	方式一：配置 tensor_method_func	见下方步骤
自定义实现逻辑、property、魔术方法	方式二：修改 patch 文件	见下方步骤

方式一：配置 tensor_method_func

文件：Paddle/python/paddle/tensor/__init__.py

# 1. import 所需函数
from .math import trace

# 2. 加入 tensor_method_func 列表（按字母表顺序插入）
tensor_method_func = [
    ...
    'trace',
    ...
]

完成。各 patch 文件会自动遍历此列表完成绑定，无需额外修改。

方式二：修改 patch 文件

需修改的文件：

文件	语言	适用
python/paddle/base/dygraph/math_op_patch.py	Python	动态图
python/paddle/pir/math_op_patch.py	Python	PIR 静态图
python/paddle/base/layers/math_op_patch.py	Python	老静态图
paddle/fluid/pybind/eager_math_op_patch.cc	C++	动态图（性能更优）

选择规则：

• 动静统一 API：三处 Python patch 文件都改
• 动态图专用 API：仅改动态图 patch 文件
• 追求性能：可用 C++ patch 文件替代 Python

修改方式：

• Python：在 eager_methods 列表中添加元组 ('方法名', 方法实现)
• C++：参考 eager_math_op_patch.cc 中已有方法实现

查找注意事项：

• ✅ 在 patch 文件中搜索，或搜索对应的普通方法 def abs(
• ❌ 不要搜索 class Tensor（方法通过 setattr 动态添加，不在类定义中）

Inplace API 实现原理

概念说明：

• 注意要区分inplace API和非 inplace API，两者是不同的 API，不要混为一谈
• inplace API（如torch.abs_）：原地操作，直接修改输入 Tensor，其不应有 out 参数，如有 out 需删除
• 非 inplace API（如torch.abs）：返回新 Tensor，不修改输入 Tensor
• Inplace API 无需测试静态图，只需测试动态图

示例对比：

y = paddle.abs(x)  # 非 inplace：返回新 Tensor，x 不变
x.abs_()           # inplace：原地修改 x

自动生成机制： Paddle 支持自动生成 inplace API，无需在ops.yaml中单独配置。当定义了inplace: (x -> out)字段后，系统自动生成对应的 inplace 版本，复用原 API 的 Kernel 实现。

配置示例：

1. OP 配置（ops.yaml，第 10-22 行）：

- op : abs
  args : (Tensor x)
  output : Tensor(out)
  inplace: (x -> out)  # 关键字段：指定 x 和 out 可以 in-place
  backward : abs_grad

2. Python API 配置（python_api_info.yaml，第 6-9 行）：

• ⚠️ 仅在 C++下沉（方案 2）时需要配置

- op : abs_
  name : [paddle.abs_, paddle.Tensor.abs_]
  args_alias :
    use_default_mapping : True

API 信息获取方式

在开展 API 对齐工作过程中，需要获取 PyTorch API 和 Paddle API 的相关信息。

参考资源：

资源类型	资源位置	说明
PyTorch 官方文档	https://pytorch.org/docs/stable/	了解 API 参数功能定义
PyTorch 源码	https://github.com/pytorch/pytorch	参考 PyTorch 底层逻辑（需注意 PyTorch 与 Paddle 架构设计存在差异）
Paddle 官方文档	https://www.paddlepaddle.org.cn/documentation/docs/zh/api/	了解 Paddle API 参数功能定义
Paddle 源码	见本地仓库 ${ROOT_DIR}/Paddle	参考 Paddle 底层逻辑

获取方式：

1. 查阅官方文档：优先查阅 PyTorch 和 Paddle 的官方文档，了解 API 的参数定义、功能说明、使用示例等
2. 查阅源码实现：当文档信息不够详细时，可查阅源码实现
3. 获取 API 签名：通过 Python 的 inspect 模块或 help() 函数获取 API 签名
4. 获取文档字符串：通过 __doc__ 属性获取 API 的文档字符串
5. 实际测试验证：编写测试代码，实际运行 API 验证其行为和参数用法

示例：

import paddle
import torch

# 获取 API 签名
import inspect
print(inspect.signature(paddle.abs))
print(inspect.signature(torch.abs))

# 获取文档字符串
print(paddle.abs.__doc__)
print(torch.abs.__doc__)

# 实际测试验证
x = paddle.to_tensor([1.0, -2.0, 3.0])
print(paddle.abs(x))

三、整体工作流程

流程概览

输入 API 列表 → Step1:所有 API 选择方案 → Step2:所有 API 代码修改 → Step3:所有 API 兼容测试 → Step4:所有 API Pytorch 测试 → Step5:所有 API 更新文档 → 全部完成

具体如下：

Step 1：选择方案（调用 /select-solution skill）

Step 1.1: 获取差异信息
Step 1.2: 提取差异信息
Step 1.3: 选择方案

Step 2：代码修改

根据 Step1 的方案选择结果，按方案分组，依次调用对应 skill，同一方案的所有 API 在一个 skill 调用中批量处理。

各方案步骤：

方案 1：Python 装饰器（调用 /python-decorator skill）

Step 2.1: 差异分析与选择装饰器
Step 2.2: 应用或开发装饰器
Step 2.3: 更新函数文档

方案 2：C++下沉（调用 /cpp-sink skill）

Step 2.1: 配置 python_api_info.yaml
Step 2.2: 迁移文档到_paddle_docs.py
Step 2.3: 替换 Python 实现

方案 3：修改 API（调用 /modify-origin-api skill）

Step 2.1: 修改 API 签名
Step 2.2: 修改函数实现逻辑
Step 2.3: 更新函数文档

方案 4：新增 API（调用 /add-new-api skill）

方案 5：新增 compat 类型 API（调用 /add-new-compat-api skill）

Step 3：兼容测试（调用 /compatibility-test skill）

Step 3.1: 编写测试用例
Step 3.2: 编译并运行单测（每次修改代码均需执行编译）

Step 4：Pytorch 测试（调用 /pytorch-test skill）

Step 4.1: 标记已完成的 API
Step 4.2: 增加测试用例
Step 4.3: 编译并运行单测（每次修改代码均需执行编译）

Step 5：更新文档（调用 /update-docs skill）

流程重要约束

1. 批量处理：每个 Step 对所有 API完成后才进入下一步
2. 正向推进：必须按 Step1 → Step2 → Step3 → Step4 → Step5 顺序执行，禁止跳过
3. 异常回退：
   • Step3/Step4 无法通过时自动回退（Step3 通过标准：单测可运行通过；Step4 通过标准：API 可配置为 ChangePrefixMatcher）
   • 选择方案错误 → 回退到 Step1；代码实现有误 → 回退到 Step2
   • 回退后从该步骤重新向前推进
4. 放弃规则：某个 API 回退 3 次以上仍失败，标记为"未对齐"并完整回退所有修改

工作示例

假设待对齐 API 为 torch.argmax：

1. Step1: 选择方案 → 得到『方案 2：C++下沉』
2. Step2: 代码修改 → 修改 Paddle 目录文件，将 paddle.argmax 下沉到 C++
3. Step3: 兼容测试 → 在 Paddle 目录添加兼容性单测，编译并运行验证
4. Step4: Pytorch 测试 → 修改 PaConvert 目录文件，编写 Pytorch 单元测试，对比测试，验证对齐
5. Step5: 更新文档 → 修改 docs 目录文件，更新 paddle.argmax 文档

四、各 Skill 说明

总控 Skill：api-compatibility（本文件）

功能定位：

• 本文件（api-compatibility）是项目的总控 skill，负责整体统筹规划
• 作为用户入口，接收 API 列表输入，协调各子 skill 完成对齐工作
• 遵循「流程正向推进」原则，按 Step1 → Step2 → Step3 → Step4 → Step5 顺序执行

核心职责：

1. 解析用户输入的 API 列表
2. 依次调用各步骤对应的子 skill
3. 汇总各步骤执行结果，输出最终对齐统计表

Skill 调用规范：

• 本项目专用 skill 为下表所列的子 skill
• 优先使用本项目专用 skill，确保流程一致性和可控性，除非其无法完成任务，否则尽量不调用其他 skill

项目专用 子 Skill 列表

Skill	对应步骤
/select-solution	Step1 选择方案
/python-decorator	Step2 方案 1 Python 装饰器
/cpp-sink	Step2 方案 2 C++下沉
/modify-origin-api	Step2 方案 3 修改原有 API
/add-new-api	Step2 方案 4 新增 API
/add-new-compat-api	Step2 方案 5 新增 compat API
/compatibility-test	Step3 兼容测试
/pytorch-test	Step4 Pytorch 测试
/update-docs	Step5 更新文档

五、自进化机制

本项目涉及的所有 skill 均具备自进化能力，通过持续学习和优化来提升工作质量。修改的 SKILL 目录为：${ROOT_DIR}/docs/docs/dev_guides/coding_agent/api_compatibility/.claude/skills

如何自进化：

• 每次交互结束后，自动复盘分析工作过程中的问题、错误和成功经验
• 结合用户反馈纠偏和运行日志，不断优化描述细节和边界条件
• 识别重复出现的问题模式和最佳实践

自进化需要修改哪里：

1. 注意事项章节：补充新发现的注意事项、工作要求
2. 常见问题处理章节：补充新发现的问题-解决方案、特殊情况处理方案
3. 修正或补充 SKILL 中新发现的错误或遗漏内容

修改注意：

• 所有优化和改进都写入各 skill 的 SKILL.md 文档，确保知识持久化
• 禁止在 SKILL 中添加任何网络代理的内容，以免安全信息泄露
• 禁止在代码中编写任何网络代理的内容，以免安全信息泄露

六、常见问题处理

Q1：API 别名如何管理？

统一放在 __init__.py 的 "API alias" 区块，不要在 math.py 等实现文件中定义。

涉及文件：

• paddle/tensor/__init__.py
• paddle/__init__.py

示例（正确做法）：

# 在 __init__.py 的 "API alias" 区块
fix = trunc
fix_ = trunc_
mod = remainder

注意：定义别名后，需从 from .math import 中移除该别名，避免导入错误。

Q2：Inplace API 如何实现？

与输入 input 相关的所有操作都必须使用 inplace 方法（scale_、add_ 等），不能用 *、+ 等非 inplace 操作。可以参考 addcdiv_的实现。