以贡献飞桨框架API为例，手把手教你从User进阶到Contributor

Posted 2023-03-05 百度大脑

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了以贡献飞桨框架API为例，手把手教你从User进阶到Contributor相关的知识，希望对你有一定的参考价值。

2016年9月，飞桨框架正式开源。飞桨框架建设并非只靠百度工程师，也离不开热爱飞桨、热爱开源的开发者们，他们用自己的方式参与飞桨框架建设，与飞桨共同成长。作为大型开源项目，飞桨社区十分欢迎各位开发者积极提出需求或不足，并主动提交pr解决。本文将由开发者李其睿介绍贡献API的经验。

前段时间百度飞桨组织了飞桨黑客马拉松第三期活动，该活动发布了诸多有趣的开发任务。我参与了基础API方向的开发任务，并新增了paddle.triu_indices API。这个API可以获取一个Tensor主对角线所有右上方元素的坐标，在不久前发布的飞桨2.4版本中已经上线(官方文档)。借此机会记录一下开发过程，供有兴趣为飞桨贡献的小伙伴入门参考。

感兴趣的同学可以直接参考PR:

飞桨代码
https://github.com/PaddlePaddle/Paddle/pull/45168
文档
https://github.com/PaddlePaddle/docs/pull/5161
提案
https://github.com/PaddlePaddle/community/pull/207

一个API背后的组成

由于飞桨核心是由C++构建的，通过Python封装了API供用户使用，因此每个API均对应着Python部分的代码和C++部分的代码，以下将分开介绍。

C++部分

现在飞桨的算子库核心代码都在paddle/phi这个目录下。

paddle/phi/kernels: 这个目录下是算子的实现部分，分别需要实现“.h”文件（头文件）、 “.cc”文件（CPU算子）、“.cu”文件（GPU算子) 这三个部分；
paddle/phi/infermeta: 这个目录下的文件是推理一个API的输出参数的meta数据，例如：数据维度、数据type等。该目录下有多个文件，根据算子输入Tensor的参数数量确定InferMeta函数放置位置，比如算子输入Tensor参数是0个，那推理函数需要放在nullary.cc/h中；如果是Tensor参数有2个，则需要放在binary.cc/h中；
paddle/phi/api/yaml：这个目录下是用以注册API属性的yaml文件，需要在yaml文件中添加你新增API的一些属性信息。

Python部分

Python部分相对而言内容比较少了，主要在python/paddle目录下。

python/paddle/tensor/creation.py: 这个文件主要是用来构造该API在Python端调用时的接口，其中包含了入参的校验、算子的调用过程。另外英文版的API文档也在这里进行编写；
python/paddle/_init_.py：初始化文件；
python/paddle/fluid/tests/unittests/test_xxxx.py：单测文件。

文档

一个API的完整构建，除了代码的开发外，其文档的撰写也是非常必要的。飞桨的中文文档位于PaddlePaddle/docs仓库中。

docs/api/paddle/Overview_cn.rst中用一句话对API的功能进行简要概述；
docs/api/paddle/xxxxx_cn.rst对于新增的API，需要新增一个rst文件进行文档撰写，撰写内容包括API的输入、输出、代码示例等。

撰写提案

当着手开发一个新的API时，第一步不是写代码，而是进行分析和设计。

关于设计，有以下几点需要注意：

飞桨的现状。想要实现的API是否不存在、是否可以由其他API组合方式实现？
业内是否有此API？例如PyTorch、NumPy、TensorFlow等，如果有的话他们是怎么实现的？哪种实现方式更好？
飞桨中新增的这个API的命名、参数设计。
测试方案设计。

作为社区开发者，我们可以综合上述几点将设计写成文档，提交至Coummunity库，与飞桨的工程师沟通、调整并确定方案。

正式开发

拉代码并成功编译

首先在Paddle仓库的GitHub页面上fork一份代码；
最方便的搭建开发环境的办法就是使用飞桨官方提供的Docker镜像；

