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

中国软件开源创新大赛:飞桨框架任务挑战赛 赛题六 RFC #529

Merged
merged 13 commits into from
May 16, 2023

Conversation

Liyulingyue
Copy link
Contributor

@paddle-bot
Copy link

paddle-bot bot commented Apr 28, 2023

你的PR提交成功,感谢你对开源项目的贡献!
请检查PR提交格式和内容是否完备,具体请参考示例模版
Your PR has been submitted. Thanks for your contribution!
Please check its format and content. For this, you can refer to Template and Demo.

Copy link
Contributor

@jiahy0825 jiahy0825 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

赞细致的文档和深入的思考!!

整体来看,有些概念是赛题写的不够清楚,在 comment 里做了澄清(例如 C++ 文档不必和 Python 对齐,这部分可以节省些开发工作)。其次,C++ 相关的展示信息也许可以更加丰富些(这部分也许需要更多的开发工作)~~

如果有我表述不清楚的,也许看下 torch 的 C++ 文档,部分疑惑可以得到解答:https://pytorch.org/cppdocs/api/library_root.html

另外,非常鼓励自己的思考,如果一些展示的结果,能参考并超越 torch 的文档思路和设计,相信对自己个人的成长和赛题本身,都非常有意义!

# 一、概述
## 1、相关背景

自 paddle 2.3 版本开始,飞桨深度学习框架提供定义与用法与相应 Python API 类似的 C++ API,其 API 命名、参数顺序及类型均和相应的 paddle Python API 对齐,可以通过查找相应 Python API 的官方文档了解其用法,并在自定义算子开发时使用。通过调用这些接口,可以省去封装基础运算的时间,从而提高开发效率。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

现在的 C++ API 主要在自定义算子场景下使用。
未来框架是有可能打造自己的 C++ 体系的,从这个角度出发:本赛题想做的范围其实更“广”,可以算作 C++ 体系构建的预备工作。


在[飞桨API文档页面](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/index_cn.html)引入新的章节`PADDLE_API`,用于展示飞桨当前的类 Python 的 C++运算 API。

展示内容应与Python API文档对其,包括:API名称、对应的Python API名称、API介绍、参数、返回值、示例代码。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

复用 Python 文档的想法很棒!只是出于以下几点考虑,C++ API 的展示应该独立于 Python API,并不要求 C++ API 的展示内容与 Python API 文档对齐(也许根本无法对齐):

  1. 虽然 paddle/phi/api/include/api.h 内的 C++ API 已经在尽可能的与 Python 对齐,但是由于一些历史原因,部分 API 的参数和用法仍不能保证与 Python API 完全一致
    (注:现在已经对齐的 API 可以从 paddle/phi/api/ext/tensor_compat.h 文件中查阅)
  2. 未来如果构建 C++ 体系,C++ API 可能会有一些自己专属的 API,这部分 API 是没有 Python API 做参考的。
  3. C++ API 仍在迭代建设中,尚无 CI 监控,变化较为频繁,手动维护的成本较高。

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

更新了文档内容~

修正为,仅对类Python的API进行复用和对齐~


## 2、功能目标

在[飞桨API文档页面](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/index_cn.html)引入新的章节`PADDLE_API`,用于展示飞桨当前的类 Python 的 C++运算 API。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

此处能否加一些示例性的图片?前期尽可能的对齐想法,有利于推进后续的开发过程。

例如我理解的章节,是否在这里新增一章,名称为 “C++ 文档” ?(此处后续可能要 assign PM 一起看下)

063668b193c418fbffb383ff6e5e939f

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

如果cpp的文档足以支撑一个单独的章节,我觉得可以放在此处。但我原意是在API文档下面,和paddle、paddle.amp、paddle.auido这些共同作为同一级的标题。

Comment on lines 37 to 39
飞桨的 C++ API 体系还在建设中,最终暴露给用户的API信息通过在安装根目录`site-packages/paddle/include/paddle`中搜索`PADDLE_API`获取。当前有12个class,450个API以及2个宏定义。

相比于Python API,无法在C++ API的源码中获取对应的API说明和示例代码。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

