Esportazione Hailo per modelli Ultralytics YOLO#

Gli acceleratori Hailo AI eseguono modelli compilati in formato Hailo Executable Format (HEF) su dispositivi edge come il Raspberry Pi AI Kit e l'AI HAT+. Ultralytics esporta i modelli YOLO di rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, posa e OBB direttamente in HEF con il Hailo Dataflow Compiler (DFC).

Il deployment su Hailo è progettato per la computer vision all'edge: telecamere, robot, sistemi industriali, gateway e altri dispositivi che necessitano di un rilevamento di oggetti in locale senza inviare ogni frame al cloud. Un HEF compilato contiene la rete quantizzata, l'allocazione hardware, la pianificazione e l'eventuale post-elaborazione HailoRT necessaria per l'acceleratore selezionato.

Perché effettuare il deployment di Ultralytics YOLO su Hailo?#

Combinare Ultralytics YOLO con una neural processing unit (NPU) Hailo fornisce un percorso pratico dall'addestramento del modello all'inferenza AI edge a basso consumo. I casi d'uso comuni includono:

• Telecamere intelligenti e video analisi: esegui il rilevamento di oggetti in tempo reale vicino alla telecamera per applicazioni di sicurezza, vendita al dettaglio, traffico e rilevamento occupazione.
• Robotica e sistemi autonomi: rileva persone, veicoli, pacchi, strumenti o ostacoli senza dipendere da una connessione cloud continua.
• Computer vision industriale: esegui il deployment di modelli YOLO personalizzati per ispezione, conteggio, monitoraggio della sicurezza e controllo qualità.
• Progetti Raspberry Pi AI: aggiungi l'inferenza di visione accelerata ai sistemi Raspberry Pi utilizzando l'AI Kit o l'AI HAT+.
• Edge gateway e PC AI: elabora flussi video o di sensori multipli localmente riducendo i requisiti di larghezza di banda e di calcolo cloud.

L'inferenza locale può migliorare la privacy e il tempo di risposta poiché le immagini rimangono sul dispositivo di deployment. Il throughput effettivo, la latenza e il consumo energetico dipendono dalla dimensione del modello YOLO, dalla risoluzione dell'input, dall'architettura Hailo, dal sistema host e dalla pipeline dell'applicazione.

Come funziona l'esportazione Hailo#

Ultralytics gestisce l'intero flusso di lavoro di esportazione dietro format="hailo":

YOLO (.pt) -> ONNX -> Hailo parse -> INT8 optimization -> HEF compile

L'esportatore esegue automaticamente queste fasi:

1. Esporta un grafo ONNX statico con impostazioni compatibili con il compilatore.
2. Seleziona gli output della head per l'architettura del modello.
3. Genera direttive di normalizzazione, attivazione e post-elaborazione.
4. Crea un flusso di calibrazione rappresentativo e quantizza il modello in INT8.
5. Compila il grafo ottimizzato per l'acceleratore Hailo selezionato.
6. Salva l'HEF con i metadati Ultralytics e rimuove il file ONNX intermedio.

I modelli di rilevamento YOLOv8 e YOLO11 utilizzano HailoRT YOLO NMS nella pipeline compilata. I modelli di rilevamento YOLO26 utilizzano i loro output one-to-one senza NMS, quindi l'esportatore seleziona automaticamente un output e un percorso di quantizzazione differenti. La segmentazione, la posa e l'OBB di YOLOv8/YOLO11 compilano i tensori grezzi della testa, che Ultralytics decodifica durante l'inferenza, e la classificazione di YOLOv8/YOLO11/YOLO26 esegue il softmax su chip in modo che l'HEF restituisca direttamente le probabilità delle classi. Per la segmentazione semantica di YOLO26, l'esportatore segue l'acceleratore: Hailo-8/8L (DFC v3.x) restituiscono i logit del classificatore per l'upsampling e la riduzione sull'host, mentre Hailo-10/15 (DFC v5.x) compilano teste ArgMax multi-classe su chip e restituiscono una mappa di classe compatta. Le teste a classe singola utilizzano il percorso dei logit dell'host su ogni target perché richiedono una soglia anziché ArgMax. I modelli di profondità YOLO26 compilano la convoluzione densa dei logit in a16 e ricostruiscono la mappa di profondità metrica sull'host (clamp/exp e calibrazione log-affine appresa che seguono la testa), in modo che il quantizzatore mantenga il suo intervallo più ampio sul logit grezzo. Gli utenti non devono trovare nodi finali ONNX, scrivere uno script del modello Hailo (.alls) o creare manualmente un file JSON NMS.

Installazione#

Installa Ultralytics e scarica il wheel DFC per il tuo hardware di destinazione dalla Hailo Developer Zone (è richiesta la registrazione gratuita):

pip install ultralytics
pip install /path/to/hailo_dataflow_compiler-*.whl

Hailo-8 e Hailo-8L utilizzano DFC v3.x. Hailo-10 e Hailo-15 utilizzano DFC v5.x. Installa la generazione del compilatore che corrisponde all'acceleratore di destinazione.

Esporta un modello HEF Hailo#

Usa format="hailo" e seleziona l'acceleratore di destinazione con name:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")
output = model.export(format="hailo", name="hailo8l")
print(output)  # yolo11n_hailo_model/

Il comando CLI equivalente è:

yolo export model=yolo11n.pt format=hailo name=hailo8l

L'esportazione su Hailo è esclusivamente in INT8. Ultralytics scarica automaticamente un dataset di calibrazione specifico per l'attività quando data non viene fornito. Per i modelli personalizzati, usa immagini di addestramento o validazione rappresentative:

model.export(format="hailo", name="hailo8l", data="path/to/dataset.yaml")

La compilazione utilizza una forma di input fissa. Imposta imgsz sulla risoluzione utilizzata sul dispositivo:

model.export(format="hailo", name="hailo8l", imgsz=640)

Modelli e hardware supportati#

L'ecosistema Hailo copre un'ampia gamma di carichi di lavoro di visione artificiale, ma l'esportatore format="hailo" di Ultralytics convalida attualmente le teste standard di rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, posa e OBB di YOLO. La tabella delle attività descrive i percorsi degli esportatori disponibili; la validazione hardware è elencata separatamente di seguito.

Famiglie di rilevamento specializzate come YOLOv10, YOLO-World, YOLOE e RT-DETR sono anch'esse ❌ non supportate. Ultralytics rifiuta queste attività e famiglie di modelli prima della compilazione invece di produrre un HEF non convalidato.

Posa, OBB, classificazione, segmentazione semantica YOLO26 e stima della profondità YOLO26 (percorso Hailo-8/8L) sono stati convalidati su Hailo-8L con HailoRT 4.23 e DFC 3.33. L'esportatore accetta gli altri target elencati, ma quei nuovi percorsi di attività richiedono la convalida con il compilatore e il dispositivo corrispondenti prima dell'uso in produzione.

Seleziona uno di questi valori name:

hailo8l è l'impostazione predefinita. Installa la generazione del DFC corrispondente al target selezionato.

Generazioni di hardware e SDK Hailo#

Le famiglie di acceleratori Hailo utilizzano generazioni di compiler diverse. L'HEF generato deve corrispondere all'hardware di destinazione, quindi scegli name per il dispositivo che eseguirà l'inferenza anziché per la macchina che esegue l'esportazione.

Il compilatore viene eseguito su Linux x86_64, mentre l'HEF risultante viene eseguito sul dispositivo Hailo tramite HailoRT. Questa separazione ti consente di compilare su una workstation o nella Ultralytics Platform e di distribuire il piccolo artefatto runtime su un host edge ARM o x86.

Note sulla compatibilità#

La compilazione Hailo è specifica per l'hardware e utilizza una forma di input fissa. Tieni a mente questi vincoli:

• Il valore name selezionato deve corrispondere all'acceleratore di distribuzione.
• Le immagini di calibrazione dovrebbero rappresentare l'illuminazione, i punti di vista, gli oggetti e gli sfondi previsti in produzione.
• Un HEF compilato con un determinato imgsz non diventa ridimensionabile dinamicamente a runtime.
• I conteggi delle classi personalizzate sono supportati poiché Ultralytics genera la configurazione di post-elaborazione dai metadati del modello.
• Sono supportati i modelli di rilevamento con teste standard Ultralytics Detect, i modelli di segmentazione, posa e OBB di YOLOv8/YOLO11, i modelli di classificazione di YOLOv8/YOLO11/YOLO26 e i modelli di segmentazione semantica e stima della profondità di YOLO26; la segmentazione di istanze, la posa e il bounding box orientato di YOLO26, insieme alle esportazioni di YOLO-World, YOLOE, YOLOv10 e RT-DETR, non sono attualmente supportati.
• Gli artefatti Hailo-8/8L e Hailo-10/15 sono compilati da diverse generazioni di DFC e non sono intercambiabili.

Calibrazione e quantizzazione INT8#

L'esportazione Hailo HEF utilizza la quantizzazione INT8 per mappare la rete YOLO in modo efficiente sull'acceleratore. Il dataset di calibrazione stima gli intervalli di attivazione; non riaddestra il modello né richiede etichette durante la compilazione.

Quando data viene omesso, Ultralytics utilizza un dataset di calibrazione leggero specifico per l'attività, come COCO128 per il rilevamento, cityscapes8 per la segmentazione semantica o depth8 per la stima della profondità. La testa di profondità densa è particolarmente sensibile al dominio di calibrazione: calibrare un modello di profondità con immagini di rilevamento non correlate appiattisce la mappa prevista, e insiemi più grandi nello stesso dominio migliorano la fedeltà. Per un modello di visione artificiale personalizzato, punta data al suo YAML del dataset in modo che il compilatore osservi immagini rappresentative dal dominio di distribuzione effettivo:

model.export(format="hailo", name="hailo8l", data="my_dataset.yaml")

fraction seleziona la porzione di dataset utilizzata per la calibrazione. Più immagini aiutano solo quando rappresentano il dominio di distribuzione; le immagini fuori dominio possono ridurre l'accuratezza quantizzata e aumentare il tempo di ottimizzazione. Se l'HEF INT8 perde accuratezza rispetto al modello PyTorch originale, migliora prima i dati di calibrazione prima di modificare le impostazioni del modello o del runtime.

Aspettative di accuratezza per famiglia di modelli#

Misurati su un Hailo-8L con calibrazione in-domain (COCO128, 128 immagini), gli export HEF in INT8 mantengono la seguente quota del loro mAP50 PyTorch sotto lo stesso protocollo di valutazione:

La conservazione confronta entrambi i modelli alla stessa soglia di confidenza. Gli HEF di YOLOv8 e YOLO11 integrano il valore conf (predefinito 0,25) del momento dell'esportazione nell'NMS su chip, quindi la validazione rispetto a una baseline PyTorch alla sua soglia bassa predefinita integra una parte più ampia della curva precisione-richiamo e sovrastima il divario di quantizzazione.

Oltre al rilevamento, i percorsi di esportazione per segmentazione, posa, OBB e classificazione sono stati validati sullo stesso Hailo-8L (DFC 3.33, HailoRT 4.23). Ogni HEF INT8 è stato confrontato con il relativo checkpoint PyTorch sullo stesso split di validazione, utilizzando una calibrazione in-domain:

La segmentazione, la posa e l'OBB sono stati calibrati con il set predefinito nel dominio di ciascuna attività (COCO128-seg, COCO8-pose, DOTA128); la classificazione è stata calibrazione con ImageNet100. Da questi valori predefiniti derivano due avvertenze: COCO8-pose contiene solo 8 immagini, quindi considera la posa come indicativa e passa un valore data= più grande per la produzione, e DOTA8 satura l'mAP50 vicino al 100% per entrambi i modelli, motivo per cui l'OBB viene letto su DOTA128. La classificazione è anche l'unica attività in cui YOLO11 mantiene di più rispetto a YOLOv8; per le altre, il backbone di attenzione di YOLO11 è più sensibile all'INT8.

Dalle misurazioni sui dispositivi derivano tre regole pratiche:

1. Calibra sempre in-domain. Il fine-tuning con immagini out-of-domain equivale a disabilitarlo completamente: uno YOLO26n calibrato con 1.238 immagini out-of-domain mantiene la stessa accuratezza (85.7%) di uno compilato senza fine-tuning. Un piccolo set in-domain supera uno grande out-of-domain.
2. Riduci conf di circa 0,05 per le distribuzioni YOLO26. La quantizzazione sposta i punteggi di YOLO26 verso il basso di circa 0,05 in media, quindi una soglia ottimizzata in PyTorch scarta i rilevamenti validi sull'HEF. L'utilizzo di conf=0.20 sul dispositivo corrisponde al conteggio dei rilevamenti di PyTorch a conf=0.25, e una riduzione leggermente superiore (intorno a conf=0.15) recupera essenzialmente tutto il divario mAP50 rimanente a costo di un maggior numero di rilevamenti a bassa confidenza. La quantizzazione riordina anche circa il 20% dei rilevamenti, un effetto di ordinamento permanente che nessuna soglia annulla, ma tale rimescolamento non blocca il recupero dell'mAP50 alla soglia inferiore.
3. La penalità di attenzione è strutturale su Hailo-8/8L (DFC 3.33). I blocchi di attenzione vengono compilati in operazioni matmul che mantengono gli input di attivazione INT8 in ogni modalità offerta dal compilatore per essi; la modalità di output a 16 bit fallisce l'allocazione per questo grafo e l'aumento della precisione dei layer circostanti non aiuta perché il matmul requantizza comunque i suoi input in INT8 (la protezione delle convoluzioni depthwise e di output a 16 bit ha lasciato l'mAP invariato nei nostri test). Quando l'accuratezza è la priorità e il modello è intercambiabile, YOLO11 si quantizza attualmente meglio di YOLO26 in questo caso; le generazioni Hailo più recenti (DFC 5.x) offrono più opzioni di precisione mista e potrebbero differire.

Artefatti esportati#

L'esportazione crea una directory contenente l'HEF distribuibile e i metadati Ultralytics:

yolo11n_hailo_model/
├── yolo11n.hef
├── metadata.yaml
└── nms_config.json

• *.hef è il modello compilato caricato da HailoRT.
• metadata.yaml conserva i nomi dei modelli, l'attività, la dimensione di input, lo stride e le informazioni sul target Hailo.
• nms_config.json registra la configurazione NMS di HailoRT generata per i modelli di rilevamento YOLOv8 e YOLO11. Il rilevamento YOLO26 e tutte le attività non di rilevamento (segmentazione, semantica, profondità, classificazione, posa, OBB) non utilizzano questo file.

Il grafo ONNX intermedio viene rimosso dopo la compilazione.

Esegui l'inferenza su hardware Hailo#

Installa HailoRT sul dispositivo di destinazione. Gli utenti di Raspberry Pi AI Kit e AI HAT+ possono seguire la guida al software Raspberry Pi AI:

sudo apt install hailo-all
hailortcli fw-control identify

Copia l'intera directory di esportazione sul dispositivo in modo che metadata.yaml rimanga accanto all'HEF. Ultralytics utilizza HailoRT per eseguire predict e val direttamente sulla directory esportata:

from ultralytics import YOLO

model = YOLO("yolo11n_hailo_model")
results = model.predict("path/to/image.jpg")

Per i modelli di rilevamento, il backend converte l'output NMS HailoRT di YOLOv8 e YOLO11 e decodifica automaticamente gli output one-to-one di YOLO26. Decodifica i tensori grezzi di segmentazione, posa e OBB, restituisce le probabilità di classificazione su chip e produce mappe di classe semantiche tramite riduzione sull'host su Hailo-8/8L e tutte le teste a classe singola o un ArgMax su chip per le teste multi-classe Hailo-10/15. TAPPAS, GStreamer e l'helper picamera2.devices.Hailo di Raspberry Pi rimangono disponibili per pipeline specifiche dell'applicazione.

Per una distribuzione GStreamer, passa l'HEF a hailonet:

gst-launch-1.0 filesrc location=video.mp4 ! decodebin ! videoconvert ! \
  hailonet hef-path=yolo11n_hailo_model/yolo11n.hef ! \
  hailofilter function-name=yolov8 ! hailooverlay ! autovideosink

Opzioni di deployment Hailo#

L'HEF è lo stesso artefatto di modello distribuibile su diverse interfacce runtime Hailo. Scegli l'interfaccia adatta all'applicazione:

Conserva metadata.yaml insieme all'HEF quando l'applicazione richiede i nomi delle classi, la dimensione di input, lo stride o altre informazioni sul modello di Ultralytics. L'HEF in sé non sostituisce la logica a livello di applicazione per acquisizione da telecamera, visualizzazione, tracciamento, avvisi o archiviazione.

Verifica il dispositivo Hailo e l'HEF#

Prima di integrare una fotocamera o una pipeline video, verifica il runtime e l'acceleratore in modo indipendente:

hailortcli fw-control identify
hailortcli parse-hef yolo11n_hailo_model/yolo11n.hef

Le misurazioni delle prestazioni del solo dispositivo isolano l'inferenza Hailo dalla decodifica video, dal ridimensionamento dell'immagine, dal disegno e dall'I/O dell'applicazione. Misura l'applicazione completa separatamente quando stimi la latenza end-to-end o i fotogrammi al secondo.

Confronto di Hailo con altri formati di esportazione YOLO#

Scegli un formato di esportazione basato sull'hardware che eseguirà il modello:

HEF è la scelta corretta quando il dispositivo finale contiene un acceleratore Hailo. ONNX rimane utile come formato di interscambio portabile, ma HailoRT esegue l'HEF specifico per l'hardware prodotto dal DFC anziché il modello ONNX originale.

Ottimizza le prestazioni della computer vision su Hailo#

Le scelte relative al modello e alla pipeline contano spesso più dei flag del compilatore:

• Inizia con un modello YOLO piccolo e aumenta la dimensione del modello solo quando la precisione lo richiede.
• Scegli il valore imgsz fisso più basso che preservi comunque gli oggetti importanti per l'applicazione.
• Usa immagini di calibrazione dalla fotocamera e dall'ambiente reali quando possibile.
• Mantieni la rete Hailo attiva tra un fotogramma e l'altro invece di riaprire l'HEF per ogni inferenza.
• Separa il tempo di inferenza del dispositivo dalla pre-elaborazione, dalla decodifica video, dalla post-elaborazione, dalla visualizzazione e dall'I/O di rete.
• Usa una pipeline di streaming come GStreamer per carichi di lavoro video sostenuti.
• Convalida l'HEF esportato sull'acceleratore esatto e sulla versione di HailoRT utilizzata in produzione.

Argomenti di esportazione#

Per l'esportazione del rilevamento, YOLOv8 e YOLO11 ricevono HailoRT NMS, mentre YOLO26 mantiene i suoi output one-to-one senza NMS. La segmentazione, la posa e l'OBB utilizzano tensori di testa grezzi, la classificazione restituisce probabilità su chip e la segmentazione semantica restituisce logit grezzi su Hailo-8/8L e tutte le teste a classe singola o mappe di classe integrate per le teste multi-classe Hailo-10/15. La stima della profondità restituisce il logit di profondità grezzo, che Ultralytics decodifica in una mappa di profondità metrica durante l'inferenza. Non passare end2end; le sostituzioni esplicite vengono rifiutate. Forme dinamiche, batch superiori a uno, NMS di Ultralytics incorporato, FP16 e FP32 non sono supportati.

Risoluzione dei problemi di esportazione Hailo#

Errore di importazione del compilatore Hailo Dataflow#

Se l'esportazione segnala che manca hailo_sdk_client, installa il pacchetto wheel del DFC per la generazione dell'hardware di destinazione nello stesso ambiente Python di Ultralytics. Hailo-8/8L e Hailo-10/15 richiedono generazioni di compilatori diverse.

Sistema operativo o architettura non supportati#

La compilazione HEF è supportata su Linux x86_64. Esporta tramite Ultralytics Platform o usa una workstation compatibile se il computer locale è macOS, Windows, Raspberry Pi o un altro sistema ARM.

L'esportazione richiede molto tempo#

L'ottimizzazione DFC è la fase più onerosa. Il tempo di compilazione aumenta con la dimensione del modello, la risoluzione di input e i dati di calibrazione. Una GPU supportata può accelerare l'ottimizzazione, mentre la compilazione basata solo su CPU può essere sostanzialmente più lenta.

La precisione del modello quantizzato diminuisce#

Usa immagini di calibrazione che assomiglino agli input di produzione e includano oggetti importanti, scale, condizioni di illuminazione e sfondi. Confronta il modello PyTorch originale e l'HEF esportato sullo stesso set di validazione prima della distribuzione. Rimane un divario moderato dipendente dalla famiglia anche con una buona calibrazione; consulta Accuracy Expectations by Model Family per le baseline misurate.

L'HEF non viene caricato sul dispositivo#

Conferma che name corrisponda all'architettura fisica di Hailo e che il driver del dispositivo, il firmware e i pacchetti HailoRT siano reciprocamente compatibili. Ispeziona l'artefatto con hailortcli parse-hef e verifica l'acceleratore con hailortcli fw-control identify.

L'analisi dell'output sembra errata#

Conserva metadata.yaml accanto all'HEF in modo che Ultralytics possa selezionare il percorso di post-elaborazione corrispondente per YOLOv8, YOLO11 o YOLO26. Le applicazioni HailoRT personalizzate devono allo stesso modo abbinare la post-elaborazione alla famiglia di modelli esportata.

Riepilogo#

L'esportazione Ultralytics Hailo fornisce un percorso diretto da un modello YOLO addestrato a un HEF distribuibile:

1. Carica un modello di rilevamento o classificazione YOLOv8, YOLO11 o YOLO26, un modello di segmentazione, posa o OBB di YOLOv8/YOLO11, oppure un modello di segmentazione semantica o stima della profondità di YOLO26.
2. Esporta con format="hailo" e seleziona l'architettura di destinazione.
3. Calibra e compila localmente con il DFC corrispondente, oppure utilizza l'esportazione gestita nella piattaforma Ultralytics.
4. Copia l'HEF e metadata.yaml sul dispositivo edge basato su Hailo.
5. Esegui l'inferenza con HailoRT, Raspberry Pi Picamera2 o una pipeline video GStreamer.

Per altri target di distribuzione di visione artificiale, consulta Export mode, Benchmark mode e la guida alle integrazioni. Le guide hardware correlate includono ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 e Qualcomm QNN.

FAQ#