From a8d113e220aae47b49eacb98341d8148fe82d388 Mon Sep 17 00:00:00 2001 From: shanyi15 Date: Sat, 2 Mar 2019 15:58:56 +0800 Subject: [PATCH 1/3] Tables_rm_op --- .../development/new_op/new_op_cn.md | 1 - doc/fluid/beginners_guide/install/Tables.md | 153 +++++++------ .../beginners_guide/install/Tables_en.md | 214 ++++++++---------- 3 files changed, 168 insertions(+), 200 deletions(-) delete mode 120000 doc/fluid/advanced_usage/development/new_op/new_op_cn.md diff --git a/doc/fluid/advanced_usage/development/new_op/new_op_cn.md b/doc/fluid/advanced_usage/development/new_op/new_op_cn.md deleted file mode 120000 index dce0348585b..00000000000 --- a/doc/fluid/advanced_usage/development/new_op/new_op_cn.md +++ /dev/null @@ -1 +0,0 @@ -../../../dev/new_op_cn.md \ No newline at end of file diff --git a/doc/fluid/beginners_guide/install/Tables.md b/doc/fluid/beginners_guide/install/Tables.md index 755305cf09b..aedc16f44f5 100644 --- a/doc/fluid/beginners_guide/install/Tables.md +++ b/doc/fluid/beginners_guide/install/Tables.md @@ -1,4 +1,3 @@ -*** # 附录 @@ -36,7 +35,7 @@ SWIG 最低 2.0 - https://github.com/PaddlePaddle/Paddle/tree/develop/doc/design/mkldnn + apt install swig 或 yum install swig @@ -176,11 +175,6 @@ 是否编译带有分布式的版本 OFF - - WITH_MKL - 是否使用MKL数学库，如果为否则是用OpenBLAS - ON - WITH_RDMA 是否编译支持RDMA的相关部分 @@ -245,86 +239,27 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。 - paddlepaddle==[版本号] 如 paddlepaddle==1.0.1(下载1.0.1版本只支持CPU的PaddlePaddle) + paddlepaddle==[版本号] 例如 paddlepaddle==1.2.0 只支持CPU对应版本的PaddlePaddle，具体版本请参见Pypi - paddlepaddle-gpu==1.0.1 - 使用CUDA 9.0和cuDNN 7编译的1.0.1版本 - - - paddlepaddle-gpu==1.0.1.post87 - 使用CUDA 8.0和cuDNN 7编译的1.0.1版本 - - - paddlepaddle-gpu==1.0.1.post85 - 使用CUDA 8.0和cuDNN 5编译的1.0.1版本 - - - paddlepaddle-gpu==1.0.0 - 使用CUDA 9.0和cuDNN 7编译的1.0.0版本 - - - paddlepaddle-gpu==1.0.0.post87 - 使用CUDA 8.0和cuDNN 7编译的1.0.0版本 - - - paddlepaddle-gpu==1.0.0.post85 - 使用CUDA 8.0和cuDNN 5编译的1.0.0版本 - - - paddlepaddle-gpu==0.15.0 - 使用CUDA 9.0和cuDNN 7编译的0.15.0版本 - - - paddlepaddle-gpu==0.15.0.post87 - 使用CUDA 8.0和cuDNN 7编译的0.15.0版本 - - - paddlepaddle-gpu==0.15.0.post85 - 使用CUDA 8.0和cuDNN 5编译的0.15.0版本 - - - paddlepaddle-gpu==0.14.0 - 使用CUDA 9.0和cuDNN 7编译的0.15.0版本 - - - paddlepaddle-gpu==0.14.0.post87 - 使用CUDA 8.0和cuDNN 7编译的0.15.0版本 - - - paddlepaddle-gpu==0.14.0.post85 - 使用CUDA 8.0和cuDNN 5编译的0.15.0版本 - - - paddlepaddle-gpu==0.13.0 - 使用CUDA 9.0和cuDNN 7编译的0.13.0版本 - - - paddlepaddle-gpu==0.12.0 - 使用CUDA 8.0和cuDNN 5编译的0.12.0版本 - - - paddlepaddle-gpu==0.11.0.post87 - 使用CUDA 8.0和cuDNN 7编译的0.11.0版本 + paddlepaddle-gpu==1.2.0 + 使用CUDA 9.0和cuDNN 7编译的1.2.0版本 - paddlepaddle-gpu==0.11.0.post85 - 使用CUDA 8.0和cuDNN 5编译的0.11.0版本 + paddlepaddle-gpu==1.2.0.post87 + 使用CUDA 8.0和cuDNN 7编译的1.2.0版本 - paddlepaddle-gpu==0.11.0 - 使用CUDA 7.5和cuDNN 5编译的0.11.0版本 + paddlepaddle-gpu==1.2.0.post85 + 使用CUDA 8.0和cuDNN 5编译的1.2.0版本

- 您可以在 [Release History](https://pypi.org/project/paddlepaddle-gpu/#history) 中找到PaddlePaddle-gpu的各个发行版本。 - -*** - +需要注意的是，在v1.3版本中， paddlepaddle-gpu命令 在windows环境下，会默认安装CUDA 8.0和cuDNN 5编译的PaddlePaddle *** @@ -425,10 +360,80 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。 paddlepaddle_gpu-1.3.0-cp37-cp37m-linux_x86_64.whl + + win_amd64 + - + + paddlepaddle-1.3.0-cp27-cp27m-win_amd64.whl + + paddlepaddle-1.3.0-cp35-cp35m-win_amd64.whl + + paddlepaddle-1.3.0-cp36-cp36m-win_amd64.whl + + paddlepaddle-1.3.0-cp37-cp37m-win_amd64.whl + + + cuda8.0_cudnn5_win_amd64 + - + + paddlepaddle_gpu-1.3.0-cp27-cp27m-win_amd64.whl + + paddlepaddle_gpu-1.3.0-cp35-cp35m-win_amd64.whl + + paddlepaddle_gpu-1.3.0-cp36-cp36m-win_amd64.whl + + paddlepaddle_gpu-1.3.0-cp37-cp37m-win_amd64.whl +

+### 表格说明 + +- 纵轴 + +cpu_noavx_mkl: 只支持CPU训练和预测，使用sse指令集和Intel mkl数学库 + +cpu_avx_mkl: 只支持CPU训练和预测，使用avx指令集和Intel mkl数学库 + +cpu_avx_openblas: 只支持CPU训练和预测，使用avx指令集和openblas数学库 + +cuda8.0_cudnn5_avx_mkl: 支持GPU训练和预测，使用avx指令集和Intel mkl数学库 + +cuda8.0_cudnn7_noavx_mkl: 支持GPU训练和预测，使用sse指令集和Intel mkl数学库 + +cuda8.0_cudnn7_avx_mkl: 支持GPU训练和预测，使用avx指令集和Intel mkl数学库 + +cuda9.0_cudnn7_avx_mkl: 支持GPU训练和预测，使用avx指令集和Intel mkl数学库 + +win_amd64：只支持CPU训练和预测，使用AMD64指令集 + +cuda8.0_cudnn5_win_amd64：支持支持GPU训练和预测，使用AMD64指令集 + +- 横轴 + +一般是类似于“cp27-cp27mu”的形式，其中： + +27:python tag,指python2.7，类似的还有“35”、“36”、“37”等 + +mu:指unicode版本python，若为m则指非unicode版本python + +- 安装包命名规则 + +每个安装包都有一个专属的名字，它们是按照Python的官方规则 来命名的，形式如下： + +{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl + +其中build tag可以缺少，其他部分不能缺少 + +distribution: wheel名称version: 版本，例如0.14.0 (要求必须是数字格式) + +python tag: 类似'py27', 'py2', 'py3'，用于标明对应的python版本 + +abi tag: 类似'cp33m', 'abi3', 'none' + +platform tag: 类似 'linux_x86_64', 'any' +

## **多版本whl包列表-dev** diff --git a/doc/fluid/beginners_guide/install/Tables_en.md b/doc/fluid/beginners_guide/install/Tables_en.md index ed8c565242a..f55fca8e9f6 100644 --- a/doc/fluid/beginners_guide/install/Tables_en.md +++ b/doc/fluid/beginners_guide/install/Tables_en.md @@ -177,11 +177,6 @@ Whether to Compile with distributed version OFF - - WITH_MKL - Whether to uses the MKL math library, if not, using OpenBLAS - ON - WITH_RDMA Whether to compile the relevant parts that supports RDMA @@ -244,76 +239,20 @@ PaddePaddle implements references to various BLAS/CUDA/cuDNN libraries by specif - paddlepaddle==[version code] such as paddlepaddle==1.0.1 (download version 1.0.1 which only supports CPU PaddlePaddle) + paddlepaddle==[version code] such as paddlepaddle==1.2.0 Only support the corresponding version of the CPU PaddlePaddle, please refer to Pypi for the specific version. - paddlepaddle-gpu==1.0.1 - Using version 1.0.1 compiled with CUDA 9.0 and cuDNN 7 - - - paddlepaddle-gpu==1.0.1.post87 - Using version 1.0.1 compiled with CUDA 8.0 and cuDNN 7 - - - paddlepaddle-gpu==1.0.1.post85 - Using version 1.0.1 compiled with CUDA 8.0 and cuDNN 5 - - - paddlepaddle-gpu==1.0.0 - Using version 1.0.0 compiled with CUDA 9.0 and cuDNN 7 - - - paddlepaddle-gpu==1.0.0.post87 - Using version 1.0.0 compiled with CUDA 8.0 and cuDNN 7 - - - paddlepaddle-gpu==1.0.0.post85 - Using version 1.0.0 compiled with CUDA 8.0 and cuDNN 5 - - - paddlepaddle-gpu==0.15.0 - Using version 0.15.0 compiled with CUDA 9.0 and cuDNN 7 - - - paddlepaddle-gpu==0.15.0.post87 - Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 7 - - - paddlepaddle-gpu==0.15.0.post85 - Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 5 - - - paddlepaddle-gpu==0.14.0 - Using version 0.15.0 compiled with CUDA 9.0 and cuDNN 7 - - - paddlepaddle-gpu==0.14.0.post87 - Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 7 - - - paddlepaddle-gpu==0.14.0.post85 - Using version 0.15.0 compiled with CUDA 8.0 and cuDNN 5 - - - paddlepaddle-gpu==0.13.0 - Using version 0.13.0 compiled with CUDA 9.0 and cuDNN 7 - - - paddlepaddle-gpu==0.12.0 - Using version 0.12.0 compiled with CUDA 8.0 and cuDNN 5 - - - paddlepaddle-gpu==0.11.0.post87 - Using version 0.11.0 compiled with CUDA 8.0 and cuDNN 7 + paddlepaddle-gpu==1.2.0 + Using version 1.2.0 compiled with CUDA 9.0 and cuDNN 7 - paddlepaddle-gpu==0.11.0.post85 - Using version 0.11.0 compiled with CUDA 8.0 and cuDNN 5 + paddlepaddle-gpu==1.2.0.post87 + Using version 1.2.0 compiled with CUDA 8.0 and cuDNN 7 - paddlepaddle-gpu==0.11.0 - Using version 0.11.0 compiled with CUDA 7.5 and cuDNN 5 + paddlepaddle-gpu==1.2.0.post85 + Using version 1.2.0 compiled with CUDA 8.0 and cuDNN 5 @@ -322,6 +261,7 @@ PaddePaddle implements references to various BLAS/CUDA/cuDNN libraries by specif You can find various distributions of PaddlePaddle-gpu in [the Release History](https://pypi.org/project/paddlepaddle-gpu/#history). +Please note that: paddlepaddle-gpu==1.3.0 in windows, will download package compiled with CUDA 8.0 and cuDNN 5 *** @@ -382,81 +322,105 @@ You can find the docker image for each release of PaddlePaddle in the [DockerHub cpu-noavx-mkl - - paddlepaddle-1.2.1-cp27-cp27mu-linux_x86_64.whl - - paddlepaddle-1.2.1-cp27-cp27m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp35-cp35m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp36-cp36m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp37-cp37m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp27-cp27mu-linux_x86_64.whl + + paddlepaddle-1.3.0-cp27-cp27m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp35-cp35m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp36-cp36m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp37-cp37m-linux_x86_64.whl cpu_avx_mkl - - paddlepaddle-1.2.1-cp27-cp27mu-linux_x86_64.whl - - paddlepaddle-1.2.1-cp27-cp27m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp35-cp35m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp36-cp36m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp37-cp37m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp27-cp27mu-linux_x86_64.whl + + paddlepaddle-1.3.0-cp27-cp27m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp35-cp35m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp36-cp36m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp37-cp37m-linux_x86_64.whl cpu_avx_openblas - - paddlepaddle-1.2.1-cp27-cp27mu-linux_x86_64.whl - paddlepaddle-1.2.1-cp27-cp27m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp35-cp35m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp36-cp36m-linux_x86_64.whl - - paddlepaddle-1.2.1-cp37-cp37m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp27-cp27mu-linux_x86_64.whl + paddlepaddle-1.3.0-cp27-cp27m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp35-cp35m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp36-cp36m-linux_x86_64.whl + + paddlepaddle-1.3.0-cp37-cp37m-linux_x86_64.whl cuda8.0_cudnn5_avx_mkl - paddlepaddle_gpu-1.2.1-cp27-cp27mu-linux_x86_64.whl - paddlepaddle_gpu-1.2.1-cp27-cp27m-linux_x86_64.whl - paddlepaddle_gpu-1.2.1-cp35-cp35m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1-cp36-cp36m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1-cp37-cp37m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp27-cp27mu-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp27-cp27m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp35-cp35m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0-cp36-cp36m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0-cp37-cp37m-linux_x86_64.whl cuda8.0_cudnn7_noavx_mkl - paddlepaddle_gpu-1.2.1-cp27-cp27mu-linux_x86_64.whl - paddlepaddle_gpu-1.2.1-cp27-cp27m-linux_x86_64.whl - paddlepaddle_gpu-1.2.1-cp35-cp35m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1-cp36-cp36m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1-cp37-cp37m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp27-cp27mu-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp27-cp27m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp35-cp35m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0-cp36-cp36m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0-cp37-cp37m-linux_x86_64.whl cuda8.0_cudnn7_avx_mkl - paddlepaddle_gpu-1.2.1.post87-cp27-cp27mu-linux_x86_64.whl - paddlepaddle_gpu-1.2.1.post87-cp27-cp27m-linux_x86_64.whl - paddlepaddle_gpu-1.2.1.post87-cp35-cp35m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1.post87-cp36-cp36m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1.post87-cp37-cp37m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0.post87-cp27-cp27mu-linux_x86_64.whl + paddlepaddle_gpu-1.3.0.post87-cp27-cp27m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0.post87-cp35-cp35m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0.post87-cp36-cp36m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0.post87-cp37-cp37m-linux_x86_64.whl cuda9.0_cudnn7_avx_mkl - paddlepaddle_gpu-1.2.1-cp27-cp27mu-linux_x86_64.whl - paddlepaddle_gpu-1.2.1-cp27-cp27m-linux_x86_64.whl - paddlepaddle_gpu-1.2.1-cp35-cp35m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1-cp36-cp36m-linux_x86_64.whl - - paddlepaddle_gpu-1.2.1-cp37-cp37m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp27-cp27mu-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp27-cp27m-linux_x86_64.whl + paddlepaddle_gpu-1.3.0-cp35-cp35m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0-cp36-cp36m-linux_x86_64.whl + + paddlepaddle_gpu-1.3.0-cp37-cp37m-linux_x86_64.whl + + + win_amd64 + - + + paddlepaddle-1.3.0-cp27-cp27m-win_amd64.whl + + paddlepaddle-1.3.0-cp35-cp35m-win_amd64.whl + + paddlepaddle-1.3.0-cp36-cp36m-win_amd64.whl + + paddlepaddle-1.3.0-cp37-cp37m-win_amd64.whl + + + cuda8.0_cudnn5_win_amd64 + - + + paddlepaddle_gpu-1.3.0-cp27-cp27m-win_amd64.whl + + paddlepaddle_gpu-1.3.0-cp35-cp35m-win_amd64.whl + + paddlepaddle_gpu-1.3.0-cp36-cp36m-win_amd64.whl + + paddlepaddle_gpu-1.3.0-cp37-cp37m-win_amd64.whl From 36af95d8bc8a92283a8017bd0d0f970a2ed79781 Mon Sep 17 00:00:00 2001 From: shanyi15 Date: Sat, 2 Mar 2019 16:09:04 +0800 Subject: [PATCH 2/3] update_op --- .../development/new_op/index_cn.rst | 5 +- .../development/new_op/new_op.md | 452 ++++++++++++++++++ .../development/new_op/op_notes.md | 2 +- 3 files changed, 456 insertions(+), 3 deletions(-) create mode 100644 doc/fluid/advanced_usage/development/new_op/new_op.md diff --git a/doc/fluid/advanced_usage/development/new_op/index_cn.rst b/doc/fluid/advanced_usage/development/new_op/index_cn.rst index 55f037585b4..a1b2866a49e 100644 --- a/doc/fluid/advanced_usage/development/new_op/index_cn.rst +++ b/doc/fluid/advanced_usage/development/new_op/index_cn.rst @@ -1,10 +1,11 @@ ############# -新增operator +新增Operator ############# -- `op相关的一些注意事项 <../../../advanced_usage/development/new_op/op_notes.html>`_ ：介绍op相关的一些注意事项 +在这里，您将掌握如何添加新的Operator，本部分有如下几个部分： .. toctree:: :hidden: + new_op.md op_notes.md diff --git a/doc/fluid/advanced_usage/development/new_op/new_op.md b/doc/fluid/advanced_usage/development/new_op/new_op.md new file mode 100644 index 00000000000..ae42ee5162a --- /dev/null +++ b/doc/fluid/advanced_usage/development/new_op/new_op.md @@ -0,0 +1,452 @@ +# 如何写新的op + + - [概念简介](#概念简介) + - [实现C++类](#实现c类) + - [定义ProtoMaker类](#定义protomaker类) + - [定义Operator类](#定义operator类) + - [定义OpKernel类](#定义opkernel类) + - [注册Operator](#注册operator) + - [编译](#编译) + - [绑定Python](#绑定python) + - [实现单元测试](#实现单元测试) + - [前向Operator单测](#前向operator单测) + - [反向Operator单测](#反向operator单测) + - [编译和执行](#编译和执行) + - [注意事项](#注意事项) + + +## 概念简介 + +简单介绍需要用到基类，详细介绍请参考设计文档。 + +- `framework::OperatorBase`: Operator(简写，Op)基类。 +- `framework::OpKernel`: Op计算函数的基类，称作Kernel。 +- `framework::OperatorWithKernel`：继承自OperatorBase，Op有计算函数，称作有Kernel。 +- `class OpProtoAndCheckerMaker`：描述该Op的输入、输出、属性、注释,主要用于Python API接口生成 + +依据是否包含kernel，可以将Op分为两种：包含Kernel的Op和不包含kernel的Op，前者Op的定义继承自`OperatorWithKernel`，后者继承自`OperatorBase`。本教程主要介绍带Kernel的Op如何写，简单总结Op需要包含的内容如下： + + + + + + + + + + + + + + + + + + + + + + + + + + +
内容定义位置
OpProtoMake定义 .cc 文件，Backward Op不需要定义OpProtoMake
Op定义 .cc 文件
Kernel实现 CPU、CUDA共享Kernel实现在.h 文件中，否则，CPU 实现在.cc 文件中，CUDA 实现在.cu 文件中。
注册Op Op注册实现在.cc 文件；Kernel注册CPU实现在.cc 文件中，CUDA实现在.cu 文件中
+ + +实现新的op都添加至目录[paddle/fluid/operators](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/fluid/operators)下，文件命名以`*_op.h`（如有） 、 `*_op.cc` 、`*_op.cu`（如有）结尾。**系统会根据文件名自动构建op和其对应的Python扩展。** + + +下面以矩阵乘操作，即[MulOp](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/mul_op.cc)为例来介绍如何写带Kernel的Operator。 + + +## 实现C++类 + + +### 定义ProtoMaker类 + +矩阵乘法的公式：$Out = X * Y$, 可见该计算由两个输入，一个输出组成。 + +首先定义`ProtoMaker`来描述该Op的输入、输出，并添加注释： + +```cpp +class MulOpMaker : public framework::OpProtoAndCheckerMaker { + public: + MulOpMaker(OpProto *proto, OpAttrChecker *op_checker) + : OpProtoAndCheckerMaker(proto, op_checker) { + AddInput("X", "(Tensor), 2D tensor of size (M x K)"); + AddInput("Y", "(Tensor), 2D tensor of size (K x N)"); + AddOutput("Out", "(Tensor), 2D tensor of size (M x N)"); + AddComment(R"DOC( +Two Element Mul Operator. +The equation is: Out = X * Y +)DOC"); + } +}; +``` + +[`MulOpMaker`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/mul_op.cc#L76-L127)继承自`framework::OpProtoAndCheckerMaker`，构造函数含有2个参数： + + - `framework::OpProto` ： 前者存储Op的输入输出和参数属性，将用于Python API接口的生成。 + - `framework::OpAttrChecker` ：后者用于检查参数属性的合法性。 + +构造函数里通过`AddInput`添加输入参数，通过`AddOutput`添加输出参数，通过`AddComment`添加Op的注释。这些函数会将对应内容添加到`OpProto`中。 + +上面的代码在`MulOp`中添加两个输入`X`和`Y`，添加了一个输出`Out`，并解释了各自含义，命名请遵守[命名规范](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/fluid/dev/name_convention.md)。 + + +再以[`ScaleOp`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/scale_op.cc#L38-L55)为例： + +```cpp +template +class ScaleOpMaker : public framework::OpProtoAndCheckerMaker { + public: + ScaleOpMaker(OpProto *proto, OpAttrChecker *op_checker) + : OpProtoAndCheckerMaker(proto, op_checker) { + AddInput("X", "(Tensor) Input tensor of scale operator."); + AddOutput("Out", "(Tensor) Output tensor of scale operator."); + AddComment(R"DOC( +Scale operator +$$Out = scale*X$$ +)DOC"); + AddAttr("scale", + "(float, default 1.0)" + "The scaling factor of the scale operator.") + .SetDefault(1.0); + } +}; +``` + +这个例子有`AddAttr("scale", "...").SetDefault(1.0);` : 增加`scale`系数，作为参数属性，并且设置默认值为1.0。 + +### 定义GradProtoMaker类 +每个Op的必须有一个对应的GraProtoMaker，若未定制对应前向Op的GradProtoMaker，fluid提供了DefaultGradProtoMaker，默认注册会使用全部输入输出，包括Input, Output, Output@Grad等，使用不需要的变量的会造成显存浪费。 +下面示例定义了ScaleOp的GradProtoMaker。 + +```cpp +class ScaleGradMaker : public framework::SingleGradOpDescMaker { + public: + using framework::SingleGradOpDescMaker::SingleGradOpDescMaker; + + std::unique_ptr Apply() const override { + auto *grad_op = new framework::OpDesc(); + grad_op->SetType("scale"); + grad_op->SetInput("X", OutputGrad("Out")); + grad_op->SetOutput("Out", InputGrad("X")); + grad_op->SetAttr("scale", GetAttr("scale")); + return std::unique_ptr(grad_op); + } +}; +``` + +### 定义Operator类 + +下面实现了MulOp的定义： + +```cpp +class MulOp : public framework::OperatorWithKernel { + public: + using framework::OperatorWithKernel::OperatorWithKernel; + + protected: + void InferShape(const framework::InferShapeContext &ctx) const override { + //never use Input or Output if you want a to get a LoDTensor. + auto dim0 = ctx.Input("X")->dims(); + auto dim1 = ctx.Input("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("Out")->Resize({dim0[0], dim1[1]}); + } +}; +``` + +[`MulOp`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/mul_op.cc#L22)继承自`OperatorWithKernel`。`public`成员： + +```cpp +using framework::OperatorWithKernel::OperatorWithKernel; +``` + +这句表示使用基类`OperatorWithKernel`的构造函数，也可写成： + +```cpp +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`，通过该参数可获取到输入输出以及属性。它的功能是： + + - 做检查， 尽早报错：检查输入数据维度、类型等是否合法。 + - 设置输出Tensor的形状。 + +通常`OpProtoMaker`和`Op`类的定义写在`.cc`文件中，和下面将要介绍的注册函数一起放在`.cc`中 + +### 定义OpKernel类 + +`MulKernel`继承自`framework::OpKernel`，带有下面两个模板参数: + +- `typename DeviceContext`: 表示设备类型，不同设备(CPU、CUDA)共享同一个Kernel时，需加该模板参数，不共享则不加，一个不共享的例子是[`OnehotCrossEntropyOpKernel`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/cross_entropy_op.h#L43)。 + +- `typename T` : 表示数据类型，如`float`, `double`等。 + +需要为`MulKernel`类重写`Compute`接口。 + +- `Compute`接受一个输入参数：`const framework::ExecutionContext& context`。 + +- 与`InferShapeContext`相比，`ExecutionContext`增加了设备类型，同样可获取到输入输出和属性参数。 + +- `Compute`函数里实现`OpKernel`的具体计算逻辑。 + +Op的输入和输出可分别通过`ExecutionContext::Input()`和`ExecutionContext::Output()`获得。 + +**注意：** 若op的输入/输出的变量类型是`LoDTensor`（fluid默认所有的Tensor默认都是LoDTensor类型），请写成`ExecutionContext::Input()`和`ExecutionContext::Output()`，不要写`ExecutionContext::Input()`和`ExecutionContext::Output()`。因为若实际的变量类型为`SelectedRows`，`Input()`和`Output()`方法会将`SelectedRows`类型特化为`Tensor`，导致潜在的错误。 + +下面是 `MulKernel` `Compute`的实现： + + ```cpp + template + class MulKernel : public framework::OpKernel { + public: + void Compute(const framework::ExecutionContext& context) const override { + auto* X = context.Input("X"); + auto* Y = context.Input("Y"); + auto* Z = context.Output("Out"); + Z->mutable_data(context.GetPlace()); + auto& device_context = context.template device_context(); + math::matmul(*X, false, *Y, false, 1, Z, 0, device_context); + } + }; + ``` + +需要注意：**不同设备(CPU、CUDA)共享一个Op定义，是否则共享同一个`OpKernel`，取决于`Compute`调用的函数是否支持不同设备。** + +`MulOp`的CPU、CUDA实现共享同一个`Kernel`。`OpKernel`不共享的例子可以参考：[`OnehotCrossEntropyOpKernel`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/operators/cross_entropy_op.h#L43)。 + +为了使`OpKernel`的计算过程书写更加简单，并且CPU、CUDA的代码可以复用，我们通常借助 Eigen unsupported Tensor模块来实现`Compute`接口。关于在PaddlePaddle中如何使用Eigen库，请参考[使用文档](https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/fluid/dev/use_eigen_cn.md)。 + +到此，前向Op实现完成。接下来，需要在`.cc`文件中注册该op和kernel。 +反向Op类的定义，反向OpKernel的定义与前向Op类似，这里不再赘述。**但需注意反向Op没有`ProtoMaker`**。 + +### 注册Operator + +- 在`.cc`文件中注册前向、反向Op类，注册CPU Kernel。 + + ```cpp + namespace ops = paddle::operators; + REGISTER_OPERATOR(mul, ops::MulOp, ops::MulOpMaker, + paddle::framework::DefaultGradOpDescMaker) + REGISTER_OPERATOR(mul_grad, ops::MulGradOp) + REGISTER_OP_CPU_KERNEL(mul, ops::MulKernel); + REGISTER_OP_CPU_KERNEL(mul_grad, + ops::MulGradKernel); + ``` + + 在上面的代码中： + + - `REGISTER_OPERATOR` ： 注册`ops::MulOp`类，类型名为`mul`，该类的`ProtoMaker`为`ops::MulOpMaker`，注册`ops::MulOpGrad`，类型名为`mul_grad`。 + + - `REGISTER_OP_CPU_KERNEL` ：注册`ops::MulKernel`类，并特化模板参数为`paddle::platform::CPUPlace`和`float`类型，同理，注册`ops::MulGradKernel`类。 + + +- 在 `.cu`文件中注册CUDA Kernel。 + - 请注意，如果CUDA Kernel的实现基于Eigen unsupported模块，那么在 `.cu`的开始请加上宏定义 `#define EIGEN_USE_GPU`，代码示例如下： + + + ```cpp + // if use Eigen unsupported module before include head files + #define EIGEN_USE_GPU + + namespace ops = paddle::operators; + REGISTER_OP_CUDA_KERNEL(mul, ops::MulKernel); + REGISTER_OP_CUDA_KERNEL(mul_grad, + ops::MulGradKernel); + ``` + +### 编译 + +运行下面命令可以进行编译： + +``` +make mul_op +``` + +## 绑定Python + +系统会对新增的op自动绑定Python，并链接到生成的lib库中。 + +## 实现单元测试 + +单测包括对比前向Op不同设备(CPU、CUDA)的实现、对比反向OP不同设备(CPU、CUDA)的实现、反向Op的梯度测试。下面介绍介绍[`MulOp`的单元测试](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/fluid/tests/unittests/test_mul_op.py)。 + +### 前向Operator单测 + +Op单元测试继承自`OpTest`。各项更加具体的单元测试在`TestMulOp`里完成。测试Operator，需要： + +1. 在`setUp`函数定义输入、输出，以及相关的属性参数。 +2. 生成随机的输入数据。 +3. 在Python脚本中实现与前向operator相同的计算逻辑，得到输出值，与operator前向计算的输出进行对比。 +4. 反向计算已经自动集成进测试框架，直接调用相应接口即可。 + + + ```python + import unittest + import numpy as np + from op_test import OpTest + + + class TestMulOp(OpTest): + def setUp(self): + self.op_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'])} + + def test_check_output(self): + self.check_output() + + def test_check_grad_normal(self): + self.check_grad(['X', 'Y'], 'Out', max_relative_error=0.5) + + def test_check_grad_ingore_x(self): + self.check_grad( + ['Y'], 'Out', max_relative_error=0.5, no_grad_set=set("X")) + + def test_check_grad_ingore_y(self): + self.check_grad( + ['X'], 'Out', max_relative_error=0.5, no_grad_set=set('Y')) + ``` + + 上面的代码首先导入依赖的包，下面是对`setUp`函数中操作的重要变量的详细解释： + + - `self.op_type = "mul" ` : 定义类型，与operator注册时注册的类型一致。 + - `self.inputs` : 定义输入，类型为`numpy.array`，并初始化。 + - `self.outputs` : 定义输出，并在Python脚本中完成与operator同样的计算逻辑，返回Python端的计算结果。 + +### 反向operator单测 + +而反向测试中： + +- `test_check_grad_normal`中调用`check_grad`使用数值法检测梯度正确性和稳定性。 + - 第一个参数`["X", "Y"]` : 指定对输入变量`X`、`Y`做梯度检测。 + - 第二个参数`"Out"` : 指定前向网络最终的输出目标变量`Out`。 + - 第三个参数`max_relative_error`：指定检测梯度时能容忍的最大错误值。 + +- `test_check_grad_ingore_x`和`test_check_grad_ingore_y`分支用来测试只需要计算一个输入梯度的情况。 + + +### 编译和执行 + +`python/paddle/fluid/tests/unittests/` 目录下新增的 `test_*.py` 单元测试会被自动加入工程进行编译。 + +请注意，**不同于Op的编译测试，运行单元测试测时需要编译整个工程**，并且编译时需要打开`WITH_TESTING`, 即`cmake paddle_dir -DWITH_TESTING=ON`。编译成功后，执行下面的命令来运行单元测试： + +```bash +make test ARGS="-R test_mul_op -V" +``` + +或者: + +```bash +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等宏定义，基本格式如下： + +``` +PADDLE_ENFORCE(表达式, 错误提示信息) +PADDLE_ENFORCE_EQ(比较对象A, 比较对象B, 错误提示信息) +``` + +如果表达式为真，或者比较对象A=B，则检查通过，否则会终止程序运行，向用户反馈相应的错误提示信息。 +为了确保提示友好易懂，开发者需要注意其使用方法。 + +#### 总体原则 + +任何使用了PADDLE_ENFORCE与PADDLE_ENFORCE_**检查的地方，必须有详略得当的备注解释！**错误提示信息**不能为空！ + +#### 提示信息书写标准 + +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 ：未写提示信息 + ``` + PADDLE_ENFORCE(ctx->HasInput("X"), ""); + ``` + 问题示例2 ：提示信息过于简单 + ``` + PADDLE_ENFORCE(i != nullptr, "i must be set"); // i是什么？ + ``` + +2. 在报错信息中使用开发人员定义的变量缩写，不易理解！ + + 问题示例： + ``` + PADDLE_ENFORCE(forward_pd != nullptr, + "Fail to find eltwise_fwd_pd in device context"); //eltwise_fwd_pd用户可能看不懂 + ``` + +3. OP内部调用非法接口：Op内部如果出现Output = ShareDataWith(Input) + 问题示例： + ```cpp + auto *out = ctx.Output("Out"); + auto *in = ctx.Input("X"); + 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.` + + 正确示例： + ``` + PADDLE_ENFORCE(ctx->HasInput("Input"), + "Input(Input) of LSTMP operator should not be null."); + ``` + +- 反向Op的输入输出检查，要写明反向Op的名字 + + 正确示例： + ``` + PADDLE_ENFORCE(ctx->HasInput("X"), + "Input(X) of LoDResetGrad opreator should not be null."); + ``` diff --git a/doc/fluid/advanced_usage/development/new_op/op_notes.md b/doc/fluid/advanced_usage/development/new_op/op_notes.md index e48f804d0d0..501b81c6ad0 100644 --- a/doc/fluid/advanced_usage/development/new_op/op_notes.md +++ b/doc/fluid/advanced_usage/development/new_op/op_notes.md @@ -1,4 +1,4 @@ -# op相关的一些注意事项 +# op相关注意事项 ## Fluid中Op的构建逻辑 ### 1.Fluid中Op的构建逻辑 From b5948c782f7afea7952bd08a08e2350fb8f7291b Mon Sep 17 00:00:00 2001 From: shanyi15 Date: Sat, 2 Mar 2019 16:32:45 +0800 Subject: [PATCH 3/3] update_index --- doc/fluid/advanced_usage/development/new_op/index_cn.rst | 7 ++++++- doc/fluid/beginners_guide/install/Tables.md | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/fluid/advanced_usage/development/new_op/index_cn.rst b/doc/fluid/advanced_usage/development/new_op/index_cn.rst index a1b2866a49e..fc56472ce91 100644 --- a/doc/fluid/advanced_usage/development/new_op/index_cn.rst +++ b/doc/fluid/advanced_usage/development/new_op/index_cn.rst @@ -2,10 +2,15 @@ 新增Operator ############# -在这里，您将掌握如何添加新的Operator，本部分有如下几个部分： +本部分将指导您如何新增Operator，也包括一些必要的注意事项 + +- `如何写新的op <./new_op.html>`_ + +- `op相关注意事项 <./op_notes.html>`_ .. toctree:: :hidden: new_op.md op_notes.md + diff --git a/doc/fluid/beginners_guide/install/Tables.md b/doc/fluid/beginners_guide/install/Tables.md index aedc16f44f5..1644f5bed5e 100644 --- a/doc/fluid/beginners_guide/install/Tables.md +++ b/doc/fluid/beginners_guide/install/Tables.md @@ -259,7 +259,7 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。

您可以在 [Release History](https://pypi.org/project/paddlepaddle-gpu/#history) 中找到PaddlePaddle-gpu的各个发行版本。 -需要注意的是，在v1.3版本中， paddlepaddle-gpu命令 在windows环境下，会默认安装CUDA 8.0和cuDNN 5编译的PaddlePaddle +需要注意的是，在v1.3版本中， paddlepaddle-gpu 命令在windows环境下，会默认安装CUDA 8.0和cuDNN 5编译的PaddlePaddle ***