赞这部分的统计和描述👍

Comment on lines 51 to 53
无法确定能够通过自动化脚本获取的信息有:
- C++ API的参数信息和返回值信息,如果C++ API的参数信息完全与Python对齐,则C++文档直接抽取Python文档的参数信息即可,否则,则需要人工补足。
- C++ API的示例代码,C++API的示例代码目前需要人工补足。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

能否尽可能的减少手动工作(同时也可以节省一些本赛题的开发工作),基于如下几点考虑:

  1. 本赛题结束后,很可能不会有大量的人力放到维护 C++ 文档上。手动维护成本过高,不利于后续的扩展
  2. C++ API 仍有频繁变动的可能,经过一段时间的开发,很可能造成手工维护文档与 C++ 代码之间的差异。
  3. 基于前面的 comment,C++ 文档不需要和 Python 对齐,因此不需要人工补足抽取 Python 文档的参数信息。
  4. C++ API 的示例代码,目前来看是不需要提供的。从上述统计数据来看,API 数量多达 400+,挨个补足的成本有些过高了。

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

考虑到维护性,以及C++可能会自成体系,可以只补全部分类Python的 C++ API介绍文档。

Comment on lines 47 to 49
- C++ API的文件路径、接口注释、命名空间、返回值信息。这些信息可以通过扫描源代码文件自动提取。
- C++ API对应的Python API,由于两种语言的API命名几乎保持一直,可以通过搜索匹配的方式获取对应的Python API名称。
- API对应的介绍文本。C++ API和Python API的介绍文本可以保持一直。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

需要注意的是,本赛题不仅要展示 C++ API,同时也包括 C++ class。
是否有考虑过 C++ class 的展示形式?以及目录结构如何展示?建议再丰富下这部分信息。

提供一个全局的视角:如果我是一名只会写 C++ 代码的开发者,我期望从 C++ 文档中,获得什么信息?如何快速的获取这些信息?从这个角度出发,也许有利于整理思路~~

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

更替了一下描述

  • 以PADDLE_API泛指所有被修饰的成员
  • 增加了对Overview的描述

Comment on lines 61 to 65
## 3、 C++ API 与 Python API 对齐

C++ API 与 Python API 有两种对齐方案,其一是通过文件记录映射表,将C++ API名称映射到指定的Python API上;其二,根据C++ API文件名直接匹配对应的Python API。

本次优先使用后者,对于特殊的API,使用第一种方案进行铆定。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

参考上述 comment,这部分对齐工作是不必要的。

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

整体修正为仅对齐类Python API 的C++ API,故对于这部分还需要对齐

Comment on lines 149 to 154
1. 构建API抽取脚本,实现API抽取
2. 构建API对齐脚本,用于根据抽取的API匹配当前已有的Python文档,生成对应rst。
3. 开放Tracking Issue,募集开发者人工审查文档信息,并补充C++ 示例代码
4. C++ 文档接入官网文档页面develop分支
5. C++ 文档自动化更新脚本接入官网文档页面develop分支
6. (可选) 在Docs仓库下构建C++ 代码审查CI
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

不仅考虑 API 的抽取,被 PADDLE_API 修饰的都需要考虑进去~~

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

不仅考虑 API 的抽取,被 PADDLE_API 修饰的都需要考虑进去~~

更替了一下描述,以PADDLE_API泛指所有被修饰的成员~

