Guide de conversion de modèle Hailo HEF

Ce guide décrit le flux de développement pour convertir un modèle de vision par ordinateur en un fichier exécutable Hailo (.hef) pour reComputer R Series (CM5 + Hailo-8) ou reComputer R Series (CM5 + Hailo-10H).

Un .hef est spécifique à la cible. Ne déployez pas un HEF Hailo-8 sur Hailo-10H, ni un HEF Hailo-10H sur Hailo-8. Construisez, validez, étiquetez et publiez chaque cible comme un artefact distinct.

Avant de commencer

La conversion de modèle est différente de l'inférence à l'exécution :

• HailoRT exécute un HEF existant sur le périphérique ; il ne convertit pas de modèle ONNX.
  • Le Dataflow Compiler (DFC) de Hailo prend en charge l'analyse, l'optimisation, la quantification et la compilation du HEF.
  • Exécutez le DFC sur l'environnement de développement hôte pris en charge par Hailo, et non sur le périphérique de déploiement Raspberry Pi.

Préparez les éléments suivants avant la conversion :

1. Un modèle ONNX à forme fixe et une disposition d'entrée/ordre de couleurs explicite. 2. Un jeu d'images de calibration représentatif correspondant aux données de production.
2. Les exigences de post-traitement : liste de classes, ancres, seuils, mode NMS, disposition des points clés, décodage de masque et toute opération côté hôte.
3. La version du DFC et du Model Zoo compatible avec la cible matérielle souhaitée.

La branche master actuelle du Model Zoo Hailo cible les périphériques Hailo-10/15. Pour Hailo-8 ou Hailo-8L, utilisez une version compatible du Model Zoo v2.x avec la version correspondante du DFC. N'utilisez pas master pour compiler un modèle Hailo-8.

1. Installer l'environnement de développement officiel

Installez la Hailo Software Suite ou le Dataflow Compiler depuis la Hailo Developer Zone, puis activez l'environnement Python fourni avec cette installation. Le DFC n'est pas installé sur le périphérique de déploiement Raspberry Pi.

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>

Vérifiez que l'interface en ligne de commande est disponible :

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>

Si vous avez besoin d'inspecter les étapes séparément, l'interface en ligne de commande officielle expose également :

them before accepting the generated HEF.

3. Worked Example: Convert YOLO11n

Hailo officially provides the yolov11n Model Zoo configuration. The v2.19.0

Le nom du réseau, le jeu de calibration, le prétraitement, le post-traitement et le script modèle proviennent des fichiers YAML et ALLS du réseau dans le Model Zoo. Examinez-les avant d'accepter le HEF généré.

3. Exemple pratique : Conversion de YOLO11n

Hailo fournit officiellement la configuration Model Zoo yolov11n. La configuration v2.19.0 prend en charge Hailo-8/Hailo-8L, tandis que la

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

Le Model Zoo télécharge le point de contrôle référencé et applique sa

# 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.

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

Exportez d'abord le point de contrôle d'entraînement Ultralytics vers un modèle ONNX à taille fixe de 640 pixels. Exécutez cette étape dans

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

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

standard de YOLO11n peuvent ne plus s'appliquer. Mettez à jour et validez ces fichiers au lieu de forcer la commande à se terminer.

Enfin, copiez le HEF sur le périphérique cible et vérifiez qu'il s'exécute :

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>

4. Compiler un autre point de contrôle ONNX personnalisé pris en charge

Les guides d'entraînement officiels de Hailo utilisent le formulaire Model Zoo suivant lorsqu'un modèle ONNX personnalisé correspond à une définition de

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>

Ajoutez des surcharges de nœuds d'analyse uniquement lorsque le guide officiel du modèle ou une inspection Netron vérifiée les exige :

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

Pour une architecture complètement nouvelle qui n'a pas de configuration YAML et ALLS correspondante dans le Model Zoo, utilisez le flux de travail du Dataflow Compiler décrit dans le guide de l'utilisateur du DFC. Une commande générique hailomz compile ne peut pas déterminer automatiquement les nœuds de sortie, le prétraitement, la quantification ou le post-traitement corrects.

5. Flux de travail de conversion

1. Exporter et valider le ONNX. Figez la taille d'entrée et le prétraitement. Vérifiez le modèle ONNX avec une image de test côté hôte avant de compiler.
2. Choisir la cible matérielle. Créez des espaces de travail de conversion

6. Valider le HEF

Copiez le HEF généré sur le matériel équipé de l’accélérateur correspondant et de la version HailoRT appropriée, puis identifiez le périphérique et exécutez la commande de benchmark officielle :

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

Le succès du benchmark prouve que le HEF peut s’exécuter sur le périphérique. Cette validation ne couvre pas le prétraitement applicatif ni le décodage des sorties ; comparez donc également le résultat de bout en bout avec l’implémentation de référence du modèle source.

7. Liste de contrôle pour les versions Hailo-8 et Hailo-10H

8. Publier et déployer

Pour chaque nouvelle cible de modèle :

1. Ajoutez le HEF, le module source, le Dockerfile, les médias de démonstration et la commande testée au dépôt Hailo CV correspondant.
2. Construisez et testez l’image GHCR sur le matériel cible physique.
3. Ajoutez l’entrée de déploiement du modèle AI Lab correspondante ainsi que le Wiki spécifique à la plateforme.
4. Ajoutez l’URL du package à downloadSources afin que les totaux de téléchargement du modèle puissent être affichés.

Une fois le HEF validé, suivez la page dédiée Déploiement de modèle CV Hailo-8 ou Déploiement de modèle CV Hailo-10H de cette section pour obtenir la procédure complète de vérification du périphérique, de tirage (pull) de l’image, de commande docker run et d’aperçu dans le navigateur.

Références officielles :

• 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