Export Ambarella CVflow pour les modèles YOLO Ultralytics#

Le déploiement de modèles Ultralytics YOLO sur les SoC Ambarella nécessite la compilation des modèles avec les outils de compilation Ambarella. Les modèles optimisés pour l’architecture CVflow offrent de meilleures performances à l’inférence. Ce fork d’Ultralytics intègre directement la boîte à outils de compression SpongeTorch d’Ambarella au pipeline d’entraînement, de validation et d’export, afin de permettre aux développeurs de générer des modèles optimisés pour un déploiement efficace sur du matériel Ambarella.

Ce guide présente le workflow actuel de déploiement de la détection d’objets, de l’entraînement tenant compte de la compression à l’inférence sur l’appareil (consulte la présentation du workflow pour découvrir le pipeline complet).

Le format de checkpoint AmbaPB est une extension propre à Ambarella de la spécification ONNX IR. Il prend en charge les primitives de calcul CVflow et regroupe les artefacts générés par les outils du SDK. Cet artefact côté hôte sert à valider la précision du modèle compilé avant le déploiement ; le binaire Cavalry distinct, produit pour l’appareil cible, est celui qui s’exécute sur la carte.

Qu’est-ce qu’Ambarella ?#

Ambarella, dont le siège social se trouve à Santa Clara, en Californie, est une entreprise de semi-conducteurs qui conçoit des SoC d’IA en périphérie. Ses processeurs combinent le traitement du signal d’image, l’encodage vidéo et le calcul d’IA sur puce. Ils sont utilisés dans des appareils de sécurité, automobiles, robotiques, industriels et grand public.

Qu’est-ce que CVflow ?#

CVflow est l’architecture de traitement de la vision d’Ambarella. Elle utilise un moteur de vision dédié, distinct du CPU et du GPU, pour exécuter des charges de travail de vision par ordinateur et de réseaux neuronaux. Les modèles entraînés avec des frameworks comme PyTorch sont compilés au format natif CVflow avec le SDK Ambarella avant leur exécution sur le moteur.

Familles de SoC CVflow actuelles et leurs applications courantes :

Pourquoi déployer YOLO sur Ambarella ?#

• Performance par watt : les SoC CVflow sont conçus pour l’IA en périphérie fonctionnant en continu et exécutent la détection d’objets en temps réel dans les limites de consommation des caméras.
• Entraînement tenant compte de la compression : SpongeTorch applique un élagage pendant l’entraînement pour aider le modèle à conserver sa précision tout en devenant plus creux et plus efficace pour le déploiement sur CVflow.
• Pipeline de caméra intégré : les SoC Ambarella combinent un processeur de signal d’image (ISP), l’encodage vidéo ultra-haute définition et CVflow pour prendre en charge divers systèmes de caméras à faible consommation. Un seul SoC Ambarella gère ainsi l’ensemble du pipeline de caméra IA.

Présentation du workflow#

Le pipeline comporte six étapes :

1. Entraînement tenant compte de la compression — entraîne le modèle avec une configuration SpongeKit (amba_config) afin que SpongeTorch applique progressivement un élagage non structuré pendant l’entraînement. Lorsque la précision obtenue par la quantification après entraînement (PTQ) n’est pas satisfaisante, SpongeTorch prend également en charge l’entraînement tenant compte de la quantification (QAT), mais cette méthode n’est pas encore intégrée à cette intégration Ultralytics et est prévue pour une prochaine version.
2. Export ONNX — exporte le checkpoint compressé avec le même amba_config, en conservant la structure de compression dans le graphe ONNX.
3. Compilation — compile le modèle ONNX en checkpoint AmbaPB avec les outils de compilation du SDK, qui appliquent la PTQ pour le moteur CVflow.
4. Validation sur hôte — exécute le modèle compilé *.ambapb.ckpt.onnx via le backend AmbaPB à l’aide de predict/val d’Ultralytics pour vérifier sa précision avant le déploiement.
5. Conversion Cavalry — convertis le checkpoint AmbaPB validé en binaire Cavalry avec les outils du SDK.
6. Exécution sur l’appareil — exécute le binaire Cavalry sur l’appareil avec la bibliothèque d’exécution du SDK Ambarella.

Le workflow d’entraînement et d’export SpongeTorch est facultatif et peut être remplacé par un export ONNX standard (voir Exporter sans SpongeTorch).

Prérequis#

Installation#

Installe ce fork d’Ultralytics, puis configure le SDK Ambarella CVflow — qui comprend les outils de compilation et la bibliothèque cvflowbackend — et installe la wheel spongetorch distribuée avec celui-ci :

