如何写新的C++ OP

概念简介

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

  • framework::OperatorBase: Operator(简写,Op)基类。

  • framework::OpKernel: Op计算函数的基类,称作Kernel。

  • framework::OperatorWithKernel:继承自OperatorBase,Op有计算函数,称作有Kernel。

  • framework::OpProtoAndCheckerMaker:描述该Op的输入、输出、属性、注释,主要用于Python API接口生成。

根据是否包含Kernel,可以将Op分为两种:包含Kernel的Op和不包含kernel的Op:

  • 包含Kernel的Op继承自OperatorWithKernel,这类Op的功能实现与输入的数据类型、数据布局、数据所在的设备以及Op实现所调用第三方库等有关。比如ConvOp,如果使用CPU计算,一般通过调用mkl库中的矩阵乘操作实现,如果使用GPU计算,一般通过调用cublas库中的矩阵乘操作实现,或者直接调用cudnn库中的卷积操作。

  • 不包含Kernel的Op继承自OperatorBase,因为这类Op的功能实现与设备以及输入的数据不相关。比如WhileOp、IfElseOp等。

本教程主要介绍带Kernel的Op如何写,简单总结Op需要包含的内容如下:

内容定义位置
OpProtoMake定义.cc 文件
Op定义.cc 文件
Kernel实现CPU、CUDA共享Kernel实现在.h 文件中,否则,CPU 实现在.cc 文件中,CUDA 实现在.cu 文件中。
注册OpOp注册实现在.cc 文件;Kernel注册CPU实现在.cc 文件中,CUDA实现在.cu 文件中

实现新的op都添加至目录paddle/fluid/operators下,文件命名以*_op.h(如有)、*_op.cc*_op.cu(如有)结尾。系统会根据文件名自动构建op和其对应的Python扩展。

下面以矩阵乘操作,即MulOp为例来介绍如何写带Kernel的Operator。

实现C++类

定义ProtoMaker类

矩阵乘法的公式:Out\=X∗YOut\=X∗Y, 可见该计算由两个输入,一个输出组成。

首先定义ProtoMaker来描述该Op的输入、输出,并添加注释:

  1. class MulOpMaker : public framework::OpProtoAndCheckerMaker {
  2. public:
  3. void Make() override {
  4. AddInput("X", "(Tensor), The first input tensor of mul op.");
  5. AddInput("Y", "(Tensor), The second input tensor of mul op.");
  6. AddOutput("Out", "(Tensor), The output tensor of mul op.");
  7. AddAttr<bool>("use_mkldnn",
  8. "(bool, default false) Only used in mkldnn kernel")
  9. .SetDefault(false);
  10. AddAttr<int>(
  11. "x_num_col_dims",
  12. R"DOC((int, default 1), The mul_op can take tensors with more than two
  13. dimensions as its inputs. If the input $X$ is a tensor with more
  14. than two dimensions, $X$ will be flattened into a two-dimensional
  15. matrix first. The flattening rule is: the first `num_col_dims`
  16. will be flattened to form the first dimension of the final matrix
  17. (the height of the matrix), and the rest `rank(X) - num_col_dims`
  18. dimensions are flattened to form the second dimension of the final
  19. matrix (the width of the matrix). As a result, height of the
  20. flattened matrix is equal to the product of $X$'s first
  21. `x_num_col_dims` dimensions' sizes, and width of the flattened
  22. matrix is equal to the product of $X$'s last `rank(x) - num_col_dims`
  23. dimensions' size. For example, suppose $X$ is a 6-dimensional
  24. tensor with the shape [2, 3, 4, 5, 6], and `x_num_col_dims` = 3.
  25. Thus, the flattened matrix will have a shape [2 x 3 x 4, 5 x 6] =
  26. [24, 30].
  27. )DOC")
  28. .SetDefault(1)
  29. .EqualGreaterThan(1);
  30. AddAttr<int>(
  31. "y_num_col_dims",
  32. R"DOC((int, default 1), The mul_op can take tensors with more than two,
  33. dimensions as its inputs. If the input $Y$ is a tensor with more
  34. than two dimensions, $Y$ will be flattened into a two-dimensional
  35. matrix first. The attribute `y_num_col_dims` determines how $Y$ is
  36. flattened. See comments of `x_num_col_dims` for more details.
  37. )DOC")
  38. .SetDefault(1)
  39. .EqualGreaterThan(1);
  40. AddAttr<float>(
  41. "scale_x",
  42. "scale_x to be used for int8 mul input data x. scale_x has the"
  43. "same purpose as scale_in in OPs that support quantization."
  44. "Only to be used with MKL-DNN INT8")
  45. .SetDefault(1.0f);
  46. AddAttr<std::vector<float>>(
  47. "scale_y",
  48. "scale_y to be used for int8 mul input data y. scale_y has the"
  49. "same purpose as scale_weights in OPs that support quantization."
  50. "Only to be used with MKL-DNN INT8")
  51. .SetDefault({1.0f});
  52. AddAttr<float>("scale_out",
  53. "scale_out to be used for int8 output data."
  54. "Only used with MKL-DNN INT8")
  55. .SetDefault(1.0f);
  56. AddAttr<bool>(
  57. "force_fp32_output",
  58. "(bool, default false) Force quantize kernel output FP32, only "
  59. "used in quantized MKL-DNN.")
  60. .SetDefault(false);
  61. AddComment(R"DOC(
  62. Mul Operator.
  63. This operator is used to perform matrix multiplication for input $X$ and $Y$.
  64. The equation is:
  65. $$Out = X * Y$$
  66. Both the input $X$ and $Y$ can carry the LoD (Level of Details) information,
  67. or not. But the output only shares the LoD information with input $X$.
  68. )DOC");
  69. }
  70. };

