new_op_cn.md 12.8 KB
Newer Older
1 2 3 4 5 6
# 如何写新的Operator

 - [概念简介](#概念简介)
 - [实现C++类](#实现C++类)
   - [定义ProtoMaker类](#定义ProtoMaker类)
   - [定义Operator类](#定义Operator类)
Q
qingqing01 已提交
7
   - [定义OpKernel类](#定义OpKernel类)
8
   - [注册Operator](#注册Operator)
9 10 11
   - [编译](#编译)
 - [绑定Python](#绑定Python)
 - [实现单元测试](#实现单元测试)
Q
qingqing01 已提交
12 13
   - [前向Operator单测](#前向Operator单测)
   - [反向Operator单测](#反向Operator单测)
14
   - [编译和执行](#编译和执行)
15 16 17 18 19 20 21 22 23 24 25


## 概念简介

简单介绍需要用到基类,详细介绍请参考设计文档。

- `framework::OperatorBase`: Operator(简写,Op)基类。
- `framework::OpKernel`: Op计算函数的基类,称作Kernel。
- `framework::OperatorWithKernel`:继承自OperatorBase,Op有计算函数,称作有Kernel。
- `class OpProtoAndCheckerMaker`:描述该Op的输入、输出、属性、注释,主要用于Python API接口生成

26
依据是否包含kernel,将Op分为两种:包含Kernel的Op和不包含kernel的Op,前者Op的定义继承自`OperatorBase`,后者继承自`OperatorWithKernel`。本教程主要介绍带Kernel的Op如何写,简单总结Op需要包含的内容如下:
27

28 29 30 31 32 33 34 35
  
 内容            | 定义位置         
--------------  | :----------------------  
OpProtoMake定义  | `.cc`文件,Backward Op不需要定义OpProtoMake
Op定义           | `.cc`文件 
Kernel实现       | CPU、GPU共享Kernel在`.h`文件,否则,CPU可以在`.cc`文件,GPU可在`.cu`文件。 
注册Op           | Op注册在`.cc`文件;Kernel注册CPU在`.cc`文件,GPU在`.cu`文件
     
36 37 38 39 40 41 42 43 44
     
下面以矩阵乘操作,即[MulOp](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/mul_op.cc)为例来介绍如何写带Kernel的Operator。


## 实现C++类


### 1. 定义ProtoMaker类

Q
qingqing01 已提交
45
矩阵乘的公式:$Out = X * Y$, 可见该计算由两个输入,一个输出组成。首先定义`ProtoMaker`来描述该Op的输入、输出及注释:
46
    
Q
qingqing01 已提交
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
```
class MulOpMaker : public framework::OpProtoAndCheckerMaker {
 public:
  MulOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker)
      : OpProtoAndCheckerMaker(proto, op_checker) {
    AddInput("X", "The first input of mul op");
    AddInput("Y", "The second input of mul op");
    AddOutput("Out", "The output of mul op");
    AddComment(R"DOC(
Two Element Mul Operator.
The equation is: Out = X * Y
)DOC");
  }
};
```
62 63 64 65 66 67 68 69 70 71 72 73 74
   
[`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`,并解释了各自含义,该命名尽可能的规范。

   
再举个[`ScaleOp`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/scale_op.cc#L37)的例子:
   
Q
qingqing01 已提交
75 76
```
template <typename AttrType>
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
class ScaleOpMaker : public framework::OpProtoAndCheckerMaker {
 public:
  ScaleOpMaker(framework::OpProto *proto, framework::OpAttrChecker *op_checker)
      : OpProtoAndCheckerMaker(proto, op_checker) {
    AddInput("X", "The input tensor of scale operator.").NotInGradient();
    AddOutput("Out", "The output tensor of scale operator.").NotInGradient();
    AddComment(R"DOC(Scale operator
The equation is: Out = scale*X
)DOC");
    AddAttr<AttrType>("scale", "scale of scale operator.").SetDefault(1.0);
  }
};
```
 
 在这个例子里,两处不同:
 
  - `AddInput("X","...").NotInGradient()` : 表示`X`这个输入不参与`ScaleOp`对应的梯度Op计算之中。
  - `AddAttr<AttrType>("scale", "...").SetDefault(1.0);` : 增加`scale`系数,作为参数属性,并且设置默认值为1.0。
   

### 2. 定义Operator类


Q
qingqing01 已提交
100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
```c++
class MulOp : public framework::OperatorWithKernel {
 public:
  using framework::OperatorWithKernel::OperatorWithKernel;

 protected:
  void InferShape(const framework::InferShapeContext &ctx) const override {
    auto dim0 = ctx.Input<Tensor>("X")->dims();
    auto dim1 = ctx.Input<Tensor>("Y")->dims();
    PADDLE_ENFORCE_EQ(dim0.size(), 2,
                      "input X(%s) should be a tensor with 2 dims, a matrix",
                      ctx.op_.Input("X"));
    PADDLE_ENFORCE_EQ(dim1.size(), 2,
                      "input Y(%s) should be a tensor with 2 dims, a matrix",
                      ctx.op_.Input("Y"));
    PADDLE_ENFORCE_EQ(
        dim0[1], dim1[0],
        "First matrix's width must be equal with second matrix's height.");
    ctx.Output<Tensor>("Out")->Resize({dim0[0], dim1[1]});
  }
};
```
122 123 124

[`MulOp`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/mul_op.cc#L22)继承自`OperatorWithKernel``public`成员:
	 
Q
qingqing01 已提交
125
```c++
126 127 128 129 130
using framework::OperatorWithKernel::OperatorWithKernel;
```

这句表示使用基类`OperatorWithKernel`的构造函数,也可写成:
   
Q
qingqing01 已提交
131 132 133 134 135
```c++
MulOp(const std::string &type, const framework::VariableNameMap &inputs,
      const framework::VariableNameMap &outputs,
      const framework::AttributeMap &attrs)
  : OperatorWithKernel(type, inputs, outputs, attrs) {}
136 137 138
```	
	
还需要重写`InferShape`接口。`InferShape`为const函数,不能修改Op的成员变量,参数为`const framework::InferShapeContext &ctx`,通过该参数可获取到输入输出以及属性。它的功能是:
139 140 141

  - 1). 做检查, 尽早报错:检查输入数据维度、类型等是否合法。
  - 2). 设置输出Tensor的形状。
142 143 144

通常`OpProtoMaker``Op`类的定义写在`.cc`文件中,和要讲到的注册函数一起放在`.cc`

Q
qingqing01 已提交
145
### 3. 定义OpKernel类
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174

```C++
template <typename Place, typename T>
class MulKernel : public framework::OpKernel {
 public:
  void Compute(const framework::ExecutionContext& context) const override {
    auto* X = context.Input<Tensor>("X");
    auto* Y = context.Input<Tensor>("Y");
    auto* Z = context.Output<Tensor>("Out");
    Z->mutable_data<T>(context.GetPlace());
    auto* device_context =
        const_cast<platform::DeviceContext*>(context.device_context_);
    math::matmul<Place, T>(*X, false, *Y, false, 1, Z, 0, device_context);
  }
};
```

`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)
   
到此前向Op实现完成,需要在`.cc`文件中注册该op和kernel。反向Op类的定义和Kernel定义与前向Op类似,这里不再重复。但注意,反向Op没有`ProtoMaker`
   
175
### 4. 注册Operator
176 177 178

`.cc`文件中注册前向、反向Op类,注册CPU Kernel。

Q
qingqing01 已提交
179 180
```c++
namespace ops = paddle::operators;
F
fengjiayi 已提交
181
REGISTER_OP(mul, ops::MulOp, ops::MulOpMaker, ops::MulOpGrad);
Q
qingqing01 已提交
182 183 184 185
REGISTER_OP_CPU_KERNEL(mul, ops::MulKernel<paddle::platform::CPUPlace, float>);
REGISTER_OP_CPU_KERNEL(mul_grad,
              ops::MulGradKernel<paddle::platform::CPUPlace, float>);
```
186
    
F
fengjiayi 已提交
187
  - `REGISTER_OP` : 注册`ops::MulOp`类,类型名为`mul`,该类的`ProtoMaker``ops::MulOpMaker`,并且注册`ops::MulOpGrad`为其反向Op。
188 189 190 191 192
  - `REGISTER_OP_WITHOUT_GRADIENT` : 用于注册没有反向的Op。
  - `REGISTER_OP_CPU_KERNEL` :注册`ops::MulKernel`类,并特化模板参数为`paddle::platform::CPUPlace``float`类型,同理,注册`ops::MulKernel`类。

`.cu`文件中注册GPU Kernel。
   
Q
qingqing01 已提交
193 194 195 196 197 198
```c++
namespace ops = paddle::operators;
REGISTER_OP_GPU_KERNEL(mul, ops::MulKernel<paddle::platform::GPUPlace, float>);
REGISTER_OP_GPU_KERNEL(mul_grad,
                       ops::MulGradKernel<paddle::platform::GPUPlace, float>);
```
199 200 201 202 203

### 5. 编译

[paddle/operators/CMakeLists.txt](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/operators/CMakeLists.txt)文件中添加编译。
   
Q
qingqing01 已提交
204 205 206
```
op_library(mul_op SRCS mul_op.cc mul_op.cu DEPS math_function)
```
207 208 209
   
下面命令可以编译:
   
Q
qingqing01 已提交
210 211 212
```
make mul_op
```
213 214 215

## 绑定Python

Q
qingqing01 已提交
216
- 绑定Python 
217
 
Q
qingqing01 已提交
218
[`paddle/pybind/pybind.cc 
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/pybind/pybind.cc)文件中添加该类:

    ```
    USE_OP(mul);
    ```
    如果只实现了CPU版本,则使用`USE_CPU_ONLY_OP`:
    
    ```
    USE_CPU_ONLY_OP(gather);
    ```
    
    使用`USE_OP`告知编译器需要链接该Op的目标文件,具体解释参考[代码注释](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/framework/op_registry.h#L81)。
    
    
 - 生成库

Q
qingqing01 已提交
235
[`paddle/pybind/CMakeLists.txt`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/pybind/CMakeLists.txt)文件添加类到`DEPS`中,使得该Op可以链接到生成的lib库中。
236 237 238
   
   ```
   if(WITH_PYTHON)
Q
qingqing01 已提交
239 240 241 242 243 244
     cc_library(paddle_pybind SHARED
     SRCS pybind.cc
     DEPS pybind python backward
     mul_op
     minus_op)
   endif(WITH_PYTHON)
245 246 247 248 249 250
   ```

## 实现单元测试

单测包括对比前向Op不同设备(CPU、GPU)的实现、对比反向OP不同设备(CPU、GPU)的实现、反向Op的梯度测试。下面介绍介绍[`MulOp`的单测](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/v2/framework/tests/test_mul_op.py)

Q
qingqing01 已提交
251
### 前向Operator单测
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278

前向Op单测继承自`unittest.TestCase`,并定义元类`__metaclass__ = OpTestMeta`,具体单测流程在`OpTestMeta`里完成。需在`setUp`函数定义输入输出和属性参数,以及Python对比的输出值。

```
import unittest
import numpy as np
from gradient_checker import GradientChecker, create_op
from op_test_util import OpTestMeta

class TestMulOp(unittest.TestCase):
    __metaclass__ = OpTestMeta

    def setUp(self):
        self.type = "mul"
        self.inputs = {
            'X': np.random.random((32, 84)).astype("float32"),
            'Y': np.random.random((84, 100)).astype("float32")
        }
        self.outputs = {'Out': np.dot(self.inputs['X'], self.inputs['Y'])}
```
   首先需要`import`必要的包,下面详细解释其他值:
   
   - `self.type = "mul" ` : 定义类型,和注册的类型一致。
   - `self.inputs` : 定义输入,类型为Numpy.array,并初始化。
   - `self.outputs` : 定义输出,并得到Python结算结果。

 
Q
qingqing01 已提交
279
### 反向Operator单测
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299

反向Op单测继承自`GradientChecker`,而`GradientChecker`集成自`unittest.TestCase`,所以反向单测函数需要`test_`开头。

 ```
 class MulGradOpTest(GradientChecker):
    def test_mul(self):
        op = create_op("mul")
        inputs = {
            'X': np.random.random((32, 84)).astype("float32"),
            'Y': np.random.random((84, 100)).astype("float32")
        }
        self.compare_grad(op, inputs)      
        # mul op will enlarge the relative error
        self.check_grad(
            op, inputs, set(["X", "Y"]), "Out", max_relative_error=0.5)
 ```

   - 调用`create_op("mul")`创建反向Op对应的前向Op。
   - 定义输入`inputs`
   - 调用`compare_grad`函数对比CPU、GPU计算结果。
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
   - 调用`check_grad`检查梯度稳定性,这里采用数值法检测梯度正确性。
      - 第一个参数`op` : 前向op。
      - 第二个参数`inputs` : 输入词典,词典的Key和`ProtoMaker`定义保持一致。
      - 第三个参数`set(["X", "Y"])` : 指定对输入变量`X``Y`做梯度检测。
      - 第四个参数`"Out"` : 指定前向网络最终的输出目标变量`Out`


### 编译和执行 

单测完成之后,在[`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)
```

315
编译时需要打开`WITH_TESTING`, 即 `cmake paddle_dir -DWITH_TESTING=ON`,编译成功之后执行单测命令为:
316 317 318 319 320 321 322 323 324

```
make test ARGS="-R test_mul_op -V"
```
或者:

```
ctest -R test_mul_op
```