# Install this Ultralytics fork from source
git clone https://github.com/Ambarella-Inc/ultralytics
cd ultralytics
git checkout amba_v8.4.46
pip install -e .

# Access and set up the Ambarella SDK compilation tools
# After the environment is ready, install the spongetorch library
pip install /path/to/spongetorch-*.whl

AutoBackend trouve cvflowbackend via la commande tv2 des outils de compilation du SDK (tv2 -libpath cvflowbackend). Les outils de compilation du SDK doivent donc être installés et présents dans ton PATH avant l’exécution de l’inférence ou de la validation avec des modèles compilés.

Fichier de configuration SpongeKit#

SpongeTorch s’appuie sur un fichier de configuration SpongeKit (format protobuf-text, .prototxt) qui définit les étapes d’élagage, notamment les objectifs de parcimonie et le calendrier de compression. Récupère des exemples de configuration et la documentation du schéma correspondant dans la version de ton SDK Ambarella. Pour assurer la cohérence entre l’entraînement, la validation et le déploiement, utilise la configuration d’entraînement chaque fois que la validation doit préparer à nouveau le modèle, et utilise toujours la même configuration pour exporter un checkpoint compressé.

Arguments Amba#

Deux arguments contrôlent l’intégration de SpongeTorch dans les modes train, val et export :

Le fork ajoute également un argument d’export général :

Entraînement tenant compte de la compression#

Entraîne ton modèle (ou ajuste-le) avec la compression SpongeTorch activée :

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.train(
    data="coco8.yaml",
    epochs=100,
    amba_config="config.prototxt",
    amba_chipset="CV72",
)

Lorsque amba_config est défini, l’entraîneur encapsule le modèle et l’optimiseur avec spongetorch.prepare() lors de la configuration. La compression est appliquée progressivement selon un calendrier d’étapes, afin que le réseau apprenne à conserver sa précision tout en devenant parcimonieux. Le checkpoint entraîné stocke l’état parcimonieux de SpongeTorch (tenseurs _orig/_mask), nécessaire à l’étape d’export. Le fichier de configuration est copié dans le répertoire d’exécution sous le nom amba_config.prototxt pour assurer la reproductibilité.

Validation du checkpoint compressé#

Valide la précision avant la compilation en utilisant la même configuration :

yolo val model=runs/detect/train/weights/best.pt data=coco8.yaml \
  amba_config=config.prototxt amba_chipset=CV72

Le validateur réapplique spongetorch.prepare() si nécessaire et désactive la fusion Conv+BN pour préserver la structure de compression. Compare la mAP à celle de ta référence non compressée ; si la baisse de précision est trop importante, ajuste la configuration SpongeKit et entraîne à nouveau le modèle.

Exporter vers ONNX#

Exporte le checkpoint compressé avec la même configuration amba_config que celle utilisée pour l’entraînement :

from ultralytics import YOLO

model = YOLO("runs/detect/train/weights/best.pt")
model.export(
    format="onnx",
    amba_config="config.prototxt",
    amba_chipset="CV72",
)

L’exporteur reconstruit le modèle, réapplique spongetorch.prepare() avec ta configuration, recharge les poids du checkpoint parcimonieux dans la structure préparée et effectue le traçage vers ONNX avec la fusion Conv+BN désactivée. Le graphe obtenu est ainsi exactement au format attendu par les outils de compilation du SDK.

Conserver les métadonnées du modèle#

L’export ONNX intègre dans le fichier ONNX la tâche du modèle, les noms des classes, le stride et la taille d’entrée, tandis que le backend AmbaPB lit ces informations dans un fichier annexe metadata.yaml placé à côté du modèle compilé. À moins que tes outils de compilation du SDK ne créent ce fichier annexe, extrais-le du modèle ONNX avant la compilation :

import onnx

from ultralytics.utils import YAML

model = onnx.load("model.onnx")
YAML.save("metadata.yaml", {item.key: item.value for item in model.metadata_props})

Conserve metadata.yaml dans le même répertoire que le fichier compilé *.ambapb.ckpt.onnx ou *.ambapb.fastckpt.onnx.

Compiler avec les outils SDK#

Compile le modèle ONNX exporté pour ton jeu de puces cible à l’aide des outils de compilation du SDK, en suivant le guide de compilation du SDK. Les outils projettent le graphe sur le moteur d’IA CVflow — en appliquant la PTQ, la planification et la gestion de la mémoire — et produisent le point de contrôle AmbaPB pour la validation sur l’hôte.