MulOpMaker继承自framework::OpProtoAndCheckerMaker

开发者通过覆盖framework::OpProtoAndCheckerMaker中的Make函数来定义Op所对应的Proto,通过AddInput添加输入参数,通过AddOutput添加输出参数,通过AddAttr添加属性参数,通过AddComment添加Op的注释。这些函数会将对应内容添加到OpProto中。

上面的代码在MulOp中添加两个输入XY,添加了一个输出Out,以及use_mkldnn等属性,并解释了各自含义,命名请遵守命名规范

定义GradOpMaker类

通常情况下,大部分Op只有一个对应的反向Op,每个Op的会有一个对应的GradOpMaker。为方便代码编写,paddle为只有一个反向的Op提供了一个模板类SingleGradOpMakerMulOpGradOpMaker需要继承这个模板类,并在Apply()方法中设置反向Op的输入、输出和属性。此外,paddle还提供了一个默认的GradOpMakerDefaultGradOpMaker,该模板类会使用前向Op的全部输入(Input)输出(Output)以及输出变量所对应的梯度(Output@Grad)作为反向Op的输入,将前向Op的输入变量所对应的的梯度(Input@Grad)作为输出。

注意: 不要将反向Op不会用到的变量放到反向Op的输入列表中,这样会导致这些不会被反向Op用到的变量的空间不能够及时回收,进而有可能导致用到该Op的模型可以设置的batch_size较低。 比如relu操作的前向操作为:out.device(d) = x.cwiseMax(static_cast<T>(0));反向操作为:dx.device(d) = dout * (out > static_cast<T>(0)).template cast<T>();。显然,反向操作中只是用到了outdoutdx,没有用到x。因此,通常不建议使用默认的DefaultGradOpMaker

下面示例定义了MulOpGradOpMaker

  1. template <typename T>
  2. class MulOpGradMaker : public framework::SingleGradOpMaker<T> {
  3. public:
  4. using framework::SingleGradOpMaker<T>::SingleGradOpMaker;
  5. protected:
  6. void Apply(GradOpPtr<T> retv) const override {
  7. retv->SetType("mul_grad");
  8. retv->SetInput("X", this->Input("X"));
  9. retv->SetInput("Y", this->Input("Y"));
  10. retv->SetInput(framework::GradVarName("Out"), this->OutputGrad("Out"));
  11. retv->SetOutput(framework::GradVarName("X"), this->InputGrad("X"));
  12. retv->SetOutput(framework::GradVarName("Y"), this->InputGrad("Y"));
  13. retv->SetAttrMap(this->Attrs());
  14. }
  15. };

