Hailo HEF Model Conversion Guide

This guide describes the development workflow for converting a CV model into a Hailo Executable File (.hef) for reComputer R Series (CM5 + Hailo-8) or reComputer R Series (CM5 + Hailo-10H).

A .hef is target-specific. Do not deploy a Hailo-8 HEF on Hailo-10H, or a Hailo-10H HEF on Hailo-8. Build, validate, label, and publish each target as a separate artifact.

Before You Start

Model conversion is different from runtime inference:

• HailoRT runs an existing HEF on the device; it does not convert ONNX.
• The Hailo Dataflow Compiler (DFC) performs parsing, optimization, quantization, and HEF compilation.
• Run DFC on the supported development-host environment supplied by Hailo, not on the Raspberry Pi deployment device.

Prepare the following before conversion:

1. A fixed-shape ONNX model and an explicit input layout/color order.
2. A representative calibration image set that matches production data.
3. Post-processing requirements: class list, anchors, thresholds, NMS mode, keypoint layout, mask decode, and any host-side operations.
4. The DFC and Model Zoo release that supports the intended hardware target.

Hailo's current Model Zoo master branch targets Hailo-10/15 devices. For Hailo-8 or Hailo-8L, use a compatible Model Zoo v2.x release together with the corresponding DFC release. Do not use master to compile a Hailo-8 model.

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.

Clone the official Model Zoo and select a release compatible with your DFC and target. Replace the tag placeholder with the release documented by the Hailo Software Suite you installed.

Hailo-10H

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

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:

hailomz --version
hailomz info <model_name>

2. Compile an Official Model Zoo Network

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

# 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

If you need to inspect stages separately, the official CLI also exposes:

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 them before accepting the generated HEF.

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 configuration supports Hailo-10H. Use the environment and branch that match your target.

Compile Hailo's pretrained YOLO11n

The Model Zoo downloads the referenced checkpoint and applies its maintained YAML, parser nodes, model script, calibration flow, and NMS configuration:

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

# 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

First export the Ultralytics training checkpoint to a fixed 640-pixel ONNX model. Run this step in the training environment, not in the DFC environment unless their Python requirements are compatible.

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

Validate the exported ONNX before quantization:

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:

# 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 directory. If training changed more than weights and class count—for example, the input resolution, detection head, layer names, or output layout—the stock YOLO11n YAML and ALLS files may no longer apply. Update and validate those files instead of forcing the command to complete.

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

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

The application must use the same input preprocessing, class labels, and YOLO11 NMS/output contract used during compilation. A successful benchmark does not by itself validate bounding-box decoding.

4. Compile Another Supported Custom ONNX Checkpoint

Hailo's official training guides use the following Model Zoo form when a custom ONNX model matches an existing Model Zoo network definition:

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:

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. Validate the HEF

Copy the generated HEF to hardware with the matching accelerator and HailoRT release, then identify the device and run the official benchmark command:

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

Benchmark success proves that the HEF can execute on the device. It does not validate application preprocessing or output decoding, so also compare the end-to-end result with the source-model reference implementation.

7. Hailo-8 and Hailo-10H Release Checklist

8. Publish and Deploy

For every new model target:

1. Add the HEF, source module, Dockerfile, demo media, and tested command to the corresponding Hailo CV repository.
2. Build and test the GHCR image on the physical target hardware.
3. Add the matching AI Lab model deployment entry and platform-specific Wiki.
4. Add the package URL to downloadSources so model download totals can be displayed.

After the HEF is validated, follow the separate Hailo-8 CV Model Deployment or Hailo-10H CV Model Deployment page in this section for the complete device checks, image pull, Docker run command, and browser preview procedure.

Official references:

• Hailo Model Zoo
• Model Zoo Getting Started
• Hailo-8 YOLO11n network configuration
• Hailo-10H YOLO11n network configuration
• Hailo Apps installation guide
• Ultralytics ONNX export guide