第二十一届走马观碑赛题引入目标板识别环节，车模需要检测目标板、判断类别，并执行对应通行策略。官方演示方案采用 YOLOv5 + ONNX + OpenCV DNN。本文按 Linux 环境整理完整流程，覆盖环境搭建、数据集构建、模型训练、ONNX 转换和龙芯平台部署。

当前子工程目录名为 tb_yolo，其中 tb 表示 target board，yolo 表示 yolo v5 检测方案。

一、环境与资源准备

本节进行 Linux 下训练环境搭建。当前项目通常在专用虚拟机中配合 VS Code 开发，因此直接使用系统 Python 环境。

1.1 安装系统依赖

在 Ubuntu/Debian 类系统中执行：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ sudo apt update
zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ sudo apt install -y python3 python3-pip

1.2 初始化 Python 环境

在仓库根目录执行：

zhengyang@ubuntu:~$ cd /opt/2k0300/loongson_2k300_lib/tb_yolo/
zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ ./scripts/setup_env.sh

该脚本会完成：

• 检查当前 python3 和 pip 是否可用；
• 安装 tb_yolo/requirements-linux.txt 中的辅助依赖；
• 安装 yolo v5 自带 requirements.txt。

1.3 子工程目录结构

当前 tb_yolo 目录按职责划分如下：

tb_yolo/
  vendor/
    yolov5/                        # 第三方 YOLOv5 上游源码
  configs/
    target_board.names             # 类别名
    target_board.yaml              # YOLOv5 数据集配置
  dataset/
    images/train/
    images/val/
    labels/train/
    labels/val/
    # 已迁入演示数据集：train 401 张，val 51 张
  models/
    pretrained/yolov5n.pt          # 轻量级预训练权重
    demo/best.pt                   # 演示包已有 PyTorch 权重
    demo/best.onnx                 # 演示包已有 ONNX 模型
  outputs/
    train/                         # 新训练输出
  scripts/                           # 本项目流程脚本
  docs/                            # 部署和训练记录文档

vendor/yolov5 是第三方源码目录，里面自带 data/、models/、utils/ 等目录。外层的 configs/、dataset/、models/、outputs/ 才是本目标板项目自己的配置、数据集、权重和输出。日常操作优先使用外层目录和 scripts/ 脚本。

原本放在 vendor/yolov5/dataset02 的数据集已经迁移到外层 tb_yolo/dataset/。vendor/yolov5 只保留 yolo v5 源码和上游自带示例文件，不再作为项目数据目录使用。

1.4 已接入的本地模型

当前已经整理出：

vendor/yolov5
models/pretrained/yolov5n.pt
models/demo/best.pt
models/demo/best.onnx
dataset/images/train
dataset/images/val
dataset/labels/train
dataset/labels/val

权重下载地址可作为备用来源：《yolo v5权重文件下载》。

二、数据集构建与配置

2.1 测试数据集

2.1.1 数据来源

测试数据集来自官方演示数据包，主要用于快速验证当前 yolo v5 训练、导出和推理流程是否跑通。该数据集已经迁移到外层 dataset/，不再放在 vendor/yolov5 源码目录中。

2.1.2 目录结构

当前测试数据集结构如下：

dataset/
  images/
    train/
    val/
  labels/
    train/
    val/

2.1.3 数据规模

当前数据量如下：

images/train: 401
labels/train: 401
images/val:   51
labels/val:   51

2.1.4 类别文件

测试数据集对应的类别文件为：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ cat configs/target_board.names

当前演示包类别为：

Mouse
Printer
drill
Wrench
Screwdriver

2.1.5 快速验证

如果只是验证流程，可以直接使用该测试数据集训练：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ ./scripts/train_yolov5_linux.sh

注意：智能车项目，应按实际目标板重新采集图片、标注标签，并更新类别文件。

2.2 用户目标数据集

用户目标数据集指自己采集、标注并用于最终训练的真实目标板数据。以本项目为例，就是走马观碑赛题中的目标板图片数据。

2.2.1 数据集目录规范

yolo v5 数据集需要图片和标签分开存放，训练集和验证集也需要分开。最终训练目录仍统一整理到：

dataset/
  images/
    train/
    val/
  labels/
    train/
    val/

关键原则：

• images/train 与 labels/train 一一对应；
• images/val 与 labels/val 一一对应；
• 图片名和标签名除后缀外必须一致；
• 无目标负样本也可以保留空 txt 标签文件。

2.2.2 准备原始图片

建议先建立临时原始数据目录：

raw_dataset/
  images/       # 全部原始图片
  labels/       # LabelImg 输出的 YOLO 标签

将采集到的目标板图片放入：

raw_dataset/images/

建议覆盖以下场景：

近距离、中距离、远距离
正视、左偏、右偏、俯仰角变化
强光、弱光、背光、阴影
运动模糊、轻微失焦
赛道背景干扰
目标板边缘不完整

2.2.3 使用 LabelImg 标注

安装和启动：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ labelimg

LabelImg 设置：

标注格式切换为 YOLO
Open Dir 选择 raw_dataset/images
Change Save Dir 选择 raw_dataset/labels

常用快捷键：

W       创建矩形框
A       上一张
D       下一张
Ctrl+S  保存

标注完成后，raw_dataset/labels/ 中应生成同名 .txt 文件，例如：

0001.jpg -> 0001.txt
0002.jpg -> 0002.txt

yolo标签格式如下：

class_id center_x center_y width height

其中坐标均为 0-1 的归一化值。

2.2.4 划分训练集和验证集

执行：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ python3 scripts/split_dataset.py \
  --images raw_dataset/images \
  --labels raw_dataset/labels \
  --out dataset \
  --val-ratio 0.2 \
  --copy

说明：

--val-ratio 0.2  表示 20% 数据作为验证集
--copy           表示复制文件，不移动原始 raw_dataset

执行后，raw_dataset/ 中的原始数据会按比例整理到 dataset/。如果 dataset/ 中原本是测试数据集，请先确认是否需要备份，再覆盖为真实目标板数据。

2.2.5 类别文件

编辑：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ vim configs/target_board.names

每行一个类别。当前演示包类别为：

Mouse
Printer
drill
Wrench
Screwdriver

训练自己的目标板时，将其改成真实目标板类别，例如：

left
right
straight
stop
slow

注意：target_board.names、LabelImg 生成的 classes.txt、推理代码中的类别数组，三者顺序必须完全一致。

2.2.6 生成 yolo v5 数据集配置

执行：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ python3 scripts/update_yaml_from_names.py

生成：

configs/target_board.yaml

示例内容：

path: /opt/2k0300/loongson_2k300_lib/tb_yolo/dataset
train: images/train
val: images/val
test: null
names:
  0: Mouse
  1: Printer

其中 path 为绝对路径，避免 yolo v5从不同工作目录启动时找错数据集。

三、模型训练与转换

3.1 推荐训练参数

当前封装脚本默认参数如下：

weights: models/pretrained/yolov5n.pt
data:    configs/target_board.yaml
imgsz:   64
epochs:  150
batch:   4
device:  cpu
project: outputs/train
name:    exp_ls2k
workers: 0
cache:   disk

参数说明：

--weights      预训练权重，默认 yolov5n.pt
--data         数据集配置文件
--epochs       训练轮次，建议 100-200
--batch-size   每批图片数量，CPU 或小显存建议 2-4
--imgsz        输入尺寸，智能车建议 64 或 96
--device       cpu 或 cuda:0
--workers      数据加载线程，稳定起见默认 0
--cache        disk，缓存到磁盘

3.2 启动训练

默认训练：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ ./scripts/train_yolov5_linux.sh

指定训练参数：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ IMG_SIZE=96 EPOCHS=200 BATCH_SIZE=4 DEVICE=cuda:0 RUN_NAME=exp_target_96 \
  ./scripts/train_yolov5_linux.sh

也可以显式指定配置和权重：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ ./scripts/train_yolov5_linux.sh \
  configs/target_board.yaml \
  models/pretrained/yolov5n.pt

训练完成后，最优权重位于：

outputs/train/exp_ls2k/weights/best.pt

训练得到的 .pt 是 PyTorch 权重，龙芯平台 OpenCV DNN 推理需要使用 .onnx。

3.3 安装导出依赖

初始化脚本已经安装了：

• onnx；
• onnxruntime；
• onnxsim。

如果需要手动安装：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ python3 -m pip install onnx onnxruntime onnxsim

3.4 导出 ONNX

默认导出新训练结果：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ ./scripts/export_onnx_linux.sh

指定权重和输入尺寸：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ IMG_SIZE=96 OPSET=12 \
  ./scripts/export_onnx_linux.sh \
  outputs/train/exp_target_96/weights/best.pt