注意:

  • 有些Op的前向逻辑和反向逻辑是一样的,比如ScaleOp.这种情况下,前向Op和反向Op的Kernel可以为同一个。

  • 有些前向Op所对应的反向Op可能有多个,比如SumOp,这种情况下,GradMaker需要继承framework::GradOpDescMakerBase

  • 有些Op的反向对应另一个Op的前向,比如SplitOp,这种情况下,SplitGradMaker中定义的SplitOp反向Op的Type就是concat

  • 为高效地同时支持命令式编程模式(动态图)和声明式编程模式(静态图),SingleGradOpMaker是一个模板类,在注册Operator时需要同时注册MulOpGradMaker<OpDesc>(声明式编程模式使用)和MulOpGradMaker<OpBase>(命令式编程模式使用)。

定义Operator类

下面实现了MulOp的定义:

  1. class MulOp : public framework::OperatorWithKernel {
  2. public:
  3. using framework::OperatorWithKernel::OperatorWithKernel;
  4. void InferShape(framework::InferShapeContext* ctx) const override {
  5. PADDLE_ENFORCE_EQ(
  6. ctx->HasInput("X"), true,
  7. platform::errors::NotFound("Input(X) of MulOp should not be null."));
  8. PADDLE_ENFORCE_EQ(
  9. ctx->HasInput("Y"), true,
  10. platform::errors::NotFound("Input(Y) of MulOp should not be null."));
  11. PADDLE_ENFORCE_EQ(
  12. ctx->HasOutput("Out"), true,
  13. platform::errors::NotFound("Output(Out) of MulOp should not be null."));
  14. auto x_dims = ctx->GetInputDim("X");
  15. auto y_dims = ctx->GetInputDim("Y");
  16. int x_num_col_dims = ctx->Attrs().Get<int>("x_num_col_dims");
  17. int y_num_col_dims = ctx->Attrs().Get<int>("y_num_col_dims");
  18. VLOG(3) << "mul operator x.shape=" << x_dims << " y.shape=" << y_dims
  19. << " x_num_col_dims=" << x_num_col_dims
  20. << " y_num_col_dims=" << y_num_col_dims;
  21. PADDLE_ENFORCE_NE(framework::product(y_dims), 0,
  22. platform::errors::PreconditionNotMet(
  23. "The Input variable Y(%s) has not "
  24. "been initialized. You may need to confirm "
  25. "if you put exe.run(startup_program) "
  26. "after optimizer.minimize function.",
  27. ctx->Inputs("Y").front()));
  28. PADDLE_ENFORCE_GT(
  29. x_dims.size(), x_num_col_dims,
  30. platform::errors::InvalidArgument(
  31. "The input tensor X's dimensions of MulOp "
  32. "should be larger than x_num_col_dims. But received X's "
  33. "dimensions = %d, X's shape = [%s], x_num_col_dims = %d.",
  34. x_dims.size(), x_dims, x_num_col_dims));
  35. PADDLE_ENFORCE_GT(
  36. y_dims.size(), y_num_col_dims,
  37. platform::errors::InvalidArgument(
  38. "The input tensor Y's dimensions of MulOp "
  39. "should be larger than y_num_col_dims. But received Y's "
  40. "dimensions = %d, Y's shape = [%s], y_num_col_dims = %d.",
  41. y_dims.size(), y_dims, y_num_col_dims));
  42. auto x_mat_dims = framework::flatten_to_2d(x_dims, x_num_col_dims);
  43. auto y_mat_dims = framework::flatten_to_2d(y_dims, y_num_col_dims);
  44. PADDLE_ENFORCE_EQ(
  45. x_mat_dims[1], y_mat_dims[0],
  46. platform::errors::InvalidArgument(
  47. "After flatten the input tensor X and Y to 2-D dimensions "
  48. "matrix X1 and Y1, the matrix X1's width must be equal with matrix "
  49. "Y1's height. But received X's shape = [%s], X1's shape = [%s], "
  50. "X1's "
  51. "width = %s; Y's shape = [%s], Y1's shape = [%s], Y1's height = "
  52. "%s.",
  53. x_dims, x_mat_dims, x_mat_dims[1], y_dims, y_mat_dims,
  54. y_mat_dims[0]));
  55. std::vector<int64_t> output_dims;
  56. output_dims.reserve(
  57. static_cast<size_t>(x_num_col_dims + y_dims.size() - y_num_col_dims));
  58. for (int i = 0; i < x_num_col_dims; ++i) {
  59. output_dims.push_back(x_dims[i]);
  60. }
  61. for (int i = y_num_col_dims; i < y_dims.size(); ++i) {
  62. output_dims.push_back(y_dims[i]);
  63. }
  64. ctx->SetOutputDim("Out", framework::make_ddim(output_dims));
  65. ctx->ShareLoD("X", /*->*/ "Out");
  66. }
  67. framework::OpKernelType GetExpectedKernelType(
  68. const framework::ExecutionContext& ctx) const {
  69. framework::LibraryType library = framework::LibraryType::kPlain;
  70. framework::DataLayout layout = framework::DataLayout::kAnyLayout;
  71. int customized_type_value =
  72. framework::OpKernelType::kDefaultCustomizedTypeValue;
  73. auto input_data_type = OperatorWithKernel::IndicateVarDataType(ctx, "X");
  74. #ifdef PADDLE_WITH_MKLDNN
  75. if (library == framework::LibraryType::kPlain &&
  76. platform::CanMKLDNNBeUsed(ctx)) {
  77. library = framework::LibraryType::kMKLDNN;
  78. layout = framework::DataLayout::kMKLDNN;
  79. if (input_data_type == framework::DataTypeTrait<int8_t>::DataType() ||
  80. input_data_type == framework::DataTypeTrait<uint8_t>::DataType()) {
  81. customized_type_value = kMULMKLDNNINT8;
  82. }
  83. }
  84. #endif
  85. return framework::OpKernelType(input_data_type, ctx.GetPlace(), layout,
  86. library, customized_type_value);
  87. }
  88. };

