Esportazione Hailo per modelli YOLO Ultralytics#

Gli acceleratori AI Hailo eseguono modelli compilati nel formato eseguibile Hailo (HEF) su dispositivi edge come Raspberry Pi AI HAT+ e AI HAT+ 2. Ultralytics esporta direttamente in HEF i modelli YOLO per rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, posa e OBB con il compilatore del flusso di dati Hailo (DFC).

Il deployment Hailo è progettato per la computer vision all'edge: fotocamere, robot, sistemi industriali, gateway e altri dispositivi che richiedono il rilevamento locale degli oggetti senza inviare ogni fotogramma al cloud. Un HEF compilato contiene la rete quantizzata, l'allocazione hardware, la pianificazione e l'eventuale post-processing HailoRT necessari per l'acceleratore selezionato.

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

La combinazione di Ultralytics YOLO con un'unità di elaborazione neurale Hailo (NPU) offre un percorso pratico dall'addestramento del modello all'inferenza AI edge. I casi d'uso comuni includono:

• Smart camera e analisi video: esegui il rilevamento degli oggetti in tempo reale vicino alla fotocamera per applicazioni di sicurezza, vendita al dettaglio, traffico e monitoraggio dell'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 AI con Raspberry Pi: aggiungi l'inferenza vision accelerata ai sistemi Raspberry Pi usando AI HAT+ o AI HAT+ 2.
• Gateway edge e PC AI: elabora localmente più flussi video o di sensori, riducendo al contempo i requisiti di banda e di elaborazione cloud.

L'inferenza locale può migliorare la privacy e i tempi di risposta, perché le immagini rimangono sul dispositivo di deployment. Throughput effettivo, latenza e consumo energetico dipendono dalle dimensioni del modello YOLO, dalla risoluzione di input, dall'architettura Hailo, dal sistema host e dalla pipeline applicativa.

Come funziona l'esportazione Hailo#

Ultralytics gestisce l'intero workflow 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 le direttive di normalizzazione, attivazione e post-processing.
4. Costruisce 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 propri output one-to-one senza NMS, quindi l'esportatore seleziona automaticamente un percorso diverso per output e quantizzazione. I modelli di segmentazione, posa e OBB YOLOv8/YOLO11 compilano i tensori raw della head, che Ultralytics decodifica durante l'inferenza, mentre la classificazione YOLOv8/YOLO11/YOLO26 esegue softmax sul chip, così l'HEF restituisce direttamente le probabilità delle classi. Per la segmentazione semantica YOLO26, l'esportatore segue l'acceleratore: Hailo-8/8L (DFC v3.x) restituiscono i logits del classificatore per l'upsampling e la riduzione sull'host, mentre Hailo-10H/15 (DFC v5.x) compilano sul chip le head ArgMax multiclass e restituiscono una mappa delle classi compatta. Le head a classe singola utilizzano il percorso con logits sull'host per ogni target, perché richiedono una soglia invece di ArgMax. I modelli di profondità YOLO26 compilano la convoluzione dense logit in a16 e ricostruiscono sull'host la mappa di profondità metrica (il clamp/exp e la calibrazione log-affine appresa che seguono la head), quindi il quantizzatore mantiene l'intervallo più ampio sul logit raw. Non è necessario trovare i nodi finali ONNX, scrivere uno script del modello Hailo (.alls) o creare manualmente un JSON NMS.

Installazione#

Installa Ultralytics e scarica la wheel DFC per il tuo hardware target 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-10H e Hailo-15 utilizzano DFC v5.x. Installa la generazione del compilatore corrispondente all'acceleratore target.

Esporta un modello Hailo HEF#

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

from ultralytics import YOLO

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

Il comando CLI equivalente è:

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

L'esportazione Hailo è solo INT8. Ultralytics scarica automaticamente un dataset di calibrazione specifico per il task quando non viene fornito data. Per i modelli personalizzati, usa immagini rappresentative di addestramento o validazione:

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

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

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

Modelli e hardware supportati#

L'ecosistema Hailo copre un'ampia gamma di workload di computer vision, ma l'esportatore Ultralytics format="hailo" attualmente convalida le head standard YOLO per rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, posa e OBB. La tabella dei task descrive i percorsi di esportazione disponibili; la convalida hardware è elencata separatamente di seguito.

Famiglie di rilevamento specializzate come YOLOv10, YOLO-World, YOLOE e RT-DETR non sono attualmente supportate ❌ tramite il percorso Ultralytics format="hailo". Ultralytics rifiuta questi task e famiglie di modelli prima della compilazione, invece di produrre un HEF non convalidato.

La posa, l'OBB, la classificazione, la segmentazione semantica YOLO26 e la stima della profondità YOLO26 (percorso Hailo-8/8L) sono state convalidate su Hailo-8L con HailoRT 4.23 e DFC 3.33. L'esportatore accetta gli altri target elencati, ma questi nuovi percorsi dei task richiedono la convalida con il compilatore e il dispositivo corrispondenti prima dell'uso in produzione.

Seleziona uno di questi valori name:

Se name viene omesso, hailo8l viene utilizzato come valore predefinito; imposta name sull'acceleratore su cui effettuerai il deployment. Installa la generazione DFC corrispondente al target selezionato.

Generazioni hardware e SDK Hailo#

Le famiglie di acceleratori Hailo utilizzano generazioni diverse del compilatore. L'HEF generato deve corrispondere all'hardware target, quindi scegli name per il dispositivo che eseguirà l'inferenza, non 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 consente di compilare su una workstation o nella Ultralytics Platform e di distribuire il piccolo artefatto di 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 presenti questi vincoli:

• Il valore name selezionato deve corrispondere all'acceleratore di deployment.
• Le immagini di calibrazione devono rappresentare l'illuminazione, i punti di vista, gli oggetti e gli sfondi previsti in produzione.
• Ogni HEF viene compilato per un valore imgsz fisso. Per gestire più risoluzioni, ridimensiona i fotogrammi sull'host alla dimensione compilata oppure compila un HEF separato per ogni risoluzione.
• Sono supportati numeri di classi personalizzati, perché Ultralytics genera la configurazione del post-processing dai metadati del modello.
• Sono supportati i modelli di rilevamento con head standard Detect di Ultralytics, i modelli YOLOv8/YOLO11 per segmentazione, posa e OBB, i modelli YOLOv8/YOLO11/YOLO26 per classificazione e i modelli YOLO26 per segmentazione semantica e stima della profondità; la segmentazione delle istanze, la posa e i riquadri di delimitazione orientati di YOLO26, insieme alle esportazioni YOLO-World, YOLOE, YOLOv10 e RT-DETR, non sono attualmente supportati.
• Gli artefatti Hailo-8/8L e Hailo-10H/15 vengono compilati da generazioni diverse di DFC e non sono intercambiabili.

Calibrazione e quantizzazione INT8#

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

Quando data viene omesso, Ultralytics usa 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à. L'head densa della profondità è particolarmente sensibile al dominio di calibrazione: calibrare un modello di profondità con immagini di rilevamento non correlate appiattisce la mappa prevista, mentre set più grandi e appartenenti al dominio migliorano la fedeltà. Per un modello di computer vision personalizzato, imposta data sul relativo YAML del dataset, in modo che il compilatore osservi immagini rappresentative dell'effettivo dominio di distribuzione:

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

fraction seleziona il rapporto o il numero di immagini usato per la calibrazione. Gli elenchi [train, val, test] limitano ogni suddivisione, gli elenchi di due elementi lasciano completo test e 0 salta il test. Un numero maggiore di immagini è utile 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 innanzitutto i dati di calibrazione prima di modificare le impostazioni del modello o del runtime.

Aspettative di accuratezza per famiglia di modelli#

Misurate su Hailo-8L con calibrazione appartenente al dominio (COCO128, 128 immagini), le esportazioni HEF INT8 conservano la seguente percentuale del loro mAP50 PyTorch secondo lo stesso protocollo di valutazione:

La conservazione confronta entrambi i modelli alla stessa soglia di confidenza. Gli HEF YOLOv8 e YOLO11 incorporano conf del momento dell'esportazione (predefinito 0.25) nel NMS sul chip, quindi la validazione rispetto a una baseline PyTorch alla sua soglia bassa predefinita integra una parte più ampia della curva precision-recall e sovrastima il divario di quantizzazione.

Oltre al rilevamento, i percorsi di esportazione per segmentazione, posa, OBB e classificazione sono stati convalidati sullo stesso Hailo-8L (DFC 3.33, HailoRT 4.23). Ogni HEF INT8 è stato confrontato con il relativo checkpoint PyTorch sulla stessa suddivisione di validazione, usando una calibrazione appartenente al dominio:

Segmentazione, posa e OBB sono stati calibrati con il set predefinito appartenente al dominio di ciascuna attività (COCO128-seg, COCO8-pose, DOTA128); la classificazione è stata calibrata con ImageNet100. Da queste impostazioni predefinite derivano due precisazioni: COCO8-pose contiene solo 8 immagini, quindi considera la posa indicativa e passa un data= più grande per la produzione; inoltre, DOTA8 porta il mAP50 vicino al 100% per entrambi i modelli, motivo per cui OBB viene valutato su DOTA128. La classificazione è anche l'unica attività in cui YOLO11 conserva più accuratezza di YOLOv8; per le altre, il backbone con attenzione di YOLO11 è più sensibile a INT8.

Dalle misurazioni sul dispositivo emergono tre regole pratiche:

1. Calibra sempre nel dominio. Il fine-tuning con immagini fuori dominio equivale a disabilitare del tutto il fine-tuning: un YOLO26n calibrato con 1.238 immagini fuori dominio conserva la stessa accuratezza (85,7%) di uno compilato senza fine-tuning. Un piccolo set appartenente al dominio è migliore di uno grande fuori dominio.
2. Riduci conf di circa 0.05 per le distribuzioni YOLO26. La quantizzazione riduce i punteggi YOLO26 di circa 0.05 in media, quindi una soglia regolata in PyTorch elimina rilevamenti validi sull'HEF. Usare conf=0.20 sul dispositivo corrisponde al numero di rilevamenti di PyTorch a conf=0.25, mentre ridurre ulteriormente la soglia (a circa conf=0.15) recupera essenzialmente tutto il divario mAP50 rimanente, al costo di un numero maggiore di rilevamenti a bassa confidenza. La quantizzazione modifica inoltre l'ordinamento di circa il 20% dei rilevamenti — un effetto permanente sull'ordine che nessuna soglia può annullare — ma questo rimescolamento non impedisce di recuperare il mAP50 con la soglia più bassa.
3. La penalizzazione dell'attenzione è strutturale su Hailo-8/8L (DFC 3.33). I blocchi di attenzione vengono compilati in operazioni matmul che mantengono gli input delle attivazioni INT8 in ogni modalità offerta dal compilatore; la modalità con output a 16 bit non riesce ad allocare questo grafo e aumentare la precisione dei layer circostanti non aiuta, perché il prodotto matriciale ricquantizza comunque i propri input a INT8 (proteggere le convoluzioni depthwise e di output a 16 bit ha lasciato invariato il mAP nei nostri test). Quando l'accuratezza è prioritaria e il modello è intercambiabile, qui YOLO11 attualmente quantizza meglio di YOLO26; le generazioni Hailo più recenti (DFC 5.x) espongono più opzioni di precisione mista e potrebbero comportarsi diversamente.

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 del modello, l'attività, la dimensione dell'input, lo stride e le informazioni sulla destinazione Hailo.
• nms_config.json registra la configurazione NMS 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 usano questo file.

Il grafo ONNX intermedio viene rimosso dopo la compilazione.

Eseguire l'inferenza sull'hardware Hailo#

Installa HailoRT sul dispositivo di destinazione. Gli utenti di Raspberry Pi AI HAT+ e AI HAT+ 2 possono seguire la guida al software AI di Raspberry Pi. Su Raspberry Pi OS i due set di pacchetti non possono essere installati insieme, quindi esegui solo il blocco corrispondente al tuo hardware, poi riavvia.

Per AI HAT+ (Hailo-8 / Hailo-8L):

sudo apt install dkms
sudo apt install hailo-all
sudo reboot

Per AI HAT+ 2 (Hailo-10H, Raspberry Pi OS Trixie o versione successiva):

sudo apt install dkms
sudo apt install hailo-h10-all
sudo reboot

Dopo il riavvio, verifica che l'acceleratore sia rilevato:

hailortcli fw-control identify

Copia l'intera directory di esportazione sul dispositivo, in modo che metadata.yaml rimanga accanto all'HEF. Ultralytics usa HailoRT per eseguire direttamente predict e val 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 automaticamente l'output NMS HailoRT di YOLOv8 e YOLO11 e decodifica gli output one-to-one di YOLO26. Decodifica i tensori grezzi di segmentazione, posa e OBB, restituisce le probabilità di classificazione sul chip e produce mappe delle classi semantiche tramite riduzione sull'host su Hailo-8/8L e per tutti gli head a classe singola, oppure tramite ArgMax sul chip per gli head multi-classe Hailo-10H/15. TAPPAS, GStreamer e l'helper picamera2.devices.Hailo di Raspberry Pi restano 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 distribuzione Hailo#

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

Conserva metadata.yaml insieme all'HEF quando l'applicazione richiede i nomi delle classi Ultralytics, la dimensione dell'input, lo stride o altre informazioni sul modello. L'HEF da solo non sostituisce la logica a livello applicativo per acquisizione dalla videocamera, visualizzazione, tracking, avvisi o archiviazione.

Verificare il dispositivo Hailo e l'HEF#

Prima di integrare una pipeline video o per videocamera, verifica separatamente il runtime e l'acceleratore:

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

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

Hailo a confronto con altri formati di esportazione YOLO#

Scegli un formato di esportazione in base all'hardware che eseguirà il modello. HEF è specifico per l'hardware e va scelto quando il dispositivo finale contiene già un acceleratore Hailo, non come formato edge generico o automaticamente più veloce.

Non dare per scontato che Hailo sia più veloce o più efficiente nei consumi solo perché è una NPU. Per le nuove distribuzioni M.2, DeepX è il candidato più solido per prestazioni YOLO superiori e migliori prestazioni per watt, mentre Axelera punta a un throughput multi-stream sostanzialmente maggiore. Rockchip è un'opzione popolare e meno costosa per SBC e sistemi embedded. I valori TOPS e di consumo dei produttori non sono benchmark applicativi direttamente confrontabili, quindi convalida lo stesso checkpoint YOLO, la stessa dimensione dell'input, la stessa accuratezza, lo stesso host e la pipeline video completa sugli eventuali dispositivi prima di acquistare l'hardware.

Ottimizzare le prestazioni di computer vision su Hailo#

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

• Inizia con un modello YOLO piccolo e aumenta le dimensioni del modello solo quando l'accuratezza lo richiede.
• Scegli il valore fisso più basso di imgsz che mantenga comunque gli oggetti importanti per l'applicazione.
• Quando possibile, usa immagini di calibrazione provenienti dalla videocamera e dall'ambiente reali.
• Mantieni attiva la rete Hailo tra un fotogramma e l'altro invece di riaprire l'HEF per ogni inferenza.
• Separa il tempo di inferenza sul dispositivo dal pre-processing, dalla decodifica video, dal post-processing, dalla visualizzazione e dall'I/O di rete.
• Usa una pipeline di streaming come GStreamer per carichi video prolungati.
• Convalida l'HEF esportato sull'acceleratore esatto e sulla versione di HailoRT utilizzati in produzione.

Argomenti di esportazione#

Per l'esportazione della rilevazione, YOLOv8 e YOLO11 ricevono NMS di HailoRT, mentre YOLO26 mantiene i propri output one-to-one senza NMS. La segmentazione, la stima della posa e gli OBB utilizzano i tensori grezzi della head, la classificazione restituisce probabilità on-chip e la segmentazione semantica restituisce logits grezzi su Hailo-8/8L e su tutte le head a classe singola, oppure mappe delle classi integrate per le head Hailo-10H/15 multiclass. La stima della profondità restituisce il logit grezzo della profondità, che Ultralytics decodifica in una mappa di profondità metrica durante l'inferenza. Non passare end2end; le sostituzioni esplicite vengono rifiutate. Le forme dinamiche, l'NMS Ultralytics integrato, FP16 e FP32 non sono supportati.

Risoluzione dei problemi dell'esportazione Hailo#

Errore di importazione del compilatore Hailo Dataflow#

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

Sistema operativo o architettura non supportati#

La compilazione HEF è supportata su Linux x86_64. Esegui l'esportazione tramite Ultralytics Platform oppure utilizza una workstation compatibile se il computer locale è un sistema 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 le dimensioni del modello, la risoluzione di input e i dati di calibrazione. Una GPU supportata può accelerare l'ottimizzazione, mentre la compilazione che utilizza solo la CPU può essere sensibilmente più lenta.

Riduzione della precisione del modello quantizzato#

Utilizza immagini di calibrazione simili agli input di produzione e includi gli oggetti, le scale, le condizioni di illuminazione e gli sfondi importanti. Confronta il modello PyTorch originale e l'HEF esportato sullo stesso set di validazione prima della distribuzione. Anche con una buona calibrazione rimane una differenza moderata, dipendente dalla famiglia; consulta Aspettative di precisione per famiglia di modelli per i valori di riferimento misurati.

L'HEF non viene caricato sul dispositivo#

Verifica che name corrisponda all'architettura Hailo fisica 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#

Mantieni metadata.yaml accanto all'HEF, in modo che Ultralytics possa selezionare il percorso di post-elaborazione corrispondente per YOLOv8, YOLO11 o YOLO26. Anche le applicazioni HailoRT personalizzate devono associare la post-elaborazione alla famiglia di modelli esportata.

Riepilogo#

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

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

Per altre destinazioni di distribuzione della computer vision, consulta Modalità di esportazione, Modalità benchmark e la guida alle integrazioni. Le guide hardware correlate includono DeepX, Axelera, ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 e Qualcomm QNN.

FAQ#