22-使用 PaddleClas 快速训练图像分类模型

概述

前面几篇文章使用 Paddle 原生 API 手写了 CNN 训练流程。这种方式适合理解原理，但真实图像分类项目通常还需要：

更成熟的模型结构。
标准训练配置。
预训练权重。
多卡训练脚本。
评估、导出、部署工具。
数据集格式约定。
日志、保存、恢复等工程能力。

PaddleClas 是飞桨图像分类与识别方向的工具套件。它把常见图像分类工程流程封装好，让你可以通过配置文件和脚本快速训练模型。

本篇目标不是替代前面的 Paddle 基础，而是让你理解：

text 复制代码

手写 Paddle 训练循环：适合学原理和自定义
PaddleClas：适合快速跑通图像分类工程

读完本文，你应该知道 PaddleClas 的基本目录、训练命令、评估命令和快速实验流程。

PaddleClas 适合解决什么问题

PaddleClas 适合：

标准图像分类。
迁移学习和微调。
使用 ResNet、MobileNet、PP-LCNet 等成熟模型。
快速复现实验。
导出推理模型。
后续接入部署工具。

不适合直接替代所有自定义训练代码。如果你的任务有特殊输入、多任务 loss、复杂采样逻辑，仍然可能需要回到 Paddle 原生 API。

可以用下面的判断：

text 复制代码

任务是标准分类，优先试 PaddleClas
任务高度定制，使用 Paddle 原生训练循环

环境准备：先确认 Paddle 和 PaddleClas

推荐先确认 Paddle 可用：

bash 复制代码

python -c "import paddle; paddle.utils.run_check()"

获取 PaddleClas 代码：

bash 复制代码

git clone https://github.com/PaddlePaddle/PaddleClas.git
cd PaddleClas

安装依赖：

bash 复制代码

python -m pip install -r requirements.txt

设置 PYTHONPATH：

bash 复制代码

export PYTHONPATH=./:$PYTHONPATH

Windows PowerShell 可以使用：

powershell 复制代码

$env:PYTHONPATH = ".;$env:PYTHONPATH"

PaddleClas 官方"开始使用"文档也强调需要设置 PYTHONPATH，否则脚本可能找不到 ppcls 包。

快速理解 PaddleClas 目录

进入 PaddleClas 后，常见目录包括：

text 复制代码

PaddleClas/
    ppcls/
        engine/
        arch/
        data/
        optimizer/
    tools/
        train.py
        eval.py
        infer.py
        export_model.py
    ppcls/configs/
        quick_start/
        ImageNet/
        ...
    deploy/
        python/
        configs/

最常接触的是：

路径	作用
`tools/train.py`	启动训练
`tools/eval.py`	启动评估
`tools/infer.py`	使用训练权重预测
`tools/export_model.py`	导出推理模型
`ppcls/configs`	训练配置文件
`deploy`	推理部署相关脚本

PaddleClas 的核心工作方式是：

text 复制代码

选择配置文件
    |
准备数据集
    |
运行 train.py
    |
运行 eval.py
    |
导出 inference model
    |
部署预测

选择一个快速开始配置

官方文档中常用 MobileNetV3 的 quick start 配置作为示例：

text 复制代码

ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml

它包含：

模型结构。
数据集路径。
训练 transform。
验证 transform。
优化器。
学习率。
epoch。
保存路径。
指标配置。

相比手写训练循环，PaddleClas 把大量配置集中在 YAML 文件中。

启动训练

单机 CPU 或单卡 GPU 可以运行：

bash 复制代码

python tools/train.py \
    -c ./ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml \
    -o Arch.pretrained=False

参数解释：

-c：指定配置文件。
-o：覆盖配置文件中的某个字段。
Arch.pretrained=False：不加载预训练权重，从头训练。

如果要加载预训练权重做微调，可以设置：

bash 复制代码

python tools/train.py \
    -c ./ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml \
    -o Arch.pretrained=True

官方文档也说明，-o 可以在命令行覆盖配置项，适合快速实验。

多卡训练命令

Linux 多卡训练通常使用 Paddle 分布式启动：

bash 复制代码

export CUDA_VISIBLE_DEVICES=0,1,2,3
python -m paddle.distributed.launch \
    --gpus="0,1,2,3" \
    tools/train.py \
    -c ./ppcls/configs/quick_start/MobileNetV3_large_x1_0.yaml

有些 PaddleClas 文档版本中使用 --selected_gpus，不同版本启动参数可能略有差异。实际使用时以当前 PaddleClas 文档和脚本帮助为准：

bash 复制代码

python -m paddle.distributed.launch --help
python tools/train.py --help

入门阶段建议先用单卡或 CPU 跑通，再切多卡。

查看训练日志

训练日志通常会包含：

text 复制代码

epoch
step
loss
top1
top5
lr
elapse

含义：

字段	含义
`loss`	当前 batch 或统计窗口损失
`top1`	Top-1 准确率
`top5`	Top-5 准确率
`lr`	当前学习率
`elapse`	耗时

不要只看 loss，也要看 top1/top5 是否提升。

启动评估

训练完成后，常用 tools/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

注意：官方文档提示，加载模型时通常指定不带 .pdparams 后缀的路径，PaddleClas 会自动补充。

也就是说：

text 复制代码

./output/MobileNetV3_large_x1_0/best_model

而不是：

text 复制代码

./output/MobileNetV3_large_x1_0/best_model.pdparams

使用训练权重预测

使用训练得到的权重预测图片：

bash 复制代码

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

关键参数：

Infer.infer_imgs：要预测的图片或图片目录。
Global.pretrained_model：训练得到的权重路径，不带后缀。

这一步使用的是训练权重，不是专门导出的 inference model。后续部署一般还要走导出流程。

快速实验建议

第一次使用 PaddleClas，不建议一上来就训练大数据集。建议：

使用官方 quick start 配置。
准备一个很小的二分类或多分类数据集。
先把 epochs 改小，例如 3 到 5。
先跑通训练、评估、预测。
再换模型、调学习率、增加数据增强。

PaddleClas 是工程套件，先跑通完整流程比一开始追求高精度更重要。

和手写 Paddle 训练循环的关系

手写训练循环：

python 复制代码

for batch_x, batch_y in loader:
    logits = model(batch_x)
    loss = F.cross_entropy(logits, batch_y)
    loss.backward()
    optimizer.step()
    optimizer.clear_grad()

PaddleClas：

bash 复制代码

python tools/train.py -c config.yaml

本质上两者做的是同一件事，只是 PaddleClas 把模型、数据、优化器、学习率、日志、保存、评估都配置化了。

理解 Paddle 基础能让你更容易读懂 PaddleClas 配置，也更容易排查训练问题。

常见错误：PaddleClas 快速上手排查清单

错误一：没有设置 PYTHONPATH

如果报找不到 ppcls，先设置：

bash 复制代码

export PYTHONPATH=./:$PYTHONPATH

错误二：配置文件路径写错

检查：

bash 复制代码

ls ./ppcls/configs/quick_start/

确认 YAML 文件存在。

错误三：数据路径不匹配

配置文件中的数据路径必须和实际数据目录一致。后续第 23 篇会详细讲数据集和配置。

错误四：pretrained_model 路径带了后缀

评估时通常指定不带 .pdparams 的路径。

错误五：CPU/GPU 配置不一致

如果没有 GPU，就不要强行配置 GPU。先用 CPU 或单卡 GPU 跑通。

建议练习：跑通 PaddleClas 标准流程

克隆 PaddleClas 并安装依赖。
设置 PYTHONPATH。
找到 quick start 配置文件。
用 tools/train.py 跑 1 到 3 个 epoch。
用 tools/eval.py 评估 best model。
用 tools/infer.py 预测一张图片。
使用 -o 覆盖一个配置项。

总结

这一篇讲了 PaddleClas 快速训练图像分类模型的基本流程：

PaddleClas 提供训练、评估、预测、导出等脚本。
tools/train.py 负责训练。
tools/eval.py 负责评估。
tools/infer.py 可使用训练权重预测图片。
配置文件集中管理模型、数据、优化器和训练参数。
-o 可以从命令行覆盖配置项。
入门阶段先跑通 quick start，再改数据和模型。

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

PaddleClas 把图像分类的常规工程流程配置化，让你从手写训练循环进入可复用的分类训练体系。