PP-ShiTuV2 Image Recognition System in PaddleClas: Architecture, Training, and End-to-End Deployment Guide
PP-ShiTuV2 Image Recognition System in PaddleClas: Architecture, Training, and End-to-End Deployment Guide
PP-ShiTuV2 是 PaddleClas 中基于 PaddlePaddle 打造的轻量级通用图像识别系统，由主体检测（mainbody detection）、特征提取（feature extraction）与向量检索（vector search）三大模块串联而成。本文以仓库中的官方介绍文档（docs/en/PPShiTu/PPShiTuV2_introduction.md）为主线，结合仓库内真实训练配置、模型变体源码与部署脚本，系统讲解 PP-ShiTuV2 的模型组成、相对 V1 的精度提升、快速体验方式、各模块训练细节，以及基于 Paddle Inference / C++ / Serving / Lite / ONNX 的完整部署链路。读完本文，你将掌握从零跑通一条"检测 → 提特征 → 建索引 → 检索识别"的图像识别流水线的全部关键步骤，并能依据源码级配置说明自行定制与调优。
1. PP-ShiTuV2 系统概览与相对 V1 的改进
PP-ShiTuV2 是在 PP-ShiTuV1 基础上升级而来的实用型轻量通用图像识别系统，其整体流水线由三个模块组成：
- 主体检测（Mainbody Detection）：检测图像中一个或多个目标物体的坐标位置，并将对应区域裁剪出来送入识别流程，用于去除复杂背景、提升识别精度；
- 特征提取（Feature Extraction）：将裁剪后的图像转换为固定维度的特征向量，供后续向量检索使用；
- 向量检索（Vector Search）：在已建好的向量数据库中，计算查询向量与库内向量的相似度/距离，返回候选向量的相似度排序结果。
与 PP-ShiTuV1 相比，PP-ShiTuV2 在识别精度更高、泛化能力更强的前提下保持了相近的推理速度，主要优化点集中在训练数据集、更强的主干网络、损失函数与训练策略上，从而显著提升了多个实际应用场景下的检索性能。其系统结构如下图所示（docs/images/structure.jpg）：
官方文档给出的 PP-ShiTuV1 与 PP-ShiTuV2 指标对比如下：
| model | storage (mainbody detection + feature extraction) | product recall@1 |
|---|---|---|
| PP-ShiTuV1 | 64(30+34)MB | 66.8% |
| PP-ShiTuV2 | 49(30+19)MB | 73.8% |
说明：
- recall 与 mAP 等检索指标的定义可参考 Retrieval Metric 文档；
- 上述延迟数据基于 Intel(R) Xeon(R) Gold 6148 CPU @ 2.40GHz，启用 MKLDNN 加速策略，线程数为 10。
2. 快速体验 PP-ShiTuV2
2.1 Android Demo 快速体验
扫描二维码或点击官方 APK 下载链接安装 PP-ShiTu Android Demo 应用，将如下示例图片保存到手机相册：
打开已安装的 APP，点击下方的 "file recognition"（文件识别） 按钮，选择上述保存的图片，即可得到如下识别结果：
2.2 命令行快速体验
命令行体验分三步：安装依赖 → 安装 paddleclas whl 包 → 下载演示数据并执行识别。
第一步：安装 paddlepaddle 与 faiss
# 若机器已安装 CUDA9 或 CUDA10，执行以下命令安装 GPU 版
python3.7 -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple
# 若机器为 CPU 环境，执行以下命令安装 CPU 版
python3.7 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
# 安装 faiss 向量检索数据库
python3.7 -m pip install faiss-cpu==1.7.1post2
第二步：安装 paddleclas whl 包
# 进入 PaddleClas 仓库根目录
cd PaddleClas
# 以可编辑模式安装 paddleclas
pip install -v -e .
第三步：下载演示数据并执行识别
# 下载并解压演示数据 drink_dataset_v2.0
wget -nc https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/data/drink_dataset_v2.0.tar && tar -xf drink_dataset_v2.0.tar
# 执行识别命令
paddleclas \
--model_name=PP-ShiTuV2 \
--infer_imgs=./drink_dataset_v2.0/test_images/100.jpeg \
--index_dir=./drink_dataset_v2.0/index/ \
--data_file=./drink_dataset_v2.0/gallery/drink_label.txt
其中 --model_name=PP-ShiTuV2 指定使用 PP-ShiTuV2 预置模型，--index_dir 指向预构建的向量索引目录，--data_file 指向图库标注文件。
3. 三大模块详解与训练
3.1 主体检测（Mainbody Detection）
主体检测是一种应用广泛的检测技术：先检测出图像中一个或多个物体的坐标位置，再裁剪出对应区域用于后续识别，是整个识别任务的前置环节。经过主体检测后的输入图像可以去除复杂背景干扰，有效提升识别精度。
综合考虑检测速度、模型体积、检测精度等因素，PP-ShiTuV2 最终选用 PaddleDetection 团队开发的轻量模型 PicoDet-LCNet_x2_5 作为主体检测模型。
关于该检测模型的数据集、训练、评估、推理等完整细节，请参考文档：mainbody_detection_en.md。
3.2 特征提取（Feature Extraction）
特征提取是图像识别的关键环节，其作用是将输入图像转换为固定维度的特征向量，供后续向量检索使用。综合考虑特征提取模型的速度、体积与性能，PaddleClas 最终选用自研的 PPLCNetV2_base（详细模型说明见 PP-LCNetV2 文档）作为特征提取网络。与 PP-ShiTuV1 使用的 PPLCNet_x2_5 相比，PPLCNetV2_base 在基本保持高分类精度的同时，推理时间降低了约 40%。
注： 该推理数据基于 Intel(R) Xeon(R) Gold 6271C CPU @ 2.60GHz 硬件平台与 OpenVINO 推理平台。
实验发现，在保持推理速度基本不变的前提下，可以对 PPLCNetV2_base 做如下针对性改造，使其在识别任务上取得更高性能：
- 移除
PPLCNetV2_base末尾的ReLU与FC层； - 将最后一个 stage（RepDepthwiseSeparable）的 stride 改为 1。
上述改造在仓库源码 ppcls/arch/backbone/variant_models/pp_lcnetv2_variant.py 中以 PPLCNetV2_base_ShiTu 变体形式实现，源码注释明确列出了三处改动：移除 last_conv 后的 ReLU、为 last_conv 增加 bias、将最后两个 RepDepthwiseSeparable Block 的 stride 改为 1。该文件通过 upgrade_sublayer 机制分别以 ["act"]、["last_conv"]、["stages[3][0]", "stages[3][1]"] 三个 pattern 完成层替换，并在改造完成后重新加载预训练权重。
特征提取模型的训练配置位于 ppcls/configs/GeneralRecognitionV2/GeneralRecognitionV2_PPLCNetV2_base.yaml，从配置中可以还原完整的训练方案：
- 模型结构：
RecModel架构，主干为PPLCNetV2_base_ShiTu（开启 SSLD 预训练，class_expand设为 512），经flatten停止层后接BNNeck（输出 512 维特征，bias 以极小学习率1.0e-20冻结为 0），最终 Head 为FC（embedding_size=512，class_num=192612，对应大规模训练集类别数）； - 损失函数：训练阶段同时使用
CELoss（权重 1.0，epsilon=0.1 的标签平滑）与TripletAngularMarginLoss（margin=0.5，add_absolute绝对损失权重 0.1，ap_value=0.8、an_value=0.4，启用特征归一化）； - 优化器：Momentum（momentum=0.9）+ Cosine 学习率（初始 0.06，warmup 5 个 epoch，针对 8 GPU × 256 batch_size 设置）+ L2 正则（coeff=1e-5）；
- 数据采样：训练集使用
ImageNetDataset并relabel: True，采样器为PKSampler（batch_size=256，每 ID 采样 4 张，id_list与ratio控制类别采样策略）；训练增强包含 Resize 到 224、随机翻转、Pad、RandCropImageV2、RandomRotation（50% 概率、±90°）与 ImageNet 风格 Normalize； - 评估指标：Eval 模式为 retrieval，Query/Gallery 均使用
VeriWild数据集（Aliproduct 验证集），Metric.Eval配置Recallk（topk=[1, 5]）与mAP。
关于特征提取模型的数据集、训练、评估、推理等完整细节，请参考文档：feature_extraction_en.md。
3.3 向量检索（Vector Search）
向量检索技术在图像识别中应用广泛，其核心目标是对给定的查询向量，在已建立的向量数据库中计算特征向量的相似度或距离，并返回候选向量的相似度排序结果。
PP-ShiTuV2 识别系统选用 Faiss 开源向量检索库，其具备适应性好、安装简单、算法丰富、同时支持 CPU 与 GPU 等优点。
Faiss 在 PP-ShiTuV2 系统中的安装与使用细节，请参考文档：vector_search_en.md。
在仓库中，向量索引的构建逻辑位于 deploy/python/build_gallery.py，关键实现包括：
- 通过
split_datafile按分隔符（默认\t）解析图库标注文件data_file，得到gallery_images与gallery_docs； - 使用
RecPredictor批量提取图库特征（batch_size 默认 32）； - 依据
IndexProcess.index_method创建索引：默认HNSW32，支持IVF（自动计算 nlist 数量）与Flat；dist_type为IP时使用内积度量（faiss.METRIC_INNER_PRODUCT），为hamming时使用二值索引并给 index_method 加B前缀； - 支持三种索引操作：
new（新建，训练并写入）、append（追加，加载旧索引后add_with_ids）、remove（删除，remove_ids按 id_map 反向定位；注意HNSW32不支持 remove 操作，代码中会抛出 RuntimeError）； - 最终产出
vector.index与id_map.pkl两个文件，分别保存 faiss 索引与 id → 图库文本的映射。
4. 推理部署
4.1 推理模型准备
Paddle Inference 是 Paddle 原生推理引擎，可在服务器与云端提供高性能推理能力。相比直接基于预训练模型做预测，Paddle Inference 可借助 MKLDNN、CUDNN、TensorRT 等实现预测加速，获得更优推理性能。
使用 Paddle Inference 推理时，加载的模型类型为推理模型（inference model）。本案例提供两种获取方式；若希望得到与文档完全一致的结果，建议直接下载推理模型。
4.1.1 从预训练模型导出推理模型
主体检测推理模型的导出请参考 mainbody_detection_en.md。特征提取模型权重的导出命令如下：
python3.7 tools/export_model.py \
-c ./ppcls/configs/GeneralRecognitionV2/GeneralRecognitionV2_PPLCNetV2_base.yaml \
-o Global.pretrained_model="https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/models/pretrain/PPShiTuV2/general_PPLCNetV2_base_pretrained_v1.0.pdparams" \
-o Global.save_inference_dir=deploy/models/GeneralRecognitionV2_PPLCNetV2_base
执行后将在 deploy/models/ 下生成 GeneralRecognitionV2_PPLCNetV2_base 文件夹，结构如下：
deploy/models/
├── GeneralRecognitionV2_PPLCNetV2_base
│ ├── inference.pdiparams
│ ├── inference.pdiparams.info
│ └── inference.pdmodel
4.1.2 直接下载推理模型
cd deploy/models
# 下载主体检测推理模型并解压
wget -nc https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/models/inference/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_infer.tar && tar -xf picodet_PPLCNet_x2_5_mainbody_lite_v1.0_infer.tar
# 下载特征提取推理模型并解压
wget -nc https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/models/inference/PP-ShiTuV2/general_PPLCNetV2_base_pretrained_v1.0_infer.tar && tar -xf general_PPLCNetV2_base_pretrained_v1.0_infer.tar
4.2 测试数据准备
# 回到 ./deploy 目录
cd ../
# 下载测试数据 drink_dataset_v2.0 并解压
wget -nc https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/data/drink_dataset_v2.0.tar && tar -xf drink_dataset_v2.0.tar
4.3 基于 Python 推理引擎的预测
4.3.1 单张图片预测
# GPU 预测
python3.7 python/predict_system.py -c configs/inference_general.yaml -o Global.infer_imgs="./drink_dataset_v2.0/test_images/100.jpeg"
# CPU 预测
python3.7 python/predict_system.py -c configs/inference_general.yaml -o Global.infer_imgs="./drink_dataset_v2.0/test_images/100.jpeg" -o Global.use_gpu=False
最终输出如下：
[{'bbox': [437, 71, 660, 728], 'rec_docs': '元气森林', 'rec_scores': 0.7740249}, {'bbox': [221, 72, 449, 701], 'rec_docs': '元气森林', 'rec_scores': 0.6950992}, {'bbox': [794, 104, 979, 652], 'rec_docs': '元气森林', 'rec_scores': 0.6305153}]
灵活配置：跳过检测模块，整图直接提特征。 用户也可以选择不使用检测模型，直接将整张图像输入特征提取模型并计算特征向量用于检索，从而降低整体识别耗时：
# 整图预测（GPU）
python3.7 python/predict_system.py -c configs/inference_general.yaml -o Global.det_inference_model_dir=None
# 整图预测（CPU）
python3.7 python/predict_system.py -c configs/inference_general.yaml -o Global.use_gpu=False -o Global.det_inference_model_dir=None
输出如下：
INFO: find 'Global.det_inference_model_dir' empty(), so det_predictor is disabled
[{'bbox': [0, 0, 1200, 802], 'rec_docs': '元气森林', 'rec_scores': 0.5696486}]
从源码 deploy/python/predict_system.py 可以看到，SystemPredictor 在初始化时检测 Global.det_inference_model_dir 是否为空，为空则禁用 det_predictor；同时要求索引目录下必须存在 vector.index 与 id_map.pkl，并依据 IndexProcess.dist_type 选择 read_index_binary（hamming）或 read_index 加载 Faiss 索引。
predict 方法的完整调用链（predict_system.py）为：det 检测 → append_self 将整图补入结果（bbox 为全图 [0, 0, w, h]，score=1.0）以提升召回 → 对每个 bbox 裁剪区域做特征提取 → Searcher.search 检索 top-k → 按 score_thres（默认 0.5）过滤 → 最后按 Global.rec_nms_thresold（默认 0.05）做 NMS 去除重复结果。
4.3.2 多张图片预测
若需预测文件夹内全部图片，可直接修改配置文件的 Global.infer_imgs 字段，或通过 -o 参数覆盖：
# GPU 预测整个文件夹
python3.7 python/predict_system.py -c configs/inference_general.yaml -o Global.infer_imgs="./drink_dataset_v2.0/test_images"
# CPU 预测整个文件夹
python3.7 python/predict_system.py -c configs/inference_general.yaml -o Global.infer_imgs="./drink_dataset_v2.0/test_images" -o Global.use_gpu=False
终端将输出文件夹内所有图片的识别结果：
...
[{'bbox': [0, 0, 600, 600], 'rec_docs': '红牛-强化型', 'rec_scores': 0.74081033}]
Inference: 120.39852142333984 ms per batch image
[{'bbox': [0, 0, 514, 436], 'rec_docs': '康师傅矿物质水', 'rec_scores': 0.6918598}]
Inference: 32.045602798461914 ms per batch image
[{'bbox': [138, 40, 573, 1198], 'rec_docs': '乐虎功能饮料', 'rec_scores': 0.68214047}]
Inference: 113.41428756713867 ms per batch image
[{'bbox': [328, 7, 467, 272], 'rec_docs': '脉动', 'rec_scores': 0.60406065}]
Inference: 122.04337120056152 ms per batch image
[{'bbox': [242, 82, 498, 726], 'rec_docs': '味全_每日C', 'rec_scores': 0.5428652}]
Inference: 37.95266151428223 ms per batch image
[{'bbox': [437, 71, 660, 728], 'rec_docs': '元气森林', 'rec_scores': 0.7740249}, {'bbox': [221, 72, 449, 701], 'rec_docs': '元气森林', 'rec_scores': 0.6950992}, {'bbox': [794, 104, 979, 652], 'rec_docs': '元气森林', 'rec_scores': 0.6305153}]
...
其中 bbox 表示检测到的主体的边界框，rec_docs 表示索引库中与检测目标最相似的类别，rec_scores 表示对应的相似度。
关键配置速查： 上述 Python 推理使用的 deploy/configs/inference_general.yaml 中的核心参数及其默认值如下：
Global.det_inference_model_dir/Global.rec_inference_model_dir：检测与特征提取推理模型目录（分别指向下载或导出的picodet_PPLCNet_x2_5_mainbody_lite_v1.0_infer与general_PPLCNetV2_base_pretrained_v1.0_infer）；Global.rec_nms_thresold: 0.05：最终识别结果的 NMS 阈值；Global.image_shape: [3, 640, 640]/Global.batch_size: 1：检测输入尺寸与批大小（预测脚本断言 batch_size 必须为 1）；Global.threshold: 0.2、Global.max_det_results: 5：检测置信度阈值与最大检测框数；Global.use_gpu: True、Global.enable_mkldnn: True、Global.cpu_num_threads: 10、Global.use_tensorrt: False、Global.gpu_mem: 8000：推理后端与加速配置；DetPreProcess.transform_ops：检测前处理，DetResize到 640×640（keep_ratio=false）、DetNormalizeImage（ImageNet 均值和方差）、DetPermute；RecPreProcess.transform_ops：识别前处理，ResizeImage 到 224×224、NormalizeImage（scale 1/255）、ToCHWImage；IndexProcess.index_method: "HNSW32"（支持 HNSW32 / IVF / Flat）、IndexProcess.dist_type: "IP"、IndexProcess.embedding_size: 512、IndexProcess.index_operation: "new"（支持 append / remove / new）、IndexProcess.return_k: 5、IndexProcess.score_thres: 0.5：向量索引的构建与检索参数。
4.3 基于 C++ 推理引擎的预测
PaddleClas 提供了基于 C++ 预测引擎的推理示例，可参考 Server-side C++ prediction 完成对应推理部署。若使用 Windows 平台，可参考 Python 部署文档 完成预测库编译与模型预测工作。
4.4 Serving 部署
Paddle Serving 提供高性能、灵活易用的工业级在线推理服务，支持 RESTful、gRPC、bRPC 等多种协议，并提供多种异构硬件与操作系统环境下的推理方案。PaddleClas 提供了基于 Paddle Serving 的模型服务化部署示例，可参考 recognition_serving_deploy_en.md 完成对应部署。
4.5 Lite 部署
Paddle Lite 是一款高性能、轻量、灵活且易扩展的深度学习推理框架，定位是支持移动端、嵌入式与服务器等多种硬件平台。PP-ShiTu 的 Lite 端示例代码位于 deploy/lite_shitu，包含 C++ 实现的检测前处理、特征提取、向量检索与后处理模块。
4.6 Paddle2ONNX
Paddle2ONNX 支持将 PaddlePaddle 模型格式转换为 ONNX 模型格式，通过 ONNX 即可完成 Paddle 模型到 TensorRT / OpenVINO / MNN / TNN / NCNN 等各类推理引擎或支持 ONNX 开源格式的硬件的部署。PaddleClas 提供了基于 Paddle2ONNX 的模型转换与推理预测示例，可参考 Paddle2ONNX Model Conversion and Prediction 完成对应部署工作。
5. 总结与扩展阅读
PP-ShiTuV2 以"检测 → 特征提取 → 向量检索"三段式流水线为核心，通过轻量检测模型 PicoDet-LCNet_x2_5、经过识别任务改造的 PPLCNetV2_base_ShiTu 特征网络与 Faiss 高效索引，在 49MB 的存储占用下实现了 73.8% 的商品 recall@1，并覆盖 Android Demo、Python / C++ 推理、Serving、Lite 与 ONNX 全链路部署形态。
如需进一步深入，可继续阅读仓库内以下材料：
- 特征提取训练配置：ppcls/configs/GeneralRecognitionV2/GeneralRecognitionV2_PPLCNetV2_base.yaml
- 特征网络变体实现：ppcls/arch/backbone/variant_models/pp_lcnetv2_variant.py
- 推理配置：deploy/configs/inference_general.yaml
- 检索流水线实现：deploy/python/predict_system.py
- 索引构建实现：deploy/python/build_gallery.py
- 检测/特征/检索三篇专题文档：mainbody_detection_en.md、feature_extraction_en.md、vector_search_en.md
references
- Schall, Konstantin, et al. "GPR1200: A Benchmark for General-Purpose Content-Based Image Retrieval." International Conference on Multimedia Modeling. Springer, Cham, 2022.
- Luo, Hao, et al. "A strong baseline and batch normalization neck for deep person re-identification." IEEE Transactions on Multimedia 22.10 (2019): 2597-2609.