Esportazione AMD Xilinx per Ultralytics YOLO con Vitis AI#

L'esportazione dei modelli Ultralytics YOLO26 con format="xilinx" li quantizza con AMD Quark per la NPU dei SoC adattivi AMD Versal AI Edge Series Gen 2, pronti per la compilazione di un modello .rai con il compilatore Vitis AI di AMD. La stessa esportazione convalida la precisione INT8 su qualsiasi host prima della distribuzione.

I dispositivi AMD Xilinx sono alla base di molte telecamere industriali, sistemi di visione per il settore automobilistico, robot, droni e prodotti di diagnostica per immagini nel mondo. Combinano processori Arm con logica programmabile e, nei dispositivi più recenti, AI Engine dedicati; così, un singolo chip può acquisire video, preelaborarlo, eseguire il rilevamento di oggetti e agire in base al risultato con una latenza di inferenza bassa e prevedibile.

Questa guida illustra l'esportazione AMD Xilinx, come compilarla ed eseguirla su una scheda Versal, le famiglie di dispositivi AMD Xilinx, il funzionamento dell'AI su questi dispositivi e gli operatori Ultralytics YOLO supportati da ciascun acceleratore.

Che cos'è AMD Xilinx?#

Xilinx ha inventato il field-programmable gate array (FPGA), ovvero l'array di gate programmabile sul campo, negli anni '80 ed è diventata un fornitore leader di SoC e FPGA adattivi. AMD ha completato l'acquisizione di Xilinx nel febbraio 2022 e ora commercializza queste linee di prodotti con il marchio AMD: AMD Zynq, AMD Kria, AMD Versal e AMD Vitis.

Termini e concetti chiave#

La distribuzione AMD Xilinx usa un vocabolario specifico. La tabella seguente spiega tutti i termini usati in questa guida.

Famiglie di dispositivi AMD Xilinx per l'AI edge#

I dispositivi AMD Xilinx per l'AI edge appartengono a tre famiglie. Zynq e Kria usano la DPU nella logica programmabile, mentre i dispositivi Versal AI Edge descritti qui usano la NPU sui rispettivi AI Engine.

MPSoC Zynq UltraScale+#

Ogni chip Zynq UltraScale+ abbina la logica FPGA a un sistema di elaborazione Arm, con core Cortex-A53 dual-core (CG) o quad-core (EG ed EV) e core Cortex-R5F in tempo reale. I dispositivi EV aggiungono un codec video H.264/H.265 integrato. Per eseguire reti neurali, i progettisti integrano una DPU nella logica, accanto alle pipeline della videocamera e del video. Nei dispositivi più piccoli la DPU deve condividere lo spazio con il resto del progetto.

System-on-Module Kria#

Il modulo Kria K26 integra un MPSoC Zynq UltraScale+, memoria e alimentazione in un modulo pronto per la produzione, così non devi progettare autonomamente il processore, la memoria e il sottosistema di alimentazione. Il modulo si collega a una scheda carrier, che può essere quella di un kit di sviluppo o una tua scheda. È alla base del KV260 Vision AI Starter Kit per le telecamere intelligenti e del KR260 Robotics Starter Kit per la robotica. Poiché il K26 è basato su Zynq UltraScale+, usa lo stesso flusso DPU. La gamma Kria comprende anche altri moduli: verifica quale processore usa il tuo modulo prima di scegliere un flusso.

SoC adattivi Versal#

Versal è la famiglia di SoC adattivi di AMD. Le serie AI Edge e AI Core aggiungono AI Engine integrati accanto ai core Arm e alla logica programmabile, mentre alcune altre serie Versal non dispongono di AI Engine. L'IP NPU di AMD usa insieme AI Engine e logica programmabile, e Vitis AI è destinato ai componenti AIE-ML della serie AI Edge, come VE2302 e VE2802. La serie Versal AI Edge (kit di valutazione VEK280) e la serie Versal AI Edge Gen 2 (kit di valutazione VEK385) sono gli attuali target di AMD per l'AI edge e l'obiettivo delle versioni correnti di Vitis AI.

Come funziona l'AI sui dispositivi AMD Xilinx: DPU e NPU a confronto#

La maggior parte delle distribuzioni AI AMD Xilinx segue lo stesso schema. L'acceleratore esegue i livelli supportati, la CPU Arm gestisce la preelaborazione, la post-elaborazione e gli eventuali livelli non supportati dall'acceleratore, mentre un runtime sulla scheda coordina le due componenti.

AMD ha distribuito due generazioni di acceleratori, ciascuna con la propria toolchain e il proprio file del modello compilato. Questa guida tratta Vitis AI 3.5 per la DPU e Vitis AI 6.3 per la NPU; consulta la documentazione AMD aggiornata per le versioni successive.

Quale flusso Vitis AI mi serve?#

Scegli il flusso in base al dispositivo presente sulla tua scheda:

Esportazione su AMD Xilinx: convertire il modello YOLO#

Attività supportate#

L'esportazione AMD Xilinx supporta tutti e sette i task Ultralytics. La segmentazione semantica e la stima della profondità sono disponibili solo con YOLO26, l'unica famiglia che include queste teste.

Installazione#

L'esportazione AMD Xilinx funziona su Linux (x86-64 o ARM64) con Python da 3.11 a 3.13, le versioni supportate da AMD Quark. La prima esportazione compila anche gli operatori personalizzati di Quark, per cui serve un compilatore C++, ad esempio g++.

# Install the required package for YOLO
pip install ultralytics

AMD Quark viene installato automaticamente da PyPI alla prima esportazione. Per preinstallare le dipendenze necessarie all'esportazione:

pip install "ultralytics[export-xilinx]"

Per installare il repository in modalità modificabile, sostituisci "ultralytics[export-xilinx]" con -e ".[export-base,export-xilinx]". Per riprodurre l'ambiente Python 3.12 e l'esportazione di prova usati da CI, esegui il generatore di ambienti esistente dalla directory principale del repository:

ULTRALYTICS_ISOLATED_VENVS="$PWD/.venvs" python .github/scripts/create-export-env.py --env isolated-xilinx

Utilizzo#

Il formato AMD Xilinx supporta le modalità Esporta, Predici e Convalida. Senza AMD Vitis AI Execution Provider, la predizione e la convalida eseguono il modello quantizzato sulla CPU con ONNX Runtime, misurandone la precisione INT8 su qualsiasi host. Quando ONNX Runtime rende disponibile VitisAIExecutionProvider, come su una scheda Versal AI Edge Series Gen 2, Ultralytics lo seleziona automaticamente.

from ultralytics import YOLO

# Carica un modello YOLO26
model = YOLO("yolo26n.pt")

# Esporta nel formato AMD Xilinx per VEK385 (quantize=8 viene applicato automaticamente)
model.export(format="xilinx")  # creates 'yolo26n_xilinx_model/'

from ultralytics import YOLO

# Carica il modello AMD Xilinx esportato
model = YOLO("yolo26n_xilinx_model")

# Esegui l'inferenza
results = model("https://ultralytics.com/images/bus.jpg")

from ultralytics import YOLO

# Carica il modello AMD Xilinx esportato
model = YOLO("yolo26n_xilinx_model")

# Convalida la precisione INT8 sul dataset COCO8
metrics = model.val(data="coco8.yaml")

I nomi dei formati vitis, vitisai e versal sono alias di xilinx.

Argomenti di esportazione#

Imposta nms=False per esportare la testa YOLO26 senza NMS. La NMS incorporata (nms=True) non è supportata, perché AMD include NonMaxSuppression tra gli operatori che possono costringere l'intero modello a essere eseguito sulla CPU.

Per ulteriori dettagli sul processo di esportazione, visita la pagina della documentazione Ultralytics dedicata all'esportazione.

Struttura dell'output#

Dopo un'esportazione riuscita, viene creata una directory del modello con la seguente struttura:

yolo26n_xilinx_model/
├── yolo26n.onnx          # AMD Quark VINT8 model with the Ultralytics metadata
└── vitisai_config.json   # Vitis AI compiler configuration for the target device

La compilazione del modello, descritta di seguito, aggiunge una cache del compilatore yolo26n/ alla stessa directory, contenente il modello NPU yolo26n.rai e i report di compilazione di AMD, come final-vaiml-pass-summary.txt.

Come funziona l'esportazione#

L'esportazione segue il flusso Vitis AI documentato da AMD per Versal AI Edge Series Gen 2:

1. Esportazione ONNX con opset 17 e dimensione batch statica pari a 1.
2. Quantizzazione AMD Quark con la configurazione VINT8 (INT8 simmetrico con scale basate su potenze di due) e le opzioni richieste da AMD per la compilazione NPU: Int32Bias=False, enable_npu_cnn=True, DedicatedQDQPair=True e QuantizeAllOpTypes=True. La calibrazione usa il loader standard di Ultralytics per la calibrazione INT8, con lo stesso letterbox e lo stesso preprocessing RGB e 0–1 usati in inferenza.
3. Precisione mista: la testa del modello rimane in virgola mobile e il compilatore Vitis AI la esegue sulla NPU in BF16. Quantizzare la testa in INT8 causa gran parte della perdita di precisione; per lo stesso motivo, il tutorial YOLOv8m di AMD lascia la parte finale di post-processing fuori da INT8.
4. Configurazione del compilatore: vitisai_config.json seleziona la destinazione VAIML e il dispositivo da name.

Precisione#

La tabella confronta il modello INT8 esportato con il modello ONNX FP32 sul set val2017 di COCO (5.000 immagini) a 640, eseguendo entrambi con ONNX Runtime sulla CPU dell'host. I modelli INT8 sono stati calibrati sul dataset predefinito coco128.yaml; calibrare sui tuoi dati di distribuzione in genere riduce il divario.

Questi risultati su host eseguono il modello quantizzato con ONNX Runtime sulla CPU, che è il riferimento usato da metodologia di precisione di AMD per confrontare i risultati sulla NPU. I risultati pubblicati da AMD per YOLOv8m su VEK385 mostrano lo stesso approccio a precisione mista sulla NPU:

Fonte: tutorial di AMD su YOLOv8m per Versal AI Edge Gen 2, che riporta anche un tempo medio di inferenza di 10.69 ms su 100 esecuzioni VART a dp_size=1.

Compilazione ed esecuzione su Versal AI Edge Gen 2#

La directory esportata è pronta per il compilatore Vitis AI di AMD, che crea il modello .rai eseguito sulla NPU.

1. Prepara l'host e la scheda. Compila su un host Linux x86-64 con l'immagine Docker Vitis AI 6.3 per Versal AI Edge Gen 2 di AMD e una licenza del compilatore AMD AI Engine (consulta la pagina delle licenze AMD). Configura VEK385 seguendo la guida di configurazione della scheda di AMD.

2. Compila. Nel container, crea una sessione ONNX Runtime con Vitis AI Execution Provider, come nella guida alla compilazione di AMD. La sessione scrive nella directory di esportazione la cache yolo26n/ con yolo26n.rai:

   import onnxruntime as ort
   
   d = "yolo26n_xilinx_model"
   options = {"config_file": f"{d}/vitisai_config.json", "cache_dir": d, "cache_key": "yolo26n", "target": "VAIML"}
   ort.InferenceSession(f"{d}/yolo26n.onnx", providers=["VitisAIExecutionProvider"], provider_options=[options])

   Controlla yolo26n_xilinx_model/yolo26n/final-vaiml-pass-summary.txt per sapere quale parte del modello viene eseguita sulla NPU. Per YOLO26n a 640, il compilatore AMD Vitis AI 6.3 colloca il 99,9% degli operatori e dei calcoli sulla NPU VEK385 in un'unica partizione.

3. Esegui sulla scheda. Copia la directory di esportazione su VEK385. ONNX Runtime con Vitis AI Execution Provider carica yolo26n.rai compilato e lo esegue sulla NPU; YOLO("yolo26n_xilinx_model") seleziona automaticamente questo provider quando è disponibile.

Per la compilazione basta ONNX Runtime di AMD: esporta su qualsiasi macchina Linux e copia la directory nel container, invece di installarvi Ultralytics, perché questo potrebbe modificare i pacchetti bloccati del container. Quando Ultralytics è installato insieme alla build AMD onnxruntime-vitisai, come sulla scheda, mantiene quella build invece di sostituirla con onnxruntime standard.

Compatibilità dei modelli YOLO e operatori supportati#

Un acceleratore velocizza solo gli operatori implementati nell'hardware. Se un modello contiene un operatore non supportato, il compilatore in genere assegna quella parte della rete alla CPU Arm e ogni passaggio tra acceleratore e CPU aggiunge latenza. Alcuni operatori non possono essere suddivisi: sulla NPU Versal AI Edge Gen 2, AMD indica operatori come NonZero e NonMaxSuppression che possono costringere l'intero modello a essere eseguito sulla CPU. Il supporto degli operatori è il fattore più importante per le prestazioni dei modelli YOLO sull'hardware AMD Xilinx.

La tabella mostra dove viene eseguito ciascun operatore in un modello YOLO26. Un'esportazione ONNX standard di YOLO26n contiene 87 attivazioni SiLU, ognuna esportata come Sigmoid e Mul, oltre a 4 operatori MatMul e 2 operatori Softmax dai suoi due blocchi di attenzione: il blocco C2PSA alla fine del backbone (layer 10) e il blocco C3k2 con attenzione abilitata che produce l'output P5 (layer 22).

Fonti: operatori supportati UG1414 di AMD, supporto degli operatori PyTorch e gli elenchi degli operatori supportati, partizionati sulla CPU e non supportati di Versal AI Edge Gen 2. Il supporto dipende anche dalla configurazione della DPU e dai pattern del grafo, quindi controlla sempre il rapporto di partizionamento del compilatore.

Rendi YOLO26 compatibile con la DPU usando Hard-Swish#

La DPU fonde nelle convoluzioni solo ReLU, ReLU6, LeakyReLU, Hard-Swish e Hard-Sigmoid. Hard-Swish è un'approssimazione di SiLU adatta all'hardware, perciò è la sostituzione più naturale. I file YAML dei modelli Ultralytics accettano una chiave activation che modifica l'attivazione predefinita dei blocchi Conv (Guida alla configurazione YAML del modello).

Copia yolo26.yaml in yolo26-hswish.yaml e aggiungi una riga sotto i parametri:

# Parameters
nc: 80 # number of classes
activation: nn.Hardswish() # default Conv activation, DPU-native
end2end: True # whether to use end-to-end mode

Quindi crea il modello, trasferisci i pesi YOLO26 preaddestrati e esegui il fine-tuning sul tuo dataset:

from ultralytics import YOLO

# # Crea YOLO26n con attivazioni Hard-Swish; la 'n' nel nome indica la scala nano
model = YOLO("yolo26n-hswish.yaml").load("yolo26n.pt")  # # trasferisci i pesi preaddestrati

# # Esegui il fine-tuning per adattare la rete a Hard-Swish
model.train(data="coco8.yaml", epochs=100, imgsz=640)

Le attivazioni non hanno pesi, quindi tutti i pesi preaddestrati vengono trasferiti. Il grafo ONNX esportato contiene quindi 87 operatori HardSwish e nessun SiLU. Sostituisci coco8.yaml con il tuo dataset e confronta la precisione con quella del modello SiLU usando Val mode prima della distribuzione.

Gestione dei blocchi di attenzione sulla DPU#

YOLO26 applica l'attenzione alla risoluzione più bassa (una griglia 20×20 con input 640) in due punti: il blocco C2PSA al layer 10 e il blocco C3k2 con attenzione abilitata al layer 22. YOLO11 ha un solo blocco C2PSA. Su una DPU, gli operatori MatMul e Softmax vengono eseguiti sulla CPU, suddividendo il modello in sottografi DPU e CPU alternati. Hai tre opzioni:

1. Accetta i blocchi sulla CPU. Il modello compilato .xmodel conterrà quindi sottografi CPU: eseguilo con il Graph Runner di AMD, che esegue insieme i sottografi DPU e CPU quando è disponibile un'implementazione CPU per ogni operatore; altrimenti devi implementare e registrare gli operatori mancanti. Con una griglia 20×20, il calcolo dell'attenzione è ridotto, ma ogni trasferimento aggiuntivo tra DPU e CPU introduce latenza, quindi misurala sulla tua scheda.

2. Usa un file YAML senza attenzione. Nel tuo file YAML Hard-Swish, sostituisci il layer C2PSA con nn.Identity affinché gli indici dei layer usati da Concat e Detect restino validi, quindi disabilita l'attenzione nel layer 22:

   backbone:
       # ... layers 0-9 unchanged
       - [-1, 1, nn.Identity, []] # 10 C2PSA removed; keeps later layer indices valid
   
   head:
       # ... layers 11-21 unchanged
       - [-1, 1, C3k2, [1024, True, 0.5, False]] # 22 (P5/32-large), attention disabled
       - [[16, 19, 22], 1, Detect, [nc]] # Detect(P3, P4, P5)

   Il grafo ONNX esportato non contiene quindi operatori MatMul o Softmax. I pesi dell'attenzione non sono più applicabili (vengono trasferiti 624 dei 666 pesi di YOLO26n), quindi esegui il fine-tuning più a lungo e confronta la precisione con Val mode.

3. Usa un modello senza attenzione, come YOLOv8, che AMD ha utilizzato nei propri esempi DPU.

Su Versal AI Edge Gen 2, gli operatori di attenzione sono elencati tra quelli supportati dalla NPU, quindi di solito queste modifiche non sono necessarie. Verifica il posizionamento nel rapporto del compilatore, perché AMD segnala che gli operatori supportati possono comunque essere eseguiti sulla CPU a causa di vincoli di configurazione o memoria.

Compatibilità dei modelli a colpo d'occhio#

Distribuzione su altre destinazioni AMD Xilinx#

Le DPU Zynq UltraScale+ e Kria e la NPU Versal AI Edge di prima generazione usano flussi Vitis AI che format="xilinx" non produce. Addestra con Ultralytics, poi crea l'artefatto per la destinazione con gli strumenti AMD nelle rispettive immagini Docker Linux x86-64. Scegli la scheda corrispondente al tuo dispositivo:

Prepara la scheda con un progetto hardware e un'immagine Linux che includano la configurazione dell'acceleratore per cui hai compilato, oltre al runtime Vitis AI corrispondente. Consulta le guide di configurazione AMD per le destinazioni DPU Zynq UltraScale+ e Kria e Versal AI Edge (VEK280), quindi copia gli artefatti richiesti dal runtime:

Sulla DPU, i buffer VART contengono valori INT8 a virgola fissa: recupera la forma e la scala fix_point di ogni tensore, quantizza gli input e dequantizza gli output prima del post-processing. Graph Runner restituisce gli output del grafo completo, mentre un runner limitato alla DPU restituisce gli output intermedi dei sottografi DPU, che il tuo codice deve completare. VART-ML su VEK280 usa per impostazione predefinita viste hardware dei tensori, la cui forma, tipo di dati e layout di memoria possono differire dai layout ONNX; configura quindi i tipi dei tensori di input e output del runner come viste CPU oppure converti tu il formato hardware (consulta la panoramica dell'architettura VART-ML di AMD).

Applicazioni nel mondo reale#

I dispositivi AMD Xilinx sono comuni in tutti i contesti in cui l'IA visiva deve funzionare in tempo reale, a basso consumo e vicino al sensore:

• Sicurezza industriale e nei cantieri: rileva persone e macchinari intorno ad attrezzature pesanti e monitora le zone di lavoro con il rilevamento di oggetti e il conteggio degli oggetti.
• Visione per il settore automobilistico e i veicoli fuoristrada: esegui la percezione basata su telecamere su componenti qualificati per il settore automobilistico, a supporto dei veicoli autonomi e dei sistemi di assistenza alla guida.
• Telecamere intelligenti e analisi video: combina acquisizione video, codifica e inferenza YOLO su un unico chip per i sistemi di sicurezza e l'analisi video.
• Visione artificiale e controllo qualità: abbina l'acquisizione di immagini ad alta velocità basata su FPGA alla segmentazione delle istanze o alla classificazione YOLO per rilevare difetti in linea.
• Robotica e droni: usa i moduli Kria KR260 o Versal per la stima della posa, il rilevamento di oggetti orientati e la navigazione con latenza deterministica.

Riepilogo#

L'esportazione con format="xilinx" quantizza i modelli Ultralytics YOLO con AMD Quark per le NPU Versal AI Edge Series Gen 2, mantiene la testa in BF16 e salva la configurazione del compilatore Vitis AI accanto al modello. Convalida la precisione INT8 su qualsiasi host, compila il modello .rai nell'immagine Docker Vitis AI di AMD ed eseguilo sulla scheda con ONNX Runtime e Vitis AI Execution Provider.

I dispositivi AMD Xilinx meno recenti usano altri flussi. La DPU su Zynq UltraScale+ e Kria usa la toolchain Vitis AI 3.5, ormai congelata, e i file .xmodel; richiede attivazioni native della DPU, come Hard-Swish, ed esegue l'attenzione sulla CPU. La NPU Versal AI Edge di prima generazione usa il flusso snapshot, con copertura degli operatori che dipende dalla versione e dalla precisione di Vitis AI.

Per altre destinazioni di distribuzione, consulta la guida alle opzioni di distribuzione dei modelli, le best practice per la distribuzione e le integrazioni per acceleratori come Hailo, Rockchip RKNN e Axelera.

Domande frequenti#