From 506e8ad9a037fc91e2cccfb4b35276cbbd900e03 Mon Sep 17 00:00:00 2001 From: cc <52520497+juncaipeng@users.noreply.github.com> Date: Wed, 19 Feb 2020 16:54:03 +0800 Subject: [PATCH] [cherry-pick] add all other docs for release2.3 (#2936) * add docs for cxx demo and java demo, test=develop, test=document_fix (#2932) * [cherry-pick] add all other docs for release2.3 --- .../cuda.md | 0 docs/advanced_user_guides/cv.md | 2 +- docs/advanced_user_guides/debug_tools.md | 54 +++ .../fpga.md | 0 .../opencl.md | 4 +- docs/advanced_user_guides/test_tools.md | 32 ++ docs/advanced_user_guides/x2paddle.md | 44 +++ .../x2paddle_models_doc.md | 22 ++ docs/api_reference/index.rst | 0 docs/benchmark/index.rst | 0 docs/develop_guides/architecture-intro.md | 245 +++++++++++++ docs/develop_guides/for-developer.md | 14 + docs/develop_guides/index.rst | 0 docs/index.rst | 23 +- docs/introduction/faq.md | 4 + docs/introduction/roadmap.md | 27 ++ docs/user_guides/android_ios_app_demo.md | 3 + docs/user_guides/cpp_demo.md | 343 ++++++++++++++++++ docs/user_guides/java_demo.md | 99 +++++ docs/user_guides/paddle_mobile.md | 7 + docs/user_guides/tutorial.md | 55 +++ 21 files changed, 971 insertions(+), 7 deletions(-) rename docs/{user_guides => advanced_user_guides}/cuda.md (100%) create mode 100644 docs/advanced_user_guides/debug_tools.md rename docs/{user_guides => advanced_user_guides}/fpga.md (100%) rename docs/{user_guides => advanced_user_guides}/opencl.md (99%) create mode 100644 docs/advanced_user_guides/test_tools.md create mode 100644 docs/advanced_user_guides/x2paddle.md create mode 100644 docs/advanced_user_guides/x2paddle_models_doc.md delete mode 100644 docs/api_reference/index.rst delete mode 100644 docs/benchmark/index.rst create mode 100644 docs/develop_guides/architecture-intro.md create mode 100644 docs/develop_guides/for-developer.md delete mode 100644 docs/develop_guides/index.rst create mode 100644 docs/introduction/faq.md create mode 100644 docs/introduction/roadmap.md create mode 100644 docs/user_guides/android_ios_app_demo.md create mode 100644 docs/user_guides/cpp_demo.md create mode 100644 docs/user_guides/java_demo.md create mode 100644 docs/user_guides/paddle_mobile.md create mode 100644 docs/user_guides/tutorial.md diff --git a/docs/user_guides/cuda.md b/docs/advanced_user_guides/cuda.md similarity index 100% rename from docs/user_guides/cuda.md rename to docs/advanced_user_guides/cuda.md diff --git a/docs/advanced_user_guides/cv.md b/docs/advanced_user_guides/cv.md index 1f53ac8756..76cf607d5a 100644 --- a/docs/advanced_user_guides/cv.md +++ b/docs/advanced_user_guides/cv.md @@ -1,4 +1,4 @@ -# CV 图像预处理API接口介绍 +# CV图像预处理库 请把编译脚本`Paddle-Lite/lite/too/build.sh`中`BUILD_CV`变量设置为`ON`， 其他编译参数设置请参考[源码编译](../source_compile)， 以确保 Lite 可以正确编译。这样`CV`图像的加速库就会编译进去，且会生成`paddle_image_preprocess.h`的API文件 diff --git a/docs/advanced_user_guides/debug_tools.md b/docs/advanced_user_guides/debug_tools.md new file mode 100644 index 0000000000..d2f775ecaf --- /dev/null +++ b/docs/advanced_user_guides/debug_tools.md @@ -0,0 +1,54 @@ +# 调试方法 + +**Lite Model Debug Tool** 是用来检查Paddle-Lite框架与Paddle-Fluid框架运行时tensor(包括variable与weight)之间diff信息的基础工具。 + +## 编译方法: + +1. 参照 [编译安装](../source_compile) 中的**full_publish**部分进行环境配置和编译。 +2. 在生成的`build`目录下，执行`make lite_model_debug_tool`，`lite_model_debug_tool`产出在编译目录的`lite/tools/debug`目录下。 + +## 工作流程: + +1. 运行 `/bin/bash check_model.sh --model_dir= --build_root_dir= debug_cpp_stage` 获得模型在Paddle-Lite框架下的运行拓扑信息、varibles信息和weights信息。运行后拓扑信息将会存储在默认名为 `topo_file.txt` 的文件中，variables和weights信息将会存储在默认名为 `tensor_cpp.txt` 的文件中。 +2. 运行 `/bin/bash check_model.sh --model_dir= --build_root_dir= debug_py_stage`执行fluid框架预测以获取相同模型在fluid框架下的variable与weight信息(注意：我们使用fluid的python api运行fluid模型，因此您在运行此步之前应确保已正确安装fluid的python api)。然后debug tool将会自动比较Paddle-Lite框架输出的信息和Paddle-Fluid框架输出的信息来检查是否存在运行时diff。 执行Paddle-Fluid框架，输出的信息将会存储在默认名为 `tensor_py.txt` 的文件中，相应的diff信息将会存储在默认名为 `diff.txt`的文件中(默认情况下，只会输出执行拓扑序中第一个有diff的variable相关的信息)。 + +## 注意事项: + +1. 输出的结果是在**执行完一次预测后**输出的相应变量/权重的最终值，因此如果您在预测过程进行过诸如变量复用/子图融合等优化方法，则相应的输出可能会出现偏差。 +2. 默认情况下debug tools将以全1作为输入进行比对。 +3. 默认情况下，为了保证与Paddle-Fluid框架的结果可比对，debug tool将会禁用掉所有的Paddle-Lite的优化策略。 +4. Paddle-Lite框架的执行环境由与您的编译选项有关，比如您开启了LITE_WITH_ARM编译选项，那debug tool的`debug_cpp_stage`也需要在ARM平台下运行。 + +## Diff信息输出： + +如果debug tool检测到diff信息，那么在`diff.txt`中将会输出类似以下结构信息 + +```c++ +>>>>>>>>>>>>>>>>>>DIFF VARIABLE: dropout_0.tmp_0<<<<<<<<<<<<<<<<<<< +dropout (X:pool2d_7.tmp_0) (Mask:dropout_0.tmp_1 Out:dropout_0.tmp_0) +--------------- Tensor File info --------------- +pool2d_7.tmp_0 {1,1536,1,1} 0.749892 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0150336 0.621641 0.147099 0.636727 0.0 0.0 0.00410917 0.784708 0.0 0.0704846 0.233599 0.840123 0.239201 0.112878 0.0 0.155352 0.306906 0.0 0.0 0.860938 0.221037 0.787316 0.256585 ... +dropout_0.tmp_0 {1,1536,1,1} 0.749892 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0150336 0.621641 0.147099 0.636727 0.0 0.0 0.00410917 0.784708 0.0 0.0704846 0.233599 0.840123 0.239201 0.112878 0.0 0.155352 0.306906 0.0 0.0 0.860938 0.221037 0.787316 0.256585 ... +--------------- Fluid Tensor info --------------- +pool2d_7.tmp_0 {1,1536,1,1} 0.7498912 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.015033395 0.6216395 0.14709876 0.63672537 0.0 0.0 0.0041093696 0.7847073 0.0 0.07048465 0.23359808 0.8401219 0.23919891 0.1128789 0.0 0.1553514 0.3069055 0.0 0.0 0.8609365 0.22103554 ... +dropout_0.tmp_0 {1,1536,1,1} 0.599913 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.012026716 0.4973116 0.117679015 0.5093803 0.0 0.0 0.0032874958 0.62776583 0.0 0.056387722 0.18687847 0.67209756 0.19135913 0.090303116 0.0 0.12428112 0.2455244 0.0 0.0 0.68874925 ... +``` + +其中第二行为op相关信息，标明了执行哪个op出现了diff及其对应的输入输出变量名。Tensor File info为Paddle-Lite框架的输出信息，而Fluid Tensor info为Paddle-Fluid框架的相应输出信息。 +示例中的`dropout_0.tmp_1`没有相应的tensor信息是因为工具检测到其在预测的后序流程中未被使用，因此不会对预测结果造成影响，从而将其自动屏蔽掉以保证输出尽量简洁。 + +## 其他选项： + +| Option | Description | +| --------------------------- | ------------------------------------------------------------ | +| --input_file | 输入文件名，不同field以逗号分隔，相同field内以空格分隔, 只有文件中的第一行输入信息会被使用. 如果您不指定input_file，那么所有输入将会被置为1。注意：`debug_py_stage`目前不支持多field输入。 | +| --cpp_topo_file | 存储运行时拓扑信息，由`debug_cpp_stage`写入并且由`debug_py_stage`读取使用。 默认为`topo_file.txt` 。 | +| --cpp_tensor_file | 存储`debug_cpp_stage` 在运行拓扑序下的输出信息，默认为 `tensor_cpp.txt` 。 | +| --tensor_names | 如果此选项不为空，那么只输出由此选项中指定名字的variable/weight信息，名字间用逗号分隔。 | +| --tensor_output_length | 输出数据的长度，默认为全部输出。 | +| --py_threshold | 判断diff发生的阈值，默认为 `1e-5` 。 | +| --py_tensor_file | 存储`debug_py_stage` 在运行拓扑序下的输出信息，默认为`tensor_py.txt`. | +| --py_output_file | diff信息的存储文件，默认为`diff.txt`。 | +| --py_only_output_first_diff | 是否只输出运行时拓扑序中第一个有diff的var/op信息，默认为true | + +您可以参考 `check_model.sh` 脚本中的代码以获得更多细节. diff --git a/docs/user_guides/fpga.md b/docs/advanced_user_guides/fpga.md similarity index 100% rename from docs/user_guides/fpga.md rename to docs/advanced_user_guides/fpga.md diff --git a/docs/user_guides/opencl.md b/docs/advanced_user_guides/opencl.md similarity index 99% rename from docs/user_guides/opencl.md rename to docs/advanced_user_guides/opencl.md index e9533af1ff..b5549b2f97 100644 --- a/docs/user_guides/opencl.md +++ b/docs/advanced_user_guides/opencl.md @@ -1,4 +1,4 @@ -# Lite基于OpenCL的ARM GPU预测 +# Lite基于OpenCL的模型预测 Lite支持在Android系统上运行基于OpenCL的程序，目前支持Ubuntu环境下armv8、armv7的交叉编译。 @@ -230,7 +230,7 @@ adb shell /data/local/tmp/opencl/test_layout_opencl ``` -# 如何在Code中使用 +### 如何在Code中使用 见运行示例1的demo代码: diff --git a/docs/advanced_user_guides/test_tools.md b/docs/advanced_user_guides/test_tools.md new file mode 100644 index 0000000000..4114f333c7 --- /dev/null +++ b/docs/advanced_user_guides/test_tools.md @@ -0,0 +1,32 @@ +# 测试工具 + +Basic profiler 用于 CPU 上kernel 耗时的统计。 + +## 开启方法: + +参照 [编译安装](../source_compile) 中的**full_publish**部分进行环境配置，在 cmake 时添加 `-DLITE_WITH_PROFILER=ON` ，就可以开启相应支持。 + +## 使用示例： + +在模型执行完毕后，会自动打印类似如下 profiler 的日志 + +``` + kernel average min max count + feed/def/1/4/2 0 0 0 1 + conv2d/def/4/1/1 1175 1175 1175 1 + conv2d/def/4/1/1 1253 1253 1253 1 + depthwise_conv2d/def/4/1/1 519 519 519 1 + conv2d/def/4/1/1 721 721 721 1 + elementwise_add/def/4/1/1 18 18 18 1 + conv2d/def/4/1/1 2174 2174 2174 1 + depthwise_conv2d/def/4/1/1 380 380 380 1 + conv2d/def/4/1/1 773 773 773 1 + elementwise_add/def/4/1/1 2 2 2 1 + conv2d/def/4/1/1 1248 1248 1248 1 + depthwise_conv2d/def/4/1/1 492 492 492 1 + conv2d/def/4/1/1 1150 1150 1150 1 + elementwise_add/def/4/1/1 33 33 33 1 + elementwise_add/def/4/1/1 3 3 3 1 + conv2d/def/4/1/1 1254 1254 1254 1 + depthwise_conv2d/def/4/1/1 126 126 126 1 +``` diff --git a/docs/advanced_user_guides/x2paddle.md b/docs/advanced_user_guides/x2paddle.md new file mode 100644 index 0000000000..0dfd65010d --- /dev/null +++ b/docs/advanced_user_guides/x2paddle.md @@ -0,0 +1,44 @@ +# 通过 X2Paddle 转换模型 + +[X2Paddle](https://github.com/PaddlePaddle/X2Paddle)支持将Caffe/TensorFlow模型转换为PaddlePaddle模型。目前X2Paddle支持的模型参考[x2paddle_model_zoo](https://github.com/PaddlePaddle/X2Paddle/blob/develop/x2paddle_model_zoo.md)。 + +## 安装 + +``` +pip install x2paddle +``` + +安装最新版本，可使用如下安装方式 + +``` +pip install git+https://github.com/PaddlePaddle/X2Paddle.git@develop +``` + +## 使用 + +### Caffe + +``` +x2paddle --framework caffe \ + --prototxt model.proto \ + --weight model.caffemodel \ + --save_dir paddle_model +``` + +### TensorFlow + +``` +x2paddle --framework tensorflow \ + --model model.pb \ + --save_dir paddle_model +``` + +## 转换结果说明 + +在指定的`save_dir`下生成两个目录 +1. inference_model : 模型结构和参数均序列化保存的模型格式 +2. model_with_code : 保存了模型参数文件和模型的python代码 + +## 问题反馈 + +X2Paddle使用时存在问题时，欢迎您将问题或Bug报告以[Github Issues](https://github.com/PaddlePaddle/X2Paddle/issues)的形式提交给我们，我们会实时跟进。 diff --git a/docs/advanced_user_guides/x2paddle_models_doc.md b/docs/advanced_user_guides/x2paddle_models_doc.md new file mode 100644 index 0000000000..54b5f316cd --- /dev/null +++ b/docs/advanced_user_guides/x2paddle_models_doc.md @@ -0,0 +1,22 @@ +# X2Paddle 支持模型列表 + +## 多框架支持 + +|模型 | caffe | tensorflow | onnx | +|---|---|---|---| +|mobilenetv1 | Y | Y | | +|mobilenetv2 | Y | Y | Y | +|resnet18 | Y | Y | | +|resnet50 | Y | Y | Y | +|mnasnet | Y | Y | | +|efficientnet | Y | Y | Y | +|squeezenetv1.1 | Y | Y | Y | +|shufflenet | Y | Y | | +|mobilenet_ssd | Y | Y | | +|mobilenet_yolov3 | | Y | | +|inceptionv4 | | | | +|mtcnn | Y | Y | | +|facedetection | Y | | | +|unet | Y | Y | | +|ocr_attention | | | | +|vgg16 | | | | diff --git a/docs/api_reference/index.rst b/docs/api_reference/index.rst deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/benchmark/index.rst b/docs/benchmark/index.rst deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/develop_guides/architecture-intro.md b/docs/develop_guides/architecture-intro.md new file mode 100644 index 0000000000..f49f0525e1 --- /dev/null +++ b/docs/develop_guides/architecture-intro.md @@ -0,0 +1,245 @@ +# 架构详解 + +这篇文档会从开发者角度详细介绍开发 Paddle-Lite 需要的相关信息。 + +## 设计及思考 + +近年来，各种深度学习预估硬件称出不穷，从手机APP到车载设备，再到音箱，均需要部署深度学习预测，且有如下共性需求： + +1. 高性能 +2. 硬件支持和扩展容易 +3. 轻量级部署 + +Paddle-Lite 的架构方面便是定向参考如上需求设计实现的，具体地 + +- 高性能方面 + - 通过 MIR(Machine IR) 实现精细复杂的计算图的分析和优化 + - 执行期 Kernel 的简单设计，几乎没有额外调度开销 + - 适当的硬件层抽象，框架支持各个硬件后端中做特定的调度实现 +- 轻量级部署方面 + - 拆分分析和执行两个阶段，执行阶段轻量级实现，可以单独部署 + - 轻量级 Op 和 Kernel 设计 +- 硬件支持和扩展方面 + - 通过 MIR 支撑带硬件和执行信息的宏观分析优化 + - TypeSystem 抽象带硬件的不同计算模式的表示，实现整个计算图的强类型推导，以及执行状态机的静态分析 + +Paddle-Lite 的架构尝试从强类型推导的角度建模支持多硬件，多种计算模式（不同量化精度、不同的 data layout等）的混合计算，从而实现宏观上的各异硬件和计算模式的混合。 + +框架部分已经经过 FPGA，GPU，NPU 等异构硬件的打磨，各项能力也在完善中。 + +## 重要模块介绍 + +### OpLite + +[OpLite](https://github.com/PaddlePaddle/Paddle-Lite/blob/v2.0.0-beta1-prerel/lite/core/op_lite.h#L52) 是 Paddle-Lite 中的 Operator，用户扩展单个硬件时，最多的就是扩展 Op 和 Kernel。 + +重要方法如下： + +```c++ +class OpLite : public Registry { + public: + // Check the shape. + virtual bool CheckShape() const { return true; } + // Inference the outputs' shape. + virtual bool InferShape() const { return true; } + // Link the external execution environ to internal context. + bool AttachImpl(const cpp::OpDesc &opdesc, lite::Scope *scope); +}; +``` + +其中，分析期执行 + +- `AttachImpl` + +执行期执行 + +- `CheckShape` +- `InferShape` + +扩展须知： + +1. `CheckShape` 只在第一个 batch 执行，所以耗时不敏感 + +2. `InferShape` 需要在每个 batch 执行，应该严格耗时 + + 1. 可以通过添加 member variable 的方式，对其中一部分信息增加 cache，比如 + + ```c++ + class XXOp : public OpLite { + void InferShape() { + int batch_size = param().input.shape[0]; + if (!shape_cache_.empty()) { + shape_cache_[0] = batch_size; + param().output->Resize(shape_cache_); + } + } + + private: + shape_t shape_cache_; + } + ``` + + + +### OpParam + +[OpParam](https://github.com/PaddlePaddle/Paddle-Lite/blob/v2.0.0-beta1-prerel/lite/operators/op_params.h) 用于存储执行期 Kernel 需要的各项参数。 所有字段可以直接存储（比如指针或者 `int`），以避免执行中获取参数的延迟。 + +因为没有需求，OpParam 暂时没有设置基类。 + +实际例子： + +```c++ +// For Softmax op +struct SoftmaxParam { + lite::Tensor* x{}; + lite::Tensor* output{}; + int axis{-1}; +}; +``` + +OpLite 的 `AttachImpl` 方法就用于构建 `OpParam` ，复制传递给 `Kernel` 用于执行。 + +OpParam 是执行期的重要模块，需要严格保证性能，相应的扩展要求： + +1. 字段的获取必须是低延迟的，可以直接用指针，或者直接复制值 +2. 避免执行无关信息混入，包括 debug 信息 +3. 命名需要与 Paddle OpDesc 中的信息严格一致，以降低功能对齐和理解的难度 + +### Kernel + +```c++ +template +class KernelLite : public KernelBase { + public: + // Run the kernel. + virtual void Run() { CHECK(false) << "Not Implemented"; } + + TargetType target() const override { return Target; } + PrecisionType precision() const override { return Precision; } + DataLayoutType layout() const override { return DataLayout; } + Place place() const override { return Place{Target, Precision, DataLayout}; } + std::string name() const override; +}; +``` + +由于是执行期的重要概念，因此 Kernel 设计地非常简单高效。 + +其中，执行期的 `Run` 是其唯一重要的接口，其中包含具体的计算逻辑。 + +模板中的参数主要用于方便多硬件编译，以及自解释： + +- Target: 执行硬件 +- Precision: 主要的计算精度 +- DataLayout：主要计算的 data layout + +这部分信息用于帮助挑选 kernel，具体的值并不严格。 + + + +Kernel 的注册需要用到 TypeSystem，不光对 Kernel 本身的特性进行描述，对其输入和输出均进行详尽的定义。 + +例如 FullyConnected 的注册 + +```c++ +REGISTER_LITE_KERNEL( + fc, kARM, kFloat, kNCHW, paddle::lite::kernels::arm::FcCompute, def) + .BindInput("Input", {LiteType::GetTensorTy(TARGET(kARM), PRECISION(kFloat), LAYOUT(kNCHW))}) + .BindInput("Bias", {LiteType::GetTensorTy(TARGET(kARM))}) + .BindInput("W", {LiteType::GetTensorTy(TARGET(kARM))}) + .BindOutput("Out", {LiteType::GetTensorTy(TARGET(kARM))}) + .Finalize(); +``` + +Kernel自身定义是 `kARM` 的，也就是ARM上的kernel，主要的计算精度是 `kFloat`，主要的 Data layout 是 `kNCHW`。 + +接着会对其所有的输入和输出做详细定义，比如看 `Input` 输入的定义是 `LiteType::GetTensorTy(TARGET(kARM), PRECISION(kFloat), LAYOUT(kNCHW))`，也就是声明其 Target 是 `kARM`， PRECISION 是 `kFloat`，Data Layout 是 `kNCHW`。 + +这里的设计思想是类似C++中的函数重载，同一个 Kernel（的名字），在重载了其输入输出的类型之后可以是不同的kernel。 + +#### 扩展须知 + +1. 模板参数选用计算中主要的来表示 + 1. 比如，scale kernel，同时能接受 `float` 和 `int` 的输入，但其不算量化 kernel，那应该设置为 `Precision=float`，代表常规的计算精度中使用 +2. Kernel 输入输出的定义需要足够精确，是什么类型就是什么类型；框架会根据其输入输出的定义来动态构建状态机，否则会出现分析期和执行期的状态机不一致，造成未定义行为 + +### MIR + +MIR 类似于 LLVM 里的 IR，只是加上了硬件和执行期的信息参与分析优化。 + +Pass 是MIR中的模块化策略，其输入和输出都是 SSA Graph. + +框架会自动基于模型的Program 构建 SSA Graph，之后按 [Optimizer](https://github.com/PaddlePaddle/Paddle-Lite/blob/v2.0.0-beta1-prerel/lite/core/optimizer.h) 中定义的pass的顺序调用一系列 Pass。 + +#### Op Fusion + +MIR 中的 [PatternMacher](https://github.com/PaddlePaddle/Paddle-Lite/blob/v2.0.0-beta1-prerel/lite/core/mir/pattern_matcher.h) 实现了简单有效的基于图的模板识别的算法，相关的 op fusion 的图操作可以基于此实现。 + +实际的例子可以参考 [fc_fuse_pass.h](https://github.com/PaddlePaddle/Paddle-Lite/blob/v2.0.0-beta1-prerel/lite/core/mir/fusion/fc_fuse_pass.h)。 + +### TypeSystem + +TypeSystem 是 Paddle-Lite 中构建复杂计算图的基础模块，核心思想是协助 SSA Graph 构建一个状态机，表示其中不同的状态。 + +这里的 Type 主要包含下面四组信息，更多的信息可以按需扩展： + +- TargetType +- Precision +- DataLayout +- device id，用于表示卡号 + + + +状态机的表示： + +```python +Tensor0(kARM, kFloat, kNCHW) --pass--> Tensor1(kOpenCL, kFloat, kNCHW) +``` + +MIR 会识别出，Tensor0 和 Tensor1 的硬件位置不同，因此触发相依的 Pass 插入对应的 cast op 来进行 type cast，比如 + +``` +Tensor0(kARM, kFloat, kNCHW) --pass-> IoCopyOp(kARM, kOpenCL) --pass-> Tensor1(kOpenCL, kFloat, kNCHW) +``` + +### KernelContext + +KernelContext 是硬件支持的核心封装，主要用于为 Kernel 提供执行期的硬件上下文。 + +KernelContext 的设计类似于 OpParam，两者均没有基类；对于 KernelContext，其假定是，不同的硬件间的接口和逻辑可能完全不同，比如 kARM 和 kCUDA，因此不设定基类，也不需要提供统一的接口来封装不同硬件行为。 + +不同硬件的 KernelContext 直接与该硬件对应的 Kernel 对接。 + +KernelContext 的行为可以被 MIR 在分析期确定和调度。 + +注意事项： + +1. 由于是执行期概念，KernelContext 也需要注意性能和轻量化 +2. 移动端部署时只会部署执行期，因此 MIR 和 KernelContext 会拆开，因此 KernelContext 相应的设置需要能够序列化到 ProgramDesc 中，以便执行期载入和执行 + +## 扩展硬件后端 + +### 扩展现有的硬件后端 + +主要是扩充 Op 和 Kernel 的工作，如果需要 fuse，则参考 MIR 章节，增加相应的fuse pass便可，具体地，可以参考 + +- [fc_op](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/operators/fc_op.h) 实现类似的 Op +- [fc_compute](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/kernels/arm/fc_compute.h) 实现类似的 Kernel +- [fc_fuse_pass](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/core/mir/fusion/fc_fuse_pass.h) 实现fuse逻辑，并注册到 [optimizer](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/core/optimizer.h) + +### 扩展全新硬件后端 + +需要额外扩充如下模块，让框架能够支撑硬件执行： + +- TypeSystem，需要扩充其中相关的 type + - 相关 [enum](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/api/paddle_place.h#L44) +- MIR，需要扩展其中的 type cast 相关的 pass + - [TargetType cast pass](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/core/mir/type_target_cast_pass.cc) 用于拷贝不同硬件上的tensor + - [Data layout cast pass](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/core/mir/type_target_cast_pass.h) 用于转化不同的 data layout + - [Precision cast pass](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/core/mir/type_precision_cast_pass.h) 用于转化不同 tensor 的量化精度 +- KernelContext，具体地可以参考 + - [ARM context](https://github.com/PaddlePaddle/Paddle-Lite/blob/release/v2.0.0-beta1/lite/core/context.h#L91) + - 需要注意的是，硬件 context 的接口只服务于该硬件的 kernel + - context 有分析期和执行期两个阶段，如果分析期没有特殊的优化，则无需考虑；否则，需要注意将分析期的信息整理并序列化到离线模型中，用于执行期直接加载。 diff --git a/docs/develop_guides/for-developer.md b/docs/develop_guides/for-developer.md new file mode 100644 index 0000000000..fc7bd412ee --- /dev/null +++ b/docs/develop_guides/for-developer.md @@ -0,0 +1,14 @@ +# 开发基础须知 + +可以参考 [Paddle 开发者文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/1.5/advanced_usage/development/contribute_to_paddle/local_dev_guide.html)。 + +## 提交PR + +需要在 commit message 里加上 `test=develop` 才能触发 CI + +## 版本发布检查清单 + +1. 所有 feature 梳理，确认状态 +2. 所有 QA 测试结果梳理，确认版本可靠 +3. Release note 确认 review 通过 +4. 确认需要 release 的 binary 编译完毕 diff --git a/docs/develop_guides/index.rst b/docs/develop_guides/index.rst deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/index.rst b/docs/index.rst index f927e368d2..1c16fcf542 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Welcome to Paddle-Lite's documentation! introduction/tech_highlights introduction/architecture introduction/support_hardware + introduction/roadmap .. toctree:: :maxdepth: 1 @@ -35,21 +36,30 @@ Welcome to Paddle-Lite's documentation! :caption: 使用指南 :name: sec-user-guides + user_guides/tutorial user_guides/model_optimize_tool + user_guides/cpp_demo + user_guides/java_demo + user_guides/android_ios_app_demo user_guides/library_tailoring - user_guides/cuda - user_guides/fpga - user_guides/opencl .. toctree:: :maxdepth: 1 :caption: 进阶使用指南 + advanced_user_guides/x2paddle + advanced_user_guides/x2paddle_models_doc + advanced_user_guides/model_quantization advanced_user_guides/support_operation_list advanced_user_guides/add_operation advanced_user_guides/add_layout - advanced_user_guides/model_quantization advanced_user_guides/add_new_pass + advanced_user_guides/test_tools + advanced_user_guides/debug_tools + advanced_user_guides/npu + advanced_user_guides/opencl + advanced_user_guides/fpga + advanced_user_guides/cuda advanced_user_guides/x86 advanced_user_guides/cv @@ -57,6 +67,9 @@ Welcome to Paddle-Lite's documentation! :maxdepth: 1 :caption: 开发者文档 + develop_guides/for-developer + develop_guides/architecture-intro + .. toctree:: :maxdepth: 1 :caption: API文档 @@ -67,6 +80,8 @@ Welcome to Paddle-Lite's documentation! :maxdepth: 1 :caption: FAQ + introduction/faq + .. toctree:: :maxdepth: 1 :caption: paddle-mobile diff --git a/docs/introduction/faq.md b/docs/introduction/faq.md new file mode 100644 index 0000000000..b16aad65b4 --- /dev/null +++ b/docs/introduction/faq.md @@ -0,0 +1,4 @@ +# FAQ + +问题或建议可以发Issue，为加快问题解决效率，可先检索是否有类似问题，我们也会及时解答！ +欢迎加入Paddle-Lite百度官方QQ群：696965088 diff --git a/docs/introduction/roadmap.md b/docs/introduction/roadmap.md new file mode 100644 index 0000000000..6def1502ba --- /dev/null +++ b/docs/introduction/roadmap.md @@ -0,0 +1,27 @@ +# Road map + +这篇文档会介绍 Paddle-Lite 近期对外的开源版本和计划。 + +其中包含的 feature 为最小集合，按最终发布的版本为准。 + + +## 2.0.0-beta1-prerelease + +预计发布 *2019-8-26 ~ 2days* + +- 完善编译和 benchmark 文档 +- 增加第三方依赖代码的离线下载功能，加速编译过程 +- 去掉 `tiny_publish` 模式下无关的第三方代码下载，可以不依赖任何第三方 + +## 2.0.0-beta1 + +预计发布 *2019-9-1~2days* + +- `model_optimize_tool` 从 ARM 上执行修改为 Host 上执行，只从 kernel 分布来确定计算图优化；后续硬件针对优化会发布新的工具； +- Paddle 模型支持参数 composed 的格式 +- 增加分层编译来控制常用模型的部署库的大小，分两个模式 `basic`, `extra`；默认 `basic` 模式只发布核心的op 和kernel；将控制流相关的Op和kernel 折叠进 `extra` 按需编译 +- 增加 INT8 量化，从 PaddleSlim 训练到 PaddleLite 部署完整案例 +- 支持内存中加载模型，以支持 APP 的简易加密 + +## 2.0.0-rc ? +预计发布 *2019-9-16~7days* diff --git a/docs/user_guides/android_ios_app_demo.md b/docs/user_guides/android_ios_app_demo.md new file mode 100644 index 0000000000..49ddf51b39 --- /dev/null +++ b/docs/user_guides/android_ios_app_demo.md @@ -0,0 +1,3 @@ +# Android/IOS APP demo + +请参考[Paddle-Lite-Demo](https://github.com/PaddlePaddle/Paddle-Lite-Demo)。 diff --git a/docs/user_guides/cpp_demo.md b/docs/user_guides/cpp_demo.md new file mode 100644 index 0000000000..a915a3f05e --- /dev/null +++ b/docs/user_guides/cpp_demo.md @@ -0,0 +1,343 @@ +# C++ Demo + +## 编译 + +首先按照[PaddleLite 源码编译](https://github.com/PaddlePaddle/Paddle-Lite/wiki/source_compile)准备交叉编译环境，之后拉取最新[PaddleLite release发布版代码](https://github.com/PaddlePaddle/Paddle-Lite)。下面以Android-ARMv8架构为例，介绍编译过程，并最终在手机上跑通MobilNetv1模型。 + +进入 Paddle-Lite 目录，运行以下命令编译代码（**需加编译选项`--build_extra=ON`确保完整编译**）： + +``` +./lite/tools/build.sh \ + --arm_os=android \ + --arm_abi=armv8 \ + --arm_lang=gcc \ + --android_stl=c++_static \ + --build_extra=ON \ + full_publish +``` + +编译完成后 `./build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/` 文件夹下包含： + +- cxx + - include (头文件文件夹) + - lib (库文件文件夹) + - libpaddle_api_full_bundled.a + - libpaddle_api_light_bundled.a + - libpaddle_light_api_shared.so + - libpaddle_full_api_shared.so +- demo + - cxx （C++ demo） + - mobile_light (light api demo) + - mobile_full (full api demo) + - mobile_detection (detection model api demo) + - mobile_classify (classify model api demo) + - Makefile.def + - include +- third_party （第三方库文件夹） + - gflags + +## 准备执行环境 + +执行环境有两种：使用安卓手机；若没安卓手机，也可在安卓模拟器中执行。 + +### 环境一：使用安卓手机 + +将手机连上电脑，在手机上打开选项 -> 开启-开发者模式 -> 开启-USB调试模式。确保 `adb devices` 能够看到相应的设备。 + +### 环境二：使用安卓模拟器 + +运行下面命令，分别创建安卓armv8、armv7架构的模拟器。若需在真机测试，将模拟器换成相应架构的真机环境即可。 + +``` +*android-armv8* +adb kill-server +adb devices | grep emulator | cut -f1 | while read line; do adb -s $line emu kill; done +echo n | avdmanager create avd -f -n paddle-armv8 -k "system-images;android-24;google_apis;arm64-v8a" +echo -ne '\n' | ${ANDROID_HOME}/emulator/emulator -avd paddle-armv8 -noaudio -no-window -gpu off -port 5554 & +sleep 1m +``` + +``` +*android-armv7* +adb kill-server +adb devices | grep emulator | cut -f1 | while read line; do adb -s $line emu kill; done +echo n | avdmanager create avd -f -n paddle-armv7 -k "system-images;android-24;google_apis;armeabi-v7a" +echo -ne '\n' | ${ANDROID_HOME}/emulator/emulator -avd paddle-armv7 -noaudio -no-window -gpu off -port 5554 & +sleep 1m +``` + +## 下载模型并运行示例 + +``` +cd inference_lite_lib.android.armv8/demo/cxx/mobile_full +wget http://paddle-inference-dist.bj.bcebos.com/mobilenet_v1.tar.gz +tar zxvf mobilenet_v1.tar.gz + +make + +adb push mobilenet_v1 /data/local/tmp/ +adb push mobilenetv1_full_api /data/local/tmp/ +adb shell chmod +x /data/local/tmp/mobilenetv1_full_api +adb shell "/data/local/tmp/mobilenetv1_full_api --model_dir=/data/local/tmp/mobilenet_v1 --optimized_model_dir=/data/local/tmp/mobilenet_v1.opt" +``` + +注：我们也提供了轻量级 API 的 demo、图像分类demo和目标检测demo，支持图像输入； + +### Light API Demo + +``` +cd ../mobile_light +make +adb push mobilenetv1_light_api /data/local/tmp/ +adb shell chmod +x /data/local/tmp/mobilenetv1_light_api +adb shell "/data/local/tmp/mobilenetv1_light_api --model_dir=/data/local/tmp/mobilenet_v1.opt " +``` + + +### 图像分类 Demo + +``` +cd ../mobile_classify +wget http://paddle-inference-dist.bj.bcebos.com/mobilenet_v1.tar.gz +tar zxvf mobilenet_v1.tar.gz +make +adb push mobile_classify /data/local/tmp/ +adb push test.jpg /data/local/tmp/ +adb push labels.txt /data/local/tmp/ +adb push ../../../cxx/lib/libpaddle_light_api_shared.so /data/local/tmp/ +adb shell chmod +x /data/local/tmp/mobile_classify +adb shell "export LD_LIBRARY_PATH=/data/local/tmp/:$LD_LIBRARY_PATH && /data/local/tmp/mobile_classify /data/local/tmp/mobilenet_v1.opt /data/local/tmp/test.jpg /data/local/tmp/labels.txt" +``` + +### 目标检测 Demo + +``` +cd ../mobile_detection +wget https://paddle-inference-dist.bj.bcebos.com/mobilenetv1-ssd.tar.gz +tar zxvf mobilenetv1-ssd.tar.gz +make +adb push mobile_detection /data/local/tmp/ +adb push test.jpg /data/local/tmp/ +adb push ../../../cxx/lib/libpaddle_light_api_shared.so /data/local/tmp/ +adb shell chmod +x /data/local/tmp/mobile_detection +adb shell "export LD_LIBRARY_PATH=/data/local/tmp/:$LD_LIBRARY_PATH && /data/local/tmp/mobile_detection /data/local/tmp/mobilenetv1-ssd /data/local/tmp/test.jpg" +adb pull /data/local/tmp/test_detection_result.jpg ./ +``` + +## Demo 程序运行结果 + +### light API Demo 运行结果 + +运行成功后 ，将在控制台输出预测结果的前10个类别的预测概率： + +``` +Output dim: 1000 +Output[0]: 0.000191 +Output[100]: 0.000160 +Output[200]: 0.000264 +Output[300]: 0.000211 +Output[400]: 0.001032 +Output[500]: 0.000110 +Output[600]: 0.004829 +Output[700]: 0.001845 +Output[800]: 0.000202 +Output[900]: 0.000586 +``` + +### 图像分类 Demo 运行结果 + +运行成功后 ，将在控制台输出预测结果的前5个类别的类型索引、名字和预测概率： + +``` +parameter: model_dir, image_path and label_file are necessary +parameter: topk, input_width, input_height, are optional +i: 0, index: 285, name: Egyptian cat, score: 0.482870 +i: 1, index: 281, name: tabby, tabby cat, score: 0.471593 +i: 2, index: 282, name: tiger cat, score: 0.039779 +i: 3, index: 287, name: lynx, catamount, score: 0.002430 +i: 4, index: 722, name: ping-pong ball, score: 0.000508 +``` + +### 目标检测 Demo 运行结果 + +运行成功后 ，将在控制台输出检测目标的类型、预测概率和坐标： + +``` +running result: +detection image size: 935, 1241, detect object: person, score: 0.996098, location: x=187, y=43, width=540, height=592 +detection image size: 935, 1241, detect object: person, score: 0.935293, location: x=123, y=639, width=579, height=597 +``` + +## 如何在代码中使用 API + +在C++中使用PaddleLite API非常简单，不需要添加太多额外代码，具体步骤如下： + +- 加入头文件引用 + +``` + #include + #include + #include "paddle_api.h" + #include "paddle_use_kernels.h" + #include "paddle_use_ops.h" + #include "paddle_use_passes.h" +``` + +- 通过MobileConfig设置：模型文件位置（model_dir）、线程数（thread）和能耗模式( power mode )。输入数据（input），从 MobileConfig 创建 PaddlePredictor 并执行预测。 （注：Lite还支持从memory直接加载模型，可以通过MobileConfig::set_model_buffer方法实现） + +代码示例： + +``` +// 1. Create MobileConfig +MobileConfig config; + +// 2. Load model +config.set_model_dir("path to your model directory"); // model dir +/*load model: Lite supports loading model from file or from memory (naive buffer from optimized model) +//Method One: Load model from memory: +void set_model_buffer(const char* model_buffer, + size_t model_buffer_size, + const char* param_buffer, + size_t param_buffer_size) +//Method Two: Load model from file: +void set_model_dir(const std::string& model_dir) */ + +// 3. Set MobileConfig (or you can skip this step to use default value): +config.set_power_mode(LITE_POWER_HIGH); // power mode +/*power modes: Lite supports the following power modes + LITE_POWER_HIGH + LITE_POWER_LOW + LITE_POWER_FULL + LITE_POWER_NO_BIND + LITE_POWER_RAND_HIGH + LITE_POWER_RAND_LOW */ +config.set_threads("num of threads"); // threads + +// 4. Create PaddlePredictor by MobileConfig +std::shared_ptr predictor = + CreatePaddlePredictor(config); + +// 5. Prepare input data +std::unique_ptr input_tensor(std::move(predictor->GetInput(0))); +input_tensor->Resize({1, 3, 224, 224}); +auto *data = input_tensor -> mutable_data(); +for (int i = 0; i < ShapeProduction(input_tensor->shape()); ++i) { + data[i] = 1; +} + +// 6. Run predictor +predictor->Run(); + +// 7. Get output +std::unique_ptr output_tensor(std::move(predictor->GetOutput(0))); +``` + +## CxxConfig案例: OCR_model的运行 + +1. OCR 模型文件： + - 我们提供Pb格式的[ocr_attention_mode](https://paddle-inference-dist.cdn.bcebos.com/ocr_attention.tar.gz)l下载 + - 也可以从[Paddle/model项目](https://github.com/PaddlePaddle/models/tree/develop/PaddleCV/ocr_recognition)中训练出模型 +2. 示例代码： + + +``` +#include "paddle_api.h" // NOLINT +#include "paddle_use_passes.h" // NOLINT +#include +#include +#include +using namespace paddle::lite_api; // NOLINT + +DEFINE_string(model_dir, "", "Model dir path."); +DEFINE_bool(prefer_int8_kernel, false, "Prefer to run model with int8 kernels"); + +int64_t ShapeProduction(const shape_t &shape) { + int64_t res = 1; + for (auto i : shape) + res *= i; + return res; +} + +void RunModel() { + // 1. Set CxxConfig + CxxConfig config; + config.set_model_dir(FLAGS_model_dir); + std::vector valid_places({Place{TARGET(kARM), PRECISION(kFloat)}}); + if (FLAGS_prefer_int8_kernel) { + valid_places.insert(valid_places.begin(), + Place{TARGET(kARM), PRECISION(kInt8)}); + } + config.set_valid_places(valid_places); + + // 2. Create PaddlePredictor by CxxConfig + std::shared_ptr predictor = + CreatePaddlePredictor(config); + + // 3. Prepare input data + // input 0 + std::unique_ptr input_tensor(std::move(predictor->GetInput(0))); + input_tensor->Resize(shape_t({1, 1, 48, 512})); + auto *data = input_tensor->mutable_data(); + for (int i = 0; i < ShapeProduction(input_tensor->shape()); ++i) { + data[i] = 1; + } + // input1 + std::unique_ptr init_ids(std::move(predictor->GetInput(1))); + init_ids->Resize(shape_t({1, 1})); + auto *data_ids = init_ids->mutable_data(); + for (int i = 0; i < ShapeProduction(init_ids->shape()); ++i) { + data_ids[i] = 0; + } + + lod_t lod_i; + lod_i.push_back({0, 1}); + lod_i.push_back({0, 1}); + init_ids->SetLoD(lod_i); + // input2 + std::unique_ptr init_scores(std::move(predictor->GetInput(2))); + init_scores->Resize(shape_t({1, 1})); + auto *data_scores = init_scores->mutable_data(); + for (int i = 0; i < ShapeProduction(init_scores->shape()); ++i) { + data_scores[i] = 0; + } + lod_t lod_s; + lod_s.push_back({0, 1}); + lod_s.push_back({0, 1}); + init_scores->SetLoD(lod_s); + + // 4. Run predictor + predictor->Run(); + + // 5. Get output + std::unique_ptr output_tensor( + std::move(predictor->GetOutput(0))); + for (int i = 0; i < ShapeProduction(output_tensor->shape()); i++) { + printf("Output[%d]: %f\n", i, output_tensor->data()[i]); + } +} + +int main(int argc, char **argv) { + google::ParseCommandLineFlags(&argc, &argv, true); + RunModel(); + return 0; +} +``` + +3. 运行方法： + 参考以上代码编译出可执行文件`OCR_DEMO`，模型文件夹为`ocr_attention`。手机以USB调试、文件传输模式连接电脑。 +``` +简单编译出`OCR_DEMO`的方法：用以上示例代码替换编译结果中`build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/demo/cxx/mobile_full/mobilenetv1_full_api.cc`文件的内容，终端进入该路径（`demo/cxx/mobile_full/`），终端中执行`make && mv mobilenetv1_full_api OCR_DEMO`即编译出了OCR模型的可执行文件`OCR_DEMO` +``` + 在终端中输入以下命令执行OCR model测试： + +``` +#OCR_DEMO为编译出的可执行文件名称；ocr_attention为ocr_attention模型的文件夹名称；libpaddle_full_api_shared.so是编译出的动态库文件，位于`build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/cxx/lib` +adb push OCR_DEMO /data/local/tmp +adb push ocr_attention /data/local/tmp +adb push libpaddle_full_api_shared.so /data/local/tmp/ +adb shell 'export LD_LIBRARY_PATH=/data/local/tmp/:$LD_LIBRARY_PATH && cd /data/local/tmp && ./OCR_DEMO --model_dir=./OCR_DEMO' +``` + +4. 运行结果 + + diff --git a/docs/user_guides/java_demo.md b/docs/user_guides/java_demo.md new file mode 100644 index 0000000000..4a09826cd4 --- /dev/null +++ b/docs/user_guides/java_demo.md @@ -0,0 +1,99 @@ +# Java Demo + +本节中，Java demo 完整代码位于 [demo/java](https://github.com/PaddlePaddle/Paddle-Lite/tree/develop/lite/demo/java) 。 + +要编译和跑起Android demo 程序 PaddlePredictor，你需要准备： + +1. 一台能运行安卓程序的安卓手机 +2. 一台带有AndroidStudio的开发机 + +## 编译 + +首先在PaddleLite的开发 [Docker镜像](../source_compile) 中，拉取最新PaddleLite代码，编译对应你手机架构的预测库， +下面我们以arm8 架构举例。进入paddlelite 目录，运行以下命令： + +```shell +./lite/tools/build.sh \ + --arm_os=android \ + --arm_abi=armv8 \ + --arm_lang=gcc \ + --android_stl=c++_static \ + tiny_publish +``` + +命令完成后查看要存在 + +``` +./build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/java/so/libpaddle_lite_jni.so +./build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/java/jar/PaddlePredictor.jar +./build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/demo/java/android +``` + +libpaddle_lite_jni.so为 PaddleLite c++ 动态链接库，PaddlePredictor.jar为 Java jar 包，两者包含 PaddleLite Java API，接下来 Android Java 代码会使用这些api。android文件夹中则是Android demo。 + +## 准备 demo 需要的其他文件 + +Demo 除了代码，还需要准备在Android工程目录下配置好JNI .so 库（上节提到的`libpaddle_lite_jni.so`），Java .jar 包（上文提到的`PaddlePredictor.jar` ），和模型文件。我们提供了自动化的脚本和手动拷贝两种方法，用户可以根据自己需要选择： + +### 脚本方法 + +进入 `build.lite.android.armv8.gcc/inference_lite_lib.android.armv8/demo/java/android`，我们准备了一个脚本`prepare_demo.bash`，脚本输入一个参数，为你要拷贝的.so 对应的架构文件夹名。 + +例如运行 + +``` +bash prepare_demo.bash arm8 +``` + +该脚本自动下载并解压缩模型文件，拷贝了 .jar 包进demo，还有生成的.so包进`PaddlePredictor/app/src/main/jinLibs/架构文件夹下`， +在我们这个例子里，armv8 就是架构文件夹。备注：这种方式构建的 demo 在 armv8 手机运行正常。如果要demo 程序在别的手机架构（如 armv7）上也运行正常，需要添加别的架构。 + +### 手动拷贝方法 + +接下来我们介绍手动拷贝，如果使用了脚本，那么可以跳过以下手动方法的介绍。 + +### 把 .so 动态库和 .jar 拷贝进安卓demo程序： + +1. 将PaddlePredictor 载入到AndroidStudio。 +2. 将`libpaddle_lite_jni.so`拷贝进 `PaddlePredictor/app/src/main/jinLibs/架构文件夹下` ，比如文件夹arm8里要包含该 .so文件。 +3. 将 `PaddlePredictor.jar` 拷贝进 `PaddlePredictor/app/libs` 下 + +### 把demo使用到的模型文件拷贝进安卓程序： + +下载我们的5个模型文件，并解压缩到 `PaddlePredictor/app/src/main/assets` 这个文件夹中 +需要拷贝的模型文件和下载地址： + +``` +inception_v4_simple_opt.nb http://paddle-inference-dist.bj.bcebos.com/inception_v4_simple_opt.nb.tar.gz +lite_naive_model_opt.nb http://paddle-inference-dist.bj.bcebos.com/lite_naive_model_opt.nb.tar.gz +mobilenet_v1_opt.nb http://paddle-inference-dist.bj.bcebos.com/mobilenet_v1_opt.nb.tar.gz +mobilenet_v2_relu_opt.nb http://paddle-inference-dist.bj.bcebos.com/mobilenet_v2_relu_opt.nb.tar.gz +resnet50_opt.nb http://paddle-inference-dist.bj.bcebos.com/resnet50_opt.nb.tar.gz +``` + +下载完后，assets文件夹里要包含解压后的上面五个模型文件夹，但demo里不需要保存原压缩.tar.gz 文件。 + +注意：输入的模型要求为naive buffer存储格式，您可以通过 [**Model Optimize Tool**](../model_optimize_tool) 将fluid模型转为naive buffer存储格式。 + +## 运行 Android 程序结果 + +以上准备工作完成，就可以开始Build 、安装、和运行安卓demo程序。当你运行PaddlePredictor 程序时，大概会等10秒，然后看到类似以下字样： + +``` +lite_naive_model output: 50.213173, -28.872887 +expected: 50.2132, -28.8729 + +inception_v4_simple test:true +time: xxx ms + +resnet50 test:true +time: xxx ms + +mobilenet_v1 test:true +time: xxx ms + +mobilenet_v2 test:true +time: xxx ms +``` + +该 demo 程序跑我们的 5 个模型，第一个模型结果将真正的头两个数字输出，并在第二行附上期望的正确值。你应该要看到他们的误差小于0.001。后面四个模型如果你看到 `test:true` 字样，说明模型输出通过了我们在 demo 程序里对其输出的测试。time 代表该测试花费的时间。 diff --git a/docs/user_guides/paddle_mobile.md b/docs/user_guides/paddle_mobile.md new file mode 100644 index 0000000000..43d17db7be --- /dev/null +++ b/docs/user_guides/paddle_mobile.md @@ -0,0 +1,7 @@ +# paddle-mobile 编译 + +详情可以参考 [mobile/README](https://github.com/PaddlePaddle/Paddle-Lite/tree/develop/mobile) + +要切换 paddle-mobile 编译，cmake 需要加上 **-DWITH_PADDLE_MOBILE=ON** 开关，其余 flag 请参考上面文档添加到后面 + +所有其他选项跟 paddle-mobile 原始操作完全一致 diff --git a/docs/user_guides/tutorial.md b/docs/user_guides/tutorial.md new file mode 100644 index 0000000000..d1f3582f8c --- /dev/null +++ b/docs/user_guides/tutorial.md @@ -0,0 +1,55 @@ +# 使用流程 + +Lite是一种轻量级、灵活性强、易于扩展的高性能的深度学习预测框架，它可以支持诸如ARM、OpenCL、NPU等等多种终端，同时拥有强大的图优化及预测加速能力。如果您希望将Lite框架集成到自己的项目中，那么只需要如下几步简单操作即可。 + +## 一. 准备模型 + +Lite框架目前支持的模型结构为[PaddlePaddle](https://github.com/PaddlePaddle/Paddle)深度学习框架产出的模型格式。因此，在您开始使用 Lite 框架前您需要准备一个由PaddlePaddle框架保存的模型。 +如果您手中的模型是由诸如Caffe2、Tensorflow等框架产出的，那么我们推荐您使用 [X2Paddle](https://github.com/PaddlePaddle/X2Paddle) 工具进行模型格式转换。 + +## 二. 模型优化 + +Lite框架拥有强大的加速、优化策略及实现，其中包含诸如量化、子图融合、Kernel优选等等优化手段，为了方便您使用这些优化策略，我们提供了[Model Optimize Tool](../model_optimize_tool)帮助您轻松进行模型优化。优化后的模型更轻量级，耗费资源更少，并且执行速度也更快。 + +Model Optimize Tool的详细介绍，请您参考 [模型优化方法](../model_optimize_tool) 。 + +使用Model Optimize Tool，您只需编译后在开发机上执行以下代码： + +``` shell +$ cd +$ cd build.model_optimize_tool/lite/api/ +$ ./model_optimize_tool \ + --model_dir= \ + --model_file= \ + --param_file= \ + --optimize_out_type=(protobuf|naive_buffer) \ + --optimize_out= \ + --valid_targets=(arm|opencl|x86) \ + --prefer_int8_kernel=(ture|false) +``` + +其中，optimize_out为您希望的优化模型的输出路径。optimize_out_type则可以指定输出模型的序列化方式，其目前支持Protobuf与Naive Buffer两种方式，其中Naive Buffer是一种更轻量级的序列化/反序列化实现。如果你需要使用Lite在mobile端进行预测，那么您需要设置optimize_out_type=naive_buffer。 + +## 三. 使用Lite框架执行预测 + +在上一节中，我们已经通过Model Optimize Tool获取到了优化后的模型，使用优化模型进行预测也十分的简单。为了方便您的使用，Lite进行了良好的API设计，隐藏了大量您不需要投入时间研究的细节。您只需要简单的五步即可使用Lite在移动端完成预测（以C++ API进行说明）： + + +1. 声明MobileConfig。在config中可以设置**从文件加载模型**也可以设置**从memory加载模型**。从文件加载模型需要声明模型文件路径，如 `config.set_model_dir(FLAGS_model_dir)` ；从memory加载模型方法现只支持加载优化后模型的naive buffer，实现方法为： +`void set_model_buffer(model_buffer,model_buffer_size,param_buffer,param_buffer_size) ` + +2. 创建Predictor。Predictor即为Lite框架的预测引擎，为了方便您的使用我们提供了 `CreatePaddlePredictor` 接口，你只需要简单的执行一行代码即可完成预测引擎的初始化，`std::shared_ptr predictor = CreatePaddlePredictor(config)` 。 +3. 准备输入。执行predictor->GetInput(0)您将会获得输入的第0个field，同样的，如果您的模型有多个输入，那您可以执行 `predictor->GetInput(i)` 来获取相应的输入变量。得到输入变量后您可以使用Resize方法指定其具体大小，并填入输入值。 +4. 执行预测。您只需要执行 `predictor->Run()` 即可使用Lite框架完成预测。 +5. 获取输出。与输入类似，您可以使用 `predictor->GetOutput(i)` 来获得输出的第i个变量。您可以通过其shape()方法获取输出变量的维度，通过 `data()` 模板方法获取其输出值。 + + + + +## 四. Lite API + +为了方便您的使用，我们提供了C++、Java、Python三种API，并且提供了相应的api的完整使用示例:[C++完整示例](../cpp_demo)、[Java完整示例](../java_demo)、[Python完整示例](../cuda)，您可以参考示例中的说明快速了解C++/Java/Python的API使用方法，并集成到您自己的项目中去。需要说明的是，为了减少第三方库的依赖、提高Lite预测框架的通用性，在移动端使用Lite API您需要准备Naive Buffer存储格式的模型，具体方法可参考第2节`模型优化`。 + +## 五. 测试工具 + +为了使您更好的了解并使用Lite框架，我们向有进一步使用需求的用户开放了 [Lite Model Debug Tool](../debug_tools) 和 [Profile Monitor Tool](../debug_tools)。Lite Model Debug Tool可以用来查找Lite框架与PaddlePaddle框架在执行预测时模型中的对应变量值是否有差异，进一步快速定位问题Op，方便复现与排查问题。Profile Monitor Tool可以帮助您了解每个Op的执行时间消耗，其会自动统计Op执行的次数，最长、最短、平均执行时间等等信息，为性能调优做一个基础参考。您可以通过 [相关专题](../debug_tools) 了解更多内容。 -- GitLab