1. 树莓派5 上 YOLOv8 只有 5fps，问题到底卡在哪

如果你在树莓派5 上直接跑过 YOLOv8，大概率见过这个画面：CPU 占用拉满，风扇狂转，帧率却只有 5fps 左右，视频流检测基本没法看，只能当个抓拍工具用。这不是你代码写得不好，而是树莓派5 的 CPU 和集成 GPU 本来就不适合做密集的卷积推理。YOLOv8n 在 640×640 输入下，单帧的算力需求已经远超它能实时处理的范围。

真正让边缘端跑出高帧率的思路，是把推理卸载到专用 NPU 上。Hailo-8 就是干这个的，26 TOPS 的算力，功耗却只有几瓦，配合树莓派5 的 PCIe 接口，能把 YOLOv8 的推理速度拉到几十甚至上百帧。但问题在于，Hailo-8 不能直接吃 PyTorch 的 .pt 文件，也不能直接吃 ONNX，它只认自己编译出来的 .hef 格式。从 ONNX 到 HEF 这一步，就是整个链路里最容易卡住的地方。

这篇内容聚焦的就是这条完整链路：自建数据集训练出的 YOLOv8 模型，怎么导出 ONNX，怎么用 Dataflow Compiler 转成 HEF，校准集怎么准备，推理脚本怎么调，最后在树莓派5 上验证帧率。适合已经会训练 YOLOv8、但卡在部署环节的人。如果你连 YOLOv8 训练都没跑通过，建议先把训练流程走一遍再回来。

我试过在 WSL2 里配转换环境，也踩过 CUDA 版本不匹配、numpy 冲突、校准集路径写错这些坑，下面会把每一步的命令和配置文件骨架都给出来，你照着改路径就能用。

2. 转换环境准备：WSL2 + CUDA 11.8 + Hailo Dataflow Compiler

Hailo 的模型转换工具叫 Hailo Dataflow Compiler，它只能在 Ubuntu 20.04 或 22.04 上跑，而且对 CUDA 和 cuDNN 版本有硬性要求。我建议在本地 Windows 的 WSL2 里装 Ubuntu 22.04，不要用服务器，因为服务器环境经常变动，版本一冲突就得重配。WSL2 默认装的是 24.04，需要先卸载再装 22.04。

装好 Ubuntu 22.04 后，先确认基础环境：

python3 --version
nvcc --version
ls -l /usr/local/cuda/lib64/libcudnn.so*

CUDA 建议 11.8，cuDNN 对应 8.9。cuDNN 没装或者版本不对，后面编译时会报 libcudnn.so 找不到。WSL2 里装 CUDA 和 cuDNN 的流程和原生 Ubuntu 基本一致，注意装完后把环境变量写进 ~/.bashrc：

export PATH=/usr/local/cuda-11.8/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH

然后装 Python 虚拟环境相关的包：

sudo apt install python3-pip python3.10-venv python3.10-dev python3.10-distutils python3-tk libfuse2 graphviz libgraphviz-dev

创建并进入虚拟环境：

python3 -m venv hailo_venv
source ./hailo_venv/bin/activate

虚拟环境的作用是隔离依赖，因为 Hailo 的工具链对 numpy、numba 这些包的版本很敏感，和系统里的其他 Python 包混在一起很容易冲突。

接下来安装 Dataflow Compiler 的 whl 包。这个包需要从 Hailo 开发者平台获取，版本要和你的 HailoRT 固件匹配，我用的 3.30.0：

pip install hailo_dataflow_compiler-3.30.0-py3-none-linux_x86_64.whl

装完后验证：

hailo -h
pip freeze | grep hailo

没有报错就说明工具链装好了。然后把 Hailo Model Zoo 拉下来，进入目录安装：

cd hailo_model_zoo
pip install -e .

这一步大概率会报 numpy 和 numba 的版本冲突。解决办法是先卸载再装指定版本：

pip uninstall numpy numba
pip install numpy==1.23.3 numba==0.60.0

然后再跑一次 pip install -e .，基本就能过了。

3. 从 ONNX 到 HEF：YOLOv8 模型转换全流程

3.1 导出 ONNX

在训练 YOLOv8 的机器上，拿到 best.pt 后执行：

yolo export model=./best.pt imgsz=640 format=onnx opset=11

opset 用 11，这是 Hailo 工具链兼容性最好的版本。导出后会得到 best.onnx，把它和校准集图片一起放到 WSL2 的 hailo 文件夹下。

3.2 准备校准集

校准集的作用是让编译器在量化时统计激活值分布，直接影响转换后的精度。建议从训练集里抽 100 到 200 张有代表性的图片，放到一个目录里，比如 VOC/images/train/。图片不需要标注文件，只要原图就行。校准集覆盖的场景越全，量化损失越小。

3.3 配置文件骨架

Hailo Model Zoo 里已经有 YOLOv8 的 yaml 模板，在 hailo_model_zoo/hailo_model_zoo/cfg/networks/ 下能找到 yolov8n.yaml。你主要改两个地方：