La PTQ applique une quantification INT8 à l’aide d’images d’étalonnage (préparées comme indiqué dans le guide de compilation du SDK), et les outils de compilation équilibrent la précision et la latence à l’exécution : affecter davantage d’opérations à INT8 réduit la latence, mais peut diminuer la précision, tandis que conserver davantage d’opérations en FP16 préserve la précision au prix d’une latence supérieure. Lorsque la PTQ ne permet pas d’atteindre ton objectif de précision au niveau INT8 requis par ton budget de latence, la QAT avec SpongeTorch est la solution prévue : elle entraîne le modèle à tolérer une quantification INT8 plus agressive, ce qui permet de récupérer de la précision avec un point de fonctionnement à latence plus faible. La QAT n’est pas encore disponible dans cette intégration et est prévue pour une version ultérieure.

Exécuter l’inférence avec le modèle compilé#

Le modèle AmbaPB compilé se charge directement via l’API Ultralytics — AutoBackend détecte le suffixe .ambapb et achemine l’inférence via cvflowbackend, en exécutant le modèle comme il le sera sur le moteur d’IA :

from ultralytics import YOLO

model = YOLO("model.ambapb.ckpt.onnx")

# Inference
results = model("https://ultralytics.com/images/bus.jpg")

# Validation
metrics = model.val(data="coco8.yaml")

Il s’agit de la vérification finale de la précision avant le déploiement matériel, en tenant compte de tous les effets de quantification du compilateur. Si un fichier metadata.yaml se trouve à côté du modèle compilé, le backend en lit les noms de classes, le pas et les informations sur la tâche. Par défaut, le backend utilise le mode d’inférence CVflow acinf ; définis la variable d’environnement ULTRALYTICS_AMBAPB_DEBUG=1 pour consigner les détails des entrées et sorties à des fins de débogage.

Convertir en binaire Cavalry#

Une fois que le point de contrôle AmbaPB a passé la validation sur l’hôte, utilise les outils de compilation du SDK pour le convertir en binaire Cavalry adapté à ton appareil cible, en suivant le guide de compilation du SDK. Le binaire Cavalry est le format exécuté par la bibliothèque d’exécution du SDK sur la carte.

Déployer sur la carte#

Charge le binaire Cavalry sur ton appareil Ambarella à l’aide de l’environnement d’exécution du SDK Ambarella. Le prétraitement et le post-traitement doivent correspondre à ce pour quoi le modèle de détection a été compilé : une entrée RGB avec letterboxing dans la plage 0–255, et le décodage standard des détections YOLO sur les sorties. Consulte la documentation de déploiement du SDK pour les API d’exécution.

Exporter sans SpongeTorch#

Si tu n’as pas besoin de l’élagage de SpongeTorch pendant l’entraînement, le pipeline standard d’Ultralytics produit également un modèle que les outils SDK peuvent compiler :

yolo export model=yolo26n.pt format=onnx

Compile le fichier ONNX obtenu avec les outils de compilation du SDK, qui effectuent eux-mêmes la quantification après entraînement. Cette approche sacrifie une partie des performances à l’exécution et de la précision quantifiée au profit d’un flux de travail plus simple, sans dépendance à spongetorch au moment de l’entraînement.

Applications concrètes#

Les modèles Ultralytics YOLO sur les SoC Ambarella CVflow assurent une vision toujours active en périphérie :

• Caméras de sécurité IA : détection en temps réel de personnes et de véhicules sur des caméras IP 4K avec une consommation inférieure à 3 W.
• Drones et robotique : détection et suivi d’objets embarqués pour la navigation, l’inspection et la livraison sur des puces de classe CV5.
• Analyse industrielle et commerciale : comptage de personnes sur plusieurs flux, détection des EPI et surveillance des rayons sur des équipements périphériques.

Résumé#

Ce guide a présenté le flux de travail actuel pour déployer des modèles Ultralytics YOLO sur les SoC Ambarella CVflow : entraînement tenant compte de la compression avec SpongeTorch (amba_config/amba_chipset), exportation ONNX du point de contrôle compressé, compilation hors ligne en point de contrôle AmbaPB avec les outils SDK, validation sur l’hôte via Ultralytics et conversion en binaire Cavalry pour le déploiement sur l’appareil avec le SDK Ambarella.

Pour d’autres cibles d’IA en périphérie, consulte les guides Hailo, Rockchip RKNN, Sony IMX500, Qualcomm QNN, DEEPX et Axelera. Pour consulter la liste complète des formats d’exportation, visite la documentation du mode Export et la page des intégrations.

FAQ#