PaddleDetection 快速开始实战：10 分钟完成道路标志检测模型的训练、评估与推理

• 人工智能
• 深度学习
• 计算机视觉

本指南是 PaddleDetection 的官方快速上手教程，以道路标志（road sign）检测为实战场景，完整演示"预训练模型推理 → 小数据集微调训练 → 评估 → 推理"的端到端流程。读完本文，你将掌握tools/train.py、tools/eval.py、tools/infer.py三大工具的标准用法，理解 PaddleDetection 基于_BASE_的配置继承机制，并能在约 10 分钟（1080Ti GPU）内产出一个 mAP 0.85 左右的目标检测模型。

一、前置环境：设置 GPU

PaddleDetection 的默认运行设备为 GPU，训练、评估、推理前需要先指定当前进程可见的 GPU 卡号。在终端中执行：

export CUDA_VISIBLE_DEVICES=0

该命令将显卡 0 暴露给当前进程。若机器有多张显卡，可通过CUDA_VISIBLE_DEVICES=0,1,2,3指定多卡用于分布式训练（本教程中的示例均为单卡操作）。若没有 GPU 环境，可在后续命令中把-o use_gpu=false传入，训练将回退到 CPU（耗时约 1 小时）。

二、快速体验：用预训练模型直接推理

在动手训练之前，可以先使用 PaddleDetection 提供的 COCO 预训练模型体验一次推理，直观感受模型效果。执行：

python tools/infer.py -c configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml -o use_gpu=true weights=https://paddledet.bj.bcebos.com/models/ppyolo_r50vd_dcn_1x_coco.pdparams --infer_img=demo/000000014439.jpg

命令中几个关键参数的含义如下：

• -c：指定模型配置文件，这里使用 PP-YOLO 在 COCO 数据集上的配置 configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml；
• -o：覆盖配置文件中的字段，use_gpu=true表示强制使用 GPU 推理；
• weights：直接指定预训练权重文件的 URL，推理时会自动下载 [weights 指向的.pdparams权重]（configs/ppyolo/ppyolo_r50vd_dcn_1x_coco.yml 中即weights: output/ppyolo_r50vd_dcn_1x_coco/model_final，此处通过-o覆盖为远程地址）；
• --infer_img：指定待推理的单张图像路径。

预测结束后，会在output文件夹下生成一张画有预测框的同名图像（默认输出目录为output，可通过--output_dir修改；可视化保留阈值由--draw_threshold控制，默认 0.5，见 tools/infer.py 的参数定义）。

三、准备数据：roadsign_voc 道路标志数据集

本教程使用 Kaggle 的 road-sign-detection 道路标志数据集，共 877 张图像、4 个类别：crosswalk（人行横道）、speedlimit（限速）、stop（停止）、trafficlight（红绿灯）。数据集被划分为训练集 701 张、测试集 176 张，并按 VOC 格式整理。

仓库已内置该数据集的下载脚本：

python dataset/roadsign_voc/download_roadsign_voc.py

注意：此步骤可以跳过——训练阶段若检测到数据不存在会自动下载。该脚本位于 dataset/roadsign_voc/download_roadsign_voc.py，其核心逻辑是调用ppdet.utils.download模块的download_dataset(download_path, 'roadsign_voc')，将数据集解压到当前脚本所在目录（即dataset/roadsign_voc）。

下载完成后，目录中应包含：

• JPEGImages/：全部图像；
• Annotations/：VOC 格式的 XML 标注；
• train.txt/valid.txt：训练集与验证集的图像列表（供 configs/datasets/roadsign_voc.yml 引用）；
• label_list.txt：类别名称列表。

对应地，configs/datasets/roadsign_voc.yml 中通过TrainDataset/EvalDataset/TestDataset三组配置分别描述了训练、评估、推理阶段的数据来源，并声明metric: VOC、map_type: integral、num_classes: 4。

四、训练：对小数据集微调 YOLOv3

1. 训练命令

本教程的核心训练配置是 configs/yolov3/yolov3_mobilenet_v1_roadsign.yml，它基于 COCO 预训练的 YOLOv3 + MobileNetV1 主干，在 4 类道路标志小数据集上微调。执行：

