paddle-op-dev

name: paddle-op-dev description: PaddlePaddle (飞桨) C++ 算子开发指南。提供从 YAML 配置、InferMeta 函数、Kernel 实现、Python API 封装、单元测试到编译验证的完整算子开发流程指导。在以下场景使用此 skill：(1) 为 Paddle 框架新增 C++ 算子 (2) 修改或调试已有 Paddle 算子 (3) 编写算子的 YAML 配置、InferMeta、Kernel、Python API 或单元测试 (4) 理解 Paddle 算子开发架构和流程 (5) 编译 Paddle 并验证算子正确性

Paddle 算子开发

架构概览

Python API (paddle.xxx)
    │
    ▼ (YAML 自动生成的调度代码)
算子 InferMeta ──→ 推导输出 shape/dtype
    │
    ▼
算子 Kernel ──→ 实际计算（CPU/GPU 分别实现）

YAML 配置是连接 Python API 与底层 Kernel 的桥梁，框架编译时自动生成调度代码。

开发流程

新增算子 xxx 需完成以下 6 步：

步骤 1：YAML 算子定义

在 paddle/phi/ops/yaml/ops.yaml 和 backward.yaml 中配置前向和反向算子。

关键配置项：op(名称)、args(输入)、output(输出)、infer_meta(推导函数)、kernel(计算函数)、backward(反向算子)。

快速示例：

# ops.yaml
- op: trace
  args: (Tensor x, int offset = 0, int axis1 = 0, int axis2 = 1)
  output: Tensor(out)
  infer_meta:
    func: TraceInferMeta
  kernel:
    func: trace
  backward: trace_grad

详细配置规则见 references/yaml-config.md。

步骤 2：InferMeta 函数

在 paddle/phi/infermeta/ 下实现，按输入 Tensor 个数分文件（unary/binary/multiary）。

职责：推导输出 shape 和 dtype，检查输入合法性。

函数签名模式：

void XxxInferMeta(const MetaTensor& x, int attr, MetaTensor* out) {
  // PADDLE_ENFORCE_XX 检查输入
  out->set_dims(...);
  out->set_dtype(x.dtype());
}

详细规则和示例见 references/infermeta.md。

步骤 3：Kernel 实现

在 paddle/phi/kernels/ 下实现。设备无关的放根目录，设备相关的分 cpu/ 和 gpu/ 子目录。

文件结构：

• xxx_kernel.h — 前向声明
• cpu/xxx_kernel.cc / gpu/xxx_kernel.cu — 设备实现
• xxx_grad_kernel.h + 对应设备实现 — 反向

Kernel 函数模式：

template <typename T, typename Context>
void XxxKernel(const Context& dev_ctx, const DenseTensor& x,
               int attr, DenseTensor* out) {
  dev_ctx.template Alloc<T>(out);
  // 计算逻辑
}
// 注册
PD_REGISTER_KERNEL(xxx, CPU, ALL_LAYOUT, phi::XxxKernel, float, double) {}

参考 PyTorch 实现：Paddle 算子的计算逻辑与 PyTorch (ATen) 往往相似。实现 Kernel 时可参考 PyTorch 对应算子的实现（位于 aten/src/ATen/native/ 目录），理解核心算法后适配为 Paddle 的 API 风格（DenseTensor、dev_ctx 等）。注意不要直接复制代码，需根据 Paddle 框架规范进行适配。

详细规则和示例见 references/kernel-dev.md。

步骤 4：Python API 封装

在 python/paddle/ 对应子目录中实现 Python API。

关键要素：

• 动态图：_C_ops.xxx(args...)
• 静态图：LayerHelper + append_op
• 完整的 docstring（含可运行的 Examples）

详细规则和示例见 references/python-api.md。

步骤 5：单元测试

在 test/legacy_test/test_xxx_op.py 中编写，继承 OpTest。

测试要点：

• setUp() 设置 op_type、python_api、inputs、attrs、outputs
• test_check_output(check_pir=True) 验证前向
• test_check_grad(['X'], 'Out', check_pir=True) 验证反向
• 多 Case 继承基类重写 init_config()

详细规则和示例见 references/unit-test.md。

步骤 6：编译与验证

完成代码开发后，需要编译 Paddle 并运行测试来验证算子的正确性。

6.1 增量编译

在 Paddle 的 build 目录下执行增量编译。新增算子通常只需重新编译 phi 相关目标，无需全量编译。

cd build

# 增量编译（推荐使用 ninja，速度更快）
ninja -j$(nproc)

# 或使用 make
make -j$(nproc)

如果只修改了 Kernel/InferMeta 等 C++ 文件，可以缩小编译范围：

# 只编译 phi 库（覆盖 Kernel + InferMeta）
ninja phi -j$(nproc)

# 编译完成后重新安装 Python 包
pip install -e . --no-build-isolation
# 或
cd python && pip install -e .

6.2 运行单元测试

# 方式 1：直接运行测试文件
python test/legacy_test/test_xxx_op.py

# 方式 2：使用 pytest（支持更灵活的筛选）
python -m pytest test/legacy_test/test_xxx_op.py -v

# 方式 3：通过 ctest 运行（在 build 目录下）
cd build && ctest -R test_xxx_op -V

6.3 验证要点

• 前向正确性：test_check_output 通过，算子输出与 NumPy 参考实现一致
• 反向正确性：test_check_grad 通过，梯度通过数值微分法校验
• PIR 模式：确认 check_pir=True 下测试通过
• 多设备验证：有 GPU 环境时确认 CPU 和 GPU 结果一致

6.4 GPU 算子调试

GPU 算子出现 CUDA 错误时，使用以下环境变量辅助定位：

# 启用 CUDA 同步错误检查 + 系统内存分配器
FLAGS_check_cuda_error=1 FLAGS_use_system_allocator=1 python test/legacy_test/test_xxx_op.py

# 强制 CUDA kernel 同步执行，定位出错的 kernel
CUDA_LAUNCH_BLOCKING=1 python test/legacy_test/test_xxx_op.py

常见问题：

• CUDA error(9) — kernel 配置无效，检查 grid/block size 是否为 0（通常由空 Tensor 触发）
• CUDA error(700) — 非法内存访问，检查数组越界或空指针
• CUDA error(2) — 显存不足，减小测试数据规模或检查是否有显存泄漏

6.5 常见编译错误排查

文件清单速查

显存优化

• inplace：输出复用输入显存，YAML 中配置 inplace: (x -> out)
• no_need_buffer：反向不需要前向变量的内存数据时配置，提前释放内存
• 减少反向无关变量：反向 args 中只包含实际需要的前向变量

参考文档

• 官方文档