MulOp继承自OperatorWithKernelpublic成员:

  1. using framework::OperatorWithKernel::OperatorWithKernel;

这句表示使用基类OperatorWithKernel的构造函数,也可写成:

  1. MulOp(const std::string &type, const framework::VariableNameMap &inputs,
  2. const framework::VariableNameMap &outputs,
  3. const framework::AttributeMap &attrs)
  4. : OperatorWithKernel(type, inputs, outputs, attrs) {}

此外,Operator类通常需要重写InferShape接口,并在有必要时重写GetExpectedKernelType接口。InferShape为const函数,不能修改Op的成员变量,参数为framework::InferShapeContext* ctx,通过该参数可获取到输入输出以及属性。它的功能是:

  • 做检查, 尽早报错:检查输入数据维度、类型等是否合法。

  • 设置输出Tensor的形状以及LoD信息。

GetExpectedKernelType接口OperatorWithKernel类中用于获取指定设备(例如CPU,GPU)上指定数据类型(例如double,float)的OpKernel的方法。该方法的重写可见请参考写C++ OP相关注意事项

通常OpProtoMakerOp类的定义写在.cc文件中,和下面将要介绍的注册函数一起放在.cc

InferShape区分 compile time 和 run time

在我们的声明式编程模式网络中,InferShape操作在编译时(compile time)和运行时(run time)都会被调用,在compile time时,由于真实的维度未知,框架内部用-1来表示,在run time时,用实际的维度表示,因此维度的值在compile time和 run time时可能不一致,如果存在维度的判断和运算操作,InferShape就需要区分compile time 和 run time。

以下两种情况需要区分compile time和 run time。

1.检查

如以下代码:

  1. auto x_dim = ctx->GetInputDim("X");
  2. int i = xxx;
  3. PADDLE_ENFORCE_GT( x_dim[i] , 10)

在compile time的时候,x_dim[i]可能等于-1,导致这个PADDLE_ENFORCE_GT报错退出。

如果用了以下paddle中定义的宏进行判断:

  1. PADDLE_ENFORCE_EQ ( x_dim[i] , 10)
  2. PADDLE_ENFORCE_NE ( x_dim[i] , 10)
  3. PADDLE_ENFORCE_GT ( x_dim[i] , 10)
  4. PADDLE_ENFORCE_GE ( x_dim[i] , 10)
  5. PADDLE_ENFORCE_LT ( x_dim[i] , 10)
  6. PADDLE_ENFORCE_LE ( x_dim[i] , 10)

都需要区分compile time和run time

2. 运算

如以下代码:

  1. auto x_dim = ctx->GetInputDim("X");
  2. int i = xxx;
  3. y_dim[0] = x_dim[i] + 10

