Exportation Hailo pour les modèles YOLO d'Ultralytics

La chaîne d'outils Hailo utilise des fichiers HEF pour des plateformes embarquées, notamment le Raspberry Pi AI Kit et le AI HAT+, les caméras industrielles, les passerelles edge et les PC IA.

Ce guide détaille l'exportation des modèles de détection Ultralytics YOLO vers le format HEF (Hailo Executable Format) de Hailo en utilisant le SDK Hailo Dataflow Compiler (DFC). Le flux de travail commence par un modèle YOLO .pt, exporte vers ONNX, compile avec les outils Hailo et produit un fichier .hef prêt pour les accélérateurs Hailo-8, Hailo-8L et Hailo-15.

Quand utiliser HEF de Hailo

HEF est l'artefact compilé consommé par HailoRT sur les appareils cibles Hailo. Utilise ce guide uniquement si ton matériel de déploiement nécessite spécifiquement HEF de Hailo. Si tu es encore en phase de choix de matériel edge ou de cibles d'exportation, commence par les nouveaux formats d'exportation directs d'Ultralytics tels que Axelera AI ou DeepX, qui proposent un flux model.export(...) pris en charge et de meilleures options de performance par watt que les anciens déploiements Hailo.

Le rôle du HEF lors du déploiement est similaire à celui de formats spécifiques au matériel comme RKNN pour les NPU Rockchip, IMX500 pour les caméras IA Raspberry Pi, et Qualcomm QNN pour les NPU Snapdragon, mais il n'est pas actuellement généré directement par Ultralytics.

Ce flux de travail est pertinent lorsque tu as besoin de :

• Compatibilité Raspberry Pi AI Kit : Hailo-8L est utilisé dans le Raspberry Pi AI Kit officiel et l'AI HAT+.
• Post-traitement HailoRT : HailoRT peut inclure la non-maximum suppression (NMS) YOLO dans le pipeline d'inférence compilé.
• Compilation INT8 : Le DFC de Hailo quantifie le modèle avec des images de calibration représentatives pour produire un graphe INT8 destiné au matériel Hailo. Apprends-en davantage sur la quantification de modèle.

Format d'exportation HEF de Hailo

HEF est un exécutable spécifique au matériel généré par le Dataflow Compiler de Hailo. Il contient le graphe du modèle quantifié, l'allocation mémoire, l'ordonnancement et un post-traitement optionnel configuré pour une architecture Hailo cible. Contrairement aux formats standard du mode Export de YOLO produits directement par model.export(format=...), la compilation HEF utilise actuellement un processus en deux étapes :

1. Exporter YOLO vers ONNX avec Ultralytics.
2. Utiliser les outils DFC de Hailo pour analyser, optimiser, quantifier et compiler le modèle ONNX en HEF.

Le flux de travail complet se divise dans le pipeline suivant :

YOLO (.pt) -> ONNX -> HAR (parse) -> HAR (optimize/quantize) -> HEF (compile)

1. Exporter vers ONNX en utilisant le mode Export d'Ultralytics
2. Analyser le modèle ONNX dans le format intermédiaire HAR de Hailo
3. Charger un script de modèle (.alls) avec des directives de normalisation et de post-traitement
4. Calibrer et quantifier en utilisant des images représentatives
5. Compiler vers un fichier HEF déployable

Tâches prises en charge

Ce guide se concentre sur les modèles de détection d'objets YOLO d'Ultralytics, car le script de modèle Hailo et la configuration NMS sont spécifiques à la tête de détection.

Pour les déploiements de segmentation d'instance, segmentation sémantique, pose, OBB et classification, compare d'autres formats edge dans le tableau du mode Export ou utilise un pipeline ONNX générique là où ton environnement d'exécution cible prend en charge la tâche.

Notes de compatibilité

La compatibilité de l'exportation Hailo dépend de la tête du modèle, de la taille de l'image d'entrée, du nombre de classes, de l'architecture Hailo, du script de modèle (.alls) et de la configuration NMS. Les fichiers statiques du Hailo Model Zoo sont des références utiles, mais ne constituent pas des modèles universels. Par exemple, un JSON de NMS créé pour un modèle YOLO11n COCO à 80 classes n'est pas correct pour un modèle personnalisé à 3 classes ou pour une imgsz fixe différente.

