modify new_cpp_ op doc #4942
modify new_cpp_ op doc #4942
Conversation
|
感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-4942.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html |
| </tr> | ||
| <tr> | ||
| <td>args</td> | ||
| <td>算子输入参数，与该算子Python API函数的输入参数对应（当前支持的输入数据类型包括：Tensor, Tensor[]/*Tensor数组*/, float, double, bool, int, int64_t, int[], int64_t[], str, Place, DataType, DataLayout, IntArray/*主要用于表示shape,index和axes等类型数据，可以直接使用Tensor或者普通整型数组构造，目前仍在测试阶段，如非必要暂不建议使用*/, Scalar/*标量，支持不同的普通数据类型*/）。我们一般称这里Tensor类型的参数为Input(输入)，非Tensor类型的参数为Attribute(属性)</td> |
There was a problem hiding this comment.
Tensor[]/Tensor数组/，读到这里的时候一下没理解这是个注释，以为是两个类型，这个解释要不要放到句尾，更明确一下，比如在句尾加一个（注：xxxx表示xxx），后面的IntArray也是
| </tr> | ||
| <tr> | ||
| <td>kernel:data_type</td> | ||
| <td>根据指定参数推导调用kernel的data_type(对应kernel函数的模板参数'T')，默认不进行配置，会根据输入Tensor自动进行推导。如果kernel的data_type类型由某个输入Tensor决定，需要将该Tensor参数的变量名填入该项。示例中未配置则kernel的data_type由输入变量'x'决定</td> |
There was a problem hiding this comment.
如果kernel的data_type类型由某个输入Tensor决定，需要将该Tensor参数的变量名填入该项。这里是不是还要考虑参数的情况，比如dtype参数，“由某个输入参数（Tensor或者DataType参数）决定，需要将该参数对应的变量名填入该项”，下面backend也一样
| @@ -771,8 +796,8 @@ def trace(x, offset=0, axis1=0, axis2=1, name=None): | |||
|
|
|||
| - Python API 实现要点 | |||
| - 对输入参数进行合法性检查，即 `__check_input(input, offset, axis1, axis2)` | |||
| - 添加动态图分支调用，即 `if paddle.in_dynamic_mode()` 分支 | |||
| - 添加静态图分支调用，即dygraph mode分支后剩余的代码 | |||
| - 添加动态图分支调用，即 `if in_dygraph_mode` 新动态图分支和 `if _in_legacy_dygraph` 旧动态图分支 | |||
There was a problem hiding this comment.
这里末尾加一个解释吧，动态图正在重构中，暂时存在新旧两种状态，后续会移除legacy。另外，这里paddle.in_dynamic_mode是不是后来新增的，更加推荐使用的2.0接口，估计后面还得改回来
There was a problem hiding this comment.
另一个文档“API Python端开发指南“中相应的描述和这里有出入，需要一并更新下
| @@ -1,250 +1,65 @@ | |||
| # C++ OP 开发注意事项 | |||
There was a problem hiding this comment.
这个注意事项文档内容不多了，建议直接移除，相关内容附到上一个文档末尾，增加一章，避免用户需要关注两个链接
| 对Op的修改需要考虑兼容性问题，要保证Op修改之后，之前的模型都能够正常加载及运行，即新版本的Paddle预测库能成功加载运行旧版本训练的模型。<font color="#FF0000">**所以，需要保证Op的Input、Output和Attribute不能被修改（文档除外）或删除，可以新增Input、Output和Attribute，但是新增的Input，Output必须设置AsDispensable，新增的Attribute必须设置默认值。更多详细内容请参考[OP修改规范：Input/Output/Attribute只能做兼容修改](https://github.com/PaddlePaddle/Paddle/wiki/OP-Input-Output-Attribute-Compatibility-Modification)**</font> 。 | ||
|
|
||
| ### 6.ShareDataWith的调用 | ||
| ### 3.ShareDataWith的调用 |
There was a problem hiding this comment.
这节可以删了，ShareDataWith已经是要废弃的接口，而且它的功能就是DenseTensor赋值操作
|
关于kernel复用的介绍，我们还得加大一下介绍粒度，之前也没怎么展开，比如把“实现Kernel函数”那一节，改成”实现设备相关Kernel函数”，前面再加一节“通过复用已有Kernel实现设备无关Kernel函数”，暂时没有太好的示例，可以拿一个单独的示例讲一下方式，重点在于推荐这种形式，例如，PaddlePaddle/Paddle#42720 |
| @@ -1,6 +1,6 @@ | |||
| # C++ OP 开发 | |||
There was a problem hiding this comment.
这个标题要不也改成开发指南吧，和其他几个文档风格一致
| @@ -46,147 +46,188 @@ | |||
|
|
|||
| 关于Python API所处位置，可以参考 [飞桨官方 API 文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html) ，了解各个目录存放API的性质，从而决定具体的放置目录。 | |||
|
|
|||
| 接下来，我们以Trace操作，计算输入 Tensor 在指定平面上的对角线元素之和，并输出相应的计算结果，即 [TraceOp](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/trace_op.cc) 为例来介绍如何新增算子。 | |||
| 接下来，我们以Trace操作，计算输入 Tensor 在指定平面上的对角线元素之和，并输出相应的计算结果，即 [trace](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/trace_cn.html#trace) 为例来介绍如何新增算子。 | |||
| </tr> | ||
| <tr> | ||
| <td>args</td> | ||
| <td>算子输入参数，与该算子Python API函数的输入参数对应（当前支持的输入数据类型包括：Tensor, Tensor[]/*Tensor数组*/, float, double, bool, int, int64_t, int[], int64_t[], str, Place, DataType, DataLayout, IntArray/*主要用于表示shape,index和axes等类型数据，可以直接使用Tensor或者普通整型数组构造，目前仍在测试阶段，如非必要暂不建议使用*/, Scalar/*标量，支持不同的普通数据类型*/）。我们一般称这里Tensor类型的参数为Input(输入)，非Tensor类型的参数为Attribute(属性)</td> |
更新C++ Op开发文档