Esportazione Hailo per modelli YOLO Ultralytics

La toolchain di Hailo utilizza file HEF per piattaforme embedded, inclusi Raspberry Pi AI Kit e AI HAT+, telecamere industriali, gateway edge e PC IA.

Questa guida ti accompagna nell'esportazione dei modelli di rilevamento Ultralytics YOLO nel formato HEF (Hailo Executable Format) di Hailo utilizzando l'SDK Hailo Dataflow Compiler (DFC). Il flusso di lavoro parte da un modello YOLO .pt, esporta in ONNX, compila con gli strumenti Hailo e produce un file .hef pronto per gli acceleratori Hailo-8, Hailo-8L e Hailo-15.

Quando utilizzare Hailo HEF

HEF è l'artefatto compilato utilizzato da HailoRT sui dispositivi target Hailo. Segui questa guida solo quando il tuo hardware di deployment richiede specificamente Hailo HEF. Se stai ancora scegliendo l'hardware edge o i target di esportazione, inizia con i più recenti formati di esportazione Ultralytics diretti come Axelera AI o DeepX, che offrono un flusso di lavoro model.export(...) supportato e migliori opzioni di prestazioni per watt rispetto ai vecchi deployment Hailo.

HEF ha un ruolo nel deployment simile a quello di formati specifici per l'hardware come RKNN per le NPU Rockchip, IMX500 per le telecamere AI Raspberry Pi e Qualcomm QNN per le NPU Snapdragon, ma attualmente non viene generato direttamente da Ultralytics.

Questo flusso di lavoro è pertinente quando hai bisogno di:

• Compatibilità Raspberry Pi AI Kit: Hailo-8L viene utilizzato nel Raspberry Pi AI Kit ufficiale e in AI HAT+.
• Post-processing HailoRT: HailoRT può includere la non-maximum suppression di YOLO nella pipeline di inferenza compilata.
• Compilazione INT8: Il DFC di Hailo quantizza il modello con immagini di calibrazione rappresentative per produrre un grafo INT8 per l'hardware Hailo. Scopri di più sulla quantizzazione del modello.

Formato di esportazione Hailo HEF

HEF è un eseguibile specifico per l'hardware generato dal Dataflow Compiler di Hailo. Contiene il grafo del modello quantizzato, l'allocazione di memoria, la pianificazione e il post-processing opzionale configurato per un'architettura Hailo target. A differenza dei formati standard della modalità Esporta di YOLO, che vengono prodotti direttamente da model.export(format=...), la compilazione HEF utilizza attualmente un flusso a due fasi:

1. Esporta YOLO in ONNX con Ultralytics.
2. Utilizza gli strumenti DFC di Hailo per analizzare, ottimizzare, quantizzare e compilare il modello ONNX in HEF.

Il flusso di lavoro completo si espande nella seguente pipeline:

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

1. Esporta in ONNX utilizzando la modalità Esporta di Ultralytics
2. Analizza (Parse) il modello ONNX nel formato intermedio HAR di Hailo
3. Carica uno script di modello (.alls) con direttive di normalizzazione e post-processing
4. Calibra e quantizza utilizzando immagini rappresentative
5. Compila in un file HEF distribuibile

Attività supportate

Questa guida si concentra sui modelli di object detection YOLO di Ultralytics, poiché lo script del modello Hailo e la configurazione NMS sono specifici per la head di rilevamento.

Per i deployment di segmentazione di istanze, segmentazione semantica, posa, OBB e classificazione, confronta altri formati edge nella tabella della modalità Esporta o utilizza una pipeline ONNX generica dove il tuo runtime target supporta l'attività.

Note sulla compatibilità

La compatibilità dell'esportazione Hailo dipende dalla head del modello, dalle dimensioni dell'immagine di input, dal numero di classi, dall'architettura Hailo, dallo script del modello (.alls) e dalla configurazione NMS. I file statici dello Hailo Model Zoo sono riferimenti utili, ma non sono modelli universali. Ad esempio, un JSON NMS creato per un modello YOLO11n a 80 classi COCO non è corretto per un modello personalizzato a 3 classi o per un imgsz fisso diverso.

Installazione

Passaggio 1: Installa Ultralytics

pip install ultralytics

Passaggio 2: Installa l'SDK Hailo DFC

Il DFC di Hailo è necessario per l'analisi, l'ottimizzazione e la compilazione. Scarica la wheel Python dalla Hailo Developer Zone (è richiesta la registrazione gratuita) e installala:

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

Esempio di esportazione HEF YOLO11n

Lo script qui sotto compila un modello di rilevamento YOLO11n da .pt a .hef con una dimensione di input fissa di 640 pixel. Esporta in ONNX utilizzando Ultralytics, quindi compila con Hailo DFC utilizzando COCO128 come piccolo set di dati di calibrazione.

Prima di eseguire lo script, scarica il file di configurazione NMS YOLO11n corrispondente dallo Hailo Model Zoo o crea il tuo JSON NMS Hailo per il modello. Riutilizza questo script come punto di partenza noto per YOLO11n; i modelli personalizzati necessitano di nodi finali corrispondenti, direttive .alls e impostazioni NMS.

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

Il file HEF risultante, come yolo11n.hef, è pronto per essere distribuito su un dispositivo Hailo compatibile. Se stai compilando per Raspberry Pi AI Kit, imposta HW_ARCH = "hailo8l" prima di eseguire il passaggio di compilazione.

Analisi passo dopo passo

Passaggio 1: Esporta in ONNX

Ultralytics esporta il tuo modello addestrato in formato ONNX, che il DFC di Hailo riceve in input. Imposta opset=11 per un'ampia compatibilità DFC.

from ultralytics import YOLO

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

Passaggio 2: Analizza il modello ONNX

La chiamata translate_onnx_model converte il grafo ONNX nella rappresentazione HAR intermedia di Hailo. L'elenco end_node_names indica al DFC dove tagliare il grafo prima della NMS, in modo che Hailo possa collegare il suo post-processing hardware.

from hailo_sdk_client import ClientRunner

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

Passaggio 3: Carica lo script del modello

Lo script del modello (.alls) configura la normalizzazione dell'input, l'attivazione dell'output e il post-processing NMS. L'impostazione meta_arch=yolov8 si applica sia a YOLOv8 che a YOLO11 poiché condividono lo stesso layout della head di rilevamento.

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)

Passaggio 4: Crea il set di dati di calibrazione

La quantizzazione INT8 richiede un set rappresentativo di immagini. Lo script sottostante utilizza COCO128, che Ultralytics scarica automaticamente tramite 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"

Passaggio 5: Ottimizza e quantizza

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

Questo passaggio applica un fine-tuning sensibile alla quantizzazione e un'analisi del rumore dei layer. Una GPU è fortemente raccomandata; senza di essa, questo passaggio può richiedere diverse ore.

Passaggio 6: Compila in HEF

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

Modelli supportati e nodi finali

Per i modelli di rilevamento, end_node_names identifica gli output della head di rilevamento ONNX che Hailo dovrebbe compilare prima di allegare il suo post-processing NMS. Questi nomi variano in base all'architettura e possono cambiare quando il grafo esportato cambia.

YOLO11 e YOLOv8

YOLO11 e YOLOv8 condividono la stessa head di rilevamento disaccoppiata. L'indice del layer differisce di uno tra le due famiglie:

Nodi finali YOLO11 (tutte le dimensioni: 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",
]

Nodi finali YOLOv8 (tutte le dimensioni: 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",
]

Altre architetture

Per altre architetture di rilevamento, esegui prima il passaggio di parsing senza end_node_names, leggi i nodi suggeriti dall'output del log DFC, quindi riesegui con quei nodi:

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

Script .alls predefiniti e file di configurazione NMS per molte varianti YOLO sono disponibili nel Hailo Model Zoo.

Architetture Hardware Supportate

Imposta HW_ARCH nello script affinché corrisponda al tuo dispositivo target prima di compilare.

Esecuzione dell'Inferenza su Hardware Hailo

Una volta ottenuto il file .hef, copialo sul tuo dispositivo alimentato da Hailo ed esegui l'inferenza utilizzando l'API Python HailoRT (pacchetto hailo_platform). A differenza dei passaggi di esportazione DFC, l'inferenza viene eseguita direttamente sul dispositivo edge.

Passaggio 1: Installa HailoRT sul Dispositivo

Sul dispositivo target, installa HailoRT e i binding Python. Per gli utenti di Raspberry Pi AI Kit e AI HAT+, la guida ufficiale al software AI di Raspberry Pi installa HailoRT, il driver del dispositivo e i binding Python con:

sudo apt install dkms
sudo apt install hailo-all

Per i dispositivi Hailo diversi da Raspberry Pi, installa il pacchetto HailoRT che corrisponde al tuo dispositivo, driver e versione SDK dalla Hailo Developer Zone.

I dispositivi AI HAT+ 2 utilizzano un pacchetto Raspberry Pi diverso (hailo-h10-all) e il flusso di lavoro Hailo-10H. Segui la guida al software AI di Raspberry Pi per quella generazione di hardware.

Passaggio 2: Controllo Rapido

Prima di eseguire l'inferenza Python, conferma che il dispositivo Hailo sia riconosciuto:

hailortcli fw-control identify

Dovresti vedere stampati il tipo di dispositivo, la versione del firmware e il numero di serie.

Passaggio 3: Esegui l'Inferenza

Lo script qui sotto esegue il rilevamento di oggetti su una singola immagine utilizzando il file HEF compilato e l'API Python hailo_platform. Gestisce il pre-processing, l'inferenza e il disegno dei riquadri di delimitazione (bounding boxes) dall'output NMS di 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 e AI HAT+

Il Raspberry Pi AI Kit e l'AI HAT+ da 13 TOPS utilizzano Hailo-8L. Per utilizzare uno dei due dispositivi:

1. Imposta HW_ARCH = "hailo8l" prima di compilare il tuo HEF sulla macchina x86.
2. Copia il .hef sul tuo Raspberry Pi.
3. Installa HailoRT seguendo la guida ufficiale al software AI di Raspberry Pi.
4. Esegui lo script di inferenza sopra riportato.

Per l'inferenza basata su fotocamera su Raspberry Pi, gli esempi picamera2 Hailo forniscono script pronti all'uso per il rilevamento dal vivo con il modulo fotocamera. Puoi anche confrontare i percorsi di distribuzione su Raspberry Pi nella guida Coral Edge TPU su Raspberry Pi e nella guida all'integrazione Sony IMX500.

Inferenza Video con TAPPAS

Per pipeline video ad alto throughput, TAPPAS fornisce elementi GStreamer che trasmettono video attraverso il chip Hailo in tempo reale:

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

Consulta la documentazione TAPPAS per le opzioni complete di configurazione della pipeline.

Riepilogo

Questa guida ha coperto il flusso di lavoro completo per esportare i modelli di rilevamento YOLO di Ultralytics nel formato HEF di Hailo:

1. Esporta in ONNX con Ultralytics (model.export(format="onnx")).
2. Analizza (parse) il modello ONNX con Hailo DFC e specifica i nodi finali della head di rilevamento.
3. Configura la normalizzazione e l'NMS tramite uno script di modello.
4. Quantizza con un set di dati di calibrazione (COCO128 via Ultralytics).
5. Compila in un file .hef pronto per Hailo-8, Hailo-8L o Hailo-15.

Per ulteriori dettagli, consulta la Hailo Developer Zone, la documentazione Hailo e il Hailo Model Zoo. Per altri target di esportazione Ultralytics, consulta le guide correlate su ONNX, OpenVINO, TensorRT, NCNN, TFLite Edge TPU, RKNN, Sony IMX500 e Qualcomm QNN. Per confrontare la velocità e l'accuratezza del modello esportato tra i vari formati, utilizza la modalità Benchmark. Per l'elenco completo dei formati e delle opzioni, visita la documentazione della modalità Esportazione e la pagina della guida alle integrazioni.

FAQ

Quali dispositivi Hailo sono supportati?

Il DFC di Hailo supporta Hailo-8 (hailo8), Hailo-8L (hailo8l) e Hailo-15H (hailo15h). Consulta la tabella Architetture Hardware Supportate per il valore HW_ARCH corrispondente.

Quali modelli Ultralytics possono essere esportati?

Questa guida si concentra sui modelli di rilevamento. Consulta Attività Supportate per l'ambito a livello di attività, Note sulla Compatibilità per i limiti di compatibilità del modello e Modelli e Nodi Finali Supportati per esempi di nodi finali di YOLO11 e YOLOv8.

Perché lo script del modello usa meta_arch=yolov8 per YOLO11?

YOLO11 utilizza la stessa architettura della head di rilevamento disaccoppiata di YOLOv8. Il DFC di Hailo utilizza meta_arch=yolov8 per la configurazione NMS per entrambe le famiglie di modelli.

Ho bisogno di una GPU per il passaggio di ottimizzazione?

Una GPU è fortemente raccomandata per il fine-tuning consapevole della quantizzazione in runner.optimize(). Senza una GPU, il processo funziona comunque ma è significativamente più lento (diverse ore rispetto a circa 10-20 minuti con una GPU).

Come trovo i nodi finali corretti per il mio modello?

Esegui runner.translate_onnx_model(...) senza specificare end_node_names, quindi utilizza i nodi della head di rilevamento suggeriti stampati dal DFC. Vedi Altre Architetture per il comando di esempio.

Dove posso trovare l'SDK Hailo DFC e i file di configurazione NMS?

Il wheel Python dell'SDK Hailo DFC è disponibile dalla Hailo Developer Zone, mentre gli script .alls predefiniti e i file di configurazione NMS sono disponibili dal Hailo Model Zoo.