【树莓派5 AI HIT+】自建数据集并使用YOLOV8实现目标检测

更新日期: 2025年4月15日

本教程基于Custom Object Detection on Raspberry Pi AI Kit with Hailo8L，对其中的流程和指令进行了优化，解决了常见问题。适用于Hailo官网2025年4月2日更新的软件包，不保证后续版本的兼容性。

1. 自建数据集

RoboFlow是一个优秀的数据集制作工具。关于数据集制作和树莓派AI扩展板的详细介绍，可直接参考原教程。创建完成后下载ZIP文件并解压，同时记录下Roboflow提供的下载代码，后续训练时会用到。

2. 训练和导出YOLO模型

在模型训练部分，由于我是单目标检测，并且没有其他对模型更多的要求，所以也是直接使用教程提供的的colab方法，也可以使用网上其他自建的或现成的yolo训练方法，只要能生成最终我们需要的yolov8.onnx模型即可

2.1 训练注意事项

• 安装ultralytics时，删除版本号限制，直接安装最新版：
  

下面是YOLOV8的性能对比图，接下来统称n（nano）和s（small）为轻量模型，m（middle）、l（large）和x统称为大模型。官方推荐的模型是yolov8m（middle）

2.2 Colab长时间训练方案

如果你是轻量模型，可以colab给出的步骤按照一步一步运行，并实时查看模型的性能和输出，如果你的数据集很大或者是大模型，训练通常需要几个小时，而长时间不操作colab会自动断连，训练就前功尽弃了，可以在Custom Training部分使用下面代码一步到位，训练完直接导出模型，也就是说点击运行就可以离开了，等几个小时后查看是不是有模型下载好即可。

# Custom Training
%cd {HOME}
!yolo task=detect mode=train model=yolov8l.pt data={dataset.location}/data.yaml epochs=100 batch=16 imgsz=640 plots=True

# Model Validation
%cd {HOME}
!yolo task=detect mode=val model={HOME}/runs/detect/train/weights/best.pt data={dataset.location}/data.yaml

# Inference
%cd {HOME}
!yolo task=detect mode=predict model={HOME}/runs/detect/train/weights/best.pt conf=0.25 source={dataset.location}/test/images save=True

# Export ONNX
from ultralytics import YOLO
model = YOLO("/content/runs/detect/train/weights/best.pt")
model.export(format="onnx")

# Download ONNX
from google.colab import files
files.download('/content/runs/detect/train/weights/best.onnx')

如果模型实在太大，训练时间一定会超过colab规定时间，减少epochs数也无法解决，可以自己在本地利用colab里给出代码进行训练，python代码colab都已经给出，也可以直接参考官方训练手册的CLI命令行方法，并不困难。

至此，我们会获得一个YOLO的ONNX模型

3. 编译ONNX模型到HEF格式

这是最关键的一部分，踩了无数的坑，被各种库版本和依赖问题折磨了很久，就不要看之前的教程了，直接使用我下面的方案，步骤正确是一定可以编译成功的。
教程给出的是使用Windows的WSL进行编译，对于轻量的模型无所谓，但大模型在optimism部分会非常慢而且无法使用GPU，很可能会损失精度，建议还是在Ubuntu服务器或双系统下进行编译

3.1 选择编译环境

WSL环境安装（可选）
以管理员身份运行命令行：

# 查看可用的Linux虚拟机
wsl --list --online

# 下载Ubuntu22.04
# 重启计算机后再次运行下载命令激活Ubuntu
wsl --install -d Ubuntu-22.04
sudo apt update

Conda虚拟环境（推荐）：conda下载就不多说了，直接在conda里下载hailo支持的cuda版本即可

创建指定python版本的conda环境：

conda create --name hailo python=3.10.12
conda activate hailo

3.2 快速配置编译环境

为了避免出现环境配置问题，我建了一个gitee仓库作为编译的工作空间，并写了一个脚本来简化环境配置，会踩到的坑和配置问题都已经解决，可以直接在conda环境里克隆：

git clone https://gitee.com/li-bozha0/compile-onnx-to-hef.git
cd compile-onnx-to-hef

3.3 下载Hailo软件包

从Hailo Software Downloads注册账号并下载三个软件包：

• Hailo Dataflow Compiler (>=3.30.0)
• HailoRT – Python package (whl) (>=4.20.0)
• HailoRT – Ubuntu package (deb) (>=4.20.0)

重要：确保下载的三个软件包为同一天更新的版本，否则可能出现no module named ‘hailo_platform’（非常常见）等兼容性问题。

3.4 准备编译环境

将下载的三个软件包放在当前工作空间

运行安装脚本配置环境：

chmod +x install_compile.sh
./install_compile.sh

该脚本会自动完成：

• 安装必要的Python依赖库
• 使用国内镜像源加速下载
• 配置Hailo环境
• 克隆并设置hailo_model_zoo

中间会询问是否启动hailort，直接输入y即可

安装成功后，会显示类似以下信息：

HailoRT v4.21.0
Hailo Dataflow Compiler v3.31.0
Hailo Model Zoo v2.15.0

再从Roboflow下载的数据集中，复制/train到当前工作空间。执行编译前的完整工作空间如下所示：

