💡 **环境搭建是基础**: 文章首先强调了在Linux系统下部署Hailo AI Software Suite Docker环境的重要性，包括安装PCIe驱动、解压安装包以及验证环境配置，为后续的模型转换和推理奠定基础。

⚙️ **模型转换的关键步骤**: 详细介绍了将ONNX模型转换为HEF格式的流程，包括准备ONNX模型、YAML配置文件、校准集，并使用`hailomz compile`命令进行转换，特别指出了`--classes`参数的设置以及修改`yolov11n.yaml`和后处理配置文件以适配模型和设备需求。

🚀 **树莓派端推理部署**: 阐述了在树莓派上进行图像目标检测的步骤，包括创建虚拟环境、安装`pyHailoRT`驱动、克隆Hailo应用代码示例、下载依赖，以及最终通过`object_detection.py`脚本执行推理，并提及了修改`coco.txt`以适配自定义类别名称。

前言

本次任务是实现将yolov11n.onnx格式模型转换为HEF格式模型，并使用HEF模型在边缘设备树莓派上对图像进行目标检测。这两个步骤分别在不同的环境中完成，实现起来比较复杂繁琐。作为一个实习生和初学者，笔者花费了比较长的时间进行探索和实现，做此文章用于记录、学习与分享。

环境说明

包含Hailo Model Zoo、Hailo DataFlow Compiler和HailoRT的Docker环境(Linux系统);树莓派(使用shell连接)，下载Hailo-Application-Code-Examples项目

1. 模型转换

Linux系统中，到Hailo官网注册并下载合适版本的AI Software Suite(本次使用的具体版本是：hailo_ai_sw_suite_2025-01_docker.zip)，里面包含Hailo Dataflow Compiler，Hailo Model Zoo和HailoRT。

准备软件安装包

创建新目录 mkdir my_docker，进入到my_docker目录下，放入下载好的安装包hailo_ai_sw_suite_ 2025-01_docker.zip。另外，再下载对应HailoRT版本的驱动 hailopcie-driver_4.20.0_all.deb(选择同一时间发布的)。

打开终端，开始部署环境

1)安装PCIe驱动程序：

sudo dpkg -i hailort-pcie-driver_4.20.0_all.deb

2)重启电脑: reboot
3)将安装包hailo_ai_sw_suite_2025-01_docker.zip 解压

unzip hailo_ai_sw_suite_2025-01_docker.zip 

在当前目录下，多了一个hailo_ai_sw_suite_2025-01.tar.gz 文件和一个hailo_ai_sw_suite_docker_run.sh 文件。

执行 ./hailo_ai_sw_suite_docker_run.sh ，自动创建一个docker容器，同时在当前目录下创建了一个文件夹 shared_with_docker。另外，可以看到，环境名字和用户名字已经变成了 (hailo_virtualenv) hailo@xxx:/local/workspace$

查看容器信息：使用命令行，列出当前系统中所有容器的详细信息，包括容器ID，镜像名称，启动命令，创建时间，状态，端口映射及容器名称等。

sudo docker ps -a

查看用户： whoami 看到结果： hailo 。

使用 pip list | grep hailo 命令，可以看到安装了Hailo相关的软件。

到此Hailo环境部署完成。(此前是逐个安装Hailo相关软件，由于版本冲突问题，最后选择下载套装的Hailo的Docker版本)

模型转换

1.准备自己训练好的 yolov11n.onnx格式模型文件；
2.从Hailo model zoo网站下载yolov11n.yaml文件；
3.另外，创建文件夹(此处命名为YOLO_img_data) 放置训练图像，作为校准集合。

先将所有会用到的文件放置在宿主机的 /home/Downloads/ 目录下，然后，使用命令行将文件复制到容器内的/local/workspace/ 目录下。从上面可以看到，当前使用的容器的ID: xxx_52(换成自己的CONTAINER ID)。
这种方式比较笨，效率低，可以使用绑定挂载或者数据卷等方式实现，请读者自行学习。

# 将文件从宿主机传输到docker内sudo docker cp /home/Downloads/xxx xxx_52:/local/workspace/# 将文件从docker传输到宿主机sudo docker cp xxx_52:/local/workspace/xxx /home/Downloads/

说明：此处xxx代表自己想要传的文件； xxx_52表示当前使用的容器的ID:。

在/local/workspace/ 目录下，使用 ls 命令，已经可以查看到yolov11n.onnx文件和yolov11n.yaml文件。

在YOLO_img_data目录下，将图像压缩包解压，发现所有图像放置在/images文件夹下。从而知道校准集位置：/local/workspace/YOLO_img_data/images/。

使用命令行 开始转换格式：