Comment on lines 73 to 81
```python
.. _cn_api_fluid_layers_abs:

abs
-------------------------------

.. cpp:function:: PADDLE_API Tensor abs(const Tensor& x)

绝对值函数。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

从上述 comment 来看,这部分的示例内容需要更新下。也许可以参考 torch API 的展示信息(以 from_blob 为例):https://pytorch.org/cppdocs/api/function_namespacetorch_1ac009244049812a3efdf4605d19c5e79b.html?highlight=from_blob

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

增加一些条目信息

  • namespace
  • 文件路径
  • 对应Python API名称

@Liyulingyue
Copy link
Contributor Author

@jiahy0825 @gouzil 文档更新啦~

@gouzil
Copy link
Member

gouzil commented Apr 30, 2023

补充说明: rst目录结构目前有两个想法, 研发大哥看一下哪个好点

  • .h作为目录结构和二级标题划分
  • namespace作为目录结构和二级标题划分

@Liyulingyue Liyulingyue requested a review from jiahy0825 May 3, 2023 05:20
Copy link
Contributor

@jiahy0825 jiahy0825 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

第二次 Review 总结:文档日臻完善,仍有一个核心问题待回答:
对研发人员来讲,目标是后续的手工维护成本接近于 0,最好不用投入手工维护成本。本赛题完成后,研发在新增/修改 C++ API/Class 时,需要投入的维护成本有多高?能否做到尽可能少的手动维护?

Comment on lines +69 to +71
## 3、 C++ API 与 Python API 对齐

仅类Python 的 C++ API 需要与 Python API 信息对齐。对于这部分API,首先根据C++ API文件名直接匹配对应的Python API,再对这部分信息进行核验,生成文档映射表。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

C++ 和 Python 对齐这块,参考上一次 review 的 comment,仍有疑问需要解答:

  1. 由于一些历史原因,部分 C++ API 仍未和 Python API 完全对齐,这些 C++ API 如何与 Python 对齐?
  2. 如果是手工对齐的话,如果 C++ API 的参数和用法未来发生变化,是否还要对文档做手工维护呢?

需要想个办法避免 API 对齐的手动维护成本~~否则后续开发时,非常容易造成 C++ 和 Python 不一致的情况。


```

## 5、 C++ API文档
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

本章节仅展示了与 Python API 对齐的 C++ API 示例。对于 C++ 专属的 API,展示示例是什么样的?建议也提供一份示例代码~

Comment on lines 141 to 147
代码示例
:::::::::::::::::::::

#include "paddle/extension.h"

auto x = paddle::full({3, 4}, -1.0);
auto grad_x = paddle::abs(x);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这部分的代码示例是需要的吗?如果要做的话,可能会有几个难点:

  1. 示例代码的正确性如何保证?
  2. 手动添加示例代码的工作量,最好预先评估下,如果工作量过大,是否有绕过的办法?
  3. 后续的手动维护成本如何?

Comment on lines 230 to 235
## 7、 更新与维护

每日更新时,拉取最新paddle源码,并编译对应的whl包,用于自动提取PADDLE_API。对于不同的提取结果,采用不同的策略:
- 对于已有但是没有抽取到的信息,可以被视为退场,docs目录下虽然保存对应的rst文件,但不在官网页面展示
- 对于新增或修改的信息,通过脚本自动抽取对应信息生成rst文档。
- 对于类Python 的 C++ API,不仅需要解析C++的文件信息,还需要根据对应Python 文档修改rst内容。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

建议本章再增加一小节,“手动维护成本”,该小节总结本赛题完成后,研发后续需要投入的人工维护成本,便于后续我们对这个方案做评估。
核心需要总结的点在于:

  1. 如果新增了一个 C++ API/Class,为了维护 C++ 文档,研发需要手工添加哪些信息?
  2. 如果修改了一个 C++ API/Class,为了维护 C++ 文档,研发需要手动维护哪些地方的代码?

@jiahy0825
Copy link
Contributor

jiahy0825 commented May 6, 2023

补充说明: rst目录结构目前有两个想法, 研发大哥看一下哪个好点

  • .h作为目录结构和二级标题划分
  • namespace作为目录结构和二级标题划分

个人倾向于按照 .h 划分~~ 因为 C++ 开发者可能直接 include .h 头文件,按照 .h 划分可以提升文档查找效率。

Copy link
Contributor

@jiahy0825 jiahy0825 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

第三次 review 总结:文档相对很完善了,对上次 review 关注的核心问题也做了解答,很赞~~
本次 review 添加的意见,主要是在对齐我们之间的设计思路,以及提出了几个疑惑和 tips

- 类Python 的 C++ API对应的Python API信息。由于两种语言的API命名几乎保持一致,可以通过搜索匹配的方式获取对应的Python API名称、说明等信息。