3.5 模型编译

使用以下命令将ONNX模型编译为HEF格式：

hailomz compile yolov8m --ckpt=myyolov8.onnx --hw-arch hailo8 --calib-path train/images --classes 1 --performance

参数说明：

• yolov8m：使用的模型架构
• –ckpt=myyolov8.onnx：ONNX模型文件名（替换为实际文件名）
• –hw-arch hailo8：目标硬件平台（根据设备选择，如hailo8、hailo15h等，建议先跳到4.1节，使用hailortcli fw-control identify 查看自己的设备架构）
• –calib-path train/images：校准图像目录
• –classes 1：类别数量（根据模型调整）
• –performance：启用性能优化

编译yolov8m.onnx在性能模式下一定会编译失败，解决方法见yolov8m编译失败解决方法

编译完成后（优化的过程很长，我v8m的模型足足编译了12小时），将在当前目录生成.hef文件，可直接部署到Hailo硬件上。

4. 部署与测试

4.1 硬件配置

• 树莓派5：16GB内存版本，BCM2712处理器 2.4GHz四核64位Arm Cortex-A76，搭配Raspberry Pi AI HAT+ (26T)。
• 操作系统：安装Raspberry Pi OS 64-Bit（Bookworm版本）

更新至最新固件：

sudo apt update && sudo apt full-upgrade
sudo rpi-eeprom-update -a

设置PCIe Gen3模式（提升Hailo模块性能）：

sudo raspi-config
# 进入Advanced Options > PCIe Speed > Gen3打开PCIe

安装Hailo驱动：

sudo apt install hailo-all
sudo reboot

验证硬件识别

hailortcli fw-control identify

可以看到我的是设备架构是HAILO8，由此得知上一节编译的时候 --hw-arch要选择hailo8架构

4.2 下载rpi5-examples

在树莓派上科学上网比较麻烦，所以同样地，我自建了一个gitee仓库，将官方的example和apps-infra架构完整拉取至本地；同时优化了install.sh，解决了官方脚本的依赖和下载失败等问题。

# 克隆我自建的rpi-examples
git clone https://gitee.com/li-bozha0/hailo-rpi5-examples.git
cd hailo-rpi5-examples
./install.sh

脚本将自动下载所有需要的库，并且编译apps-infra

注意：即便是用了国内镜像，下载整个官方提供的resources还是很慢，所以我注释掉了以下部分。
hailo-rpi5-examples/ install.sh
hailo-apps-infra/update setup.py
可以根据自己需求下载其他想要的模型

4.3 运行模型

创建一个自定义标签文件：hf100yolov8m.json。将“标签”部分替换为检测对象名称，然后保存。

{
"iou_threshold": 0.45,
"detection_threshold": 0.7,
"output_activation": "none",
"max_boxes":200,
"anchors": [
 [ 116, 90, 156, 198, 373, 326 ],
 [ 30, 61, 62, 45, 59, 119 ],
 [ 10, 13, 16, 30, 33, 23 ]
],
"labels": [
 "UAV"
]
}

参数说明：

• iou_threshold（交并比阈值）：用于非极大值抑制（NMS）阶段，控制重叠框的合并阈值。当两个预测框的IoU（交并比）超过该阈值时，仅保留置信度更高的框。
• detection_threshold（检测阈值）：置信度过滤阈值，仅保留置信度高于该值的预测框。
• output_activation（输出激活函数）：指定输出层是否应用激活函数。
• max_boxes（最大检测框数）：限制每张图像最多检测出的目标数量，防止内存溢出或处理冗余框。
• 锚框（Anchors）配置：模型基于锚框预测偏移量（Δx, Δy, Δw, Δh），通过公式计算实际边界框的位置和尺寸 。
• labels（标签列表）：定义模型需要检测的类别名称。

其他参数（可能会用到）：

• label_offset（标签偏移量）：索引对齐，某些数据集（如COCO）的类别索引从1开始（背景类为0），而模型输出可能从0开始。通过设置label_offset=1，可将模型预测的类别索引（0-based）与数据集的标签（1-based）对齐。

激活虚拟环境

source setup_env.sh

使用如下命令运行运行模型

python3 basic_pipelines/detection.py --hef-path hf100yolov8m.hef --input rpi --labels-json hf100yolov8m.json --frame-rate 60 --show-fps

参数说明：

• –hef-path ：指定Hailo模型文件（HEF格式）的路径。
• –input rpi：设置输入源为树莓派摄像头，若需其他输入源（如USB摄像头、视频文件），参看官方手册。
• –labels-json hf100yolov8m.json：加载与模型匹配的标签配置文件。
• –frame-rate 60：设定目标帧率为60 FPS。
• –show-fps：在输出画面上显示实时帧率（FPS）。
  
  运行完将传回摄像头的图像，下面是我的摄像头画面，可以看到成功识别出目标
  

参考教程

• Custom Object Detection on Raspberry Pi AI Kit with Hailo8L
• Hailo’s Community
• Hailo_model_zoo
• Hailo Raspberry Pi 5 Examples
• Ultralytics YOLO Docs
• YouTube - Custom YOLOV8 Object Detection