在compile time的时候,x_dim[i]可能等于-1,得到的 y_dim[0] 等于 9,是不符合逻辑的

如果用到了类似以下的运算操作

  1. y_dim[i] = x_dim[i] + 10
  2. y_dim[i] = x_dim[i] - 10
  3. y_dim[i] = x_dim[i] * 10
  4. y_dim[i] = x_dim[i] / 10
  5. y_dim[i] = x_dim[i] + z_dim[i]

都需要区分compile time和run time

处理的标准

  • 检查: compile time的时候不判断维度等于-1的情况,但在runtime的时候检查

  • 运算: -1和其他数做任何运算都要等于-1

参考代码

  1. 判断的实现方法可以参考cross_entropy_op,cross_entropy_op 要求X和labels的两个输入,除了最后一维以外,其他的维度完全一致
  1. bool contain_unknown_dim = framework::contain_unknown_dim(x_dims) ||
  2. framework::contain_unknown_dim(label_dims);
  3. bool check = ctx->IsRuntime() || !contain_unknown_dim;
  4. if (check) {
  5. PADDLE_ENFORCE_EQ(framework::slice_ddim(x_dims, 0, rank - 1),
  6. framework::slice_ddim(label_dims, 0, rank - 1),
  7. "Input(X) and Input(Label) shall have the same shape "
  8. "except the last dimension.");
  9. }
  1. 运算的实现可以参考concat_op,concat在InferShape判断时,调用ComputeAndCheckShape,除了进行concat轴之外,其他的维度完全一致;在生成output的维度时,把concat轴的维度求和,其他的维度和输入保持一致。
  1. const size_t n = inputs_dims.size();
  2. auto out_dims = inputs_dims[0];
  3. size_t in_zero_dims_size = out_dims.size();
  4. for (size_t i = 1; i < n; i++) {
  5. for (size_t j = 0; j < in_zero_dims_size; j++) {
  6. if (j == axis) {
  7. if (is_runtime) {
  8. out_dims[axis] += inputs_dims[i][j];
  9. } else {
  10. if (inputs_dims[i][j] == -1) {
  11. out_dims[axis] = -1;
  12. } else {
  13. out_dims[axis] += inputs_dims[i][j];
  14. }
  15. }
  16. } else {
  17. bool check_shape =
  18. is_runtime || (out_dims[j] > 0 && inputs_dims[i][j] > 0);
  19. if (check_shape) {
  20. // check all shape in run time
  21. PADDLE_ENFORCE_EQ(
  22. inputs_dims[0][j], inputs_dims[i][j],
  23. "ShapeError: Dimension %d in inputs' shapes must be equal. "
  24. "But recevied input[0]'s shape = "
  25. "[%s], input[%d]'s shape = [%s].",
  26. j, inputs_dims[0], i, inputs_dims[i]);
  27. }
  28. }
  29. }
  30. }

定义OpKernel类

MulKernel继承自framework::OpKernel,带有下面两个模板参数:

  • typename DeviceContext: 表示设备类型。不同设备(CPU、CUDA)共享同一个Kernel时,需加该模板参数;不共享则不加,一个不共享的例子是SGDOpKernel

  • typename T : 表示数据类型,如float, double, int16等。

需要为MulKernel类重写Compute接口。

  • Compute接受一个输入参数:const framework::ExecutionContext& context

  • InferShapeContext相比,ExecutionContext增加了设备类型,同样可获取到输入输出和属性参数。

  • Compute函数里实现OpKernel的具体计算逻辑。

Op的输入和输出可分别通过ExecutionContext::Input<T>()ExecutionContext::Output<T>()获得。

注意: 若op的输入/输出的变量类型是LoDTensor(paddle默认所有的Tensor默认都是LoDTensor类型),请写成ExecutionContext::Input<LoDTensor>()ExecutionContext::Output<LoDTensor>(),不要写ExecutionContext::Input<Tensor>()ExecutionContext::Output<Tensor>()。因为若实际的变量类型为SelectedRowsInput<Tensor>()Output<Tensor>()方法会将SelectedRows类型特化为Tensor,导致潜在的错误。

