24-PaddleClas 模型评估、导出与推理部署入门

概述

PaddleClas 训练结束后，通常会得到训练权重文件。但真实项目还要回答几个问题：

这个模型在验证集或测试集上表现怎样？
如何选择 best model？
如何把训练权重导出成推理模型？
如何用导出的模型预测图片？
训练权重和推理模型有什么区别？
推理部署前应该检查哪些问题？

本篇文章围绕 PaddleClas 的后训练流程：

text 复制代码

训练得到权重
    |
eval.py 评估
    |
export_model.py 导出 inference model
    |
deploy/python/predict_cls.py 推理
    |
部署前验证

读完本文，你应该能完成 PaddleClas 模型从训练权重到可推理模型的基本流程。

训练权重与推理模型的区别

训练后常见文件：

text 复制代码

best_model.pdparams
latest.pdparams

这些是训练权重，适合：

恢复训练。
继续微调。
用 tools/eval.py 评估。
用 tools/infer.py 简单预测。

推理部署通常需要导出后的模型：

text 复制代码

inference.pdmodel
inference.pdiparams

推理模型适合：

Paddle Inference。
服务部署。
端侧或边缘部署前转换。
标准化预测脚本。

训练权重面向训练流程，推理模型面向部署流程。

使用 eval.py 评估训练权重

评估命令：

bash 复制代码

python tools/eval.py \
    -c ./ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml \
    -o Global.pretrained_model=./output/MobileNetV3_large_x1_0/best_model

注意：

text 复制代码

Global.pretrained_model 通常填写不带 .pdparams 后缀的路径

评估输出通常包括：

top1
top5
loss
数据加载和推理耗时

如果是二分类或类别数小于 5，配置中不要强行计算 Top-5。

评估前检查配置

评估结果异常时，先检查：

Arch.class_num 是否和训练一致。
DataLoader.Eval.dataset.cls_label_path 是否指向验证集。
DataLoader.Eval.dataset.image_root 是否正确。
Eval transform 是否和训练时验证配置一致。
Global.pretrained_model 是否指向正确权重。

不要用训练集当验证集来报告最终结果。

使用 infer.py 做快速预测

tools/infer.py 可以直接使用训练权重预测图片：

bash 复制代码

python tools/infer.py \
    -c ./ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml \
    -o Infer.infer_imgs=./demo/demo.jpg \
    -o Global.pretrained_model=./output/MobileNetV3_large_x1_0/best_model

它适合快速检查：

模型能否加载。
单张图片能否预测。
label 映射是否合理。
预处理是否和训练一致。

但如果要部署，通常还要导出 inference model。

导出推理模型

使用 tools/export_model.py：

bash 复制代码

python tools/export_model.py \
    -c ./ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml \
    -o Global.pretrained_model=./output/MobileNetV3_large_x1_0/best_model \
    -o Global.save_inference_dir=./inference/MobileNetV3_large_x1_0

导出后通常得到：

text 复制代码

inference/MobileNetV3_large_x1_0/
    inference.pdmodel
    inference.pdiparams
    inference.yml

其中：

inference.pdmodel：模型结构。
inference.pdiparams：模型参数。
inference.yml：推理相关配置。

具体文件名可能随版本略有不同，以实际导出结果为准。

使用导出模型进行推理

PaddleClas 部署目录通常提供 Python 推理脚本，例如：

bash 复制代码

python deploy/python/predict_cls.py \
    -c deploy/configs/inference_cls.yaml \
    -o Global.inference_model_dir=./inference/MobileNetV3_large_x1_0 \
    -o Global.infer_imgs=./demo/demo.jpg

常见推理配置项：

配置	作用
`Global.inference_model_dir`	导出模型目录
`Global.infer_imgs`	图片路径或目录
`PostProcess.Topk.topk`	输出前 K 个类别
`PreProcess.transform_ops`	推理预处理
`PostProcess.class_id_map_file`	类别映射文件

推理时最容易出错的是预处理不一致：训练时 Resize/Normalize 是一套，部署时必须保持一致。

类别映射：预测 ID 如何变成类别名

模型输出的是类别 ID 和概率。如果要显示类别名，需要类别映射文件。

示例：

text 复制代码

0 rose
1 tulip
2 sunflower

或者某些配置使用：

text 复制代码

rose
tulip
sunflower

具体格式以当前 PaddleClas 推理配置要求为准。

原则：

类别 ID 顺序必须和训练标签一致。
不要训练时一个映射、推理时另一个映射。
自定义数据集应保存一份稳定的 label_list.txt。

评估、infer、deploy predict 的区别

命令	输入模型	主要用途
`tools/eval.py`	训练权重	评估验证集指标
`tools/infer.py`	训练权重	快速预测图片
`tools/export_model.py`	训练权重	导出推理模型
`deploy/python/predict_cls.py`	推理模型	部署侧预测验证

不要把这些命令混在一起：

评估精度用 eval.py。
快速看结果用 infer.py。
部署前先 export_model.py。
验证导出模型用 deploy 预测脚本。

部署前检查清单

导出推理模型后，至少检查：

同一张图片，训练权重预测和导出模型预测是否一致或接近。
推理预处理是否和训练验证配置一致。
类别映射是否正确。
输入图片通道顺序是否正确。
Top-K 输出是否符合业务需要。
推理耗时是否满足要求。
模型目录是否包含必要文件。

如果导出模型预测明显异常，优先检查预处理和类别映射。

常见错误

错误一：pretrained_model 路径带后缀

PaddleClas 评估和导出时通常填写不带 .pdparams 的路径。

错误二：导出目录写错

确认：

bash 复制代码

ls ./inference/MobileNetV3_large_x1_0

里面应有推理模型文件。

错误三：部署配置的预处理和训练不一致

检查 Resize、Crop、Normalize、通道顺序。

错误四：类别名错位

如果预测 ID 正确但显示类别名错误，通常是 label map 顺序不一致。

错误五：用 eval.py 评估了训练集

确认 cls_label_path 指向验证集或测试集。

建议练习：完成一次后训练流程

训练一个 PaddleClas quick start 模型。
使用 eval.py 评估 best model。
使用 infer.py 预测单张图片。
使用 export_model.py 导出 inference model。
使用 deploy 预测脚本验证导出模型。
修改 Top-K 输出数量。
故意打乱 label map，观察预测类别名错误。

总结

这一篇讲了 PaddleClas 后训练流程：

eval.py 用于评估训练权重。
infer.py 可快速使用训练权重预测图片。
export_model.py 将训练权重导出成 inference model。
deploy 预测脚本用于验证导出模型。
训练权重和推理模型用途不同。
部署前必须检查预处理和类别映射。

如果只能记住一句话，那就是：

训练得到高 accuracy 只是第一步，导出后推理结果正确，模型才真正进入可部署状态。