diff --git a/doc/howto/usage/capi/a_simple_example.md b/doc/howto/usage/capi/a_simple_example_cn.md similarity index 68% rename from doc/howto/usage/capi/a_simple_example.md rename to doc/howto/usage/capi/a_simple_example_cn.md index b1eceea38bc3360be0ff469b69232c8845845ed0..abe07a41cfa28c12fad7c90e826a90057b6389e1 100644 --- a/doc/howto/usage/capi/a_simple_example.md +++ b/doc/howto/usage/capi/a_simple_example_cn.md @@ -4,8 +4,8 @@ ### 使用流程 -使用 C-API 分为：准备工作和预测程序开发两部分。 -- 准备 +使用 C-API 分为：准备预测模型和预测程序开发两部分。 +- 准备预测模型 1. 将神经网络模型结构进行序列化。 - 调用C-API预测时，需要提供序列化之后的网络结构和训练好的模型参数文件。 1. 将PaddlePaddle训练出的模型参数文件（多个）合并成一个文件。 @@ -14,18 +14,17 @@ - **注意**：以上两种方式只需选择其一即可。 - 调用 PaddlePaddle C-API 开发预测序 1. 初始化PaddlePaddle运行环境。 - 1. 创建神经网络的输入，组织输入数据。 1. 加载模型。 + 1. 创建神经网络的输入，组织输入数据。 1. 进行前向计算，获得计算结果。 1. 清理。 +本文档以手写数字识别任务为例，介绍如何使用 C-API 进行预测，完整代码请查看[此目录](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/capi/examples/model_inference/dense)。 -这里我们以手写数字识别任务为例，介绍如何使用 C-API 进行预测，完整代码请查看[此目录](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/capi/examples/model_inference/dense)。 - -运行目录下的 `python mnist_v2.py` 可以使用 PaddlePaddle 内置的 [MNIST 数据集](http://yann.lecun.com/exdb/mnist/)进行训练。脚本中的模型定义了一个简单的含有[两个隐层的全连接网络](https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/README.cn.md#softmax回归softmax-regression)，网络接受一幅图片作为输入，将图片分类到 0 ~ 9 类别标签之一。训练好的模型默认保存在当前运行目录下的`models`目录中。下面，我们将调用 C-API 加载训练好的模型进行预测。 +### 准备预测模型 - -### 外部准备 +通过在终端执行`python mnist_v2.py` +运行[目录](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/capi/examples/model_inference/dense)下的 `mnist_v2.py` s可以使用 PaddlePaddle 内置的 [MNIST 数据集](http://yann.lecun.com/exdb/mnist/)进行训练。脚本中的模型定义了一个简单的含有[两个隐层的全连接网络](https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/README.cn.md#softmax回归softmax-regression)，网络接受一幅图片作为输入，将图片分类到 0 ~ 9 类别标签之一。训练好的模型默认保存在当前运行目录下的`models`目录中。下面，我们将调用 C-API 加载训练好的模型进行预测。 1. 序列化神经网络模型配置 @@ -52,8 +51,7 @@ 代码示例如下： ```python - from paddle.utils.merge_model import merge_v2_model - + from paddle.utils.merge_model import merge_v2_modelss from mnist_v2 import network net = network(is_infer=True) @@ -70,54 +68,65 @@ ### 编写预测代码 -#### step 1. 初始化及加载模型 +#### step 1. 初始化PaddlePaddle运行环境 +使用C-API第一步需首先调用[`paddle_init`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/capi/main.h#L27) 初始化PaddlePaddle运行环境。接口接受两个参数：参数的个数和参数。 -1. 初始化PaddlePaddle运行环境。 - ```c - // Initalize the PaddlePaddle runtime environment. - char* argv[] = {"--use_gpu=False"}; - CHECK(paddle_init(1, (char**)argv)); - ``` +下面的代码片段在初始化PaddlePaddle运行环境时指定不使用GPU： -1. 加载训练好的模型。 +```c +// Initalize the PaddlePaddle runtime environment. +char* argv[] = {"--use_gpu=False"}; +CHECK(paddle_init(1, (char**)argv)); +``` - 这里需要介绍C-API使用中的一个重要概念：Gradient Machine。概念上，在 PaddlePaddle 内部，一个GradientMachine类的对象管理着一组计算层（PaddlePaddle Layers）来完成前向和反向计算，并处理与之相关的所有细节。特别的，在调用C-API预测时只需进行前向计算。这篇文档的之后部分我们会使用`gradient machine`来特指调用PaddlePaddle C-API创建的GradientMachine类的对象。 +下面的代码片段在初始化PaddlePaddle运行环境时指定了两个参数：不使用GPU和[使用MKLDNN](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/design/mkl/mkldnn.md)： - 每一个 `gradient machine` 都会管理维护一份训练好的模型，模型可以通过以下两种方式获取： - 1. 从磁盘加载；这时`gradient machine`会独立拥有一份训练好的模型； - 1. 共享自其它`gradient machine`的模型；这种情况多出现在使用多线程预测时； +```c +char* argv[] = {"--use_gpu=False", "--use_mkldnn=True"}; +CHECK(paddle_init(2, (char**)argv)); +``` - 下面的代码片段创建 `gradient machine`，并从指定路径加载训练好的模型。 +#### step2. 加载模型 - ```c - // Read the binary configuration file generated by `convert_protobin.sh` - long size; - void* buf = read_config(CONFIG_BIN, &size); +这里介绍C-API使用中的一个重要概念：Gradient Machine。概念上，在 PaddlePaddle 内部一个GradientMachine类的对象管理着一组计算层（PaddlePaddle Layers）来完成前向和反向计算，并处理与之相关的所有细节。在调用C-API预测时，只需进行前向计算而无需调用反向计算。这篇文档的之后部分我们会使用`gradient machine`来特指调用PaddlePaddle C-API创建的GradientMachine类的对象。 - // Create the gradient machine for inference. - paddle_gradient_machine machine; - CHECK(paddle_gradient_machine_create_for_inference(&machine, buf, (int)size)); +每一个 `gradient machine` 都会管理维护一份训练好的模型，下面是两种最常用的模型加载方式： - // Load the trained model. Modify the parameter MODEL_PATH to set the correct - // path of the trained model. - CHECK(paddle_gradient_machine_load_parameter_from_disk(machine, MODEL_PATH)); - ``` +1. 从磁盘加载：这时`gradient machine`会独立拥有一份训练好的模型； +1. 共享自其它`gradient machine`的模型：这种情况多出现在使用多线程预测时，通过多个线程共享同一个模型来减少内存开销。可参考[此示例](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/capi/examples/model_inference/multi_thread/main.c)。 + +下面的代码片段创建 `gradient machine`，并从指定路径加载训练好的模型。 + +```c +// Read the binary configuration file generated by `convert_protobin.sh` +long size; +void* buf = read_config(CONFIG_BIN, &size); + +// Create the gradient machine for inference. +paddle_gradient_machine machine; +CHECK(paddle_gradient_machine_create_for_inference(&machine, buf, (int)size)); + +// Load the trained model. Modify the parameter MODEL_PATH to set the correct +// path of the trained model. +CHECK(paddle_gradient_machine_load_parameter_from_disk(machine, MODEL_PATH)); +``` ##### 注意事项 1. 以上代码片段使用“仅序列化神经网络结构”的方式加载模型，需要同时指定模型参数存储的路径。 - 使用PaddlePaddle V2 API训练，模型中所有可学习参数会被存为一个压缩文件，需要手动进行解压，将它们放在同一目录中，C-API不会直接加载 V2 API 存储的压缩文件。 1. 如果使用`merge model`方式将神经网络结构和训练好的参数序列化到一个文件，请参考此[示例](https://github.com/PaddlePaddle/Mobile/blob/develop/Demo/linux/paddle_image_recognizer.cpp#L59)。 +1. 加载模型有多种方式，也可以在程序运行过程中再加载另外一个模型。 #### step 2. 创建神经网络输入，组织输入数据 基本使用概念： -- 在PaddlePaddle内部，神经网络中一个计算层的输入/输出被组织为一个 `Argument` 结构体，如果神经网络有多个输入或者多个输入，每一个输入/输入都会对应有自己的`Argument`。 +- 在PaddlePaddle内部，神经网络中一个计算层的输入输出被组织为一个 `Argument` 结构体，如果神经网络有多个输入或者多个输出，每一个输入/输出都会对应有自己的`Argument`。 - `Argument` 并不真正“存储”数据，而是将输入/输出数据有机地组织在一起。 - 在`Argument`内部由：1. `Matrix`（二维矩阵，存储浮点类型输入/输出）；2. `IVector`（一维数组，**仅用于存储整型值**，多用于自然语言处理任务）来实际存储数据。 *注：本文档使用的示例任务手写数字识别不涉及一维整型数组作为输入，因此，本文档仅讨论二维稠密矩阵作为输入的情形。更多输入数据格式请参考输入/输出数据一节的内容。* -这篇文档的之后部分会使用`argument`来**特指** PaddlePaddle C-API中神经网的一个输入/输出，使用`paddle_matrix`**特指**`argument`中用于存储数据的`Matrix`类的对象。 +这篇文档的之后部分会使用`argument`来**特指** PaddlePaddle C-API中神经网络的一个输入/输出，使用`paddle_matrix`**特指**`argument`中用于存储数据的`Matrix`类的对象。 于是，在组织神经网络输入，获取输出时，需要思考完成以下工作： 1. 为每一个输入/输出创建`argument`； diff --git a/doc/howto/usage/capi/compile_paddle_lib.md b/doc/howto/usage/capi/compile_paddle_lib.md deleted file mode 100644 index d4ac4f27711a8df64cb4c5f9206a6abfed4cba10..0000000000000000000000000000000000000000 --- a/doc/howto/usage/capi/compile_paddle_lib.md +++ /dev/null @@ -1,70 +0,0 @@ -## 编译 PaddlePaddle 链接库 - -### 概述 - -使用 C-API 进行预测依赖于将 PaddlePaddle 核心代码编译成链接库，只需在编译时指定编译选项：`-DWITH_C_API=ON`。同时，**建议将：`DWITH_PYTHON`，`DWITH_SWIG_PY`，`DWITH_GOLANG`，均设置为`OFF`**，以避免链接不必要的库。其它编译选项按需进行设定。 - -```shell -INSTALL_PREFIX=/path/of/capi/ -PADDLE_ROOT=/path/of/paddle_source/ -cmake $PADDLE_ROOT -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX \ - -DCMAKE_BUILD_TYPE=Release \ - -DWITH_C_API=ON \ - -DWITH_SWIG_PY=OFF \ - -DWITH_GOLANG=OFF \ - -DWITH_PYTHON=OFF \ - -DWITH_MKLML=OFF \ - -DWITH_MKLDNN=OFF \ - -DWITH_GPU=OFF \ - ... -``` -在上面的代码片段中，`PADDLE_ROOT` 表示 PaddlePaddle 源码所在目录，生成Makefile文件后执行：`make && make install`。成功执行后，使用CAPI所需的依赖（包括：（1）编译出的PaddlePaddle 链接和头文件；（2）第三方链接库和头文件）均会存放于`INSTALL_PREFIX`目录中。 - -编译成功后在 `INSTALL_PREFIX` 下会看到如下目录结构（包括了编译出的PaddlePaddle头文件和链接库，以及第三方依赖链接库和头文件（如果需要，由链接方式决定））： - -```text -├── include -│   └── paddle -│   ├── arguments.h -│   ├── capi.h -│   ├── capi_private.h -│   ├── config.h -│   ├── error.h -│   ├── gradient_machine.h -│   ├── main.h -│   ├── matrix.h -│   ├── paddle_capi.map -│   └── vector.h -├── lib -│   ├── libpaddle_capi_engine.a -│   ├── libpaddle_capi_layers.a -│   ├── libpaddle_capi_shared.dylib -│   └── libpaddle_capi_whole.a -└── third_party - ├── ...... -``` - -### 链接方式说明 - -目前提供三种链接方式： - -1. 链接`libpaddle_capi_shared.so` 动态库 - - 使用 PaddlePaddle C-API 开发预测程序链接`libpaddle_capi_shared.so`时，需注意： - 1. 如果编译时指定编译CPU版本，且使用`OpenBLAS`矩阵库，在使用CAPI开发预测程序时，只需要链接`libpaddle_capi_shared.so`这一个库。 - 1. 如果是用编译时指定CPU版本，且使用`MKL`矩阵库，由于`MKL`库有自己独立的动态库文件，在使用PaddlePaddle CAPI开发预测程序时，需要自己链接MKL链接库。 - 1. 如果编译时指定编译GPU版本，CUDA相关库会在预测程序运行时动态装载，需要将CUDA相关的库设置到`LD_LIBRARY_PATH`环境变量中。 - - 这种方式最为简便，链接相对容易，**在无特殊需求情况下，推荐使用此方式**。 - -2. 链接静态库 `libpaddle_capi_whole.a` - - 使用PaddlePaddle C-API 开发预测程序链接`libpaddle_capi_whole.a`时，需注意： - 1. 需要指定`-Wl,--whole-archive`链接选项。 - 1. 需要显式地链接 `gflags`、`glog`、`libz`、`protobuf` 等第三方库，可在`INSTALL_PREFIX\third_party`下找到。 - 1. 如果在编译 C-API 时使用OpenBLAS矩阵库，需要显示地链接`libopenblas.a`。 - 1. 如果在编译 C-API 是使用 MKL 矩阵库，需要显示地链接 MKL 的动态库。 - -3. 链接静态库 `libpaddle_capi_layers.a`和`libpaddle_capi_engine.a` - - 使用PaddlePaddle C-API 开发预测程序链接`libpaddle_capi_whole.a`时，需注意： - 1. 这种链接方式主要用于移动端预测。 - 1. 为了减少生成链接库的大小把`libpaddle_capi_whole.a`拆成以上两个静态链接库。 - 1. 需指定`-Wl,--whole-archive -lpaddle_capi_layers` 和 `-Wl,--no-whole-archive -lpaddle_capi_engine` 进行链接。 - 1. 第三方依赖库需要按照与方式2同样方法显示地进行链接。 diff --git a/doc/howto/usage/capi/compile_paddle_lib_cn.md b/doc/howto/usage/capi/compile_paddle_lib_cn.md new file mode 100644 index 0000000000000000000000000000000000000000..ac5ecffe2ea8ddc3703a32e9a0a8ee83bbe5dd14 --- /dev/null +++ b/doc/howto/usage/capi/compile_paddle_lib_cn.md @@ -0,0 +1,122 @@ +## 编译 PaddlePaddle 预测库 + +### 概述 + +使用 C-API 进行预测依赖于将 PaddlePaddle 核心代码编译成链接库，只需在编译时需配制下面这些编译选项： + +必须配置选项： +- `WITH_C_API`，必须配置为`ON`。 + +推荐配置选项： +- `WITH_PYTHON`，推荐配置为`OFF` +- `WITH_SWIG_PY`，推荐配置为`OFF` +- `WITH_GOLANG`，推荐设置为`OFF` + +可选配置选项： +- `WITH_GPU`，可配置为`ON/OFF` +- `WITH_MKL`，可配置为`ON/OFF` + +对推荐配置中的选项建议按照设置，以避免链接不必要的库。其它可选编译选项按需进行设定。 + +下面的代码片段从github拉取最新代码，配制编译选项（需要将PADDLE_ROOT替换为PaddlePaddle预测库的安装路径）： + +```shell +PADDLE_ROOT=/path/of/capi +git clone https://github.com/PaddlePaddle/Paddle.git +cd Paddle +mkdir build +cd build +cmake -DCMAKE_INSTALL_PREFIX=$PADDLE_ROOT \ + -DCMAKE_BUILD_TYPE=Release \ + -DWITH_C_API=ON \ + -DWITH_SWIG_PY=OFF \ + -DWITH_GOLANG=OFF \ + -DWITH_PYTHON=OFF \ + -DWITH_MKL=OFF \ + -DWITH_GPU=OFF \ + .. +``` + +执行上述代码生成Makefile文件后，执行：`make && make install`。成功编译后，使用C-API所需的依赖（包括：（1）编译出的PaddlePaddle预测库和头文件；（2）第三方链接库和头文件）均会存放于`PADDLE_ROOT`目录中。 + +编译成功后在 `PADDLE_ROOT` 下会看到如下目录结构（包括了编译出的PaddlePaddle头文件和链接库，以及第三方依赖链接库和头文件（如果需要，由链接方式决定））： + +```text +├── include +│   └── paddle +│   ├── arguments.h +│   ├── capi.h +│   ├── capi_private.h +│   ├── config.h +│   ├── error.h +│   ├── gradient_machine.h +│   ├── main.h +│   ├── matrix.h +│   ├── paddle_capi.map +│   └── vector.h +├── lib +│   ├── libpaddle_capi_engine.a +│   ├── libpaddle_capi_layers.a +│   ├── libpaddle_capi_shared.so +│   └── libpaddle_capi_whole.a +└── third_party + ├── gflags + │   ├── include + │   │   └── gflags + │   │   ├── gflags_completions.h + │   │   ├── gflags_declare.h + │   │   ... + │   └── lib + │   └── libgflags.a + ├── glog + │   ├── include + │   │   └── glog + │   │   ├── config.h + │   │   ... + │   └── lib + │   └── libglog.a + ├── openblas + │   ├── include + │   │   ├── cblas.h + │   │   ... + │   └── lib + │   ... + ├── protobuf + │   ├── include + │   │   └── google + │   │   └── protobuf + │   │   ... + │   └── lib + │   └── libprotobuf-lite.a + └── zlib + ├── include + │   ... + └── lib + ... + +``` + +### 链接说明 + +目前提供三种链接方式： + +1. 链接`libpaddle_capi_shared.so` 动态库 + - 使用 PaddlePaddle C-API 开发预测程序链接`libpaddle_capi_shared.so`时，需注意： + 1. 如果编译时指定编译CPU版本，且使用`OpenBLAS`数学库，在使用C-API开发预测程序时，只需要链接`libpaddle_capi_shared.so`这一个库。 + 1. 如果是用编译时指定CPU版本，且使用`MKL`数学库，由于`MKL`库有自己独立的动态库文件，在使用PaddlePaddle C-API开发预测程序时，需要自己链接MKL链接库。 + 1. 如果编译时指定编译GPU版本，CUDA相关库会在预测程序运行时动态装载，需要将CUDA相关的库设置到`LD_LIBRARY_PATH`环境变量中。 + - 这种方式最为简便，链接相对容易，**在无特殊需求情况下，推荐使用此方式**。 + +2. 链接静态库 `libpaddle_capi_whole.a` + - 使用PaddlePaddle C-API 开发预测程序链接`libpaddle_capi_whole.a`时，需注意： + 1. 需要指定`-Wl,--whole-archive`链接选项。 + 1. 需要显式地链接 `gflags`、`glog`、`libz`、`protobuf` 等第三方库，可在`PADDLE_ROOT/third_party`下找到。 + 1. 如果在编译 C-API 时使用OpenBLAS数学库，需要显示地链接`libopenblas.a`。 + 1. 如果在编译 C-API 是使用MKL数学库，需要显示地链接MKL的动态库。 + +3. 链接静态库 `libpaddle_capi_layers.a`和`libpaddle_capi_engine.a` + - 使用PaddlePaddle C-API 开发预测程序链接`libpaddle_capi_whole.a`时，需注意： + 1. 这种链接方式主要用于移动端预测。 + 1. 为了减少生成链接库的大小把`libpaddle_capi_whole.a`拆成以上两个静态链接库。 + 1. 需指定`-Wl,--whole-archive -lpaddle_capi_layers` 和 `-Wl,--no-whole-archive -lpaddle_capi_engine` 进行链接。 + 1. 第三方依赖库需要按照与方式2同样方法显示地进行链接。 diff --git a/doc/howto/usage/capi/index_cn.rst b/doc/howto/usage/capi/index_cn.rst index 3b36f31bfd0da37f4a812ab59e96981c4c35a86b..b2822fca2b723abd9a6c2b2e1e69bde36517a6b4 100644 --- a/doc/howto/usage/capi/index_cn.rst +++ b/doc/howto/usage/capi/index_cn.rst @@ -4,6 +4,6 @@ PaddlePaddle C-API .. toctree:: :maxdepth: 1 - compile_paddle_lib.md - organization_of_the_inputs.md - a_simple_example.md + compile_paddle_lib_cn.md + organization_of_the_inputs_cn.md + a_simple_example_cn.md diff --git a/doc/howto/usage/capi/organization_of_the_inputs.md b/doc/howto/usage/capi/organization_of_the_inputs_cn.md similarity index 99% rename from doc/howto/usage/capi/organization_of_the_inputs.md rename to doc/howto/usage/capi/organization_of_the_inputs_cn.md index 7563e236da679a58c0285ca183842af0645c4eab..787af8b0a7646aaef08b63c17c1f89bff2f86935 100644 --- a/doc/howto/usage/capi/organization_of_the_inputs.md +++ b/doc/howto/usage/capi/organization_of_the_inputs_cn.md @@ -260,6 +260,8 @@
+ + ### 输出数据 PaddlePaddle中一个计算层的输出数据组织方式和输入数据组织方式完全相同。一个输出数据同样被组织为一个`argument`，`argument`通过`paddle_matrix`或`paddle_ivector`存数数据，如果输出是一个序列，那么会携带有`sequence_start_positions`信息。调用C-API相关接口，读取需要的结果即可。