Merge pull request #1980 from RainFrost1/deploy_doc

update python inference doc

Merge pull request #1980 from RainFrost1/deploy_doc
update python inference doc
e956ac88 · cuicheng01 · GitHub · f4020359 · abfced46 · e956ac88
4 changed file
--- a/docs/images/algorithm_introduction/hnsw.png
+++ b/docs/images/algorithm_introduction/hnsw.png
--- a/docs/zh_CN/image_recognition_pipeline/mainbody_detection.md
+++ b/docs/zh_CN/image_recognition_pipeline/mainbody_detection.md
@@ -19,9 +19,13 @@
  - [3.3 配置文件改动和说明](#3.3)
  - [3.4 启动训练](#3.4)
  - [3.5 模型预测与调试](#3.5)
-  - [3.6 模型导出与预测部署](#3.6)
+- [4. 模型推理部署](#4)
+  - [4.1 推理模型准备](#4.1)
+  - [4.2 基于python预测引擎推理](#4.2)
+  - [4.3 其他推理方式](#4.3)

-<a name="1"></a> 
+
+<a name="1"></a>

 ## 1. 数据集

@@ -37,7 +41,7 @@

 在实际训练的过程中，将所有数据集混合在一起。由于是主体检测，这里将所有标注出的检测框对应的类别都修改为 `前景` 的类别，最终融合的数据集中只包含 1 个类别，即前景。

-<a name="2"></a> 
+<a name="2"></a>

 ## 2. 模型选择

@@ -55,7 +59,7 @@
  * 速度评测机器的 CPU 具体信息为：`Intel(R) Xeon(R) Gold 6148 CPU @ 2.40GHz`，速度指标为开启 mkldnn，线程数设置为 10 测试得到。
  * 主体检测的预处理过程较为耗时，平均每张图在上述机器上的时间在 40~55 ms 左右，没有包含在上述的预测耗时统计中。

-<a name="2.1"></a> 
+<a name="2.1"></a>

 ### 2.1 轻量级主体检测模型

@@ -72,7 +76,7 @@ PicoDet 由 [PaddleDetection](https://github.com/PaddlePaddle/PaddleDetection) 

 在轻量级主体检测任务中，为了更好地兼顾检测速度与效果，我们使用 PPLCNet_x2_5 作为主体检测模型的骨干网络，同时将训练与预测的图像尺度修改为了 640x640，其余配置与 [picodet_lcnet_1_5x_416_coco.yml](https://github.com/PaddlePaddle/PaddleDetection/blob/develop/configs/picodet/more_config/picodet_lcnet_1_5x_416_coco.yml) 完全一致。将数据集更换为自定义的主体检测数据集，进行训练，最终得到检测模型。

-<a name="2.2"></a> 
+<a name="2.2"></a>

 ### 2.2 服务端主体检测模型

@@ -93,13 +97,13 @@ PP-YOLO 由 [PaddleDetection](https://github.com/PaddlePaddle/PaddleDetection) 

 在服务端主体检测任务中，为了保证检测效果，我们使用 ResNet50vd-DCN 作为检测模型的骨干网络，使用配置文件 [ppyolov2_r50vd_dcn_365e_coco.yml](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.1/configs/ppyolo/ppyolov2_r50vd_dcn_365e_coco.yml)，更换为自定义的主体检测数据集，进行训练，最终得到检测模型。

-<a name="3"></a> 
+<a name="3"></a>

 ## 3. 模型训练

 本节主要介绍怎样基于 PaddleDetection，基于自己的数据集，训练主体检测模型。

-<a name="3.1"></a> 
+<a name="3.1"></a>

 ### 3.1 环境准备

@@ -116,7 +120,7 @@ pip install -r requirements.txt

 更多安装教程，请参考: [安装文档](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.1/docs/tutorials/INSTALL_cn.md)

-<a name="3.2"></a> 
+<a name="3.2"></a>

 ### 3.2 数据准备

@@ -128,7 +132,7 @@ pip install -r requirements.txt
 [{u'id': 1, u'name': u'foreground', u'supercategory': u'foreground'}]
 ```

-<a name="3.3"></a> 
+<a name="3.3"></a>

 ### 3.3 配置文件改动和说明

@@ -154,7 +158,7 @@ ppyolov2_reader.yml：主要说明数据读取器配置，如 batch size，并

 此外，也可以根据实际情况，修改上述文件，比如，如果显存溢出，可以将 batch size 和学习率等比缩小等。

-<a name="3.4"></a> 
+<a name="3.4"></a>

 ### 3.4 启动训练

@@ -198,7 +202,7 @@ python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/ppy

 注意：如果遇到 "`Out of memory error`" 问题, 尝试在 `ppyolov2_reader.yml` 文件中调小 `batch_size`，同时等比例调小学习率。

-<a name="3.5"></a> 
+<a name="3.5"></a>

 ### 3.5 模型预测与调试

@@ -211,9 +215,11 @@ python tools/infer.py -c configs/ppyolo/ppyolov2_r50vd_dcn_365e_coco.yml --infer

 `--draw_threshold` 是个可选参数. 根据 [NMS](https://ieeexplore.ieee.org/document/1699659) 的计算，不同阈值会产生不同的结果 `keep_top_k` 表示设置输出目标的最大数量，默认值为 100，用户可以根据自己的实际情况进行设定。

-<a name="3.6"></a> 
+<a name="4"></a>
+## 4. 模型推理部署

-### 3.6 模型导出与预测部署。
+<a name="4.1"></a>
+### 4.1 推理模型准备

 执行导出模型脚本：

@@ -225,15 +231,21 @@ python tools/export_model.py -c configs/ppyolo/ppyolov2_r50vd_dcn_365e_coco.yml

 注意： `PaddleDetection` 导出的 inference 模型的文件格式为 `model.xxx`，这里如果希望与 PaddleClas 的 inference 模型文件格式保持一致，需要将其 `model.xxx` 文件修改为 `inference.xxx` 文件，用于后续主体检测的预测部署。

-更多模型导出教程，请参考： [EXPORT_MODEL](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.1/deploy/EXPORT_MODEL.md)
+更多模型导出教程，请参考： [EXPORT_MODEL](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.4/deploy/EXPORT_MODEL.md)

 最终，目录 `inference/ppyolov2_r50vd_dcn_365e_coco` 中包含 `inference.pdiparams`, `inference.pdiparams.info` 以及 `inference.pdmodel` 文件，其中 `inference.pdiparams` 为保存的 inference 模型权重文件，`inference.pdmodel` 为保存的 inference 模型结构文件。

+<a name="4.2"></a>
+### 4.2 基于python预测引擎推理

 导出模型之后，在主体检测与识别任务中，就可以将检测模型的路径更改为该 inference 模型路径，完成预测。

 以商品识别为例，其配置文件为 [inference_product.yaml](../../../deploy/configs/inference_product.yaml)，修改其中的 `Global.det_inference_model_dir` 字段为导出的主体检测 inference 模型目录，参考[图像识别快速开始教程](../quick_start/quick_start_recognition.md)，即可完成商品检测与识别过程。

+<a name="4.3"></a>
+### 4.3 其他推理方式
+其他推理方法，如C++推理部署、PaddleServing部署等请参考[检测模型推理部署](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.4/deploy/README.md)。
+

 ### FAQ


--- a/docs/zh_CN/image_recognition_pipeline/vector_search.md
+++ b/docs/zh_CN/image_recognition_pipeline/vector_search.md
 # 向量检索

+## 目录
+
+- [1. 向量检索应用场景介绍](#1)
+- [2. 向量检索算法介绍](#2)
+	- [2.1 HNSW](#2.1)
+	- [2.2 IVF](#2.2)
+	- [2.3 FLAT](#2.3)
+- [3. 检索库安装](#3)
+- [4. 使用及配置文档介绍](#4)
+	- [4.1 建库及配置文件参数](#4.1)
+	- [4.2 检索配置文件参数](#4.2)
+
+
+<a name="1"></a>
+## 1. 向量检索应用场景介绍
+
 向量检索技术在图像识别、图像检索中应用比较广泛。其主要目标是，对于给定的查询向量，在已经建立好的向量库中，与库中所有的待查询向量，进行特征向量的相似度或距离计算，得到相似度排序。在图像识别系统中，我们使用 [Faiss](https://github.com/facebookresearch/faiss) 对此部分进行支持，具体信息请详查 [Faiss 官网](https://github.com/facebookresearch/faiss)。`Faiss` 主要有以下优势

 - 适配性好：支持 Windos、Linux、MacOS 系统
@@ -20,17 +36,33 @@

 --------------------------

-## 目录
+<a name="2"></a>
+## 2. 使用的检索算法
+
+目前 `PaddleClas` 中检索模块，支持三种检索算法**HNSW32**、**IVF**、**FLAT**。每种检索算法，满足不同场景。其中 `HNSW32` 为默认方法，此方法的检索精度、检索速度可以取得一个较好的平衡，具体算法介绍可以查看[官方文档](https://github.com/facebookresearch/faiss/wiki)。
+
+<a name="2.1"></a>
+### 2.1 HNSW方法
+
+此方法为图索引方法，如下图所示，在建立索引的时候，分为不同的层，所以检索精度较高，速度较快，但是特征库只支持添加图像功能，不支持删除图像特征功能。基于图的向量检索算法在向量检索的评测中性能都是比较优异的。如果比较在乎检索算法的效率，而且可以容忍一定的空间成本，多数场景下比较推荐基于图的检索算法。而HNSW是一种典型的，应用广泛的图算法，很多分布式检索引擎都对HNSW算法进行了分布式改造，以应用于高并发，大数据量的线上查询。此方法为默认方法。
+<div align="center">
+<img src="../../images/algorithm_introduction/hnsw.png"  width = "400" />
+</div>
+
+<a name="2.2"></a>
+### 2.2 IVF

- [1. 检索库安装](#1)
- [2. 使用的检索算法](#2)
- [3. 使用及配置文档介绍](#3)
-  - [3.1 建库及配置文件参数](#3.1)
-  - [3.2 检索配置文件参数](#3.2)
+一种倒排索引检索方法。速度较快，但是精度略低。特征库支持增加、删除图像特征功能。IVF主要利用倒排的思想保存每个聚类中心下的向量，每次查询向量的时候找到最近的几个中心，分别搜索这几个中心下的向量。通过减小搜索范围，大大提升搜索效率。

-<a name="1"></a> 
+<a name="2.3"></a>
+### 2.3 FLAT

-## 1. 检索库安装
+暴力检索算法。精度最高，但是数据量大时，检索速度较慢。特征库支持增加、删除图像特征功能。
+
+
+<a name="3"></a>
+
+## 3. 检索库安装

 `Faiss` 具体安装方法如下：

@@ -40,27 +72,16 @@ pip install faiss-cpu==1.7.1post2

 若使用时，不能正常引用，则 `uninstall` 之后，重新 `install`，尤其是 `windows` 下。

-<a name="2"></a> 
-
-## 2. 使用的检索算法
-
-目前 `PaddleClas` 中检索模块，支持如下三种检索算法
-
- **HNSW32**: 一种图索引方法。检索精度较高，速度较快。但是特征库只支持添加图像功能，不支持删除图像特征功能。（默认方法）
- **IVF**：倒排索引检索方法。速度较快，但是精度略低。特征库支持增加、删除图像特征功能。
- **FLAT**： 暴力检索算法。精度最高，但是数据量大时，检索速度较慢。特征库支持增加、删除图像特征功能。
-
-每种检索算法，满足不同场景。其中 `HNSW32` 为默认方法，此方法的检索精度、检索速度可以取得一个较好的平衡，具体算法介绍可以查看[官方文档](https://github.com/facebookresearch/faiss/wiki)。

-<a name="3"></a> 
+<a name="4"></a>

-## 3. 使用及配置文档介绍
+## 4. 使用及配置文档介绍

-涉及检索模块配置文件位于：`deploy/configs/` 下，其中 `build_*.yaml` 是建立特征库的相关配置文件，`inference_*.yaml` 是检索或者分类的推理配置文件。
+涉及检索模块配置文件位于：`deploy/configs/` 下，其中 `inference_*.yaml` 是检索或者分类的推理配置文件,同时也是建立特征库的相关配置文件。

-<a name="3.1"></a> 
+<a name="4.1"></a>

-### 3.1 建库及配置文件参数
+### 4.1 建库及配置文件参数

 建库的具体操作如下：

@@ -68,14 +89,14 @@ pip install faiss-cpu==1.7.1post2
 # 进入 deploy 目录
 cd deploy
 # yaml 文件根据需要改成自己所需的具体 yaml 文件
-python python/build_gallery.py -c configs/build_***.yaml
+python python/build_gallery.py -c configs/inference_***.yaml
 ```

 其中 `yaml` 文件的建库的配置如下，在运行时，请根据实际情况进行修改。建库操作会将根据 `data_file` 的图像列表，将 `image_root` 下的图像进行特征提取，并在 `index_dir` 下进行存储，以待后续检索使用。

 其中 `data_file` 文件存储的是图像文件的路径和标签，每一行的格式为：`image_path  label`。中间间隔以 `yaml` 文件中 `delimiter` 参数作为间隔。

-关于特征提取的具体模型参数，可查看 `yaml` 文件。
+关于特征提取的具体模型参数，可查看 `yaml` 文件。注意下面的配置参数只列举了建立索引库相关部分。

 ```yaml
 # indexing engine config
@@ -88,6 +109,7 @@ IndexProcess:
  delimiter: "\t"
  dist_type: "IP"
  embedding_size: 512
+  batch_size: 32
 ```

 - **index_method**：使用的检索算法。目前支持三种，HNSW32、IVF、Flat
@@ -98,23 +120,29 @@ IndexProcess:
 - **delimiter**：**data_file** 中每一行的间隔符
 - **dist_type**: 特征匹配过程中使用的相似度计算方式。例如 `IP` 内积相似度计算方式，`L2` 欧式距离计算方法
 - **embedding_size**：特征维度
+- **batch_size**：建立特征库时，特征提取的`batch_size`

-<a name="3.2"></a> 
+<a name="4.2"></a>
+
+### 4.2 检索配置文件参数

-### 3.2 检索配置文件参数

 将检索的过程融合到 `PP-ShiTu` 的整体流程中，请参考 [README](../../../README_ch.md) 中 `PP-ShiTu 图像识别系统介绍` 部分。检索具体使用操作请参考[识别快速开始文档](../quick_start/quick_start_recognition.md)。

 其中，检索部分配置如下，整体检索配置文件，请参考 `deploy/configs/inference_*.yaml` 文件。

+注意：此部分参数只是列举了离线检索相关部分参数。
+
 ```yaml
 IndexProcess:
  index_dir: "./recognition_demo_data_v1.1/gallery_logo/index/"
  return_k: 5
  score_thres: 0.5
+  hamming_radius: 100
 ```

 与建库配置文件不同，新参数主要如下：

 - `return_k`: 检索结果返回 `k` 个结果
 - `score_thres`: 检索匹配的阈值
+- `hamming_radius`: 汉明距离半径。此参数只有在使用二值特征模型，`dist_type`设置为`hamming`时才能生效。具体二值特征模型使用方法请参考[哈希编码](./deep_hashing.md)
--- a/docs/zh_CN/inference_deployment/python_deploy.md
+++ b/docs/zh_CN/inference_deployment/python_deploy.md
@@ -6,10 +6,11 @@

 ## 目录

- [1. 图像分类推理](#1)
- [2. 主体检测模型推理](#2)
- [3. 特征提取模型推理](#3)
- [4. 主体检测、特征提取和向量检索串联](#4)
+- [1. 图像分类模型推理](#1)
+- [2. PP-ShiTu模型推理](#2)
+	- [2.1 主体检测模型推理](#2.1)
+	- [2.2 特征提取模型推理](#2.2)
+	- [2.3 PP-ShiTu PipeLine推理](#2.3)

 <a name="1"></a>
 ## 1. 图像分类推理
@@ -42,7 +43,12 @@ python python/predict_cls.py -c configs/inference_cls.yaml
 * 如果你希望提升评测模型速度，使用 GPU 评测时，建议开启 TensorRT 加速预测，使用 CPU 评测时，建议开启 MKL-DNN 加速预测。

 <a name="2"></a>
-## 2. 主体检测模型推理
+## 2. PP-ShiTu模型推理
+
+PP-ShiTu整个Pipeline包含三部分：主体检测、特提取模型、特征检索。其中主体检测、特征模型可以单独推理使用。单独主体检测详见[2.1](#2.1)，特征提取模型单独推理详见[2.2](#2.2)， PP-ShiTu整体推理详见[2.3](#2.3)。
+
+<a name="2.1"></a>
+### 2.1 主体检测模型推理

 进入 PaddleClas 的 `deploy` 目录下：

@@ -70,8 +76,8 @@ python python/predict_det.py -c configs/inference_det.yaml
 * `Global.use_gpu`： 是否使用 GPU 预测，默认为 `True`。


-<a name="3"></a>
-## 3. 特征提取模型推理
+<a name="2.2"></a>
+### 2.2 特征提取模型推理

 下面以商品特征提取为例，介绍特征提取模型推理。首先进入 PaddleClas 的 `deploy` 目录下：

@@ -90,7 +96,7 @@ tar -xf ./models/product_ResNet50_vd_aliproduct_v1.0_infer.tar -C ./models/

 上述预测命令可以得到一个 512 维的特征向量，直接输出在在命令行中。

-<a name="4"></a>
-## 4. 主体检测、特征提取和向量检索串联
+<a name="2.3"></a>
+### 2.3. PP-ShiTu PipeLine推理

 主体检测、特征提取和向量检索的串联预测，可以参考图像识别[快速体验](../quick_start/quick_start_recognition.md)。