\u200E
中|EN
以贡献飞桨框架API为例，手把手教你从User进阶到Contributor
发布日期：2022-12-21 09:48浏览量：590次

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

由于飞桨核心是由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]])

单测的编写

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

  • 函数功能在各种参数配置下是否都正确，可以与NumPy、PyTorch进行比较；

  • 函数在动态图、静态图中是否都可以正常使用；

  • 函数是否能正常报错。

当所有的单测都通过，API的代码开发就基本完成了。只剩最后一项，编写中文文档。

文档编写

文档主要内容包括API的功能、接口形式、入参/出参的具体含义和格式以及使用示例。这几部分内容和英文文档几乎可以一一对应，写完一个可再翻译另一个。
到此，整个API开发的流程就结束了。通常在开发编译时会反复报错、debug、修改代码、重试，这些过程是必不可少的，最终体验到的喜悦也是难以言表的。
如果你也想加入开源、体验贡献开源的乐趣，快来参加
飞桨快乐开源活动：快来提PR，领取新年礼物啦
为鼓励更多的开发者参与到飞桨社区的开源建设中，帮助社区修复bug或贡献feature，加入开源、共建飞桨。飞桨快乐开源活动暖冬来袭，我们提供了三种类型的贡献任务，并为完成任务的贡献者准备了礼品表示感谢！
如果你对提PR仍有问题，欢迎在 评论区留言 或 扫描下方图片二维码 沟通咨询~

关注【飞桨PaddlePaddle】公众号
获取更多技术内容~


上一篇：飞桨最新升级汇总 （附赠AI产业应用技术方案和学习资料大礼包）
下一篇：海峡智汇加入飞桨技术伙伴计划，共同赋能“AI+机器人”智能巡检场景
相关动态
百度AI技术赋能，产业级AI落地强化营开营
上半年新增用户量翻倍！AI简历神器助“求职萌新”重塑应聘竞争力
统一多场景自动编译加速——支持动态shape场景，一套架构搞定训推需求
PaddleX图像分类赋能野生动物保护，打造濒危物种守护官
百度AICA再开课！已为业界输送410名首席AI架构师
以贡献飞桨框架API为例，手把手教你从User进阶到Contributor
发布日期：2022-12-21T09:48:25.000+0000 浏览量：590次

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

由于飞桨核心是由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]])

单测的编写

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

  • 函数功能在各种参数配置下是否都正确，可以与NumPy、PyTorch进行比较；

  • 函数在动态图、静态图中是否都可以正常使用；

  • 函数是否能正常报错。

当所有的单测都通过，API的代码开发就基本完成了。只剩最后一项，编写中文文档。

文档编写

文档主要内容包括API的功能、接口形式、入参/出参的具体含义和格式以及使用示例。这几部分内容和英文文档几乎可以一一对应，写完一个可再翻译另一个。
到此，整个API开发的流程就结束了。通常在开发编译时会反复报错、debug、修改代码、重试，这些过程是必不可少的，最终体验到的喜悦也是难以言表的。
如果你也想加入开源、体验贡献开源的乐趣，快来参加
飞桨快乐开源活动：快来提PR，领取新年礼物啦
为鼓励更多的开发者参与到飞桨社区的开源建设中，帮助社区修复bug或贡献feature，加入开源、共建飞桨。飞桨快乐开源活动暖冬来袭，我们提供了三种类型的贡献任务，并为完成任务的贡献者准备了礼品表示感谢！
如果你对提PR仍有问题，欢迎在 评论区留言 或 扫描下方图片二维码 沟通咨询~

关注【飞桨PaddlePaddle】公众号
获取更多技术内容~


上一篇：飞桨最新升级汇总 （附赠AI产业应用技术方案和学习资料大礼包）
下一篇：海峡智汇加入飞桨技术伙伴计划，共同赋能“AI+机器人”智能巡检场景
相关动态
百度AI技术赋能，产业级AI落地强化营开营
上半年新增用户量翻倍！AI简历神器助“求职萌新”重塑应聘竞争力
统一多场景自动编译加速——支持动态shape场景，一套架构搞定训推需求
PaddleX图像分类赋能野生动物保护，打造濒危物种守护官
百度AICA再开课！已为业界输送410名首席AI架构师