Hailo HEF 模型转换指南

准备 ONNX 模型、校准数据以及针对 Hailo-8 或 Hailo-10H 的目标 HEF。

本指南介绍了将 CV 模型转换为 reComputer R Series (CM5 + Hailo-8) 或 reComputer R Series (CM5 + Hailo-10H) 所需的 Hailo 可执行文件（.hef）的开发流程。

.hef 文件与目标硬件绑定。请勿将 Hailo-8 的 HEF 部署到 Hailo-10H，或将 Hailo-10H 的 HEF 部署到 Hailo-8。应为每个目标单独构建、验证、标记并发布对应的制品。

开始之前

模型转换与运行时推理不同：

  • HailoRT 在设备上运行已有的 HEF，不进行 ONNX 转换。
  • Hailo Dataflow Compiler (DFC) 负责解析、优化、量化和 HEF 编译。
  • 请在 Hailo 提供的受支持开发主机环境中运行 DFC，而非在 Raspberry Pi 部署设备上运行。

转换前请准备以下内容：

  1. 固定尺寸的 ONNX 模型，以及明确的输入布局/颜色顺序。
  2. 与实际生产数据匹配的代表性校准图像集。
  3. 后处理需求：类别列表、锚框、阈值、NMS 模式、关键点布局、掩码解码以及任何主机端操作。
  4. 支持目标硬件的 DFC 和 Model Zoo 版本。

Hailo 当前 Model Zoo 的 master 分支面向 Hailo-10/15 设备。对于 Hailo-8 或 Hailo-8L，请使用兼容的 Model Zoo v2.x 版本以及对应的 DFC 版本。请勿使用 master 分支编译 Hailo-8 模型。

1. 安装官方开发环境

从 Hailo Developer Zone 安装 Hailo Software Suite 或 Dataflow Compiler，然后激活安装包提供的 Python 环境。DFC 不会安装在 Raspberry Pi 部署设备上。

克隆官方 Model Zoo，并选择与您的 DFC 和目标硬件兼容的版本。请根据您安装的 Hailo Software Suite 文档，将标签占位符替换为对应的版本。

Hailo-10H

1. Install the Official Development Environment

Install the Hailo Software Suite or Dataflow Compiler from the Hailo Developer Zone, then activate the Python environment supplied with that installation. The DFC is not installed on the Raspberry Pi deployment device.

Hailo-8

Hailo-10H

bash
git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
git checkout <compatible-hailo10h-release>
pip install -e .

Hailo-8

bash
git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
git checkout <compatible-v2.x-release>
pip install -e .

Confirm that the CLI is available:

bash
hailomz --version
hailomz info <model_name>

如果需单独检查各阶段，官方 CLI 还提供了以下命令：

For a network already provided by Hailo Model Zoo, compile runs the required parse and optimization stages and produces the HEF:

bash
# Hailo-8: run this from a compatible Model Zoo v2.x environment
hailomz compile <model_name> --hw-arch hailo8

# Hailo-10H: run this from a compatible Hailo-10H environment
hailomz compile <model_name> --hw-arch hailo10h

Hailo 官方提供了 yolov11n 的 Model Zoo 配置。v2.19.0 配置支持 Hailo-8/Hailo-8L，而当前的 Hailo-10H Model Zoo 配置支持 Hailo-10H。请使用与您的目标硬件匹配的环境和分支。

编译 Hailo 预训练的 YOLO11n

bash
hailomz parse <model_name> --hw-arch <hailo8-or-hailo10h>
hailomz optimize <model_name> --hw-arch <hailo8-or-hailo10h>
hailomz compile <model_name> --hw-arch <hailo8-or-hailo10h>

The network name, calibration dataset, preprocessing, post-processing, and model script come from that network's Model Zoo YAML and ALLS files. Review

3. Worked Example: Convert YOLO11n

Hailo officially provides the yolov11n Model Zoo configuration. The v2.19.0 configuration supports Hailo-8/Hailo-8L, while the current Hailo-10H Model Zoo

编译完成后，命令会输出生成的 HEF 路径。

编译您自己训练的 YOLO11n

首先将 Ultralytics 训练检查点导出为固定 640 像素的 ONNX 模型。请在与 DFC 环境单独的、或 Python 依赖兼容的训练环境中执行此步骤。

bash
# In a Hailo-8-compatible Model Zoo v2.x environment
hailomz info yolov11n
hailomz compile yolov11n --hw-arch hailo8
bash
# In a Hailo-10H-compatible Model Zoo environment
hailomz info yolov11n
hailomz compile yolov11n --hw-arch hailo10h

The command prints the generated HEF path when compilation completes.

Compile your own trained YOLO11n

model. Run this step in the training environment, not in the DFC environment unless their Python requirements are compatible.

bash
pip install ultralytics
yolo export model=/path/to/best.pt format=onnx imgsz=640

校准目录中请使用具有代表性的 .jpg、.jpeg 或 .png 图像。如果训练改动的不仅仅是权重和类别数，例如输入分辨率、检测头、层名称或输出布局发生了变化，则原始的 YOLO11n YAML 和 ALLS 文件可能不再适用。请更新并验证这些文件，而不是强行运行命令。

bash
yolo predict model=/path/to/best.onnx source=/path/to/test.jpg

Then activate the matching Hailo DFC/Model Zoo environment. Set the target and class count for your trained dataset and compile using Hailo's YOLO11n network configuration:

bash
# Use hailo8 in a compatible v2.x environment, or hailo10h in its matching environment.
TARGET_ARCH=hailo10h
NUM_CLASSES=3

hailomz compile \
  --ckpt /path/to/best.onnx \
  --calib-path /path/to/calibration/images \
  --yaml hailo_model_zoo/cfg/networks/yolov11n.yaml \
  --classes "$NUM_CLASSES" \
  --hw-arch "$TARGET_ARCH"

Use representative .jpg, .jpeg, or .png images in the calibration

仅当模型官方指南或经过验证的 Netron 检查需要时，才添加解析器节点覆盖：

files instead of forcing the command to complete.

Finally, copy the HEF to the target device and verify that it executes:

bash
scp /path/to/yolov11n.hef seeed@<BOARD_IP>:~/
ssh seeed@<BOARD_IP>
hailortcli fw-control identify
hailortcli benchmark ~/yolov11n.hef

对于全新的架构，即没有匹配的 Model Zoo YAML 和 ALLS 配置时，请使用 DFC 用户指南中的 Dataflow Compiler 工作流。通用的 hailomz compile 命令无法自动确定正确的端节点、预处理、量化或后处理。

5. 转换工作流

  1. 导出并验证 ONNX。 固定输入尺寸和预处理。编译前使用主机端测试图像检查 ONNX 模型。
  2. 选择目标硬件。 为 Hailo-8 和 Hailo-10H 创建独立的转换工作区。保持源 ONNX 和校准数据的可追溯性。
  3. 解析网络。 使用 DFC 解析器生成中间网络表示，并检查所有输入/输出张量的名称和形状。
  4. 配置预处理和后处理。 优先使用对应的 Hailo Model Zoo 网络配置（如果可用）。在模型 README 中记录所有自定义的归一化、缩放、锚框、NMS 和输出解码决策。
  5. 使用校准数据优化。 使用代表性图像运行量化。编译前检查警告和精度结果。
  6. 编译 HEF。 为所选目标分别编译，然后明确命名制品，例如 model_hailo8.hef 和 model_hailo10h.hef。
bash
hailomz compile \
  --ckpt /path/to/model.onnx \
  --calib-path /path/to/calibration/images \
  --yaml /path/to/hailo_model_zoo/cfg/networks/<network>.yaml \
  --hw-arch <hailo8-or-hailo10h>

Only add parser node overrides when the model's official guide or a verified Netron inspection requires them:

bash
hailomz compile \
  --ckpt /path/to/model.onnx \
  --calib-path /path/to/calibration/images \
  --yaml /path/to/<network>.yaml \
  --start-node-names <input_node> \
  --end-node-names <output_node_1> <output_node_2> \
  --hw-arch <hailo8-or-hailo10h>

For a completely new architecture that has no matching Model Zoo YAML and ALLS configuration, use the Dataflow Compiler workflow from the DFC User Guide. A generic hailomz compile command cannot determine the correct end nodes, preprocessing, quantization, or post-processing automatically.

5. Conversion Workflow

  1. Export and validate ONNX. Freeze input size and preprocessing. Check the ONNX model with a host-side test image before compiling.
  2. Choose the hardware target. Create distinct conversion workspaces for Hailo-8 and Hailo-10H. Keep the source ONNX and calibration data traceable.
  3. Parse the network. Use the DFC parser to produce the intermediate network representation and inspect all input/output tensor names and shapes.
  4. Configure preprocessing and post-processing. Prefer the corresponding Hailo Model Zoo network configuration when available. Record every custom normalization, resize, anchor, NMS, and output-decode decision in the model README.
  5. Optimize with calibration data. Run quantization using representative images. Inspect warnings and accuracy results before compiling.
  6. Compile the HEF. Compile separately for the selected target, then name artifacts unambiguously, for example model_hailo8.hef and model_hailo10h.hef.
  7. Validate on hardware. Run the HEF with the matching HailoRT release, compare output tensors and post-processed results with the host reference, and verify /dev/hailo0 is available.

6. 验证 HEF

将生成的 HEF 复制到搭载匹配加速器及对应 HailoRT 版本的硬件上， 然后识别设备并运行官方基准测试命令：

bash
hailortcli fw-control identify
hailortcli benchmark /path/to/model.hef

基准测试成功表明该 HEF 可在设备上运行。但这并不验证应用的预处理或 输出解码，因此还需将端到端结果与源模型参考实现进行对比。

7. Hailo-8 与 Hailo-10H 发布检查清单

检查项Hailo-8Hailo-10H
HEF 目标Hailo-8Hailo-10H
运行时匹配设备上的 HailoRT 4.x 版本匹配设备上的 HailoRT 5.x 版本
容器挂载匹配 libhailort.so.4.x匹配 libhailort.so.5.x
验证hailortcli fw-control identify 与服务推理hailortcli fw-control identify 与服务推理

8. 发布与部署

针对每个新模型目标：

  1. 将 HEF、源模块、Dockerfile、演示媒体以及经过测试的命令添加到 对应的 Hailo CV 仓库。
  2. 在物理目标硬件上构建并测试 GHCR 镜像。
  3. 添加对应的 AI Lab 模型部署条目以及平台专属 Wiki。
  4. 将软件包 URL 添加到 downloadSources，以便显示模型下载总量。

HEF 验证通过后，请参考本节中独立的 Hailo-8 CV Model Deployment 或 Hailo-10H CV Model Deployment 页面，了解完整的设备检查、 镜像拉取、Docker 运行命令及浏览器预览流程。

官方参考资料：