下面是 MulKernel Compute的实现:

  1. template <typename DeviceContext, typename T>
  2. class MulKernel : public framework::OpKernel<T> {
  3. public:
  4. void Compute(const framework::ExecutionContext& context) const override {
  5. const Tensor* x = context.Input<Tensor>("X");
  6. const Tensor* y = context.Input<Tensor>("Y");
  7. Tensor* z = context.Output<Tensor>("Out");
  8. const Tensor x_matrix =
  9. x->dims().size() > 2
  10. ? framework::ReshapeToMatrix(
  11. *x, context.template Attr<int>("x_num_col_dims"))
  12. : *x;
  13. const Tensor y_matrix =
  14. y->dims().size() > 2
  15. ? framework::ReshapeToMatrix(
  16. *y, context.template Attr<int>("y_num_col_dims"))
  17. : *y;
  18. z->mutable_data<T>(context.GetPlace());
  19. auto z_dim = z->dims();
  20. if (z_dim.size() != 2) {
  21. z->Resize({x_matrix.dims()[0], y_matrix.dims()[1]});
  22. }
  23. auto blas = math::GetBlas<DeviceContext, T>(context);
  24. blas.MatMul(x_matrix, y_matrix, z);
  25. if (z_dim.size() != 2) {
  26. z->Resize(z_dim);
  27. }
  28. }
  29. };

需要注意:不同设备(CPU、CUDA)共享一个Op定义,是否则共享同一个OpKernel,取决于Compute调用的函数是否支持不同设备。

MulOp的CPU、CUDA实现共享同一个KernelOpKernel不共享的例子可以参考:SGDOpKernel

为了使OpKernel的计算过程书写更加简单,并且CPU、CUDA的代码可以复用,我们通常借助 Eigen unsupported Tensor模块来实现Compute接口。关于在PaddlePaddle中如何使用Eigen库,请参考使用文档

到此,前向Op实现完成。接下来,需要在.cc文件中注册该op和kernel。 反向Op类的定义,反向OpKernel的定义与前向Op类似,这里不再赘述。

注册Operator

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

    1. namespace ops = paddle::operators;
    2. REGISTER_OPERATOR(mul, ops::MulOp, ops::MulOpMaker, ops::MulOpInferVarType,
    3. ops::MulOpGradMaker<paddle::framework::OpDesc>,
    4. ops::MulOpGradMaker<paddle::imperative::OpBase>);
    5. REGISTER_OPERATOR(mul_grad, ops::MulGradOp);
    6. REGISTER_OP_CPU_KERNEL(mul,
    7. ops::MulKernel<paddle::platform::CPUDeviceContext, float>,
    8. ops::MulKernel<paddle::platform::CPUDeviceContext, double>);
    9. REGISTER_OP_CPU_KERNEL(mul_grad,
    10. ops::MulGradKernel<paddle::platform::CPUDeviceContext, float>,
    11. ops::MulGradKernel<paddle::platform::CPUDeviceContext, double>);

    在上面的代码中,使用REGISTER_OPERATOR注册了ops::MulOp类,类型名为mul,该类的ProtoMakerops::MulOpMaker,其GradOpMaker分别是ops::MulOpGradMaker<paddle::framework::OpDesc>(声明式编程模式使用)和ops::MulOpGradMaker<paddle::imperative::OpBase>(命令式编程模式使用),并使用REGISTER_OPERATOR注册ops::MulGradOp,类型名为mul_grad。然后,使用REGISTER_OP_CPU_KERNEL注册了ops::MulKernel类,并特化模板参数为设备为paddle::platform::CPUPlace、数据类型为float类型和double类型;同理,注册ops::MulGradKernel类。

  • .cu文件中注册CUDA Kernel。

    • 请注意,如果CUDA Kernel的实现基于Eigen unsupported模块,那么在 .cu的开始请加上宏定义 #define EIGEN_USE_GPU,代码示例如下:
    1. // if use Eigen unsupported module before include head files
    2. #define EIGEN_USE_GPU
    3. namespace ops = paddle::operators;
    4. REGISTER_OP_CUDA_KERNEL(mul,
    5. ops::MulKernel<paddle::platform::CUDADeviceContext, float>,
    6. ops::MulKernel<paddle::platform::CUDADeviceContext, double>);
    7. REGISTER_OP_CUDA_KERNEL(mul_grad,
    8. ops::MulGradKernel<paddle::platform::CUDADeviceContext, float>,
    9. ops::MulGradKernel<paddle::platform::CUDADeviceContext, double>);