python tools/train.py -c configs/yolov3/yolov3_mobilenet_v1_roadsign.yml --eval -o use_gpu=true

• -c参数指定配置文件；
• -o参数覆盖配置文件中的全局变量，这里设置使用 GPU；
• --eval参数表示边训练边评估，训练结束后会自动保存一个名为model_final的模型（评估结果最优时对应保存的模型路径由配置中的weights: output/yolov3_mobilenet_v1_roadsign/model_final决定）。

参考耗时：1080Ti GPU 约 10 分钟，纯 CPU 约 1 小时。

从 tools/train.py 的源码看，训练流程如下：

1. ArgsParser解析命令行参数，load_config加载 YAML 配置，merge_config合并-o传入的覆盖项；
2. 依据cfg.use_gpu调用paddle.set_device('gpu'/'cpu')设置运行设备；
3. Trainer(cfg, mode='train')构建训练器，并根据pretrain_weights自动加载 COCO 预训练权重（见配置中pretrain_weights: https://paddledet.bj.bcebos.com/models/yolov3_mobilenet_v1_270e_coco.pdparams）；
4. trainer.train(FLAGS.eval)启动训练，--eval标志决定是否在训练过程中周期性地执行验证。

2. 配置文件深度解读

该训练配置通过_BASE_字段继承 5 个基础配置，这是 PaddleDetection 的核心配置组织方式：

_BASE_: [ '../datasets/roadsign_voc.yml', # 数据集与评测指标 '../runtime.yml', # 运行期通用配置 '_base_/optimizer_40e.yml', # 优化器与学习率 '_base_/yolov3_mobilenet_v1.yml', # 模型结构 '_base_/yolov3_reader.yml', # 数据读取与增强 ] pretrain_weights: https://paddledet.bj.bcebos.com/models/yolov3_mobilenet_v1_270e_coco.pdparams weights: output/yolov3_mobilenet_v1_roadsign/model_final YOLOv3Loss: ignore_thresh: 0.7 label_smooth: true

各继承配置的关键内容如下：

优化器与学习率（configs/yolov3/base/optimizer_40e.yml）：共训练 40 个 epoch；base_lr: 0.0001基础学习率；学习率调度采用PiecewiseDecay（在第 32、36 epoch 时按gamma: 0.1阶梯衰减）叠加LinearWarmup（前 100 步从 1/3 倍线性预热到全量学习率）；优化器为 Momentum（动量 0.9），配合 L2 权重衰减（factor 0.0005）。微调场景下学习率通常远小于从头训练，以保留预训练特征。

模型结构（configs/yolov3/base/yolov3_mobilenet_v1.yml）：architecture: YOLOv3，主干为MobileNet（scale 1，输出特征层[4, 6, 13]），颈部为YOLOv3FPN，检测头为YOLOv3Head（3 个尺度共 9 组 anchor，anchor_masks将 9 组 anchor 分配到 32/16/8 三个下采样层级）；BBoxPostProcess负责解码与MultiClassNMS后处理，其中conf_thresh: 0.005、nms_threshold: 0.45、keep_top_k: 100。该文件还额外覆盖了YOLOv3Loss：开启label_smooth: true并把ignore_thresh设为 0.7，用于缓解小数据集的过拟合。

数据读取与增强（configs/yolov3/base/yolov3_reader.yml）：训练阶段batch_size: 8，依次执行Decode → Mixup → RandomDistort → RandomExpand → RandomCrop → RandomFlip等样本级增强，并配合BatchRandomResize在 320~608 之间随机缩放、Gt2YoloTarget将标注转换为 YOLOv3 的网格目标格式；评估与推理阶段则统一Resize到 608×608，batch_size: 1。这也是"小数据集上短时间训出好效果"的数据层面保障。

运行期配置（configs/runtime.yml）：定义了use_gpu: true、log_iter: 20（每 20 个迭代打印一次日志）、save_dir: output（模型保存根目录）、snapshot_epoch: 1（每个 epoch 保存一次快照）等全局字段，其中-o use_gpu=true覆盖的正是这里的use_gpu。

3. 使用 VisualDL 实时观察训练曲线

如果想实时观察 loss 变化曲线，可在训练命令中追加--use_vdl=true，并通过--vdl_log_dir设置日志保存路径。VisualDL 需要 Python>=3.5，先安装：

python -m pip install visualdl -i https://mirror.baidu.com/pypi/simple

然后带 VisualDL 日志启动训练：

python -u tools/train.py -c configs/yolov3/yolov3_mobilenet_v1_roadsign.yml \ --use_vdl=true \ --vdl_log_dir=vdl_dir/scalar \ --eval

训练过程中（或结束后），通过 visualdl 命令在浏览器中实时查看曲线：

visualdl --logdir vdl_dir/scalar/ --host <host_IP> --port <port_num>

--use_vdl与--vdl_log_dir两个参数在 tools/train.py 中均有明确定义，其中--vdl_log_dir的默认值为vdl_log_dir/scalar，与上面显式指定的路径一致。

五、评估

训练完成后，使用 tools/eval.py 评估模型精度。默认加载配置中weights指向的model_final权重：

python tools/eval.py -c configs/yolov3/yolov3_mobilenet_v1_roadsign.yml -o use_gpu=true

• -c参数指定配置文件；
• -o参数覆盖配置文件中的全局变量；
• 评估目前只支持单卡。

最终模型的 mAP 应在 0.85 左右。由于数据集较小，每次训练结束后的精度会有一定波动，这是小数据集微调的正常现象。

如需更细粒度的评估信息，tools/eval.py 还支持--classwise（输出每个类别的 AP 并绘制 P-R 曲线）、--output_eval（指定评估结果输出路径）等参数，可用于定位具体类别的表现。

六、推理：对任意图像进行预测

评估满意后，即可用训练好的模型对任意图像执行推理：

python tools/infer.py -c configs/yolov3/yolov3_mobilenet_v1_roadsign.yml -o use_gpu=true --infer_img=demo/road554.png

• -c参数指定配置文件；
• -o参数覆盖配置文件中的全局变量；
• --infer_img指定预测图像路径；
• 预测结束后会在output文件夹中生成一张画有预测结果的同名图像。

结果如下图所示：

从 tools/infer.py 源码可知，推理工具还支持更多使用场景：--infer_dir可对目录下所有图像批量推理（--infer_img优先级更高），--infer_list可配合--infer_dir指定图像列表文件，--output_dir自定义输出目录，--draw_threshold/--save_threshold分别控制可视化和保存结果的置信度阈值（默认 0.5）。这些参数使得推理阶段可以直接复用训练配置（数据集、预处理、后处理保持一致），无需额外编写推理脚本。

七、从快速开始到实际业务

本教程通过道路标志检测展示了 PaddleDetection 的完整使用闭环：配置驱动、预训练迁移、三工具分工。其中几个要点在实际业务中具有普遍参考价值：

1. 配置即代码：模型结构、数据、优化策略全部沉淀在 YAML 配置中，通过_BASE_组合复用，换数据集或换模型只需更换配置，无需改动代码；
2. -o覆盖机制：命令行可通过-o key=value灵活覆盖配置字段（如use_gpu、weights），适合快速实验；
3. 微调范式：在 COCO 等大数据集预训练权重的基础上对业务小数据集微调，是短时间内获得可用模型的高效路径；
4. 可视化辅助：VisualDL 实时监控 loss 曲线，便于快速判断训练是否收敛。

实际业务中，建议根据具体需求在 configs 目录下选择合适的模型配置文件进行适配——PaddleDetection 提供了从轻量移动端（如 PicoDet、PP-YOLOE-Tiny）到高精度大模型（如 RT-DETR、DINO）的丰富配置，覆盖检测、实例分割、多目标跟踪与关键点检测等任务。入门阶段先跑通本教程的完整流程，即可在此基础上平滑迁移到更多业务场景。

• 人工智能
• 深度学习
• 计算机视觉