Installation

Étape 1 : Installer Ultralytics

pip install ultralytics

Étape 2 : Installer le SDK Hailo DFC

Le DFC de Hailo est requis pour l'analyse, l'optimisation et la compilation. Télécharge le wheel Python depuis la Hailo Developer Zone (inscription gratuite requise) et installe-le :

pip install /path/to/hailo_sdk_client-*.whl

Exemple d'exportation HEF pour YOLO11n

Le script ci-dessous compile un modèle de détection YOLO11n de .pt vers .hef à une taille d'entrée fixe de 640 pixels. Il exporte vers ONNX en utilisant Ultralytics, puis compile avec Hailo DFC en utilisant COCO128 comme petit ensemble de données de calibration.

Avant d'exécuter le script, télécharge le fichier de configuration NMS YOLO11n correspondant depuis le Hailo Model Zoo ou crée ton propre JSON de NMS Hailo pour le modèle. Réutilise ce script comme point de départ connu pour YOLO11n ; les modèles personnalisés ont besoin de nœuds finaux, de directives .alls et de paramètres NMS correspondants.

import random

import numpy as np
from hailo_sdk_client import ClientRunner
from PIL import Image

from ultralytics import YOLO
from ultralytics.data.utils import check_det_dataset
from ultralytics.utils import DATASETS_DIR

# Configuration
MODEL = "yolo11n"
HW_ARCH = "hailo8"  # hailo8 | hailo8l | hailo15h
IMGSZ = 640
CALIB_IMAGES = 128
NMS_CONFIG = "yolo11n_nms_config.json"  # Download or generate for your exact model.

# YOLO11 detection head end nodes. See "Supported Models and End Nodes" for YOLOv8 and other families.
END_NODES = [
    "/model.23/cv2.0/cv2.0.2/Conv",
    "/model.23/cv3.0/cv3.0.2/Conv",
    "/model.23/cv2.1/cv2.1.2/Conv",
    "/model.23/cv3.1/cv3.1.2/Conv",
    "/model.23/cv2.2/cv2.2.2/Conv",
    "/model.23/cv3.2/cv3.2.2/Conv",
]

# Step 1: Export to ONNX
model = YOLO(f"{MODEL}.pt")
model.export(format="onnx", imgsz=IMGSZ, opset=11)  # creates an ONNX file named after MODEL

# Step 2: Parse ONNX with Hailo DFC
# The DFC prints the detected end nodes after parsing; use them if unsure.
runner = ClientRunner(hw_arch=HW_ARCH)
runner.translate_onnx_model(f"{MODEL}.onnx", end_node_names=END_NODES)

# Step 3: Load model script (normalization + HailoRT NMS)
# The conv layer names are generated by DFC and can change for other model sizes/families.
alls = (
    "normalization1 = normalization([0.0, 0.0, 0.0], [255.0, 255.0, 255.0])\n"
    "change_output_activation(conv54, sigmoid)\n"
    "change_output_activation(conv65, sigmoid)\n"
    "change_output_activation(conv80, sigmoid)\n"
    f'nms_postprocess("{NMS_CONFIG}", meta_arch=yolov8, engine=cpu)\n'
    "allocator_param(width_splitter_defuse=disabled)"
)
runner.load_model_script(alls)

# Step 4: Build calibration dataset (auto-downloads COCO128)
check_det_dataset("coco128.yaml")
calib_dir = DATASETS_DIR / "coco128" / "images" / "train2017"
image_files = list(calib_dir.glob("*.jpg")) + list(calib_dir.glob("*.png"))
if not image_files:
    raise FileNotFoundError(f"No calibration images found in {calib_dir}")

