PaddleClas 实战指南：从 PULC 超轻量图像分类到 PP-ShiTuV2 图像识别系统

PaddleClas 是飞桨（PaddlePaddle）面向工业界与学术界提供的图像识别与图像分类工具集，覆盖骨干网络选型、模型训练、模型压缩、推理部署全链路。本文将以仓库根目录的 README_ch.md 为核心脉络，系统拆解 PULC 超轻量实用图像分类方案、PP-ShiTuV2 轻量级通用图像识别系统的设计原理与快速上手路径，并结合仓库源码与配置说明其底层实现，帮助读者掌握"从选模型、训练、压缩到部署"的完整落地能力。

1. PaddleClas 是什么

PaddleClas 是飞桨图像识别套件，为图像识别与图像分类任务提供了一站式工具集，目标是助力使用者训练出更好的视觉模型并完成应用落地。围绕这一目标，仓库主要提供了三类能力：

• 前沿算法与产业级骨干网络：包括面向 CPU 场景的 PP-LCNet、PP-LCNetV2、面向 GPU 高精度场景的 PP-HGNet，以及 SSLD 半监督知识蒸馏方案；
• 两大实用方案：PULC 超轻量图像分类方案与 PP-ShiTu 图像识别系统；
• 完整工具链：模型训练（tools/train.py）、评估（tools/eval.py）、推理（tools/infer.py）、导出（tools/export_model.py）、模型压缩（deploy/slim/）以及 Python/C++/服务化/端侧等多形态部署。

1.1 近期重要更新

• 2024.11.5：依托 PaddleClas 技术推出飞桨低代码开发工具 PaddleX，支持图像分类与图像检索领域的低代码全流程开发——将通用图像分类、图像多标签分类、通用图像识别、人脸识别涉及的 98 个模型整合为 6 条模型产线，通过极简 Python API 一键调用；同时新增 MobileNetV4、StarNet、FasterNet 等图像分类算法，新增 PP-ShiTuV2_rec_CLIP_vit_base / vit_large 服务端识别模型，新增 CLIP_vit_base_patch16_448_ML、PP-HGNetV2-B0/B4/B6_ML、PP-LCNet_x1_0_ML、ResNet50_ML 等多标签分类模型，以及 MobileFaceNet、ResNet50_face 人脸识别模型。详见 docs/zh_CN/paddlex/quick_start.md。
• 2022.9.13：发布超轻量图像识别系统 PP-ShiTuV2，Recall1 精度提升约 8 个百分点，覆盖商品识别、垃圾分类、航拍场景等 20+ 识别场景，并新增 库管理工具 与全新体验的 Android Demo。
• 更完整的更新记录参见 docs/zh_CN/version_history.md。

1.2 核心特性

PaddleClas 支持多种前沿图像分类、识别相关算法，发布产业级特色骨干网络 PP-HGNet、PP-LCNetV2、PP-LCNet 和 SSLD 半监督知识蒸馏方案，并在此基础上打造 PULC 超轻量图像分类方案与 PP-ShiTu 图像识别系统。两大方案面向的场景不同：PULC 面向类别固定、轻量高精度的分类需求；PP-ShiTu 面向类别频繁变动、类别数量多的检索需求。

2. PP 系列核心模型与骨干网络

README 中列出的 PP 系列模型及其应用场景如下：

模型简介	应用场景	说明
PULC 超轻量图像分类方案	固定图像类别分类方案	人体、车辆、文字相关 9 大模型，见 PULC 模型库
PP-ShiTuV2 轻量图像识别系统	场景数据类别频繁变动、类别数据多	主体检测 + 识别（特征提取）双模型
PP-LCNet 轻量骨干网络	针对 Intel CPU 设备及 MKLDNN 加速库定制	PPLCNet_x1_0 为常用规格
PP-LCNetV2 轻量骨干网络	针对 Intel CPU 设备，适配 OpenVINO	PPLCNetV2_base 为默认识别骨干
PP-HGNet 高精度骨干网络	GPU 设备上相同推理时间精度更高	PPHGNet_small 等规格