无法确定能够通过自动化脚本获取的信息有:
- C++ API的参数信息和返回值信息,如果C++ API的参数信息完全与Python对齐,则C++文档直接抽取Python文档的参数信息即可,否则,可能需要人工补足。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

对于 C++ API的参数信息和返回值信息这个表述,是可以自动化获取的吧?因为在解析 API 函数签名的时候,已经可以解析出参数类型和返回值类型了。
比如 PADDLE_API Tensor abs(const Tensor& x); 解析函数签名的时候,可以自动解析出输入 x 类型是 const Tensor&,返回值类型是 Tensor

此处表达的是想展示这样的信息吗? **x** (Tensor) - 输入的 Tensor,数据类型为:float32、float64。
想要展示对输入和输出参数的具体描述,这个信息如果要手工补足,有手动维护成本的话,不展示即可~~


## 3、 C++ API 与 Python API 对齐

仅类Python 的 C++ API 需要与 Python API 信息对齐。对于这部分API,首先根据C++ API文件名直接匹配对应的Python API,再对这部分信息进行核验,生成文档映射表。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

可以参考 paddle/phi/api/ext/tensor_compat.h 文件,这个文件里维护了 C++ 和 Python API 完全对齐的 API 列表。就不需要再核验 C++ 和 Python API 是否匹配啦~

PS-这个文件的作用:tensor_compat.h 文件里的 API 是经过我们对齐后的、稳定的 API,因此外部用户使用的时候,可以直接用 paddle::abs 的方式来调用。对于不稳定的 API,或者说 api.h 头文件里的 API,外部用户调用的时候,得加上 experimental 命名空间,例如 arange 这个 API 没放到 tensor_compat.h 文件里,用户调用的时候,就得用 paddle::experimental::arange 的方式调用。

Comment on lines 150 to 164
对应的Python API
:::::::::::::::::::::
[paddle.abs(x, name=None)](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/abs_cn.html)

定义目录
:::::::::::::::::::::
paddle\phi\api\include\api.h

参数
:::::::::::::::::::::
- **x** (Tensor) - 输入的 Tensor。

返回
:::::::::::::::::::::
输出 Tensor,与 ``x`` 维度相同。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

能够对齐的 C++ API,复用 python API 并展示 python 链接的方法很棒~~

那么对于 python 文档里面已有的信息,是不是就不需要重复 copy 到 C++ 文档里了?
以 abs 为例,参数返回 这两部分的内容,还有从 python 文档里 copy 过来的必要吗?

## 9、 扩展与维护成本

综合考虑赛题要求、赛题导师和参赛成员的意见,当前的 rfc 方案侧重于0人工维护。当前的解决方案几乎可以实现0人工维护,但在下述情况下,仍需要进行人工维护:
1. 补充注释:随着C++ 算子的开发,注释必然日趋规范,目前的API注释比仅为 3/460,即当前的注释规范可能并不稳定。在后续的工作中,注释规范可能发生变化,当我们确定了注释的格式后,需要对文档抽取函数进行少量更改,以适配新的注释格式抽取API的说明。维护量:低
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

对齐下我们的理解:此处想做的是提供一种 “根据指定格式来自动解析注释” 的机制。

如果是这样的话,我觉得这个部分很有意义,有利于后续 PADDLE_API 的扩展和维护。并且鉴于现在只有很少量的 API 和 class 写了注释,修改这些注释代码的成本也不高。
如果后续注释格式确定了,可以在文档里补充下格式(比如说根据注释格式里的什么标志,确定解析该注释并展示在文档中)


定义目录
:::::::::::::::::::::
paddle\phi\api\include\api.h
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tips:此处的目录,是否还可以直接链接到 github 的代码位置?

Copy link
Contributor

@jiahy0825 jiahy0825 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

第三次 review 总结:文档相对很完善了,对上次 review 关注的核心问题也做了解答,很赞~~
本次 review 添加的意见,主要是在对齐我们之间的设计思路,以及提出了几个疑惑和 tips