注意:

在运行Op时,框架系统会根据输入数据所在的设备、输入数据的类型等信息自动的选择合适的OpKernel,比如输入的数据是在GPU上,并且为float类型,框架系统会选择由REGISTER_OP_CUDA_KERNEL注册的ops::MulKernel<paddle::platform::CUDADeviceContext, float>。如果用户希望指定运行时可被调用的OpKernel,用户需要覆盖framework::OperatorWithKernel中的GetExpectedKernelType函数,比如MulOp会根据属性use_mkldnnfalse还是为true决定是否调用mkldnn库来完成计算。

编译

详细的编译环境准备和执行流程可参考从源码编译,下面简单介绍几个主要步骤。 在Paddle代码目录下创建并切换到build目录:

  1. mkdir build && cd build

执行cmake命令,具体选项可参考从源码编译中的介绍,下面的命令为编译Python3.5,GPU版本,带测试,Release版本的Paddle。

  1. cmake .. -DPY_VERSION=3.5 -DWITH_GPU=ON -DWITH_TESTING=ON -DCMAKE_BUILD_TYPE=Release

build目录下,运行下面命令可以进行编译整个paddle:

  1. make -j$(nproc)

注意: 新增op后请重新执行cmake命令,然后再执行make命令编译paddle。

绑定Python

系统会对新增的op自动绑定Python,并链接到生成的lib库中。

使用mul操作在Python端构建Layer

在Python端,mul操作用于构建FC层,即:

Out\=Act(X∗W+b)Out\=Act(X∗W+b)

具体实现方式可参考FC层的实现代码

实现单元测试

单测包括对比前向Op不同设备(CPU、CUDA)的实现、对比反向OP不同设备(CPU、CUDA)的实现、反向Op的梯度测试。下面介绍介绍MulOp的单元测试

注意:

单测中的测试用例需要尽可能的覆盖Op中的所有分支。

前向Operator单测

Op单元测试继承自OpTest。各项具体的单元测试在TestMulOp里完成。测试Operator,需要:

  1. setUp函数定义输入、输出,以及相关的属性参数。

    注意:输入输出请以ndarray的类型配置输入/输出,如果需要配置一个带LOD的输入/输出,请以tuple的形式传入,tuple中应该有两个类型为ndarray的元素,第一个是实际的数据,第二个是LOD

  2. 生成随机的输入数据。

  3. 在Python脚本中实现与前向operator相同的计算逻辑,得到输出值,与operator前向计算的输出进行对比。

  4. 反向计算已经自动集成进测试框架,直接调用相应接口即可。

    ``` import unittest import numpy as np from op_test import OpTest

  1. class TestMulOp(OpTest):
  2. def setUp(self):
  3. self.op_type = "mul"
  4. self.inputs = {
  5. 'X': np.random.random((32, 84)).astype("float32"),
  6. 'Y': np.random.random((84, 100)).astype("float32")
  7. }
  8. self.outputs = {'Out': np.dot(self.inputs['X'], self.inputs['Y'])}
  9. def test_check_output(self):
  10. self.check_output()
  11. def test_check_grad_normal(self):
  12. self.check_grad(['X', 'Y'], 'Out', max_relative_error=0.5)
  13. def test_check_grad_ingore_x(self):
  14. self.check_grad(
  15. ['Y'], 'Out', max_relative_error=0.5, no_grad_set=set("X"))
  16. def test_check_grad_ingore_y(self):
  17. self.check_grad(
  18. ['X'], 'Out', max_relative_error=0.5, no_grad_set=set('Y'))
  19. ```
  20. 上面的代码首先导入依赖的包,下面是对`setUp`函数中操作的重要变量的详细解释:
  21. - `self.op_type = "mul"` : 定义类型,与operator注册时注册的类型一致。
  22. - `self.inputs` : 定义输入,类型为`numpy.array`,并初始化。
  23. - `self.outputs` : 定义输出,并在Python脚本中完成与operator同样的计算逻辑,返回Python端的计算结果。

反向operator单测

而反向测试中:

  • test_check_grad_normal中调用check_grad使用数值法检测梯度正确性和稳定性。

    • 第一个参数["X", "Y"] : 指定对输入变量XY做梯度检测。

    • 第二个参数"Out" : 指定前向网络最终的输出目标变量Out

    • 第三个参数max_relative_error:指定检测梯度时能容忍的最大错误值。

  • test_check_grad_ingore_xtest_check_grad_ingore_y分支用来测试只需要计算一个输入梯度的情况。