2.1 PP-LCNet：面向 Intel CPU 与 MKLDNN 的轻量骨干

从源码 ppcls/arch/backbone/legendary_models/pp_lcnet.py 可以看到，PP-LCNet 的网络结构通过 NET_CONFIG 以"深度可分离卷积块"列表的形式定义（每个块包含 kernel_size、输入通道、输出通道、stride、是否使用 SE 模块五个要素）：

NET_CONFIG = {
    # [k, in_c, out_c, s, use_se]
    "blocks2": [[3, 16, 32, 1, False]],
    "blocks3": [[3, 32, 64, 2, False], [3, 64, 64, 1, False]],
    "blocks4": [[3, 64, 128, 2, False], [3, 128, 128, 1, False]],
    "blocks5": [[3, 128, 256, 2, False], [5, 256, 256, 1, False], ...],
    "blocks6": [[5, 256, 512, 2, True], [5, 512, 512, 1, True]]
}

该模型通过 make_divisible 将通道数对齐到 8 的倍数以便硬件加速，并提供 PPLCNet_x0_25 至 PPLCNet_x2_5 多个宽度系数版本（见同文件 MODEL_URLS）。其中 PPLCNet_x1_0 是 PULC 系列模型统一采用的骨干。

2.2 PP-LCNetV2：PP-ShiTuV2 的默认识别骨干

pp_lcnet_v2.py 中 NET_CONFIG 以 [in_channels, kernel_size, split_pw, use_rep, use_se, use_shortcut] 描述四个 stage，引入了 split pointwise 卷积、重参数化（use_rep）、SE 与残差捷径等设计。PP-ShiTuV2 默认识别模型即 PPLCNetV2_base_ShiTu。

2.3 PP-HGNet：GPU 高精度骨干

pp_hgnet.py（及 pp_hgnet_v2.py）面向 GPU 场景，追求在相同推理时间下获得更高精度，是追求分类精度的推荐选择。全部模型下载链接可在 ImageNet1k 模型库 及各模型介绍文档中查看。

2.4 产业范例

• 基于 PP-ShiTuV2 的生鲜品自助结算：docs/zh_CN/samples/Fresh_Food_Recogniiton/README.md
• 基于 PULC 的人员出入视频管理：docs/zh_CN/samples/Personnel_Access/README.md
• 基于 PP-ShiTu 的智慧商超商品识别：docs/zh_CN/samples/Goods_Recognition/README.md
• 基于 PP-ShiTu 的电梯内电瓶车入室识别：docs/zh_CN/samples/Electromobile_In_Elevator_Detection/README.md

3. PULC 超轻量图像分类方案

PULC（Practical Ultra Lightweight Classification）融合了骨干网络、数据增广、蒸馏等多种前沿算法，可以自动训练得到轻量且高精度的图像分类模型。方案整体由四部分组成：PP-LCNet 轻量级骨干网络、SSLD 预训练权重、数据增强策略集成（EDA）与 SKL-UGI 知识蒸馏算法，此外还通过超参搜索高效优化训练超参数。PaddleClas 提供了覆盖人、车、OCR 场景 9 大常见任务的分类模型，CPU 推理约 3ms，精度可比肩 SwinTransformer 系列。方案详述见 docs/zh_CN/training/PULC.md。

3.1 PULC 模型库一览

以下指标与下载信息取自 PULC 模型库，其中预训练模型可用于微调训练，推理模型可直接用于预测和部署：

