paddle-op-dev: Скилл разработки C++ операторов Paddle

--- 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`(反向算子)。 快速示例： ```yaml # 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](references/yaml-config.md)。 ### 步骤 2：InferMeta 函数 在 `paddle/phi/infermeta/` 下实现，按输入 Tensor 个数分文件（unary/binary/multiary）。 职责：推导输出 shape 和 dtype，检查输入合法性。 函数签名模式： ```cpp void XxxInferMeta(const MetaTensor& x, int attr, MetaTensor* out) { // PADDLE_ENFORCE_XX 检查输入 out->set_dims(...); out->set_dtype(x.dtype()); } ``` 详细规则和示例见 [references/infermeta.md](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 函数模式： ```cpp 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](references/kernel-dev.md)。 ### 步骤 4：Python API 封装 在 `python/paddle/` 对应子目录中实现 Python API。 关键要素： - 动态图：`_C_ops.xxx(args...)` - 静态图：`LayerHelper` + `append_op` - 完整的 docstring（含可运行的 Examples） 详细规则和示例见 [references/python-api.md](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](references/unit-test.md)。 ### 步骤 6：编译与验证 完成代码开发后，需要编译 Paddle 并运行测试来验证算子的正确性。 #### 6.1 增量编译 在 Paddle 的 `build` 目录下执行增量编译。新增算子通常只需重新编译 phi 相关目标，无需全量编译。 ```bash cd build # 增量编译（推荐使用 ninja，速度更快） ninja -j$(nproc) # 或使用 make make -j$(nproc) ``` 如果只修改了 Kernel/InferMeta 等 C++ 文件，可以缩小编译范围： ```bash # 只编译 phi 库（覆盖 Kernel + InferMeta） ninja phi -j$(nproc) # 编译完成后重新安装 Python 包 pip install -e . --no-build-isolation # 或 cd python && pip install -e . ``` #### 6.2 运行单元测试 ```bash # 方式 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 错误时，使用以下环境变量辅助定位： ```bash # 启用 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 常见编译错误排查 | 现象 | 排查方向 | |---|---| | 找不到 `XxxInferMeta` 符号 | 检查 InferMeta 函数是否在 `.h` 中声明、YAML 中函数名是否拼写一致 | | 找不到 `xxx` kernel | 检查 `PD_REGISTER_KERNEL` 注册名是否与 YAML `kernel:func` 一致 | | Python 端 `_C_ops.xxx` 不存在 | 确认 YAML 配置正确且已重新编译，`pip install -e .` 已执行 | | 参数数量不匹配 | 对照 YAML `args` 与 InferMeta/Kernel 函数签名的参数列表 | ## 文件清单速查 | 内容 | 文件位置 | |---|---| | 前向 YAML | `paddle/phi/ops/yaml/ops.yaml` | | 反向 YAML | `paddle/phi/ops/yaml/backward.yaml` | | InferMeta | `paddle/phi/infermeta/{unary,binary,multiary}.{h,cc}` | | Kernel 头文件 | `paddle/phi/kernels/xxx_kernel.h` | | CPU Kernel | `paddle/phi/kernels/cpu/xxx_kernel.cc` | | GPU Kernel | `paddle/phi/kernels/gpu/xxx_kernel.cu` | | Python API | `python/paddle/` 对应子目录 | | 单元测试 | `test/legacy_test/test_xxx_op.py` | ## 显存优化 - **inplace**：输出复用输入显存，YAML 中配置 `inplace: (x -> out)` - **no_need_buffer**：反向不需要前向变量的内存数据时配置，提前释放内存 - **减少反向无关变量**：反向 args 中只包含实际需要的前向变量 ## 参考文档 - [官方文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/api_contributing_guides/new_cpp_op_cn.html)