Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the contribution guide #5104

Merged
merged 20 commits into from
Aug 11, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ API 设计文档的目的是为了社区开发者更容易的参与开源项目
.. toctree::
:hidden:

read_before_contributing_cn.md
api_design_guidelines_standard_cn.md
new_python_api_cn.md
new_cpp_op_cn.md
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# 贡献前阅读

本章主要介绍开发飞桨原生算子 API 的方法,可先参见通用的 [代码贡献流程](../code_contributing_path_cn.html) 章节,再结合本文介绍的 API 开发要点,即可掌握飞桨原生算子 API 开发方法和流程。

## 一、飞桨原生算子 API 开发解读

飞桨框架 API 前端采用 Python 语言,以便获得更好的编程体验;后端的计算逻辑实现采用 C++ 语言,调用底层算子内核 (kernel)函数实现计算逻辑,以便获得更好的运行性能,如下图所示。

开发一个新的飞桨原生算子(Operator,OP),通常需要先开发 C++ OP,即通过 Yaml 配置定义算子描述、C++ 开发算子 kernel,再封装 Python API;如果要新增的算子可以用其他 Python API 组合得到,则可以只开发 Python API 代码。

- 使用 C++ 定义算子,开发门槛较高,需有一定 C++ 或 CUDA 等软件栈开发基础,但是具有性能优势;
- 使用 Python API 组合方式,只需 Python 编码,代码实现相对简单灵活,但会引入 Python 调度开销,影响性能;如果当前飞桨框架提供的基础算子 API 无法满足需求,仍然需要使用 C++ 实现算子。

![img](images/paddle_api.png)


## 二、飞桨 API 设计文档提交说明

设计文档,通常也叫 RFC(Request for Comment)文档,可方便开发者与飞桨核心团队、其他社区开发者充分交流设计思路,以便进一步完善设计方案,并确保与飞桨设计理念一致。请参考如下步骤完成 API 设计文档的提交:

1. 阅读 [飞桨 API 设计和命名规范](api_design_guidelines_standard_cn.html),确保新增 API 符合飞桨相关规范。
2. 根据 [API 设计文档模版](https://github.com/PaddlePaddle/community/blob/master/rfcs/APIs/api_design_template.md),填写必要的设计内容。另外可参考 [API 设计文档样例](https://github.com/PaddlePaddle/community/blob/master/rfcs/APIs/20200301_api_design_for_quantile.md)。
3. 将设计文档提交 Pull Request (PR)到 [community/rfcs/APIs/ ](https://github.com/PaddlePaddle/community/tree/master/rfcs/APIs) 目录下。
4. 等待文档接受评审和讨论,并根据各方意见修改文档。通常飞桨团队会在三个工作日内回复,如果 API 功能较复杂,还将发起评审会议,并提前在 PR 的评论区公布会议时间、会议地址、参与人、议题等内容,请及时关注 PR 中最新动态。

当设计文档通过评审后,将会合入到 [community/rfcs/APIs/ ](https://github.com/PaddlePaddle/community/tree/master/rfcs/APIs) 目录下。

## 三、飞桨 API 代码实现流程

当 API 设计文档合入后,开发者即可进行代码开发。此过程请参考相应的开发规范,包括如下步骤:

- 如果新增 API 不需要开发新的 C++ OP,可以用其他 Python API 组合得到新的 API,请参考 [飞桨 API Python 端开发指南](new_python_api_cn.html) 章节完成,包括开发 Python 代码、单元测试代码和 API 文档等步骤。
- 如果新增 API 需要开发新的 C++ OP,请参考 [C++ 算子开发指南](new_cpp_op_cn.html) 章节完成,包括开发 OP 实现代码、封装 Python API 代码、单元测试代码和 API 文档等步骤。
- 在 paddle/phi/kernels 目录下存放了飞桨框架已经实现的不同硬件的算子内核,可供开发 C++ OP 时调用。
- 有时也需要自己开发新的算子内核(OP Kernel),这时可能需要使用硬件支持的软件栈(如 CUDA)来实现,或者使用飞桨框架提供的 Kernel Primitive API 来实现,后者具体介绍请参见 [Kernel Primitive API](../op_optimization/kernel_primitive_api/index_cn.html) 章节。

值得注意的是,代码开发完成后,请确保通过了单元测试和 CI 测试。

![img](images/paddle_api_dev_flow.png)

## 四、飞桨 API 代码开发规范说明

请遵循如下开发规范和测试要求:

- [代码风格规范](../style_guide_and_references/style_guides_cn.html)
- [飞桨 API 设计和命名规范](api_design_guidelines_standard_cn.html)
- [飞桨 API 单元测试及验收规范](api_accpetance_criteria_cn.html)
- [Paddle CI 测试详解](../style_guide_and_references/paddle_ci_manual_cn.html)
Loading