模型名称	任务简介	精度指标	模型大小	CPU 推理耗时
person_exists	判断图片中是否有人	96.23（TprAtFpr）	7.0M	2.58ms
person_attribute	行人性别、年龄、朝向、配饰、包、服装风格等属性识别	78.59（mA）	7.2M	2.01ms
safety_helmet	判断人脸是否佩戴安全帽	99.38（TprAtFpr）	7.1M	2.03ms
traffic_sign	常见交通标志分类，共 232 类	98.35（Top-1 Acc）	8.2M	2.10ms
vehicle_attribute	车辆颜色与车型属性识别	90.81（mA）	7.2M	2.36ms
car_exists	判断图片中是否有车	95.92（TprAtFpr）	7.1M	2.38ms
text_image_orientation	含文字图像方向（0/90/180/270 度）	99.06（Top-1 Acc）	7.1M	2.16ms
textline_orientation	文本行方向（0/180 度）	96.01（Top-1 Acc）	7.0M	2.72ms
language_classification	10 种常见语种分类	99.26（Top-1 Acc）	7.1M	2.58ms
table_attribute	表格拍照与否、数量、颜色、清晰度、有无干扰、角度 6 属性	88.1（mA）	7.1M	2.58ms
code_exists	有无广告码（二维码、条形码、小程序码）	94.9（Top-1 Acc）	7.0M	2.13ms
clarity_assessment	图片清晰度评估	95.3（Top-1 Acc）	7.0M	2.13ms
image_orientation	图像方向分类	89.99（Top-1 Acc）	7.1M	2.16ms

备注：以上所有模型 backbone 均为 PPLCNet_x1_0，模型大小差异主要来自分类输出维度不同；推理耗时基于 Intel Xeon Gold 6148 CPU @ 2.40GHz、开启 MKLDNN 加速、线程数 10 测得，速度测试存在轻微波动。各模型下载链接与详细训练文档见 PULC 模型库 及 docs/zh_CN/models/PULC/ 下对应文档（如 PULC_person_exists.md、PULC_person_attribute.md 等）。

3.2 PULC 快速体验：whl 包一行命令预测

PULC 系列模型可以通过 PaddleClas whl 包直接使用，完整步骤见 docs/zh_CN/quick_start/PULC.md。

第一步：安装环境

# CPU 环境
python3 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
# GPU 环境（CUDA9 / CUDA10）
python3 -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple
# 安装 PaddleClas whl 包
pip3 install paddleclas

第二步：命令行预测

paddleclas --model_name=person_exists --infer_imgs=pulc_demo_imgs/person_exists/objects365_01780782.jpg

输出示例：

>>> result
class_ids: [0], scores: [0.9955421453341842], label_names: ['nobody'], filename: pulc_demo_imgs/person_exists/objects365_01780782.jpg
Predict complete!

预测结果为 nobody 表示图中没有人，someone 表示图中有人。更换图片只需修改 --infer_imgs（支持传入整个文件夹），更换模型则修改 --model_name。

第三步：Python 脚本调用

import paddleclas
model = paddleclas.PaddleClas(model_name="person_exists")
result = model.predict(input_data="pulc_demo_imgs/person_exists/objects365_01780782.jpg")
print(next(result))

输出示例：

[{'class_ids': [0], 'scores': [0.9955421453341842], 'label_names': ['nobody'], 'filename': 'pulc_demo_imgs/person_exists/objects365_01780782.jpg'}]

注意 model.predict() 返回可迭代的 generator 对象，需使用 next() 或 for 循环迭代调用，每次按 batch_size（默认 1）预测一批；如需调整可实例化时指定，如 model = paddleclas.PaddleClas(model_name="person_exists", batch_size=2)。PaddleClas whl 包的底层入口为仓库 paddleclas.py，其 PaddleClas 类封装了 deploy/python/predict_cls.py 的分类预测器（ClsPredictor）与 deploy/python/predict_system.py 的识别系统预测器（SystemPredictor），并负责推理模型与演示图片的自动下载、缓存到 ~/.paddleclas/ 目录。

3.3 PULC 方案源码级配置解读

以有人/无人场景为例，标准训练配置见 ppcls/configs/PULC/person_exists/PPLCNet_x1_0.yaml，关键配置项如下：