然后在Docker镜像内clone，并切换到develop分支(最好在做每个任务时从develop分支checkout一个新分支，会更方便)。

顺利的话到此就编译成功。编译好的whl文件在 /paddle/build/python/dist目录下，进入目录使用pip install安装。

以后修改完代码就重复执行make、pip3 install的过程即可。

到此就可以正式开始写代码

第一步：首先需要实现最核心的kernel部分。

让我们从最简单的部分开始，头文件triu_indices_kernel.h。头文件通常不需要写主要的代码逻辑，只要注册好方法就好。

第二步：接下来需要实现CPU端的代码逻辑triu_indices_kernel.cc。

CPU端的主体的计算逻辑其实并不复杂，这里对代码的几个注意点进行说明：

kernel需要在phi这个命名空间下；
受Python书写习惯影响，有时会输出return。更好的方式是将输出需要用到的内存分配后作为参数传入kernel；
需要多关注边界条件，以及不要受惯性思维限制。比如Tensor不一定是正方形，对角线也不一定是主对角线，对于这类非常规情况的处理需要格外注意，这些情况可能也是需要代码量最多的地方（如下图所示）；
最后通过PD_REGISTER_KERNEL注册算子。

第三步：接下来需要实现GPU端的kernel：triu_indices_kernel.cu。

编写GPU kernel需要有一点CUDA的基础知识，这里需要稍加学习，理解基础的概念。如果零基础的话，指路比较好的入门资料如下：

一个入门博客：

https://face2ai.com/program-blog/#GPU编程（CUDA）；

两本入门书：《CUDA By Example》《Professional CUDA C Programming》

在编写GPU kernel时，我们需要抛弃掉往常写代码线性执行代码的思想，将整个计算任务展开成一个计算组。有许许多多个worker帮我们，每个worker只需要负责很小一部分数据计算即可。当转变成并行计算的思想后，代码编写和理解就会稍微简单一些。

由于整体的kernel代码较长，这里不再另作展示，有需求的可自行前往代码库里查看。

第四步：写完两个kernel，最难的部分就结束了，下面该写配套代码了。

首先是推理meta信息所在：nullary.cc和nullary.h。这一步很简单，在nullary.h里进行函数声明，在nullary.cc里实现具体推理meta信息的逻辑。.cc文件内较为复杂的是需要计算输出的shape，当输入是正方形，对角线就是主对角线，其计算很简单。但当输入是矩形，对角线进行了向上或向下平移的话则需要考虑不同的情况。

第五步：最后一项工作就是注册算子。在legacy_api.yaml中添加信息（最新develop已经更新为legacy_op.yaml）。

根据格式规范，写清楚API的名字、参数等重要信息。

第六步：下面就是轻松的Python代码环节。首先说核心的creation.py。

这里定义的函数格式就是以后使用该API过程中交互的格式。

def triu_indices(row, col=None, offset=0, dtype='int64'):
    """
    英文文档部分
"""
# 校验各入参类型
# 根据计算图类型引用算子
# 返回计算结果
        )
    return out

其中主要做的是例如参数校验、与op交互等过程。另外，这里的文档编写是直接展示在英文版飞桨文档网页的，需要认真编写。编写完成后，在__init__.py中导入即可。

到这里API主体代码就全部完成了，可以执行make、pip install去进行测试了。这里可以先试验，体验一下自己的工作成果。

import paddle
data1 = paddle.triu_indices(4,4,0)
print(data1)
Tensor(shape=[2, 10], dtype=int64, place=Place(cpu), stop_gradient=True,

Output:
       [[0, 0, 0, 0, 1, 1, 1, 2, 2, 3],
        [0, 1, 2, 3, 1, 2, 3, 2, 3, 3]])

单测的编写

简单的体验看起来是没问题的，下面需要编写详尽的单测案例来进行测试。主要测试以下几项：