Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
夏有凉风,冬有雪
Paddle
提交
c1075126
P
Paddle
项目概览
夏有凉风,冬有雪
/
Paddle
与 Fork 源项目一致
Fork自
PaddlePaddle / Paddle
通知
1
Star
1
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
1
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
P
Paddle
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
1
Issue
1
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
c1075126
编写于
9月 06, 2017
作者:
C
Cao Ying
提交者:
GitHub
9月 06, 2017
浏览文件
操作
浏览文件
下载
差异文件
Merge pull request #3873 from lcy-seso/update_doc
update the doc for how to write the operators.
上级
b59f3018
20be846c
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
76 addition
and
81 deletion
+76
-81
doc/howto/dev/new_op_cn.md
doc/howto/dev/new_op_cn.md
+76
-81
未找到文件。
doc/howto/dev/new_op_cn.md
浏览文件 @
c1075126
...
...
@@ -23,17 +23,20 @@
-
`framework::OperatorWithKernel`
:继承自OperatorBase,Op有计算函数,称作有Kernel。
-
`class OpProtoAndCheckerMaker`
:描述该Op的输入、输出、属性、注释,主要用于Python API接口生成
依据是否包含kernel,将Op分为两种:包含Kernel的Op和不包含kernel的Op,前者Op的定义继承自
`OperatorBase`
,后者继承自
`OperatorWithKernel`
。本教程主要介绍带Kernel的Op如何写,简单总结Op需要包含的内容如下:
依据是否包含kernel,
可以
将Op分为两种:包含Kernel的Op和不包含kernel的Op,前者Op的定义继承自
`OperatorBase`
,后者继承自
`OperatorWithKernel`
。本教程主要介绍带Kernel的Op如何写,简单总结Op需要包含的内容如下:
内容 | 定义位置
-------------- | :----------------------
内容 | 定义位置
-------------- | :----------------------
OpProtoMake定义 |
`.cc`
文件,Backward Op不需要定义OpProtoMake
Op定义 |
`.cc`
文件
Kernel实现 | CPU、GPU共享Kernel在
`.h`
文件,否则,CPU可以在
`.cc`
文件,GPU可在
`.cu`
文件。
注册Op | Op注册在
`.cc`
文件;Kernel注册CPU在
`.cc`
文件,GPU在
`.cu`
文件
Op定义 |
`.cc`
文件
Kernel实现 | CPU、GPU共享Kernel实现在
`.h`
文件中,否则,CPU 实现在
`.cc`
文件中,GPU 实现在
`.cu`
文件中。
注册Op | Op注册实现在
`.cc`
文件;Kernel注册CPU实现在
`.cc`
文件中,GPU实现在
`.cu`
文件中
实现新的op都添加至目录
[
paddle/operators
](
https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/operators
)
下,文件命名以
`*_op.h`
(如有) 、
`*_op.cc`
、
`*_op.cu`
(如有)结尾。
下面以矩阵乘操作,即
[
MulOp
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/mul_op.cc
)
为例来介绍如何写带Kernel的Operator。
...
...
@@ -43,8 +46,8 @@ Kernel实现 | CPU、GPU共享Kernel在`.h`文件,否则,CPU可以在`
### 1. 定义ProtoMaker类
矩阵乘的公式:$Out = X
*
Y$, 可见该计算由两个输入,一个输出组成。首先定义
`ProtoMaker`
来描述该Op的输入、输出及注释:
```
```
cpp
class
MulOpMaker
:
public
framework
::
OpProtoAndCheckerMaker
{
public:
MulOpMaker
(
framework
::
OpProto
*
proto
,
framework
::
OpAttrChecker
*
op_checker
)
...
...
@@ -59,20 +62,20 @@ The equation is: Out = X * Y
}
};
```
[
`MulOpMaker`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/mul_op.cc#L43
)
继承自
`framework::OpProtoAndCheckerMaker`
,构造函数包括2个:
[
`MulOpMaker`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/mul_op.cc#L43
)
继承自
`framework::OpProtoAndCheckerMaker`
,构造函数包括2个
参数
:
-
`framework::OpProto`
: 前者存储Op的输入输出和参数属性,将用于Python API接口的生成。
-
`framework::OpAttrChecker`
:后者用于检查参数属性的合法性。
构造函数里通过
`AddInput`
添加输入参数,通过
`AddOutput`
添加输出参数,通过
`AddComment`
添加该Op的注释,这些函数会将对应内容添加到
`OpProto`
中。
在
`MulOp`
中添加两个输入
`X`
和
`Y`
,添加了一个输出
`Out`
,并解释了各自含义,该命名尽可能的规范。
在
`MulOp`
中添加两个输入
`X`
和
`Y`
,添加了一个输出
`Out`
,并解释了各自含义,命名请遵守命名规范。
再举个
[
`ScaleOp`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/scale_op.cc#L37
)
的例子:
```
```
cpp
template
<
typename
AttrType
>
class
ScaleOpMaker
:
public
framework
::
OpProtoAndCheckerMaker
{
public:
...
...
@@ -87,17 +90,17 @@ The equation is: Out = scale*X
}
};
```
在这个例子里,
两处不同:
这个例子有
两处不同:
-
`AddInput("X","...").NotInGradient()`
: 表示
`X`
这个输入不参与
`ScaleOp`
对应的梯度Op计算之中。
-
`AddAttr<AttrType>("scale", "...").SetDefault(1.0);`
: 增加
`scale`
系数,作为参数属性,并且设置默认值为1.0。
### 2. 定义Operator类
```
c
++
```
c
pp
class
MulOp
:
public
framework
::
OperatorWithKernel
{
public:
using
framework
::
OperatorWithKernel
::
OperatorWithKernel
;
...
...
@@ -121,20 +124,20 @@ class MulOp : public framework::OperatorWithKernel {
```
[
`MulOp`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/mul_op.cc#L22
)
继承自
`OperatorWithKernel`
。
`public`
成员:
```
c
++
```
c
pp
using
framework
::
OperatorWithKernel
::
OperatorWithKernel
;
```
这句表示使用基类
`OperatorWithKernel`
的构造函数,也可写成:
```
c
++
```
c
pp
MulOp
(
const
std
::
string
&
type
,
const
framework
::
VariableNameMap
&
inputs
,
const
framework
::
VariableNameMap
&
outputs
,
const
framework
::
AttributeMap
&
attrs
)
:
OperatorWithKernel
(
type
,
inputs
,
outputs
,
attrs
)
{}
```
```
还需要重写
`InferShape`
接口。
`InferShape`
为const函数,不能修改Op的成员变量,参数为
`const framework::InferShapeContext &ctx`
,通过该参数可获取到输入输出以及属性。它的功能是:
-
1). 做检查, 尽早报错:检查输入数据维度、类型等是否合法。
...
...
@@ -144,7 +147,7 @@ MulOp(const std::string &type, const framework::VariableNameMap &inputs,
### 3. 定义OpKernel类
```
C++
```
cpp
template
<
typename
Place
,
typename
T
>
class
MulKernel
:
public
framework
::
OpKernel
{
public:
...
...
@@ -163,36 +166,36 @@ class MulKernel : public framework::OpKernel {
`MulKernel`
继承自
`framework::OpKernel`
,带有模板参数:
-
`typename Place`
: 表示设备类型,不同设备(CPU、GPU)共享同一个Kernel时,需加该模板参数,不共享则不加,一个不共享的例子是
[
`OnehotCrossEntropyOpKernel`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/cross_entropy_op.h#L43
)
。
-
`typename T`
: 表示数据类型,如
`float`
,
`double`
等。
`MulKernel`
需要重写
`Compute`
接口,该接口参数为
`const framework::ExecutionContext& context`
,
`ExecutionContext`
相比
`InferShapeContext`
增加了设备类型,同样可获取到输入输出和属性参数,
`Compute`
函数里写具体实现时。
注意,不同设备(CPU、GPU)共享一个Op定义,是否则共享同一个
`OpKernel`
,取决于
`Compute`
调用的函数是否支持不同设备。
`MulOp`
的CPU、GPU实现共享同一个
`Kernel`
,
`OpKernel`
不共享的例子可以参考
[
`OnehotCrossEntropyOpKernel`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/cross_entropy_op.h#L43
)
。
为了使得
`OpKernel`
的计算过程书写较为简单,CPU、GPU的代码可以复用,我们通常借助Eigen unsupported Tensor模块来实现。关于在paddle中如何使用Eigen库,请参考对应的使用
[
文档
](
https://github.com/PaddlePaddle/Paddle/blob/develop/doc/howto/dev/use_eigen_cn.md
)
到此前向Op实现完成,需要在
`.cc`
文件中注册该op和kernel。反向Op类的定义和Kernel定义与前向Op类似,这里不再重复。但注意,反向Op没有
`ProtoMaker`
。
### 4. 注册Operator
在
`.cc`
文件中注册前向、反向Op类,注册CPU Kernel。
```
c
++
```
c
pp
namespace
ops
=
paddle
::
operators
;
REGISTER_OP
(
mul
,
ops
::
MulOp
,
ops
::
MulOpMaker
,
mul_grad
,
ops
::
MulOpGrad
);
REGISTER_OP_CPU_KERNEL
(
mul
,
ops
::
MulKernel
<
paddle
::
platform
::
CPUPlace
,
float
>
);
REGISTER_OP_CPU_KERNEL
(
mul_grad
,
ops
::
MulGradKernel
<
paddle
::
platform
::
CPUPlace
,
float
>
);
```
-
`REGISTER_OP`
: 注册
`ops::MulOp`
类,类型名为
`mul`
,该类的
`ProtoMaker`
为
`ops::MulOpMaker`
,注册
`ops::MulOpGrad`
,类型名为
`mul_grad`
,
-
`REGISTER_OP_WITHOUT_GRADIENT`
: 用于注册没有反向的Op。
-
`REGISTER_OP_CPU_KERNEL`
:注册
`ops::MulKernel`
类,并特化模板参数为
`paddle::platform::CPUPlace`
和
`float`
类型,同理,注册
`ops::MulKernel`
类。
在
`.cu`
文件中注册GPU Kernel。请注意,如果GPU Kernel的实现是基于Eigen unsupported模块,那么在
`.cu`
的最前面请加上宏定义
`#define EIGEN_USE_GPU`
```
c
++
```
c
pp
// if use Eigen unsupported module before include head files
#define EIGEN_USE_GPU
...
...
@@ -204,66 +207,57 @@ REGISTER_OP_GPU_KERNEL(mul_grad,
### 5. 编译
在
[
paddle/operators/CMakeLists.txt
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/CMakeLists.txt
)
文件中添加编译。
```
op_library(mul_op SRCS mul_op.cc mul_op.cu DEPS math_function)
```
下面命令可以编译:
```
make mul_op
```
-
简单
**无特殊依赖**
的OP无需修改CMakeList.txt文件。
[
paddle/operators/CMakeLists.txt
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/CMakeLists.txt
)
会自动将
`paddle/operators`
目录下新增的
`*_op.cc`
文件加入编译。
-
较为复杂、
**有额外依赖**
的operator仍需要修改
[
paddle/operators/CMakeLists.txt
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/CMakeLists.txt
)
。如,
`mul_op`
依赖
`math_function`
,需要在
`CMakeLists.txt`
中添加如下内容:
```
op_library(mul_op SRCS mul_op.cc mul_op.cu DEPS math_function) +
```
-
运行下面命令可以进行编译:
```
make mul_op
```
## 绑定Python
-
绑定Python
在
[
`paddle/pybind/pybind.cc
-
绑定Python
在 [`paddle/pybind/pybind.cc
`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/pybind/pybind.cc)文件中添加该类:
```
USE_OP(mul);
```
如果只实现了CPU版本,则使用`
USE_CPU_ONLY_OP
`:
```
USE_CPU_ONLY_OP(gather);
```
如果OP不带Kernel,则使用`
USE_NO_KENREL_OP
`:
```
USE_NO_KENREL_OP(recurrent);
```
使用`
USE_OP
`告知编译器需要链接该Op的目标文件,具体解释参考[代码注释](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/framework/op_registry.h#L81)。
- 生成库
在
[
`paddle/pybind/CMakeLists.txt`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/pybind/CMakeLists.txt
)
文件添加类到
`DEPS`
中,使得该Op可以链接到生成的lib库中。
```
if(WITH_PYTHON)
cc_library(paddle_pybind SHARED
SRCS pybind.cc
DEPS pybind python backward
mul_op
minus_op)
endif(WITH_PYTHON)
```
无需修改 [`
paddle/pybind/CMakeLists.txt
`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/pybind/CMakeLists.txt)文件,`
paddle/operators
` 目录下新增的 `
*
_op.cc
` 文件会自动被添加链接到生成的lib库中。
## 实现单元测试
单测包括对比前向Op不同设备(CPU、GPU)的实现、对比反向OP不同设备(CPU、GPU)的实现、反向Op的梯度测试。下面介绍介绍[`
MulOp
`的单测](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/v2/framework/tests/test_mul_op.py)。
### 前向Operator单
测
### 前向Operator单
元测试
前向Op单测继承自`
unittest.TestCase
`,并定义元类`
__metaclass__
= OpTestMeta
`,具体单测流程在`
OpTestMeta
`里完成。需在`
setUp
`函数定义输入输出和属性参数,以及Python对比的输出值。
```
```
python
import unittest
import numpy as np
from gradient_checker import GradientChecker, create_op
...
...
@@ -281,17 +275,17 @@ class TestMulOp(unittest.TestCase):
self.outputs = {'Out': np.dot(self.inputs['X'], self.inputs['Y'])}
```
首先需要`
import
`必要的包,下面详细解释其他值:
- `
self.type = "mul"
` : 定义类型,和注册的类型一致。
- `
self.inputs
` : 定义输入,类型为Numpy.array,并初始化。
- `
self.outputs
` : 定义输出,并得到Python结算结果。
### 反向Operator单
测
### 反向Operator单
元测试
反向Op单测继承自`
GradientChecker
`,而`
GradientChecker
`集成自`
unittest.TestCase
`,所以反向单测函数需要`
test_
`开头。
```
```
cpp
class TestMulGradOp(GradientChecker):
def setUp(self):
self.op = create_op("mul")
...
...
@@ -337,21 +331,22 @@ class TestMulGradOp(GradientChecker):
- `
test_ignore_x
`和`
test_ignore_y
`分支测试只需要计算一个输入梯度的情况。
### 编译和执行
### 编译和执行
单元测试
单测完成之后,在
[
`python/paddle/v2/framework/tests/CMakeLists.txt`
](
https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/v2/framework/tests/CMakeLists.txt
)
里添加
编译
:
单测完成之后,在[`
python/paddle/v2/framework/tests/CMakeLists.txt
`](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/v2/framework/tests/CMakeLists.txt)里添加
以下内容将单测加入工程中
:
```
py_test(test_mul_op SRCS test_mul_op.py)
```
编译时需要打开
`WITH_TESTING`
, 即
`cmake paddle_dir -DWITH_TESTING=ON`
,编译成功之后执行单测命令为
:
请注意,**不同于Op的编译测试,运行单元测试测时需要编译整个工程**,并且编译时需要打开`
WITH_TESTING
`, 即`
cmake paddle_dir -DWITH_TESTING=ON
`。编译成功后,执行下面的命令来运行单测
:
```
```
bash
make test ARGS="-R test_mul_op -V"
```
或者:
```
```
bash
ctest -R test_mul_op
``
`
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录