编译和执行

python/paddle/fluid/tests/unittests/ 目录下新增的 test_*.py 单元测试会被自动加入工程进行编译。

请注意,运行单元测试测时需要编译整个工程,并且编译时需要打开WITH_TESTING

参考上述编译过程,编译成功后,在build目录下执行下面的命令来运行单元测试:

  1. make test ARGS="-R test_mul_op -V"

或者执行:

  1. ctest -R test_mul_op

注意事项

  • 注册Op时的类型名,需要和该Op的名字一样。即不允许在A_op.cc里面,注册REGISTER_OPERATOR(B, ...)等,这将会导致单元测试出错。

  • 如果Op没有实现CUDA Kernel,请不要创建空的*_op.cu,这将会导致单元测试出错。

  • 如果多个Op依赖一些共用的函数,可以创建非*_op.*格式的文件来存放,如gather.h文件。

PADDLE_ENFORCE使用注意

实现Op时检查数据的合法性需要使用PADDLE_ENFORCE以及PADDLE_ENFORCE_EQ等宏定义,基本格式如下:

  1. PADDLE_ENFORCE(表达式, 错误提示信息)
  2. PADDLE_ENFORCE_EQ(比较对象A, 比较对象B, 错误提示信息)

如果表达式为真,或者比较对象A=B,则检查通过,否则会终止程序运行,向用户反馈相应的错误提示信息。 为了确保提示友好易懂,开发者需要注意其使用方法。

总体原则

任何使用了PADDLE_ENFORCE与PADDLE_ENFORCE_XX检查的地方,必须有详略得当的备注解释!错误提示信息不能为空!

提示信息书写标准

  1. [required] 哪里错了?为什么错了?

    • 例如:ValueError: Mismatched label shape
  2. [optional] 期望的输入是什么样的?实际的输入是怎样的?

    • 例如:Expected labels dimension=1. Received 4.
  3. [optional] 能否给出修改意见?

    • 例如:Suggested Fix:If your classifier expects one-hot encoding label,check your n_classes argument to the estimatorand/or the shape of your label.Otherwise, check the shape of your label.

如果并非必要或者简洁的描述即可表达清楚以上要点,根据情况书写亦可。

FAQ 典型问题

  1. 无报错信息或报错信息过于简单,不能给用户提供有效的提示!

    问题示例1 :未写提示信息

    1. PADDLE_ENFORCE(ctx->HasInput("X"), "");

    问题示例2 :提示信息过于简单

    1. PADDLE_ENFORCE(i != nullptr, "i must be set"); // i是什么?
  2. 在报错信息中使用开发人员定义的变量缩写,不易理解!

    问题示例:

    1. PADDLE_ENFORCE(forward_pd != nullptr,
    2. "Fail to find eltwise_fwd_pd in device context"); //eltwise_fwd_pd用户可能看不懂
  3. OP内部调用非法接口:Op内部如果出现Output = ShareDataWith(Input) 问题示例:

    1. auto *out = ctx.Output<framework::LoDTensor>("Out");
    2. auto *in = ctx.Input<framework::LoDTensor>("X");
    3. out->ShareDataWith(*in);

    Op内部如果出现Output = ShareDataWith(Input),相当于operator图的中有一条隐藏边,连接了Input和Output,这条边无法在图分析中表达,引发基于图优化的错误。

  4. OP实现的性能实践 调用了eigen的broadcast, chop等操作,性能会比手写cuda kernel差几倍以上。此时cpu的实现可以复用eigen,gpu实现可以实现cuda kernel.

OP InferShape检查提示信息特别说明

  • 检查输入输出变量,请统一遵循以下格式 Input(变量名) of OP名 operator should not be null.

    正确示例:

    1. PADDLE_ENFORCE(ctx->HasInput("Input"),
    2. "Input(Input) of LSTMP operator should not be null.");
  • 反向Op的输入输出检查,要写明反向Op的名字

    正确示例:

    1. PADDLE_ENFORCE(ctx->HasInput("X"),
    2. "Input(X) of LoDResetGrad opreator should not be null.");