如何写新的C++ OP
概念简介
简单介绍需要用到基类，详细介绍请参考设计文档。
根据是否包含Kernel，可以将Op分为两种：包含Kernel的Op和不包含kernel的Op：
本文主要介绍带Kernel的Op如何写，简单总结Op需要包含的内容如下：
实现新的op都添加至目录paddle/fluid/operators下，文件命名以*_op.h（如有）、*_op.cc 、*_op.cu（如有）结尾。系统会根据文件名自动构建op和其对应的Python扩展。
下面以矩阵乘操作，即MulOp为例来介绍如何写带Kernel的Operator。
实现C++类
定义ProtoMaker类
矩阵乘法的公式：Out=X∗YOut=X∗Y, 可见该计算由两个输入，一个输出组成。
首先定义ProtoMaker来描述该Op的输入、输出，并添加注释：
class MulOpMaker : public framework::OpProtoAndCheckerMaker {
public:
void Make() override {
AddInput("X", "(Tensor), The first input tensor of mul op.");
AddInput("Y", "(Tensor), The second input tensor of mul op.");
AddOutput("Out", "(Tensor), The output tensor of mul op.");
AddAttr
"(bool, default false) Only used in mkldnn kernel")
.SetDefault(false);
AddAttr
"x_num_col_dims",
R"DOC((int, default 1), The mul_op can take tensors with more than two
dimensions as its inputs. If the input $X$ is a tensor with more
than two dimensions, $X$ will be flattened into a two-dimensional
matrix first. The flattening rule is: the first `num_col_dims`
will be flattened to form the first dimension of the final matrix
(the height of the matrix), and the rest `rank(X) - num_col_dims`
dimensions are flattened to form the second dimension of the final
matrix (the width of the matrix). As a result, height of the
flattened matrix is equal to the product of $X$'s first
`x_num_col_dims` dimensions' sizes, and width of the flattened
matrix is equal to the product of $X$'s last `rank(x) - num_col_dims`
dimensions' size. For example, suppose $X$ is a 6-dimensional
tensor with the shape [2, 3, 4, 5, 6], and `x_num_col_dims` = 3.
Thus, the flattened matrix will have a shape [2 x 3 x 4, 5 x 6] =
[24, 30].
)DOC")
.SetDefault(1)
.EqualGreaterThan(1);
AddAttr
"y_num_col_dims",
R"DOC((int, default 1), The mul_op can take tensors with more than two,
dimensions as its inputs. If the input $Y$ is a tensor with more
than two dimensions, $Y$ will be flattened into a two-dimensional
matrix first. The attribute `y_num_col_dims` determines how $Y$ is
flattened. See comments of `x_num_col_dims` for more details.
)DOC")
.SetDefault(1)
.EqualGreaterThan(1);
AddAttr
"scale_x",
"scale_x to be used for int8 mul input data x. scale_x has the"
"same purpose as scale_in in OPs that support quantization."
"Only to be used with MKL-DNN INT8")
.SetDefault(1.0f);
AddAttr
"scale_y",
"scale_y to be used for int8 mul input data y. scale_y has the"
"same purpose as scale_weights in OPs that support quantization."
"Only to be used with MKL-DNN INT8")
.SetDefault({1.0f});
AddAttr
"scale_out to be used for int8 output data."
"Only used with MKL-DNN INT8")
.SetDefault(1.0f);
AddAttr
"force_fp32_output",
"(bool, default false) Force quantize kernel output FP32, only "
"used in quantized MKL-DNN.")
.SetDefault(false);
AddComment(R"DOC(
Mul Operator.
This operator is used to perform matrix multiplication for input $X$ and $Y$.
The equation is:
$$Out = X * Y$$
Both the input $X$ and $Y$ can carry the LoD (Level of Details) information,
or not. But the output only shares the LoD information with input $X$.
)DOC");
}
};
MulOpMaker继承自framework::OpProtoAndCheckerMaker。
开发者通过覆盖framework::OpProtoAndCheckerMaker中的Make函数来定义Op所对应的Proto，通过AddInput添加输入参数，通过AddOutput添加输出参数，通过AddAttr添加属性参数，通过AddComment添加Op的注释。这些函数会将对应内容添加到OpProto中。
上面的代码在MulOp中添加两个输入X和Y，添加了一个输出Out，以及use_mkldnn等属性，并解释了各自含义，命名请遵守命名规范。
定义GradOpMaker类
通常情况下，大部分Op只有一个对应的反向Op，每个Op的会有一个对应的GradOpMaker。为方便代码编写，paddle为只有一个反向的Op提供了一个模板类SingleGradOpMaker。MulOp的GradOpMaker需要继承这个模板类，并在Apply()方法中设置反向Op的输入、输出和属性。此外，paddle还提供了一个默认的GradOpMaker， DefaultGradOpMaker，该模板类会使用前向Op的全部输入(Input)输出(Output)以及输出变量所对应的梯度（Output@Grad）作为反向Op的输入，将前向Op的输入变量所对应的的梯度（Input@Grad）作为输出。
注意: 不要将反向Op不会用到的变量放到反向Op的输入列表中，这样会导致这些不会被反向Op用到的变量的空间不能够及时回收，进而有可能导致用到该Op的模型可以设置的batch_size较低。 比如relu操作的前向操作为：out.device(d) = x.cwiseMax(static_cast
下面示例定义了MulOp的GradOpMaker。
template <typename T>
class MulOpGradMaker : public framework::SingleGradOpMaker
public:
using framework::SingleGradOpMaker
protected:
void Apply(GradOpPtr
retv->SetType("mul_grad");
retv->SetInput("X", this->Input("X"));
retv->SetInput("Y", this->Input("Y"));
retv->SetInput(framework::GradVarName("Out"), this->OutputGrad("Out"));
retv->SetOutput(framework::GradVarName("X"), this->InputGrad("X"));
retv->SetOutput(framework::GradVarName("Y"), this->InputGrad("Y"));
retv->SetAttrMap(this->Attrs());
}
};
注意：
定义Operator类
下面实现了MulOp的定义：
class MulOp : public framework::OperatorWithKernel {
public:
using framework::OperatorWithKernel::OperatorWithKernel;
void InferShape(framework::InferShapeContext* ctx) const override {
PADDLE_ENFORCE_EQ(
ctx->HasInput("X"), true,
platform::errors::NotFound("Input(X) of MulOp should not be null."));
PADDLE_ENFORCE_EQ(
ctx->HasInput("Y"), true,
platform::errors::NotFound("Input(Y) of MulOp should not be null."));
PADDLE_ENFORCE_EQ(
ctx->HasOutput("Out"), true,
platform::errors::NotFound("Output(Out) of MulOp should not be null."));
auto x_dims = ctx->GetInputDim("X");
auto y_dims = ctx->GetInputDim("Y");
int x_num_col_dims = ctx->Attrs().Get<int>("x_num_col_dims");
int y_num_col_dims = ctx->Attrs().Get<int>("y_num_col_dims");
VLOG(3) <<"mul operator x.shape=" < "been initialized. You may need to confirm " "if you put exe.run(startup_program) " "after optimizer.minimize function.", ctx->Inputs("Y").front())); PADDLE_ENFORCE_GT( x_dims.size(), x_num_col_dims, platform::errors::InvalidArgument( "The input tensor X's dimensions of MulOp " "should be larger than x_num_col_dims. But received X's " "dimensiOns= %d, X's shape = [%s], x_num_col_dims = %d.", x_dims.size(), x_dims, x_num_col_dims)); PADDLE_ENFORCE_GT( y_dims.size(), y_num_col_dims, platform::errors::InvalidArgument( "The input tensor Y's dimensions of MulOp " "should be larger than y_num_col_dims. But received Y's " "dimensiOns= %d, Y's shape = [%s], y_num_col_dims = %d.", y_dims.size(), y_dims, y_num_col_dims)); auto x_mat_dims = framework::flatten_to_2d(x_dims, x_num_col_dims); auto y_mat_dims = framework::flatten_to_2d(y_dims, y_num_col_dims); PADDLE_ENFORCE_EQ( x_mat_dims[1], y_mat_dims[0], platform::errors::InvalidArgument( "After flatten the input tensor X and Y to 2-D dimensions " "matrix X1 and Y1, the matrix X1's width must be equal with matrix " "Y1's height. But received X's shape = [%s], X1's shape = [%s], " "X1's " "width = %s; Y's shape = [%s], Y1's shape = [%s], Y1's height = " "%s.", x_dims, x_mat_dims, x_mat_dims[1], y_dims, y_mat_dims, y_mat_dims[0])); std::vector<int64_t> output_dims; output_dims.reserve( static_cast<size_t>(x_num_col_dims + y_dims.size() - y_num_col_dims)); for (int i = 0; i output_dims.push_back(x_dims[i]); } for (int i = y_num_col_dims; i output_dims.push_back(y_dims[i]); } ctx->SetOutputDim("Out", framework::make_ddim(output_dims)); ctx->ShareLoD("X", /*->*/ "Out"); } framework::OpKernelType GetExpectedKernelType( const framework::ExecutionContext& ctx) const { framework::LibraryType library = framework::LibraryType::kPlain; framework::DataLayout layout = framework::DataLayout::kAnyLayout; int customized_type_value = framework::OpKernelType::kDefaultCustomizedTypeValue; auto input_data_type = OperatorWithKernel::IndicateVarDataType(ctx, "X"); #ifdef PADDLE_WITH_MKLDNN if (library == framework::LibraryType::kPlain && platform::CanMKLDNNBeUsed(ctx)) { library = framework::LibraryType::kMKLDNN; layout = framework::DataLayout::kMKLDNN; if (input_data_type == framework::DataTypeTrait<int8_t>::DataType() || input_data_type == framework::DataTypeTrait<uint8_t>::DataType()) { customized_type_value = kMULMKLDNNINT8; } } #endif return framework::OpKernelType(input_data_type, ctx.GetPlace(), layout, library, customized_type_value); } }; MulOp继承自OperatorWithKernel。public成员： using framework::OperatorWithKernel::OperatorWithKernel; 这句表示使用基类OperatorWithKernel的构造函数，也可写成： MulOp(const std::string &type, const framework::VariableNameMap &inputs, const framework::VariableNameMap &outputs, const framework::AttributeMap &attrs) : OperatorWithKernel(type, inputs, outputs, attrs) {} 此外，Operator类通常需要重写InferShape接口，并在有必要时重写GetExpectedKernelType接口。InferShape为const函数，不能修改Op的成员变量，参数为framework::InferShapeContext* ctx，通过该参数可获取到输入输出以及属性。它的功能是： GetExpectedKernelType接口OperatorWithKernel类中用于获取指定设备（例如CPU，GPU）上指定数据类型（例如double，float）的OpKernel的方法。该方法的重写可见请参考写C++ OP相关注意事项。 通常OpProtoMaker和Op类的定义写在.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.检查 如以下代码： auto x_dim = ctx->GetInputDim("X"); int i = xxx; PADDLE_ENFORCE_GT( x_dim[i] , 10) 在compile time的时候，x_dim[i]可能等于-1，导致这个PADDLE_ENFORCE_GT报错退出。 如果用了以下paddle中定义的宏进行判断： PADDLE_ENFORCE_EQ ( x_dim[i] , 10) PADDLE_ENFORCE_NE ( x_dim[i] , 10) PADDLE_ENFORCE_GT ( x_dim[i] , 10) PADDLE_ENFORCE_GE ( x_dim[i] , 10) PADDLE_ENFORCE_LT ( x_dim[i] , 10) PADDLE_ENFORCE_LE ( x_dim[i] , 10) 都需要区分compile time和run time 2. 运算 如以下代码: auto x_dim = ctx->GetInputDim("X"); int i = xxx; y_dim[0] = x_dim[i] + 10 在compile time的时候，x_dim[i]可能等于-1，得到的 y_dim[0] 等于 9，是不符合逻辑的 如果用到了类似以下的运算操作 y_dim[i] = x_dim[i] + 10 y_dim[i] = x_dim[i] - 10 y_dim[i] = x_dim[i] * 10 y_dim[i] = x_dim[i] / 10 y_dim[i] = x_dim[i] + z_dim[i] 都需要区分compile time和run time 处理的标准： 参考代码 bool contain_unknown_dim = framework::contain_unknown_dim(x_dims) || framework::contain_unknown_dim(label_dims); bool check = ctx->IsRuntime() || !contain_unknown_dim; if (check) { PADDLE_ENFORCE_EQ(framework::slice_ddim(x_dims, 0, rank - 1), framework::slice_ddim(label_dims, 0, rank - 1), "Input(X) and Input(Label) shall have the same shape " "except the last dimension."); } const size_t n = inputs_dims.size(); auto out_dims = inputs_dims[0]; size_t in_zero_dims_size = out_dims.size(); for (size_t i = 1; i for (size_t j = 0; j if (j == axis) { if (is_runtime) { out_dims[axis] += inputs_dims[i][j]; } else { if (inputs_dims[i][j] == -1) { out_dims[axis] = -1; } else { out_dims[axis] += inputs_dims[i][j]; } } } else { bool check_shape = is_runtime || (out_dims[j] > 0 && inputs_dims[i][j] > 0); if (check_shape) { // check all shape in run time PADDLE_ENFORCE_EQ( inputs_dims[0][j], inputs_dims[i][j], "ShapeError: Dimension %d in inputs' shapes must be equal. " "But recevied input[0]'s shape = " "[%s], input[%d]'s shape = [%s].", j, inputs_dims[0], i, inputs_dims[i]); } } } } 定义OpKernel类 MulKernel继承自framework::OpKernel，带有下面两个模板参数: 需要为MulKernel类重写Compute接口。 Op的输入和输出可分别通过ExecutionContext::Input 注意： 若op的输入/输出的变量类型是LoDTensor（paddle默认所有的Tensor默认都是LoDTensor类型），请写成ExecutionContext::Input 下面是 MulKernel Compute的实现： template <typename DeviceContext, typename T> class MulKernel : public framework::OpKernel public: void Compute(const framework::ExecutionContext& context) const override { const Tensor* x = context.Input const Tensor* y = context.Input Tensor* z = context.Output const Tensor x_matrix = x->dims().size() > 2 ? framework::ReshapeToMatrix( *x, context.template Attr<int>("x_num_col_dims")) : *x; const Tensor y_matrix = y->dims().size() > 2 ? framework::ReshapeToMatrix( *y, context.template Attr<int>("y_num_col_dims")) : *y; z->mutable_data auto z_dim = z->dims(); if (z_dim.size() != 2) { z->Resize({x_matrix.dims()[0], y_matrix.dims()[1]}); } auto blas = math::GetBlas blas.MatMul(x_matrix, y_matrix, z); if (z_dim.size() != 2) { z->Resize(z_dim); } } }; 需要注意：不同设备(CPU、CUDA)共享一个Op定义，是否则共享同一个OpKernel，取决于Compute调用的函数是否支持不同设备。 MulOp的CPU、CUDA实现共享同一个Kernel。OpKernel不共享的例子可以参考：SGDOpKernel。 为了使OpKernel的计算过程书写更加简单，并且CPU、CUDA的代码可以复用，我们通常借助 Eigen unsupported Tensor模块来实现Compute接口。关于在PaddlePaddle中如何使用Eigen库，请参考使用文档。 到此，前向Op实现完成。接下来，需要在.cc文件中注册该op和kernel。 反向Op类的定义，反向OpKernel的定义与前向Op类似，这里不再赘述。 注册Operator , ); float>, double>); float>, double>); 在上面的代码中，使用REGISTER_OPERATOR注册了ops::MulOp类，类型名为mul，该类的ProtoMaker为ops::MulOpMaker，其GradOpMaker分别是ops::MulOpGradMaker （声明式编程模式使用）和ops::MulOpGradMaker (命令式编程模式使用)，并使用REGISTER_OPERATOR注册ops::MulGradOp，类型名为mul_grad。然后，使用REGISTER_OP_CPU_KERNEL注册了ops::MulKernel类，并特化模板参数为设备为paddle::platform::CPUPlace、数据类型为float类型和double类型；同理，注册ops::MulGradKernel类。 float>, double>); float>, double>); 注意： 在运行Op时，框架系统会根据输入数据所在的设备、输入数据的类型等信息自动的选择合适的OpKernel，比如输入的数据是在GPU上，并且为float类型，框架系统会选择由REGISTER_OP_CUDA_KERNEL注册的ops::MulKernel 。如果用户希望指定运行时可被调用的OpKernel，用户需要覆盖framework::OperatorWithKernel中的GetExpectedKernelType函数，比如MulOp会根据属性use_mkldnn为false还是为true决定是否调用mkldnn库来完成计算。 编译 详细的编译环境准备和执行流程可参考从源码编译，下面简单介绍几个主要步骤。 在Paddle代码目录下创建并切换到build目录： mkdir build && cd build 执行cmake命令，具体选项可参考从源码编译中的介绍，下面的命令为编译Python3.5，GPU版本，带测试，Release版本的Paddle。 cmake .. -DPY_VERSION=3.5 -DWITH_GPU=ON -DWITH_TESTING=ON -DCMAKE_BUILD_TYPE=Release 在build目录下，运行下面命令可以进行编译整个paddle： 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，需要： 注意：输入输出请以ndarray的类型配置输入/输出，如果需要配置一个带LOD的输入/输出，请以tuple的形式传入，tuple中应该有两个类型为ndarray的元素，第一个是实际的数据，第二个是LOD 10. class TestMulOp(OpTest): 上面的代码首先导入依赖的包，下面是对setUp函数中操作的重要变量的详细解释： 反向operator单测 而反向测试中： 编译和执行 python/paddle/fluid/tests/unittests/ 目录下新增的 test_*.py 单元测试会被自动加入工程进行编译。 请注意，运行单元测试测时需要编译整个工程，并且编译时需要打开WITH_TESTING。 参考上述编译过程，编译成功后，在build目录下执行下面的命令来运行单元测试： make test ARGS="-R test_mul_op -V" 或者执行: ctest -R test_mul_op 注意事项 PADDLE_ENFORCE使用注意 实现Op时检查数据的合法性需要使用PADDLE_ENFORCE以及PADDLE_ENFORCE_EQ等宏定义，基本格式如下： PADDLE_ENFORCE(表达式, 错误提示信息) PADDLE_ENFORCE_EQ(比较对象A, 比较对象B, 错误提示信息) 如果表达式为真，或者比较对象A=B，则检查通过，否则会终止程序运行，向用户反馈相应的错误提示信息。 为了确保提示友好易懂，开发者需要注意其使用方法。 总体原则 任何使用了PADDLE_ENFORCE与PADDLE_ENFORCE_XX检查的地方，必须有详略得当的备注解释！错误提示信息不能为空！ 提示信息书写标准 如果并非必要或者简洁的描述即可表达清楚以上要点，根据情况书写亦可。 FAQ 典型问题 问题示例1 ：未写提示信息 PADDLE_ENFORCE(ctx->HasInput("X"), ""); 问题示例2 ：提示信息过于简单 PADDLE_ENFORCE(i != nullptr, "i must be set"); // i是什么？ 问题示例： PADDLE_ENFORCE(forward_pd != nullptr, "Fail to find eltwise_fwd_pd in device context"); //eltwise_fwd_pd用户可能看不懂 Op内部如果出现Output = ShareDataWith(Input)，相当于operator图的中有一条隐藏边，连接了Input和Output，这条边无法在图分析中表达，引发基于图优化的错误。 OP InferShape检查提示信息特别说明 正确示例： PADDLE_ENFORCE(ctx->HasInput("Input"), "Input(Input) of LSTMP operator should not be null."); 正确示例： PADDLE_ENFORCE(ctx->HasInput("X"), "Input(X) of LoDResetGrad opreator should not be null.");
京公网安备 11010802041100号 | 京ICP备19059560号-4 | PHP1.CN 第一PHP社区 版权所有 