Hailo HEF-modelconversiehandleiding

Bereid een ONNX-model, kalibratiedata en een doelgebonden Hailo HEF voor Hailo-8 of Hailo-10H voor.

In deze handleiding wordt de ontwikkelworkflow beschreven voor het omzetten van een CV-model naar een Hailo Executable File (.hef) voor reComputer R Series (CM5 + Hailo-8) of reComputer R Series (CM5 + Hailo-10H).

Een .hef is doelgebonden. Gebruik een Hailo-8 HEF niet op een Hailo-10H, en een Hailo-10H HEF niet op een Hailo-8. Bouw, valideer, label en publiceer elk doel als een apart artefact.

Voordat u begint

Modelconversie is iets anders dan runtime-inferentie:

  • HailoRT voert een bestaande HEF uit op het apparaat; het converteert geen ONNX.
  • De Hailo Dataflow Compiler (DFC) voert parsing, optimalisatie, kwantisering en HEF-compilatie uit.
  • Voer DFC uit op de ondersteunde ontwikkelhost-omgeving die door Hailo wordt geleverd, niet op het Raspberry Pi-implementatieapparaat.

Zorg dat u het volgende voorbereidt voordat u met de conversie begint:

  1. Een ONNX-model met vaste vorm en een expliciete invoerlay-out/kleurvolgorde.
  2. Een representatieve set kalibratieafbeeldingen die overeenkomt met de productiedata.
  3. Vereisten voor nabewerking: klasselijst, ankers, drempelwaarden, NMS-modus, keypoint-indeling, mask-decodering en eventuele bewerkingen aan de hostzijde.
  4. De DFC- en Model Zoo-release die het beoogde hardwareplatform ondersteunt.

De huidige master-branch van Hailo's Model Zoo is gericht op Hailo-10/15-apparaten. Voor Hailo-8 of Hailo-8L gebruikt u een compatibele Model Zoo v2.x-release samen met de bijbehorende DFC-release. Gebruik master niet om een Hailo-8-model te compileren.

1. Installeer de officiële ontwikkelomgeving

Installeer de Hailo Software Suite of Dataflow Compiler uit de Hailo Developer Zone en activeer vervolgens de Python-omgeving die bij die installatie wordt geleverd. De DFC wordt niet geïnstalleerd op het Raspberry Pi-implementatieapparaat.

Clone de officiële Model Zoo en selecteer een release die compatibel is met uw DFC en doelplatform. Vervang de tag-placeholder door de release die is gedocumenteerd in de door u geïnstalleerde Hailo Software Suite.

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 .

Controleer of de CLI beschikbaar is:

bash
hailomz --version
hailomz info <model_name>

2. Compileer een officieel Model Zoo-netwerk

Voor een netwerk dat al door Hailo Model Zoo wordt aangeboden, voert compile de vereiste parseer- en optimalisatiefasen uit en produceert het de 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

Als u de fasen afzonderlijk wilt inspecteren, biedt de officiële CLI ook:

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>

De netwerknaam, kalibratiedataset, voorbewerking, nabewerking en het modelscript komen uit de YAML- en ALLS-bestanden van dat netwerk in de Model Zoo. Bekijk ze voordat u de gegenereerde HEF accepteert.

3. Uitgewerkt voorbeeld: Converteer YOLO11n

Hailo biedt officieel de yolov11n Model Zoo-configuratie aan. De v2.19.0- configuratie ondersteunt Hailo-8/Hailo-8L, terwijl de huidige Hailo-10H Model Zoo- configuratie Hailo-10H ondersteunt. Gebruik de omgeving en branch die bij uw doelplatform passen.

Compileer Hailo's voorgetrainde YOLO11n

De Model Zoo downloadt het gerefereerde checkpoint en past de onderhouden YAML-, parserknooppunten, modelscript, kalibratiestroom en NMS-configuratie toe:

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

De opdracht toont het gegenereerde HEF-pad wanneer de compilatie is voltooid.

Compileer uw eigen getrainde YOLO11n

Exporteer eerst het Ultralytics-trainingscheckpoint naar een vast ONNX-model van 640 pixels. Voer deze stap uit in de trainingsomgeving, niet in de DFC-omgeving, tenzij hun Python-vereisten compatibel zijn.

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

Valideer de geëxporteerde ONNX vóór kwantisering:

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

Activeer vervolgens de overeenkomstige Hailo DFC/Model Zoo-omgeving. Stel het doelplatform en het aantal klassen voor uw getrainde dataset in en compileer met de YOLO11n-netwerk- configuratie van Hailo:

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"

Gebruik representatieve .jpg-, .jpeg- of .png-afbeeldingen in de kalibratie- directory. Als de training meer heeft veranderd dan gewichten en het aantal klassen, bijvoorbeeld de invoerresolutie, de detectiehead, laagnamen of de uitvoerindeling, zijn de standaard YOLO11n YAML- en ALLS-bestanden mogelijk niet langer van toepassing. Werk die bestanden bij en valideer ze in plaats van de opdracht te forceren.

Kopieer ten slotte de HEF naar het doelapparaat en controleer of deze wordt uitgevoerd:

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

De applicatie moet dezelfde invoervoorbewerking, klasselabels en YOLO11 NMS-/uitvoercontract gebruiken die tijdens de compilatie zijn gebruikt. Een geslaagde benchmark valideert op zichzelf niet de decodering van de bounding box.

4. Compileer een ander ondersteund aangepast ONNX-checkpoint

De officiële trainingshandleidingen van Hailo gebruiken het volgende Model Zoo-formulier wanneer een aangepast ONNX-model overeenkomt met een bestaande Model Zoo-netwerkdefinitie:

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>

Voeg alleen parserknooppuntoverschrijvingen toe wanneer de officiële handleiding van het model of een geverifieerde Netron-inspectie dit vereist:

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>

Gebruik voor een volledig nieuwe architectuur waarvoor geen overeenkomende Model Zoo YAML- en ALLS-configuratie bestaat, de Dataflow Compiler-workflow uit de DFC User Guide. Een generieke opdracht hailomz compile kan niet automatisch de juiste eind- knooppunten, voorbewerking, kwantisering of nabewerking bepalen.

5. Conversieworkflow

  1. Exporteer en valideer ONNX. Leg de invoergrootte en voorbewerking vast. Controleer het ONNX-model met een testafbeelding aan de hostzijde voordat u compileert.
  2. Kies het hardwareplatform. Maak afzonderlijke conversiewerkruimten voor Hailo-8 en Hailo-10H. Houd de bron-ONNX en kalibratiedata traceerbaar.
  3. Parseer het netwerk. Gebruik de DFC-parser om de tussenliggende netwerkrepresentatie te produceren en inspecteer alle in- en uitvoertensornamen en -vormen.
  4. Configureer voor- en nabewerking. Gebruik bij voorkeur de overeenkomstige Hailo Model Zoo-netwerkconfiguratie wanneer deze beschikbaar is. Leg elke aangepaste normalisatie, resize, anker-, NMS- en uitvoerdecodeerbeslissing vast in de model- README.
  5. Optimaliseer met kalibratiedata. Voer kwantisering uit met representatieve afbeeldingen. Inspecteer waarschuwingen en nauwkeurigheidsresultaten voordat u compileert.
  6. Compileer de HEF. Compileer afzonderlijk voor het geselecteerde doelplatform en geef artefacten ondubbelzinnige namen, bijvoorbeeld model_hailo8.hef en model_hailo10h.hef.
  7. Valideer op hardware. Voer de HEF uit met de overeenkomende HailoRT-release, vergelijk uitvoertensoren en nagebewerkte resultaten met de hostreferentie en controleer of /dev/hailo0 beschikbaar is.

6. Valideer de HEF

Kopieer de gegenereerde HEF naar hardware met de bijbehorende accelerator en HailoRT‑release, identificeer het apparaat en voer het officiële benchmarkcommando uit:

release, then identify the device and run the official benchmark command:

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

7. Releasechecklist voor Hailo‑8 en Hailo‑10H

ControleHailo‑8Hailo‑10H
HEF‑doelHailo‑8Hailo‑10H
RuntimeKomt overeen met de HailoRT 4.x‑release op het apparaatKomt overeen met de HailoRT 5.x‑release op het apparaat
Container‑mountOvereenkomende libhailort.so.4.xOvereenkomende libhailort.so.5.x
Validatiehailortcli fw-control identify en service‑inferentiehailortcli fw-control identify en service‑inferentie

8. Publiceren en implementeren

Voor elk nieuw modeldoel:

  1. Voeg de HEF, bronmodule, Dockerfile, demomedia en geteste commando’s toe aan de betreffende Hailo CV‑repository.

  2. Bouw en test de GHCR‑image op de fysieke doelhardware.

  3. Voeg de bijbehorende AI Lab‑modelimplementatie‑entry en platformspecifieke wiki toe.

  4. Voeg de pakket‑URL toe aan downloadSources zodat de downloadtotalen van het model kunnen worden weergegeven.

    Nadat de HEF is gevalideerd, volg je de aparte pagina Hailo‑8 CV‑modelimplementatie of Hailo‑10H CV‑modelimplementatie in deze sectie voor de volledige procedure: apparaatcontroles, image pull, Docker‑run‑opdracht en voorbeeldweergave in de browser.

Officiële referenties: