Merge pull request #6 from PaddlePaddle/develop

00

Author: SunAhong1993

.pre-commit-config.yaml

@@ -14,10 +14,27 @@
     -   id: check-symlinks
     -   id: check-added-large-files
 -   repo: local
+
     hooks:
     -   id: copyright_checker
         name: copyright_checker
         entry: python ./.copyright.hook
         language: system
         files: \.(c|cc|cxx|cpp|cu|h|hpp|hxx|proto|py)$
         exclude: (?!.*third_party)^.*$
+
+    hooks:
+    -   id: clang-format-with-version-check
+        name: clang-format
+        description: Format files with ClangFormat.
+        entry: bash ./tools/codestyle/clang_format.hook -i
+        language: system
+        files: \.(c|cc|cxx|cpp|cu|h|hpp|hxx|proto)$
+
+    hooks:
+    -   id: cpplint-cpp-source
+        name: cpplint
+        description: Check C++ code style using cpplint.py.
+        entry: bash cpplint_pre_commit.hook
+        language: system
+        files: \.(c|cc|cxx|cpp|cu|h|hpp|hxx)$

README.md

@@ -11,18 +11,18 @@ PaddleX是基于飞桨核心框架、开发套件和工具组件的深度学习
 
 ## 特点
 
-- **全流程打通** 
-  - 数据准备：支持LabelMe，精灵标注等主流数据标注工具协议，同时无缝集成[EasyData智能数据服务平台](https://ai.baidu.com/easydata/), 助力开发者高效获取AI开发所需高质量数据。
-  - 模型训练：基于飞桨核心框架集成[PaddleClas](https://github.com/PaddlePaddle/PaddleClas), [PaddleDetection](https://github.com/PaddlePaddle/PaddleDetection), [PaddleSeg](https://github.com/PaddlePaddle/PaddleSeg)视觉开发套件，[VisualDL](https://github.com/PaddlePaddle/VisualDL)可视化分析组件，高效完成模型训练。
-  - 多端部署：内置[PaddleSlim](https://github.com/PaddlePaddle/PaddleSlim)模型压缩工具和AES模型加密SDK，结合Paddle Inference和[Paddle Lite](https://github.com/PaddlePaddle/Paddle-Lite)便捷完成高性能且可靠的多端部署。
+- **全流程打通**
+  - **数据准备**：支持[EasyData智能数据服务平台](https://ai.baidu.com/easydata/)数据协议，通过平台便捷完成智能标注,低质数据清洗工作, 同时兼容主流标注工具协议, 助力开发者更快完成数据准备工作。
+  - **模型训练**：集成[PaddleClas](https://github.com/PaddlePaddle/PaddleClas), [PaddleDetection](https://github.com/PaddlePaddle/PaddleDetection), [PaddleSeg](https://github.com/PaddlePaddle/PaddleSeg)视觉开发套件，丰富的高质量预训练模型，更快实现工业级模型效果。
+  - **模型调优**：内置模型可解释性模块、[VisualDL](https://github.com/PaddlePaddle/VisualDL)可视化分析组件, 提供丰富的信息更好地理解模型，优化模型。
+  - **多端安全部署**：内置[PaddleSlim](https://github.com/PaddlePaddle/PaddleSlim)模型压缩工具和**模型加密部署模块**，结合Paddle Inference或[Paddle Lite](https://github.com/PaddlePaddle/Paddle-Lite)便捷完成高性能的多端安全部署。
 
-- **融合产业实践** 
+- **融合产业实践**
   - 精选飞桨产业实践的成熟模型结构，开放案例实践教程，加速开发者产业落地。
-  - 通过[PaddleHub](https://github.com/PaddlePaddle/Paddle)内置丰富的飞桨高质量预训练模型，助力开发者高效实现飞桨Master模式。
 
 - **易用易集成**
-  - PadldeX提供简洁易用的全流程API，几行代码即可实现上百种数据增强、模型可解释性、C++模型部署等功能。
-  - 提供以PaddleX API为核心集成的跨平台GUI界面，降低深度学习全流程应用门槛。
+  - 统一易用的全流程API，5步完成模型训练，10行代码实现Python/C++高性能部署。
+  - 提供以PaddleX为核心集成的跨平台可视化工具PaddleX-GUI，快速体验飞桨深度学习全流程。
 
 
 ## 安装
@@ -31,7 +31,7 @@ PaddleX提供两种开发模式，满足不同场景和用户需求：
 
 - **Python开发模式：** 通过Python API方式完成全流程使用或集成，该模型提供全面、灵活、开放的深度学习功能，有更高的定制化空间。
 
-- **GUI开发模式：** 以PaddleX API为核心集成的跨平台GUI客户端，支持`Python开发模式`下的常用功能，以更低门槛的方式快速完成产业验证的模型训练。
+- **Padlde-GUI模式：** PaddleX-GUI支持`Python开发模式`下的常用功能，以更低门槛的方式快速完成产业验证的模型训练。
 
 开发者可根据自身需要按需选择不同的模式进行安装使用。
 
@@ -47,21 +47,21 @@ PaddleX提供两种开发模式，满足不同场景和用户需求：
 ```
 pip install paddlex -i https://mirror.baidu.com/pypi/simple
 ```
+安装的相关问题参考[PaddleX安装](https://paddlex.readthedocs.io/zh_CN/latest/install.html)
 
-### GUI开发模式安装
+### PaddleX-GUI安装
 
 进入PaddleX官网[下载使用](https://www.paddlepaddle.org.cn/paddle/paddlex)，申请下载绿色安装包，开箱即用。
-GUI模式的使用教程可参考[PaddleX GUI模式使用教程](https://paddlex.readthedocs.io/zh_CN/latest/paddlex_gui/index.html)
+Paddle-GUI的使用教程可参考[PaddleX-GUI模式使用教程](https://paddlex.readthedocs.io/zh_CN/latest/paddlex_gui/index.html)
 
-## 使用文档 
+## 使用文档
 
 推荐访问[PaddleX在线使用文档](https://paddlex.readthedocs.io/zh_CN/latest/index.html)，快速查阅读使用教程和API文档说明。
 
-- [10分钟快速上手](https://paddlex.readthedocs.io/zh_CN/latest/quick_start.html)
-- [PaddleX模型训练](https://paddlex.readthedocs.io/zh_CN/latest/tutorials/train/index.html#id1)
-- [PaddleX模型压缩](https://paddlex.readthedocs.io/zh_CN/latest/slim/index.html#id1)
-- [PaddleX模型库](https://paddlex.readthedocs.io/zh_CN/latest/model_zoo.html#id1)
-- [PaddleX多端部署](docs/deploy.md)
+- [10分钟快速上手使用](https://paddlex.readthedocs.io/zh_CN/latest/quick_start.html)
+- [PaddleX全流程开发教程](https://paddlex.readthedocs.io/zh_CN/latest/tutorials/index.html)
+- [PaddleX视觉方案介绍](https://paddlex.readthedocs.io/zh_CN/latest/cv_solutions.html)
+- [PaddleX API参考文档](https://paddlex.readthedocs.io/zh_CN/latest/apis/index.html)
 
 ## 在线教程
 
@@ -74,12 +74,16 @@ GUI模式的使用教程可参考[PaddleX GUI模式使用教程](https://paddlex
 ## 交流与反馈
 
 - 项目官网: https://www.paddlepaddle.org.cn/paddle/paddlex
-- PaddleX用户QQ群: 1045148026 (手机QQ扫描如下二维码快速加入)  
+- PaddleX用户交流群: 1045148026 (手机QQ扫描如下二维码快速加入)  
 <img src="./docs/images/QQGroup.jpeg" width="195" height="300" alt="QQGroup" align="center" />
 
 ## FAQ
 
 ## 更新日志
+* 2020.05.20
+
+  **`v1.0.0`**
+  * 正式版本发布。
 
 ## 贡献代码
 

deploy/README.md

@@ -1,6 +1,7 @@
-# 模型部署
+# 多端安全部署
 
-本目录为PaddleX模型部署代码, 编译和使用的教程参考：
+本目录为PaddleX模型部署代码，编译和使用教程参考：
 
-- [C++部署文档](../docs/tutorials/deploy/deploy.md#C部署)
-- [OpenVINO部署文档](../docs/tutorials/deploy/deploy.md#openvino部署)
+- [服务端部署(支持Python部署、C++部署、模型加密部署)](../docs/tutorials/deploy/deploy_server/)
+- [OpenVINO部署](../docs/tutorials/deploy/deploy_openvino.md)
+- [移动端部署](../docs/tutorials/deploy/deploy_lite.md)

deploy/lite/export_lite.py

@@ -0,0 +1,48 @@
+#copyright (c) 2020 PaddlePaddle Authors. All Rights Reserve.
+#
+#Licensed under the Apache License, Version 2.0 (the "License");
+#you may not use this file except in compliance with the License.
+#You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#Unless required by applicable law or agreed to in writing, software
+#distributed under the License is distributed on an "AS IS" BASIS,
+#WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#See the License for the specific language governing permissions and
+#limitations under the License.
+
+import paddlelite.lite as lite
+import os
+import argparse
+
+
+def export_lite():
+    opt = lite.Opt()
+    model_file = os.path.join(FLAGS.model_path, '__model__')
+    params_file = os.path.join(FLAGS.model_path, '__params__')
+    opt.run_optimize("", model_file, params_file, FLAGS.place, FLAGS.save_dir)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--model_path",
+        type=str,
+        default="",
+        help="model path.",
+        required=True)
+    parser.add_argument(
+        "--place",
+        type=str,
+        default="arm",
+        help="preprocess config path.",
+        required=True)
+    parser.add_argument(
+        "--save_dir",
+        type=str,
+        default="paddlex.onnx",
+        help="Directory for storing the output visualization files.",
+        required=True)
+    FLAGS = parser.parse_args()
+    export_lite()

docs/FAQ.md

@@ -1,22 +1,25 @@
 # 常见问题
 
-## 1. 训练过程因显存不够出错
+## 1. 训练参数如何调整
+> 参考[参数调整文档](appendix/parameters.md)
+
+## 2. 训练过程因显存不够出错
 
 > 通过使用在终端`nvidia-smi`命令，查看GPU是否被其它任务占用，尝试清除其它任务；  
 > 调低训练时的`batch_size`参数，从而降低显存的要求，注意需等比例调低`learning_rate`等参数；
 > 选用更小的模型或backbone。
 
-## 2. 是否有更小的模型，适用于更低配置的设备上运行
+## 3. 是否有更小的模型，适用于更低配置的设备上运行
 > 可以使用模型裁剪，参考文档[模型裁剪使用教程](slim/prune.md)，通过调整裁剪参数，可以控制模型裁剪后的大小，在实际实验中，如VOC检测数据，使用yolov3-mobilenet，原模型大小为XXM，裁剪后为XX M，精度基本保持不变
 
-## 3. 如何配置训练时GPU的卡数
+## 4. 如何配置训练时GPU的卡数
 > 通过在终端export环境变量，或在Python代码中设置，可参考文档[CPU/多卡GPU训练](gpu_configure.md)
 
-## 4. 想将之前训练的模型参数上继续训练
+## 5. 想将之前训练的模型参数上继续训练
 > 在训练调用`train`接口时，将`pretrain_weights`设为之前的模型保存路径即可
 
 
-## 5. PaddleX保存的模型分为正常训练过程中产生、裁剪训练产生、导出为部署模型和量化保存这么多种，有什么差别，怎么区分
+## 6. PaddleX保存的模型分为正常训练过程中产生、裁剪训练产生、导出为部署模型和量化保存这么多种，有什么差别，怎么区分
 
 **不同模型的功能差异**
 
@@ -40,20 +43,20 @@
 >> 通过模型目录下model.yml文件中`status`字段来区别不同的模型类型, 'Normal'、'Prune'、'Infer'、'Quant'分别表示正常模型训练保存、裁剪训练保存、导出的部署模型、量化保存模型
 
 
-## 6. 模型训练需要太久时间，或者训练速度太慢，怎么提速
+## 7. 模型训练需要太久时间，或者训练速度太慢，怎么提速
 > 1.模型训练速度与用户选定的模型大小，和设定的`batch_size`相关，模型大小可直接参考[模型库](model_zoo.md)中的指标，一般而言，模型越大，训练速度就越慢；  
 
 > 2.在模型速度之外，模型训练完成所需的时间又与用户设定的`num_epochs`迭代轮数相关，用户可以通过观察模型在验证集上的指标来决定是否提示结束掉训练进程（训练时设定`save_interval_epochs`参数，训练过程会每间隔`save_interval_epochs`轮数在验证集上计算指标，并保存模型）；  
 
-## 7. 如何设定迭代的轮数
+## 8. 如何设定迭代的轮数
 > 1. 用户自行训练时，如不确定迭代的轮数，可以将轮数设高一些，同时注意设置`save_interval_epochs`，这样模型迭代每间隔相应轮数就会在验证集上进行评估和保存，可以根据不同轮数模型在验证集上的评估指标，判断模型是否已经收敛，若模型已收敛，可以自行结束训练进程
 >
-## 8. 只有CPU，没有GPU，如何提升训练速度
+## 9. 只有CPU，没有GPU，如何提升训练速度
 > 当没有GPU时，可以根据自己的CPU配置，选择是否使用多CPU进行训练，具体配置方式可以参考文档[多卡CPU/GPU训练](gpu_configure.md)
 >
-## 9. 电脑不能联网，训练时因为下载预训练模型失败，如何解决
+## 10. 电脑不能联网，训练时因为下载预训练模型失败，如何解决
 > 可以预先通过其它方式准备好预训练模型，然后训练时自定义`pretrain_weights`即可，可参考文档[无联网模型训练](how_to_offline_run.md)
 
-## 10. 每次训练新的模型，都需要重新下载预训练模型，怎样可以下载一次就搞定
+## 11. 每次训练新的模型，都需要重新下载预训练模型，怎样可以下载一次就搞定
 > 1.可以按照9的方式来解决这个问题  
 > 2.每次训练前都设定`paddlex.pretrain_dir`路径，如设定`paddlex.pretrain_dir='/usrname/paddlex`，如此下载完的预训练模型会存放至`/usrname/paddlex`目录下，而已经下载在该目录的模型也不会再次重复下载

docs/apis/visualize.md

@@ -114,27 +114,54 @@ pdx.slim.visualize(model, 'mobilenetv2.sensitivities', save_dir='./')
 # 可视化结果保存在./sensitivities.png
 ```
 
-## 可解释性结果可视化
+## LIME可解释性结果可视化
 ```
-paddlex.interpret.visualize(img_file, 
-                            model, 
-                            dataset=None, 
-                            algo='lime',
-                            num_samples=3000, 
-                            batch_size=50,
-                            save_dir='./')
+paddlex.interpret.lime(img_file, 
+                       model, 
+                       num_samples=3000, 
+                       batch_size=50,
+                       save_dir='./')
 ```
-将模型预测结果的可解释性可视化，目前只支持分类模型。
+使用LIME算法将模型预测结果的可解释性可视化。  
+LIME表示与模型无关的局部可解释性，可以解释任何模型。LIME的思想是以输入样本为中心，在其附近的空间中进行随机采样，每个采样通过原模型得到新的输出，这样得到一系列的输入和对应的输出，LIME用一个简单的、可解释的模型（比如线性回归模型）来拟合这个映射关系，得到每个输入维度的权重，以此来解释模型。    
+
+**注意：** 可解释性结果可视化目前只支持分类模型。
 
 ### 参数
 >* **img_file** (str): 预测图像路径。
 >* **model** (paddlex.cv.models): paddlex中的模型。
->* **dataset** (paddlex.datasets): 数据集读取器，默认为None。
->* **algo** (str): 可解释性方式，当前可选'lime'和'normlime'。
 >* **num_samples** (int): LIME用于学习线性模型的采样数，默认为3000。
 >* **batch_size** (int): 预测数据batch大小，默认为50。
 >* **save_dir** (str): 可解释性可视化结果（保存为png格式文件）和中间文件存储路径。 
 
 
 ### 使用示例
-> 对预测可解释性结果可视化的过程可参见[代码](https://github.com/PaddlePaddle/PaddleX/blob/develop/tutorials/interpret/interpret.py)。
+> 对预测可解释性结果可视化的过程可参见[代码](https://github.com/PaddlePaddle/PaddleX/blob/develop/tutorials/interpret/lime.py)。
+
+
+## NormLIME可解释性结果可视化
+```
+paddlex.interpret.normlime(img_file, 
+                           model, 
+                           dataset=None,
+                           num_samples=3000, 
+                           batch_size=50,
+                           save_dir='./')
+```
+使用NormLIME算法将模型预测结果的可解释性可视化。
+NormLIME是利用一定数量的样本来出一个全局的解释。NormLIME会提前计算一定数量的测试样本的LIME结果，然后对相同的特征进行权重的归一化，这样来得到一个全局的输入和输出的关系。
+
+**注意：** 可解释性结果可视化目前只支持分类模型。
+
+### 参数
+>* **img_file** (str): 预测图像路径。
+>* **model** (paddlex.cv.models): paddlex中的模型。
+>* **dataset** (paddlex.datasets): 数据集读取器，默认为None。
+>* **num_samples** (int): LIME用于学习线性模型的采样数，默认为3000。
+>* **batch_size** (int): 预测数据batch大小，默认为50。
+>* **save_dir** (str): 可解释性可视化结果（保存为png格式文件）和中间文件存储路径。 
+
+**注意：** dataset`读取的是一个数据集，该数据集不宜过大，否则计算时间会较长，但应包含所有类别的数据。
+### 使用示例
+> 对预测可解释性结果可视化的过程可参见[代码](https://github.com/PaddlePaddle/PaddleX/blob/develop/tutorials/interpret/normlime.py)。
+

docs/appendix/index.rst

@@ -8,13 +8,7 @@
 
    model_zoo.md
    metrics.md
+   parameters.md
    how_to_convert_dataset.md
    datasets.md
 
-
-* PaddleX版本: v0.1.7
-* 项目官网: http://www.paddlepaddle.org.cn/paddle/paddlex  
-* 项目GitHub: https://github.com/PaddlePaddle/PaddleX/tree/develop  
-* 官方QQ用户群: 1045148026  
-* GitHub Issue反馈: http://www.github.com/PaddlePaddle/PaddleX/issues
-

docs/appendix/parameters.md

@@ -0,0 +1,25 @@
+# 训练参数调整
+
+PaddleX所有训练接口中，内置的参数均为根据单GPU卡相应batch_size下的较优参数，用户在自己的数据上训练模型，涉及到参数调整时，如无太多参数调优经验，则可参考如下方式
+
+## 1.Epoch数的调整
+Epoch数是模型训练过程，迭代的轮数，用户可以设置较大的数值，根据模型迭代过程在验证集上的指标表现，来判断模型是否收敛，进而提前终止训练。此外也可以使用`train`接口中的`early_stop`策略，模型在训练过程会自动判断模型是否收敛自动中止。
+
+## 2.Batch Size的调整
+Batch Size指模型在训练过程中，一次性处理的样本数量, 如若使用多卡训练， batch_size会均分到各张卡上（因此需要让batch size整除卡数）。这个参数跟机器的显存/内存高度相关，`batch_size`越高，所消耗的显存/内存就越高。PaddleX在各个`train`接口中均配置了默认的batch size，如若用户调整batch size，则也注意需要对应调整其它参数，如下表所示展示YOLOv3在训练时的参数配置
+
+|       参数       |     默认值    |      调整比例       |      示例     |
+|:---------------- | :------------ | :------------------ | :------------ |
+| train_batch_size |      8        |   调整为 8*alpha    |      16       |
+| learning_rate    |    1.0/8000   |   调整为 alpha/8000 |    2.0/8000   |
+| warmup_steps     |    1000       |   调整为 1000/alpha<br>(该参数也可以自行根据数据情况调整) |     500       |
+| lr_decay_epochs  | [213, 240]    |   不变              |   [213, 240]  |
+
+
+更多训练接口可以参考
+- [分类模型-train](https://paddlex.readthedocs.io/zh_CN/latest/apis/models/classification.html#train)
+- [目标检测检测FasterRCNN-train](https://paddlex.readthedocs.io/zh_CN/latest/apis/models/detection.html#id2)
+- [目标检测YOLOv3-train](https://paddlex.readthedocs.io/zh_CN/latest/apis/models/detection.html#train)
+- [实例分割MaskRCNN-train](https://paddlex.readthedocs.io/zh_CN/latest/apis/models/instance_segmentation.html#train)
+- [语义分割DeepLabv3p-train](https://paddlex.readthedocs.io/zh_CN/latest/apis/models/semantic_segmentation.html#train)
+- [语义分割UNet](https://paddlex.readthedocs.io/zh_CN/latest/apis/models/semantic_segmentation.html#id2)