calibset = np.zeros((CALIB_IMAGES, IMGSZ, IMGSZ, 3), dtype=np.float32)
for i in range(CALIB_IMAGES):
    img = Image.open(random.choice(image_files)).convert("RGB").resize((IMGSZ, IMGSZ))
    calibset[i] = np.array(img, dtype=np.float32)

# Step 5: Optimize and quantize
runner.optimize(calibset)
runner.save_har(f"{MODEL}.o.har")  # optional intermediate HAR

# Step 6: Compile to HEF
hef = runner.compile()
with open(f"{MODEL}.hef", "wb") as f:
    f.write(hef)

print(f"Compiled HEF saved to: {MODEL}.hef")

Le fichier HEF résultant, comme yolo11n.hef, est prêt à être déployé sur un appareil Hailo compatible. Si tu compiles pour le Raspberry Pi AI Kit, règle HW_ARCH = "hailo8l" avant d'exécuter l'étape de compilation.

Détail étape par étape

Étape 1 : Exporter vers ONNX

Ultralytics exporte ton modèle entraîné au format ONNX, que le DFC de Hailo ingère en entrée. Règle opset=11 pour une large compatibilité avec le DFC.

from ultralytics import YOLO

MODEL = "yolo11n"
model = YOLO(f"{MODEL}.pt")
model.export(format="onnx", imgsz=640, opset=11)

Étape 2 : Analyser le modèle ONNX

L'appel translate_onnx_model convertit le graphe ONNX dans la représentation intermédiaire HAR de Hailo. La liste end_node_names indique au DFC où couper le graphe avant la NMS afin que Hailo puisse attacher son propre post-traitement matériel.

from hailo_sdk_client import ClientRunner

runner = ClientRunner(hw_arch="hailo8")
runner.translate_onnx_model(f"{MODEL}.onnx", end_node_names=END_NODES)

Étape 3 : Charger le script de modèle

Le script de modèle (.alls) configure la normalisation d'entrée, l'activation de sortie et le post-traitement NMS. Le paramètre meta_arch=yolov8 s'applique à la fois à YOLOv8 et YOLO11 car ils partagent la même disposition de tête de détection.

MODEL = "yolo11n"
NMS_CONFIG = "yolo11n_nms_config.json"
alls = (
    "normalization1 = normalization([0.0, 0.0, 0.0], [255.0, 255.0, 255.0])\n"
    "change_output_activation(conv54, sigmoid)\n"
    "change_output_activation(conv65, sigmoid)\n"
    "change_output_activation(conv80, sigmoid)\n"
    f'nms_postprocess("{NMS_CONFIG}", meta_arch=yolov8, engine=cpu)\n'
    "allocator_param(width_splitter_defuse=disabled)"
)
runner.load_model_script(alls)

Étape 4 : Construire l'ensemble de données de calibration

La quantification INT8 nécessite un ensemble représentatif d'images. Le script ci-dessous utilise COCO128, qu'Ultralytics télécharge automatiquement via check_det_dataset :

from ultralytics.data.utils import check_det_dataset
from ultralytics.utils import DATASETS_DIR

check_det_dataset("coco128.yaml")  # downloads to DATASETS_DIR if not present
calib_dir = DATASETS_DIR / "coco128" / "images" / "train2017"

Étape 5 : Optimiser et quantifier

runner.optimize(calibset)
runner.save_har(f"{MODEL}.o.har")  # optional intermediate checkpoint

Cette étape applique un réglage fin sensible à la quantification et une analyse du bruit des couches. Un GPU est fortement recommandé ; sans cela, cette étape peut prendre plusieurs heures.

Étape 6 : Compiler vers HEF

hef = runner.compile()
with open(f"{MODEL}.hef", "wb") as f:
    f.write(hef)

Modèles pris en charge et nœuds finaux

Pour les modèles de détection, end_node_names identifie les sorties de tête de détection ONNX que Hailo doit compiler avant d'attacher son post-traitement NMS. Ces noms varient selon l'architecture et peuvent changer lorsque le graphe exporté change.

YOLO11 et YOLOv8

YOLO11 et YOLOv8 partagent la même tête de détection découplée. L'index de couche diffère d'un entre les deux familles :