network_name: yolov8n
network_path: /mnt/d/hailo/best.onnx

network_path 写绝对路径，WSL2 里 /mnt/d 对应 Windows 的 D 盘。operations 和 parameters 保持默认，除非你改了网络结构。

3.4 执行编译

编译命令：

hailomz compile yolov8n \
  --ckpt best.onnx \
  --hw-arch hailo8 \
  --calib-path VOC/images/train/ \
  --classes 20 \
  --performance

参数说明：

参数	含义
--ckpt	ONNX 模型路径
--hw-arch	芯片型号，hailo8 或 hailo8l
--calib-path	校准集图片目录
--classes	检测类别数，按你的数据集填
--performance	开启性能优化，编译时间会变长

编译过程会占用大量显存和内存，建议不要同时开其他大程序。跑完后会在输出目录生成 .hef 文件，这就是树莓派上要用的模型。

注意：--classes 一定要和你的数据集类别数一致，填错了推理时类别会错位。

4. 树莓派5 端部署与帧率验证

4.1 系统与 PCIe 配置

先把树莓派系统更新到最新：

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

然后开启 PCIe Gen 3，否则 Hailo-8 的带宽跑不满：

sudo raspi-config

进入 Advanced Options → PCIe Speed → 选择 Yes，重启。

4.2 安装 Hailo 驱动与工具

sudo apt install hailo-all

重启后验证设备识别：

hailortcli fw-control identify

能打印出设备信息和固件版本就说明驱动正常。

4.3 拉取示例代码

git clone https://github.com/hailo-ai/hailo-rpi5-examples.git
cd hailo-rpi5-examples
source setup_env.sh

如果 clone 慢，可以让树莓派连手机热点。进入虚拟环境：

source ./venv_hailo_rpi5_examples/bin/activate

4.4 标注 JSON 配置

在 resources/ 下新建 best-labels.json，内容骨架：

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

labels 数组最前面要加一个占位项，label_offset 设为 1，否则标注会错位一个。这是实测下来必须加的一步。

4.5 安装 apps-infra 依赖

pip install git+https://github.com/hailo-ai/hailo-apps-infra.git

必须在虚拟环境里执行，网络不通就换热点。

4.6 运行推理

python3 basic_pipelines/detection.py \
  --hef-path resources/yolov8n.hef \
  --input rpi \
  --labels-json resources/best-labels.json

--input rpi 用 CSI 摄像头。USB 摄像头先用 get-usb-camera 找到设备号，然后：

python basic_pipelines/detection.py --input /dev/video0

第一次运行如果报环境错误，再执行一次 source setup_env.sh 然后重跑即可。

4.7 帧率验证

运行后终端会打印每帧的推理耗时和 FPS。YOLOv8n 在 640×640 下，Hailo-8 实测能稳定在 80 到 120fps 之间，具体取决于模型复杂度和后处理开销。如果帧率明显偏低，先检查 PCIe 是否跑在 Gen 3，再看 hailortcli 的吞吐数据。

5. 常见报错与排查

编译时报 libcudnn.so not found：cuDNN 没装或版本不对，确认 /usr/local/cuda/lib64/ 下有 libcudnn.so.8，并检查 LD_LIBRARY_PATH。

pip install -e . 报 numpy 冲突：卸载 numpy 和 numba，装 numpy==1.23.3 和 numba==0.60.0。

hailortcli fw-control identify 无输出：PCIe 没启用或驱动没装好，重跑 sudo apt install hailo-all 并重启。

推理时类别错位：labels 数组没加占位项，或 label_offset 没设成 1。

帧率只有十几 fps：PCIe 还在 Gen 2，回 raspi-config 确认 PCIe Speed 设置。

校准集路径报错：--calib-path 要用绝对路径或相对于执行目录的正确路径，目录里必须有图片文件。

6. 模型调优与长期编码建议

转换后的 HEF 模型相比原始 PyTorch 模型会有一定精度损失，这是量化带来的正常现象。如果发现某些类别漏检严重，可以增加校准集里该类别的样本数量，或者调整 detection_threshold。Hailo 官方有模型优化指南，涉及逐层量化和敏感层分析，有兴趣可以深入。

如果你后续要频繁做模型转换和推理脚本调试，建议把转换环境固定下来，不要每次重装。另外，如果你在写推理脚本时需要快速验证模型输出格式、调试后处理逻辑，可以用 TaoToken 的模型对话功能直接贴代码和输出问问题，比翻文档快。

对于长期在边缘端做编码和 Agent 开发的场景，TaoToken 的 Coding Plan 提供了稳定的模型调用额度，适合把模型转换、脚本调试、报错排查这些环节串起来。接入文档和 API Key 在下面：

API Key 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api_keys

接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model_chat

Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding_plan

整个链路跑通后，你会发现树莓派5 + Hailo-8 的组合在边缘端确实能打，26 TOPS 的算力不是纸面参数，YOLOv8 跑出上百帧是实际可用的水平。关键是把 ONNX 导出、校准集准备、HEF 编译这三步的版本和路径对齐，剩下的就是调参和验证。