Merge pull request #2255 from RainFrost1/develop

主页及相关文档更新

README_ch.md

@@ -60,19 +60,18 @@ PP-ShiTu图像识别快速体验：[点击这里](./docs/zh_CN/quick_start/quick
 - [环境准备](docs/zh_CN/installation/install_paddleclas.md)
 - [PP-ShiTuV2图像识别系统介绍](./docs/zh_CN/PPShiTu/PPShiTuV2_introduction.md)
   - [图像识别快速体验](docs/zh_CN/quick_start/quick_start_recognition.md)
-  - 模块介绍
+  - [20+应用场景库](docs/zh_CN/introduction/ppshitu_application_scenarios.md)
+  - 子模块算法介绍及模型训练
     - [主体检测](./docs/zh_CN/image_recognition_pipeline/mainbody_detection.md)
     - [特征提取模型](./docs/zh_CN/image_recognition_pipeline/feature_extraction.md)
     - [向量检索](./docs/zh_CN/image_recognition_pipeline/vector_search.md)
-    - [哈希编码](docs/zh_CN/image_recognition_pipeline/)
-  - [模型训练](docs/zh_CN/models_training/recognition.md)
-  - 推理部署
+    - [哈希编码](docs/zh_CN/image_recognition_pipeline/deep_hashing.md)
+  - PipeLine 推理部署
     - [基于python预测引擎推理](docs/zh_CN/inference_deployment/python_deploy.md#2)
     - [基于C++预测引擎推理](deploy/cpp_shitu/readme.md)
     - [服务化部署](docs/zh_CN/inference_deployment/recognition_serving_deploy.md)
     - [端侧部署](docs/zh_CN/inference_deployment/lite_shitu.md)
     - [库管理工具](docs/zh_CN/inference_deployment/shitu_gallery_manager.md)
- - [20+应用场景库](docs/zh_CN/introduction/ppshitu_application_scenarios.md)
 - [PULC超轻量图像分类实用方案](docs/zh_CN/PULC/PULC_train.md)
   - [超轻量图像分类快速体验](docs/zh_CN/PULC/PULC_quickstart.md)
   - [超轻量图像分类模型库](docs/zh_CN/PULC/PULC_model_list.md)

docs/zh_CN/algorithm_introduction/deep_hashing_introduction.md

+# Deep Hashing算法介绍
+----
+## 目录
+
+* [1. 简介](#1)
+* [2. 算法介绍](#2)
+    * [2.1 DCH](#2.1)
+    * [2.2 DSHSD](#2.2)
+    * [2.3 LCDSH](#2.3)
+* [3. 快速体验](#3)
+* [4. 总结及建议](#4)
+
+<a name='1'></a>
+## 1. 简介
+
+最近邻搜索是指在数据库中查找与查询数据距离最近的点，在计算机视觉、推荐系统、机器学习等领域中广泛使用。在PP-ShiTu中，输入图像经过主体检测模型去掉背景后，再经过特征提取模型提取特征，之后经过检索得到检索图像等类别。在这个过程中，一般来说，提取的特征是float32数据类型。当离线特征库中存储的feature比较多时，就占用较大的存储空间，同时检索过程也会变慢。如果利用哈希编码将特征由float32转成0或者1表示的二值特征，那么不仅降低存储空间，同时也能大大加快检索速度。
+
+<a name='2'></a>
+## 2. 算法介绍
+
+目前PaddleClas中，主要复现了三种DeepHash的方法，分别是：[DCH](http://ise.thss.tsinghua.edu.cn/~mlong/doc/deep-cauchy-hashing-cvpr18.pdf)，[DSHSD](https://ieeexplore.ieee.org/document/8648432/), [LCDSH](https://www.ijcai.org/Proceedings/2017/0499.pdf)。以下做简要介绍。
+
+<a name='2.1'></a>
+## 2.1 DCH
+
+此方法基于柯西分布，提出一种成对的交叉熵损失函数，能够较好的得到紧密的hamming特征。在多个数据集上取得较好的结果。详见[论文](http://ise.thss.tsinghua.edu.cn/~mlong/doc/deep-cauchy-hashing-cvpr18.pdf)。方法示意图如下：
+
+<div align="center">
+<img src="../../images/deep_hash/DCH.png"  width = "400" />
+</div>
+
+<a name='2.2'></a>
+## 2.2 DSHSD
+
+DSHSD主要创新点在于，在保证分布一致性的情况下消除差异。首先，作者利用平滑投影函数来放松离散约束，而不是使用任何量化正则化器，其中平滑量是可调整的。其次，在平滑投影和特征分布之间建立数学联系，以保持分布的一致性。进而提出了一种多语义信息融合方法，使hash码学习后能够保留更多的语义信息，从而加快训练收敛速度。其方法在在CIFAR-10、NUS-WIDE和ImageNet数据集上的大量实验表现良好。具体可查看[论文](https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8648432)。
+
+<div align="center">
+<img src="../../images/deep_hash/DSHSD.png"  width = "400" />
+</div>
+
+<a name='2.3'></a>
+## 2.3 LCDSH
+
+LCDSH是一种局部约束深度监督哈希算法。该方案通过学习图像对之间的相似特征使得，哈希码保持了DCNN特征的分布，从而有利于准确的图像检索。具体可查看[论文](https://www.ijcai.org/Proceedings/2017/0499.pdf)。
+
+<div align="center">
+<img src="../../images/deep_hash/LCDSH.png"  width = "400" />
+</div>
+
+<a name='3'></a>
+## 3. 快速体验
+
+这个三个哈希算法的配置文件具体位置：
+`DCH`: ppcls/configs/DeepHash/DCH.yaml
+`DSHSD`: ppcls/configs/DeepHash/DSHSD.yaml
+`LCDSH`: ppcls/configs/DeepHash/LCDSH.yaml
+
+具体训练方法，请参考[分类模型训练文档](../models_training/classification.md)
+
+<a name='4'></a>
+## 4. 总结及建议
+
+不同的DeepHash方法，具有不同特性。可以分别对不同的哈希方法进行尝试，选取最合适自己数据集的方法。

docs/zh_CN/image_recognition_pipeline/deep_hashing.md

+# 哈希编码
+
+最近邻搜索是指在数据库中查找与查询数据距离最近的点，在计算机视觉、推荐系统、机器学习等领域中广泛使用。在`PP-ShiTu`中，输入图像经过主体检测模型去掉背景后，再经过特征提取模型提取特征，之后经过检索得到输入图像的类别。在这个过程中，一般来说，提取的特征是`float32`数据类型。当离线特征库中存储的`feature`比较多时，就占用较大的存储空间，同时检索过程也会变慢。如果利用`哈希编码`将特征由`float32`转成`0`或者`1`表示的二值特征，那么不仅降低存储空间，同时也能大大加快检索速度。
+
+哈希编码，主要用在`PP-ShiTu`的**特征提取模型**部分，将模型输出特征直接二值化。即训练特征提取模型时，将模型的输出映射到二值空间。
+
+注意，由于使用二值特征表示图像特征，精度可能会下降，请根据实际情况，酌情使用。
+
+
+## 目录
+
+- [1. 特征模型二值特征训练](#1)
+	- [1.1 PP-ShiTu特征提取模型二值训练](#1.1)
+	- [1.2 其他特征模型二值训练](#1.2)
+- [2. 检索算法配置](#2)
+
+<a name="1"></a>
+
+## 1. 特征模型二值特征训练
+
+<a name="1.1"></a>
+
+注意，此模块目前只支持`PP-ShiTuV1`,`PP-ShiTuV2`暂未适配。
+
+### 1.1 PP-ShiTu特征提取模型二值训练
+
+PP-ShiTu特征提取模型二值特征模型，配置文件位于`ppcls/configs/GeneralRecognition/GeneralRecognition_PPLCNet_x2_5_binary.yaml`，相关训练方法如下。
+
+```shell
+# 单卡 GPU
+python3.7 tools/train.py \
+-c ./ppcls/configs/GeneralRecognition/GeneralRecognition_PPLCNet_x2_5_binary.yaml \
+-o Arch.Backbone.pretrained=True \
+-o Global.device=gpu
+
+# 多卡 GPU
+export CUDA_VISIBLE_DEVICES=0,1,2,3
+python3.7 -m paddle.distributed.launch tools/train.py \
+-c ppcls/configs/GeneralRecognition/GeneralRecognition_PPLCNet_x2_5_binary.yaml \
+-o Arch.Backbone.pretrained=True \
+-o Global.device=gpu
+```
+
+其中`数据准备`、`模型评估`等，请参考[此文档](https://github.com/PaddlePaddle/PaddleClas/blob/release/2.4/docs/zh_CN/models_training/recognition.md)。
+
+<a name="1.2"></a>
+
+### 1.2 其他特征模型二值训练
+
+其他二值特征训练模型的配置文件位于`ppcls/configs/DeepHash/`文件夹下，此文件夹下的相关配置文件主要是复现相关`deep hashing`相关算法。包括：`DCH, DSHSD, LCDSH`三种算法。这三种算法相关介绍，详见[Deep Hashing相关算法介绍](../algorithm_introduction/deep_hashing_introduction.md)。
+
+相关训练方法，请参考[分类模型训练文档](../models_training/classification.md)。
+
+<a name="2"></a>
+
+## 2. 检索算法配置
+
+在PP-ShiTu中使用二值特征，部署及离线推理配置请参考`deploy/configs/inference_general_binary.yaml`。配置文件中相关参数介绍请参考[向量检索文档](./vector_search.md).
+
+其中需值得注意的是，二值检索相关配置应设置如下：
+
+```yaml
+IndexProcess:
+  index_method: "FLAT" # supported: HNSW32, IVF, Flat
+  delimiter: "\t"
+  dist_type: "hamming"
+  hamming_radius: 100
+```
+
+其中`hamming_radius`可以根据自己实际精度要求，适当调节。

docs/zh_CN/image_recognition_pipeline/mainbody_detection.md

@@ -70,9 +70,9 @@ PicoDet 由 [PaddleDetection](https://github.com/PaddlePaddle/PaddleDetection)
 - [ATSS](https://arxiv.org/abs/1912.02424)及[SimOTA](https://arxiv.org/abs/2107.08430) 标签分配策略
 
 
-更多关于 PicoDet 的优化细节与 benchmark 可以参考 [PicoDet 系列模型介绍](https://github.com/PaddlePaddle/PaddleDetection/tree/release/2.5/configs/picodet)。
+更多关于 PicoDet 的优化细节与 benchmark 可以参考 [PicoDet 系列模型介绍](https://github.com/PaddlePaddle/PaddleDetection/tree/release/2.3/configs/picodet)。
 
-在轻量级主体检测任务中，为了更好地兼顾检测速度与效果，我们使用 PPLCNet_x2_5 作为主体检测模型的骨干网络，同时将训练与预测的图像尺度修改为了 640x640，其余配置与 [picodet_lcnet_1_5x_416_coco.yml](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/configs/picodet/picodet_l_416_coco_lcnet.yml) 完全一致。将数据集更换为自定义的主体检测数据集，进行训练，最终得到检测模型。
+在轻量级主体检测任务中，为了更好地兼顾检测速度与效果，我们使用 PPLCNet_x2_5 作为主体检测模型的骨干网络，同时将训练与预测的图像尺度修改为了 640x640，其余配置与 [picodet_l_416_coco.yml](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.3/configs/picodet/picodet_l_416_coco.yml) 完全一致。将数据集更换为自定义的主体检测数据集，进行训练，最终得到检测模型。
 
 <a name="3"></a>
 
@@ -89,19 +89,20 @@ PicoDet 由 [PaddleDetection](https://github.com/PaddlePaddle/PaddleDetection)
 ```shell
 cd <path/to/clone/PaddleDetection>
 git clone https://github.com/PaddlePaddle/PaddleDetection.git
-
 cd PaddleDetection
+# 切换到2.3分支
+git checkout release/2.3
 # 安装其他依赖
 pip install -r requirements.txt
 ```
 
-更多安装教程，请参考: [安装文档](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/docs/tutorials/INSTALL_cn.md)
+更多安装教程，请参考: [安装文档](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.3/docs/tutorials/INSTALL_cn.md)
 
 <a name="3.2"></a>
 
 ### 3.2 数据准备
 
-对于自定义数据集，首先需要将自己的数据集修改为 COCO 格式，可以参考[自定义检测数据集教程](https://github.com/PaddlePaddle/PaddleDetection/tree/release/2.5/docs/tutorials/data)制作 COCO 格式的数据集。
+对于自定义数据集，首先需要将自己的数据集修改为 COCO 格式，可以参考[自定义检测数据集教程](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.3/docs/tutorials/PrepareDataSet.md)制作 COCO 格式的数据集。
 
 主体检测任务中，所有的检测框均属于前景，在这里需要将标注文件中，检测框的 `category_id` 修改为 1，同时将整个标注文件中的 `categories` 映射表修改为下面的格式，即整个类别映射表中只包含`前景`类别。
 
@@ -113,7 +114,7 @@ pip install -r requirements.txt
 
 ### 3.3 配置文件改动和说明
 
-我们使用 [mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml) 配置进行训练，配置文件摘要如下：
+我们使用 [mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.3/configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml) 配置进行训练，配置文件摘要如下：
 
 ![](../../images/det/PaddleDetection_config.png)
 
@@ -144,14 +145,14 @@ PaddleDetection 提供了单卡/多卡训练模式，满足用户多种训练需
 ```bash
 # windows 和 Mac 下不需要执行该命令
 export CUDA_VISIBLE_DEVICES=0
-python tools/train.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml
+python tools/train.py -c configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml
 ```
 
 * GPU 多卡训练
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0,1,2,3
-python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --eval
+python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/picodet/legacy_model/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --eval
 ```
 
 --eval：表示边训练边验证。
@@ -163,7 +164,7 @@ python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/pic
 ```bash
 export CUDA_VISIBLE_DEVICES=0
 # 指定 pretrain_weights 参数，加载通用的主体检测预训练模型
-python tools/train.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml -o pretrain_weights=https://paddledet.bj.bcebos.com/models/picodet_lcnet_x2_5_640_mainbody.pdparams
+python tools/train.py -c configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml -o pretrain_weights=https://paddledet.bj.bcebos.com/models/picodet_lcnet_x2_5_640_mainbody.pdparams
 ```
 
 * 模型恢复训练
@@ -172,7 +173,7 @@ python tools/train.py -c configs/picodet/legacy_model/application/mainbody_detec
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0,1,2,3
-python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --eval -r output/picodet_lcnet_x2_5_640_mainbody/20
+python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --eval -r output/picodet_lcnet_x2_5_640_mainbody/20
 ```
 
 注意：
@@ -189,7 +190,7 @@ python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/pic
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0
-python tools/infer.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --infer_img=your_image_path.jpg --output_dir=infer_output/ --draw_threshold=0.5 -o weights=output/picodet_lcnet_x2_5_640_mainbody/model_final
+python tools/infer.py -c configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --infer_img=your_image_path.jpg --output_dir=infer_output/ --draw_threshold=0.5 -o weights=output/picodet_lcnet_x2_5_640_mainbody/model_final
 ```
 
 `--draw_threshold` 是个可选参数. 根据 [NMS](https://ieeexplore.ieee.org/document/1699659) 的计算，不同阈值会产生不同的结果 `keep_top_k` 表示设置输出目标的最大数量，默认值为 100，用户可以根据自己的实际情况进行设定。
@@ -204,7 +205,7 @@ python tools/infer.py -c configs/picodet/legacy_model/application/mainbody_detec
 执行导出模型脚本：
 
 ```bash
-python tools/export_model.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --output_dir=./inference -o weights=output/picodet_lcnet_x2_5_640_mainbody/model_final.pdparams
+python tools/export_model.py -c configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml --output_dir=./inference -o weights=output/picodet_lcnet_x2_5_640_mainbody/model_final.pdparams
 ```
 
 预测模型会导出到 `inference/picodet_lcnet_x2_5_640_mainbody` 目录下，分别为 `infer_cfg.yml` (预测不需要), `model.pdiparams`, `model.pdiparams.info`, `model.pdmodel` 。
@@ -224,7 +225,7 @@ python tools/export_model.py -c configs/picodet/legacy_model/application/mainbod
 
 <a name="4.3"></a>
 ### 4.3 其他推理方式
-其他推理方法，如C++推理部署、PaddleServing部署等请参考[检测模型推理部署](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/deploy/README.md)。
+其他推理方法，如C++推理部署、PaddleServing部署等请参考[检测模型推理部署](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.3/deploy/README.md)。
 
 
 ### FAQ

docs/zh_CN/inference_deployment/lite_shitu.md

@@ -198,8 +198,10 @@ cd $code_path
 git clone https://github.com/PaddlePaddle/PaddleDetection.git
 # 进入PaddleDetection根目录
 cd PaddleDetection
+# 切换到2.3分支
+git checkout release/2.3
 # 将预训练模型导出为inference模型
-python tools/export_model.py -c configs/picodet/legacy_model/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml -o weights=https://paddledet.bj.bcebos.com/models/picodet_lcnet_x2_5_640_mainbody.pdparams export_post_process=False --output_dir=inference
+python tools/export_model.py -c configs/picodet/application/mainbody_detection/picodet_lcnet_x2_5_640_mainbody.yml -o weights=https://paddledet.bj.bcebos.com/models/picodet_lcnet_x2_5_640_mainbody.pdparams export_post_process=False --output_dir=inference
 # 将inference模型转化为Paddle-Lite优化模型
 paddle_lite_opt --model_file=inference/picodet_lcnet_x2_5_640_mainbody/model.pdmodel --param_file=inference/picodet_lcnet_x2_5_640_mainbody/model.pdiparams --optimize_out=inference/picodet_lcnet_x2_5_640_mainbody/mainbody_det
 # 将转好的模型复制到lite_shitu目录下

docs/zh_CN/inference_deployment/shitu_gallery_manager.md

@@ -2,6 +2,12 @@
 
 本工具是PP-ShiTu的离线库管理工具，主要功能包括：新建图像库、更改图像库、建立索引库、更新索引库等功能。此工具是为了用户能够可视化的管理图像及对应的index库，用户可根据实际情况，灵活的增删改查相应的gallery图像库及索引文件，在提升用户体验的同时，辅助PP-ShiTu在实际应用的过程中达到更好的效果。
 
+目前此工具支持平台包括：
+
+- Mac
+- Windows
+- Linux（注意，由于linux输入法问题，可能无法支持中文）
+
 ## 目录
 
 - [1. 功能介绍](#1)