Nœuds finaux YOLO11 (toutes tailles : n, s, m, l, x) :

END_NODES = [
    "/model.23/cv2.0/cv2.0.2/Conv",
    "/model.23/cv3.0/cv3.0.2/Conv",
    "/model.23/cv2.1/cv2.1.2/Conv",
    "/model.23/cv3.1/cv3.1.2/Conv",
    "/model.23/cv2.2/cv2.2.2/Conv",
    "/model.23/cv3.2/cv3.2.2/Conv",
]

Nœuds finaux YOLOv8 (toutes tailles : n, s, m, l, x) :

END_NODES = [
    "/model.22/cv2.0/cv2.0.2/Conv",
    "/model.22/cv3.0/cv3.0.2/Conv",
    "/model.22/cv2.1/cv2.1.2/Conv",
    "/model.22/cv3.1/cv3.1.2/Conv",
    "/model.22/cv2.2/cv2.2.2/Conv",
    "/model.22/cv3.2/cv3.2.2/Conv",
]

Autres architectures

Pour d'autres architectures de détection, exécute d'abord l'étape d'analyse sans end_node_names, lis les nœuds suggérés dans la sortie du journal DFC, puis relance avec ces nœuds :

# First pass: let the DFC suggest end nodes
runner = ClientRunner(hw_arch=HW_ARCH)
runner.translate_onnx_model(f"{MODEL}.onnx")
# Check the printed log for: "[info] In order to use HailoRT post-processing..."

Des scripts .alls prédéfinis et des fichiers de configuration NMS pour de nombreuses variantes de YOLO sont disponibles dans le Hailo Model Zoo.

Architectures matérielles prises en charge

Défini HW_ARCH dans le script pour qu'il corresponde à ton appareil cible avant la compilation.

Exécution de l'inférence sur le matériel Hailo

Une fois que tu as le fichier .hef, copie-le sur ton appareil équipé de Hailo et exécute l'inférence en utilisant l'API Python HailoRT (package hailo_platform). Contrairement aux étapes d'exportation DFC, l'inférence s'exécute directement sur l'appareil en périphérie (edge).

Étape 1 : Installer HailoRT sur l'appareil

Sur l'appareil cible, installe HailoRT et les liaisons Python. Pour les utilisateurs de Raspberry Pi AI Kit et AI HAT+, le guide officiel du logiciel Raspberry Pi AI installe HailoRT, le pilote de périphérique et les liaisons Python avec :

sudo apt install dkms
sudo apt install hailo-all

Pour les appareils Hailo autres que Raspberry Pi, installe le package HailoRT qui correspond à ton appareil, ton pilote et ta version du SDK depuis la Hailo Developer Zone.

Les appareils AI HAT+ 2 utilisent un package Raspberry Pi différent (hailo-h10-all) et un flux de travail Hailo-10H. Suis le guide du logiciel Raspberry Pi AI pour cette génération de matériel.

Étape 2 : Vérification rapide

Avant d'exécuter l'inférence Python, confirme que l'appareil Hailo est reconnu :

hailortcli fw-control identify

Tu devrais voir le type d'appareil, la version du micrologiciel et le numéro de série imprimés.

Étape 3 : Exécuter l'inférence

Le script ci-dessous exécute la détection d'objets sur une seule image en utilisant le fichier HEF compilé et l'API Python hailo_platform. Il gère le prétraitement, l'inférence et le dessin des boîtes englobantes à partir de la sortie NMS de HailoRT.

import numpy as np
from hailo_platform import (
    HEF,
    ConfigureParams,
    FormatType,
    HailoStreamInterface,
    InferVStreams,
    InputVStreamParams,
    OutputVStreamParams,
    VDevice,
)
from PIL import Image, ImageDraw

# Configuration
MODEL = "yolo11n"
HEF_PATH = f"{MODEL}.hef"  # path to your compiled HEF file
SOURCE = "bus.jpg"  # image path
IMGSZ = 640
CONF = 0.25

