Hailo HEF Modellkonvertierung – Leitfaden

Dieser Leitfaden beschreibt den Entwicklungsworkflow, um ein CV-Modell in eine Hailo Executable File (.hef) für reComputer R Series (CM5 + Hailo-8) oder reComputer R Series (CM5 + Hailo-10H) zu konvertieren.

Eine .hef-Datei ist zielspezifisch. Setzen Sie eine Hailo-8-HEF nicht auf Hailo-10H ein und umgekehrt. Erstellen, validieren, kennzeichnen und veröffentlichen Sie jede Zielplattform als separates Artefakt.

Bevor Sie beginnen

Die Modellkonvertierung unterscheidet sich von der Inferenz zur Laufzeit:

HailoRT führt eine vorhandene HEF auf dem Gerät aus; es konvertiert kein ONNX.
- Der Hailo Dataflow Compiler (DFC) führt Parsing, Optimierung, Quantisierung und die HEF-Kompilierung durch.
- Führen Sie den DFC in der von Hailo bereitgestellten, unterstützten Entwicklungsumgebung aus, nicht auf dem Raspberry Pi (Einsatzgerät).

Bereiten Sie vor der Konvertierung Folgendes vor:

Ein ONNX-Modell mit fester Shape und explizitem Eingabe-Layout/Farbreihenfolge.
Einen repräsentativen Kalibrierbildsatz, der mit den Produktionsdaten übereinstimmt.
Anforderungen an die Nachbearbeitung: Klassenliste, Anker, Schwellwerte, NMS-Modus, Keypoint-Layout, Maskendekodierung und alle hostseitigen Operationen.
Das DFC- und Model Zoo-Release, das die gewünschte Hardware-Zielplattform unterstützt.

Der aktuelle master-Zweig des Hailo Model Zoo zielt auf Hailo-10/15-Geräte ab. Für Hailo-8 oder Hailo-8L verwenden Sie eine kompatible Model Zoo v2.x-Version zusammen mit dem entsprechenden DFC-Release. Kompilieren Sie ein Hailo-8-Modell nicht mit dem master-Zweig.

1. Offizielle Entwicklungsumgebung installieren

Installieren Sie die Hailo Software Suite oder den Dataflow Compiler aus der Hailo Developer Zone und aktivieren Sie anschließend die mitgelieferte Python-Umgebung. Der DFC wird nicht auf dem Raspberry Pi (Einsatzgerät) installiert.

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>

Bestätigen Sie, dass die CLI verfügbar ist:

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

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

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>

Wenn Sie die einzelnen Stufen separat untersuchen müssen, stellt die offizielle CLI auch Folgendes bereit:

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

Der Netzwerkname, der Kalibrierdatensatz, die Vorverarbeitung, die Nachverarbeitung und das Modellskript stammen aus den YAML- und ALLS-Dateien des entsprechenden Model Zoo-Netzwerks. Überprüfen Sie diese, bevor Sie die generierte HEF akzeptieren.

3. Praxisbeispiel: YOLO11n konvertieren

bash

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

Hailos vortrainiertes YOLO11n kompilieren

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

abgeschlossen ist.

Ihr eigenes trainiertes YOLO11n kompilieren

bash

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

Trainingsumgebung aus, nicht in der DFC-Umgebung, es sei denn, die Python-Anforderungen sind kompatibel.

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

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

Kalibrierungsverzeichnis. Wenn beim Training mehr als nur Gewichte und Klassenanzahl geändert wurden – zum Beispiel die Eingabeauflösung, der Erkennungskopf, die Layer-Namen oder das Ausgabe-Layout –, sind die Standard-YAML- und ALLS-Dateien für YOLO11n möglicherweise nicht mehr anwendbar. Aktualisieren und validieren Sie diese Dateien, anstatt den Befehl erzwingen zu wollen.

Kopieren Sie abschließend die HEF auf das Zielgerät und überprüfen Sie die Ausführung:

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>

Die Anwendung muss dieselbe Eingabe-Vorverarbeitung, dieselben Klassenlabels und denselben YOLO11-NMS-/Ausgabe-Kontrakt verwenden, die während der Kompilierung verwendet wurden. Ein erfolgreicher Benchmark allein validiert nicht die Dekodierung der Bounding Boxes.

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.

Fügen Sie Parser-Knoten-Überschreibungen nur dann hinzu, wenn die offizielle Anleitung des Modells oder eine verifizierte Netron-Inspektion sie erfordert:

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.

Für eine völlig neue Architektur, die keine passende Model Zoo-YAML- und ALLS-Konfiguration besitzt, verwenden Sie den Dataflow-Compiler-Workflow aus dem DFC-Benutzerhandbuch. Ein generischer hailomz compile-Befehl kann die korrekten Endknoten, die Vorverarbeitung, die Quantisierung oder die Nachbearbeitung nicht automatisch ermitteln.

5. Konvertierungsworkflow

6. HEF validieren

Kopieren Sie das generierte HEF auf die Hardware mit dem passenden Accelerator und der entsprechenden HailoRT-Version. Identifizieren Sie anschließend das Gerät und führen Sie den offiziellen Benchmark-Befehl aus:

bash

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

Ein erfolgreicher Benchmark belegt, dass das HEF auf dem Gerät ausführbar ist. Er prüft weder die Vorverarbeitung der Anwendung noch die Dekodierung der Ausgabe. Vergleichen Sie daher das End-to-End-Ergebnis mit der Referenzimplementierung des Quellmodells.

7. Release-Checkliste für Hailo-8 und Hailo-10H

Prüfpunkt	Hailo-8	Hailo-10H
HEF-Ziel	Hailo-8	Hailo-10H
Laufzeitumgebung	Passende HailoRT-4.x-Version auf dem Gerät	Passende HailoRT-5.x-Version auf dem Gerät
Container-Mount	Passende `libhailort.so.4.x`	Passende `libhailort.so.5.x`
Validierung	`hailortcli fw-control identify` und Service-Inferenz	`hailortcli fw-control identify` und Service-Inferenz

8. Veröffentlichung und Bereitstellung

Für jedes neue Modellziel:

Fügen Sie das HEF, das Quellmodul, das Dockerfile, Demo-Medien und den getesteten Befehl zum entsprechenden Hailo-CV-Repository hinzu.
Erstellen und testen Sie das GHCR-Image auf der physischen Zielhardware.
Fügen Sie den passenden AI Lab-Modellbereitstellungseintrag und das plattformspezifische Wiki hinzu.
Fügen Sie die Paket-URL zu downloadSources hinzu, damit die Gesamtzahl der Modell-Downloads angezeigt werden kann.

Nachdem das HEF validiert wurde, folgen Sie der separaten Seite Hailo-8 CV Model Deployment oder Hailo-10H CV Model Deployment in diesem Abschnitt für die vollständigen Geräteprüfungen, den Image-Pull, den Docker-Run-Befehl und die Browser-Vorschau.

Offizielle Referenzen: