第二十一届走马观碑赛题引入目标板识别环节，车模需要检测目标板、判断类别，并执行对应通行策略。官方演示方案采用 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: Mouse1: 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