COCO_NAMES = [
    "person",
    "bicycle",
    "car",
    "motorcycle",
    "airplane",
    "bus",
    "train",
    "truck",
    "boat",
    "traffic light",
    "fire hydrant",
    "stop sign",
    "parking meter",
    "bench",
    "bird",
    "cat",
    "dog",
    "horse",
    "sheep",
    "cow",
    "elephant",
    "bear",
    "zebra",
    "giraffe",
    "backpack",
    "umbrella",
    "handbag",
    "tie",
    "suitcase",
    "frisbee",
    "skis",
    "snowboard",
    "sports ball",
    "kite",
    "baseball bat",
    "baseball glove",
    "skateboard",
    "surfboard",
    "tennis racket",
    "bottle",
    "wine glass",
    "cup",
    "fork",
    "knife",
    "spoon",
    "bowl",
    "banana",
    "apple",
    "sandwich",
    "orange",
    "broccoli",
    "carrot",
    "hot dog",
    "pizza",
    "donut",
    "cake",
    "chair",
    "couch",
    "potted plant",
    "bed",
    "dining table",
    "toilet",
    "tv",
    "laptop",
    "mouse",
    "remote",
    "keyboard",
    "cell phone",
    "microwave",
    "oven",
    "toaster",
    "sink",
    "refrigerator",
    "book",
    "clock",
    "vase",
    "scissors",
    "teddy bear",
    "hair drier",
    "toothbrush",
]

# Load HEF and connect to device
hef = HEF(HEF_PATH)
params = VDevice.create_params()
target = VDevice(params)

configure_params = ConfigureParams.create_from_hef(hef, interface=HailoStreamInterface.PCIe)
network_groups = target.configure(hef, configure_params)
network_group = network_groups[0]
network_group_params = network_group.create_params()

# Setup I/O virtual streams
input_vstreams_params = InputVStreamParams.make(network_group, quantized=False, format_type=FormatType.FLOAT32)
output_vstreams_params = OutputVStreamParams.make(network_group, quantized=False, format_type=FormatType.FLOAT32)

# Preprocess
orig = Image.open(SOURCE).convert("RGB")
ow, oh = orig.size
resized = orig.resize((IMGSZ, IMGSZ))
input_data = np.expand_dims(np.array(resized, dtype=np.float32), axis=0)  # (1,640,640,3)
input_name = hef.get_input_vstream_infos()[0].name

# Inference
with InferVStreams(network_group, input_vstreams_params, output_vstreams_params) as pipeline:
    with network_group.activate(network_group_params):
        pipeline.send({input_name: input_data})
        raw = pipeline.recv()

# Parse HailoRT NMS output and draw results
# When compiled with nms_postprocess the HEF outputs detections grouped by
# class: shape (batch, num_classes, max_dets, 5) where 5 = [y1,x1,y2,x2,score]
draw = ImageDraw.Draw(orig)
output_key = next(iter(raw.keys()))
batch_dets = raw[output_key][0]  # shape: (num_classes, max_dets, 5)

for cls_idx, cls_dets in enumerate(batch_dets):
    for det in cls_dets:
        score = float(det[4])
        if score < CONF:
            continue
        y1, x1, y2, x2 = det[:4]
        # Scale from model coords (0-640) back to original image size
        x1 = int(x1 * ow / IMGSZ)
        y1 = int(y1 * oh / IMGSZ)
        x2 = int(x2 * ow / IMGSZ)
        y2 = int(y2 * oh / IMGSZ)
        label = f"{COCO_NAMES[cls_idx]} {score:.2f}"
        draw.rectangle([x1, y1, x2, y2], outline="red", width=2)
        draw.text((x1 + 2, y1 + 2), label, fill="red")

orig.save("output.jpg")
print("Saved output.jpg")

Raspberry Pi AI Kit et AI HAT+

Le Raspberry Pi AI Kit et l'AI HAT+ de 13 TOPS utilisent Hailo-8L. Pour utiliser l'un ou l'autre appareil :

