Update docs (#251)

* Update README.md
* Update change logs
* Update docs/advanced_tutorials/inference/INFERENCE.md

README.md

@@ -29,26 +29,37 @@ PaddleDetection的目的是为工业界和学术界提供丰富、易用的目
 
 支持的模型结构：
 
-|                    | ResNet | ResNet-vd <sup>[1](#vd)</sup> | ResNeXt-vd | SENet | MobileNet | DarkNet | VGG | HRNet | Res2Net |
-|--------------------|:------:|------------------------------:|:----------:|:-----:|:---------:|:-------:|:---:|:-----:| :--:    |
-| Faster R-CNN       | ✓      |                             ✓ | x          | ✓     | ✗         | ✗       | ✗   | ✗    |  ✗       |
-| Faster R-CNN + FPN | ✓      |                             ✓ | ✓          | ✓     | ✗         | ✗       | ✗   | ✓    |  ✓       |
-| Mask R-CNN         | ✓      |                             ✓ | x          | ✓     | ✗         | ✗       | ✗   | ✗    |  ✗       |
-| Mask R-CNN + FPN   | ✓      |                             ✓ | ✓          | ✓     | ✗         | ✗       | ✗   | ✗    |  ✓       |
-| Cascade Faster-RCNN | ✓      |                             ✓ | ✓          | ✗     | ✗         | ✗       | ✗  | ✗    |  ✗       |
-| Cascade Mask-RCNN  | ✓      |                             ✗ | ✗          | ✓     | ✗         | ✗       | ✗   | ✗    |  ✗       |
-| RetinaNet          | ✓      |                             ✗ | ✓          | ✗     | ✗         | ✗       | ✗   | ✗    |  ✗       |
-| YOLOv3             | ✓      |                             ✗ | ✗          | ✗     | ✓         | ✓       | ✗   | ✗    |  ✗       |
-| SSD                | ✗      |                             ✗ | ✗          | ✗     | ✓         | ✗       | ✓   | ✗    |  ✗       |
+|                    | ResNet | ResNet-vd <sup>[1](#vd)</sup> | ResNeXt-vd | SENet | MobileNet |  HRNet | Res2Net |
+|--------------------|:------:|------------------------------:|:----------:|:-----:|:---------:|:------:| :--:    |
+| Faster R-CNN       | ✓      |                             ✓ | x          | ✓     | ✗         |  ✗     |  ✗      |
+| Faster R-CNN + FPN | ✓      |                             ✓ | ✓          | ✓     | ✗         |  ✓     |  ✓      |
+| Mask R-CNN         | ✓      |                             ✓ | x          | ✓     | ✗         |  ✗     |  ✗      |
+| Mask R-CNN + FPN   | ✓      |                             ✓ | ✓          | ✓     | ✗         |  ✗     |  ✓      |
+| Cascade Faster-RCNN | ✓     |                             ✓ | ✓          | ✗     | ✗         |  ✗     |  ✗      |
+| Cascade Mask-RCNN  | ✓      |                             ✗ | ✗          | ✓     | ✗         |  ✗     |  ✗      |
+| Libra R-CNN        | ✗      |                             ✓ | ✗          | ✗     | ✗         |  ✗     |  ✗      |
+| RetinaNet          | ✓      |                             ✗ | ✓          | ✗     | ✗         |  ✗     |  ✗      |
+| YOLOv3             | ✓      |                             ✗ | ✗          | ✗     | ✓         |  ✗     |  ✗      |
+| SSD                | ✗      |                             ✗ | ✗          | ✗     | ✓         |  ✗     |  ✗      |
+| BlazeFace          | ✗      |                             ✗ | ✗          | ✗     | ✗         |  ✗     |  ✗      |
+| Faceboxes          | ✗      |                             ✗ | ✗          | ✗     | ✗         |  ✗     |  ✗      |
 
 <a name="vd">[1]</a> [ResNet-vd](https://arxiv.org/pdf/1812.01187) 模型提供了较大的精度提高和较少的性能损失。
 
+更多的Backone：
+
+- DarkNet
+- VGG
+- GCNet
+- CBNet
+
 扩展特性：
 
 - [x] **Synchronized Batch Norm**: 目前在YOLOv3中使用。
 - [x] **Group Norm**
 - [x] **Modulated Deformable Convolution**
 - [x] **Deformable PSRoI Pooling**
+- [x] **Non-local和GCNet**
 
 **注意:** Synchronized batch normalization 只能在多GPU环境下使用，不能在CPU环境或者单GPU环境下使用。
 
@@ -69,13 +80,14 @@ PaddleDetection的目的是为工业界和学术界提供丰富、易用的目
 - [IPython Notebook demo](demo/mask_rcnn_demo.ipynb)
 - [迁移学习教程](docs/advanced_tutorials/TRANSFER_LEARNING_cn.md)
 - [模型压缩](slim)
-    - [量化训练压缩示例](slim/quantization)
-    - [剪枝压缩示例](slim/prune)
-    - [蒸馏压缩示例](slim/distillation)
-    - [神经网络搜索示例](slim/nas)
+    - [量化](slim/quantization)
+    - [剪枝](slim/prune)
+    - [蒸馏](slim/distillation)
+    - [神经网络搜索](slim/nas)
+    - [压缩benchmark](slim)
 - [推理部署](inference)
     - [模型导出教程](docs/advanced_tutorials/inference/EXPORT_MODEL.md)
-    - [模型预测](docs/advanced_tutorials/inference/INFERENCE.md)
+    - [预测引擎Python API使用示例](docs/advanced_tutorials/inference/INFERENCE.md)
     - [C++推理部署](inference/README.md)
     - [推理Benchmark](docs/advanced_tutorials/inference/BENCHMARK_INFER_cn.md)
 

README_en.md

@@ -39,26 +39,37 @@ multi-GPU training.
 
 Supported Architectures:
 
-|                     | ResNet | ResNet-vd <sup>[1](#vd)</sup> | ResNeXt-vd | SENet | MobileNet | DarkNet | VGG  | HRNet | Res2Net |
-| ------------------- | :----: | ----------------------------: | :--------: | :---: | :-------: | :-----: | :--: | :--:  | :--:    |
-| Faster R-CNN        |   ✓    |                             ✓ |     x      |   ✓   |     ✗     |    ✗    |  ✗   |  ✗    |  ✗      |
-| Faster R-CNN + FPN  |   ✓    |                             ✓ |     ✓      |   ✓   |     ✗     |    ✗    |  ✗   |  ✓    |  ✓      |
-| Mask R-CNN          |   ✓    |                             ✓ |     x      |   ✓   |     ✗     |    ✗    |  ✗   |  ✗    |  ✗      |
-| Mask R-CNN + FPN    |   ✓    |                             ✓ |     ✓      |   ✓   |     ✗     |    ✗    |  ✗   |  ✗    |  ✓      |
-| Cascade Faster-RCNN |   ✓    |                             ✓ |     ✓      |   ✗   |     ✗     |    ✗    |  ✗   |  ✗    |  ✗      |
-| Cascade Mask-RCNN   |   ✓    |                             ✗ |     ✗      |   ✓   |     ✗     |    ✗    |  ✗   |  ✗    |  ✗      |
-| RetinaNet           |   ✓    |                             ✗ |     ✗      |   ✗   |     ✗     |    ✗    |  ✗   |  ✗    |  ✗      |
-| YOLOv3              |   ✓    |                             ✗ |     ✗      |   ✗   |     ✓     |    ✓    |  ✗   |  ✗    |  ✗      |
-| SSD                 |   ✗    |                             ✗ |     ✗      |   ✗   |     ✓     |    ✗    |  ✓   |  ✗    |  ✗      |
+|                     | ResNet | ResNet-vd <sup>[1](#vd)</sup> | ResNeXt-vd | SENet | MobileNet |  HRNet | Res2Net |
+| ------------------- | :----: | ----------------------------: | :--------: | :---: | :-------: |:------:|:-----:  |
+| Faster R-CNN        |   ✓    |                             ✓ |     x      |   ✓   |     ✗     |   ✗    |  ✗      |
+| Faster R-CNN + FPN  |   ✓    |                             ✓ |     ✓      |   ✓   |     ✗     |   ✓    |  ✓      |
+| Mask R-CNN          |   ✓    |                             ✓ |     x      |   ✓   |     ✗     |   ✗    |  ✗      |
+| Mask R-CNN + FPN    |   ✓    |                             ✓ |     ✓      |   ✓   |     ✗     |   ✗    |  ✓      |
+| Cascade Faster-RCNN |   ✓    |                             ✓ |     ✓      |   ✗   |     ✗     |   ✗    |  ✗      |
+| Cascade Mask-RCNN   |   ✓    |                             ✗ |     ✗      |   ✓   |     ✗     |   ✗    |  ✗      |
+| Libra R-CNN         |   ✗    |                             ✓ |     ✗      |   ✗   |     ✗     |   ✗    |  ✗      |
+| RetinaNet           |   ✓    |                             ✗ |     ✗      |   ✗   |     ✗     |   ✗    |  ✗      |
+| YOLOv3              |   ✓    |                             ✗ |     ✗      |   ✗   |     ✓     |   ✗    |  ✗      |
+| SSD                 |   ✗    |                             ✗ |     ✗      |   ✗   |     ✓     |   ✗    |  ✗      |
+| BlazeFace           |   ✗    |                             ✗ |     ✗      |   ✗   |     ✗     |   ✗    |  ✗      |
+| Faceboxes           |   ✗    |                             ✗ |     ✗      |   ✗   |     ✗     |   ✗    |  ✗      |
 
 <a name="vd">[1]</a> [ResNet-vd](https://arxiv.org/pdf/1812.01187) models offer much improved accuracy with negligible performance cost.
 
+More Backbones:
+
+- DarkNet
+- VGG
+- GCNet
+- CBNet
+
 Advanced Features:
 
 - [x] **Synchronized Batch Norm**: currently used by YOLOv3.
 - [x] **Group Norm**
 - [x] **Modulated Deformable Convolution**
 - [x] **Deformable PSRoI Pooling**
+- [x] **Non-local and GCNet**
 
 **NOTE:** Synchronized batch normalization can only be used on multiple GPU devices, can not be used on CPU devices or single GPU device.
 

docs/CHANGELOG.md

 # 版本更新信息
 
+### v0.2.0(02/2020)
+  - 新增模型:
+    - 新增基于CBResNet模型。
+    - 新增LibraRCNN模型。
+    - 进一步提升YOLOv3模型精度，基于COCO数据精度达到43.2%，相比上个版本提升1.4%。
+  - 新增基础模块:
+    - 主干网络: 新增CBResNet。
+    - loss模块: YOLOv3的loss支持细粒度op组合。
+    - 正则模块: 新增DropBlock模块。
+  - 功能优化和改进:
+    - 加速YOLOv3数据预处理，整体训练提速40%。
+    - 优化数据预处理逻辑，提升易用性。
+    - 增加人脸检测预测benchmark数据。
+    - 增加C++预测引擎Python API预测示例。
+  - 检测模型压缩 :
+    - 裁剪: 发布MobileNet-YOLOv3裁剪方案和模型，基于VOC数据FLOPs - 69.6%, mAP + 1.4%，基于COCO数据FLOPS-28.8%, mAP + 0.9%; 发布ResNet50vd-dcn-YOLOv3裁剪方案和模型，基于COCO数据集FLOPS - 18.4%, mAP + 0.8%。
+    - 蒸馏: 发布MobileNet-YOLOv3蒸馏方案和模型，基于VOC数据mAP + 2.8%，基于COCO数据mAP + 2.1%。
+    - 量化: 发布YOLOv3-MobileNet和BlazeFace的量化模型。
+    - 裁剪+蒸馏: 发布MobileNet-YOLOv3裁剪+蒸馏方案和模型，基于COCO数据FLOPS - 69.6%，基于TensorRT预测加速64.5%，mAP - 0.3 %; 发布ResNet50vd-dcn-YOLOv3裁剪+蒸馏方案和模型，基于COCO数据FLOPS - 43.7%，基于TensorRT预测加速24.0%，mAP + 0.6 %。
+    - 搜索: 开源BlazeFace-Nas的完成搜索方案。
+  - 预测部署:
+    - 集成 TensorRT，支持FP16、FP32、INT8量化推理加速。
+  - 文档:
+    - 增加详细的数据预处理模块介绍文档以及实现自定义数据Reader文档。
+    - 增加如何新增算法模型的文档。
+    - 文档部署到网站: https://paddledetection.readthedocs.io/zh/latest/
+
 ### 12/2019
 - 增加Res2Net模型。
 - 增加HRNet模型。

docs/advanced_tutorials/inference/BENCHMARK_INFER_cn.md

@@ -8,7 +8,7 @@
   - PaddlePaddle v1.6
   - GPU分别为: Tesla V100和Tesla P4
 - 测试方式:
-  - 为了方面比较不同模型的推理速度，输入采用同样大小的图片，为 3x640x640，采用 `demo/000000014439_640x640.jpg` 图片。
+  - 为了方便比较不同模型的推理速度，输入采用同样大小的图片，为 3x640x640，采用 `demo/000000014439_640x640.jpg` 图片。
   - Batch Size=1
   - 去掉前10轮warmup时间，测试100轮的平均时间，单位ms/image，包括输入数据拷贝至GPU的时间、计算时间、数据拷贝只CPU的时间。
   - 采用Fluid C++预测引擎: 包含Fluid C++预测、Fluid-TensorRT预测，下面同时测试了Float32 (FP32) 和Float16 (FP16)的推理速度。

docs/advanced_tutorials/inference/INFERENCE.md

 # 模型预测
 
-基于[模型导出](EXPORT_MODEL.md)保存inference_model，通过下列方法对保存模型进行预测，同时测试不同方法下的预测速度
+本篇教程使用Python API对[导出模型](EXPORT_MODEL.md)保存的inference_model进行预测。
+
+在PaddlePaddle中预测引擎和训练引擎底层有着不同的优化方法，代码走不通的分支，两者都可以进行预测。在入门教程的训练/评估/预测流程中介绍的预测流程，即tools/infer.py是使用训练引擎分支的预测流程。保存的inference_model，可以通过`fluid.io.load_inference_model`接口，走训练引擎分支预测。本文档也同时介绍通过预测引擎的Python API进行预测，一般而言这种方式的速度优于前者。
+
+
+这篇教程介绍的Python API预测示例，除了可视化部分依赖PaddleDetection外，预处理、模型结构、执行流程均不依赖PaddleDetection。
+
 
 ## 使用方式
 
@@ -12,36 +18,36 @@ python tools/cpp_infer.py --model_path=inference_model/faster_rcnn_r50_1x/ --con
 
 主要参数说明：
 
-1. model_path: inference_model保存路径
-2. config_path: 数据预处理配置文件
-3. infer_img: 待预测图片
-4. visualize: 是否保存可视化结果，默认保存路径为```output/```。
+-  model_path:  inference_model保存路径
+-  config_path: 参数配置、数据预处理配置文件，注意不是训练时的配置文件
+-  infer_img:   待预测图片
+-  visualize:   是否保存可视化结果，默认保存路径为```output/```
 
 
-更多参数可在```tools/cpp_demo.yml```中查看,
+更多参数可在```tools/cpp_demo.yml```中查看，主要参数：
 
-**注意**
 
-1. 设置shape时必须保持与模型导出时shape大小一致；
-2. `min_subgraph_size`的设置与模型arch相关，对部分arch需要调大该参数，一般设置为40适用于所有模型。适当的调小`min_subgraph_size`会对预测有加速效果，例如YOLO中该参数可设置为3。
+- use_python_inference:
 
-3. 预处理中`PadStride`为输入图片右下角填充0，默认设置stride为0，即不对输入图片做padding操作。模型中包含FPN结构时，stride应设置为32。模型为RetinaNet系列模型时，stride应设置为128.
-## Paddle环境搭建
+  若为true，使用`fluid.io.load_inference_model`接口，走训练引擎分支预测。
 
-需要基于develop分支编译TensorRT版本Paddle, 在编译命令中指定TensorRT路径：
+- mode:
 
-```bash
-cmake .. -DWITH_MKL=ON \
-         -DWITH_GPU=ON \
-         -DWITH_TESTING=ON \
-         -DCMAKE_BUILD_TYPE=Release \
-         -DCUDA_ARCH_NAME=Auto \
-         -DCMAKE_INSTALL_PREFIX=`pwd`/output \
-         -DON_INFER=ON \
-         -DTENSORRT_ROOT=${PATH_TO_TensorRT} \
-
-make -j20
-make install
-
-export LD_LIBRARY_PATH=${PATH_TO_TensorRT}/lib:$LD_LIBRARY_PATH
-```
+  支持fluid、trt_fp32、trt_fp16、trt_int8，当use_python_inference为false时起作用。fluid是通过预测引擎分支预测，trt_fp32、trt_fp16、trt_int8是通过预测引擎分支预测，后端基于TensorRT的FP32、FP16精度。
+
+- min_subgraph_size:
+
+  当设置mode采用TensorRT时，注意设置此参数。设置与模型arch相关，对部分arch需要调大该参数，一般设置为40适用于所有模型。适当的调小`min_subgraph_size`会对预测有加速效果，例如YOLO中该参数可设置为3。
+
+- Preprocess:
+
+  数据预处理配置，一般来说顺序为Resize -> Normalize -> Permute，对于FPN模型还需配置PadStride。不同模型的数据预处理参考训练配置中的`TestReader`部分。
+
+
+**注意**
+
+1. 基于TensorRT预测，数据预处理Resize设置的shape必须保持与模型导出时shape大小一致。
+
+2. 预处理中`PadStride`为输入图片右下角填充0，默认设置stride为0，即不对输入图片做padding操作。模型中包含FPN结构时，stride应设置为32。模型为RetinaNet系列模型时，stride应设置为128.
+
+3. PaddlePaddle默认的GPU安装包(<=1.7)，是不支持基于TensorRT进行预测，如果想基于TensorRT加速预测，需要自行编译，详细可参考[预测库编译教程](https://www.paddlepaddle.org.cn/documentation/docs/zh/advanced_usage/deploy/inference/paddle_tensorrt_infer.html)。

docs/advanced_tutorials/slim/MODEL_ZOO.md

-../../../slim/MODEL_ZOO.md
\ No newline at end of file
+slim/README.md
\ No newline at end of file

slim/MODEL_ZOO.md → slim/README.md

+# 简介
+
+在PaddleDetection, 提供了基于PaddleSlim进行模型压缩的完整教程和实验结果。详细教程请参考：
+
+- [量化](quantization)
+- [裁剪](prune)
+- [蒸馏](distillation)
+- [搜索](nas)
+
+下面给出压缩的benchmark实验结果。
+
 # 压缩模型库
 
 ## 测试环境

slim/distillation/README.md

@@ -10,7 +10,7 @@
 - [检测库的常规训练方法](https://github.com/PaddlePaddle/PaddleDetection)
 - [PaddleSlim蒸馏API文档](https://paddlepaddle.github.io/PaddleSlim/api/single_distiller_api/)
 
-已发布蒸馏模型见[压缩模型库](../MODEL_ZOO.md)
+已发布蒸馏模型见[压缩模型库](../README.md)
 
 ## 安装PaddleSlim
 可按照[PaddleSlim使用文档](https://paddlepaddle.github.io/PaddleSlim/)中的步骤安装PaddleSlim

slim/extensions/distill_pruned_model/README.md

@@ -12,7 +12,7 @@
 
 请确保已正确[安装PaddleDetection](../../../docs/tutorials/INSTALL_cn.md)及其依赖。
 
-已发布蒸馏通道剪裁模型见[压缩模型库](../../MODEL_ZOO.md)
+已发布蒸馏通道剪裁模型见[压缩模型库](../../README.md)
 
 蒸馏通道剪裁模型示例见[Ipython notebook示例](./distill_pruned_model_demo.ipynb)
 
@@ -24,7 +24,7 @@
 
 通过`-c`选项指定待剪裁模型的配置文件的相对路径，更多可选配置文件请参考: [检测库配置文件](../../../configs)。
 
-蒸馏通道剪裁模型中，我们使用原模型全量权重来初始化待剪裁模型，已发布模型的权重可在[模型库](../../../docs/MODEL_ZOO.md)中获取。
+蒸馏通道剪裁模型中，我们使用原模型全量权重来初始化待剪裁模型，已发布模型的权重可在[模型库](../../../docs/README.md)中获取。
 
 通过`-o pretrain_weights`指定待剪裁模型的预训练权重，可以指定url或本地文件系统的路径。如下所示：
 

slim/prune/README.md

@@ -8,7 +8,7 @@
 
 该教程中所示操作，如无特殊说明，均在`PaddleDetection/slim/prune/`路径下执行。
 
-已发布裁剪模型见[压缩模型库](../MODEL_ZOO.md)
+已发布裁剪模型见[压缩模型库](../README.md)
 
 ## 1. 数据准备
 
@@ -32,7 +32,7 @@
 -o weights=output/yolov3_mobilenet_v1_voc/model_final
 ```
 
-官方已发布的模型请参考: [模型库](https://github.com/PaddlePaddle/PaddleDetection/blob/release/0.1/docs/MODEL_ZOO_cn.md)
+官方已发布的模型请参考: [模型库](https://github.com/PaddlePaddle/PaddleDetection/blob/release/0.1/docs/README.md)
 
 ## 3. 确定待分析参数
 

slim/quantization/README.md

@@ -10,7 +10,7 @@
 - [检测模型的常规训练方法](https://github.com/PaddlePaddle/PaddleDetection)
 - [PaddleSlim使用文档](https://paddlepaddle.github.io/PaddleSlim/)
 
-已发布量化模型见[压缩模型库](../MODEL_ZOO.md)
+已发布量化模型见[压缩模型库](../README.md)
 
 ## 安装PaddleSlim
 可按照[PaddleSlim使用文档](https://paddlepaddle.github.io/PaddleSlim/)中的步骤安装PaddleSlim。

tools/cpp_demo.yml

 # demo for cpp_infer.py
 
-mode: trt_fp32 # trt_fp32, trt_fp16, trt_int8, fluid
+use_python_inference: true # whether to use python inference
+mode: fluid # trt_fp32, trt_fp16, trt_int8, fluid
 arch: RCNN # YOLO, SSD, RCNN, RetinaNet
 min_subgraph_size: 40 # need 3 for YOLO arch
-use_python_inference: False # whether to use python inference
 
 # visualize the predicted image
 metric: COCO # COCO, VOC