From dc43b7c288a7b598aad21a9a400412f329ae264d Mon Sep 17 00:00:00 2001 From: Tink_Y <31891223+tink2123@users.noreply.github.com> Date: Mon, 6 Aug 2018 17:48:35 +0800 Subject: [PATCH] =?UTF-8?q?=E5=B0=86Paddle=20repo=200.14.0=E7=9A=84?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=90=8C=E6=AD=A5=E5=88=B0Fluiddoc=20repo=20?= =?UTF-8?q?0.14.0=20(#39)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * modified development * modified beginners_guide * modified faq * modified user_guides --- .../deploy/anakin_arm_benchmark.md | 1 - .../advanced_usage/deploy/anakin_example.md | 29 +- .../deploy/anakin_gpu_benchmark.md | 5 - .../advanced_usage/deploy/anakin_tutorial.md | 640 +++++++++++++++++- .../deploy/convert_paddle_to_anakin.md | 74 +- .../deploy/how_to_add_anakin_op.md | 406 ++++++++++- .../how_to_support_new_device_in_anakin.md | 460 ++++++++++++- source/advanced_usage/deploy/index_anakin.rst | 4 +- .../advanced_usage/deploy/install_anakin.md | 70 +- source/advanced_usage/deploy/mobile_build.md | 60 +- source/advanced_usage/deploy/mobile_dev.md | 73 +- .../deploy/run_anakin_on_arm.md | 152 ++++- .../development/gpu_profiling_cn.rst | 243 ++++++- .../development/host_memory_profiling_cn.md | 2 +- source/advanced_usage/index.rst | 1 - source/advanced_usage/pics/anakin_fm_ch.png | Bin 0 -> 45319 bytes .../basics/image_classification/index.md | 8 +- .../basics/label_semantic_roles/index.md | 28 +- .../basics/machine_translation/index.md | 32 +- .../basics/recommender_system/index.md | 18 +- .../basics/understand_sentiment/index.md | 20 +- .../beginners_guide/basics/word2vec/index.md | 32 +- .../beginners_guide/install/install_doc.rst | 174 +++-- .../quick_start/fit_a_line/README.cn.md | 120 +++- .../quick_start/recognize_digits/README.cn.md | 69 +- source/faq/faq.rst | 15 +- source/faq/index_cn.rst | 9 + .../howto/configure_simple_model/index.rst | 8 +- .../inference/build_and_install_lib_cn.rst | 99 +++ source/user_guides/howto/inference/index.rst | 11 + .../howto/inference/native_infer.rst | 108 +++ .../howto/prepare_data/feeding_data.rst | 8 +- .../user_guides/howto/prepare_data/index.rst | 10 +- .../prepare_data/use_recordio_reader.rst | 26 +- .../howto/training/checkpoint_doc_cn.md | 2 +- .../howto/training/checkpoint_doc_en.md | 2 +- .../howto/training/save_load_variables.rst | 18 +- .../howto/training/single_node.rst | 26 +- .../howto/training/test_while_training.rst | 22 +- source/user_guides/index.rst | 1 + source/user_guides/models/index.rst | 7 +- 41 files changed, 2819 insertions(+), 274 deletions(-) create mode 100644 source/advanced_usage/pics/anakin_fm_ch.png create mode 100644 source/faq/index_cn.rst create mode 100644 source/user_guides/howto/inference/build_and_install_lib_cn.rst create mode 100644 source/user_guides/howto/inference/index.rst create mode 100644 source/user_guides/howto/inference/native_infer.rst diff --git a/source/advanced_usage/deploy/anakin_arm_benchmark.md b/source/advanced_usage/deploy/anakin_arm_benchmark.md index bef1e20eb..08ea379f8 100644 --- a/source/advanced_usage/deploy/anakin_arm_benchmark.md +++ b/source/advanced_usage/deploy/anakin_arm_benchmark.md @@ -54,4 +54,3 @@ 3. 接着在测试机含有Anakin model的目录中运行'./benchmark_arm ./ anakin_model.anakin.bin 1 10 10 1' 命令 4. 最后，终端显示器上将会打印该模型的运行时间 5. 其中运行命令的参数个数和含义可以通过运行'./benchmark_arm'看到 - diff --git a/source/advanced_usage/deploy/anakin_example.md b/source/advanced_usage/deploy/anakin_example.md index 4ee61319f..e6b9e18fe 120000 --- a/source/advanced_usage/deploy/anakin_example.md +++ b/source/advanced_usage/deploy/anakin_example.md @@ -1 +1,28 @@ -../../../anakin/examples/example_introduction_cn.md \ No newline at end of file +# Example +Anakin目前只支持NCHW的格式 +示例文件在test/framework/net下 + +## 在NV的GPU上运行CNN模型 +示例文件为打开example_nv_cnn_net.cpp，整体流程如下： +- 将模型的的path设置为anakin模型的路径，初始化NV平台的图对象。 anakin模型可以通过转换器转化caffe或fluid的模型得到 +- 根据模型设置网络图的输入尺寸，进行图优化 +- 根据优化后的网络图初始化网络执行器 +- 取出网络的输入tensor，将数据拷贝到输入tensor +- 运行推导 +- 取出网络的输出tensor + +以NV平台为例演示Anakin框架的使用方法，注意编译时需要打开GPU编译开关 + +## 在X86上运行RNN模型 +示例文件为example_x86_rnn_net.cpp +整体流程与在NV的GPU上运行CNN模型相似，不同之处如下： +- 使用X86标识初始化图对象和网络执行器对象 +- rnn模型的输入尺寸是可变的，初始化图时的输入维度是维度的最大值，输入维度N代表总的词的个数。还需要设置输入tensor的seq_offset来标示这些词是如何划分为句子的,如{0,5,12}表示共有12个词，其中第0到第4个词是第一句话，第5到第11个词是第二句话 + +以X86平台为例演示Anakin框架的使用方法，注意编译时需要打开X86编译开关 + +## 在NV的GPU上使用Anakin的线程池运行CNN模型 +示例文件为example_nv_cnn_net_multi_thread.cpp ，示例使用worker的同步预测接口 +整体流程与在NV的GPU上运行CNN模型相似，不同之处如下： +- 用模型地址和线程池大小初始化worker对象 +- 将输入tensor注入任务队列,获得输出tensor diff --git a/source/advanced_usage/deploy/anakin_gpu_benchmark.md b/source/advanced_usage/deploy/anakin_gpu_benchmark.md index 343e7ae74..667f9396f 100644 --- a/source/advanced_usage/deploy/anakin_gpu_benchmark.md +++ b/source/advanced_usage/deploy/anakin_gpu_benchmark.md @@ -168,8 +168,3 @@ We tested them on single-GPU with single-thread. > 2. Switch to *source_root/benchmark/CNN* directory. Use 'mkdir ./models' to create ./models and put anakin models into this file. > 3. Use command 'sh run.sh', we will create files in logs to save model log with different batch size. Finally, model latency summary will be displayed on the screen. > 4. If you want to get more detailed information with op time, you can modify CMakeLists.txt with setting `ENABLE_OP_TIMER` to `YES`, then recompile and run. You will find detailed information in model log file. - - - - - diff --git a/source/advanced_usage/deploy/anakin_tutorial.md b/source/advanced_usage/deploy/anakin_tutorial.md index fac95f291..5efbc89ab 120000 --- a/source/advanced_usage/deploy/anakin_tutorial.md +++ b/source/advanced_usage/deploy/anakin_tutorial.md @@ -1 +1,639 @@ -../../../anakin/docs/Manual/Tutorial_ch.md \ No newline at end of file +# Anakin 使用教程 ## + +本教程将会简略的介绍Anakin的工作原理，一些基本的Anakin API，以及如何调用这些API。 + +## 内容 ### + +- [Anakin的工作原理](#principle) +- [Anakin APIs](#api) +- [示例代码](#example) + +## Anakin的工作原理 ### + +![Anakin_principle](../pics/anakin_fm_ch.png) + +用Anakin来进行前向计算主要分为三个步骤： + +- 将外部模型通过[Anakin Parser](Converter_ch.md)解析为Anakin模型 + 在使用Anakin之前，用户必须将所有其他模型转换成Anakin模型，我们提供了转换脚本，用户可通过[Anakin Parser](Converter_ch.md)进行模型转换。 +- 生成Anakin计算图 + 加载Anakin模型生成原始计算图，然后需要对原始计算图进行优化。你只需要调用相应的API优化即可。 +- 执行计算图 + Anakin会选择不同硬件平台执行计算图。 + + +## Anakin APIs ### +### Tensor #### + +`Tensor`提供基础的数据操作和管理，为ops提供统一的数据接口。`Tensor`包含以下几个属性： + +- Buffer + 数据存储区 +- Shape + 数据的维度信息 +- Event + 用于异步计算的同步 + + `Tensor` 类包含三个`Shape`对象， 分别是`_shape`, `_valid_shape`和 `offset`。 `_shape`为`tensor`真正空间信息，`_valid_shape`表示当前`tensor`使用的空间信息， `_offset`表示当前`tensor`数据指针相对于真正数据空间的信息。 `Tensor`不同维度与分别与数学中的向量、矩阵等相对应如下表所示。 + + +Dimentions | Math entity | + :----: | :----: +1 | vector +2 | matrix +3 | 3-tensor +n | n-tensor + +#### 声明tensor对象 + +`Tensor`接受三个模板参数: + + +```c++ + template + class Tensor .../* Inherit other class */{ + //some implements + ... + }; +``` + +TargetType是平台类型，如X86，GPU等等，在Anakin内部有相应的标识与之对应；datatype是普通的数据类型，在Anakin内部也有相应的标志与之对应；[LayOutType](#layout)是数据分布类型，如batch x channel x height x width [NxCxHxW], 在Anakin内部用一个struct来标识。 Anakin中数据类型与基本数据类型的对应如下: + +1. TargetType + + Anakin TargetType | platform + :----: | :----:| + NV | NVIDIA GPU + ARM | ARM + AMD | AMD GPU + X86 | X86 + NVHX86 | NVIDIA GPU with Pinned Memory + +2. DataType + +Anakin DataType | C++ | Description +:---: | :---: | :---: | +AK_HALF | short | fp16 +AK_FLOAT | float | fp32 +AK_DOUBLE | double | fp64 +AK_INT8 | char | int8 +AK_INT16 | short | int16 +AK_INT32 | int | int32 +AK_INT64 | long | int64 +AK_UINT8 | unsigned char | uint8 +AK_UINT16 | unsigned short | uint8 +AK_UINT32 | unsigned int | uint32 +AK_STRING | std::string | / +AK_BOOL | bool | / +AK_SHAPE | / | Anakin Shape +AK_TENSOR | / | Anakin Tensor + + +3. LayOutType + +Anakin LayOutType ( Tensor LayOut ) | Tensor Dimention | Tensor Support | Op Support +:---: | :---: | :---: | :---: | +W | 1-D | YES | NO +HW | 2-D | YES | NO +WH | 2-D | YES | NO +NW | 2-D | YES | YES +NHW | 3-D | YES |YES +NCHW ( default ) | 4-D | YES | YES +NHWC | 4-D | YES | NO +NCHW_C4 | 5-D | YES | YES + + +理论上，Anakin支持申明1维以上的tensor，但是对于Anakin中的Op来说，只支持NW、NHW、NCHW、NCHW_C4这四种LayOut，其中NCHW是默认的LayOutType，NCHW_C4是专门针对于int8这种数据类型的。 + + +例子 + +> 下面的代码将展示如何使用tensor， 我们建议先看看这些示例。 + +> 要想获得更多关于tensor的信息， 请参考 *soure_path/core/tensor.h* + +> 1. 使用shape对象初始化tensor +``` c++ + //create a null tensor. A null tensor holds for nothing. + //tensor's buffer is resident at CPU and its datatype is AK_FLOAT. + //tensor's Layout is NCHW(default) + Tensor mytensor; + + //1. using shape object to create a tensor. + Shape shape1(NUM); //1-D shape. NUM is the number of dimention. + Tensor mytensor1(shape1); //1-D tensor. + + // A 4-D shape + Shape shape2(N, C, H, W); // batch x channel x height x width +``` + +>`注意：Shape的维度必须和tensor的`[LayoutType](#layout)`相同，比如Shape(N,C,H,W), 那么Tensor的 LayoutType必须是NCHW，否则会出错。如下列代码所示` + + +```c++ + // A 4-D tensor. + Tensor mytensor2(shape2); //right + + //A 4-D tensor which is resident at GPU and its datatype is AK_INT8 + Tensor mytensor3(shape2); //right + + Tensor mytensor4(shape2); //wrong!! shape's dimetion must be equal to tensor's Layout. + Tensor mytensor5(shape2); //wrong!!!! + +``` + +> 2. 使用现有的数据和shape初始化tensor + +```c++ + + /** + * A construtor of Tensor. + * data_ptr is a pointer to any data type of data + * TargetType is type of a platform [Anakin TargetType] + * id : device id + * shape: a Anakin shape + */ + Tensor(Dtype* data_ptr, TargetType_t target, int id, Shape shape); + + //using existing data feed to a tensor + Tensor mytensor(data_ptr, TargetType, device_id, shape); //shape must has dimention (N, C, H, W). + +``` + +> 3. 使用tensor初始化tensor + +```c++ + Tensor tensor(exist_tensor); +``` + + +> 提示： 你可以用` typedef Tensor Tensor4d_X86 `方便定义tensor + + +#### 填充tensor数据区 + + +填充数据区得看你申明tensor的方式， 下面展示了如何填充tensor的数据区。 + +```c++ +首先来看看tensor的四种声明方式： + +1. Tensor mytensor; +2. Tensor mytensor1(shape1); +3. Tensor mytensor(data_ptr, TargetType, device_id, shape); +4. Tensor tensor(exist_tensor); + + +相关的声明方式的数据填充方法如下： + +1：声明一个空的tensor，此时没有为其分配内存，所以，我们需要手动的为其分配内存。 + + //parama shape + mytensor.re_alloc(Shape shape); + + //Get writable pointer to mytensor. + //parama index (int): where you start to write. + //Dtype is your data type such int, float or double. + Dtype *p = mytensor.mutable_data(index/*=0*/); + //write data to mytensor + for(int i = 0; i < mytensor.size(); i++){ + p[i] = 1.0f; + } + //do something ... + +2: 这种声明方式会自动分配内存 + + //Get writable pointer to mytensor. + //parama index (int): where you start to write. + //Dtype is your data type such int, float or double. + Dtype *p = mytensor1.mutable_data(index/*=0*/); + //write data to mytensor + for(int i = 0; i < mytensor.size(); i++){ + p[i] = 1.0f; + } + //do something ... + + +3：在该种声明方式中，我们仍不需要手动为其分配内存。但在构造函数内部是否为其分配内存，得依情况而定。如果data_ptr和申明的 +tensor都在都一个目标平台上，那么该tensor就会与data_ptr共享内存空间，相反，如果他们不在同一个平台上（如data_ptr在X86上，而 +tensor在GPU上），那么此时tensor就会开辟一个新的内存空间，并将data_ptr所指向的数据拷贝到tensor的buffer中。 + + //Get writable pointer to mytensor. + //parama index (int): where you start to write. + //Dtype is your data type such int, float or double. + Dtype *p = mytensor.mutable_data(index/*=0*/); + //write data to mytensor + for(int i = 0; i < mytensor.size(); i++){ + p[i] = 1.0f; + } + //do something ... + +4：该种方式仍不需要手动分配内存 + + //Get writable pointer to mytensor. + //parama index (int): where you start to write. + //Dtype is your data type such int, float or double. + Dtype *p = mytensor.mutable_data(index/*=0*/); + //write data to mytensor + for(int i = 0; i < mytensor.size(); i++){ + p[i] = 1.0f; + } + //do something ... + + +另外，你还可以获取一个tensor的可读指针，示例如下： + //Get read-only pointer to mytensor. + //parama index (int): where you start to read. + //Dtype is your data type such int, float or double. + Dtype *p = mytensor.data(index/*=0*/); + //do something ... +``` + +如果想更详细的了解tensor，请查阅*soure_path/saber/core/tensor.h* + +#### 获取tensor的shape + +```c++ +//some declarations +// ... +Shape shape = mytensor.shape(); + +//Get a first dimetion size of tesor, if it has. +int d1 = shape[0]; + +//Get a second dimention size of tensor, if it has. +int d2 = shape[1]; + +... + +//Get a n-th dimention size of tensor, if it has. +int dn = shape[n-1]; + + +//Get a tensor's dimention +int dims = mytensor.dims(); + +//Get the size of tensor. +//size = d1 x d2 x ... x dn. +int size = mytensor.size(); + +//Get the size of tensor at interval [Di, Dj) +// form i-th dimention to j-th dimention, but not including the j-th dimention. +// which means di x (di+1) x ... x (dj -1) +int size = mytensor.count(start, end); +``` + +#### 设置tensor的shape + +我们可以用tensor的成员函数set_shape来设置tensor的shape。 下面是set_shape的定义 + + +```c++ +/** + * \brief set a tensor's shape + * \param valid_shape [a Shape object] + * \param shape [a Shape object] + * \param offset [a Shape object] + * \return the status of this operation, that means whether it success * or not. + */ +SaberStatus set_shape(Shape valid_shape, Shape shape = Shape::zero(TensorAPI::layout_dims::value), Shape offset = Shape::minusone(TensorAPI::layout_dims::value)); +``` + +这个成员函数只设置tensor的shape。这些shape对象(valid_shape, shape, offset)的[LayOutType](#layout)必须和当前的tensor的相应三个shape对象的LayOutType相同，如果不同就会出错，返回SaberInvalidValue。 如果相同，那么将成功设置tensor的shape。 + +```c++ + +// some declarations +// ... +//valid_shape, shape , offset are Shape object; +//All these Shape object's LayOutType must be equal to mytensor's. +mytensor.set_shape(valid_shape, shape, offset); + +``` + +#### 重置 tensor的shape + +```c++ +//some declarations +Shape shape, valid_shape, offset; + +//do some initializations +... +mytensor.reshape(valid_shape, shape, offset); +``` + +注意： Reshape操作仍然需要shape的[LayOutType](#layout) 与tensor的相同 + + +### Graph ### + +`Graph`类负责加载Anakin模型生成计算图、对图进行优化、存储模型等操作。 + +#### 图的声明 + +与`Tensor`一样，graph也接受三个模板参数。 + +```c++ + +template +class Graph ... /* inherit other class*/{ + + //some implements + ... + +}; +``` + +前面已经介绍过[TargetType](#target)和[DataType](#datatype)是Anakin内部自定义数据类型。[TargetType](#target)表示平台类型 (如NV、X86), [DataType](#datatype)是Anakin基本数据类型与C++/C中的基本数据类型相对应。 [Precision](#precision)为op所支持的精度类型, 稍后我们在介绍它。 + + +```c++ + +//Create a empty graph object. +Graph graph = Graph tmp(); + +//Create a pointer to a empty graph. +Graph *graph = new Graph(); + +//Create a pointer to a empty graph. +auto graph = new Graph(); + +``` + +#### 加载 Anakin 模型 + +```c++ +//some declarations +... +auto graph = new Graph(); +std::string model_path = "the/path/to/where/your/models/are"; +const char *model_path1 = "the/path/to/where/your/models/are"; + +//Loading Anakin model to generate a compute graph. +auto status = graph->load(model_path); + +//Or this way. +auto status = graph->load(model_path1); +//Check whether load operation success. +if(!status){ + std::cout << "error" << endl; + //do something... +} + +``` + +#### 优化计算图 + +```c++ +//some declarations +... +//Load graph. +... +//According to the ops of loaded graph, optimize compute graph. +graph->Optimize(); + +``` + +> 注意： 第一次加载原始图，必须要优化。 + +#### 保存模型 + +你可以在任何时候保存模型， 特别的， 你可以保存一个优化的模型，这样，下次再加载模型时，就不必进行优化操作。 + + +```c++ +//some declarations +... +//Load graph. +... +// save a model +//save_model_path: the path to where your model is. +auto status = graph->save(save_model_path); + +//Checking +if(!status){ + cout << "error" << endl; + //do somethin... +} +``` + +#### 重新设置计算图里的tensor的shape + +```c++ +//some declarations +... +//Load graph. +... +vector shape{10, 256, 256, 10}; +//input_name : std::string. +//Reshape a tensor named input_name. +graph->Reshape(input_name, shape);//Note: shape is a vector, not a Shape object. +``` + +#### 设置 batch size + +`Graph` 支持重新设置batch size的大小。 + +```c++ +//some declarations +... +//Load graph. +... +//input_name : std::string. +//Reset a tensor named input_name. +int new_batch_size = 4; +graph->ResetBatchSize(input_name, new_batch_size); +``` + +### Net ### + + +`Net` 是计算图的执行器。你可以通过Net对象获得输入和输出 +#### Creating a graph executor + +`Net`接受四个模板参数。 + + +```c++ +template +class Net{ + //some implements + ... + +}; +``` +由于有些Op可能支持多种精度，我们可以通过Precision来指定。OpRunType表示同步或异步类型，异步是默认类型。OpRunType::SYNC表示同步，在GPU上只有单个流；OpRunType::ASYNC表示异步，在GPU上有多个流并以异步方式执行。实际上，Precision和OpRunType都是enum class, 详细设计请参考*source_root/framework/core/types.h*. + + +1. Precision + +Precision | Op support +:---: | :---: +Precision::INT4 | NO +Precision::INT8 | NO +Precision::FP16 | NO +Precision::FP32 | YES +Precision::FP64 | NO + +现在Op的精度只支持FP32， 但在将来我们会支持剩下的Precision. + + + +2. OpRunType + +OpRunType | Sync/Aync |Description +:---: | :---: | :---: +OpRunType::SYNC | Synchronization | single-stream on GPU +OpRunType::ASYNC | Asynchronization | multi-stream on GPU + +用graph对象创建一个执行器。 +```c++ +//some declarations +... +//Create a pointer to a graph. +auto graph = new Graph(); +//do something... +... + +//create a executor +Net executor(*graph); + +``` + +#### 获取输入输出tensor + + +获取输入输出tensor，并填充输入tensor的buffer。如果想要获取输入和输出tensor，那么必须指定输入的名字，如"input_0", "input_1", "input_2", ..., 必须传入如上字符串才能够获得输入tensor。另外，如果想知道input_i对应哪个输入，你需要去dash board查看，如何使用dash board请看[Anakin Parser](Converter_ch.md)。请看如下示例代码 + +```c++ +//some declaratinos +... + +//create a executor +//TargetType is NV [NVIDIA GPU] +Net executor(*graph); + +//Get the first input tensor. +//The following tensors(tensor_in0, tensor_in2 ...) are resident at GPU. +//Note: Member function get_in returns an pointer to tensor. +Tensor* tensor_in0 = executor.get_in("input_0"); + +//If you have multiple input tensors +//You just type this code below. +Tensor* tensor_in1 = executor.get_in("input_1"); +... +auto tensor_inn = executor.get_in("input_n"); +``` + +当得到输入tensor之后，就可以填充它的数据区了。 + +```c++ +//This tensor is resident at GPU. +auto tensor_d_in = executor.get_in("input_0"); + +//If we want to feed above tensor, we must feed the tensor which is resident at host. And then copy the host tensor to the device's one. + +//using Tensor4d = Tensor; +Tensor4d tensor_h_in; //host tensor; +//Tensor tensor_h_in; + +//Allocate memory for host tensor. +tensor_h_in.re_alloc(tensor_d_in->valid_shape()); +//Get a writable pointer to tensor. +float *h_data = tensor_h_in.mutable_data(); + +//Feed your tensor. +/** example +for(int i = 0; i < tensor_h_in.size(); i++){ + h_data[i] = 1.0f; +} +*/ +//Copy host tensor's data to device tensor. +tensor_d_in->copy_from(tensor_h_in); + +// And then +``` + + +类似的，我们可以利用成员函数get_out来获得输出tensor。但与获得输入tensor不同的是， 我们需要指定输入tensor结点的名字，这个可以从dash board中看到，请从[Anakin Parser](Converter_ch.md)中查看dash board的使用方法。假如有个输出结点叫pred_out, 那么我们可以通过如下代码获得相应的输出tensor： +```c++ +//Note: this tensor are resident at GPU. +Tensor* tensor_out_d = executor.get_out("pred_out"); + +``` + + +#### Executing graph + + +当一切准备就绪后，我们就可以执行真正的计算了！ +```c++ +executor.prediction(); +``` + +## 示例代码 ## + +下面的例子展示了如何调用Anakin。 + +在这儿之前， 请确保你已经有了Anakin模型。如果还没有，那么请使用[Anakin Parser](Converter_ch.md)转换你的模型。 + +### Single-thread + +单线程例子在 *source_root/test/framework/net/net_exec_test.cpp`* + +```c++ + +std::string model_path = "your_Anakin_models/xxxxx.anakin.bin"; +// Create an empty graph object. +auto graph = new Graph(); +// Load Anakin model. +auto status = graph->load(model_path); +if(!status ) { + LOG(FATAL) << " [ERROR] " << status.info(); +} +// Reshape +graph->Reshape("input_0", {10, 384, 960, 10}); +// You must optimize graph for the first time. +graph->Optimize(); +// Create a executer. +Net net_executer(*graph); + +//Get your input tensors through some specific string such as "input_0", "input_1", and +//so on. +//And then, feed the input tensor. +//If you don't know Which input do these specific string ("input_0", "input_1") correspond with, you can launch dash board to find out. +auto d_tensor_in_p = net_executer.get_in("input_0"); +Tensor4d h_tensor_in; +auto valid_shape_in = d_tensor_in_p->valid_shape(); +for (int i=0; icopy_from(h_tensor_in); + +//Do inference. +net_executer.prediction(); + +//Get result tensor through the name of output node. +//And also, you need to see the dash board again to find out how many output nodes are and remember their name. + +//For example, you've got a output node named obj_pre_out +//Then, you can get an output tensor. +auto d_tensor_out_0_p = net_executer.get_out("obj_pred_out"); //get_out returns a pointer to output tensor. +auto d_tensor_out_1_p = net_executer.get_out("lc_pred_out"); //get_out returns a pointer to output tensor. +//...... +// do something else ... +//... +//save model. +//You might not optimize the graph when you load the saved model again. +std::string save_model_path = model_path + std::string(".saved"); +auto status = graph->save(save_model_path); +if (!status ) { + LOG(FATAL) << " [ERROR] " << status.info(); +} + +``` diff --git a/source/advanced_usage/deploy/convert_paddle_to_anakin.md b/source/advanced_usage/deploy/convert_paddle_to_anakin.md index e9f36b4da..56ca582b2 120000 --- a/source/advanced_usage/deploy/convert_paddle_to_anakin.md +++ b/source/advanced_usage/deploy/convert_paddle_to_anakin.md @@ -1 +1,73 @@ -../../../anakin/docs/Manual/Converter_ch.md \ No newline at end of file +# 模型转换指南 + +Anakin 支持不同框架的模型预测。但由于格式的差别，Anakin 需要您预先转换模型。本文档介绍如何转换模型。 + +## 简介 + +Anakin 模型转换器输入支持 Caffe 和 Fluid 两种格式的预测模型，模型包含网络结构（model 或 prototxt）和权重参数（param 或 caffemodel）。 + +模型转换的输出是一个 bin 文件，它作为 Anakin 框架的 graph 参数导入。 + +您还可以使用模型转换器的 launch board 功能生成网络结构的 HTML 预览。 + + +## 系统要求 + +- python 2.7+ +- pyyaml +- flask +- protobuf 3.5+ + + +## 用法 + +### 1、环境 +转换器所需的依赖标注于 *系统要求* 一节。 + +### 2、配置 +您需要对 *config.yaml* 文件进行修改以告知您的需求。工程中给出了 *config.yaml* 示例，下面作进一步说明。 + +#### config.yaml +```bash +OPTIONS: + Framework: CAFFE # 依框架类型填写 CAFFE 或 FLUID + SavePath: ./output # 转换结束后模型的保存位置 + ResultName: googlenet # 输出模型的名字 + Config: + LaunchBoard: ON # 是否生成网络结构预览页面 + Server: + ip: 0.0.0.0 + port: 8888 # 从一个可用端口访问预览页面 + OptimizedGraph: # 当您使用了 Anakin 框架的 Optimized 功能时，才应该打开此项 + enable: OFF + path: /path/to/anakin_optimized_anakin_model/googlenet.anakin.bin.saved + LOGGER: + LogToPath: ./log/ # 生成日志的路径 + WithColor: ON + +TARGET: + CAFFE: + # 当 Framework 为 CAFFE 时需填写 + ProtoPaths: + - /path/to/caffe/src/caffe/proto/caffe.proto + PrototxtPath: /path/to/your/googlenet.prototxt + ModelPath: /path/to/your/googlenet.caffemodel + + FLUID: + # 当 Framework 为 FLUID 时需填写 + Debug: NULL + ProtoPaths: + - / + PrototxtPath: /path/to/fluid/inference_model + ModelPath: /path/to/fluid/inference_model + # ... +``` + +### 3、转换 +在完成配置文件的修改后，您只需执行 ```python converter.py``` 就可以进行模型转换了。 + + +### 4、预览 +最后一步，就是在浏览器中查看令人振奋的转换结果！网址是在 *config.yaml* 中配置的，例如 http://0.0.0.0:8888 。 + +> 注意：若您使用了默认的 IP 地址 0.0.0.0，请在预览时使用真实的服务器地址 real_ip:port 替代它。 diff --git a/source/advanced_usage/deploy/how_to_add_anakin_op.md b/source/advanced_usage/deploy/how_to_add_anakin_op.md index ceeedeb9b..f2783eb9f 120000 --- a/source/advanced_usage/deploy/how_to_add_anakin_op.md +++ b/source/advanced_usage/deploy/how_to_add_anakin_op.md @@ -1 +1,405 @@ -../../../anakin/docs/Manual/addCustomOp.md \ No newline at end of file +# 如何增加新的Operator + +## 基本概念 + +简单介绍下几个同Operator相关的基本概念，详情请参考设计文档。 + +```framework```: 上层的逻辑代码，负责从parser中获取参数及weights，添加op时主要修改framework/operator目录下的内容。 + +```saber```: 底层的实现代码，Anakin通过saber封装了不同的backends，不同的实现(impl)分别特化出自己的实现，外层framework通过不同的template进入各自的impl完成调用。各个op的parameter放在saber/saber_funcs_param.h文件中，增加op主要修改saber/funcs下的内容。 + +saber的文件结构： +* saber/funcs下的是各个funcs的外部接口，这一层的op与具体的设备实现无关，只与各op完成的功能有关。由于跟实现(impl)无关，本层文件明均不带impl。 +* saber/funcs/impl下是各个op的impl声明，特定设备需要完成该层声明的特化版本，如saber/funcs/impl/x86实现了上一层impl声明的x86特化版本，saber/funcs/impl/cuda实现了上一层impl声明的NV特化版本。当增加新的backends时需要特化出新的实现。本层代码同实现相关，均带有```impl_```前缀。 +* saber/funcs/impl/cuda/base/cuda_c内有cuda```.cu```扩展名的文件，添加cuda的kernel需要在该文件目录下添加。 +* saber/funcs/impl/cuda/base/sass 内有不同架构的汇编代码编译的静态库。 + +### 涉及到的基类及各个类之前的关系 + +简单介绍相关的基类 + +* ```anakin::Operator```: framework的operator基类，位于framework/core/operator/operator.h + +* ```anakin::saber::BaseFunc```: saber对外的op接口基类，提供统一的对外接口，位于saber/funcs/base.h。BaseFunc的```compute_output_shape```接口只根据input的shape和param的参数计算输出的shape，并通过```tensor```的```set_shape```接口(只设置shape，不分配空间)设置到output中。```operator()```接口为各个op的计算接口。 + +* ```ankain::saber::ImplBase```: saber设备实现的op的接口，所有设备相关实现的基类。位于saber/funcs/impl/impl_base.h。实现版本中这里分为两类，一类以```vender_```为前缀，带有```vender_```代码意为使用第三方库来实现该op，如cudnn的conv，或mkl的conv等等，这类op的性能我们难以调优，因此单独列为一类。另一类是带有源码的saber实现，这些实现都带有```saber_```为前缀，此类实现带有源码，能够通过后续优化不断提升性能，实现起名时需要注意这一点。 + +## 添加operator + +添加一个新的op需要以下几步： + +1. 添加saber的param +2. 定义saber的Operator类 +3. 定义新的impl声明 +3. 完成新的impl实现 +4. 增加framework的实现或特化 + +接下来就针对这几步，以一个简单例子为例介绍实现。 + +例如我们要添加新的Mul op。给出计算公式如下：$$Out = alpha \dot X * Y$$ + +### 为operator增加param + +涉及到的文件：```saber/saber_funcs_param.h```。如果之前已经存在需要添加的op的param，这一步可以跳过。 +这里```XXXParam```是一个```struct```。包含一个无参数的构造函数，含参数的构造函数，复制构造函数，```operator=()```及```operator==()```。 +``` +template // 能够获得target, datatype, layout +struct MulParam{ + MulParam() + : alpha(0) + {} + MulParam(float alpha_in) + : alpha(alpha_in) + {} + MulParam(const MulParam& right) + : alpha(right.alpha) + {} + MulParam &operator=(const MulParam &right) { + alpha = right.alpha; + } + bool operator==(const MulParam &right) { + return alpha == right.alpha; + } + float alpha; +}; +``` + +### 定义Operator类 +涉及到的文件:```saber/funcs/mul.h```。如果之前定义过该op的类，这里需要修改输入的impl定义头文件。 +下面给出一个相对完整的定义结构供参考。 +``` +//不同的设备需要包含对应的operator实现.[详见](#impl) +#ifdef NVIDIA_GPU +#include "saber/funcs/impl/cuda/saber_mul.h" +#include "saber/funcs/impl/cuda/vender_mul.h" +#endif +//如果一个设备现在还没有对应的operator实现，需要包含声明。[详见](#declare) +#ifdef USE_X86_PLACE +#include "saber/funcs/impl/impl_mul.h" +#endif +namespace anakin { +namespace saber { +template +class Mul : public BaseFunc< + Tensor, + Tensor, + Tensor, + ImplBase, MulParam> { +public: + using BaseFunc< + Tensor, + Tensor, + Tensor, + ImplBase, MulParam>::BaseFunc; + Mul() = default; + typedef Tensor InDataTensor; + typedef Tensor OutDataTensor; + typedef Tensor OpTensor; + typedef MulParam Param_t; + typedef std::vector Input_v; + typedef std::vector Output_v; + typedef std::vector Shape_v; + + virtual SaberStatus compute_output_shape(const Input_v &input, + Output_v &output, Param_t ¶m) override { + //计算输出的shape， + Shape output_shape = (input[0]->valid_shape()); + /* code */ + return output[0]->set_shape(output_shape); + } + virtual SaberStatus init_impl(ImplEnum implenum) override { + // 不同设备均使用此init_impl, 此接口创建对应impl的实现。 + switch (implenum) { + case VENDER_IMPL: + this->_impl.push_back(new VenderMul ); + return SaberSuccess; + case SABER_IMPL: + this->_impl.push_back(new SaberMul ); + return SaberSuccess; + default: + return SaberUnImplError; + } + } +private: + virtual void pick_best_static() override { + if (true) // some condition? + this->_best_impl = this->_impl[0]; + } + virtual void pick_best_specify(ImplEnum implenum) override { + this->_best_impl = this->_impl[0]; + } +}; +} // namespace saber +} // namespace anakin +``` + +### 为operator增加新的impl声明 + +涉及的文件:```saber/funcs/impl/impl_mul.h```。不同的设备都特化同一个声明，特化版本放在对应的文件夹下，这里的声明就是给出所有设备的统一声明。下面给出一个参考。 +``` +#include "saber/funcs/impl/impl_macro.h" +namespace anakin{ +namespace saber{ +DEFINE_OP_CLASS(Mul, MulParam); // 第一个参数是op的名字，第二个是对应param的名字 +} +} +``` + +### 完成新的operator特定后端实现 + +涉及的文件:```saber/funcs/impl/xxx/vender_mul.h```或```saber/funcs/impl/xxx/saber_mul.h``` +这里```xxx```指代特定的一种设备。```vender```是指的使用第三方库实现的op，```saber```指的源码实现的op。这里以cuda的vender实现为例，简单介绍一下特化出的函数的几个基本接口。 + +``` +// include 对应的声明 +#include "saber/funcs/impl/impl_mul.h" + +namespace anakin{ +namespace saber{ +template +class VenderMul : + public ImplBase< + Tensor, + Tensor, + Tensor, + MulParam > > +{ +public: + typedef Tensor DataTensor_in; + typedef Tensor DataTensor_out; + typedef Tensor OpTensor; + typedef typename DataTensor_in::Dtype InDataType; + typedef typename DataTensor_out::Dtype OutDataType; + typedef typename OpTensor::Dtype OpDataType; + VenderMul(){} + ~VenderMul() {} + + virtual SaberStatus init(const std::vector& inputs, + std::vector& outputs, + MulParam& param, Context& ctx) { + this->_ctx = ctx; + create(inputs, outputs, param, ctx); + } + + virtual SaberStatus create(const std::vector& inputs, + std::vector& outputs, + MulParam& param, Context& ctx) { + // set内部参数 + } + + virtual SaberStatus dispatch(const std::vector& inputs, + std::vector& outputs, + MulParam& param) { + // dispatch kernel. + } + +private: +}; +} +} +``` +```init```和```create```的区别：```init```接口是第一次初始化op的时候进入的接口，此函数只在第一次初始化op时调用，这个接口一般放一些只需要执行一次的代码，如malloc或者create之类的函数。```create```函数除了第一次init执行外，在输入发生变化或者param发生变化时会再次触发，create一般放置set函数，设置内部变量，当input发生变化时这里执行一些同input或weights直接相关的代码。但create因为触发位置在网络内，如果```create```函数执行了一些严重耗时的操作，这里会拖慢整个op的执行时间，需要慎重选择操作放置的位置。 +### 添加framework的特化 + +涉及的文件:```framework/operators/mul.h```和```framework/operators/mul.cpp```。 +这里简单介绍下如果添加或修改framework内的operator + +``` +#include "framework/core/base.h" +#include "framework/core/data_types.h" +#include "framework/core/operator/operator.h" +#include "utils/logger/logger.h" +#include "saber/funcs/mul.h" // 需要包对应的saber头文件 +namespace anakin { +namespace ops { +template +class MulHelper; + +template +class Mul : public Operator { +public: + Mul() {} + /// forward impl + virtual void operator() (OpContext &ctx, + const std::vector >& ins, + std::vector >& outs) { + LOG(ERROR) << "Not Impl Yet Operator power::type>().type_info()<<">"; + } + friend class MulHelper; +}; +template +class MulHelper : public OperatorHelper { +public: + MulHelper() = default; + ~MulHelper(); + Status InitParam() override; + + Status Init(OpContext &ctx, + const std::vector >& ins, + std::vector >& outs) override; + Status InferShape(const std::vector >& ins, + std::vector >& outs) override; + +public: + saber::MulParam> _param_mul; + saber::Mul _funcs_mul; +}; +} +} /* namespace anakin */ +``` +对应的```.cpp```文件如下： +``` +#include "framework/operators/mul.h" + +namespace anakin { +namespace ops { + +#ifdef USE_CUDA +template<> +void Mul::operator()( + OpContext& ctx, + const std::vector >& ins, + std::vector >& outs) { + auto* impl = + static_cast*>(this->_helper); + auto& param = + static_cast*>(this->_helper)->_param_mul; + impl->_funcs_mul(ins, outs, param, ctx); +} +#endif + +template +Status MulHelper::InitParam() { + auto alpha = GET_PARAMETER(float, alpha); + MulParam> param_mul(alpha); + _param_mul = param_mul; + return Status::OK(); +} + +template +Status MulHelper::Init(OpContext& ctx, + const std::vector >& ins, + std::vector >& outs) { + + SABER_CHECK(_funcs_mul.init(ins, outs, _param_mul, SPECIFY, VENDER_IMPL, ctx)); + return Status::OK(); +} + +template +Status MulHelper::InferShape(const + std::vector >& ins, + std::vector >& outs) { + SABER_CHECK(_funcs_mul.compute_output_shape(ins, outs, _param_mul)); + return Status::OK(); +} + +#ifdef USE_CUDA +template class MulHelper; +#endif +#ifdef USE_ARM_PLACE +template class MulHelper; +#endif +// register helper +#ifdef USE_CUDA +ANAKIN_REGISTER_OP_HELPER(Mul, MulHelper, NV, AK_FLOAT, Precision::FP32); +#endif +#ifdef USE_ARM_PLACE +ANAKIN_REGISTER_OP_HELPER(Mul, MulHelper, ARM, AK_FLOAT, Precision::FP32); +#endif +//! register op +ANAKIN_REGISTER_OP(Mul) +.Doc("Mul operator") +#ifdef USE_CUDA +.__alias__("mul") +#endif +#ifdef USE_ARM_PLACE +.__alias__("mul") +#endif +.num_in(1) +.num_out(1) +.Args("alpha", " alpha of Mul "); //注册 + +} /* namespace ops */ + +} /* namespace anakin */ +``` + +## 实现单元测试 +涉及的文件:```test/saber/xxx/test_saber_funcs_mul_xxx.cpp``` +在对应的test下需要添加新的单元测试 + +``` +TEST(TestSaberFuncNV, test_depthwise_conv) { + + // init tensors and some param. + + // start Reshape & doInfer + Context ctx1(0, 1, 1); + + // create param + MulParam > param(alpha); + + std::vector*> input; + std::vector*> output; + + // create saber op + Mul mul; + + // compute output shape + mul.compute_output_shape(input, output, param); + + // re_alloc output tensors memory based on output shape + output[0]->re_alloc(output[0]->shape()); + + // init saber op(calling init and create) + mul.init(input, output, param, SPECIFY, VENDER_IMPL, ctx1); + + // call operator() + mul(input, output, param, ctx1); + + // cuda specified, record events + cudaStream_t cuda_stream = ctx1.get_compute_stream(); + output[0]->record_event(cuda_stream); + output_dev.sync(); + + // param changed + param.alpha = 2.0; + // auto calling saber op(create and dispatch) + mul(input, output, param, ctx1); + + cudaDeviceSynchronize(); + CUDA_CHECK(cudaPeekAtLastError()); +} + +int main(int argc, const char** argv){ + anakin::saber::Env::env_init(); + + // initial logger + //logger::init(argv[0]); + InitTest(); + RUN_ALL_TESTS(argv[0]); + return 0; +} + +``` +## 调试及注意事项 + +一个op需要有对外的op接口和内部实现，由于存在saber/funcs/impl的非特化版本声明，当有op在某种设备下没有对应实现时，也能够编译，但此时是没有任何实现的空实现， diff --git a/source/advanced_usage/deploy/how_to_support_new_device_in_anakin.md b/source/advanced_usage/deploy/how_to_support_new_device_in_anakin.md index c3e1e3494..a1f75f5e9 120000 --- a/source/advanced_usage/deploy/how_to_support_new_device_in_anakin.md +++ b/source/advanced_usage/deploy/how_to_support_new_device_in_anakin.md @@ -1 +1,459 @@ -../../../anakin/docs/Manual/addCustomDevice.md \ No newline at end of file +# 如何支持一个新的设备 + +## 概览 + +添加一个新的设备需要以下3个步骤： + +* [在`CMakeList`中添加设备的支持](#0001) +* [在`saber`中添加设备的实现](#0002) +* [在`framework`中添加设备的具体化或实例化](#0003) + +假设新设备的名称为`TNEW`, 以下将以这个设备名称进行演示。 + +## 在`CMakeList`中添加设备的支持 ## + +* 修改根目录`CMakeList.txt` +```cmake +#select the plantform to build +anakin_option(USE_GPU_PLACE "Select the build mode for GPU place." NO) +anakin_option(USE_X86_PLACE "Select the build mode for X86 place." NO) +anakin_option(USE_ARM_PLACE "Select the build mode for ARM place." NO) +anakin_option(USE_TNEW_PLACE "Select the build mode for ARM place." YES) +``` + +* 修改`saber/CMakeList.txt` + +根据新增设备的目录完善`saber`目录下的`CMakeList.txt`。 +```cmake +if(USE_TNEW_PLACE) + anakin_fetch_files_with_suffix(${ANAKIN_SABER}/core/impl/tnew "cpp" ANAKIN_SABER_BASE_SRC) + anakin_fetch_files_with_suffix(${ANAKIN_SABER}/funcs/impl/tnew "cpp" ANAKIN_SABER_BASE_SRC) +endif() +``` + +* 修改`test/CMakeList.txt` + +新增设备的单测文件放在`test/saber/tnew`目录下，修改`test`目录下的`CMakeList.txt`。 +```cmake +if(USE_TNEW_PLACE) + anakin_fetch_files_with_suffix(${ANAKIN_UNIT_TEST}/saber/tnew "cpp" ANAKIN_TEST_CASE_SRC) +endif() +``` + +* 修改`cmake/anakin_config.h.in` +```c++ +// plantform to use +#cmakedefine USE_GPU_PLACE + +#cmakedefine USE_X86_PLACE + +#cmakedefine USE_ARM_PLACE + +#cmakedefine USE_TNEW_PLACE +``` + +* 其他依赖和编译选项 +修改`cmake`目录下的`compiler_options.cmake`和`find_modules.cmake` + + +## 在`saber`中添加设备的实现 ## +`saber`是`Anakin`的基础计算库，对外提供设备无关的统一的API，设备相关的实现都会封装到`TargetWrapper`中。 + +### 在`saber/saber_types.h`中添加设备 + +```c++ +enum TargetTypeEnum { + eINVALID = -1, + eNV = 1, + eAMD = 2, + eARM = 3, + eX86 = 4, + eNVHX86 = 5, + eTNEW = 6 +}; + +typedef TargetType NV; +typedef TargetType ARM; +typedef TargetType AMD; +typedef TargetType X86; +typedef TargetType TNEW; + +``` + +### 在`saber/core`中添加设备的实现 + +1. 在`target_traits.h`中添加新设备 + +* 增加设备类型 +```c++ +struct __cuda_device{}; +struct __arm_device{}; +struct __amd_device{}; +struct __x86_device{}; +struct __tnew_device{}; +``` + +* `TargetTypeTraits`模板具体化 +```c++ +template <> +struct TargetTypeTraits { + typedef __xxx_target target_category;//根据实际设备是host端还是device端进行选择 + typedef __tnew_device target_type; +}; +``` + +2. 在`data_traits.h`中特化`DataTrait`模板类 + +如果设备需要特殊的数据类型，则特化出设备的`DataTrait`类的实现，例如opencl数据类型的实现如下： +```c++ +#ifdef USE_OPENCL +struct ClMem{ + ClMem(){ + dmem = nullptr; + offset = 0; + } + + ClMem(cl_mem* mem_in, int offset_in = 0) { + dmem = mem_in; + offset = offset_in; + } + + ClMem(ClMem& right) { + dmem = right.dmem; + offset = right.offset; + } + + ClMem& operator=(ClMem& right) { + this->dmem = right.dmem; + this->offset = right.offset; + return *this; + } + + ClMem& operator+(int offset_in) { + this->offset += offset_in; + return *this; + } + + int offset{0}; + cl_mem* dmem; +}; + +template <> +struct DataTrait { + typedef ClMem Dtype; + typedef float dtype; +}; + +template <> +struct DataTrait { + typedef ClMem Dtype; + typedef double dtype; +}; + +template <> +struct DataTrait { + typedef ClMem Dtype; + typedef char dtype; +}; +#endif //use_opencl +``` + +3. 在`target_wrapper.h`中特化`TargetWrapper`模板类 + +特化`TargetWrapper`模板类，在`target_wrapper.h`中声明函数，具体如下： +```c++ +template <> +struct TargetWrapper { //根据TNEW的具体类型修改__xxx_target，__host_target或者__device_target + + typedef xxx_event event_t; //根据设备实现xxx_event + typedef xxx_stream stream_t; //根据设备实现xxx_stream + + static void get_device_count(int& count); + + static void set_device(int id); + + //We should add strategy to avoid malloc directly + static void mem_alloc(void** ptr, size_t n); + + static void mem_free(void* ptr); + + static void mem_set(void* ptr, int value, size_t n); + + static void create_event(event_t& event, bool flag = false); + + static void create_stream(stream_t& stream); + + static void create_stream_with_flag(stream_t& stream, unsigned int flag); + + static void create_stream_with_priority(stream_t& stream, unsigned int flag, int priority); + + static void destroy_stream(stream_t& stream); + + static void destroy_event(event_t& event); + + static void record_event(event_t& event, stream_t stream); + + static void query_event(event_t& event); + + static void sync_event(event_t& event); + + static void sync_stream(event_t& event, stream_t& stream); + + static void sync_memcpy(void* dst, int dst_id, const void* src, int src_id, \ + size_t count, __DtoD); + + static void async_memcpy(void* dst, int dst_id, const void* src, int src_id, \ + size_t count, stream_t& stream, __DtoD); + + static void sync_memcpy(void* dst, int dst_id, const void* src, int src_id, \ + size_t count, __HtoD); + + static void async_memcpy(void* dst, int dst_id, const void* src, int src_id, \ + size_t count, stream_t& stream, __HtoD); + + static void sync_memcpy(void* dst, int dst_id, const void* src, int src_id, \ + size_t count, __DtoH); + + static void async_memcpy(void* dst, int dst_id, const void* src, int src_id, \ + size_t count, stream_t& stream, __DtoH); + + static void sync_memcpy_p2p(void* dst, int dst_dev, const void* src, \ + int src_dev, size_t count); + + static void async_memcpy_p2p(void* dst, int dst_dev, const void* src, \ + int src_dev, size_t count, stream_t& stream); + + static int get_device_id(); +}; + +``` + +4. 在`impl/`目录下添加设备目录和实现 + +在`saber/core/impl`目录下添加设备目录`tnew`。 +* 实现`TargetWrapper`结构体中各函数的定义。 +如果`TargetWrapper`的实现与默认的模板类一致，则不用特化出该类。 + +```c++ +typedef TargetWrapper TNEW_API; +void TNEW_API::get_device_count(int &count) { + // add implementation +} + +void TNEW_API::set_device(int id){ + // add implementation +} + +void TNEW_API::mem_alloc(void** ptr, size_t n){ + // add implementation +} + +void TNEW_API::mem_free(void* ptr){ + if(ptr != nullptr){ + // add implementation + } +} +... + +``` + +* 特化实现`device.h`中的`Device` + +```c++ +template <> +void Device::create_stream() { + // add implementation +} + +template <> +void Device::get_info() { + + // add implementation +} + +``` + +### 在`saber/funcs`中实现设备相关的op + +参考[如何增加新的Operator](addCustomOp.md) + + +## 在`framework`中添加设备的具体化或实例化 ## + +### `framework/core` + +* `net.cpp`中添加实例化 + +```c++ +#ifdef USE_TNEW_PLACE +template class Net; +template class Net; +#endif +``` + +* `operator_func.cpp`中添加实例化 + +```c++ +#ifdef USE_TNEW_PLACE +template class OperatorFunc; +#endif +``` + +* `worker.cpp`中添加实例化 + +```c++ +#ifdef USE_TNEW_PLACE +template class Worker; +template class Worker; +#endif +``` + +* `operator_attr.cpp`中添加实例化 + +```c++ +template +OpAttrWarpper& OpAttrWarpper::__alias__(const std::string& op_name); +template +OpAttrWarpper& OpAttrWarpper::__alias__(const std::string& op_name); +template +OpAttrWarpper& OpAttrWarpper::__alias__(const std::string& op_name); +``` + +* `parameter.h`中添加设备的实现 + +```c++ +#ifdef USE_TNEW_PLACE +template +class PBlock { +public: + typedef Tensor4d::type> type; + + PBlock() { + _inner_tensor = std::make_shared(); + } + ... +} +#endif //TNEW +``` + +* `type_traits_extend.h`中添加设备的实现 + +```c++ +template<> +struct target_host { + typedef saber::X86 type; //根据TNEW选择正确的host type +}; +``` + +### `framework/graph` + +* `graph.cpp`中添加实例化 + +```c++ + #ifdef USE_TNEW_PLACE + template class Graph; + template class Graph; + template class Graph; + #endif +``` + +### `framework/model_parser` + +* `parser.cpp`中添加实例化 + +```c++ + #ifdef USE_TNEW_PLACE + template + Status load(graph::Graph* graph, + const char* model_path); + template + Status load(graph::Graph* graph, + const char* model_path); + template + Status load(graph::Graph* graph, + const char* model_path); + + template + Status save(graph::Graph* graph, + std::string& model_path); + template + Status save(graph::Graph* graph, + std::string& model_path); + template + Status save(graph::Graph* graph, + std::string& model_path); + + template + Status load(graph::Graph* graph, + std::string& model_path); + template + Status load(graph::Graph* graph, + std::string& model_path); + template + Status load(graph::Graph* graph, + std::string& model_path); + + template + Status save(graph::Graph* graph, + const char* model_path); + template + Status save(graph::Graph* graph, + const char* model_path); + template + Status save(graph::Graph* graph, + const char* model_path); + #endif +``` + +* `model_io.cpp`中添加实例化 + +```c++ +#ifdef USE_TNEW_PLACE +template class NodeIO; +template class NodeIO; +template class NodeIO; +#endif +``` + +### `framework/operators` + +为`framework/operators`目录下所有op添加实例化或具体化 +以`activation.cpp`为例，实例化如下： + +```c++ +#ifdef USE_TNEW_PLACE +INSTANCE_ACTIVATION(TNEW, AK_FLOAT, Precision::FP32); +INSTANCE_ACTIVATION(TNEW, AK_FLOAT, Precision::FP16); +INSTANCE_ACTIVATION(TNEW, AK_FLOAT, Precision::INT8); +template class ActivationHelper; +ANAKIN_REGISTER_OP_HELPER(Activation, ActivationHelper, TNEW, AK_FLOAT, Precision::FP32); +#endif +``` + +如果TNEW设备函数的实现与现有模板实现不一致，可以特化实现如下（以init()为例）： +```c++ +#ifdef USE_TNEW_PLACE +INSTANCE_ACTIVATION(TNEW, AK_FLOAT, Precision::FP32); +INSTANCE_ACTIVATION(TNEW, AK_FLOAT, Precision::FP16); +INSTANCE_ACTIVATION(TNEW, AK_FLOAT, Precision::INT8); +template <> +Status ActivationHelper::Init(OpContext &ctx,\ + const std::vector >& ins, \ + std::vector >& outs) { + SABER_CHECK(_funcs_activation.init(ins, outs, _param_activation, SPECIFY, SABER_IMPL, ctx)); //在这里选择实现方式 + return Status::OK(); +} +ANAKIN_REGISTER_OP_HELPER(Activation, ActivationHelper, TNEW, AK_FLOAT, Precision::FP32); +#endif +``` + +在`ANAKIN_REGISTER_OP(Activation)`中添加TNEW的注册 + +```c++ +#ifdef USE_TNEW_PLACE +.__alias__("activation") +#endif +``` + +## 注意事项 +不要修改`Tensor`/`Buffer`/`Env`/`Context`这些类函数的接口和实现 diff --git a/source/advanced_usage/deploy/index_anakin.rst b/source/advanced_usage/deploy/index_anakin.rst index b782242a6..e4682ccb9 100644 --- a/source/advanced_usage/deploy/index_anakin.rst +++ b/source/advanced_usage/deploy/index_anakin.rst @@ -1,5 +1,5 @@ -服务器端部署 - Anakin -##################### +Anakin - 服务器端加速引擎 +####################### 使用文档 diff --git a/source/advanced_usage/deploy/install_anakin.md b/source/advanced_usage/deploy/install_anakin.md index d14e1f720..bb7c19503 120000 --- a/source/advanced_usage/deploy/install_anakin.md +++ b/source/advanced_usage/deploy/install_anakin.md @@ -1 +1,69 @@ -../../../anakin/docs/Manual/INSTALL_ch.md \ No newline at end of file +## 从源码编译安装Anakin ## + +我们已经在CentOS 7.3上成功的安装和测试了Anakin，对于其他操作系统，我们将很快支持。 + +### 安装概览 ### + +* [在CentOS上安装 Anakin]() +* [在Ubuntu上安装 Anakin]() +* [在ARM上安装 Anakin](run_on_arm_ch.md) +* [验证安装]() + + +### 在CentOS上安装 Anakin ### +#### 1. 系统要求 #### + +* make 3.82+ +* cmake 2.8.12+ +* gcc 4.8.2+ +* g++ 4.8.2+ +* 其他需要补充的。。。 + +#### 2. 编译CPU版Anakin #### + +暂时不支持 + +#### 3. 编译支持NVIDIA GPU的Anakin #### + +- 3.1. 安装依赖 + - 3.1.1 protobuf + >$ git clone https://github.com/google/protobuf + >$ cd protobuf + >$ git submodule update --init --recursive + >$ ./autogen.sh + >$ ./configure --prefix=/path/to/your/insall_dir + >$ make + >$ make check + >$ make install + >$ sudo ldconfig + + + 如安装protobuf遇到任何问题，请访问[这里](https://github.com/google/protobuf/blob/master/src/README.md) + +- 3.2 CUDA Toolkit + - [CUDA 8.0](https://developer.nvidia.com/cuda-zone) or higher. 具体信息参见[NVIDIA's documentation](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/). + - [cuDNN v7](https://developer.nvidia.com/cudnn). 具体信息参见[NVIDIA's documentation](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/). +- 3.3 编译Anakin + >$ git clone https:/xxxxx + >$ cd anakin + >$ mkdir build + >$ camke .. + >$ make + + +#### 4. 编译支持AMD GPU的Anakin #### + +暂时还不支持 + + +### 在Ubuntu上安装 Anakin ### + +暂时还不支持 + + +### 在ARM上安装 Anakin ### + +暂时还不支持 + +### 验证安装 ### +we are coming soon... diff --git a/source/advanced_usage/deploy/mobile_build.md b/source/advanced_usage/deploy/mobile_build.md index 12b5c6ea2..e51593164 120000 --- a/source/advanced_usage/deploy/mobile_build.md +++ b/source/advanced_usage/deploy/mobile_build.md @@ -1 +1,59 @@ -../../../mobile/doc/build.md \ No newline at end of file +# 环境搭建 +## 使用 docker +### 1. 安装 docker +安装 docker 的方式，参考官方文档 [https://docs.docker.com/install/](https://docs.docker.com/install/) +### 2. 使用 docker 搭建构建环境 +首先进入 paddle-mobile 的目录下，执行 `docker build` +以 Linux/Mac 为例 (windows 建议在 'Docker Quickstart Terminal' 中执行) +``` +$ docker build -t paddle-mobile:dev - < Dockerfile +``` +使用 `docker images` 可以看到我们新建的 image +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +paddle-mobile dev 33b146787711 45 hours ago 372MB +``` +### 3. 使用 docker 构建 +进入 paddle-mobile 目录，执行 docker run +``` +$ docker run -it --mount type=bind,source=$PWD,target=/paddle-mobile paddle-mobile:dev +root@5affd29d4fc5:/ # cd /paddle-mobile +# 生成构建 android 产出的 Makefile +root@5affd29d4fc5:/ # rm CMakeCache.txt +root@5affd29d4fc5:/ # cmake -DCMAKE_TOOLCHAIN_FILE=tools/toolchains/arm-android-neon.cmake +# 生成构建 linux 产出的 Makefile +root@5affd29d4fc5:/ # rm CMakeCache.txt +root@5affd29d4fc5:/ # cmake -DCMAKE_TOOLCHAIN_FILE=tools/toolchains/arm-linux-gnueabi.cmake +``` +### 4. 设置编译选项 +可以通过 ccmake 设置编译选项 +``` +root@5affd29d4fc5:/ # ccmake . + Page 1 of 1 + CMAKE_ASM_FLAGS + CMAKE_ASM_FLAGS_DEBUG + CMAKE_ASM_FLAGS_RELEASE + CMAKE_BUILD_TYPE + CMAKE_INSTALL_PREFIX /usr/local + CMAKE_TOOLCHAIN_FILE /paddle-mobile/tools/toolchains/arm-android-neon.cmake + CPU ON + DEBUGING ON + FPGA OFF + LOG_PROFILE ON + MALI_GPU OFF + NET googlenet + USE_EXCEPTION ON + USE_OPENMP OFF +``` +修改选项后，按 `c`, `g` 更新 Makefile +### 5. 构建 +使用 make 命令进行构建 +``` +root@5affd29d4fc5:/ # make +``` +### 6. 查看构建产出 +构架产出可以在 host 机器上查看，在 paddle-mobile 的目录下，build 以及 test/build 下，可以使用 adb 指令或者 scp 传输到 device 上执行 + +## 不使用 docker +不使用 docker 的方法，可以直接用 cmake 生成 makefile 后构建。使用 ndk 构建 android 应用需要正确设置 NDK_ROOT。构建 linux 应用需要安装 arm-linux-gnueabi-gcc 或者类似的交叉编译工具，可能需要设置 CC，CXX 环境变量，或者在 tools/toolchains/ 中修改 arm-linux-gnueabi.cmake，或者增加自己需要的 toolchain file。 diff --git a/source/advanced_usage/deploy/mobile_dev.md b/source/advanced_usage/deploy/mobile_dev.md index f8f533620..474380f9d 120000 --- a/source/advanced_usage/deploy/mobile_dev.md +++ b/source/advanced_usage/deploy/mobile_dev.md @@ -1 +1,72 @@ -../../../mobile/doc/development_doc.md \ No newline at end of file +# iOS开发文档 + +## 编译 + +### 一. 使用 build.sh 编译 + +```sh +sh build.sh ios + +# 如果只想编译某个特定模型的 op, 则需执行以下命令 +sh build.sh ios googlenet + +# 在这个文件夹下, 你可以拿到生成的 .a 库 +cd ../build/release/ios/build + +``` + +### 二. 使用 xcode 编译 + +我们提供了 ios 开发更为熟悉的 xcode 编译环境: +在 ios/ 目录下打开 PaddleMobile.xcworkspace 即可编译 PaddleMobile 或者 运行 Demo + +### 三. 集成 + +#### 如使用 c++ 接口 +将 + +``` +libpaddle-mobile.a +io.h +program.h +types.h +lod_tensor.h +tensor.h +``` +拖入工程, io.h 为接口文件, 可在 [github](https://github.com/PaddlePaddle/paddle-mobile/blob/develop/src/io/io.h)上查看接口注释 + +#### 如使用 oc 接口 +将在xcode 编译生成的 +``` +libPaddleMobile.a +PaddleMobile.h +``` +拖入工程, 接口如下: + +``` +/* + 创建单例对象 +*/ ++ (instancetype)sharedInstance; + +/* + load 模型, 开辟内存 +*/ +- (BOOL)load:(NSString *)modelPath andWeightsPath:(NSString *)weighsPath; + +/* + 进行预测, means 和 scale 为训练模型时的预处理参数, 如训练时没有做这些预处理则直接使用 predict +*/ +- (NSArray *)predict:(CGImageRef)image means:(NSArray *)means scale:(float)scale; + +/* + 进行预测 +*/ +- (NSArray *)predict:(CGImageRef)image; + +/* + 清理内存 +*/ +- (void)clear; + +``` diff --git a/source/advanced_usage/deploy/run_anakin_on_arm.md b/source/advanced_usage/deploy/run_anakin_on_arm.md index d55355f1d..ebeb38f53 120000 --- a/source/advanced_usage/deploy/run_anakin_on_arm.md +++ b/source/advanced_usage/deploy/run_anakin_on_arm.md @@ -1 +1,151 @@ -../../../anakin/docs/Manual/run_on_arm_ch.md \ No newline at end of file +## 源码编译 Anakin ## + +目前Anakin支持ARM Android平台，采用Android NDK交叉编译工具链，已在mac os和centos上编译和测试通过。 + +### 安装概览 ### + +* [系统需求](#0001) +* [安装第三方依赖](#0002) +* [Anakin源码编译](#0003) +* [验证安装](#0004) + + +### 1. 系统需求 ### + +* 宿主机: linux, mac +* cmake 3.8.2+ +* Android NDK r14, Linux 版本[从这里下载](https://dl.google.com/android/repository/android-ndk-r14b-linux-x86_64.zip) + +### 2. 安装第三方依赖 ### + +- 2.1 protobuf3.4.0 + 源码从这里[下载](https://github.com/google/protobuf/releases/tag/v3.4.0) + - 2.1.1 为宿主机编译protobuf + ```bash + $ tar -xzf protobuf-3.4.0.tar.gz + $ cd protobuf-3.4.0 + $ ./autogen.sh + $ ./configure + $ make + $ make check + $ make install + ``` + 上述 $make install 执行后，可在 /usr/local/include/google 找到 libprotobuf 所需的头文件,将整个google文件夹拷贝至Anakin/third-party/arm-android/protobuf/下， + 如有问题，请点[这里](https://github.com/google/protobuf/blob/v3.4.0/src/README.md)。 + 然后将已经生成文件清除。 + ```bash + $ make distclean + ``` + - 2.1.1 交叉编译Android`armeabi-v7a`的protobuf，注意设置ANDROID_NDK的路径，以及ARCH_ABI、HOSTOSN的值， + ```bash + + $ export ANDROID_NDK=your_ndk_path + $ ARCH_ABI="arm-linux-androideabi-4.9" + $ HOSTOSN="darwin-x86_64" + $ export SYSROOT=$ANDROID_NDK/platforms/android-9/arch-arm + $ export PREBUILT=$ANDROID_NDK/toolchains/$ARCH_ABI + $ export LDFLAGS="--sysroot=$SYSROOT" + $ export LD="$ANDROID_NDK/toolchains/$ARCH_ABI/prebuilt/$HOSTOSN/arm-linux-androideabi/bin/ld $LDFLAGS" + $ export LIBS="-llog $ANDROID_NDK/sources/cxx-stl/gnu-libstdc++/4.9/libs/armeabi-v7a/libgnustl_static.a" + $ export CPPFLAGS="" + $ export INCLUDES="-I$ANDROID_NDK/sources/cxx-stl/gnu-libstdc++/4.9/include/ -I$ANDROID_NDK/platforms/android-9/arch-arm/usr/include/ -I$ANDROID_NDK/sources/cxx-stl/gnu-libstdc++/4.9/libs/armeabi-v7a/include/" + $ export CXXFLAGS="-march=armv7-a -mfloat-abi=softfp -DGOOGLE_PROTOBUF_NO_RTTI --sysroot=$SYSROOT" + $ export CCFLAGS="$CXXFLAGS" + $ export CXX="$PREBUILT/prebuilt/$HOSTOSN/bin/arm-linux-androideabi-g++ $CXXFLAGS" + $ export CC="$CXX" + $ export RANLIB="$ANDROID_NDK/toolchains/$ARCH_ABI/prebuilt/$HOSTOSN/bin/arm-linux-androideabi-ranlib" + $ ./autogen.sh + $ ./configure --host=arm-linux-androideabi --with-sysroot=$SYSROOT --enable-cross-compile --with-protoc=protoc --disable-shared CXX="$CXX" CC="$CC" LD="$LD" + $ make + ``` + + 编译生成 *.a 静态库，若希望编译*.so 动态链接库 ，请在./configure参数中改--disable-shared为--disable-static --enable-shared。 + 生成文件在src/.libs/下，将生成的文件拷贝至Anakin/third-party/arm-android/protobuf/lib下。 + 在[cmake](../../cmake/find_modules.cmake)中更新`ARM_RPOTO_ROOT`的路径。 + ```cmake + set(ARM_RPOTO_ROOT "${CMAKE_SOURCE_DIR}/third-party/arm-android/protobuf") + ``` + +- 2.2 opencv 2.4.3+(optional) + Anakin只在examples示例中使用opencv + Android系统的opencv从[这里下载](https://opencv.org/releases.html) + 解压后将 `3rdparty/libs/armeabi-v7a`中的库文件拷贝到`libs/armeabi-v7a` + 在[cmake](../../cmake/find_modules.cmake)中搜索`anakin_find_opencv`, + 并设置 `include_directories` 和 `LINK_DIRECTORIES`为自己安装的库的路径。 + ```cmake + include_directories(${CMAKE_SOURCE_DIR}/third-party/arm-android/opencv/sdk/native/jni/include/) + LINK_DIRECTORIES(${CMAKE_SOURCE_DIR}/third-party/arm-android/opencv/sdk/native/libs/armeabi-v7a/) + ``` +### 3. Anakin源码编译 ### + +#### 编译Android版本 + + 克隆[源码](https://github.com/PaddlePaddle/Anakin/tree/arm) +```bash + cd your_dir + git clone https://github.com/PaddlePaddle/Anakin.git + cd Anakin + git fetch origin arm + git checkout arm + ``` + 修改`android_build.sh` +- 修改NDK路径 + ```bash + #modify "your_ndk_path" to your NDK path + export ANDROID_NDK=your_ndk_path + ``` +- 修改ARM 处理器架构 + 对于32位ARM处理器, 将ANDROID_ABI 设置为 `armeabi-v7a with NEON`， + 对于64位ARM处理器, 可以将ANDROID_ABI 设置为 `armeabi-v7a with NEON`或者`arm64-v8a`。 + 目前我们只支持 `armeabi-v7a with NEON`；`arm64-v8a` 还在开发中。 + ```bash + -DANDROID_ABI="armeabi-v7a with NEON" + ``` +- 设置Android API + 根据Android系统的版本设置API level， 例如API Level 21 -> Android 5.0.1 + ```bash + -DANDROID_NATIVE_API_LEVEL=21 + ``` + +- 选择编译静态库或动态库 + 设置`BUILD_SHARED=NO`编译静态库 + 设置`BUILD_SHARED=YES`编译动态库 + ```bash + -DBUILD_SHARED=NO + ``` +- OpenMP多线程支持 + 设置`USE_OPENMP=YES`开启OpenMP多线程 + ```bash + -DUSE_OPENMP=YES + ``` + +- 编译单测文件 + 设置`BUILD_WITH_UNIT_TEST=YES`将会编译单测文件 + ```bash + -DBUILD_WITH_UNIT_TEST=YES + ``` + +- 编译示例文件 + 设置`BUILD_EXAMPLES=YES`将会编译示例文件 + ```bash + -DBUILD_EXAMPLES=YES + ``` + +- 开启opencv + 如果使用opencv，设置`USE_OPENCV=YES` + ```bash + -DUSE_OPENCV=YES + ``` + +- 开始编译 + 运行脚本 `android_build.sh` 将自动编译Anakin + ```bash + ./android_build.sh + ``` + +### 4. 验证安装 ### + 编译好的库会放在目录`${Anakin_root}/output`下； + 编译好的单测文件会放在`${Anakin_root}/output/unit_test`目录下； + 编译好的示例文件会放在`${Anakin_root}/output/examples`目录下。 + + 对于Android系统，打开设备的调试模式，通过ADB可以访问的目录是`data/local/tmp`，通过ADB push将测试文件、模型和数据发送到设备目录， 运行测试文件。 diff --git a/source/advanced_usage/development/gpu_profiling_cn.rst b/source/advanced_usage/development/gpu_profiling_cn.rst index be2aeff64..f2396716b 120000 --- a/source/advanced_usage/development/gpu_profiling_cn.rst +++ b/source/advanced_usage/development/gpu_profiling_cn.rst @@ -1 +1,242 @@ -../../../paddle/doc/v2/howto/optimization/gpu_profiling_cn.rst \ No newline at end of file +============ +GPU性能调优 +============ + +.. contents:: + +此教程将向您分步介绍如何使用内置的定时工具、 **nvprof** 或 **nvvp** 来运行性能分析和调优。 + +- 什么是性能分析？ +- 为什么需要性能分析？ +- 如何进行性能分析？ +- 性能分析工具介绍 +- 详细教程 +- 性能分析小技巧 + +什么是性能分析？ +================ +在软件工程的范畴里，性能分析（Profiling）是一个动态程序分析的术语，它可以指测量一个程序的空间（内存）复杂度或时间复杂度， +也可以说是某些特定指令的使用情况，或者是函数调用的频率和耗时等。通常情况下，分析得到的信息用于协助进行程序的优化。 + +简单来说，性能分析工具是用于给应用程序的性能做定量分析的。如果想很好的理解程序的行为，那程序分析工具是必不可少的利器。简单的性能分析，可以告诉您某个操作到底花了多长时间？而更深入的分析，甚至能解释为什么某个操作花了很长时间？ + +为什么需要性能分析？ +============================ +训练好一个深层神经网络通常要耗费非常长的时间，所以性能也就逐步变成了深度学习领域最重要的指标。 +而优化性能的首要任务，是需要了解哪些步骤拖慢了整体。 +如果某一块根本就不怎么耗时，那也就不需要急着优化性能啦！ + +如何进行性能分析？ +======================== +为了达到性能最优，您可以采用下面五个步骤： + +- 对代码进行性能分析 +- 找到运行慢的部分 +- 找到运行慢的原因 +- 修改成更快的版本 +- 再次对代码进行性能分析 + +Usually, processor has two key performance limits include float point throughput and +memory throughput. For GPU, it also need more parallelism to fulfill its potential. +This is why they can be so fast. + +通常情况下，处理器有两个关键性能限制：一个是浮点计算量，另一个是内存操作量。 +GPU则还需要高并行性，才能发挥其全部能力。这正是它们速度快的原因。 + +性能分析工具介绍 +====================== +就通常的GPU性能分析来说，市面上已经有NVIDIA或第三方提供的众多工具。 + +**nvprof** 是Nvidia性能分析工具， **nvvp** 则是带GUI的Nvidia可视化性能分析工具。 +在这个教程中，我们主要会介绍nvprof和nvvp。 + +:code:`test_GpuProfiler` from :code:`paddle/legacy/math/tests` directory will be used to evaluate +above profilers. + +:code:`paddle/legacy/math/test` 目录中的 :code:`test_GpuProfiler` 就是用于展示上述分析工具的用法。 + +.. literalinclude:: ../../../../paddle/legacy/math/tests/test_GpuProfiler.cpp + :language: c++ + :lines: 137-151 + :linenos: + +上述的代码片段包含了两种方法，您可以任意使用一个或两个来对感兴趣的代码段做性能分析。 + +1. :code:`REGISTER_TIMER_INFO` 是一个内置的定时器封装，可以用来计算CPU函数或cuda内核的时间消耗。 + +2. :code:`REGISTER_GPU_PROFILER` is a general purpose wrapper object of :code:`cudaProfilerStart` and :code:`cudaProfilerStop` to avoid +program crashes when CPU version of PaddlePaddle invokes them. + +3. :code:`REGISTER_GPU_PROFILER` 是一个封装对象，封装了 :code:`cudaProfilerStart` 和 :code:`cudaProfileStop` 两个操作；同时其内部实现可以避免纯CPU版本PaddlePaddle在执行本语句时发生崩溃。 + +您会在接下来的部分中获得更多的细节介绍。 + +详细教程 +============ + +内置定时器 +------------ + +如果想要启用PaddlePaddle的内置定时器，您首先需要在相关代码段中加入 :code:`REGISTER_TIMER_INFO`。 +接下来就可以使用 :code:`printStatus` 或者 :code:`printAllStatus` 函数来将信息输出到界面中。 +下面举个简单的例子： + +1. 加入 :code:`REGISTER_TIMER_INFO` 和 :code:`printAllStatus` 函数（如高亮部分）。 + + .. literalinclude:: ../../../../paddle/legacy/math/tests/test_GpuProfiler.cpp + :language: c++ + :lines: 137-151 + :emphasize-lines: 8-12,14 + :linenos: + +2. cmake配置中将 **WITH_TIMER** 打开，重新编译PaddlePaddle。 + + .. code-block:: bash + + cmake .. -DWITH_TIMER=ON + make + +3. 执行您的代码，并观察结果(如高亮部分）。 + + .. code-block:: bash + :emphasize-lines: 1,12-15 + + > ./paddle/legacy/math/tests/test_GpuProfiler + I1117 11:13:42.313065 2522362816 Util.cpp:155] commandline: ./paddle/legacy/math/tests/test_GpuProfiler + I1117 11:13:42.845065 2522362816 Util.cpp:130] Calling runInitFunctions + I1117 11:13:42.845208 2522362816 Util.cpp:143] Call runInitFunctions done. + [==========] Running 1 test from 1 test case. + [----------] Global test environment set-up. + [----------] 1 test from Profiler + [ RUN ] Profiler.BilinearFwdBwd + I1117 11:13:42.845310 2522362816 test_GpuProfiler.cpp:114] Enable GPU Profiler Stat: [testBilinearFwdBwd] "numSamples = 10, channels = 16, im + gSizeX = 64, imgSizeY = 64" + I1117 11:13:42.850154 2522362816 ThreadLocal.cpp:37] thread use undeterministic rand seed:20659751 + I1117 11:13:42.981501 2522362816 Stat.cpp:130] ======= StatSet: [GlobalStatInfo] status ====== + I1117 11:13:42.981539 2522362816 Stat.cpp:133] Stat=testBilinearFwdBwd total=136.141 avg=136.141 max=136.141 min=136.141 count=1 + I1117 11:13:42.981572 2522362816 Stat.cpp:141] ======= BarrierStatSet status ====== + I1117 11:13:42.981575 2522362816 Stat.cpp:154] -------------------------------------------------- + [ OK ] Profiler.BilinearFwdBwd (136 ms) + [----------] 1 test from Profiler (136 ms total) + + [----------] Global test environment tear-down + [==========] 1 test from 1 test case ran. (136 ms total) + [ PASSED ] 1 test. + +nvprof 工具 +---------------- + +要使用命令行分析工具 **nvprof**，您按如下步骤操作即可： + +1. 将 :code:`REGISTER_GPU_PROFILER` 函数加到代码中（参考强调部分）。 + + .. literalinclude:: ../../../../paddle/legacy/math/tests/test_GpuProfiler.cpp + :language: c++ + :lines: 137-151 + :emphasize-lines: 6-7 + :linenos: + +2. cmake中将 **WITH_PROFILER** 配置打开，重新编译PaddlePaddle。 + + .. code-block:: bash + + cmake .. -DWITH_PROFILER=ON + make + +3. 使用 **nvprof** 来分析执行文件。 + + .. code-block:: bash + + nvprof ./paddle/legacy/math/tests/test_GpuProfiler + +然后，您就能获得如下的分析结果： + +.. code-block:: bash + + ==78544== Profiling application: ./paddle/legacy/math/tests/test_GpuProfiler + ==78544== Profiling result: + Time(%) Time Calls Avg Min Max Name + 27.60% 9.6305ms 5 1.9261ms 3.4560us 6.4035ms [CUDA memcpy HtoD] + 26.07% 9.0957ms 1 9.0957ms 9.0957ms 9.0957ms KeBilinearInterpBw + 23.78% 8.2977ms 1 8.2977ms 8.2977ms 8.2977ms KeBilinearInterpFw + 22.55% 7.8661ms 2 3.9330ms 1.5798ms 6.2863ms [CUDA memcpy DtoH] + + ==78544== API calls: + Time(%) Time Calls Avg Min Max Name + 46.85% 682.28ms 8 85.285ms 12.639us 682.03ms cudaStreamCreateWithFlags + 39.83% 580.00ms 4 145.00ms 302ns 550.27ms cudaFree + 9.82% 143.03ms 9 15.892ms 8.7090us 142.78ms cudaStreamCreate + 1.23% 17.983ms 7 2.5690ms 23.210us 6.4563ms cudaMemcpy + 1.23% 17.849ms 2 8.9247ms 8.4726ms 9.3768ms cudaStreamSynchronize + 0.66% 9.5969ms 7 1.3710ms 288.43us 2.4279ms cudaHostAlloc + 0.13% 1.9530ms 11 177.54us 7.6810us 591.06us cudaMalloc + 0.07% 1.0424ms 8 130.30us 1.6970us 453.72us cudaGetDevice + 0.04% 527.90us 40 13.197us 525ns 253.99us cudaEventCreateWithFlags + 0.03% 435.73us 348 1.2520us 124ns 42.704us cuDeviceGetAttribute + 0.03% 419.36us 1 419.36us 419.36us 419.36us cudaGetDeviceCount + 0.02% 260.75us 2 130.38us 129.32us 131.43us cudaGetDeviceProperties + 0.02% 222.32us 2 111.16us 106.94us 115.39us cudaLaunch + 0.01% 214.06us 4 53.514us 28.586us 77.655us cuDeviceGetName + 0.01% 115.45us 4 28.861us 9.8250us 44.526us cuDeviceTotalMem + 0.01% 83.988us 4 20.997us 578ns 77.760us cudaSetDevice + 0.00% 38.918us 1 38.918us 38.918us 38.918us cudaEventCreate + 0.00% 34.573us 31 1.1150us 279ns 12.784us cudaDeviceGetAttribute + 0.00% 17.767us 1 17.767us 17.767us 17.767us cudaProfilerStart + 0.00% 15.228us 2 7.6140us 3.5460us 11.682us cudaConfigureCall + 0.00% 14.536us 2 7.2680us 1.1490us 13.387us cudaGetLastError + 0.00% 8.6080us 26 331ns 173ns 783ns cudaSetupArgument + 0.00% 5.5470us 6 924ns 215ns 2.6780us cuDeviceGet + 0.00% 5.4090us 6 901ns 328ns 3.3320us cuDeviceGetCount + 0.00% 4.1770us 3 1.3920us 1.0630us 1.8300us cuDriverGetVersion + 0.00% 3.4650us 3 1.1550us 1.0810us 1.2680us cuInit + 0.00% 830ns 1 830ns 830ns 830ns cudaRuntimeGetVersion + + +nvvp 工具 +-------------- + +如果想使用可视化的分析器 **nvvp**，您可以导入 :code:`nvprof -o ...` 的输出，或者从工具的界面里运行您的应用。 + +**备注: nvvp 也支持CPU的性能分析** (需在nvvp界面中选上才能开启） + +.. image:: nvvp1.png + :align: center + :scale: 33% + +从内核函数的角度， **nvvp** 可以精确说明一个长耗时操作的具体原因。 +同时，如下图所示， **nvvp** 的内核block使用情况、寄存器使用情况和共享内存使用情况能让我们对GPU的整体使用有更好的理解。 + + +.. image:: nvvp2.png + :align: center + :scale: 33% + +而从应用的角度， **nvvp** 可以帮您提供一些定位性能瓶颈的建议。 +例如，下图中就展示了一些关于内存数据迁徙和计算资源利用率的建议，为您做性能调优提供了方向。 + +.. image:: nvvp3.png + :align: center + :scale: 33% + +.. image:: nvvp4.png + :align: center + :scale: 33% + +性能分析小技巧 +================== + +- 开始阶段，从 **nvprof** 和 **nvvp** 的输出信息入手是个不错的选择。 +- 接下来可以考虑下时间线的分析。 +- 如果真想挖掘内核深处的某个秘密，您最好先确认：这一块的耗时比例真的太高，值得深入分析。 +- 可能的情况下，试着让输出的分析数据和理论值对应。 + + 1) 例如，如果我知道内核花了10ms来移动1GB数据，那我会期望分析工具统计到速度是100GB/s。 + 2) 若有不一致之处，很有可能实际应用就是没有按照您的预期情况运行。 +- 了解您的硬件：如果您的GPU理论可以达到6 TFLOPs（6万亿次浮点运算每秒），而当前已经有5.5 TFLOPs了，那估计这里的潜力就没啥好挖的了…… + +性能分析是性能优化的关键一步。有的时候简简单单的改变就能在性能上产生明显的优化效果！ +当然，具体情况因人而异。 + +参考资料 +=========== +Jeremy Appleyard, `GPU Profiling for Deep Learning `_, 2015 diff --git a/source/advanced_usage/development/host_memory_profiling_cn.md b/source/advanced_usage/development/host_memory_profiling_cn.md index b32efeb71..904968ba4 120000 --- a/source/advanced_usage/development/host_memory_profiling_cn.md +++ b/source/advanced_usage/development/host_memory_profiling_cn.md @@ -1 +1 @@ -../../../paddle/doc/fluid/howto/optimization/host_memory_profiling_cn.md \ No newline at end of file +../../../howto/optimization/host_memory_profiling_cn.md \ No newline at end of file diff --git a/source/advanced_usage/index.rst b/source/advanced_usage/index.rst index dea7c2366..89166573e 100644 --- a/source/advanced_usage/index.rst +++ b/source/advanced_usage/index.rst @@ -10,7 +10,6 @@ .. toctree:: :maxdepth: 2 - deploy/index_native.rst deploy/index_anakin.rst deploy/index_mobile.rst development/contribute_to_paddle.md diff --git a/source/advanced_usage/pics/anakin_fm_ch.png b/source/advanced_usage/pics/anakin_fm_ch.png new file mode 100644 index 0000000000000000000000000000000000000000..52d4992a22397119af949aa7c11a9ea6365c167c GIT binary patch literal 45319 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

S-4=8I67IiG{oTg*Uv#I{ zG#v}8y?)`DTzmpU5Ha%?u9LP0uyoOp#$b4&#m~J7!CZWDQPK|$y+}E EKc?MYb^rhX literal 0 HcmV?d00001 diff --git a/source/beginners_guide/basics/image_classification/index.md b/source/beginners_guide/basics/image_classification/index.md index 0f5a13d8b..5c41ed1c1 100644 --- a/source/beginners_guide/basics/image_classification/index.md +++ b/source/beginners_guide/basics/image_classification/index.md @@ -1,7 +1,7 @@ # 图像分类 -本教程源代码目录在[book/image_classification](https://github.com/PaddlePaddle/book/tree/develop/03.image_classification)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/168.html)。 +本教程源代码目录在[book/image_classification](https://github.com/PaddlePaddle/book/tree/develop/03.image_classification)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 @@ -36,7 +36,7 @@ 一个好的模型既要对不同类别识别正确，同时也应该能够对不同视角、光照、背景、变形或部分遮挡的图像正确识别(这里我们统一称作图像扰动)。图3展示了一些图像的扰动，较好的模型会像聪明的人类一样能够正确识别。 -![imageVariations](./image/variations.png) +![imageVariations](https://raw.githubusercontent.com/PaddlePaddle/book/develop/03.image_classification/image/variations.png)

图3. 扰动图片展示[22]

@@ -139,7 +139,7 @@ ResNet(Residual Network) \[[15](#参考文献)\] 是2015年ImageNet图像分类 由于ImageNet数据集较大，下载和训练较慢，为了方便大家学习，我们使用[CIFAR10]()数据集。CIFAR10数据集包含60,000张32x32的彩色图片，10个类别，每个类包含6,000张。其中50,000张图片作为训练集，10000张作为测试集。图11从每个类别中随机抽取了10张图片，展示了所有的类别。 -![CIFAR](./image/cifar.png) +![CIFAR](https://raw.githubusercontent.com/PaddlePaddle/book/develop/03.image_classification/image/cifar.png)

图11. CIFAR10数据集[21]

@@ -263,7 +263,7 @@ return tmp 2. 然后连接3组残差模块即下面配置3组 `layer_warp` ，每组采用图 10 左边残差模块组成。 3. 最后对网络做均值池化并返回该层。 -注意：除过第一层卷积层和最后一层全连接层之外，要求三组 `layer_warp` 总的含参层数能够被6整除，即 `resnet_cifar10` 的 depth 要满足 `$(depth - 2) % 6 == 0$` 。 +注意：除过第一层卷积层和最后一层全连接层之外，要求三组 `layer_warp` 总的含参层数能够被6整除，即 `resnet_cifar10` 的 depth 要满足 $(depth - 2) % 6 == 0$ 。 ```python def resnet_cifar10(ipt, depth=32): diff --git a/source/beginners_guide/basics/label_semantic_roles/index.md b/source/beginners_guide/basics/label_semantic_roles/index.md index 331c093d7..f77bfd1db 100644 --- a/source/beginners_guide/basics/label_semantic_roles/index.md +++ b/source/beginners_guide/basics/label_semantic_roles/index.md @@ -1,6 +1,6 @@ # 语义角色标注 -本教程源代码目录在[book/label_semantic_roles](https://github.com/PaddlePaddle/book/tree/develop/07.label_semantic_roles)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/178.html)。 +本教程源代码目录在[book/label_semantic_roles](https://github.com/PaddlePaddle/book/tree/develop/07.label_semantic_roles)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 @@ -44,11 +44,11 @@ $$\mbox{[小明]}_{\mbox{Agent}}\mbox{[昨天]}_{\mbox{Time}}\mbox{[晚上]}_{\m ### 栈式循环神经网络（Stacked Recurrent Neural Network） -深层网络有助于形成层次化特征，网络上层在下层已经学习到的初级特征基础上，形成更复杂的高级特征。尽管LSTM沿时间轴展开后等价于一个非常“深”的前馈网络，但由于LSTM各个时间步参数共享，`$t-1$`时刻状态到`$t$`时刻的映射，始终只经过了一次非线性映射，也就是说单层LSTM对状态转移的建模是 “浅” 的。堆叠多个LSTM单元，令前一个LSTM`$t$`时刻的输出，成为下一个LSTM单元`$t$`时刻的输入，帮助我们构建起一个深层网络，我们把它称为第一个版本的栈式循环神经网络。深层网络提高了模型拟合复杂模式的能力，能够更好地建模跨不同时间步的模式\[[2](#参考文献)\]。 +深层网络有助于形成层次化特征，网络上层在下层已经学习到的初级特征基础上，形成更复杂的高级特征。尽管LSTM沿时间轴展开后等价于一个非常“深”的前馈网络，但由于LSTM各个时间步参数共享，$t-1$时刻状态到$t$时刻的映射，始终只经过了一次非线性映射，也就是说单层LSTM对状态转移的建模是 “浅” 的。堆叠多个LSTM单元，令前一个LSTM$t$时刻的输出，成为下一个LSTM单元$t$时刻的输入，帮助我们构建起一个深层网络，我们把它称为第一个版本的栈式循环神经网络。深层网络提高了模型拟合复杂模式的能力，能够更好地建模跨不同时间步的模式\[[2](#参考文献)\]。 然而，训练一个深层LSTM网络并非易事。纵向堆叠多个LSTM单元可能遇到梯度在纵向深度上传播受阻的问题。通常，堆叠4层LSTM单元可以正常训练，当层数达到4~8层时，会出现性能衰减，这时必须考虑一些新的结构以保证梯度纵向顺畅传播，这是训练深层LSTM网络必须解决的问题。我们可以借鉴LSTM解决 “梯度消失梯度爆炸” 问题的智慧之一：在记忆单元（Memory Cell）这条信息传播的路线上没有非线性映射，当梯度反向传播时既不会衰减、也不会爆炸。因此，深层LSTM模型也可以在纵向上添加一条保证梯度顺畅传播的路径。 -一个LSTM单元完成的运算可以被分为三部分：（1）输入到隐层的映射（input-to-hidden） ：每个时间步输入信息`$x$`会首先经过一个矩阵映射，再作为遗忘门，输入门，记忆单元，输出门的输入，注意，这一次映射没有引入非线性激活；（2）隐层到隐层的映射（hidden-to-hidden）：这一步是LSTM计算的主体，包括遗忘门，输入门，记忆单元更新，输出门的计算；（3）隐层到输出的映射（hidden-to-output）：通常是简单的对隐层向量进行激活。我们在第一个版本的栈式网络的基础上，加入一条新的路径：除上一层LSTM输出之外，将前层LSTM的输入到隐层的映射作为的一个新的输入，同时加入一个线性映射去学习一个新的变换。 +一个LSTM单元完成的运算可以被分为三部分：（1）输入到隐层的映射（input-to-hidden） ：每个时间步输入信息$x$会首先经过一个矩阵映射，再作为遗忘门，输入门，记忆单元，输出门的输入，注意，这一次映射没有引入非线性激活；（2）隐层到隐层的映射（hidden-to-hidden）：这一步是LSTM计算的主体，包括遗忘门，输入门，记忆单元更新，输出门的计算；（3）隐层到输出的映射（hidden-to-output）：通常是简单的对隐层向量进行激活。我们在第一个版本的栈式网络的基础上，加入一条新的路径：除上一层LSTM输出之外，将前层LSTM的输入到隐层的映射作为的一个新的输入，同时加入一个线性映射去学习一个新的变换。 图3是最终得到的栈式循环神经网络结构示意图。 @@ -59,9 +59,9 @@ $$\mbox{[小明]}_{\mbox{Agent}}\mbox{[昨天]}_{\mbox{Time}}\mbox{[晚上]}_{\m ### 双向循环神经网络（Bidirectional Recurrent Neural Network） -在LSTM中，`$t$`时刻的隐藏层向量编码了到`$t$`时刻为止所有输入的信息，但`$t$`时刻的LSTM可以看到历史，却无法看到未来。在绝大多数自然语言处理任务中，我们几乎总是能拿到整个句子。这种情况下，如果能够像获取历史信息一样，得到未来的信息，对序列学习任务会有很大的帮助。 +在LSTM中，$t$时刻的隐藏层向量编码了到$t$时刻为止所有输入的信息，但$t$时刻的LSTM可以看到历史，却无法看到未来。在绝大多数自然语言处理任务中，我们几乎总是能拿到整个句子。这种情况下，如果能够像获取历史信息一样，得到未来的信息，对序列学习任务会有很大的帮助。 -为了克服这一缺陷，我们可以设计一种双向循环网络单元，它的思想简单且直接：对上一节的栈式循环神经网络进行一个小小的修改，堆叠多个LSTM单元，让每一层LSTM单元分别以：正向、反向、正向 …… 的顺序学习上一层的输出序列。于是，从第2层开始，`$t$`时刻我们的LSTM单元便总是可以看到历史和未来的信息。图4是基于LSTM的双向循环神经网络结构示意图。 +为了克服这一缺陷，我们可以设计一种双向循环网络单元，它的思想简单且直接：对上一节的栈式循环神经网络进行一个小小的修改，堆叠多个LSTM单元，让每一层LSTM单元分别以：正向、反向、正向 …… 的顺序学习上一层的输出序列。于是，从第2层开始，$t$时刻我们的LSTM单元便总是可以看到历史和未来的信息。图4是基于LSTM的双向循环神经网络结构示意图。 ![lstmStructure](./image/bidirectional_stacked_lstm.png)

@@ -74,7 +74,7 @@ $$\mbox{[小明]}_{\mbox{Agent}}\mbox{[昨天]}_{\mbox{Time}}\mbox{[晚上]}_{\m 使用神经网络模型解决问题的思路通常是：前层网络学习输入的特征表示，网络的最后一层在特征基础上完成最终的任务。在SRL任务中，深层LSTM网络学习输入的特征表示，条件随机场（Conditional Random Filed， CRF）在特征的基础上完成序列标注，处于整个网络的末端。 -CRF是一种概率化结构模型，可以看作是一个概率无向图模型，结点表示随机变量，边表示随机变量之间的概率依赖关系。简单来讲，CRF学习条件概率`$P(X|Y)$`，其中 `$X = (x_1, x_2, ... , x_n)$` 是输入序列，`$Y = (y_1, y_2, ... , y_n)$` 是标记序列；解码过程是给定 `$X$`序列求解令`$P(Y|X)$`最大的`$Y$`序列，即`$Y^* = \mbox{arg max}_{Y} P(Y | X)$`。 +CRF是一种概率化结构模型，可以看作是一个概率无向图模型，结点表示随机变量，边表示随机变量之间的概率依赖关系。简单来讲，CRF学习条件概率$P(X|Y)$，其中 $X = (x_1, x_2, ... , x_n)$ 是输入序列，$Y = (y_1, y_2, ... , y_n)$ 是标记序列；解码过程是给定 $X$序列求解令$P(Y|X)$最大的$Y$序列，即$Y^* = \mbox{arg max}_{Y} P(Y | X)$。 序列标注任务只需要考虑输入和输出都是一个线性序列，并且由于我们只是将输入序列作为条件，不做任何条件独立假设，因此输入序列的元素之间并不存在图结构。综上，在序列标注任务中使用的是如图5所示的定义在链式图上的CRF，称之为线性链条件随机场（Linear Chain Conditional Random Field）。 @@ -83,23 +83,23 @@ CRF是一种概率化结构模型，可以看作是一个概率无向图模型 图5. 序列标注任务中使用的线性链条件随机场

-根据线性链条件随机场上的因子分解定理\[[5](#参考文献)\]，在给定观测序列`$X$`时，一个特定标记序列`$Y$`的概率可以定义为： +根据线性链条件随机场上的因子分解定理\[[5](#参考文献)\]，在给定观测序列$X$时，一个特定标记序列$Y$的概率可以定义为： $$p(Y | X) = \frac{1}{Z(X)} \text{exp}\left(\sum_{i=1}^{n}\left(\sum_{j}\lambda_{j}t_{j} (y_{i - 1}, y_{i}, X, i) + \sum_{k} \mu_k s_k (y_i, X, i)\right)\right)$$ -其中`$Z(X)$`是归一化因子，`$t_j$` 是定义在边上的特征函数，依赖于当前和前一个位置，称为转移特征，表示对于输入序列`$X$`及其标注序列在 `$i$`及`$i - 1$`位置上标记的转移概率。`$s_k$`是定义在结点上的特征函数，称为状态特征，依赖于当前位置，表示对于观察序列`$X$`及其`$i$`位置的标记概率。`$\lambda_j$` 和 `$\mu_k$` 分别是转移特征函数和状态特征函数对应的权值。实际上，`$t$`和`$s$`可以用相同的数学形式表示，再对转移特征和状态特在各个位置`$i$`求和有：`$f_{k}(Y, X) = \sum_{i=1}^{n}f_k({y_{i - 1}, y_i, X, i})$`，把`$f$`统称为特征函数，于是`$P(Y|X)$`可表示为： +其中$Z(X)$是归一化因子，$t_j$ 是定义在边上的特征函数，依赖于当前和前一个位置，称为转移特征，表示对于输入序列$X$及其标注序列在 $i$及$i - 1$位置上标记的转移概率。$s_k$是定义在结点上的特征函数，称为状态特征，依赖于当前位置，表示对于观察序列$X$及其$i$位置的标记概率。$\lambda_j$ 和 $\mu_k$ 分别是转移特征函数和状态特征函数对应的权值。实际上，$t$和$s$可以用相同的数学形式表示，再对转移特征和状态特在各个位置$i$求和有：$f_{k}(Y, X) = \sum_{i=1}^{n}f_k({y_{i - 1}, y_i, X, i})$，把$f$统称为特征函数，于是$P(Y|X)$可表示为： $$p(Y|X, W) = \frac{1}{Z(X)}\text{exp}\sum_{k}\omega_{k}f_{k}(Y, X)$$ -`$\omega$`是特征函数对应的权值，是CRF模型要学习的参数。训练时，对于给定的输入序列和对应的标记序列集合`$D = \left[(X_1, Y_1), (X_2 , Y_2) , ... , (X_N, Y_N)\right]$` ，通过正则化的极大似然估计，求解如下优化目标： +$\omega$是特征函数对应的权值，是CRF模型要学习的参数。训练时，对于给定的输入序列和对应的标记序列集合$D = \left[(X_1, Y_1), (X_2 , Y_2) , ... , (X_N, Y_N)\right]$ ，通过正则化的极大似然估计，求解如下优化目标： $$\DeclareMathOperator*{\argmax}{arg\,max} L(\lambda, D) = - \text{log}\left(\prod_{m=1}^{N}p(Y_m|X_m, W)\right) + C \frac{1}{2}\lVert W\rVert^{2}$$ -这个优化目标可以通过反向传播算法和整个神经网络一起求解。解码时，对于给定的输入序列`$X$`，通过解码算法（通常有：维特比算法、Beam Search）求令出条件概率`$\bar{P}(Y|X)$`最大的输出序列 `$\bar{Y}$`。 +这个优化目标可以通过反向传播算法和整个神经网络一起求解。解码时，对于给定的输入序列$X$，通过解码算法（通常有：维特比算法、Beam Search）求令出条件概率$\bar{P}(Y|X)$最大的输出序列 $\bar{Y}$。 ### 深度双向LSTM（DB-LSTM）SRL模型 -在SRL任务中，输入是 “谓词” 和 “一句话”，目标是从这句话中找到谓词的论元，并标注论元的语义角色。如果一个句子含有`$n$`个谓词，这个句子会被处理`$n$`次。一个最为直接的模型是下面这样： +在SRL任务中，输入是 “谓词” 和 “一句话”，目标是从这句话中找到谓词的论元，并标注论元的语义角色。如果一个句子含有$n$个谓词，这个句子会被处理$n$次。一个最为直接的模型是下面这样： 1. 构造输入； - 输入1是谓词，输入2是句子 @@ -110,13 +110,13 @@ $$\DeclareMathOperator*{\argmax}{arg\,max} L(\lambda, D) = - \text{log}\left(\pr 大家可以尝试上面这种方法。这里，我们提出一些改进，引入两个简单但对提高系统性能非常有效的特征： -- 谓词上下文：上面的方法中，只用到了谓词的词向量表达谓词相关的所有信息，这种方法始终是非常弱的，特别是如果谓词在句子中出现多次，有可能引起一定的歧义。从经验出发，谓词前后若干个词的一个小片段，能够提供更丰富的信息，帮助消解歧义。于是，我们把这样的经验也添加到模型中，为每个谓词同时抽取一个“谓词上下文” 片段，也就是从这个谓词前后各取`$n$`个词构成的一个窗口片段； +- 谓词上下文：上面的方法中，只用到了谓词的词向量表达谓词相关的所有信息，这种方法始终是非常弱的，特别是如果谓词在句子中出现多次，有可能引起一定的歧义。从经验出发，谓词前后若干个词的一个小片段，能够提供更丰富的信息，帮助消解歧义。于是，我们把这样的经验也添加到模型中，为每个谓词同时抽取一个“谓词上下文” 片段，也就是从这个谓词前后各取$n$个词构成的一个窗口片段； - 谓词上下文区域标记：为句子中的每一个词引入一个0-1二值变量，表示它们是否在“谓词上下文”片段中； 修改后的模型如下（图6是一个深度为4的模型结构示意图）： 1. 构造输入 -- 输入1是句子序列，输入2是谓词序列，输入3是谓词上下文，从句子中抽取这个谓词前后各`$n$`个词，构成谓词上下文，用one-hot方式表示，输入4是谓词上下文区域标记，标记了句子中每一个词是否在谓词上下文中； +- 输入1是句子序列，输入2是谓词序列，输入3是谓词上下文，从句子中抽取这个谓词前后各$n$个词，构成谓词上下文，用one-hot方式表示，输入4是谓词上下文区域标记，标记了句子中每一个词是否在谓词上下文中； - 将输入2~3均扩展为和输入1一样长的序列； 2. 输入1~4均通过词表取词向量转换为实向量表示的词向量序列；其中输入1、3共享同一个词表，输入2和4各自独有词表； 3. 第2步的4个词向量序列作为双向LSTM模型的输入；LSTM模型学习输入序列的特征表示，得到新的特性表示序列； @@ -146,7 +146,7 @@ conll05st-release/ 原始数据需要进行数据预处理才能被PaddlePaddle处理，预处理包括下面几个步骤: 1. 将文本序列和标记序列其合并到一条记录中； -2. 一个句子如果含有`$n$`个谓词，这个句子会被处理`$n$`次，变成`$n$`条独立的训练样本，每个样本一个不同的谓词； +2. 一个句子如果含有$n$个谓词，这个句子会被处理$n$次，变成$n$条独立的训练样本，每个样本一个不同的谓词； 3. 抽取谓词上下文和构造谓词上下文区域标记； 4. 构造以BIO法表示的标记； 5. 依据词典获取词对应的整数索引。 diff --git a/source/beginners_guide/basics/machine_translation/index.md b/source/beginners_guide/basics/machine_translation/index.md index 06dc48bdb..5225758f3 100644 --- a/source/beginners_guide/basics/machine_translation/index.md +++ b/source/beginners_guide/basics/machine_translation/index.md @@ -1,6 +1,6 @@ # 机器翻译 -本教程源代码目录在[book/machine_translation](https://github.com/PaddlePaddle/book/tree/develop/08.machine_translation)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/179.html)。 +本教程源代码目录在[book/machine_translation](https://github.com/PaddlePaddle/book/tree/develop/08.machine_translation)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 @@ -41,7 +41,7 @@ 我们已经在[语义角色标注](https://github.com/PaddlePaddle/book/blob/develop/07.label_semantic_roles/README.cn.md)一章中介绍了一种双向循环神经网络，这里介绍Bengio团队在论文\[[2](#参考文献),[4](#参考文献)\]中提出的另一种结构。该结构的目的是输入一个序列，得到其在每个时刻的特征表示，即输出的每个时刻都用定长向量表示到该时刻的上下文语义信息。 -具体来说，该双向循环神经网络分别在时间维以顺序和逆序——即前向（forward）和后向（backward）——依次处理输入序列，并将每个时间步RNN的输出拼接成为最终的输出层。这样每个时间步的输出节点，都包含了输入序列中当前时刻完整的过去和未来的上下文信息。下图展示的是一个按时间步展开的双向循环神经网络。该网络包含一个前向和一个后向RNN，其中有六个权重矩阵：输入到前向隐层和后向隐层的权重矩阵（`$W_1, W_3$`），隐层到隐层自己的权重矩阵（`$W_2,W_5$`），前向隐层和后向隐层到输出层的权重矩阵（`$W_4, W_6$`）。注意，该网络的前向隐层和后向隐层之间没有连接。 +具体来说，该双向循环神经网络分别在时间维以顺序和逆序——即前向（forward）和后向（backward）——依次处理输入序列，并将每个时间步RNN的输出拼接成为最终的输出层。这样每个时间步的输出节点，都包含了输入序列中当前时刻完整的过去和未来的上下文信息。下图展示的是一个按时间步展开的双向循环神经网络。该网络包含一个前向和一个后向RNN，其中有六个权重矩阵：输入到前向隐层和后向隐层的权重矩阵（$W_1, W_3$），隐层到隐层自己的权重矩阵（$W_2,W_5$），前向隐层和后向隐层到输出层的权重矩阵（$W_4, W_6$）。注意，该网络的前向隐层和后向隐层之间没有连接。 ![bi_rnn](./image/bi_rnn.png)

@@ -60,13 +60,13 @@ 编码阶段分为三步： -1. one-hot vector表示：将源语言句子`$x=\left \{ x_1,x_2,...,x_T \right \}$`的每个词`$x_i$`表示成一个列向量`$w_i\epsilon \left \{ 0,1 \right \}^{\left | V \right |},i=1,2,...,T$`。这个向量`$w_i$`的维度与词汇表大小`$\left | V \right |$` 相同，并且只有一个维度上有值1（该位置对应该词在词汇表中的位置），其余全是0。 +1. one-hot vector表示：将源语言句子$x=\left \{ x_1,x_2,...,x_T \right \}$的每个词$x_i$表示成一个列向量$w_i\epsilon \left \{ 0,1 \right \}^{\left | V \right |},i=1,2,...,T$。这个向量$w_i$的维度与词汇表大小$\left | V \right |$ 相同，并且只有一个维度上有值1（该位置对应该词在词汇表中的位置），其余全是0。 -2. 映射到低维语义空间的词向量：one-hot vector表示存在两个问题，1）生成的向量维度往往很大，容易造成维数灾难；2）难以刻画词与词之间的关系（如语义相似性，也就是无法很好地表达语义）。因此，需再one-hot vector映射到低维的语义空间，由一个固定维度的稠密向量（称为词向量）表示。记映射矩阵为`$C\epsilon R^{K\times \left | V \right |}$`，用`$s_i=Cw_i$`表示第`$i$`个词的词向量，`$K$`为向量维度。 +2. 映射到低维语义空间的词向量：one-hot vector表示存在两个问题，1）生成的向量维度往往很大，容易造成维数灾难；2）难以刻画词与词之间的关系（如语义相似性，也就是无法很好地表达语义）。因此，需再one-hot vector映射到低维的语义空间，由一个固定维度的稠密向量（称为词向量）表示。记映射矩阵为$C\epsilon R^{K\times \left | V \right |}$，用$s_i=Cw_i$表示第$i$个词的词向量，$K$为向量维度。 -3. 用RNN编码源语言词序列：这一过程的计算公式为`$h_i=\varnothing _\theta \left ( h_{i-1}, s_i \right )$`，其中`$h_0$`是一个全零的向量，`$\varnothing _\theta$`是一个非线性激活函数，最后得到的`$\mathbf{h}=\left \{ h_1,..., h_T \right \}$`就是RNN依次读入源语言`$T$`个词的状态编码序列。整句话的向量表示可以采用`$\mathbf{h}$`在最后一个时间步`$T$`的状态编码，或使用时间维上的池化（pooling）结果。 +3. 用RNN编码源语言词序列：这一过程的计算公式为$h_i=\varnothing _\theta \left ( h_{i-1}, s_i \right )$，其中$h_0$是一个全零的向量，$\varnothing _\theta$是一个非线性激活函数，最后得到的$\mathbf{h}=\left \{ h_1,..., h_T \right \}$就是RNN依次读入源语言$T$个词的状态编码序列。整句话的向量表示可以采用$\mathbf{h}$在最后一个时间步$T$的状态编码，或使用时间维上的池化（pooling）结果。 -第3步也可以使用双向循环神经网络实现更复杂的句编码表示，具体可以用双向GRU实现。前向GRU按照词序列`$(x_1,x_2,...,x_T)$`的顺序依次编码源语言端词，并得到一系列隐层状态`$(\overrightarrow{h_1},\overrightarrow{h_2},...,\overrightarrow{h_T})$`。类似的，后向GRU按照`$(x_T,x_{T-1},...,x_1)$`的顺序依次编码源语言端词，得到`$(\overleftarrow{h_1},\overleftarrow{h_2},...,\overleftarrow{h_T})$`。最后对于词`$x_i$`，通过拼接两个GRU的结果得到它的隐层状态，即`$h_i=\left [ \overrightarrow{h_i^T},\overleftarrow{h_i^T} \right ]^{T}$`。 +第3步也可以使用双向循环神经网络实现更复杂的句编码表示，具体可以用双向GRU实现。前向GRU按照词序列$(x_1,x_2,...,x_T)$的顺序依次编码源语言端词，并得到一系列隐层状态$(\overrightarrow{h_1},\overrightarrow{h_2},...,\overrightarrow{h_T})$。类似的，后向GRU按照$(x_T,x_{T-1},...,x_1)$的顺序依次编码源语言端词，得到$(\overleftarrow{h_1},\overleftarrow{h_2},...,\overleftarrow{h_T})$。最后对于词$x_i$，通过拼接两个GRU的结果得到它的隐层状态，即$h_i=\left [ \overrightarrow{h_i^T},\overleftarrow{h_i^T} \right ]^{T}$。 ![encoder_attention](./image/encoder_attention.png)

@@ -77,19 +77,19 @@ 机器翻译任务的训练过程中，解码阶段的目标是最大化下一个正确的目标语言词的概率。思路是： -1. 每一个时刻，根据源语言句子的编码信息（又叫上下文向量，context vector）`$c$`、真实目标语言序列的第`$i$`个词`$u_i$`和`$i$`时刻RNN的隐层状态`$z_i$`，计算出下一个隐层状态`$z_{i+1}$`。计算公式如下： +1. 每一个时刻，根据源语言句子的编码信息（又叫上下文向量，context vector）$c$、真实目标语言序列的第$i$个词$u_i$和$i$时刻RNN的隐层状态$z_i$，计算出下一个隐层状态$z_{i+1}$。计算公式如下： $$z_{i+1}=\phi _{\theta '}\left ( c,u_i,z_i \right )$$ -其中`$\phi _{\theta '}$`是一个非线性激活函数；`$c=q\mathbf{h}$`是源语言句子的上下文向量，在不使用[注意力机制](#注意力机制)时，如果[编码器](#编码器)的输出是源语言句子编码后的最后一个元素，则可以定义`$c=h_T$`；`$u_i$`是目标语言序列的第`$i$`个单词，`$u_0$`是目标语言序列的开始标记``，表示解码开始；`$z_i$`是`$i$`时刻解码RNN的隐层状态，`$z_0$`是一个全零的向量。 +其中$\phi _{\theta '}$是一个非线性激活函数；$c=q\mathbf{h}$是源语言句子的上下文向量，在不使用[注意力机制](#注意力机制)时，如果[编码器](#编码器)的输出是源语言句子编码后的最后一个元素，则可以定义$c=h_T$；$u_i$是目标语言序列的第$i$个单词，$u_0$是目标语言序列的开始标记``，表示解码开始；$z_i$是$i$时刻解码RNN的隐层状态，$z_0$是一个全零的向量。 -2. 将`$z_{i+1}$`通过`softmax`归一化，得到目标语言序列的第`$i+1$`个单词的概率分布`$p_{i+1}$`。概率分布公式如下： +2. 将$z_{i+1}$通过`softmax`归一化，得到目标语言序列的第$i+1$个单词的概率分布$p_{i+1}$。概率分布公式如下： $$p\left ( u_{i+1}|u_{<i+1},\mathbf{x} \right )=softmax(W_sz_{i+1}+b_z)$$ -其中`$W_sz_{i+1}+b_z$`是对每个可能的输出单词进行打分，再用softmax归一化就可以得到第`$i+1$`个词的概率`$p_{i+1}$`。 +其中$W_sz_{i+1}+b_z$是对每个可能的输出单词进行打分，再用softmax归一化就可以得到第$i+1$个词的概率$p_{i+1}$。 -3. 根据`$p_{i+1}$`和`$u_{i+1}$`计算代价。 +3. 根据$p_{i+1}$和$u_{i+1}$计算代价。 4. 重复步骤1~3，直到目标语言序列中的所有词处理完毕。 机器翻译任务的生成过程，通俗来讲就是根据预先训练的模型来翻译源语言句子。生成过程中的解码阶段和上述训练过程的有所差异，具体介绍请见[柱搜索算法](#柱搜索算法)。 @@ -102,12 +102,12 @@ $$p\left ( u_{i+1}|u_{<i+1},\mathbf{x} \right )=softmax(W_sz_{i+1}+b_z)$$ 使用柱搜索算法的解码阶段，目标是最大化生成序列的概率。思路是： -1. 每一个时刻，根据源语言句子的编码信息`$c$`、生成的第`$i$`个目标语言序列单词`$u_i$`和`$i$`时刻RNN的隐层状态`$z_i$`，计算出下一个隐层状态`$z_{i+1}$`。 -2. 将`$z_{i+1}$`通过`softmax`归一化，得到目标语言序列的第`$i+1$`个单词的概率分布`$p_{i+1}$`。 -3. 根据`$p_{i+1}$`采样出单词`$u_{i+1}$`。 +1. 每一个时刻，根据源语言句子的编码信息$c$、生成的第$i$个目标语言序列单词$u_i$和$i$时刻RNN的隐层状态$z_i$，计算出下一个隐层状态$z_{i+1}$。 +2. 将$z_{i+1}$通过`softmax`归一化，得到目标语言序列的第$i+1$个单词的概率分布$p_{i+1}$。 +3. 根据$p_{i+1}$采样出单词$u_{i+1}$。 4. 重复步骤1~3，直到获得句子结束标记``或超过句子的最大生成长度为止。 -注意：`$z_{i+1}$`和`$p_{i+1}$`的计算公式同[解码器](#解码器)中的一样。且由于生成时的每一步都是通过贪心法实现的，因此并不能保证得到全局最优解。 +注意：$z_{i+1}$和$p_{i+1}$的计算公式同[解码器](#解码器)中的一样。且由于生成时的每一步都是通过贪心法实现的，因此并不能保证得到全局最优解。 ## 数据介绍 @@ -118,7 +118,7 @@ $$p\left ( u_{i+1}|u_{<i+1},\mathbf{x} \right )=softmax(W_sz_{i+1}+b_z)$$ 我们的预处理流程包括两步： - 将每个源语言到目标语言的平行语料库文件合并为一个文件： - 合并每个`XXX.src`和`XXX.trg`文件为`XXX`。 -- `XXX`中的第`$i$`行内容为`XXX.src`中的第`$i$`行和`XXX.trg`中的第`$i$`行连接，用'\t'分隔。 +- `XXX`中的第$i$行内容为`XXX.src`中的第$i$行和`XXX.trg`中的第$i$行连接，用'\t'分隔。 - 创建训练数据的“源字典”和“目标字典”。每个字典都有**DICTSIZE**个单词，包括：语料中词频最高的（DICTSIZE - 3）个单词，和3个特殊符号``（序列的开始）、``（序列的结束）和``（未登录词）。 ### 示例数据 diff --git a/source/beginners_guide/basics/recommender_system/index.md b/source/beginners_guide/basics/recommender_system/index.md index b0845ca81..2c77613de 100644 --- a/source/beginners_guide/basics/recommender_system/index.md +++ b/source/beginners_guide/basics/recommender_system/index.md @@ -1,6 +1,6 @@ # 个性化推荐 -本教程源代码目录在[book/recommender_system](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/176.html)。 +本教程源代码目录在[book/recommender_system](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 @@ -45,20 +45,20 @@ YouTube是世界上最大的视频上传、分享和发现网站，YouTube推荐 候选生成网络将推荐问题建模为一个类别数极大的多类分类问题：对于一个Youtube用户，使用其观看历史（视频ID）、搜索词记录（search tokens）、人口学信息（如地理位置、用户登录设备）、二值特征（如性别，是否登录）和连续特征（如用户年龄）等，对视频库中所有视频进行多分类，得到每一类别的分类结果（即每一个视频的推荐概率），最终输出概率较高的几百个视频。 -首先，将观看历史及搜索词记录这类历史信息，映射为向量后取平均值得到定长表示；同时，输入人口学特征以优化新用户的推荐效果，并将二值特征和连续特征归一化处理到[0, 1]范围。接下来，将所有特征表示拼接为一个向量，并输入给非线形多层感知器（MLP，详见[识别数字](https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/README.cn.md)教程）处理。最后，训练时将MLP的输出给softmax做分类，预测时计算用户的综合特征（MLP的输出）与所有视频的相似度，取得分最高的`$k$`个作为候选生成网络的筛选结果。图2显示了候选生成网络结构。 +首先，将观看历史及搜索词记录这类历史信息，映射为向量后取平均值得到定长表示；同时，输入人口学特征以优化新用户的推荐效果，并将二值特征和连续特征归一化处理到[0, 1]范围。接下来，将所有特征表示拼接为一个向量，并输入给非线形多层感知器（MLP，详见[识别数字](https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/README.cn.md)教程）处理。最后，训练时将MLP的输出给softmax做分类，预测时计算用户的综合特征（MLP的输出）与所有视频的相似度，取得分最高的$k$个作为候选生成网络的筛选结果。图2显示了候选生成网络结构。 ![Deep_candidate_generation_model_architecture](./image/Deep_candidate_generation_model_architecture.png)

图2. 候选生成网络结构

-对于一个用户`$U$`，预测此刻用户要观看的视频`$\omega$`为视频`$i$`的概率公式为： +对于一个用户$U$，预测此刻用户要观看的视频$\omega$为视频$i$的概率公式为： $$P(\omega=i|u)=\frac{e^{v_{i}u}}{\sum_{j \in V}e^{v_{j}u}}$$ -其中`$u$`为用户`$U$`的特征表示，`$V$`为视频库集合，`$v_i$`为视频库中第`$i$`个视频的特征表示。`$u$`和`$v_i$`为长度相等的向量，两者点积可以通过全连接层实现。 +其中$u$为用户$U$的特征表示，$V$为视频库集合，$v_i$为视频库中第$i$个视频的特征表示。$u$和$v_i$为长度相等的向量，两者点积可以通过全连接层实现。 -考虑到softmax分类的类别数非常多，为了保证一定的计算效率：1）训练阶段，使用负样本类别采样将实际计算的类别数缩小至数千；2）推荐（预测）阶段，忽略softmax的归一化计算（不影响结果），将类别打分问题简化为点积（dot product）空间中的最近邻（nearest neighbor）搜索问题，取与`$u$`最近的`$k$`个视频作为生成的候选。 +考虑到softmax分类的类别数非常多，为了保证一定的计算效率：1）训练阶段，使用负样本类别采样将实际计算的类别数缩小至数千；2）推荐（预测）阶段，忽略softmax的归一化计算（不影响结果），将类别打分问题简化为点积（dot product）空间中的最近邻（nearest neighbor）搜索问题，取与$u$最近的$k$个视频作为生成的候选。 #### 排序网络（Ranking Network） 排序网络的结构类似于候选生成网络，但是它的目标是对候选进行更细致的打分排序。和传统广告排序中的特征抽取方法类似，这里也构造了大量的用于视频排序的相关特征（如视频 ID、上次观看时间等）。这些特征的处理方式和候选生成网络类似，不同之处是排序网络的顶部是一个加权逻辑回归（weighted logistic regression），它对所有候选视频进行打分，从高到底排序后将分数较高的一些视频返回给用户。 @@ -77,15 +77,15 @@ $$P(\omega=i|u)=\frac{e^{v_{i}u}}{\sum_{j \in V}e^{v_{j}u}}$$ 图3. 卷积神经网络文本分类模型

-假设待处理句子的长度为`$n$`，其中第`$i$`个词的词向量（word embedding）为`$x_i\in\mathbb{R}^k$`，`$k$`为维度大小。 +假设待处理句子的长度为$n$，其中第$i$个词的词向量（word embedding）为$x_i\in\mathbb{R}^k$，$k$为维度大小。 -首先，进行词向量的拼接操作：将每`$h$`个词拼接起来形成一个大小为`$h$`的词窗口，记为`$x_{i:i+h-1}$`，它表示词序列`$x_{i},x_{i+1},\ldots,x_{i+h-1}$`的拼接，其中，`$i$`表示词窗口中第一个词在整个句子中的位置，取值范围从`$1$`到`$n-h+1$`，`$x_{i:i+h-1}\in\mathbb{R}^{hk}$`。 +首先，进行词向量的拼接操作：将每$h$个词拼接起来形成一个大小为$h$的词窗口，记为$x_{i:i+h-1}$，它表示词序列$x_{i},x_{i+1},\ldots,x_{i+h-1}$的拼接，其中，$i$表示词窗口中第一个词在整个句子中的位置，取值范围从$1$到$n-h+1$，$x_{i:i+h-1}\in\mathbb{R}^{hk}$。 -其次，进行卷积操作：把卷积核(kernel)`$w\in\mathbb{R}^{hk}$`应用于包含`$h$`个词的窗口`$x_{i:i+h-1}$`，得到特征`$c_i=f(w\cdot x_{i:i+h-1}+b)$`，其中`$b\in\mathbb{R}$`为偏置项（bias），`$f$`为非线性激活函数，如`$sigmoid$`。将卷积核应用于句子中所有的词窗口`${x_{1:h},x_{2:h+1},\ldots,x_{n-h+1:n}}$`，产生一个特征图（feature map）： +其次，进行卷积操作：把卷积核(kernel)$w\in\mathbb{R}^{hk}$应用于包含$h$个词的窗口$x_{i:i+h-1}$，得到特征$c_i=f(w\cdot x_{i:i+h-1}+b)$，其中$b\in\mathbb{R}$为偏置项（bias），$f$为非线性激活函数，如$sigmoid$。将卷积核应用于句子中所有的词窗口${x_{1:h},x_{2:h+1},\ldots,x_{n-h+1:n}}$，产生一个特征图（feature map）： $$c=[c_1,c_2,\ldots,c_{n-h+1}], c \in \mathbb{R}^{n-h+1}$$ -接下来，对特征图采用时间维度上的最大池化（max pooling over time）操作得到此卷积核对应的整句话的特征`$\hat c$`，它是特征图中所有元素的最大值： +接下来，对特征图采用时间维度上的最大池化（max pooling over time）操作得到此卷积核对应的整句话的特征$\hat c$，它是特征图中所有元素的最大值： $$\hat c=max(c)$$ diff --git a/source/beginners_guide/basics/understand_sentiment/index.md b/source/beginners_guide/basics/understand_sentiment/index.md index 792781aed..bbb065dfc 100644 --- a/source/beginners_guide/basics/understand_sentiment/index.md +++ b/source/beginners_guide/basics/understand_sentiment/index.md @@ -1,6 +1,6 @@ # 情感分析 -本教程源代码目录在[book/understand_sentiment](https://github.com/PaddlePaddle/book/tree/develop/06.understand_sentiment)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/177.html)。 +本教程源代码目录在[book/understand_sentiment](https://github.com/PaddlePaddle/book/tree/develop/06.understand_sentiment)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 @@ -41,44 +41,44 @@ 图1. 循环神经网络按时间展开的示意图

-循环神经网络按时间展开后如图1所示：在第`$t$`时刻，网络读入第`$t$`个输入`$x_t$`（向量表示）及前一时刻隐层的状态值`$h_{t-1}$`（向量表示，`$h_0$`一般初始化为`$0$`向量），计算得出本时刻隐层的状态值`$h_t$`，重复这一步骤直至读完所有输入。如果将循环神经网络所表示的函数记为`$f$`，则其公式可表示为： +循环神经网络按时间展开后如图1所示：在第$t$时刻，网络读入第$t$个输入$x_t$（向量表示）及前一时刻隐层的状态值$h_{t-1}$（向量表示，$h_0$一般初始化为$0$向量），计算得出本时刻隐层的状态值$h_t$，重复这一步骤直至读完所有输入。如果将循环神经网络所表示的函数记为$f$，则其公式可表示为： $$h_t=f(x_t,h_{t-1})=\sigma(W_{xh}x_t+W_{hh}h_{t-1}+b_h)$$ -其中`$W_{xh}$`是输入到隐层的矩阵参数，`$W_{hh}$`是隐层到隐层的矩阵参数，`$b_h$`为隐层的偏置向量（bias）参数，`$\sigma$`为`$sigmoid$`函数。 +其中$W_{xh}$是输入到隐层的矩阵参数，$W_{hh}$是隐层到隐层的矩阵参数，$b_h$为隐层的偏置向量（bias）参数，$\sigma$为$sigmoid$函数。 -在处理自然语言时，一般会先将词（one-hot表示）映射为其词向量（word embedding）表示，然后再作为循环神经网络每一时刻的输入`$x_t$`。此外，可以根据实际需要的不同在循环神经网络的隐层上连接其它层。如，可以把一个循环神经网络的隐层输出连接至下一个循环神经网络的输入构建深层（deep or stacked）循环神经网络，或者提取最后一个时刻的隐层状态作为句子表示进而使用分类模型等等。 +在处理自然语言时，一般会先将词（one-hot表示）映射为其词向量（word embedding）表示，然后再作为循环神经网络每一时刻的输入$x_t$。此外，可以根据实际需要的不同在循环神经网络的隐层上连接其它层。如，可以把一个循环神经网络的隐层输出连接至下一个循环神经网络的输入构建深层（deep or stacked）循环神经网络，或者提取最后一个时刻的隐层状态作为句子表示进而使用分类模型等等。 ### 长短期记忆网络（LSTM） 对于较长的序列数据，循环神经网络的训练过程中容易出现梯度消失或爆炸现象\[[6](#参考文献)\]。为了解决这一问题，Hochreiter S, Schmidhuber J. (1997)提出了LSTM(long short term memory\[[5](#参考文献)\])。 -相比于简单的循环神经网络，LSTM增加了记忆单元`$c$`、输入门`$i$`、遗忘门`$f$`及输出门`$o$`。这些门及记忆单元组合起来大大提升了循环神经网络处理长序列数据的能力。若将基于LSTM的循环神经网络表示的函数记为`$F$`，则其公式为： +相比于简单的循环神经网络，LSTM增加了记忆单元$c$、输入门$i$、遗忘门$f$及输出门$o$。这些门及记忆单元组合起来大大提升了循环神经网络处理长序列数据的能力。若将基于LSTM的循环神经网络表示的函数记为$F$，则其公式为： $$ h_t=F(x_t,h_{t-1})$$ -`$F$`由下列公式组合而成\[[7](#参考文献)\]： +$F$由下列公式组合而成\[[7](#参考文献)\]： $$ i_t = \sigma{(W_{xi}x_t+W_{hi}h_{t-1}+W_{ci}c_{t-1}+b_i)} $$ $$ f_t = \sigma(W_{xf}x_t+W_{hf}h_{t-1}+W_{cf}c_{t-1}+b_f) $$ $$ c_t = f_t\odot c_{t-1}+i_t\odot tanh(W_{xc}x_t+W_{hc}h_{t-1}+b_c) $$ $$ o_t = \sigma(W_{xo}x_t+W_{ho}h_{t-1}+W_{co}c_{t}+b_o) $$ $$ h_t = o_t\odot tanh(c_t) $$ -其中，`$i_t, f_t, c_t, o_t$`分别表示输入门，遗忘门，记忆单元及输出门的向量值，带角标的`$W$`及`$b$`为模型参数，`$tanh$`为双曲正切函数，`$\odot$`表示逐元素（elementwise）的乘法操作。输入门控制着新输入进入记忆单元`$c$`的强度，遗忘门控制着记忆单元维持上一时刻值的强度，输出门控制着输出记忆单元的强度。三种门的计算方式类似，但有着完全不同的参数，它们各自以不同的方式控制着记忆单元`$c$`，如图2所示： +其中，$i_t, f_t, c_t, o_t$分别表示输入门，遗忘门，记忆单元及输出门的向量值，带角标的$W$及$b$为模型参数，$tanh$为双曲正切函数，$\odot$表示逐元素（elementwise）的乘法操作。输入门控制着新输入进入记忆单元$c$的强度，遗忘门控制着记忆单元维持上一时刻值的强度，输出门控制着输出记忆单元的强度。三种门的计算方式类似，但有着完全不同的参数，它们各自以不同的方式控制着记忆单元$c$，如图2所示： ![lstm](./image/lstm.png)

-图2. 时刻`$t$`的LSTM [7] +图2. 时刻$t$的LSTM [7]

LSTM通过给简单的循环神经网络增加记忆及控制门的方式，增强了其处理远距离依赖问题的能力。类似原理的改进还有Gated Recurrent Unit (GRU)\[[8](#参考文献)\]，其设计更为简洁一些。**这些改进虽然各有不同，但是它们的宏观描述却与简单的循环神经网络一样（如图2所示），即隐状态依据当前输入及前一时刻的隐状态来改变，不断地循环这一过程直至输入处理完毕：** $$ h_t=Recrurent(x_t,h_{t-1})$$ -其中，`$Recrurent$`可以表示简单的循环神经网络、GRU或LSTM。 +其中，$Recrurent$可以表示简单的循环神经网络、GRU或LSTM。 ### 栈式双向LSTM（Stacked Bidirectional LSTM） -对于正常顺序的循环神经网络，`$h_t$`包含了`$t$`时刻之前的输入信息，也就是上文信息。同样，为了得到下文信息，我们可以使用反方向（将输入逆序处理）的循环神经网络。结合构建深层循环神经网络的方法（深层神经网络往往能得到更抽象和高级的特征表示），我们可以通过构建更加强有力的基于LSTM的栈式双向循环神经网络\[[9](#参考文献)\]，来对时序数据进行建模。 +对于正常顺序的循环神经网络，$h_t$包含了$t$时刻之前的输入信息，也就是上文信息。同样，为了得到下文信息，我们可以使用反方向（将输入逆序处理）的循环神经网络。结合构建深层循环神经网络的方法（深层神经网络往往能得到更抽象和高级的特征表示），我们可以通过构建更加强有力的基于LSTM的栈式双向循环神经网络\[[9](#参考文献)\]，来对时序数据进行建模。 如图3所示（以三层为例），奇数层LSTM正向，偶数层LSTM反向，高一层的LSTM使用低一层LSTM及之前所有层的信息作为输入，对最高层LSTM序列使用时间维度上的最大池化即可得到文本的定长向量表示（这一表示充分融合了文本的上下文信息，并且对文本进行了深层次抽象），最后我们将文本表示连接至softmax构建分类模型。 diff --git a/source/beginners_guide/basics/word2vec/index.md b/source/beginners_guide/basics/word2vec/index.md index dff9471aa..b0cc52978 100644 --- a/source/beginners_guide/basics/word2vec/index.md +++ b/source/beginners_guide/basics/word2vec/index.md @@ -1,7 +1,7 @@ # 词向量 -本教程源代码目录在[book/word2vec](https://github.com/PaddlePaddle/book/tree/develop/04.word2vec)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/175.html)。 +本教程源代码目录在[book/word2vec](https://github.com/PaddlePaddle/book/tree/develop/04.word2vec)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 @@ -12,15 +12,15 @@ One-hot vector虽然自然，但是用处有限。比如，在互联网广告系统里，如果用户输入的query是“母亲节”，而有一个广告的关键词是“康乃馨”。虽然按照常理，我们知道这两个词之间是有联系的——母亲节通常应该送给母亲一束康乃馨；但是这两个词对应的one-hot vectors之间的距离度量，无论是欧氏距离还是余弦相似度(cosine similarity)，由于其向量正交，都认为这两个词毫无相关性。 得出这种与我们相悖的结论的根本原因是：每个词本身的信息量都太小。所以，仅仅给定两个词，不足以让我们准确判别它们是否相关。要想精确计算相关性，我们还需要更多的信息——从大量数据里通过机器学习方法归纳出来的知识。 -在机器学习领域里，各种“知识”被各种模型表示，词向量模型(word embedding model)就是其中的一类。通过词向量模型可将一个 one-hot vector映射到一个维度更低的实数向量（embedding vector），如`$embedding(Mother's\ Day) = [0.3, 4.2, -1.5, ...], embedding(Carnation) = [0.2, 5.6, -2.3, ...]$`。在这个映射到的实数向量表示中，希望两个语义（或用法）上相似的词对应的词向量“更像”，这样如“母亲节”和“康乃馨”的对应词向量的余弦相似度就不再为零了。 +在机器学习领域里，各种“知识”被各种模型表示，词向量模型(word embedding model)就是其中的一类。通过词向量模型可将一个 one-hot vector映射到一个维度更低的实数向量（embedding vector），如$embedding(Mother's\ Day) = [0.3, 4.2, -1.5, ...], embedding(Carnation) = [0.2, 5.6, -2.3, ...]$。在这个映射到的实数向量表示中，希望两个语义（或用法）上相似的词对应的词向量“更像”，这样如“母亲节”和“康乃馨”的对应词向量的余弦相似度就不再为零了。 -词向量模型可以是概率模型、共生矩阵(co-occurrence matrix)模型或神经元网络模型。在用神经网络求词向量之前，传统做法是统计一个词语的共生矩阵`$X$`。`$X$`是一个`$|V| \times |V|$` 大小的矩阵，`$X_{ij}$`表示在所有语料中，词汇表`V`(vocabulary)中第i个词和第j个词同时出现的词数，`$|V|$`为词汇表的大小。对`$X$`做矩阵分解（如奇异值分解，Singular Value Decomposition \[[5](#参考文献)\]），得到的`$U$`即视为所有词的词向量： +词向量模型可以是概率模型、共生矩阵(co-occurrence matrix)模型或神经元网络模型。在用神经网络求词向量之前，传统做法是统计一个词语的共生矩阵$X$。$X$是一个$|V| \times |V|$ 大小的矩阵，$X_{ij}$表示在所有语料中，词汇表`V`(vocabulary)中第i个词和第j个词同时出现的词数，$|V|$为词汇表的大小。对$X$做矩阵分解（如奇异值分解，Singular Value Decomposition \[[5](#参考文献)\]），得到的$U$即视为所有词的词向量： $$X = USV^T$$ 但这样的传统做法有很多问题：
1) 由于很多词没有出现，导致矩阵极其稀疏，因此需要对词频做额外处理来达到好的矩阵分解效果；
-2) 矩阵非常大，维度太高(通常达到`$10^6*10^6$`的数量级)；
+2) 矩阵非常大，维度太高(通常达到$10^6*10^6$的数量级)；
3) 需要手动去掉停用词（如although, a,...），不然这些频繁出现的词也会影响矩阵分解的效果。 @@ -36,7 +36,7 @@ $$X = USV^T$$ 图1. 词向量的二维投影

-另一方面，我们知道两个向量的余弦值在`$[-1,1]$`的区间内：两个完全相同的向量余弦值为1, 两个相互垂直的向量之间余弦值为0，两个方向完全相反的向量余弦值为-1，即相关性和余弦值大小成正比。因此我们还可以计算两个词向量的余弦相似度: +另一方面，我们知道两个向量的余弦值在$[-1,1]$的区间内：两个完全相同的向量余弦值为1, 两个相互垂直的向量之间余弦值为0，两个方向完全相反的向量余弦值为-1，即相关性和余弦值大小成正比。因此我们还可以计算两个词向量的余弦相似度: ``` similarity: 0.899180685161 @@ -56,10 +56,10 @@ similarity: -0.0997506977351 ### 语言模型 在介绍词向量模型之前，我们先来引入一个概念：语言模型。 -语言模型旨在为语句的联合概率函数`$P(w_1, ..., w_T)$`建模, 其中`$w_i$`表示句子中的第i个词。语言模型的目标是，希望模型对有意义的句子赋予大概率，对没意义的句子赋予小概率。 +语言模型旨在为语句的联合概率函数$P(w_1, ..., w_T)$建模, 其中$w_i$表示句子中的第i个词。语言模型的目标是，希望模型对有意义的句子赋予大概率，对没意义的句子赋予小概率。 这样的模型可以应用于很多领域，如机器翻译、语音识别、信息检索、词性标注、手写识别等，它们都希望能得到一个连续序列的概率。 以信息检索为例，当你在搜索“how long is a football bame”时（bame是一个医学名词），搜索引擎会提示你是否希望搜索"how long is a football game", 这是因为根据语言模型计算出“how long is a football bame”的概率很低，而与bame近似的，可能引起错误的词中，game会使该句生成的概率最大。 -对语言模型的目标概率`$P(w_1, ..., w_T)$`，如果假设文本中每个词都是相互独立的，则整句话的联合概率可以表示为其中所有词语条件概率的乘积，即： +对语言模型的目标概率$P(w_1, ..., w_T)$，如果假设文本中每个词都是相互独立的，则整句话的联合概率可以表示为其中所有词语条件概率的乘积，即： $$P(w_1, ..., w_T) = \prod_{t=1}^TP(w_t)$$ @@ -75,7 +75,7 @@ $$P(w_1, ..., w_T) = \prod_{t=1}^TP(w_t | w_1, ... , w_{t-1})$$ Yoshua Bengio等科学家就于2003年在著名论文 Neural Probabilistic Language Models \[[1](#参考文献)\] 中介绍如何学习一个神经元网络表示的词向量模型。文中的神经概率语言模型（Neural Network Language Model，NNLM）通过一个线性映射和一个非线性隐层连接，同时学习了语言模型和词向量，即通过学习大量语料得到词语的向量表达，通过这些向量得到整个句子的概率。用这种方法学习语言模型可以克服维度灾难（curse of dimensionality）,即训练和测试数据不同导致的模型不准。注意：由于“神经概率语言模型”说法较为泛泛，我们在这里不用其NNLM的本名，考虑到其具体做法，本文中称该模型为N-gram neural model。 -我们在上文中已经讲到用条件概率建模语言模型，即一句话中第`$t$`个词的概率和该句话的前`$t-1$`个词相关。可实际上越远的词语其实对该词的影响越小，那么如果考虑一个n-gram, 每个词都只受其前面`n-1`个词的影响，则有： +我们在上文中已经讲到用条件概率建模语言模型，即一句话中第$t$个词的概率和该句话的前$t-1$个词相关。可实际上越远的词语其实对该词的影响越小，那么如果考虑一个n-gram, 每个词都只受其前面`n-1`个词的影响，则有： $$P(w_1, ..., w_T) = \prod_{t=n}^TP(w_t|w_{t-1}, w_{t-2}, ..., w_{t-n+1})$$ @@ -83,7 +83,7 @@ $$P(w_1, ..., w_T) = \prod_{t=n}^TP(w_t|w_{t-1}, w_{t-2}, ..., w_{t-n+1})$$ $$\frac{1}{T}\sum_t f(w_t, w_{t-1}, ..., w_{t-n+1};\theta) + R(\theta)$$ -其中`$f(w_t, w_{t-1}, ..., w_{t-n+1})$`表示根据历史n-1个词得到当前词`$w_t$`的条件概率，`$R(\theta)$`表示参数正则项。 +其中$f(w_t, w_{t-1}, ..., w_{t-n+1})$表示根据历史n-1个词得到当前词$w_t$的条件概率，$R(\theta)$表示参数正则项。 ![nnlm](./image/nnlm.png)

@@ -91,17 +91,17 @@ $$\frac{1}{T}\sum_t f(w_t, w_{t-1}, ..., w_{t-n+1};\theta) + R(\theta)$$

图2展示了N-gram神经网络模型，从下往上看，该模型分为以下几个部分： -- 对于每个样本，模型输入`$w_{t-n+1},...w_{t-1}$`, 输出句子第t个词为字典中`|V|`个词的概率。 +- 对于每个样本，模型输入$w_{t-n+1},...w_{t-1}$, 输出句子第t个词为字典中`|V|`个词的概率。 -每个输入词`$w_{t-n+1},...w_{t-1}$`首先通过映射矩阵映射到词向量`$C(w_{t-n+1}),...C(w_{t-1})$`。 +每个输入词$w_{t-n+1},...w_{t-1}$首先通过映射矩阵映射到词向量$C(w_{t-n+1}),...C(w_{t-1})$。 - 然后所有词语的词向量连接成一个大向量，并经过一个非线性映射得到历史词语的隐层表示： $$g=Utanh(\theta^Tx + b_1) + Wx + b_2$$ -其中，`$x$`为所有词语的词向量连接成的大向量，表示文本历史特征；`$\theta$`、`$U$`、`$b_1$`、`$b_2$`和`$W$`分别为词向量层到隐层连接的参数。`$g$`表示未经归一化的所有输出单词概率，`$g_i$`表示未经归一化的字典中第`$i$`个单词的输出概率。 +其中，$x$为所有词语的词向量连接成的大向量，表示文本历史特征；$\theta$、$U$、$b_1$、$b_2$和$W$分别为词向量层到隐层连接的参数。$g$表示未经归一化的所有输出单词概率，$g_i$表示未经归一化的字典中第$i$个单词的输出概率。 -- 根据softmax的定义，通过归一化`$g_i$`, 生成目标词`$w_t$`的概率为： +- 根据softmax的定义，通过归一化$g_i$, 生成目标词$w_t$的概率为： $$P(w_t | w_1, ..., w_{t-n+1}) = \frac{e^{g_{w_t}}}{\sum_i^{|V|} e^{g_i}}$$ @@ -109,7 +109,7 @@ $$P(w_t | w_1, ..., w_{t-n+1}) = \frac{e^{g_{w_t}}}{\sum_i^{|V|} e^{g_i}}$$ $$J(\theta) = -\sum_{i=1}^N\sum_{c=1}^{|V|}y_k^{i}log(softmax(g_k^i))$$ -其中`$y_k^i$`表示第`$i$`个样本第`$k$`类的真实标签(0或1)，`$softmax(g_k^i)$`表示第i个样本第k类softmax输出的概率。 +其中$y_k^i$表示第$i$个样本第$k$类的真实标签(0或1)，$softmax(g_k^i)$表示第i个样本第k类softmax输出的概率。 @@ -126,7 +126,7 @@ CBOW模型通过一个词的上下文（各N个词）预测当前词。当N=2时 $$context = \frac{x_{t-1} + x_{t-2} + x_{t+1} + x_{t+2}}{4}$$ -其中`$x_t$`为第`$t$`个词的词向量，分类分数（score）向量 `$z=U*context$`，最终的分类`$y$`采用softmax，损失函数采用多类分类交叉熵。 +其中$x_t$为第$t$个词的词向量，分类分数（score）向量 $z=U*context$，最终的分类$y$采用softmax，损失函数采用多类分类交叉熵。 ### Skip-gram model @@ -137,7 +137,7 @@ CBOW的好处是对上下文词语的分布在词向量上进行了平滑，去 图4. Skip-gram模型

-如上图所示，Skip-gram模型的具体做法是，将一个词的词向量映射到`$2n$`个词的词向量（`$2n$`表示当前输入词的前后各`$n$`个词），然后分别通过softmax得到这`$2n$`个词的分类损失值之和。 +如上图所示，Skip-gram模型的具体做法是，将一个词的词向量映射到$2n$个词的词向量（$2n$表示当前输入词的前后各$n$个词），然后分别通过softmax得到这$2n$个词的分类损失值之和。 ## 数据准备 diff --git a/source/beginners_guide/install/install_doc.rst b/source/beginners_guide/install/install_doc.rst index d862eded2..18788d2ea 100644 --- a/source/beginners_guide/install/install_doc.rst +++ b/source/beginners_guide/install/install_doc.rst @@ -3,7 +3,10 @@ 安装说明 ^^^^^^^^ -您可以使用我们提供的安装包，或使用源代码，安装PaddlePaddle。 +若您的系统为Linux或Windows，您可以使用我们提供的安装包来安装PaddlePaddle。 + +对于MacOS系统，我们暂未提供安装包，您可以使用 **从源码编译** 的方式安装。 + .. _install_linux: @@ -23,11 +26,11 @@ pip install paddlepaddle -当前的默认版本为0.13.0，cpu_avx_openblas，您可以通过指定版本号来安装其它版本，例如： +您可以通过指定版本号来安装其它版本，例如： .. code-block:: bash - pip install paddlepaddle==0.12.0 + pip install paddlepaddle==0.13.0 如果需要安装支持GPU的版本（cuda9.0_cudnn7_avx_openblas），需要执行： @@ -36,11 +39,14 @@ pip install paddlepaddle-gpu -当前的默认版本是0.13.0，PaddlePaddle针对不同需求提供了更多版本的安装包，部分列表如下： +PaddlePaddle针对不同需求提供了更多版本的安装包，部分列表如下： ================================= ======================================== 版本号 版本说明 ================================= ======================================== +paddlepaddle-gpu==0.14.0 使用CUDA 9.0和cuDNN 7编译的0.14.0版本 +paddlepaddle-gpu==0.14.0.post87 使用CUDA 8.0和cuDNN 7编译的0.14.0版本 +paddlepaddle-gpu==0.14.0.post85 使用CUDA 8.0和cuDNN 5编译的0.14.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版本 @@ -64,12 +70,15 @@ paddlepaddle-gpu==0.11.0 使用CUDA 7.5和cuDNN 5编译的0.11.0版 :header: "版本说明", "cp27-cp27mu", "cp27-cp27m" :widths: 1, 3, 3 - "cpu_avx_mkl", "`paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl `__" - "cpu_avx_openblas", "`paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl `__" - "cpu_noavx_openblas", "`paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl `_" - "cuda8.0_cudnn5_avx_mkl", "`paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl `__" - "cuda8.0_cudnn7_avx_mkl", "`paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl `__" - "cuda9.0_cudnn7_avx_mkl", "`paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl `__" + "stable_cuda9.0_cudnn7", "`paddlepaddle_gpu-0.14.0-cp27-cp27mu-manylinux1_x86_64.whl `__", "`paddlepaddle_gpu-0.14.0-cp27-cp27m-manylinux1_x86_64.whl `__" + "stable_cuda8.0_cudnn7", "`paddlepaddle_gpu-0.14.0.post87-cp27-cp27mu-manylinux1_x86_64.whl `__", "`paddlepaddle_gpu-0.14.0.post87-cp27-cp27m-manylinux1_x86_64.whl `__" + "stable_cuda8.0_cudnn5", "`paddlepaddle_gpu-0.14.0.post85-cp27-cp27mu-manylinux1_x86_64.whl `__", "`paddlepaddle_gpu-0.14.0.post85-cp27-cp27m-manylinux1_x86_64.whl `__" + "cpu_avx_mkl", "`paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl `__" + "cpu_avx_openblas", "`paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl `__" + "cpu_noavx_openblas", "`paddlepaddle-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle-latest-cp27-cp27m-linux_x86_64.whl `_" + "cuda8.0_cudnn5_avx_mkl", "`paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl `__" + "cuda8.0_cudnn7_avx_mkl", "`paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl `__" + "cuda9.0_cudnn7_avx_mkl", "`paddlepaddle_gpu-latest-cp27-cp27mu-linux_x86_64.whl `__", "`paddlepaddle_gpu-latest-cp27-cp27m-linux_x86_64.whl `__" .. _FAQ: @@ -104,102 +113,127 @@ paddlepaddle-gpu==0.11.0 使用CUDA 7.5和cuDNN 5编译的0.11.0版 .. _install_windows: -在windows安装PaddlePaddle +在Windows安装PaddlePaddle ------------------------------ +Windows系统需要通过Docker来使用PaddleaPaddle。Docker是一个虚拟容器，使用Docker可以简化复杂的环境配置工作。 -若您的系统为windows，您可以通过Docker来使用PaddlePaddle。 +我们提供了 `PaddlePaddle_Windows快速安装包 `_， +它能够帮助您安装Docker和PaddlePaddle。 -推荐您下载 `PaddlePaddle快速安装包 `_， -该安装包能够帮助您判断、安装适合的Docker，并引导您在Docker中使用PaddlePaddle。 +* 安装包支持的系统：Windows7，Windows8的所有版本，Windows10的专业版、企业版。 -.. - todo: windows的安装包要放在百度云上 - -注意事项： +* 如果您希望使用GPU提升训练速度，请使用Linux系统安装，Windows系统暂不支持。 + +.. _install_mac: -* 系统要求：windows7&8&10。 +在MacOS安装PaddlePaddle +-------- -* 下载安装包后，请您右键选择“以管理员身份运行”。 +对于MacOS系统，我们暂未提供pip安装方式，您可以使用 **源码编译** 的方式安装。 -* PaddlePaddle不支持在windows使用GPU。 +.. _others: -Docker安装完成后，请您执行下面的步骤： +其他安装方式 +------------- -请您右键选择”以管理员身份运行“，来启动Docker客户端 +.. _source: +源码编译（使用Docker镜像） +========== -获取Image ID +.. _requirements: -.. code-block:: bash +需要的软硬件 +""""""""""""" - docker images +为了编译PaddlePaddle，我们需要 -启动Docker +1. 一台电脑，可以装的是 Linux, Windows 或者 MacOS 操作系统 +2. Docker -.. code-block:: bash +不需要依赖其他任何软件了。即便是 Python 和 GCC 都不需要，因为我们会把所有编译工具都安装进一个 Docker 镜像里。 - docker run -d it -t imageid /bin/bash +.. _build_step: -获取Docker Container +编译方法 +""""""""""""" -.. code-block:: bash +PaddlePaddle需要使用Docker环境完成编译，这样可以免去单独安装编译依赖的步骤，可选的不同编译环境Docker镜像可以在 `这里 `_ 找到。 - docker ps -a -进入Container +**I. 编译CPU-Only版本的PaddlePaddle，需要执行：** .. code-block:: bash - docker attach container + # 1. 获取源码 + git clone https://github.com/PaddlePaddle/Paddle.git + cd Paddle + # 2. 执行如下命令下载最新版本的docker镜像 + docker run --name paddle-test -v $PWD:/paddle --network=host -it docker.paddlepaddlehub.com/paddle:latest-dev /bin/bash + # 3. 进入docker内执行如下命令编译CPU-Only的二进制安装包 + mkdir -p /paddle/build && cd /paddle/build + cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF + make -j$(nproc) -.. _others: +**II. 编译GPU版本的PaddlePaddle，需要执行：** -其他安装方式 -------------- +.. code-block:: bash -.. _source: -从源码编译 -========== + # 1. 获取源码 + git clone https://github.com/PaddlePaddle/Paddle.git + cd Paddle + # 2. 安装nvidia-docker + apt-get install nvidia-docker + # 3. 执行如下命令下载支持GPU运行的docker容器 + nvidia-docker run --name paddle-test-gpu -v $PWD:/paddle --network=host -it docker.paddlepaddlehub.com/paddle:latest-dev /bin/bash + # 4. 进入docker内执行如下命令编译GPU版本的PaddlePaddle + mkdir -p /paddle/build && cd /paddle/build + cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=ON -DWITH_TESTING=OFF + make -j$(nproc) -.. _requirements: +**注意事项：** -需要的软硬件 -""""""""""""" +* 上述有关 :code:`docker` 的命令把当前目录（源码树根目录）映射为 container 里的 :code:`/paddle` 目录。 +* 进入 :code:`docker` 后执行 :code:`cmake` 命令，若是出现 :code:`patchelf not found, please install it.` 错误，则执行 :code:`apt-get install -y patchelf` 命令即可解决问题。 +* 若您在使用Docker编译PaddlePaddle遇到问题时， `这个issue `_ 可能会对您有所帮助。 -为了编译PaddlePaddle，我们需要 -1. 一台电脑，可以装的是 Linux, Windows 或者 MacOS 操作系统 -2. Docker +.. _source: +源码编译（不使用Docker镜像） +========== -不需要依赖其他任何软件了。即便是 Python 和 GCC 都不需要，因为我们会把所有编译工具都安装进一个 Docker 镜像里。 +如果您选择不使用Docker镜像，则需要在本机安装下面章节列出的 `附录：编译依赖`_ 之后才能开始编译的步骤。 .. _build_step: 编译方法 """"""""""""" -PaddlePaddle需要使用Docker环境完成编译，这样可以免去单独安装编译依赖的步骤，可选的不同编译环境Docker镜像 -可以在 `这里 `_ 找到。或者 -参考下述可选步骤，从源码中构建用于编译PaddlePaddle的Docker镜像。 - -如果您选择不使用Docker镜像，则需要在本机安装下面章节列出的 `附录：编译依赖`_ 之后才能开始编译的步骤。 - -编译PaddlePaddle，需要执行： +在本机上编译CPU-Only版本的PaddlePaddle，需要执行如下命令： .. code-block:: bash - # 1. 获取源码 + # 1. 使用virtualenvwrapper创建python虚环境并将工作空间切换到虚环境 [可选] + mkvirtualenv paddle-venv + workon paddle-venv + # 2. 获取源码 git clone https://github.com/PaddlePaddle/Paddle.git cd Paddle - # 2. 可选步骤：源码中构建用于编译PaddlePaddle的Docker镜像 - docker build -t paddle:dev . # 3. 执行下面的命令编译CPU-Only的二进制 - docker run -it -v $PWD:/paddle -e "WITH_GPU=OFF" -e "WITH_TESTING=OFF" paddlepaddle/paddle_manylinux_devel:cuda8.0_cudnn5 bash -x /paddle/paddle/scripts/paddle_build.sh build - # 4. 或者也可以使用为上述可选步骤构建的镜像（必须先执行第2步） - docker run -it -v $PWD:/paddle -e "WITH_GPU=OFF" -e "WITH_TESTING=OFF" paddle:dev + mkdir build && cd build + cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF + make -j4 # 根据机器配备CPU的核心数开启相应的多线程进行编译 + -注：上述命令把当前目录（源码树根目录）映射为 container 里的 :code:`/paddle` 目录。如果使用自行 -构建的镜像（上述第4步）会执行 :code:`Dockerfile` 描述的默认入口程序 :code:`docker_build.sh` 可以省略步骤3中 -最后的执行脚本的命令。 +**注意事项：** + +* MacOS系统下因为默认安装了cblas库，所以编译时可能会遇到 :code:`use of undeclared identifier 'openblas_set_num_threads'` 错误。因此，在执行cmake命令时需要指定所使用openblas库的头文件路径，具体操作如下： + + .. code-block:: bash + + cd Paddle/build && rm -rf * + cmake .. -DWITH_FLUID_ONLY=ON -DWITH_GPU=OFF -DWITH_TESTING=OFF -DOPENBLAS_INC_DIR=/usr/local/Cellar/openblas/[本机所安装的openblas版本号]/include/ + make -j4 # 根据机器配备CPU的核心数开启相应的多线程进行编译 +* 若您在MacOS系统下从源码编译PaddlePaddle遇到问题时， `这个issue `_ 可能会对您有所帮助。 编译完成后会在build/python/dist目录下生成输出的whl包，可以选在在当前机器安装也可以拷贝到目标机器安装： @@ -230,13 +264,13 @@ PaddlePaddle需要使用Docker环境完成编译，这样可以免去单独安 .. code-block:: bash - docker run -it -v $PWD:/paddle -e "WITH_GPU=OFF" -e "WITH_TESTING=ON" -e "RUN_TEST=ON" paddlepaddle/paddle_manylinux_devel:cuda8.0_cudnn5 bash -x /paddle/paddle/scripts/paddle_build.sh build + docker run -it -v $PWD:/paddle -e "WITH_GPU=OFF" -e "WITH_TESTING=ON" -e "RUN_TEST=ON" docker.paddlepaddlehub.com/paddle:latest-dev bash -x /paddle/paddle/scripts/paddle_build.sh build 如果期望执行其中一个单元测试，（比如 :code:`test_sum_op` ）： .. code-block:: bash - docker run -it -v $PWD:/paddle -e "WITH_GPU=OFF" -e "WITH_TESTING=ON" -e "RUN_TEST=OFF" paddlepaddle/paddle_manylinux_devel:cuda8.0_cudnn5 bash -x /paddle/paddle/scripts/paddle_build.sh build + docker run -it -v $PWD:/paddle -e "WITH_GPU=OFF" -e "WITH_TESTING=ON" -e "RUN_TEST=OFF" docker.paddlepaddlehub.com/paddle:latest-dev bash -x /paddle/paddle/scripts/paddle_build.sh build cd /paddle/build ctest -R test_sum_op -V @@ -310,12 +344,16 @@ PaddlePaddle编译需要使用到下面的依赖（包含但不限于），其 :header: "依赖", "版本", "说明" :widths: 10, 15, 30 - "CMake", ">=3.2", "" + "CMake", "3.4", "" "GCC", "4.8.2", "推荐使用CentOS的devtools2" "Python", "2.7.x", "依赖libpython2.7.so" + "SWIG", ">=2.0", "" + "wget","","" + "openblas","","" "pip", ">=9.0", "" "numpy", "", "" - "SWIG", ">=2.0", "" + "protobuf","3.1.0","" + "wheel","","" "Go", ">=1.8", "可选" @@ -378,7 +416,7 @@ PaddePaddle通过编译时指定路径来实现引用各种BLAS/CUDA/cuDNN库。 cmake .. -DWITH_GPU=ON -DWITH_TESTING=OFF -DCUDNN_ROOT=/opt/cudnnv5 -**注意：这几个编译选项的设置，只在第一次cmake的时候有效。如果之后想要重新设置，推荐清理整个编译目录（** :code:`rm -rf` ）**后，再指定。** +注意：这几个编译选项的设置，只在第一次cmake的时候有效。如果之后想要重新设置，推荐清理整个编译目录（ :code:`rm -rf` ）后，再指定。 .. _install_docker: diff --git a/source/beginners_guide/quick_start/fit_a_line/README.cn.md b/source/beginners_guide/quick_start/fit_a_line/README.cn.md index 89b3cea52..8886a8307 100644 --- a/source/beginners_guide/quick_start/fit_a_line/README.cn.md +++ b/source/beginners_guide/quick_start/fit_a_line/README.cn.md @@ -4,14 +4,14 @@ # 线性回归 让我们从经典的线性回归（Linear Regression \[[1](#参考文献)\]）模型开始这份教程。在这一章里，你将使用真实的数据集建立起一个房价预测模型，并且了解到机器学习中的若干重要概念。 -本教程源代码目录在[book/fit_a_line](https://github.com/PaddlePaddle/book/tree/develop/01.fit_a_line)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/137.html)。 +本教程源代码目录在[book/fit_a_line](https://github.com/PaddlePaddle/book/tree/develop/01.fit_a_line)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 -给定一个大小为`$n$`的数据集 `${\{y_{i}, x_{i1}, ..., x_{id}\}}_{i=1}^{n}$`，其中`$x_{i1}, \ldots, x_{id}$`是第`$i$`个样本`$d$`个属性上的取值，`$y_i$`是该样本待预测的目标。线性回归模型假设目标`$y_i$`可以被属性间的线性组合描述，即 +给定一个大小为$n$的数据集 ${\{y_{i}, x_{i1}, ..., x_{id}\}}_{i=1}^{n}$，其中$x_{i1}, \ldots, x_{id}$是第$i$个样本$d$个属性上的取值，$y_i$是该样本待预测的目标。线性回归模型假设目标$y_i$可以被属性间的线性组合描述，即 $$y_i = \omega_1x_{i1} + \omega_2x_{i2} + \ldots + \omega_dx_{id} + b, i=1,\ldots,n$$ -例如，在我们将要建模的房价预测问题里，`$x_{ij}$`是描述房子`$i$`的各种属性（比如房间的个数、周围学校和医院的个数、交通状况等），而 `$y_i$`是房屋的价格。 +例如，在我们将要建模的房价预测问题里，$x_{ij}$是描述房子$i$的各种属性（比如房间的个数、周围学校和医院的个数、交通状况等），而 $y_i$是房屋的价格。 初看起来，这个假设实在过于简单了，变量间的真实关系很难是线性的。但由于线性回归模型有形式简单和易于建模分析的优点，它在实际问题中得到了大量的应用。很多经典的统计学习、机器学习书籍\[[2,3,4](#参考文献)\]也选择对线性模型独立成章重点讲解。 @@ -25,24 +25,24 @@ $$y_i = \omega_1x_{i1} + \omega_2x_{i2} + \ldots + \omega_dx_{id} + b, i=1,\ldo ### 模型定义 -在波士顿房价数据集中，和房屋相关的值共有14个：前13个用来描述房屋相关的各种信息，即模型中的 `$x_i$`；最后一个值为我们要预测的该类房屋价格的中位数，即模型中的 `$y_i$`。因此，我们的模型就可以表示成： +在波士顿房价数据集中，和房屋相关的值共有14个：前13个用来描述房屋相关的各种信息，即模型中的 $x_i$；最后一个值为我们要预测的该类房屋价格的中位数，即模型中的 $y_i$。因此，我们的模型就可以表示成： $$\hat{Y} = \omega_1X_{1} + \omega_2X_{2} + \ldots + \omega_{13}X_{13} + b$$ -`$\hat{Y}$` 表示模型的预测结果，用来和真实值`$Y$`区分。模型要学习的参数即：`$\omega_1, \ldots, \omega_{13}, b$`。 +$\hat{Y}$ 表示模型的预测结果，用来和真实值$Y$区分。模型要学习的参数即：$\omega_1, \ldots, \omega_{13}, b$。 -建立模型后，我们需要给模型一个优化目标，使得学到的参数能够让预测值`$\hat{Y}$`尽可能地接近真实值`$Y$`。这里我们引入损失函数（[Loss Function](https://en.wikipedia.org/wiki/Loss_function)，或Cost Function）这个概念。 输入任意一个数据样本的目标值`$y_{i}$`和模型给出的预测值`$\hat{y_{i}}$`，损失函数输出一个非负的实值。这个实值通常用来反映模型误差的大小。 +建立模型后，我们需要给模型一个优化目标，使得学到的参数能够让预测值$\hat{Y}$尽可能地接近真实值$Y$。这里我们引入损失函数（[Loss Function](https://en.wikipedia.org/wiki/Loss_function)，或Cost Function）这个概念。 输入任意一个数据样本的目标值$y_{i}$和模型给出的预测值$\hat{y_{i}}$，损失函数输出一个非负的实值。这个实值通常用来反映模型误差的大小。 对于线性回归模型来讲，最常见的损失函数就是均方误差（Mean Squared Error， [MSE](https://en.wikipedia.org/wiki/Mean_squared_error)）了，它的形式是： $$MSE=\frac{1}{n}\sum_{i=1}^{n}{(\hat{Y_i}-Y_i)}^2$$ -即对于一个大小为`$n$`的测试集，`$MSE$`是`$n$`个数据预测结果误差平方的均值。 +即对于一个大小为$n$的测试集，$MSE$是$n$个数据预测结果误差平方的均值。 ### 训练过程 定义好模型结构之后，我们要通过以下几个步骤进行模型训练 -1. 初始化参数，其中包括权重`$\omega_i$`和偏置`$b$`，对其进行初始化（如0均值，1方差）。 +1. 初始化参数，其中包括权重$\omega_i$和偏置$b$，对其进行初始化（如0均值，1方差）。 2. 网络正向传播计算网络输出和损失函数。 3. 根据损失函数进行反向误差传播 （[backpropagation](https://en.wikipedia.org/wiki/Backpropagation)），将网络误差从输出层依次向前传递, 并更新网络中的参数。 4. 重复2~3步骤，直至网络训练误差达到规定的程度或训练轮次达到设定值。 @@ -52,26 +52,93 @@ $$MSE=\frac{1}{n}\sum_{i=1}^{n}{(\hat{Y_i}-Y_i)}^2$$ ### 数据集介绍 这份数据集共506行，每行包含了波士顿郊区的一类房屋的相关信息及该类房屋价格的中位数。其各维属性的意义如下： -| 属性名 | 解释 | 类型 | -| ------| ------ | ------ | -| CRIM | 该镇的人均犯罪率 | 连续值 | -| ZN | 占地面积超过25,000平方呎的住宅用地比例 | 连续值 | -| INDUS | 非零售商业用地比例 | 连续值 | -| CHAS | 是否邻近 Charles River | 离散值，1=邻近；0=不邻近 | -| NOX | 一氧化氮浓度 | 连续值 | -| RM | 每栋房屋的平均客房数 | 连续值 | -| AGE | 1940年之前建成的自用单位比例 | 连续值 | -| DIS | 到波士顿5个就业中心的加权距离 | 连续值 | -| RAD | 到径向公路的可达性指数 | 连续值 | -| TAX | 全值财产税率 | 连续值 | -| PTRATIO | 学生与教师的比例 | 连续值 | -| B | 1000(BK - 0.63)^2，其中BK为黑人占比 | 连续值 | -| LSTAT | 低收入人群占比 | 连续值 | -| MEDV | 同类房屋价格的中位数 | 连续值 | +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
属性名解释类型
CRIM该镇的人均犯罪率连续值
ZN占地面积超过25,000平方呎的住宅用地比例连续值
INDUS非零售商业用地比例连续值
CHAS是否邻近 Charles River离散值，1=邻近；0=不邻近
NOX一氧化氮浓度连续值
RM每栋房屋的平均客房数连续值
AGE1940年之前建成的自用单位比例连续值
DIS到波士顿5个就业中心的加权距离连续值
RAD到径向公路的可达性指数连续值
TAX全值财产税率连续值
PTRATIO学生与教师的比例连续值
B1000(BK - 0.63)^2，其中BK为黑人占比连续值
LSTAT低收入人群占比连续值
MEDV同类房屋价格的中位数连续值
+

### 数据预处理 #### 连续值与离散值 -观察一下数据，我们的第一个发现是：所有的13维属性中，有12维的连续值和1维的离散值（CHAS）。离散值虽然也常使用类似0、1、2这样的数字表示，但是其含义与连续值是不同的，因为这里的差值没有实际意义。例如，我们用0、1、2来分别表示红色、绿色和蓝色的话，我们并不能因此说“蓝色和红色”比“绿色和红色”的距离更远。所以通常对一个有`$d$`个可能取值的离散属性，我们会将它们转为`$d$`个取值为0或1的二值属性或者将每个可能取值映射为一个多维向量。不过就这里而言，因为CHAS本身就是一个二值属性，就省去了这个麻烦。 +观察一下数据，我们的第一个发现是：所有的13维属性中，有12维的连续值和1维的离散值（CHAS）。离散值虽然也常使用类似0、1、2这样的数字表示，但是其含义与连续值是不同的，因为这里的差值没有实际意义。例如，我们用0、1、2来分别表示红色、绿色和蓝色的话，我们并不能因此说“蓝色和红色”比“绿色和红色”的距离更远。所以通常对一个有$d$个可能取值的离散属性，我们会将它们转为$d$个取值为0或1的二值属性或者将每个可能取值映射为一个多维向量。不过就这里而言，因为CHAS本身就是一个二值属性，就省去了这个麻烦。 #### 属性的归一化 另外一个稍加观察即可发现的事实是，各维属性的取值范围差别很大（如图2所示）。例如，属性B的取值范围是[0.32, 396.90]，而属性NOX的取值范围是[0.3850, 0.8170]。这里就要用到一个常见的操作-归一化（normalization）了。归一化的目标是把各位属性的取值范围放缩到差不多的区间，例如[-0.5,0.5]。这里我们使用一种很常见的操作方法：减掉均值，然后除以原取值范围。 @@ -85,7 +152,7 @@ $$MSE=\frac{1}{n}\sum_{i=1}^{n}{(\hat{Y_i}-Y_i)}^2$$

图2. 各维属性的取值范围

#### 整理训练集与测试集 -我们将数据集分割为两份：一份用于调整模型的参数，即进行模型的训练，模型在这份数据集上的误差被称为**训练误差**；另外一份被用来测试，模型在这份数据集上的误差被称为**测试误差**。我们训练模型的目的是为了通过从训练数据中找到规律来预测未知的新数据，所以测试误差是更能反映模型表现的指标。分割数据的比例要考虑到两个因素：更多的训练数据会降低参数估计的方差，从而得到更可信的模型；而更多的测试数据会降低测试误差的方差，从而得到更可信的测试误差。我们这个例子中设置的分割比例为`$8:2$` +我们将数据集分割为两份：一份用于调整模型的参数，即进行模型的训练，模型在这份数据集上的误差被称为**训练误差**；另外一份被用来测试，模型在这份数据集上的误差被称为**测试误差**。我们训练模型的目的是为了通过从训练数据中找到规律来预测未知的新数据，所以测试误差是更能反映模型表现的指标。分割数据的比例要考虑到两个因素：更多的训练数据会降低参数估计的方差，从而得到更可信的模型；而更多的测试数据会降低测试误差的方差，从而得到更可信的测试误差。我们这个例子中设置的分割比例为$8:2$ 在更复杂的模型训练过程中，我们往往还会多使用一种数据集：验证集。因为复杂的模型中常常还有一些超参数（[Hyperparameter](https://en.wikipedia.org/wiki/Hyperparameter_optimization)）需要调节，所以我们会尝试多种超参数的组合来分别训练多个模型，然后对比它们在验证集上的表现选择相对最好的一组超参数，最后才使用这组参数下训练的模型在测试集上评估测试误差。由于本章训练的模型比较简单，我们暂且忽略掉这个过程。 @@ -260,4 +327,3 @@ print("infer results: ", results[0])
知识共享许可协议
本教程 由 PaddlePaddle 创作，采用 知识共享 署名-相同方式共享 4.0 国际 许可协议进行许可。 - diff --git a/source/beginners_guide/quick_start/recognize_digits/README.cn.md b/source/beginners_guide/quick_start/recognize_digits/README.cn.md index 71d64339d..2996d3702 100644 --- a/source/beginners_guide/quick_start/recognize_digits/README.cn.md +++ b/source/beginners_guide/quick_start/recognize_digits/README.cn.md @@ -1,6 +1,6 @@ # 识别数字 -本教程源代码目录在[book/recognize_digits](https://github.com/PaddlePaddle/book/tree/develop/02.recognize_digits)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)，更多内容请参考本教程的[视频课堂](http://bit.baidu.com/course/detail/id/167.html)。 +本教程源代码目录在[book/recognize_digits](https://github.com/PaddlePaddle/book/tree/develop/02.recognize_digits)， 初次使用请参考PaddlePaddle[安装教程](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。 ## 背景介绍 当我们学习编程的时候，编写的第一个程序一般是实现打印"Hello World"。而机器学习（或深度学习）的入门教程，一般都是 [MNIST](http://yann.lecun.com/exdb/mnist/) 数据库上的手写识别问题。原因是手写识别属于典型的图像分类问题，比较简单，同时MNIST数据集也很完备。MNIST数据集作为一个简单的计算机视觉数据集，包含一系列如图1所示的手写数字图片和对应的标签。图片是28x28的像素矩阵，标签则对应着0~9的10个数字。每张图片都经过了大小归一化和居中处理。 @@ -20,21 +20,21 @@ Yann LeCun早先在手写字符识别上做了很多研究，并在研究过程 ## 模型概览 基于MNIST数据训练一个分类器，在介绍本教程使用的三个基本图像分类网络前，我们先给出一些定义： -- `$X$`是输入：MNIST图片是`$28\times28$` 的二维图像，为了进行计算，我们将其转化为`$784$`维向量，即`$X=\left ( x_0, x_1, \dots, x_{783} \right )$`。 -- `$Y$`是输出：分类器的输出是10类数字（0-9），即`$Y=\left ( y_0, y_1, \dots, y_9 \right )$`，每一维`$y_i$`代表图片分类为第`$i$`类数字的概率。 -- `$L$`是图片的真实标签：`$L=\left ( l_0, l_1, \dots, l_9 \right )$`也是10维，但只有一维为1，其他都为0。 +- $X$是输入：MNIST图片是$28\times28$ 的二维图像，为了进行计算，我们将其转化为$784$维向量，即$X=\left ( x_0, x_1, \dots, x_{783} \right )$。 +- $Y$是输出：分类器的输出是10类数字（0-9），即$Y=\left ( y_0, y_1, \dots, y_9 \right )$，每一维$y_i$代表图片分类为第$i$类数字的概率。 +- $L$是图片的真实标签：$L=\left ( l_0, l_1, \dots, l_9 \right )$也是10维，但只有一维为1，其他都为0。 ### Softmax回归(Softmax Regression) 最简单的Softmax回归模型是先将输入层经过一个全连接层得到的特征，然后直接通过softmax 函数进行多分类\[[9](#参考文献)\]。 -输入层的数据`$X$`传到输出层，在激活操作之前，会乘以相应的权重 `$W$` ，并加上偏置变量 `$b$` ，具体如下： +输入层的数据$X$传到输出层，在激活操作之前，会乘以相应的权重 $W$ ，并加上偏置变量 $b$ ，具体如下： $$ y_i = \text{softmax}(\sum_j W_{i,j}x_j + b_i) $$ -其中 `$ \text{softmax}(x_i) = \frac{e^{x_i}}{\sum_j e^{x_j}} $` +其中 $ \text{softmax}(x_i) = \frac{e^{x_i}}{\sum_j e^{x_j}} $ -对于有 `$N$` 个类别的多分类问题，指定 `$N$` 个输出节点，`$N$` 维结果向量经过softmax将归一化为 `$N$` 个[0,1]范围内的实数值，分别表示该样本属于这 `$N$` 个类别的概率。此处的 `$y_i$` 即对应该图片为数字 `$i$` 的预测概率。 +对于有 $N$ 个类别的多分类问题，指定 $N$ 个输出节点，$N$ 维结果向量经过softmax将归一化为 $N$ 个[0,1]范围内的实数值，分别表示该样本属于这 $N$ 个类别的概率。此处的 $y_i$ 即对应该图片为数字 $i$ 的预测概率。 在分类问题中，我们一般采用交叉熵代价损失函数（cross entropy），公式如下： @@ -49,9 +49,9 @@ $$ \text{crossentropy}(label, y) = -\sum_i label_ilog(y_i) $$ Softmax回归模型采用了最简单的两层神经网络，即只有输入层和输出层，因此其拟合能力有限。为了达到更好的识别效果，我们考虑在输入层和输出层中间加上若干个隐藏层\[[10](#参考文献)\]。 -1. 经过第一个隐藏层，可以得到 `$ H_1 = \phi(W_1X + b_1) $`，其中`$\phi$`代表激活函数，常见的有sigmoid、tanh或ReLU等函数。 -2. 经过第二个隐藏层，可以得到 `$ H_2 = \phi(W_2H_1 + b_2) $`。 -3. 最后，再经过输出层，得到的`$Y=\text{softmax}(W_3H_2 + b_3)$`，即为最后的分类结果向量。 +1. 经过第一个隐藏层，可以得到 $ H_1 = \phi(W_1X + b_1) $，其中$\phi$代表激活函数，常见的有sigmoid、tanh或ReLU等函数。 +2. 经过第二个隐藏层，可以得到 $ H_2 = \phi(W_2H_1 + b_2) $。 +3. 最后，再经过输出层，得到的$Y=\text{softmax}(W_3H_2 + b_3)$，即为最后的分类结果向量。 图3为多层感知器的网络结构图，图中权重用蓝线表示、偏置用红线表示、+1代表偏置参数的系数为1。 @@ -70,16 +70,16 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层 卷积层是卷积神经网络的核心基石。在图像识别里我们提到的卷积是二维卷积，即离散二维滤波器（也称作卷积核）与二维图像做卷积操作，简单的讲是二维滤波器滑动到二维图像上所有位置，并在每个位置上与该像素点及其领域像素点做内积。卷积操作被广泛应用与图像处理领域，不同卷积核可以提取不同的特征，例如边沿、线性、角等特征。在深层卷积神经网络中，通过卷积操作可以提取出图像低级到复杂的特征。 -![cnn](./image/conv_layer.png) +![cnn](https://raw.githubusercontent.com/PaddlePaddle/book/develop/02.recognize_digits/image/conv_layer.png)

图5. 卷积层图片

-图5给出一个卷积计算过程的示例图，输入图像大小为`$H=5,W=5,D=3$`，即`$5 \times 5$`大小的3通道（RGB，也称作深度）彩色图像。这个示例图中包含两（用`$K$`表示）组卷积核，即图中滤波器`$W_0$`和`$W_1$`。在卷积计算中，通常对不同的输入通道采用不同的卷积核，如图示例中每组卷积核包含（`$D=3$`）个`$3 \times 3$`（用`$F \times F$`表示）大小的卷积核。另外，这个示例中卷积核在图像的水平方向（`$W$`方向）和垂直方向（`$H$`方向）的滑动步长为2（用`$S$`表示）；对输入图像周围各填充1（用`$P$`表示）个0，即图中输入层原始数据为蓝色部分，灰色部分是进行了大小为1的扩展，用0来进行扩展。经过卷积操作得到输出为`$3 \times 3 \times 2$`（用`$H_{o} \times W_{o} \times K$`表示）大小的特征图，即`$3 \times 3$`大小的2通道特征图，其中`$H_o$`计算公式为：`$H_o = (H - F + 2 \times P)/S + 1$`，`$W_o$`同理。 而输出特征图中的每个像素，是每组滤波器与输入图像每个特征图的内积再求和，再加上偏置`$b_o$`，偏置通常对于每个输出特征图是共享的。输出特征图`$o[:,:,0]$`中的最后一个`$-2$`计算如图5右下角公式所示。 +图5给出一个卷积计算过程的示例图，输入图像大小为$H=5,W=5,D=3$，即$5 \times 5$大小的3通道（RGB，也称作深度）彩色图像。这个示例图中包含两（用$K$表示）组卷积核，即图中滤波器$W_0$和$W_1$。在卷积计算中，通常对不同的输入通道采用不同的卷积核，如图示例中每组卷积核包含（$D=3$）个$3 \times 3$（用$F \times F$表示）大小的卷积核。另外，这个示例中卷积核在图像的水平方向（$W$方向）和垂直方向（$H$方向）的滑动步长为2（用$S$表示）；对输入图像周围各填充1（用$P$表示）个0，即图中输入层原始数据为蓝色部分，灰色部分是进行了大小为1的扩展，用0来进行扩展。经过卷积操作得到输出为$3 \times 3 \times 2$（用$H_{o} \times W_{o} \times K$表示）大小的特征图，即$3 \times 3$大小的2通道特征图，其中$H_o$计算公式为：$H_o = (H - F + 2 \times P)/S + 1$，$W_o$同理。 而输出特征图中的每个像素，是每组滤波器与输入图像每个特征图的内积再求和，再加上偏置$b_o$，偏置通常对于每个输出特征图是共享的。输出特征图$o[:,:,0]$中的最后一个$-2$计算如图5右下角公式所示。 -在卷积操作中卷积核是可学习的参数，经过上面示例介绍，每层卷积的参数大小为`$D \times F \times F \times K$`。在多层感知器模型中，神经元通常是全部连接，参数较多。而卷积层的参数较少，这也是由卷积层的主要特性即局部连接和共享权重所决定。 +在卷积操作中卷积核是可学习的参数，经过上面示例介绍，每层卷积的参数大小为$D \times F \times F \times K$。在多层感知器模型中，神经元通常是全部连接，参数较多。而卷积层的参数较少，这也是由卷积层的主要特性即局部连接和共享权重所决定。 - 局部连接：每个神经元仅与输入神经元的一块区域连接，这块局部区域称作感受野（receptive field）。在图像卷积操作中，即神经元在空间维度（spatial dimension，即上图示例H和W所在的平面）是局部连接，但在深度上是全部连接。对于二维图像本身而言，也是局部像素关联较强。这种局部连接保证了学习后的过滤器能够对于局部的输入特征有最强的响应。局部连接的思想，也是受启发于生物学里面的视觉系统结构，视觉皮层的神经元就是局部接受信息的。 -- 权重共享：计算同一个深度切片的神经元时采用的滤波器是共享的。例如图4中计算`$o[:,:,0]$`的每个每个神经元的滤波器均相同，都为`$W_0$`，这样可以很大程度上减少参数。共享权重在一定程度上讲是有意义的，例如图片的底层边缘特征与特征在图中的具体位置无关。但是在一些场景中是无意的，比如输入的图片是人脸，眼睛和头发位于不同的位置，希望在不同的位置学到不同的特征 (参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/))。请注意权重只是对于同一深度切片的神经元是共享的，在卷积层，通常采用多组卷积核提取不同特征，即对应不同深度切片的特征，不同深度切片的神经元权重是不共享。另外，偏重对同一深度切片的所有神经元都是共享的。 +- 权重共享：计算同一个深度切片的神经元时采用的滤波器是共享的。例如图4中计算$o[:,:,0]$的每个每个神经元的滤波器均相同，都为$W_0$，这样可以很大程度上减少参数。共享权重在一定程度上讲是有意义的，例如图片的底层边缘特征与特征在图中的具体位置无关。但是在一些场景中是无意的，比如输入的图片是人脸，眼睛和头发位于不同的位置，希望在不同的位置学到不同的特征 (参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/))。请注意权重只是对于同一深度切片的神经元是共享的，在卷积层，通常采用多组卷积核提取不同特征，即对应不同深度切片的特征，不同深度切片的神经元权重是不共享。另外，偏重对同一深度切片的所有神经元都是共享的。 通过介绍卷积计算过程及其特性，可以看出卷积是线性操作，并具有平移不变性（shift-invariant），平移不变性即在图像每个位置执行相同的操作。卷积层的局部连接和权重共享使得需要学习的参数大大减小，这样也有利于训练较大卷积神经网络。 @@ -93,13 +93,13 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层 更详细的关于卷积神经网络的具体知识可以参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/ )和[图像分类](https://github.com/PaddlePaddle/book/blob/develop/image_classification/README.md)教程。 ### 常见激活函数介绍 -- sigmoid激活函数： `$ f(x) = sigmoid(x) = \frac{1}{1+e^{-x}} $` +- sigmoid激活函数： $ f(x) = sigmoid(x) = \frac{1}{1+e^{-x}} $ -- tanh激活函数： `$ f(x) = tanh(x) = \frac{e^x-e^{-x}}{e^x+e^{-x}} $` +- tanh激活函数： $ f(x) = tanh(x) = \frac{e^x-e^{-x}}{e^x+e^{-x}} $ 实际上，tanh函数只是规模变化的sigmoid函数，将sigmoid函数值放大2倍之后再向下平移1个单位：tanh(x) = 2sigmoid(2x) - 1 。 -- ReLU激活函数： `$ f(x) = max(0, x) $` +- ReLU激活函数： $ f(x) = max(0, x) $ 更详细的介绍请参考[维基百科激活函数](https://en.wikipedia.org/wiki/Activation_function)。 @@ -107,12 +107,35 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层 PaddlePaddle在API中提供了自动加载[MNIST](http://yann.lecun.com/exdb/mnist/)数据的模块`paddle.dataset.mnist`。加载后的数据位于`/home/username/.cache/paddle/dataset/mnist`下： -| 文件名称 | 说明 | -|-------------------------|----------------------------| -| train-images-idx3-ubyte | 训练数据图片，60,000条数据 | -| train-labels-idx1-ubyte | 训练数据标签，60,000条数据 | -| t10k-images-idx3-ubyte | 测试数据图片，10,000条数据 | -| t10k-labels-idx1-ubyte | 测试数据标签，10,000条数据 | +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
文件名称说明
train-images-idx3-ubyte训练数据图片，60,000条数据
train-labels-idx1-ubyte训练数据标签，60,000条数据
t10k-images-idx3-ubyte测试数据图片，10,000条数据
t10k-labels-idx1-ubyte测试数据标签，10,000条数据
+

## Fluid API 概述 diff --git a/source/faq/faq.rst b/source/faq/faq.rst index 9d43c91a8..3b4bd4f89 100644 --- a/source/faq/faq.rst +++ b/source/faq/faq.rst @@ -1,3 +1,12 @@ -### -FAQ -### +################### +编译安装与单元测试 +################### + +1. 通过pip安装的PaddlePaddle在 :code:`import paddle.fluid` 报找不到 :code:`libmkldnn.so` 或 :code:`libmklml_intel.so` +------------------------------------------------------------------------------------------ +出现这种问题的原因是在导入 :code:`paddle.fluid` 时需要加载 :code:`libmkldnn.so` 和 :code:`libmklml_intel.so`， +但是系统没有找到该文件。一般通过pip安装PaddlePaddle时会将 :code:`libmkldnn.so` 和 :code:`libmklml_intel.so` +拷贝到 :code:`/usr/local/lib` 路径下，所以解决办法是将该路径加到 :code:`LD_LIBRARY_PATH` 环境变量下， +即： :code:`export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH` 。 + +**注意**：如果是在虚拟环境中安装PaddlePaddle， :code:`libmkldnn.so` 和 :code:`libmklml_intel.so` 可能不在 :code:`/usr/local/lib` 路径下。 diff --git a/source/faq/index_cn.rst b/source/faq/index_cn.rst new file mode 100644 index 000000000..bb2ed9921 --- /dev/null +++ b/source/faq/index_cn.rst @@ -0,0 +1,9 @@ +FAQ +==== + +本文档对关于PaddlePaddle的一些常见问题提供了解答。如果您的问题未在此处，请您到 `PaddlePaddle社区 `_ 查找答案或直接提 `issue `_ ，我们会及时进行回复。 + +.. toctree:: + :maxdepth: 1 + + faq.rst diff --git a/source/user_guides/howto/configure_simple_model/index.rst b/source/user_guides/howto/configure_simple_model/index.rst index 9bed6fb9f..5946a2ccb 100644 --- a/source/user_guides/howto/configure_simple_model/index.rst +++ b/source/user_guides/howto/configure_simple_model/index.rst @@ -33,9 +33,9 @@ 数据层 ------ -PaddlePaddle提供了 :ref:`api_fluid_layers_data` 算子来描述输入数据的格式。 +PaddlePaddle提供了 :code:`fluid.layers.data()` 算子来描述输入数据的格式。 -:ref:`api_fluid_layers_data` 算子的输出是一个Variable。这个Variable的实际类型是Tensor。Tensor具有强大的表征能力，可以表示多维数据。为了精确描述数据结构，通常需要指定数据shape以及数值类型type。其中shape为一个整数向量，type可以是一个字符串类型。目前支持的数据类型参考 :ref:`user_guide_paddle_support_data_types` 。 模型训练一般会使用batch的方式读取数据，而batch的size在训练过程中可能不固定。data算子会依据实际数据来推断batch size，所以这里提供shape时不用关心batch size，只需关心一条样本的shape即可，更高级用法请参考 :ref:`user_guide_customize_batch_size_rank`。从上知，:math:`x` 为 :math:`13` 维的实数向量，:math:`y` 为实数，可使用下面代码定义数据层： +:code:`fluid.layers.data()` 算子的输出是一个Variable。这个Variable的实际类型是Tensor。Tensor具有强大的表征能力，可以表示多维数据。为了精确描述数据结构，通常需要指定数据shape以及数值类型type。其中shape为一个整数向量，type可以是一个字符串类型。目前支持的数据类型参考 :ref:`user_guide_paddle_support_data_types` 。 模型训练一般会使用batch的方式读取数据，而batch的size在训练过程中可能不固定。data算子会依据实际数据来推断batch size，所以这里提供shape时不用关心batch size，只需关心一条样本的shape即可，更高级用法请参考 :ref:`user_guide_customize_batch_size_rank`。从上知，:math:`x` 为 :math:`13` 维的实数向量，:math:`y` 为实数，可使用下面代码定义数据层： .. code-block:: python @@ -55,7 +55,7 @@ PaddlePaddle提供了 :ref:`api_fluid_layers_data` 算子来描述输入数据 op_2_out = fluid.layers.op_2(input=op_1_out, ...) ... -其中op_1和op_2表示算子类型，可以是fc来执行线性变换(全连接)，也可以是conv来执行卷积变换等。通过算子的输入输出的连接来定义算子的计算顺序以及数据流方向。上面的例子中，op_1的输出是op_2的输入，那么在执行计算时，会先计算op_1，然后计算op_2。更复杂的模型可能需要使用控制流算子，依据输入数据来动态执行，针对这种情况，PaddlePaddle提供了IfElseOp和WhileOp等。算子的文档可参考 :ref:`api_fluid_layers`。具体到这个任务, 我们使用一个fc算子： +其中op_1和op_2表示算子类型，可以是fc来执行线性变换(全连接)，也可以是conv来执行卷积变换等。通过算子的输入输出的连接来定义算子的计算顺序以及数据流方向。上面的例子中，op_1的输出是op_2的输入，那么在执行计算时，会先计算op_1，然后计算op_2。更复杂的模型可能需要使用控制流算子，依据输入数据来动态执行，针对这种情况，PaddlePaddle提供了IfElseOp和WhileOp等。算子的文档可参考 :code:`fluid.layers`。具体到这个任务, 我们使用一个fc算子： .. code-block:: python @@ -80,7 +80,7 @@ PaddlePaddle提供了 :ref:`api_fluid_layers_data` 算子来描述输入数据 sgd_optimizer = fluid.optimizer.SGD(learning_rate=0.001) -更多优化算子可以参考 :ref:`api_fluid_optimizer` 。 +更多优化算子可以参考 :code:`fluid.optimizer()` 。 下一步做什么？ ############## diff --git a/source/user_guides/howto/inference/build_and_install_lib_cn.rst b/source/user_guides/howto/inference/build_and_install_lib_cn.rst new file mode 100644 index 000000000..3884284ea --- /dev/null +++ b/source/user_guides/howto/inference/build_and_install_lib_cn.rst @@ -0,0 +1,99 @@ +.. _install_or_build_cpp_inference_lib: + +安装与编译C++预测库 +=========================== + +直接下载安装 +------------- + +====================== ======================================== +版本说明 C++预测库 +====================== ======================================== +cpu_avx_mkl `fluid.tgz `_ +cpu_avx_openblas `fluid.tgz `_ +cpu_noavx_openblas `fluid.tgz `_ +cuda7.5_cudnn5_avx_mkl `fluid.tgz `_ +cuda8.0_cudnn5_avx_mkl `fluid.tgz `_ +cuda8.0_cudnn7_avx_mkl `fluid.tgz `_ +cuda9.0_cudnn7_avx_mkl `fluid.tgz `_ +====================== ======================================== + +从源码编译 +---------- +用户也可以从 PaddlePaddle 核心代码编译C++预测库，只需在编译时配制下面这些编译选项： + +================= ========= +选项 值 +================= ========= +CMAKE_BUILD_TYPE Release +FLUID_INSTALL_DIR 安装路径 +WITH_FLUID_ONLY ON（推荐） +WITH_SWIG_PY OFF（推荐 +WITH_PYTHON OFF（推荐） +WITH_GPU ON/OFF +WITH_MKL ON/OFF +================= ========= + +建议按照推荐值设置，以避免链接不必要的库。其它可选编译选项按需进行设定。 + +下面的代码片段从github拉取最新代码，配制编译选项（需要将PADDLE_ROOT替换为PaddlePaddle预测库的安装路径）： + + .. code-block:: bash + + pip install paddlepaddle-gpu + PADDLE_ROOT=/path/of/capi + git clone https://github.com/PaddlePaddle/Paddle.git + cd Paddle + mkdir build + cd build + cmake -DFLUID_INSTALL_DIR=$PADDLE_ROOT \ + -DCMAKE_BUILD_TYPE=Release \ + -DWITH_FLUID_ONLY=ON \ + -DWITH_SWIG_PY=OFF \ + -DWITH_PYTHON=OFF \ + -DWITH_MKL=OFF \ + -DWITH_GPU=OFF \ + .. + make + make inference_lib_dist + +成功编译后，使用C++预测库所需的依赖（包括：（1）编译出的PaddlePaddle预测库和头文件；（2）第三方链接库和头文件；（3）版本信息与编译选项信息） +均会存放于PADDLE_ROOT目录中。目录结构如下： + + .. code-block:: text + + PaddleRoot/ + ├── CMakeCache.txt + ├── paddle + │   └── fluid + │   ├── framework + │   ├── inference + │   ├── memory + │   ├── platform + │   ├── pybind + │   └── string + ├── third_party + │   ├── boost + │   │   └── boost + │   ├── eigen3 + │   │   ├── Eigen + │   │   └── unsupported + │   └── install + │   ├── gflags + │   ├── glog + │   ├── mklml + │   ├── protobuf + │   ├── snappy + │   ├── snappystream + │   └── zlib + └── version.txt + +version.txt 中记录了该预测库的版本信息，包括Git Commit ID、使用OpenBlas或MKL数学库、CUDA/CUDNN版本号，如： + + .. code-block:: text + + GIT COMMIT ID: c95cd4742f02bb009e651a00b07b21c979637dc8 + WITH_MKL: ON + WITH_GPU: ON + CUDA version: 8.0 + CUDNN version: v5 diff --git a/source/user_guides/howto/inference/index.rst b/source/user_guides/howto/inference/index.rst new file mode 100644 index 000000000..45e1a2883 --- /dev/null +++ b/source/user_guides/howto/inference/index.rst @@ -0,0 +1,11 @@ +############ +模型预测部署 +############ + +PaddlePaddle Fluid 提供了 C++ API 来支持模型的部署上线 + +.. toctree:: + :maxdepth: 2 + + build_and_install_lib_cn.rst + native_infer.rst diff --git a/source/user_guides/howto/inference/native_infer.rst b/source/user_guides/howto/inference/native_infer.rst new file mode 100644 index 000000000..e1eee3f81 --- /dev/null +++ b/source/user_guides/howto/inference/native_infer.rst @@ -0,0 +1,108 @@ +Paddle 预测 API +=============== + +为了更简单方便的预测部署，Fluid 提供了一套高层 API +用来隐藏底层不同的优化实现。 + +`预测库相关代码 `__ +包括 + +- 头文件 ``paddle_inference_api.h`` 定义了所有的接口 +- 库文件\ ``libpaddle_fluid.so`` 或 ``libpaddle_fluid.a`` +- 库文件 ``libpaddle_inference_api.so`` 或 + ``libpaddle_inference_api.a`` + +编译和依赖可以参考 :ref:`install_or_build_cpp_inference_lib` 。 + +下面是一些 API 概念的介绍 + +PaddleTensor +------------ + +PaddleTensor 定义了预测最基本的输入输出的数据格式，其定义是 + +.. code:: cpp + + struct PaddleTensor { + std::string name; // variable name. + std::vector shape; + PaddleBuf data; // blob of data. + PaddleDType dtype; + }; + +- ``name`` 用于指定输入数据对应的 模型中variable 的名字 + （暂时没有用，但会在后续支持任意 target 时启用） +- ``shape`` 表示一个 Tensor 的 shape +- ``data`` 数据以连续内存的方式存储在\ ``PaddleBuf`` + 中，\ ``PaddleBuf`` + 可以接收外面的数据或者独立\ ``malloc``\ 内存，详细可以参考头文件中相关定义。 +- ``dtype`` 表示 Tensor 的数据类型 + +engine +------ + +高层 API 底层有多种优化实现，我们称之为 engine，目前有三种 engine + +- 原生 engine，由 paddle 原生的 forward operator + 组成，可以天然支持所有paddle 训练出的模型， +- Anakin engine，封装了 + `Anakin `__ + ，在某些模型上性能不错，但只能接受自带模型格式，无法支持所有 paddle + 模型， +- TensorRT mixed engine，用子图的方式支持了 + `TensorRT `__ ，支持所有paddle + 模型，并自动切割部分计算子图到 TensorRT 上加速（WIP） + +其实现为 + +.. code:: cpp + + enum class PaddleEngineKind { + kNative = 0, // Use the native Fluid facility. + kAnakin, // Use Anakin for inference. + kAutoMixedTensorRT // Automatically mixing TensorRT with the Fluid ops. + }; + +预测部署过程 +------------ + +总体上分为以下步骤 + +1. 用合适的配置创建 ``PaddlePredictor`` +2. 创建输入用的 ``PaddleTensor``\ ，传入到 ``PaddlePredictor`` 中 +3. 获取输出的 ``PaddleTensor`` ，将结果取出 + +下面完整演示一个简单的模型，部分细节代码隐去 + +.. code:: cpp + + #include "paddle_inference_api.h" + + // 创建一个 config，并修改相关设置 + paddle::NativeConfig config; + config.model_dir = "xxx"; + config.use_gpu = false; + // 创建一个原生的 PaddlePredictor + auto predictor = + paddle::CreatePaddlePredictor(config); + // 创建输入 tensor + int64_t data[4] = {1, 2, 3, 4}; + paddle::PaddleTensor tensor{.name = "", + .shape = std::vector({4, 1}), + .data = PaddleBuf(data, sizeof(data)), + .dtype = PaddleDType::INT64}; + // 创建输出 tensor，输出 tensor 的内存可以复用 + std::vector outputs; + // 执行预测 + CHECK(predictor->Run(slots, &outputs)); + // 获取 outputs ... + +编译时，联编 ``libpaddle_fluid.a/.so`` 和 +``libpaddle_inference_api.a/.so`` 便可。 + +详细代码参考 +------------ + +- `inference + demos `__ +- `复杂单线程/多线程例子 `__ diff --git a/source/user_guides/howto/prepare_data/feeding_data.rst b/source/user_guides/howto/prepare_data/feeding_data.rst index 78f43338d..c3bf033bb 100644 --- a/source/user_guides/howto/prepare_data/feeding_data.rst +++ b/source/user_guides/howto/prepare_data/feeding_data.rst @@ -4,15 +4,15 @@ 使用Numpy Array作为训练数据 ########################### -PaddlePaddle Fluid支持使用 :ref:`api_fluid_layers_data` 配置数据层； +PaddlePaddle Fluid支持使用 :code:`fluid.layers.data()` 配置数据层； 再使用 Numpy Array 或者直接使用Python创建C++的 -:ref:`api_guide_lod_tensor` , 通过 :code:`Executor.run(feed=...)` 传给 -:ref:`api_guide_executor` 或 :ref:`api_guide_parallel_executor` 。 +:code:`fluid.LoDTensor` , 通过 :code:`Executor.run(feed=...)` 传给 +:code:`fluid.Executor` 或 :code:`fluid.ParallelExecutor` 。 数据层配置 ########## -通过 :ref:`api_fluid_layers_data` 可以配置神经网络中需要的数据层。具体方法为: +通过 :code:`fluid.layers.data()` 可以配置神经网络中需要的数据层。具体方法为: .. code-block:: python diff --git a/source/user_guides/howto/prepare_data/index.rst b/source/user_guides/howto/prepare_data/index.rst index 643702e95..56fa92802 100644 --- a/source/user_guides/howto/prepare_data/index.rst +++ b/source/user_guides/howto/prepare_data/index.rst @@ -7,12 +7,12 @@ PaddlePaddle Fluid支持两种传入数据的方式: 1. 用户需要使用 :code:`fluid.layers.data` -配置数据输入层，并在 :ref:`api_guide_executor` 或 :ref:`api_guide_parallel_executor` +配置数据输入层，并在 :code:`fluid.Executor` 或 :code:`fluid.ParallelExecutor` 中，使用 :code:`executor.run(feed=...)` 传入训练数据。 2. 用户需要先将训练数据 -转换成 Paddle 识别的 :ref:`api_guide_recordio_file_format` ， 再使用 -:code:`fluid.layers.open_files` 以及 :ref:`api_guide_reader` 配置数据读取。 +转换成 Paddle 识别的 :code:`fluid.recordio_writer` ， 再使用 +:code:`fluid.layers.open_files` 以及 :code:`fluid.layers.reader` 配置数据读取。 这两种准备数据方法的比较如下: @@ -21,9 +21,9 @@ PaddlePaddle Fluid支持两种传入数据的方式: +------------+----------------------------------+---------------------------------------+ | | Feed数据 | 使用Reader | +============+==================================+=======================================+ -| API接口 | :code:`executor.run(feed=...)` | :ref:`api_guide_reader` | +| API接口 | :code:`executor.run(feed=...)` | :code:`fluid.layers.reader` | +------------+----------------------------------+---------------------------------------+ -| 数据格式 | Numpy Array | :ref:`api_guide_recordio_file_format` | +| 数据格式 | Numpy Array | :code:`fluid.recordio_writer` | +------------+----------------------------------+---------------------------------------+ | 数据增强 | Python端使用其他库完成 | 使用Fluid中的Operator 完成 | +------------+----------------------------------+---------------------------------------+ diff --git a/source/user_guides/howto/prepare_data/use_recordio_reader.rst b/source/user_guides/howto/prepare_data/use_recordio_reader.rst index 3121ae74c..dfda33f1b 100644 --- a/source/user_guides/howto/prepare_data/use_recordio_reader.rst +++ b/source/user_guides/howto/prepare_data/use_recordio_reader.rst @@ -7,20 +7,20 @@ 相比于 :ref:`user_guide_use_numpy_array_as_train_data`， :ref:`user_guide_use_recordio_as_train_data` 的性能更好； 但是用户需要先将训练数据集转换成RecordIO文件格式，再使用 -:ref:`api_fluid_layers_open_files` 层在神经网络配置中导入 RecordIO 文件。 -用户还可以使用 :ref:`api_fluid_layers_double_buffer` 加速数据从内存到显存的拷贝， -使用 :ref:`api_fluid_layers_Preprocessor` 工具进行数据增强。 +:code:`fluid.layers.open_files()` 层在神经网络配置中导入 RecordIO 文件。 +用户还可以使用 :code:`fluid.layers.double_buffer()` 加速数据从内存到显存的拷贝， +使用 :code:`fluid.layers.Preprocessor` 工具进行数据增强。 将训练数据转换成RecordIO文件格式 ################################ -:ref:`api_guide_recordio_file_format` 中，每个记录都是一个 +:code:`fluid.recordio_writer` 中，每个记录都是一个 :code:`vector`, 即一个支持序列信息的Tensor数组。这个数组包括训练所需 的所有特征。例如对于图像分类来说，这个数组可以包含图片和分类标签。 -用户可以使用 :ref:`api_fluid_recordio_writer_convert_reader_to_recordio_file` 可以将 +用户可以使用 :code:`fluid.recordio_writer.convert_reader_to_recordio_file()` 可以将 :ref:`user_guide_reader` 转换成一个RecordIO文件。或者可以使用 -:ref:`api_fluid_recordio_writer_convert_reader_to_recordio_files` 将一个 +:code:`fluid.recordio_writer.convert_reader_to_recordio_files()` 将一个 :ref:`user_guide_reader` 转换成多个RecordIO文件。 具体使用方法为: @@ -62,8 +62,8 @@ 配置神经网络, 打开RecordIO文件 ############################## -RecordIO文件转换好之后，用户可以使用 :ref:`api_fluid_layers_open_files` -打开文件，并使用 :ref:`api_fluid_layers_read_file` 读取文件内容。 +RecordIO文件转换好之后，用户可以使用 :code:`fluid.layers.open_files()` +打开文件，并使用 :code:`fluid.layers.read_file` 读取文件内容。 简单使用方法如下: .. code-block:: python @@ -89,11 +89,11 @@ RecordIO文件转换好之后，用户可以使用 :ref:`api_fluid_layers_open_f ######## -使用 :ref:`api_fluid_layers_double_buffer` +使用 :code:`fluid.layers.double_buffer()` ------------------------------------------ :code:`Double buffer` 使用双缓冲技术，将训练数据从内存中复制到显存中。配置双缓冲 -需要使用 :ref:`api_fluid_layers_double_buffer` 修饰文件对象。 例如: +需要使用 :code:`fluid.layers.double_buffer()` 修饰文件对象。 例如: .. code-block:: python @@ -109,7 +109,7 @@ RecordIO文件转换好之后，用户可以使用 :ref:`api_fluid_layers_open_f 配置数据增强 ------------ -使用 :ref:`api_fluid_layers_Preprocessor` 可以配置文件的数据增强方法。例如 +使用 :code:`fluid.layers.Preprocessor` 可以配置文件的数据增强方法。例如 .. code-block:: python @@ -132,7 +132,7 @@ RecordIO文件转换好之后，用户可以使用 :ref:`api_fluid_layers_open_f 使用Op组batch ------------- -使用 :ref:`api_fluid_layers_batch` 可以在训练的过程中动态的组batch。例如 +使用 :code:`fluid.layers.batch()` 可以在训练的过程中动态的组batch。例如 .. code-block:: python @@ -148,7 +148,7 @@ RecordIO文件转换好之后，用户可以使用 :ref:`api_fluid_layers_open_f 读入数据的shuffle ----------------- -使用 :ref:`api_fluid_layers_shuffle` 可以在训练过程中动态重排训练数据。例如 +使用 :code:`fluid.layers.shuffle()` 可以在训练过程中动态重排训练数据。例如 .. code-block:: python diff --git a/source/user_guides/howto/training/checkpoint_doc_cn.md b/source/user_guides/howto/training/checkpoint_doc_cn.md index 51e07683f..c4afd536c 100644 --- a/source/user_guides/howto/training/checkpoint_doc_cn.md +++ b/source/user_guides/howto/training/checkpoint_doc_cn.md @@ -57,4 +57,4 @@ trainer = Trainer(..., checkpoint_config=config) 1. 保证每个训练的```checkpoint_dir``` 与其他训练独立。 2. 最大副本数量```max_num_checkpoints```需要根据磁盘容量以及模型的大小进行调整， 保证磁盘的可用性。 3. ```epoch_interval``` 和 ```step_interval``` 不宜过小， 频繁的进行checkpoint会拖慢训练速度。 -4. **分布式训练**的过程中：每个Trainer都会在```checkpoint_dir```目录中保存当前Trainer的参数（只有Trainer 0会保存模型的参数），需要**分布式文件系统(HDFS等)**将同```checkpoint_dir```目录的数据进行合并才能得到完整的数据，恢复训练的时候需要用完整的数据进行恢复。 \ No newline at end of file +4. **分布式训练**的过程中：每个Trainer都会在```checkpoint_dir```目录中保存当前Trainer的参数（只有Trainer 0会保存模型的参数），需要**分布式文件系统(HDFS等)**将同```checkpoint_dir```目录的数据进行合并才能得到完整的数据，恢复训练的时候需要用完整的数据进行恢复。 diff --git a/source/user_guides/howto/training/checkpoint_doc_en.md b/source/user_guides/howto/training/checkpoint_doc_en.md index 60524f640..14d37246c 100644 --- a/source/user_guides/howto/training/checkpoint_doc_en.md +++ b/source/user_guides/howto/training/checkpoint_doc_en.md @@ -59,4 +59,4 @@ After all the things done, the train will save checkpoint at the specified epoch 1. Make the ```checkpoint_dir``` only be used by one train job. 2. The number of ```max_num_checkpoints``` need to be adjusted by the disk size and model size. 3. Too frequently to slow down the train speed, so too ```small epoch_interval``` and ```step_interval``` are not suitable. -4. **In distributed train**, each Trainer will save arguments in its ```checkpoint_dir``` (Only Trainer 0 will save model variables). We need **distributed file system (HDFS, etc)** to merge all the ```checkpoint_dir``` to get the whole data. \ No newline at end of file +4. **In distributed train**, each Trainer will save arguments in its ```checkpoint_dir``` (Only Trainer 0 will save model variables). We need **distributed file system (HDFS, etc)** to merge all the ```checkpoint_dir``` to get the whole data. diff --git a/source/user_guides/howto/training/save_load_variables.rst b/source/user_guides/howto/training/save_load_variables.rst index 7d6023124..a96776f4a 100644 --- a/source/user_guides/howto/training/save_load_variables.rst +++ b/source/user_guides/howto/training/save_load_variables.rst @@ -7,19 +7,19 @@ 模型变量分类 ############ -在PaddlePaddle Fluid中，所有的模型变量都用 :ref:`api_fluid_Variable` 作为基类进行表示。 +在PaddlePaddle Fluid中，所有的模型变量都用 :code:`fluid.Variable()` 作为基类进行表示。 在该基类之下，模型变量主要可以分为以下几种类别： 1. 模型参数 模型参数是深度学习模型中被训练和学习的变量，在训练过程中，训练框架根据反向传播算法计算出每一个模型参数当前的梯度， 并用优化器根据梯度对参数进行更新。模型的训练过程本质上可以看做是模型参数不断迭代更新的过程。 在PaddlePaddle Fluid中，模型参数用 :code:`fluid.framework.Parameter` 来表示， - 这是一个 :ref:`api_fluid_Variable` 的派生类，除了 :ref:`api_fluid_Variable` 具有的各项性质以外， + 这是一个 :code:`fluid.Variable()` 的派生类，除了 :code:`fluid.Variable()` 具有的各项性质以外， :code:`fluid.framework.Parameter` 还可以配置自身的初始化方法、更新率等属性。 2. 长期变量 长期变量指的是在整个训练过程中持续存在、不会因为一个迭代的结束而被销毁的变量，例如动态调节的全局学习率等。 - 在PaddlePaddle Fluid中，长期变量通过将 :ref:`api_fluid_Variable` 的 :code:`persistable` + 在PaddlePaddle Fluid中，长期变量通过将 :code:`fluid.Variable()` 的 :code:`persistable` 属性设置为 :code:`True` 来表示。所有的模型参数都是长期变量，但并非所有的长期变量都是模型参数。 3. 临时变量 @@ -43,7 +43,7 @@ ========================== 如果我们保存模型的目的是用于对新样本的预测，那么只保存模型参数就足够了。我们可以使用 -:ref:`api_fluid_io_save_params` 接口来进行模型参数的保存。 +:code:`fluid.io.save_params()` 接口来进行模型参数的保存。 例如： @@ -57,7 +57,7 @@ fluid.io.save_params(executor=exe, dirname=param_path, main_program=None) 上面的例子中，通过调用 :code:`fluid.io.save_params` 函数，PaddlePaddle Fluid会对默认 -:ref:`api_fluid_Program` 也就是 :code:`prog` 中的所有模型变量进行扫描， +:code:`fluid.Program` 也就是 :code:`prog` 中的所有模型变量进行扫描， 筛选出其中所有的模型参数，并将这些模型参数保存到指定的 :code:`param_path` 之中。 @@ -66,7 +66,7 @@ 在训练过程中，我们可能希望在一些节点上将当前的训练状态保存下来， 以便在将来需要的时候恢复训练环境继续进行训练。这一般被称作“checkpoint”。 -想要保存checkpoint，可以使用 :ref:`api_fluid_io_save_checkpoint` 接口。 +想要保存checkpoint，可以使用 :code:`fluid.io.save_checkpiont()` 接口。 例如： @@ -87,7 +87,7 @@ max_num_checkpoints=3) 上面的例子中，通过调用 :code:`fluid.io.save_checkpoint` 函数，PaddlePaddle Fluid会对默认 -:ref:`api_fluid_Program` 也就是 :code:`prog` 中的所有模型变量进行扫描， +:code:`fluid.Program` 也就是 :code:`prog` 中的所有模型变量进行扫描， 根据一系列内置的规则自动筛选出其中所有需要保存的变量，并将他们保存到指定的 :code:`path` 目录下。 :code:`fluid.io.save_checkpoint` 的各个参数中， :code:`trainer_id` 在单机情况下设置为0即可； :code:`trainer_args` @@ -125,8 +125,8 @@ 需要格外注意的是，这里的 :code:`prog` 必须和调用 :code:`fluid.io.save_params` 时所用的 :code:`prog` 中的前向部分完全一致，且不能包含任何参数更新的操作。如果两者存在不一致， 那么可能会导致一些变量未被正确加载；如果错误地包含了参数更新操作，那可能会导致正常预测过程中参数被更改。 -这两个 :ref:`api_fluid_Program` 之间的关系类似于训练 :ref:`api_fluid_Program` -和测试 :ref:`api_fluid_Program` 之间的关系，详见： :ref:`user_guide_test_while_training`。 +这两个 :code:`fluid.Program` 之间的关系类似于训练 :code:`fluid.Program` +和测试 :code:`fluid.Program` 之间的关系，详见： :ref:`user_guide_test_while_training`。 另外，需特别注意运行 :code:`fluid.default_startup_program()` 必须在调用 :code:`fluid.io.load_params` 之前。如果在之后运行，可能会覆盖已加载的模型参数导致错误。 diff --git a/source/user_guides/howto/training/single_node.rst b/source/user_guides/howto/training/single_node.rst index 4282a39bc..23eac0f83 100644 --- a/source/user_guides/howto/training/single_node.rst +++ b/source/user_guides/howto/training/single_node.rst @@ -8,8 +8,8 @@ 要进行PaddlePaddle Fluid单机训练，需要先 :ref:`user_guide_prepare_data` 和 :ref:`user_guide_configure_simple_model` 。当\ :ref:`user_guide_configure_simple_model` 完毕后，可以得到两个\ -:ref:`api_fluid_Program`， :code:`startup_program` 和 :code:`main_program`。 -默认情况下，可以使用 :ref:`api_fluid_default_startup_program` 与\ :ref:`api_fluid_default_main_program` 获得全局的 :ref:`api_fluid_Program`。 +:code:`fluid.Program`， :code:`startup_program` 和 :code:`main_program`。 +默认情况下，可以使用 :code:`fluid.default_startup_program()` 与\ :code:`fluid.default_main_program()` 获得全局的 :code:`fluid.Program`。 例如: @@ -44,8 +44,8 @@ ============== 用户配置完模型后，参数初始化操作会被写入到\ -:code:`fluid.default_startup_program()` 中。使用 :ref:`api_fluid_Executor` 运行 -这一程序，即可在全局 :ref:`api_fluid_global_scope` 中随机初始化参数。例如: +:code:`fluid.default_startup_program()` 中。使用 :code:`fluid.Executor()` 运行 +这一程序，即可在全局 :code:`fluid.global_scope()` 中随机初始化参数。例如: .. code-block:: python @@ -53,7 +53,7 @@ exe.run(program=fluid.default_startup_program()) 值得注意的是: 如果使用多GPU训练，参数需要先在GPU0上初始化，再经由\ -:ref:`api_fluid_ParallelExecutor` 分发到多张显卡上。 +:code:`fluid.ParallelExecutor` 分发到多张显卡上。 载入预定义参数 @@ -66,8 +66,8 @@ 单卡训练 ######## -执行单卡训练可以使用 :ref:`api_fluid_Executor` 中的 :code:`run()` 方法，运行训练\ -:ref:`api_fluid_Program` 即可。在运行的时候，用户可以通过 :code:`run(feed=...)`\ +执行单卡训练可以使用 :code:`fluid.Executor()` 中的 :code:`run()` 方法，运行训练\ +:code:`fluid.Program` 即可。在运行的时候，用户可以通过 :code:`run(feed=...)`\ 参数传入数据；用户可以通过 :code:`run(fetch=...)` 获取持久的数据。例如:\ .. code-block:: python @@ -86,14 +86,14 @@ 的Variable必须是persistable的。 :code:`fetch_list` 可以传入Variable的列表，\ 也可以传入Variable的名字列表。:code:`Executor.run` 返回Fetch结果列表。 3. 如果需要取回的数据包含序列信息，可以设置 - :code:`exe.run(return_numpy=False, ...)` 直接返回 :ref:`api_guide_lod_tensor` - 。用户可以直接访问 :ref:`api_guide_lod_tensor` 中的信息。 + :code:`exe.run(return_numpy=False, ...)` 直接返回 :code:`fluid.LoDTensor` + 。用户可以直接访问 :code:`fluid.LoDTensor` 中的信息。 多卡训练 ######## -执行多卡训练可以使用 :ref:`api_fluid_ParallelExecutor` 运行训练 -:ref:`api_fluid_Program`。例如: +执行多卡训练可以使用 :code:`fluid.ParallelExecutor` 运行训练 +:code:`fluid.Program`。例如: .. code-block:: python @@ -103,8 +103,8 @@ 这里有几点注意事项: -1. :code:`ParallelExecutor` 的构造函数需要指明要执行的 :ref:`api_fluid_Program` , - 并在执行过程中不能修改。默认值是 :ref:`api_fluid_default_main_program` 。 +1. :code:`ParallelExecutor` 的构造函数需要指明要执行的 :code:`fluid.Program` , + 并在执行过程中不能修改。默认值是 :code:`fluid.default_main_program()` 。 2. :code:`ParallelExecutor` 需要明确指定是否使用 CUDA 显卡进行训练。在显卡训练\ 模式下会占用全部显卡。用户可以配置 `CUDA_VISIBLE_DEVICES `_ 来修改占用\ 的显卡。 diff --git a/source/user_guides/howto/training/test_while_training.rst b/source/user_guides/howto/training/test_while_training.rst index 665aa52ec..37d5c0d78 100644 --- a/source/user_guides/howto/training/test_while_training.rst +++ b/source/user_guides/howto/training/test_while_training.rst @@ -4,7 +4,7 @@ 训练过程中评测模型 ################## -模型的测试评价与训练的 :ref:`api_fluid_Program` 不同。在测试评价中: +模型的测试评价与训练的 :code:`fluid.Program` 不同。在测试评价中: 1. 评价测试不进行反向传播，不优化更新参数。 2. 评价测试执行的操作可以不同。 @@ -13,13 +13,13 @@ * 评价模型与训练相比可以是完全不同的模型。 -生成测试 :ref:`api_fluid_Program` +生成测试 :code:`fluid.Program` ################################# -通过克隆训练 :ref:`api_fluid_Program` 生成测试 :ref:`api_fluid_Program` +通过克隆训练 :code:`fluid.Program` 生成测试 :code:`fluid.Program` ======================================================================= -:code:`Program.clone()` 方法可以复制出新的 :ref:`api_fluid_Program` 。 通过设置 +:code:`Program.clone()` 方法可以复制出新的 :code:`fluid.Program` 。 通过设置 :code:`Program.clone(for_test=True)` 复制含有用于测试的操作Program。简单的使用方法如下: .. code-block:: python @@ -45,11 +45,11 @@ 成一个 :code:`test_program` 。之后使用测试数据运行 :code:`test_program`,\ 就可以做到运行测试程序，而不影响训练结果。 -分别配置训练 :ref:`api_fluid_Program` 和测试 :ref:`api_fluid_Program` +分别配置训练 :code:`fluid.Program` 和测试 :code:`fluid.Program` ===================================================================== 如果训练程序和测试程序相差较大时，用户也可以通过完全定义两个不同的 -:ref:`api_fluid_Program`，分别进行训练和测试。在PaddlePaddle Fluid中，\ +:code:`fluid.Program`，分别进行训练和测试。在PaddlePaddle Fluid中，\ 所有的参数都有名字。如果两个不同的操作，甚至两个不同的网络使用了同样名字的参数，\ 那么他们的值和内存空间都是共享的。 @@ -84,14 +84,14 @@ PaddlePaddle Fluid中使用 :code:`fluid.unique_name` 包来随机初始化用 # fluid.default_main_program() is the train program # fluid.test_program is the test program -执行测试 :ref:`api_fluid_Program` +执行测试 :code:`fluid.Program` ################################# -使用 :code:`Executor` 执行测试 :ref:`api_fluid_Program` +使用 :code:`Executor` 执行测试 :code:`fluid.Program` ======================================================= 用户可以使用 :code:`Executor.run(program=...)` 来执行测试 -:ref:`api_fluid_Program`。 +:code:`fluid.Program`。 例如 @@ -101,10 +101,10 @@ PaddlePaddle Fluid中使用 :code:`fluid.unique_name` 包来随机初始化用 test_acc = exe.run(program=test_program, feed=test_data_batch, fetch_list=[acc]) print 'Test accuracy is ', test_acc -使用 :code:`ParallelExecutor` 执行测试 :ref:`api_fluid_Program` +使用 :code:`ParallelExecutor` 执行测试 :code:`fluid.Program` =============================================================== -用户可以使用训练用的 :code:`ParallelExecutor` 与测试 :ref:`api_fluid_Program` +用户可以使用训练用的 :code:`ParallelExecutor` 与测试 :code:`fluid.Program` 一起新建一个测试的 :code:`ParallelExecutor` ；再使用测试 :code:`ParallelExecutor.run` 来执行测试。 diff --git a/source/user_guides/index.rst b/source/user_guides/index.rst index 453cb71cf..377631109 100644 --- a/source/user_guides/index.rst +++ b/source/user_guides/index.rst @@ -15,4 +15,5 @@ howto/training/index howto/debug/index howto/evaluation/index + howto/inference/index models/index.rst diff --git a/source/user_guides/models/index.rst b/source/user_guides/models/index.rst index 0eba1bcdd..998e95c48 100644 --- a/source/user_guides/models/index.rst +++ b/source/user_guides/models/index.rst @@ -31,12 +31,13 @@ Fluid模型配置和参数文件的工具。 在目标检测任务中，我们介绍了如何基于\ `PASCAL VOC `__\ 、\ `MS -COCO `__\ 数据的训练目标检测算法SSD，SSD全称Single -Shot MultiBox -Detector，是目标检测领域较新且效果较好的检测算法之一，具有检测速度快且检测精度高的特点，并开源了训练好的\ `MobileNet-SSD模型 `__\ 。 +COCO `__\ 数据训练通用物体检测模型，当前介绍了SSD算法，SSD全称Single Shot MultiBox Detector，是目标检测领域较新且效果较好的检测算法之一，具有检测速度快且检测精度高的特点。 + +开放环境中的检测人脸，尤其是小的、模糊的和部分遮挡的人脸也是一个具有挑战的任务。我们也介绍了如何基于 `WIDER FACE `_ 数据训练百度自研的人脸检测PyramidBox模型，该算法于2018年3月份在WIDER FACE的多项评测中均获得 `第一名 `_。 - `Single Shot MultiBox Detector `__ +- `Face Detector: PyramidBox `_ 图像语义分割 ------------ -- GitLab