Design Of Refactor Topology

doc/design/layer_generation/00.how_to_write_a_layer.md

@@ -0,0 +1,249 @@
+# 如何写一个Layer
+
+这个文档是一个概念性的文档，描述在重构后用户如何写一个Layer。
+
+## 基本目标
+
+用户只需要写Layer的计算信息，而不需要写配置解析器，也不修改写Protobuf的内容。就可以完成Layer的书写。
+
+## 实现方式
+
+### 总体概览
+
+* 在注册Layer的时候，不只注册Layer的C++类型，同时注册Layer的元信息，元信息使用Protobuf来表示。
+* 使用全局静态函数生成Layer的元信息。代码生成器通过Layer访问元信息来生成配置解析器(ConfigParser)
+* 将神经网络参数推导(每一个参数的size多大，输出size是多大)功能，移至Paddle C++ Core中
+
+### Layer元信息
+
+Paddle将**每种**Layer在C++端注册元信息，将元信息声明成Protobuf。
+
+主要的元信息有两个
+
+####  LayerDef
+* LayerDef 是描述了每**种**Layer的元信息，他包含每种Layer的类型名，注释，可以接受的输入类型，参数类型，Layer的其他属性。不包括这个Layer输出什么类型
+* 注意这是**元信息**。一个`LayerDef`描述了一**种**`Layer`的类型，而不是一**个**`Layer`的具体参数。
+* 同理，LayerDef中使用的 `ArgumentDef`描述的是某**一种输入参数的类型**，而不是某一个具体的输入参数是什么。`AttributeDef`是表示某一个属性(Attribute)的**类型**，而不是这个属性的具体参数。
+* 一个全连接层(FullyConnected， 下简写为FC)的LayerDef可能为
+
+```json
+{
+  "type": "fc",
+  "description": "Fully Connected Layer is the simplest layer in nerual network. ...",
+  "inputs" : [
+    {
+      "name": "input",
+      "description": "The input of fully connected layer, could be several.",
+      "data_type": ["Dense", "Sparse", "SparseInt", "Int"],
+      "seq_nested_level": [0, 1, 2],
+      "repeatable": true
+    }
+  ],
+  "parameter_attr": [
+    {
+      "attributes": [{
+        "name": "weight_decay",
+        "type": "float",
+        "description": "The weight decay rate of parameter, used to implement L2 Norm",
+        "default_value": 0.0,
+        "max_value": 1.0,
+        "min_value": 0.0
+      }, {
+        "name": "gradient_clipping",
+        "type": "float",
+        "description": "The gradient clipping threshold",
+        "default_value": 0.0,
+        "min_value": 0.0
+      }]
+    }
+  ],
+  "bias_attr": {
+    "attributes": [{
+      "name": "weight_decay",
+      "type": "float",
+      "description": "The weight decay rate of parameter, used to implement L2 Norm",
+      "default_value": 0.0,
+      "max_value": 1.0,
+      "min_value": 0.0
+    }]
+  },
+  "layer_attr":  [
+    {
+      "name": "dropout_rate",
+      "type": "float",
+      "description": "The dropout rate of this layer",
+      "default_value": 0.0,
+      "max_value": 1.0,
+      "min_value": 0.0
+    }
+  ]
+}
+```
+
+#### LayerOutputType
+
+* LayerOutputType 表示的是，某一个Layer输入输出具体是什么类型的(不是输入输出具体是什么值)。这是在运行时中计算出来的。
+* 某一个FC Layer的LayerOutputType可能是
+
+```json
+{
+	"type": "Dense",
+	"size": 200,
+	"seq_nested_level": 2
+}
+```
+
+#### Layer元信息的Protobuf定义
+
+下面是Layer元信息的Protobuf定义。
+
+```protobuf
+enum DataType {
+  DENSE=0,
+  SPARSE_INT=1,
+  SPARSE=2,
+  INT=3,
+}
+
+enum AttributeType {
+  STRING=0,
+  INT=1,
+  FLOAT=2,
+  DOUBLE=3,
+  ...
+}
+
+message Attribute {
+  oneof {
+    string s_value = 1;
+    int    i_value = 2;
+    float  f_value = 3;
+    ...
+  }
+}
+
+message AttributeDef {
+  required string name = 1;  // supported attribute name.
+  required AttributeType type = 2;  // supported type.
+  required string description = 3; // Attribute description & comments.
+
+  optional Attribute default_value = 4; // default value.
+  optional Attribute max_value = 5;    // max value.
+  optional Attribute min_value = 6;   // min value.
+}
+
+// Argument Define the Supported InputTypes.
+message ArgumentDef {
+   	// Supported Input Type.
+   	// The data type of input/output.
+   	repeated DataType data_type = 1; 
+   	// 0 means it is not a sequence. 1 means a plain sequence. 2 means a nested sequence.  One layer could support many sequence type.
+   	repeated uint32 seq_nested_level = 2;
+
+   	// In paddle, some layer can handle variable length input.
+   	// If some input is repeatable, it means there are one or many inputs as the same input type.
+   	required bool repeatable = 3;
+
+	// In Paddle, a layer could return many outputs. Each output contains a different name.
+   	required string name = 4;
+
+   	// Comments
+  	required string description = 5;
+}
+
+message LayerDef {
+    required string type = 1;  // Layer type, such as 'fc', 'conv'
+    required string description = 2;  // Layer description & comments.
+
+
+    repeated ArgumentDef inputs = 3;
+
+
+    message ParameterDef {
+        repeated AttributeDef attributes = 1;  // Parameter Attributes Definition.
+    }
+
+    // Each input of Paddle Layer should contain zero or one parameter.
+    // so parameter_attr.size() == inputs.size()
+    repeated ParameterDef parameter_attr = 5;
+
+    // Set the bias attribute, If this layer support bias.
+    optional ParameterDef bias_attr = 6;
+
+    // The Layer Attributes.
+    repeated AttributeDef layer_attr = 7;
+}
+
+// Define the layer's output types by given input types.
+message LayerOutputType {
+	// Output name, Each Paddle Layer could have multiple outputs.
+	optional string name = 1;
+
+	// Output type
+	required DataType type = 2;
+	required uint32 size = 3;
+	required uint32 seq_nested_level = 4;
+
+}
+```
+
+### C++ 端暴露LayerDef/LayerOutputType Protobuf.
+
+基本想法:
+
+* 对于每一种类型的Layer，Paddle根据Layer的名字约定两个全局函数的名字。例如，对于FC Layer，全局函数的名字是 `__get_fc_layer_definition__` 和 `__get_fc_layer_output_type__`。 这两个全局函数通过`REGISTER_LAYER`自动生成。
+* 对于每个Layer实现的时候，实现两个静态(`static`)函数，分别实现这两个函数。
+* 对于获得LayerOutputType的函数,同时完成**神经网络推导**过程。即在运行时设置ParameterSize，动态添加Layer的辅助输入等等。
+
+举例来说，例如对于FCLayer，可能的实现为:
+
+```C++
+
+class FCLayer :public Layer {
+public:
+  void init() { ... }
+  void forward() { ... }
+  void backward() { ... }
+
+  static void getLayerDefinition(LayerDef& def) {
+    LayerDefinition::supportSize(def);
+    LayerDefinition::supportDropout(def);
+    LayerDefinition::addInput()
+        .setRepeatable(True)
+        .addSupport({ InputType::Dense, InputType::SparseInt, InputType::Sparse })
+        .addSupportSeqLevel({0, 1, 2})
+        .addDoc("FC Layer is fully connected. Blah blah blah...");
+  }
+
+  static std::vector<LayerOutputType> getLayerOutputType(const std::vector<LayerOutputDef>& inputs,
+  	    LayerConfig& self) {
+  	 // self could be modified, for calculating parameter size, etc.
+    LayerOutputDef out;
+    out.set_size(self.size());
+    out.set_type(InputType::Dense);
+    out.set_seq_nested_level(inputs[0].seq_nested_level);
+    return { out };
+  }
+};
+
+
+REGISTER_LAYER(fc, FCLayer);
+```
+
+### 配置解析运行流程
+
+配置解析(config parser)的运行流程如下图所示:
+
+![配置解析运行流程](http://api.paddlepaddle.org/graphviz?dot=https://gist.githubusercontent.com/reyoung/0a3d7bfb44e45d61d7bd80b26ca18fbc/raw/4177e2ca56f0410a65338a089cf4e37b9bb87c93/gistfile1.txt)
+
+1. 读取Paddle Core中所有的Layer的元信息， LayerDef。
+1. 根据所有Layer的元信息，LayerDefs生成解析器ConfigParser
+	* 如何生成解析器是每个语言自定义的过程
+	* 这个过程可以是离线的过程。即先将所有Layer的LayerDef写入到一个文件里，然后其他语言读取这个文件，来生成代码。
+	* 这个过程同时也可以是在线的过程。比如对于Python这种动态类型语言，运行时生成函数比较简单，就没必要先生成代码，再生成函数了。
+1. 使用ConfigParser，解析用户的配置文件`trainer_config.conf`。
+	* 这时，解析器只返回一个调用图，即Layer与Layer之间的调用关系(`Graph Protobuf`)，而不返回真正的`ModelConfig`。
+	* 这个Graph Protobuf非常简单，只包括调用了哪个Layer，设置了那个Attribute即可
+1. 讲这个调用图传递给Paddle Core，生成真正的`ModelConfig`。
+	* 对于`GraphProtobuf`中每一个项目，生成每一个LayerConfig。
+	* 进而顺序执行 `getLayerOutputType`获得这个Layer的输出，并完成神经网络参数推导过程。再将这个LayerConfig传递给下一个Layer。

doc/design/layer_generation/01.use_map_in_protobuf.md

@@ -0,0 +1,62 @@
+# 在Protobuf中支持多种类型的字典字段
+
+## 背景
+
+这项工作的背景是我们要使用代码生成器或者运行时自动生成模型配置函数，并在运行时自动检查配置的正确性。
+
+
+现阶段如何编写一个Layer呢？可以参考[文章](http://www.paddlepaddle.org/doc/dev/new_layer/index.html)。主体可以分为以下几个步骤:
+
+* 在[Protobuf文件](https://github.com/PaddlePaddle/Paddle/blob/develop/proto/ModelConfig.proto#L284)里，添加里面编写这个Layer需要的参数。如果这个Layer只需要size等常见配置，这个protobuf已经包含，复用即可。但是如果这个Layer有其他自定义的参数，就需要在这个文件里面添加字段。
+	* 也就是目前新建Layer和修改Protobuf文件是强耦合的。且这个protobuf message已经有了52个字段了。
+* 在C++端实现Layer
+* 在Python端实现这个Layer的解析函数，Wrapper，V2Layer等等。
+
+
+这个设计文档，旨在解决 Protobuf文件和Layer之间的耦合性，让用户新建一个Layer的时候不需要改Protobuf。并且，极大的简化Protobuf文件。
+
+## 实现方式
+
+使用Protobuf中的[map](https://developers.google.com/protocol-buffers/docs/proto#maps)和[oneof](https://developers.google.com/protocol-buffers/docs/proto#oneof)将Paddle Potobuf中的配置简化成一个`map<string, variant>`形式。
+
+简单的示例代码为:
+
+```protobuf
+message Attribute {
+    oneof AttributeField {
+   	     string s_value = 1;
+   	     int    i_value = 2;
+   	     float  f_value = 3;
+   	     double d_value = 4;
+   	     ...
+    }
+}
+
+message LayerConfig {
+   required string name = 1;
+   required string type = 2;
+   map<string, Attribute> attributes = 3;
+}
+```
+
+其中，每种Layer都有不同的`type`。 而`attributes`作为一个`map`，他的Key可以被每个Layer自己定义。对于一些常见的配置参数，例如`activation`，可以共享一个key。对于一些layer专有属性，可以使用`.`分隔开。例如，对于CTCLayer可以设置`blank`属性，它的Key可以为`ctc.blank`。
+
+这样，实现一个新的Layer，用户就不需要修改Protobuf消息了。并且，用户写一个新的Layer的时候，可以说明自己需要哪些属性，而这些属性的取值范围又是如何的。这样，我们在生成Python配置函数的代码时，可以生成运行时检查的代码。避免用户错误的配置神经网络。
+
+
+## 实现问题
+
+实现这项工作目前来看有如下几个先决条件需要解决:
+
+* 这项工作会修改 `Python <==> Paddle core`中间的protobuf消息定义，对于Python端Layer解析函数，需要有覆盖完整的单元测试，才能保证这一步工作进行完之后，系统行为没有问题。否则，直接修改 Protobuf 风险较高。
+* `oneof`与`map`是`protobuf2`语法，但是这是在`Protobuf 3.0`之后的代码库中添加的功能，如果Paddle依赖这个功能，那么Paddle必须依赖Protobuf 3.0以上的Protobuf版本。
+
+
+## 总结
+
+* 最终目的: 用户只需要写Layer的C++实现，剩下的Python代码自动生成
+* 阶段目的: 解耦合 Protobuf与Layer的C++实现
+* 解决办法: 用`map`和`oneof`，将属性变成一个多种类型的字典
+* 问题:
+	* 需要先完善config_parser的单测，增加单测覆盖率
+	* 这会让Paddle强制依赖`Protobuf 3.0+`的Protobuf