1. Défini HW_ARCH = "hailo8l" avant de compiler ton HEF sur la machine x86.
2. Copie le .hef sur ton Raspberry Pi.
3. Installe HailoRT en suivant le guide officiel du logiciel Raspberry Pi AI.
4. Exécute le script d'inférence ci-dessus.

Pour l'inférence basée sur une caméra sur Raspberry Pi, les exemples Hailo de picamera2 fournissent des scripts prêts à l'emploi pour la détection en direct avec le module caméra. Tu peux également comparer les chemins de déploiement Raspberry Pi dans le guide Coral Edge TPU sur Raspberry Pi et le guide d'intégration Sony IMX500.

Inférence vidéo avec TAPPAS

Pour les pipelines vidéo à haut débit, TAPPAS fournit des éléments GStreamer qui diffusent la vidéo à travers la puce Hailo en temps réel :

MODEL=yolo11n
gst-launch-1.0 filesrc location=video.mp4 ! decodebin ! \
  hailonet hef-path=${MODEL}.hef ! \
  hailofilter function-name=yolov8 ! \
  hailooverlay ! autovideosink

Consulte la documentation TAPPAS pour toutes les options de configuration du pipeline.

Résumé

Ce guide a couvert le flux de travail complet pour exporter les modèles de détection Ultralytics YOLO au format Hailo HEF :

1. Exporter vers ONNX avec Ultralytics (model.export(format="onnx")).
2. Analyser le modèle ONNX avec le DFC de Hailo et spécifier les nœuds finaux de la tête de détection.
3. Configurer la normalisation et NMS via un script de modèle.
4. Quantifier avec un ensemble de données de calibration (COCO128 via Ultralytics).
5. Compiler en un fichier .hef prêt pour Hailo-8, Hailo-8L ou Hailo-15.

Pour plus de détails, consulte la Hailo Developer Zone, la documentation Hailo et le Hailo Model Zoo. Pour d'autres cibles d'exportation Ultralytics, consulte les guides liés ONNX, OpenVINO, TensorRT, NCNN, TFLite Edge TPU, RKNN, Sony IMX500 et Qualcomm QNN. Pour comparer la vitesse et la précision des modèles exportés selon les formats, utilise le mode Benchmark. Pour la liste complète des formats et options, visite la documentation du mode Export et la page du guide d'intégrations.

FAQ

Quels appareils Hailo sont pris en charge ?

Le DFC de Hailo prend en charge Hailo-8 (hailo8), Hailo-8L (hailo8l) et Hailo-15H (hailo15h). Consulte le tableau Architectures matérielles prises en charge pour la valeur HW_ARCH correspondante.

Quels modèles Ultralytics peuvent être exportés ?

Ce guide se concentre sur les modèles de détection. Consulte Tâches prises en charge pour la portée au niveau des tâches, Notes de compatibilité pour les limites de compatibilité des modèles, et Modèles et nœuds finaux pris en charge pour des exemples de nœuds finaux YOLO11 et YOLOv8.

Pourquoi le script de modèle utilise-t-il meta_arch=yolov8 pour YOLO11 ?

YOLO11 utilise la même architecture de tête de détection découplée que YOLOv8. Le DFC de Hailo utilise meta_arch=yolov8 pour la configuration NMS pour les deux familles de modèles.

Ai-je besoin d'un GPU pour l'étape d'optimisation ?

Un GPU est fortement recommandé pour le réglage fin conscient de la quantification dans runner.optimize(). Sans GPU, le processus fonctionne mais est nettement plus lent (plusieurs heures contre environ 10-20 minutes avec un GPU).

Comment trouver les bons nœuds finaux pour mon modèle ?

Exécute runner.translate_onnx_model(...) sans spécifier end_node_names, puis utilise les nœuds de tête de détection suggérés imprimés par le DFC. Consulte Autres architectures pour l'exemple de commande.

Où puis-je obtenir le SDK DFC de Hailo et les fichiers de configuration NMS ?

Le fichier wheel Python du SDK DFC de Hailo est disponible sur la Hailo Developer Zone, tandis que les scripts .alls prédéfinis et les fichiers de configuration NMS sont disponibles sur le Hailo Model Zoo.