• Arch（模型结构）：name: PPLCNet_x1_0，class_num: 2，use_ssld: True（使用 SSLD 预训练权重），use_sync_bn: True；
• Loss：训练与评估阶段均使用 CELoss，权重 1.0；
• Optimizer：Momentum（momentum 0.9）+ Cosine 学习率（初始 0.01，warmup 5 epoch）+ L2 正则（coeff 0.00004）；
• DataLoader：训练侧使用 RandCropImage（192×192）、RandFlipImage、TimmAutoAugment、NormalizeImage、RandomErasing 组成的 EDA 数据增强链；评估侧使用 Resize 到 short 256 + CenterCrop 224 的标准流程；
• Infer/PostProcess：使用 ThreshOutput，设置 threshold: 0.9 及类别标签 label_0: nobody、label_1: someone，即置信度低于阈值时归为 nobody，这是 PULC 方案为控制误检设计的实用输出策略；
• Metric：评估同时使用 TprAtFpr（误检率约束下的召回率，正负样本不均衡场景的核心指标）与 TopkAcc。

该目录下还提供了蒸馏配置 PPLCNet_x1_0_distillation.yaml（对应 SKL-UGI 知识蒸馏）与超参搜索配置 search.yaml、PPLCNet_x1_0_search.yaml。同一套方案在 ppcls/configs/PULC/ 下覆盖了 car_exists、safety_helmet、vehicle_attribute、language_classification、text_image_orientation 等全部 9+ 个场景，配置结构完全一致，便于复制迁移。

3.4 PULC 自定义训练流程

若需要训练自定义任务，docs/zh_CN/training/PULC.md 给出了完整流程：

数据准备：PaddleClas 使用 txt 文件指定训练集与验证集，每行以空格分隔图像路径与类别标注：

train/1.jpg 0
train/10.jpg 1

已有按类别分文件夹的数据时，可用如下命令快速生成标注文件（类别文件夹层级为 2）：

tree -r -i -f train | grep -E "jpg|JPG|jpeg|JPEG|png|PNG" | awk -F "/" '{print $0" "$2}' > train_list.txt

标准分类配置训练：可直接下载官方有人/无人数据快速体验：

cd dataset
wget https://paddleclas.bj.bcebos.com/data/PULC/person_exists.tar
tar -xf person_exists.tar
cd ../

随后依次替换骨干网络（PP-LCNet）、引入 SSLD 预训练权重、叠加 EDA 数据增强、加入 SKL-UGI 蒸馏，即可复现 PULC 的精度提升路径。

超参搜索：PULC 还提供基于默认配置与自定义配置两种超参搜索方式，用于高效寻找最优超参组合。

4. PP-ShiTuV2 轻量级通用图像识别系统

PP-ShiTuV2 是一个实用的轻量级通用图像识别系统，由主体检测、特征学习和向量检索三个模块组成。相比 V1，V2 在骨干网络选择与调整、损失函数选择、数据增强、学习率变换策略、正则化参数选择、预训练模型使用以及模型裁剪量化等多个方面采用优化策略，Recall1 提升近 8 个百分点（产品数据集上 V1 为 66.8%，V2 为 73.8%，存储占用由 64MB 降至 49MB）。系统介绍与 Pipeline 评测详见 docs/zh_CN/models/PP-ShiTu/README.md。

4.1 三个子模块

• 主体检测：先从图像中定位主体区域（如商品、行人），裁剪后再送入特征提取模型，训练文档见 docs/zh_CN/training/PP-ShiTu/mainbody_detection.md，推理侧使用轻量通用检测模型 picodet_PPLCNet_x2_5_mainbody_lite；
• 特征提取：对裁剪区域提取判别性特征向量，PP-ShiTuV2 默认识别模型为 PPLCNetV2_base_ShiTu，训练文档见 docs/zh_CN/training/PP-ShiTu/feature_extraction.md；
• 向量检索：在海量特征库中召回最相似向量并返回标签，支持普通向量检索与哈希编码加速，相关文档见 docs/zh_CN/deployment/PP-ShiTu/vector_search.md 与 docs/zh_CN/training/PP-ShiTu/deep_hashing.md。

4.2 快速体验

Android 端：可通过扫描二维码下载 PP-ShiTuV2 Android Demo APP，具备图像检索、图像加库、保存检索库、初始化检索库、查看检索库标签等能力（详见 docs/zh_CN/quick_start/quick_start_recognition.md）；如需二次开发可参考 deploy/shitu_android_demo/docs/README.md。

PC 端：先安装 PaddleClas whl 包：

pip3 install paddleclas