@jiahy0825
Copy link
Contributor

hi~下午研发和 PM 内部对这个赛题做了讨论,很多内容在前几次的 review 过程中,应该也提到了,提炼讨论后的几项要点,同步在这个 RFC 中:

  1. C++ 文档标题的位置,level 与 python 的 “API 文档” 相同,放到 “API 文档” 标题的右边
  2. 本赛题重心放在工具的建设,而非 C++ 文档内容的建设,需要通过自动化的方式来生成 C++ 文档
  3. 减少 docs 仓库维护成本,没必要提大 PR 把 rst 文件托管到代码仓库,尽可能直接自动化在官网页面展示
  4. 同时提供中英文文档,两者的内容保持一致:
    对于 C++ 和 python 能够对齐的 API,可以直接从 C++ 文档给个链接,让用户参考 Python API 的用法
    对于尚未对齐的 API,即使只提供函数签名也是可接受的,不需要再翻译成中文

@Liyulingyue
Copy link
Contributor Author

hi~ 根据comments,增改了一些表述。

对于comments中的内容,我们基本没有异议,但仍有以下两点需要讨论:

  1. 中国软件开源创新大赛:飞桨框架任务挑战赛 赛题六 RFC #529 (comment) 如果API完全一致,则参数说明和返回值说明也可以直接copy,但参数和返回值的数据类型是可以直接解析的。
  2. 中国软件开源创新大赛:飞桨框架任务挑战赛 赛题六 RFC #529 (comment)10、 扩展与维护成本中,列举了当前的一些注释形式。需要讨论一下何种形式更为合适作为后续的规范。对这些注释的修改可以放入本次赛题进行,也可以放在赛题结束后再进行。

Copy link
Contributor

@jiahy0825 jiahy0825 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

第四次 Review 总结:对文档进行更细致的打磨,本次 Review 意见内已经对两个需要讨论的点做了回复~

rfcs/Docs/飞桨框架 C++ 文档抽取与展示.md Outdated Show resolved Hide resolved
rfcs/Docs/飞桨框架 C++ 文档抽取与展示.md Outdated Show resolved Hide resolved
Comment on lines +180 to +186
参数
:::::::::::::::::::::
- **x** (Tensor) - 输入的 Tensor。

返回
:::::::::::::::::::::
输出 Tensor,与 ``x`` 维度相同。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

个人理解,此处没必要把 python 的文档再 copy 过来,直接展示 python 文档的链接即可,基于两个理由:

  1. copy 过来会增加你们的开发成本:比如 Python API 会带有 name 参数,而 C++ 是没有的,copy 过来时还要对这部分逻辑做处理。这部分的开发成本是可以节省下来的,节省下来的人力,可以用来思考下其他的问题,比如 overview 是否有更好的展示方式?class 文档有没有更清晰的文档展示形态?
  2. 遵循“若无必要,勿增实体”的奥卡姆剃刀原则:从查看文档的用户来讲,他们很可能并不清楚,哪些 API 是对齐的,哪些是未对齐的,以及背后的历史背景。此时如果有些 API 提供了 “参数” 和 “返回值” 的中文解释,但有些 API 没有的话,用户很可能会有疑问,此时会增加用户的理解成本。感觉直接这样给用户提示就可以: 本 API 与 Python API 对齐,详细用法可参考链接:[paddle.abs(x, name=None)](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/abs_cn.html)

*/
```

其中第三种方式对于文本的描述最为清晰,但每次增加API时的工作成本都会偏大。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

个人倾向于第三种注释方式,这种方式对用户和研发来讲,都是更清晰的展示方式~此处似乎是第三个 的 brief 写的比较详细,实际上的成本感觉并不高。

看统计数据,只有不到 10 个 class 和 API 提供了注释,注释规范化的工作感觉可以在本赛题内完成。
此外,是否能在 Paddle 侧添加 CI 拦截?如果后续新增 PADDLE_API 修饰的 class 或 API,则需要研发提供完整的注释信息。

Copy link
Contributor

@jiahy0825 jiahy0825 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks for your hard work~~

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants