Export AMD Xilinx pour Ultralytics YOLO avec Vitis AI#

L’export des modèles Ultralytics YOLO26 avec format="xilinx" les quantifie avec AMD Quark pour le NPU des SoC adaptatifs AMD Versal AI Edge Series Gen 2, afin que le compilateur Vitis AI d’AMD puisse créer un modèle .rai. Le même export vérifie la précision INT8 sur n’importe quel hôte avant le déploiement.

Les appareils AMD Xilinx équipent de nombreuses caméras industrielles, de nombreux systèmes de vision automobile, robots, drones et produits d’imagerie médicale dans le monde. Ils associent des processeurs Arm à une logique programmable et, sur les appareils les plus récents, à des AI Engines dédiés, si bien qu’une seule puce peut capturer une vidéo, la prétraiter, effectuer la détection d’objets et agir sur le résultat avec une latence d’inférence faible et prévisible.

Ce guide présente l’export AMD Xilinx, sa compilation et son exécution sur une carte Versal, les différentes familles d’appareils AMD Xilinx, leur fonctionnement avec l’IA et les opérateurs Ultralytics YOLO pris en charge par chaque accélérateur.

Qu'est-ce qu'AMD Xilinx ?#

Xilinx a inventé les réseaux logiques programmables (FPGA) dans les années 1980 et est devenu un fournisseur majeur de SoC adaptatifs et de FPGA. AMD a finalisé l'acquisition de Xilinx en février 2022, et les gammes de produits sont désormais commercialisées sous la marque AMD sous les noms AMD Zynq, AMD Kria, AMD Versal et AMD Vitis.

Termes et concepts clés#

Le déploiement sur AMD Xilinx utilise un vocabulaire qui lui est propre. Le tableau ci-dessous explique tous les termes employés dans ce guide.

Familles d'appareils AMD Xilinx pour l'IA en périphérie#

Les appareils AMD Xilinx destinés à l'IA en périphérie se répartissent en trois familles. Zynq et Kria utilisent la DPU dans la logique programmable, tandis que les appareils Versal AI Edge abordés ici utilisent le NPU sur leurs moteurs IA.

Zynq UltraScale+ MPSoC#

Chaque puce Zynq UltraScale+ associe une logique FPGA à un système de traitement Arm, doté de cœurs Cortex-A53 double cœur (CG) ou quadruple cœur (EG et EV) et de cœurs Cortex-R5F temps réel. Les appareils EV intègrent un codec vidéo H.264/H.265 câblé. Pour exécuter des réseaux neuronaux, les concepteurs intègrent une DPU à la logique, à côté de leurs pipelines caméra et vidéo. Sur les petits appareils, la DPU doit partager l'espace avec le reste de la conception.

Modules système Kria#

Le module Kria K26 regroupe un Zynq UltraScale+ MPSoC, de la mémoire et l'alimentation dans un module prêt pour la production. Tu n'as donc pas à concevoir toi-même le sous-système processeur, mémoire et alimentation. Le module se branche sur une carte porteuse, qu'il s'agisse d'une carte de kit de démarrage ou de ta propre conception. Il équipe le kit de démarrage Vision AI KV260 pour les caméras intelligentes et le kit de démarrage robotique KR260 pour la robotique. Comme le K26 repose sur Zynq UltraScale+, il utilise le même workflow DPU. La gamme Kria comprend également d'autres modules : vérifie donc le processeur utilisé par ton module avant de choisir un workflow.

SoC adaptatifs Versal#

Versal est la famille de SoC adaptatifs d'AMD. Les séries AI Edge et AI Core ajoutent des moteurs IA câblés aux côtés des cœurs Arm et de la logique programmable, tandis que certaines autres séries Versal ne comportent pas de moteurs IA. L'IP NPU d'AMD fonctionne conjointement sur les moteurs IA et la logique programmable, et Vitis AI cible les composants AIE-ML de la série AI Edge, tels que VE2302 et VE2802. La série Versal AI Edge (kit d'évaluation VEK280) et la série Versal AI Edge Gen 2 (kit d'évaluation VEK385) sont les cibles actuelles d'AMD pour l'IA en périphérie et le principal objectif des versions récentes de Vitis AI.

Fonctionnement de l'IA sur les appareils AMD Xilinx : DPU ou NPU#

La plupart des déploiements d'IA sur AMD Xilinx suivent le même principe. L'accélérateur exécute les couches qu'il prend en charge, le CPU Arm gère le prétraitement, le post-traitement et les couches que l'accélérateur ne peut pas exécuter, et un environnement d'exécution sur la carte coordonne les deux.

AMD a commercialisé deux générations d'accélérateurs, chacune avec sa propre chaîne d'outils et son propre fichier de modèle compilé. Ce guide s'appuie sur Vitis AI 3.5 pour la DPU et Vitis AI 6.3 pour le NPU ; consulte la documentation AMD actuelle pour les versions ultérieures.

Quel flux Vitis AI me faut-il ?#

Choisis le flux en fonction du composant de ta carte :

Exporter vers AMD Xilinx : convertir ton modèle YOLO#

Tâches prises en charge#

L’export AMD Xilinx prend en charge les sept tâches Ultralytics. La segmentation sémantique et l’estimation de profondeur sont uniquement disponibles avec YOLO26, la seule famille qui propose ces têtes.

Installation#

L’export AMD Xilinx s’exécute sous Linux (x86-64 ou ARM64) avec Python 3.11 à 3.13, les versions prises en charge par AMD Quark. Le premier export compile également les opérateurs personnalisés de Quark, ce qui nécessite un compilateur C++, comme g++.

# Install the required package for YOLO
pip install ultralytics

AMD Quark est installé automatiquement depuis PyPI lors du premier export. Pour installer au préalable les dépendances d’export :

pip install "ultralytics[export-xilinx]"

Pour installer le dépôt en mode éditable, remplace "ultralytics[export-xilinx]" par -e ".[export-base,export-xilinx]". Pour reproduire l’environnement Python 3.12 et l’export de vérification utilisés par CI, exécute le générateur d’environnement existant depuis la racine du dépôt :

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

Utilisation#

Le format AMD Xilinx prend en charge les modes Export, Predict et Validate. Sans le Vitis AI Execution Provider d’AMD, Predict et Validate exécutent le modèle quantifié sur le CPU avec ONNX Runtime, ce qui permet de mesurer sa précision INT8 sur n’importe quel hôte. Lorsque ONNX Runtime fournit VitisAIExecutionProvider, comme sur une carte Versal AI Edge Series Gen 2, Ultralytics le sélectionne automatiquement.

from ultralytics import YOLO

# Charger un modèle YOLO26
model = YOLO("yolo26n.pt")

# Exporter au format AMD Xilinx pour le VEK385 (quantize=8 est appliqué automatiquement)
model.export(format="xilinx")  # creates 'yolo26n_xilinx_model/'

from ultralytics import YOLO

# Charger le modèle AMD Xilinx exporté
model = YOLO("yolo26n_xilinx_model")

# Exécuter l’inférence
results = model("https://ultralytics.com/images/bus.jpg")

from ultralytics import YOLO

# Charger le modèle AMD Xilinx exporté
model = YOLO("yolo26n_xilinx_model")

# Valider la précision INT8 sur le jeu de données COCO8
metrics = model.val(data="coco8.yaml")

Les noms de format vitis, vitisai et versal sont des alias de xilinx.

Arguments d’exportation#

Définis nms=False pour exporter la tête sans NMS de YOLO26. La NMS intégrée (nms=True) n’est pas prise en charge, car AMD indique que NonMaxSuppression fait partie des opérateurs susceptibles de faire exécuter l’ensemble du modèle sur le CPU.

Pour en savoir plus sur le processus d’export, consulte la page de la documentation Ultralytics consacrée à l’export.

Structure de sortie#

Après un export réussi, un répertoire de modèle est créé avec la structure suivante :

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 compilation du modèle, décrite ci-dessous, ajoute un cache compilateur yolo26n/ dans le même répertoire. Il contient le modèle NPU yolo26n.rai et les rapports de compilation d’AMD, tels que final-vaiml-pass-summary.txt.

Fonctionnement de l’export#

L’export suit le workflow Vitis AI documenté par AMD pour Versal AI Edge Series Gen 2 :

1. Export ONNX avec l’opset 17 et une taille de lot statique de 1.
2. Quantification AMD Quark avec la configuration VINT8 (INT8 symétrique avec des échelles en puissances de deux) et les options exigées par AMD pour la compilation NPU : Int32Bias=False, enable_npu_cnn=True, DedicatedQDQPair=True et QuantizeAllOpTypes=True. L’étalonnage utilise le chargeur standard d’étalonnage INT8 d’Ultralytics, avec le même letterbox et le même prétraitement RGB et 0–1 que pour l’inférence.
3. Précision mixte : la tête du modèle reste en virgule flottante et le compilateur Vitis AI l’exécute en BF16 sur le NPU. La quantification de la tête en INT8 entraîne la majeure partie de la perte de précision, et le tutoriel YOLOv8m d’AMD exclut également sa partie post-traitement de l’INT8 pour cette même raison.
4. Configuration du compilateur : vitisai_config.json sélectionne la cible VAIML et l’appareil défini par name.

Précision#

Le tableau compare le modèle INT8 exporté au modèle ONNX FP32 sur l’ensemble val2017 de COCO (5 000 images) en 640, les deux étant exécutés avec ONNX Runtime sur le CPU de l’hôte. Les modèles INT8 ont été étalonnés sur le jeu de données par défaut coco128.yaml ; l’étalonnage sur tes propres images de déploiement réduit généralement l’écart.

Ces résultats sur l’hôte proviennent de l’exécution du modèle quantifié avec ONNX Runtime sur le CPU, la référence utilisée par la méthodologie de précision d’AMD pour comparer les résultats du NPU. Les résultats publiés par AMD pour YOLOv8m sur le VEK385 utilisent la même approche à précision mixte sur le NPU :

Source : tutoriel YOLOv8m pour Versal AI Edge Gen 2 d’AMD, qui indique également un temps d’inférence moyen de 10,69 ms sur 100 exécutions VART à dp_size=1.

Compiler et exécuter sur Versal AI Edge Gen 2#

Le répertoire exporté est prêt pour le compilateur Vitis AI d’AMD, qui crée le modèle .rai exécuté sur le NPU.

1. Prépare l’hôte et la carte. Effectue la compilation sur un hôte Linux x86-64 avec l’image Docker Vitis AI 6.3 d’AMD pour Versal AI Edge Gen 2 et une licence du compilateur AMD AI Engine (consulte la page des licences d’AMD). Configure le VEK385 à l’aide du guide de configuration de carte d’AMD.

2. Compile. Dans le conteneur, crée une session ONNX Runtime avec le Vitis AI Execution Provider, comme dans le guide de compilation d’AMD. La commande écrit le cache yolo26n/ contenant yolo26n.rai dans le répertoire d’export :

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

   Consulte yolo26n_xilinx_model/yolo26n/final-vaiml-pass-summary.txt pour connaître la part du modèle exécutée sur le NPU. Pour YOLO26n en 640, le compilateur Vitis AI 6.3 d’AMD place 99,9 % des opérateurs et des calculs sur le NPU VEK385 dans une seule partition.

3. Exécute sur la carte. Copie le répertoire d’export sur le VEK385. ONNX Runtime avec le Vitis AI Execution Provider charge le modèle compilé yolo26n.rai et l’exécute sur le NPU ; YOLO("yolo26n_xilinx_model") sélectionne automatiquement ce provider lorsqu’il est disponible.

La compilation ne nécessite que ONNX Runtime d’AMD ; tu peux donc effectuer l’export sur n’importe quelle machine Linux et copier le répertoire dans le conteneur plutôt que d’y installer Ultralytics, ce qui risque de modifier les packages dont les versions sont épinglées dans le conteneur. Lorsqu’Ultralytics est installé à côté de la version onnxruntime-vitisai d’AMD, comme sur la carte, il conserve cette version au lieu de la remplacer par onnxruntime standard.

Compatibilité des modèles YOLO et opérateurs pris en charge#

Un accélérateur n’accélère que les opérateurs qu’il implémente matériellement. Lorsqu’un modèle contient un opérateur non pris en charge, le compilateur délègue généralement cette partie du réseau au CPU Arm, et chaque aller-retour entre l’accélérateur et le CPU ajoute de la latence. Certains opérateurs ne peuvent pas être partitionnés : sur la NPU Versal AI Edge Gen 2, AMD répertorie des opérateurs comme NonZero et NonMaxSuppression qui peuvent contraindre l’ensemble du modèle à s’exécuter sur le CPU. La prise en charge des opérateurs est le facteur le plus important pour les performances d’un modèle YOLO sur le matériel AMD Xilinx.

Le tableau indique où s’exécute chaque opérateur d’un modèle YOLO26. Un export ONNX standard de YOLO26n contient 87 activations SiLU, chacune exportée sous la forme d’un Sigmoid et d’un Mul, ainsi que 4 opérateurs MatMul et 2 opérateurs Softmax issus de ses deux blocs d’attention : le bloc C2PSA à la fin du backbone (couche 10) et le bloc C3k2 avec attention qui produit la sortie P5 (couche 22).

Sources : opérateurs pris en charge UG1414 d’AMD, prise en charge des opérateurs PyTorch et listes d’opérateurs pris en charge, partition CPU et non pris en charge pour Versal AI Edge Gen 2. La prise en charge dépend aussi de ta configuration DPU et des motifs du graphe ; vérifie donc toujours le rapport de partition du compilateur.

Rendre YOLO26 compatible avec la DPU grâce à Hard-Swish#

La DPU ne fusionne dans ses convolutions que ReLU, ReLU6, LeakyReLU, Hard-Swish et Hard-Sigmoid. Hard-Swish est une approximation de SiLU adaptée au matériel, ce qui en fait son remplacement naturel. Les fichiers YAML de modèles Ultralytics acceptent une clé activation qui modifie l’activation par défaut des blocs Conv (Guide de configuration YAML des modèles).

Copie yolo26.yaml vers yolo26-hswish.yaml, puis ajoute une ligne sous les paramètres :

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

Construis ensuite le modèle, transfère les poids YOLO26 préentraînés et affine le modèle sur ton jeu de données :

from ultralytics import YOLO

# Construire YOLO26n avec des activations Hard-Swish ; le « n » du nom indique l’échelle nano
model = YOLO("yolo26n-hswish.yaml").load("yolo26n.pt")  # transférer les poids préentraînés

# Affiner le modèle pour que le réseau s’adapte à Hard-Swish
model.train(data="coco8.yaml", epochs=100, imgsz=640)

Les activations n’ont pas de poids, donc tous les poids préentraînés sont transférés. Le graphe ONNX exporté contient alors 87 opérateurs HardSwish et aucun SiLU. Remplace coco8.yaml par ton propre jeu de données, puis compare la précision au modèle SiLU avec le mode Val avant le déploiement.

Gérer les blocs d’attention sur la DPU#

YOLO26 applique l’attention à la résolution la plus basse (une grille de 20 × 20 pour une entrée de 640) à deux endroits : le bloc C2PSA à la couche 10 et le bloc C3k2 avec attention à la couche 22. YOLO11 comporte un seul bloc C2PSA. Sur une DPU, ses opérateurs MatMul et Softmax s’exécutent sur le CPU, ce qui divise le modèle en sous-graphes alternant entre DPU et CPU. Tu as trois possibilités :

1. Accepter les blocs CPU. Le .xmodel compilé contient alors des sous-graphes CPU. Exécute-le avec le Graph Runner d’AMD, qui exécute ensemble les sous-graphes DPU et CPU lorsqu’une implémentation CPU existe pour chaque opérateur ; sinon, tu dois implémenter et enregistrer les opérateurs manquants. À 20 × 20, le calcul d’attention est léger, mais chaque transfert supplémentaire entre la DPU et le CPU ajoute de la latence ; mesure donc les performances sur ta carte.

2. Utiliser un YAML sans attention. Dans ton YAML Hard-Swish, remplace la couche C2PSA par nn.Identity pour que les indices de couche utilisés par Concat et Detect restent valides, puis désactive l’attention dans la couche 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)

   Le graphe ONNX exporté ne contient alors aucun opérateur MatMul ni Softmax. Les poids d’attention ne sont plus applicables (624 des 666 poids de YOLO26n sont transférés) ; affine donc le modèle plus longtemps et compare la précision avec le mode Val.

3. Utiliser un modèle sans attention, comme YOLOv8, qu’AMD a utilisé dans ses propres exemples DPU.

Sur Versal AI Edge Gen 2, les opérateurs d’attention sont répertoriés comme pris en charge par la NPU ; ces modifications sont donc généralement inutiles. Vérifie leur emplacement dans le rapport du compilateur, car AMD précise que des opérateurs pris en charge peuvent tout de même basculer sur le CPU en raison de contraintes de configuration ou de mémoire.

Compatibilité des modèles en un coup d’œil#

Déployer sur d’autres cibles AMD Xilinx#

Les DPU Zynq UltraScale+ et Kria, ainsi que le NPU Versal AI Edge de première génération, utilisent des workflows Vitis AI que format="xilinx" ne produit pas. Entraîne ton modèle avec Ultralytics, puis crée l’artefact cible avec les outils AMD dans leurs images Docker Linux x86-64. Choisis l’onglet correspondant à ton appareil :

Prépare la carte avec une conception matérielle et une image Linux qui intègrent la configuration de l’accélérateur pour laquelle tu as compilé, ainsi que l’environnement d’exécution Vitis AI correspondant. Consulte les guides de configuration AMD pour les cibles DPU Zynq UltraScale+ et Kria et Versal AI Edge (VEK280), puis copie les artefacts nécessaires à ton environnement d’exécution :

Sur le DPU, les tampons VART contiennent des valeurs INT8 en virgule fixe : récupère la forme et l’échelle fix_point de chaque tenseur, quantifie les entrées et déquantifie les sorties avant le post-traitement. Graph Runner renvoie les sorties du graphe complet, tandis qu’un exécuteur DPU seul renvoie les sorties des sous-graphes intermédiaires du DPU, que ton code doit compléter. VART-ML sur le VEK280 utilise par défaut des vues de tenseurs matérielles dont la forme, le type de données et la disposition mémoire peuvent différer des dispositions ONNX. Configure donc les types de tenseurs d’entrée et de sortie de l’exécuteur en vues CPU, ou convertis toi-même le format matériel (consulte la présentation de l’architecture VART-ML d’AMD).

Applications concrètes#

Les appareils AMD Xilinx sont courants dans les cas où l’IA visuelle doit fonctionner en temps réel, avec une faible consommation et à proximité du capteur :

• Sécurité industrielle et dans la construction : détecte les personnes et les machines à proximité d’équipements lourds, et surveille les zones de travail grâce à la détection d’objets et au comptage d’objets.
• Vision automobile et hors route : exécute la perception par caméra sur des composants homologués pour l’automobile, au service des véhicules autonomes et de l’aide à la conduite.
• Caméras intelligentes et analyse vidéo : combine la capture vidéo, l’encodage et l’inférence YOLO sur une seule puce pour les systèmes de sécurité et l’analyse vidéo.
• Vision industrielle et contrôle qualité : associe l’acquisition d’images à grande vitesse basée sur FPGA à YOLO pour la segmentation d’instances ou la classification afin de détecter les défauts en ligne.
• Robotique et drones : utilise les modules Kria KR260 ou Versal pour l’estimation de pose, la détection d’objets orientés et la navigation avec une latence déterministe.

Résumé#

L’export avec format="xilinx" quantifie les modèles Ultralytics YOLO avec AMD Quark pour les NPU Versal AI Edge Series Gen 2, conserve la tête en BF16 et place la configuration du compilateur Vitis AI à côté du modèle. Vérifie la précision INT8 sur n’importe quel hôte, compile le modèle .rai dans l’image Docker Vitis AI d’AMD, puis exécute-le sur la carte avec ONNX Runtime et le Vitis AI Execution Provider.

Les anciens appareils AMD Xilinx utilisent d’autres workflows. Le DPU des Zynq UltraScale+ et Kria utilise la chaîne d’outils figée Vitis AI 3.5 et les fichiers .xmodel, nécessite des activations propres au DPU comme Hard-Swish et exécute l’attention sur le CPU. Le NPU Versal AI Edge de première génération utilise le workflow snapshot, dont la couverture des opérateurs dépend de la version et de la précision de Vitis AI.

Pour d’autres cibles de déploiement, consulte le guide des options de déploiement des modèles, les bonnes pratiques de déploiement et les intégrations d’accélérateurs comme Hailo, Rockchip RKNN et Axelera.

FAQ#