如需使用 develop 分支最新功能或进行二次开发，可在仓库根目录执行 pip install -v -e . 本地构建安装。

轻量通用主体检测模型与轻量通用识别模型的推理配置为 deploy/configs/inference_general.yaml，对应推理入口为 deploy/python/predict_system.py 与 deploy/python/predict_cls.py。官方还提供了瓶装饮料（drink_dataset_v2.0）等 22 种场景的 demo 数据（见 docs/zh_CN/deployment/PP-ShiTu/application_scenarios.md），可完整体验"识别已入库图像"与"为未知类别建立索引库再识别"两条路径。

4.3 部署形态

PP-ShiTu 的推理部署覆盖 Python 预测引擎（docs/zh_CN/deployment/PP-ShiTu/python.md）、C++ 预测引擎（docs/zh_CN/deployment/PP-ShiTu/cpp.md）、服务化部署（docs/zh_CN/deployment/PP-ShiTu/paddle_serving.md）、端侧部署（docs/zh_CN/deployment/PP-ShiTu/paddle_lite.md）以及检索库管理工具（docs/zh_CN/deployment/PP-ShiTu/gallery_manager.md）。仓库中对应实现位于 deploy/cpp_shitu/（C++ 检索推理）、deploy/lite_shitu/（端侧）与 deploy/shitu_index_manager/（图形化库管理工具）。

5. 低代码全流程开发与 PaddleX

2024 年 11 月起，PaddleClas 的能力通过飞桨低代码开发工具 PaddleX 进一步开放：以统一命令行与图形界面两种方式，实现模型的简洁高效使用、组合与定制，支持高性能推理、服务化部署和端侧部署，并可在英伟达 GPU、昆仑芯、昇腾、寒武纪、海光等主流硬件间无缝切换。快速入口见 docs/zh_CN/paddlex/quick_start.md 与 docs/zh_CN/paddlex/overview.md。

6. 文档地图与学习路径

仓库提供了体系化的中文文档（docs/zh_CN/）：

• 环境准备：docs/zh_CN/installation.md；
• 快速开始：30 分钟快速体验图像分类、PULC 快速体验（docs/zh_CN/quick_start/PULC.md）、图像识别快速体验（docs/zh_CN/quick_start/quick_start_recognition.md）；
• 模型训练：PULC 训练（docs/zh_CN/training/PULC.md）、SSLD 半监督蒸馏（docs/zh_CN/training/advanced/ssld.md）、数据增强（docs/zh_CN/training/config_description/data_augmentation.md）、度量学习（docs/zh_CN/algorithm_introduction/metric_learning.md）、模型压缩（docs/zh_CN/algorithm_introduction/prune_quantization.md）；
• 推理部署：PULC 场景支持 Python/C++ 预测引擎、Paddle Serving 服务化、Paddle Lite 端侧以及 Paddle2ONNX 模型转化（见 docs/zh_CN/deployment/image_classification/），压缩方案见 deploy/slim/README.md；
• FAQ：图像分类与图像识别的精选问题解答见 docs/zh_CN/FAQ/；
• 贡献指南：docs/zh_CN/community/how_to_contribute.md。

7. 许可与社区

本项目以 Apache 2.0 license 发布（见仓库根目录 LICENSE）。社区为 PaddleClas 做出了多项贡献，例如修正 RandErasing 数据增广配置文件、修正文档错别字、添加 ViT/DeiT 与 RepVGG 系列模型等。欢迎参考贡献指南参与共建。

8. 小结

PaddleClas 以"产业级骨干网络 + 两大实用方案 + 全链路工具链"构建了从图像分类到图像识别的完整体系：需要固定类别、轻量高精度的分类能力时选择 PULC（PP-LCNet + SSLD 预训练 + EDA 增强 + SKL-UGI 蒸馏 + 超参搜索）；需要类别动态变化的大规模检索能力时选择 PP-ShiTuV2（主体检测 + 特征提取 + 向量检索三模块管线）。两者均可通过 whl 包一行命令快速体验，并可从仓库中对应的 YAML 配置与源码出发，完成自定义训练、压缩与多形态部署落地。