等价 yolo v5原生命令：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ python vendor/yolov5/export.py \
  --weights outputs/train/exp_ls2k/weights/best.pt \
  --include onnx \
  --opset 12 \
  --imgsz 64

导出后会在 best.pt 同级目录生成：

best.onnx

注意：导出时的 --imgsz 必须与训练时一致。

3.5 使用演示 ONNX

如果只是验证官方演示模型，可以直接使用：

models/demo/best.onnx

3.6 模型测试与上车验证

模型训练完成后，不建议直接上车。建议按以下顺序测试：

训练机图片测试 -> 导出 ONNX -> 龙芯平台离线推理测试 -> 智能车实车测试

3.6.1 训练机图片测试

先用训练得到的 best.pt 在本机跑图片检测，确认类别和框位置基本正确：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ python3 vendor/yolov5/detect.py \
  --weights outputs/train/exp_ls2k/weights/best.pt \
  --source dataset/images/val \
  --data configs/target_board.yaml \
  --imgsz 64 \
  --conf-thres 0.25 \
  --project outputs/detect \
  --name exp_ls2k_val

检测结果会保存到：

outputs/detect/exp_ls2k_val/

重点检查：

• 类别是否识别正确；
• 目标框是否覆盖目标板主体；
• 背景干扰是否产生明显误检；
• 远距离、小目标、强光和运动模糊图片是否仍能识别。

3.6.2 导出并检查 ONNX

本机图片测试通过后，再导出 ONNX：

zhengyang@ubuntu:/opt/2k0300/loongson_2k300_lib/tb_yolo$ ./scripts/export_onnx_linux.sh \
  outputs/train/exp_ls2k/weights/best.pt

随后使用 Netron 检查模型输入输出，确认：

输入尺寸与训练 imgsz 一致
输出节点名通常为 output0
输出最后一维等于 类别数 + 5

3.6.3 龙芯平台离线推理测试

将导出的模型复制到智能车或龙芯开发环境中，例如：

outputs/train/exp_ls2k/weights/best.onnx

然后在官方 OpenCV DNN 推理工程中同步类别数量、类别名称、输出长度和输出节点名。关键修改项见第四章 4.2 龙芯 OpenCV DNN 推理工程适配。

建议先用保存的摄像头图片或测试图片做离线推理，不要直接跑车：

输入：单张目标板图片或录制视频帧
输出：类别、置信度、目标框坐标
判断：结果是否与训练机 detect.py 输出趋势一致

3.6.4 智能车实车测试

离线推理稳定后，再接入智能车主程序。实车测试建议分阶段进行：

• 静态测试：目标板固定不动，检查识别类别和置信度；
• 低速测试：车模低速接近目标板，检查连续帧识别是否稳定；
• 策略测试：确认不同类别目标板能触发正确通行策略；
• 干扰测试：加入光照变化、背景干扰、角度变化和运动模糊。

如果实车误检或漏检明显，优先补充对应场景的数据重新训练，再调整置信度阈值和输入尺寸。

四、部署与常见问题

4.1 使用 Netron 检查模型

导出后建议用 Netron 打开 best.onnx，确认输入输出：

输入节点：images
输入尺寸：float32[1,3,64,64] 或 float32[1,3,96,96]
输出节点：output0
输出维度：float32[1,N,classes + 5]

示例：如果类别数为 5，则最后一维应为：

5 + 5 = 10

4.2 龙芯 OpenCV DNN 推理工程适配

详细说明见：

docs/deploy_opencv_dnn.md

在官方模板类似 Libraries/Driver/LQ_YOLO.cpp 的位置，需要同步：

Category_NUM = 实际类别数量
DATA_LEN = Category_NUM + 5
类别名称数组 = 按 configs/target_board.names 顺序填写
conf = 置信度阈值
out_name = Netron 中看到的输出节点名，常见为 output0

部署文件至少包括：

best.onnx
类别名称表
推理可执行程序

4.4 类别顺序不一致

以此文件为准：

configs/target_board.names

LabelImg 的 classes.txt、yolo v5 yaml、龙芯推理代码中的类别数组都要按同一顺序。

4.5 图片和标签对不上

检查每张图片是否有同名标签：

images/train/0001.jpg
labels/train/0001.txt

如果图片没有目标，也建议保留空的 .txt 标签文件。

4.6 OpenCV DNN 输出维度不匹配

检查：

target_board.names 类别数量
target_board.yaml names 数量
推理代码 DATA_LEN 是否等于 类别数 + 5
Netron 中输出节点名是否为 output0