add doc for how to use C-API. #6596
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
lcy-seso
force-pushed
the
update_capi_doc
branch
8 times, most recently
from
6426060 to
06c774d
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
from
06c774d to
635a69b
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
10 times, most recently
from
14a921f to
b110b6b
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
6 times, most recently
from
fbebb39 to
d2e9da7
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
2 times, most recently
from
10ad036 to
702743e
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
from
702743e to
b915fde
Compare
luotao1
reviewed
Dec 20, 2017
|
|
||
| ```python | ||
| from paddle.utils.merge_model import merge_v2_model | ||
|
|
| ```c | ||
| // Initalize the PaddlePaddle runtime environment. | ||
| char* argv[] = {"--use_gpu=False"}; | ||
| CHECK(paddle_init(1, (char**)argv)); |
There was a problem hiding this comment.
这里能加个例子说明下，如果初始化参数有两个，应该怎么写么？比如
char* argv[] = {"--use_gpu=False", "--use_mkldnn=True"};
CHECK(paddle_init(2, (char**)argv));
There was a problem hiding this comment.
Done. 这个例子已经补充上了。
这里我感觉其实还需要一个可以传递参数有哪些的列表和说明。我暂时也不太清楚所有可选参数。会再查看一下，补上这部分。
|
|
||
| 每一个 `gradient machine` 都会管理维护一份训练好的模型，模型可以通过以下两种方式获取： | ||
| 1. 从磁盘加载；这时`gradient machine`会独立拥有一份训练好的模型； | ||
| 1. 共享自其它`gradient machine`的模型；这种情况多出现在使用多线程预测时； |
There was a problem hiding this comment.
- 从磁盘加载：（分号改成冒号）
- 共享自其它
gradient machine的模型：（分号改成冒号）
|
|
||
| *注：本文档使用的示例任务手写数字识别不涉及一维整型数组作为输入，因此，本文档仅讨论二维稠密矩阵作为输入的情形。更多输入数据格式请参考输入/输出数据一节的内容。* | ||
|
|
||
| 这篇文档的之后部分会使用`argument`来**特指** PaddlePaddle C-API中神经网的一个输入/输出，使用`paddle_matrix`**特指**`argument`中用于存储数据的`Matrix`类的对象。 |
| 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. 链接`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链接库。 |
There was a problem hiding this comment.
矩阵库，都改成数学库。不仅仅是矩阵运算哈，还有向量等。全文同。
| 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`下找到。 |
There was a problem hiding this comment.
INSTALL_PREFIX/third_party 斜杠方向反了
doc/howto/usage/capi/index_cn.rst
Outdated
|
|
||
| compile_paddle_lib.md | ||
| organization_of_the_inputs.md | ||
| a_simple_example.md |
| </table> | ||
| </html> | ||
| <br> | ||
| ### 输出数据 |
hedaoyuan
reviewed
Dec 20, 2017
| - **注意**：以上两种方式只需选择其一即可。 | ||
| - 调用 PaddlePaddle C-API 开发预测序 | ||
| 1. 初始化PaddlePaddle运行环境。 | ||
| 1. 创建神经网络的输入，组织输入数据。 |
| 运行目录下的 `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 加载训练好的模型进行预测。 | ||
|
|
||
|
|
||
| ### 外部准备 |
| ### 使用流程 | ||
|
|
||
| 使用 C-API 分为：准备工作和预测程序开发两部分。 | ||
| - 准备 |
| #### step 2. 创建神经网络输入，组织输入数据 | ||
|
|
||
| 基本使用概念： | ||
| - 在PaddlePaddle内部，神经网络中一个计算层的输入/输出被组织为一个 `Argument` 结构体，如果神经网络有多个输入或者多个输入，每一个输入/输入都会对应有自己的`Argument`。 |
There was a problem hiding this comment.
多个输入或者多个输入 -> 多个输出
输入/输入 -> 输入/输出
|
|
||
| ### 编写预测代码 | ||
|
|
||
| #### step 1. 初始化及加载模型 |
There was a problem hiding this comment.
初始化及加载模型可以分成两个步骤。加载模型有多种方式，也可以在程序运行过程中再加载另外一个模型。
|
|
||
| 每一个 `gradient machine` 都会管理维护一份训练好的模型，模型可以通过以下两种方式获取： | ||
| 1. 从磁盘加载；这时`gradient machine`会独立拥有一份训练好的模型； | ||
| 1. 共享自其它`gradient machine`的模型；这种情况多出现在使用多线程预测时； |
There was a problem hiding this comment.
...使用多线程预测时，可以通过多个线程共享同一个模型来减少内存开销。
There was a problem hiding this comment.
Done. 已经修改。同时，我把这个tips先加入到注意事项中，暂时没有做更多的解释。不知是否合适。
|
|
||
| ### 使用流程 | ||
|
|
||
| 使用 C-API 分为：准备工作和预测程序开发两部分。 |
There was a problem hiding this comment.
使用 C-API 预测分为：准备预测模型和预测程序开发两部分。
|
|
||
| 这里我们以手写数字识别任务为例，介绍如何使用 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 加载训练好的模型进行预测。 |
There was a problem hiding this comment.
这段话也可以放到准备预测模型里面吧。准备预测模型首先是获得一个训练模型，然后再转换成预测模型。
lcy-seso
commented
Dec 26, 2017
|
|
||
| ### 使用流程 | ||
|
|
||
| 使用 C-API 分为：准备工作和预测程序开发两部分。 |
| ### 使用流程 | ||
|
|
||
| 使用 C-API 分为：准备工作和预测程序开发两部分。 | ||
| - 准备 |
| - **注意**：以上两种方式只需选择其一即可。 | ||
| - 调用 PaddlePaddle C-API 开发预测序 | ||
| 1. 初始化PaddlePaddle运行环境。 | ||
| 1. 创建神经网络的输入，组织输入数据。 |
|
|
||
| 这里我们以手写数字识别任务为例，介绍如何使用 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` 可以使用 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 加载训练好的模型进行预测。 | ||
|
|
||
|
|
||
| ### 外部准备 |
| ├── ...... | ||
| ``` | ||
|
|
||
| ### 链接方式说明 |
| │ ├── 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. 链接`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链接库。 |
There was a problem hiding this comment.
MKL库更多的操作，在这篇文档中我先没有增加更多。后续会考虑补充上（我自己再试一下，之前没有直接的经验，所以先没有增加到文档中）
| 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`下找到。 |
lcy-seso
force-pushed
the
update_capi_doc
branch
3 times, most recently
from
d58bb9a to
f635165
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
from
f635165 to
079b824
Compare
hedaoyuan
reviewed
Dec 26, 2017
| 1. 进行前向计算，获得计算结果。 | ||
| 1. 清理。 | ||
|
|
||
| 本文档以手写数字识别任务为例，介绍如何使用 C-API 进行预测，完整代码请查看[此目录](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/capi/examples/model_inference/dense)。 |
|
|
||
| ### 准备预测模型 | ||
|
|
||
| 通过在终端执行`python mnist_v2.py` |
There was a problem hiding this comment.
通过在终端执行...将图片分类到 0 ~ 9 类别标签之一。 这段话不是特别通顺。可以如下修改：
-> 通过执行python mnist_v2.py，可以训练得到一个手写数字识别模型。
另外，可以把MNIST和模型相关部分的介绍放到本文最开始的地方（最开始那段话也提到了手写数字识别）。
There was a problem hiding this comment.
Done.
这一篇整体的内容也作了一些调整。MNIST和模型相关部分的介绍，也放到按照我自己理解能够移动的最靠前部分。
| ### 准备预测模型 | ||
|
|
||
| 通过在终端执行`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 加载训练好的模型进行预测。 |
There was a problem hiding this comment.
下面，我们将调用 C-API 加载训练好的模型进行预测。 -> 下面，我们将训练好的模型转换成预测模型。
| output_file = "output.paddle.model" | ||
| merge_v2_model(net, param_file, output_file) | ||
| ``` | ||
| 对本例，或者直接运行 `python merge_v2_model.py`，序列化结果将会写入当前目录下的`output.paddle.model`文件中，该文件在调用C-API时，可被直接加载。 |
There was a problem hiding this comment.
或者直接运行 -> 可以直接运行
该文件在调用C-API时，可被直接加载。 -> 使用这种方式，运行时C-API可以通过指定output.paddle.model文件来加载模型。
|
|
||
| 2. 合并模型文件(可选) | ||
|
|
||
| 一些情况下为了便于发布，希望能够将序列化后的神经网络结构和训练好的模型参数打包进一个文件，这时可以使用`paddle.utils.merge_model`中的`merge_v2_model`接口对神经网络结构和训练好的参数进行序列化，将序列化结果写入一个文件内，调用C-API时直接只需加载这一个文件。 |
There was a problem hiding this comment.
直接只需加载 -> 只需加载
将序列化结果写入一个文件内，调用C-API时直接只需加载这一个文件。 -> 将网络序列化结果和模型参数写入一个文件内。后面会讲C-API如何加载。
|
|
||
| 对本例，或运行 `python mnist_v2.py --task dump_config`，会对示例中的网络结构进行序列化，并将结果写入当前目录下的`trainer_config.bin`文件中。 | ||
|
|
||
| 当选择使用这种方式调用 C-API 时，如果神经网络有多个可学习参数，请将它们全部放在同一文件夹内，C-API会从指定的目录寻找并加载训练好的模型。 |
There was a problem hiding this comment.
当选择使用这种方式...训练好的模型 ->
使用这种方式，需要在运行时将神经网络的多个可学习参数放在同一个目录中，C-API可以通过分别指定trainer_config.bin文件和参数目录来加载训练好的模型。
| 对本例，或者直接运行 `python merge_v2_model.py`，序列化结果将会写入当前目录下的`output.paddle.model`文件中，该文件在调用C-API时，可被直接加载。 | ||
|
|
||
| #### 注意事项 | ||
| 1. C-API 需要序列化之后神经网络结构，在调用`dump_v2_config`时，参数`binary`必须指定为`True`。 |
There was a problem hiding this comment.
C-API 需要序列化之后神经网络结构 -> 将训练模型转换成预测模型，需要序列化神经网络结构
| ### 编写预测代码 | ||
|
|
||
| #### step 1. 初始化PaddlePaddle运行环境 | ||
| 使用C-API第一步需首先调用[`paddle_init`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/capi/main.h#L27) 初始化PaddlePaddle运行环境。接口接受两个参数：参数的个数和参数。 |
There was a problem hiding this comment.
第一步需首先调用 -> 第一步需调用
接口接受两个参数：参数的个数和参数 -> 该接口接受两个参数：参数的个数和参数列表
lcy-seso
commented
Jan 8, 2018
| 1. 进行前向计算，获得计算结果。 | ||
| 1. 清理。 | ||
|
|
||
| 本文档以手写数字识别任务为例，介绍如何使用 C-API 进行预测，完整代码请查看[此目录](https://github.com/PaddlePaddle/Paddle/tree/develop/paddle/capi/examples/model_inference/dense)。 |
|
|
||
| ### 准备预测模型 | ||
|
|
||
| 通过在终端执行`python mnist_v2.py` |
There was a problem hiding this comment.
Done.
这一篇整体的内容也作了一些调整。MNIST和模型相关部分的介绍，也放到按照我自己理解能够移动的最靠前部分。
| ### 准备预测模型 | ||
|
|
||
| 通过在终端执行`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 加载训练好的模型进行预测。 |
|
|
||
| 对本例，或运行 `python mnist_v2.py --task dump_config`，会对示例中的网络结构进行序列化，并将结果写入当前目录下的`trainer_config.bin`文件中。 | ||
|
|
||
| 当选择使用这种方式调用 C-API 时，如果神经网络有多个可学习参数，请将它们全部放在同一文件夹内，C-API会从指定的目录寻找并加载训练好的模型。 |
|
|
||
| 2. 合并模型文件(可选) | ||
|
|
||
| 一些情况下为了便于发布，希望能够将序列化后的神经网络结构和训练好的模型参数打包进一个文件，这时可以使用`paddle.utils.merge_model`中的`merge_v2_model`接口对神经网络结构和训练好的参数进行序列化，将序列化结果写入一个文件内，调用C-API时直接只需加载这一个文件。 |
| output_file = "output.paddle.model" | ||
| merge_v2_model(net, param_file, output_file) | ||
| ``` | ||
| 对本例，或者直接运行 `python merge_v2_model.py`，序列化结果将会写入当前目录下的`output.paddle.model`文件中，该文件在调用C-API时，可被直接加载。 |
| 对本例，或者直接运行 `python merge_v2_model.py`，序列化结果将会写入当前目录下的`output.paddle.model`文件中，该文件在调用C-API时，可被直接加载。 | ||
|
|
||
| #### 注意事项 | ||
| 1. C-API 需要序列化之后神经网络结构，在调用`dump_v2_config`时，参数`binary`必须指定为`True`。 |
| ### 编写预测代码 | ||
|
|
||
| #### step 1. 初始化PaddlePaddle运行环境 | ||
| 使用C-API第一步需首先调用[`paddle_init`](https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/capi/main.h#L27) 初始化PaddlePaddle运行环境。接口接受两个参数：参数的个数和参数。 |
lcy-seso
force-pushed
the
update_capi_doc
branch
from
f84cd45 to
ebd4cfe
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
from
ebd4cfe to
4d4df08
Compare
luotao1
reviewed
Jan 8, 2018
doc/howto/usage/capi/index_cn.rst
Outdated
|
|
||
| compile_paddle_lib_cn.md | ||
| organization_of_the_inputs_cn.md | ||
| workflow_of_capi.md |
lcy-seso
force-pushed
the
update_capi_doc
branch
3 times, most recently
from
37670e8 to
476c617
Compare
lcy-seso
force-pushed
the
update_capi_doc
branch
from
476c617 to
a79a5bd
Compare
luotao1
approved these changes
Jan 12, 2018
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
fixes #6527 #6456 #6227 #6178 #4303 #2853 #1949 #1946
related to #6353