hailomz compile --ckpt ./yolov11n.onnx --calib-path /local/workspace/YOLO_img_data/images/ --yaml /local/workspace/yolov11n.yaml --classes 2 --hw-arch hailo8

参数说明：

hailomz compile是使用hailo的hailo model zoo预训练模型进行编译的命令；--ckpt指定onnx格式模型；--calib-path 校准集，里面放置的是训练图片，如果数据量少的话，数量尽可能在512~1024吧。其他数量的效果不知道怎么样，可以自行尝试；--yaml 是yolov11n的配置文件；--classes 分类数量；--hw-arch 树莓派的版本。

查看文件目录，发现在当前目录下多了一个yolov11n.har文件(har,全称Hailo Archive：是Hailo AI芯片专用的模型存档格式)，还有一个我们后续需要用到的yolov11n.hef文件。

注意：--classes 参数值填写，需要根据训练的时候具体的情况进行设置，否则会报类似下图这样的错误。 遇到过可以使用 --classes 3 对模型进行训练(猜测是训练模型的时候，使用到了3种类型的数据)。

参数修改

在yolov11n.yaml文件中，修改network参数

network:   network_path:   - /local/workspace/yolov11n.onnx  # 使用本地的yolov11n.onnx 文件地址  alls_script: /local/workspace/hailo_model_zoo/hailo_model_zoo/cfg/alls/generic/yolov11n.alls # 此处不使用绝对地址好像也没有问题    # 注释掉此处的url，无需从网上下载onnx文件

其他修改过的文件与参数:

1.修改 hailo_model_zoo/hailo_model_zoo/cfg/postprocess_config/yolov8n_nms_config.json

将"image_dims":[640,640] 改为："image_dims":[320,320]。(为了减少图片对资源的消耗，已经提前将输入图片设置成(320,320)。这个地方大家可以根据具体情况进行修改，或者先跟着我做的实现一遍，对项目流程熟悉之后再做修改)

2.修改 hailo_model_zoo/hailo_model_zoo/cfg/postprocess_config/yolov11n_nms_config.json

核心问题：

在目标检测任务中，画出来的检测框整体往左上角偏，原因出在这里！！！将"image_dims":[640,640] 改为：

"image_dims":[    320,    320]

3.修改 hailo_model_zoo/hailo_model_zoo/cfg/postprocess_config/base/yolo.yaml

2.图像推理

(在树莓派中) 先创建新目录: mkdir yolov11_test 。 然后搭建虚拟环境，在虚拟环境中部署项目。

创建虚拟环境

# 安装 virtualenv 工具sudo apt-get install python3-venv   # (针对Ubuntu/Debian系统)创建hailo_env虚拟环境python3 -m venv hailo_examples# 激活并进入创建的虚拟环境source hailo_examples/bin/activate

安装驱动

查看HailoRT版本： 4.20.0

下载并安装pyHailoRT
先查看python版本(python --version)，我电脑上的python版本为3.11。
到 hailo官网 查找对应hailort版本和python版本的whl文件。找到hailort-4.20.0-cp311-cp311-linux_aarch64.whl。大家要根据自己的python版本下载。对应的是cp3xx：cp311|cp310|cp39。

此处应注意，树莓派是ARM64的哦。

安装hailort驱动

pip install hailort-4.20.0-cp311-cp311-linux_aarch64.whl

结果查看(目录可能不一样，我是进入到下一步才发现有问题的)：

部署Hailo-Application-Code-Examples

(可以从 Hailo-ai网站 查看Hailo-Application-Code-Example项目。)
实现步骤：
1.使用git 克隆项目代码

# 克隆项目git clone https://github.com/hailo-ai/Hailo-Application-Code-Examples.git# cd 到object_detection目录下    cd Hailo-Application-Code-Examples/runtime/hailo-8/python/object_detection

2.下载必要依赖

pip install -r requirements.txt

3.将yolov11n.hef模型文件和想要进行推理的图像，放到当前目录下(推荐下载Xftp 与Xshell配合使用)

4.执行推理脚本

./object_detection.py -n ./yolov11n.hef -i xxx.jpg

参数：

-n：指定hef格式模型-i：指定想要进行目标检测的图像

参数修改：
在Hailo-Application-Code-Examples/runtime/hailo-8/python/common/coco.txt 文件中，是80种分类的名字，按照自己的需求修改。在实现的过程中修改为自己需要的标签名称和数量，示例：cat、dog、car。

好了，到此已经完成了对yolov11n模型的格式转换(onnx->hef)和对图像的推理。希望在到处踩坑的小伙伴尽快走出来，本人经历了多种坑，最终实现了目标检测任务，可能还有很多没有踩过的坑，大家慢慢来吧！