Exportación de AMD Xilinx para Ultralytics YOLO con Vitis AI#

Al exportar modelos Ultralytics YOLO26 con format="xilinx", se cuantizan con AMD Quark para la NPU de los SoC adaptativos AMD Versal AI Edge Series Gen 2, listos para que el compilador Vitis AI de AMD genere un modelo .rai. La misma exportación valida la precisión INT8 en cualquier equipo antes de la implementación.

Los dispositivos de AMD Xilinx impulsan muchas de las cámaras industriales, los sistemas de visión para automoción, los robots, los drones y los productos de diagnóstico por imagen del mundo. Combinan procesadores Arm con lógica programable y, en los dispositivos más recientes, motores de AI dedicados, de modo que un solo chip puede capturar vídeo, preprocesarlo, ejecutar la detección de objetos y actuar en función del resultado con una latencia de inferencia baja y predecible.

Esta guía explica la exportación de AMD Xilinx, cómo compilarla y ejecutarla en una placa Versal, qué es cada familia de dispositivos AMD Xilinx, cómo se ejecuta la IA en ellos y qué operadores de Ultralytics YOLO admite cada acelerador.

¿Qué es AMD Xilinx?#

Xilinx inventó la matriz de puertas programable en campo (FPGA) en la década de 1980 y se convirtió en uno de los principales proveedores de SoC adaptables y FPGA. AMD completó la adquisición de Xilinx en febrero de 2022, y ahora las líneas de productos se comercializan bajo la marca AMD como AMD Zynq, AMD Kria, AMD Versal y AMD Vitis.

Términos y conceptos clave#

La implementación en AMD Xilinx utiliza su propio vocabulario. En la siguiente tabla se explica cada término utilizado en esta guía.

Familias de dispositivos AMD Xilinx para IA en el extremo#

Los dispositivos AMD Xilinx para IA en el extremo se dividen en tres familias. Zynq y Kria utilizan la DPU en lógica programable, mientras que los dispositivos Versal AI Edge que se tratan aquí utilizan la NPU en sus motores de IA.

Zynq UltraScale+ MPSoC#

Cada chip Zynq UltraScale+ combina un sistema de procesamiento Arm, con núcleos Cortex-A53 de doble núcleo (CG) o cuádruple núcleo (EG y EV) y núcleos Cortex-R5F en tiempo real, con lógica FPGA. Los dispositivos EV añaden un códec de vídeo H.264/H.265 integrado. Para ejecutar redes neuronales, los diseñadores integran una DPU en la lógica, junto a los canales de procesamiento de vídeo y cámara. En los dispositivos pequeños, la DPU compite por espacio con el resto del diseño.

Módulos en sistema Kria#

El módulo Kria K26 integra un Zynq UltraScale+ MPSoC, memoria y alimentación en un módulo listo para producción, para que no tengas que diseñar por tu cuenta el procesador, la memoria ni el subsistema de alimentación. El módulo se conecta a una placa portadora, ya sea la placa de un kit de iniciación o un diseño propio. Es la base del kit de iniciación KV260 Vision AI para cámaras inteligentes y del kit de iniciación KR260 Robotics para robótica. Como el K26 se basa en Zynq UltraScale+, utiliza el mismo flujo de trabajo DPU. La gama Kria también incluye otros módulos, así que comprueba qué procesador utiliza tu módulo antes de elegir un flujo de trabajo.

SoC adaptables Versal#

Versal es la familia de SoC adaptables de AMD. Las series AI Edge y AI Core incorporan motores de IA integrados junto a los núcleos Arm y la lógica programable, mientras que algunas otras series Versal no tienen motores de IA. La IP de NPU de AMD se ejecuta conjuntamente en los motores de IA y la lógica programable, y Vitis AI está dirigido a los componentes AIE-ML de la serie AI Edge, como VE2302 y VE2802. La serie Versal AI Edge (kit de evaluación VEK280) y la serie Versal AI Edge Gen 2 (kit de evaluación VEK385) son los destinos actuales de AMD para la IA en el extremo y el foco de las versiones actuales de Vitis AI.

Cómo se ejecuta la IA en los dispositivos AMD Xilinx: DPU frente a NPU#

La mayoría de las implementaciones de IA en AMD Xilinx siguen el mismo patrón. El acelerador ejecuta las capas que admite; la CPU Arm se encarga del preprocesamiento, el posprocesamiento y las capas que el acelerador no puede ejecutar; y un entorno de ejecución en la placa coordina ambos.

AMD ha lanzado dos generaciones de aceleradores, cada una con su propia cadena de herramientas y archivo de modelo compilado. Esta guía utiliza Vitis AI 3.5 para la DPU y Vitis AI 6.3 para la NPU; consulta la documentación actual de AMD para las versiones posteriores.

¿Qué flujo de Vitis AI necesito?#

Elige el flujo según el dispositivo de tu placa:

Exportación a AMD Xilinx: conversión de tu modelo YOLO#

Tareas compatibles#

La exportación de AMD Xilinx admite las siete tareas de Ultralytics. La segmentación semántica y la estimación de profundidad solo están disponibles con YOLO26, la única familia que incluye esos cabezales.

Instalación#

La exportación de AMD Xilinx se ejecuta en Linux (x86-64 o ARM64) con Python 3.11 a 3.13, las versiones compatibles con AMD Quark. La primera exportación también compila los operadores personalizados de Quark, para lo que se necesita un compilador de C++, como g++.

# Install the required package for YOLO
pip install ultralytics

AMD Quark se instala automáticamente desde PyPI durante la primera exportación. Para instalar previamente las dependencias de exportación:

pip install "ultralytics[export-xilinx]"

Para instalar el repositorio en modo editable, sustituye "ultralytics[export-xilinx]" por -e ".[export-base,export-xilinx]". Para reproducir el entorno de Python 3.12 y la exportación de prueba utilizados por CI, ejecuta el generador de entornos existente desde la raíz del repositorio:

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

Uso#

El formato AMD Xilinx admite los modos Exportar, Predecir y Validar. Sin el proveedor de ejecución Vitis AI de AMD, los modos de predicción y validación ejecutan el modelo cuantizado con ONNX Runtime en la CPU, lo que permite medir su precisión INT8 en cualquier equipo. Cuando ONNX Runtime proporciona VitisAIExecutionProvider, como ocurre en una placa Versal AI Edge Series Gen 2, Ultralytics lo selecciona automáticamente.

from ultralytics import YOLO

# Carga un modelo YOLO26
model = YOLO("yolo26n.pt")

# Exportar al formato AMD Xilinx para VEK385 (quantize=8 se aplica automáticamente)
model.export(format="xilinx")  # creates 'yolo26n_xilinx_model/'

from ultralytics import YOLO

# Cargar el modelo AMD Xilinx exportado
model = YOLO("yolo26n_xilinx_model")

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

from ultralytics import YOLO

# Cargar el modelo AMD Xilinx exportado
model = YOLO("yolo26n_xilinx_model")

# Validar la precisión INT8 con el conjunto de datos COCO8
metrics = model.val(data="coco8.yaml")

Los nombres de formato vitis, vitisai y versal son alias de xilinx.

Argumentos de exportación#

Establece nms=False para exportar el cabezal YOLO26 sin NMS. NMS integrado (nms=True) no es compatible porque AMD incluye NonMaxSuppression entre los operadores que pueden hacer que todo el modelo se ejecute en la CPU.

Para obtener más información sobre el proceso de exportación, visita la página de documentación de Ultralytics sobre exportación.

Estructura de salida#

Tras una exportación correcta, se crea un directorio del modelo con la siguiente estructura:

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

Al compilar el modelo, tal como se describe a continuación, se añade una caché del compilador yolo26n/ al mismo directorio, que contiene el modelo NPU yolo26n.rai y los informes de compilación de AMD, como final-vaiml-pass-summary.txt.

Cómo funciona la exportación#

La exportación sigue el flujo Vitis AI documentado por AMD para Versal AI Edge Series Gen 2:

1. Exportación ONNX con opset 17 y un tamaño de lote estático de 1.
2. Cuantización con AMD Quark mediante la configuración VINT8 (INT8 simétrico con escalas de potencias de dos) y las opciones que AMD requiere para compilar en la NPU: Int32Bias=False, enable_npu_cnn=True, DedicatedQDQPair=True y QuantizeAllOpTypes=True. La calibración usa el cargador estándar de calibración INT8 de Ultralytics, con el mismo letterbox y el mismo preprocesamiento RGB y de 0–1 que la inferencia.
3. Precisión mixta: el cabezal del modelo se mantiene en coma flotante y el compilador Vitis AI lo ejecuta en BF16 en la NPU. Cuantizar el cabezal a INT8 provoca la mayor parte de la pérdida de precisión, y el tutorial de YOLOv8m de AMD mantiene su etapa de posprocesamiento fuera de INT8 por el mismo motivo.
4. Configuración del compilador: vitisai_config.json selecciona el destino VAIML y el dispositivo de name.

Precisión#

La tabla compara el modelo INT8 exportado con el modelo ONNX FP32 en COCO val2017 (5000 imágenes) a 640; ambos se ejecutan con ONNX Runtime en la CPU del equipo. Los modelos INT8 se calibraron con el conjunto de datos predeterminado coco128.yaml; calibrar con tus propias imágenes de implementación suele reducir la diferencia.

Estos resultados en el equipo ejecutan el modelo cuantizado con ONNX Runtime en la CPU, que es la referencia frente a la que AMD compara los resultados de su metodología de precisión en la NPU. Los resultados publicados por AMD para YOLOv8m en VEK385 muestran el mismo enfoque de precisión mixta en la NPU:

Fuente: tutorial de YOLOv8m para Versal AI Edge Gen 2 de AMD, que también informa de un tiempo medio de inferencia de 10,69 ms en 100 ejecuciones de VART con dp_size=1.

Compilar y ejecutar en Versal AI Edge Gen 2#

El directorio exportado está listo para el compilador Vitis AI de AMD, que genera el modelo .rai que se ejecuta en la NPU.

1. Prepara el equipo y la placa. Compila en un equipo host Linux x86-64 con la imagen Docker Vitis AI 6.3 para Versal AI Edge Gen 2 de AMD y una licencia del compilador AMD AI Engine (consulta la página de licencias de AMD). Configura el VEK385 con la guía de configuración de la placa de AMD.

2. Compila. Dentro del contenedor, crea una sesión de ONNX Runtime con el proveedor de ejecución Vitis AI, usando la misma llamada que en la guía de compilación de AMD. Escribe la caché yolo26n/ con yolo26n.rai en el directorio de exportación:

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

   Comprueba yolo26n_xilinx_model/yolo26n/final-vaiml-pass-summary.txt para ver qué parte del modelo se ejecuta en la NPU. Para YOLO26n a 640, el compilador Vitis AI 6.3 de AMD coloca el 99,9 % de los operadores y del cálculo en la NPU VEK385, en una sola partición.

3. Ejecuta en la placa. Copia el directorio de exportación al VEK385. ONNX Runtime con el proveedor de ejecución Vitis AI carga el yolo26n.rai compilado y lo ejecuta en la NPU; YOLO("yolo26n_xilinx_model") selecciona automáticamente este proveedor cuando está disponible.

La compilación solo necesita ONNX Runtime de AMD, así que puedes exportar en cualquier máquina Linux y copiar el directorio al contenedor en lugar de instalar allí Ultralytics, lo que podría cambiar los paquetes fijados del contenedor. Cuando Ultralytics está instalado junto a la versión onnxruntime-vitisai de AMD, como en la placa, conserva esa versión en lugar de sustituirla por la versión estándar onnxruntime.

Compatibilidad de modelos YOLO y operadores compatibles#

Un acelerador solo acelera los operadores que implementa en el hardware. Cuando un modelo contiene un operador no compatible, el compilador suele enviar esa parte de la red a la CPU Arm, y cada ida y vuelta entre el acelerador y la CPU añade latencia. Algunos operadores no se pueden particionar: en la NPU Versal AI Edge Gen 2, AMD enumera operadores como NonZero y NonMaxSuppression que pueden obligar a ejecutar todo el modelo en la CPU. La compatibilidad con operadores es el factor más importante para el rendimiento de un modelo YOLO en el hardware AMD Xilinx.

La tabla muestra dónde se ejecuta cada operador de un modelo YOLO26. Una exportación estándar de YOLO26n a ONNX contiene 87 activaciones SiLU, cada una exportada como Sigmoid y Mul, además de 4 operadores MatMul y 2 operadores Softmax de sus dos bloques de atención: el bloque C2PSA al final del backbone (capa 10) y el bloque C3k2 con atención que genera la salida P5 (capa 22).

Fuentes: operadores compatibles según UG1414 de AMD, compatibilidad con operadores de PyTorch y listas de operadores compatibles, particionados en la CPU y no compatibles de Versal AI Edge Gen 2. La compatibilidad también depende de la configuración de la DPU y de los patrones del grafo, así que consulta siempre el informe de particiones del compilador.

Prepara YOLO26 para la DPU con Hard-Swish#

La DPU solo fusiona ReLU, ReLU6, LeakyReLU, Hard-Swish y Hard-Sigmoid con sus convoluciones. Hard-Swish es una aproximación de SiLU adaptada al hardware, por lo que es el sustituto natural. Los archivos YAML de modelo de Ultralytics aceptan una clave activation que cambia la activación predeterminada de los bloques Conv (Guía de configuración de YAML de modelos).

Copia yolo26.yaml en yolo26-hswish.yaml y añade una línea bajo los parámetros:

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

A continuación, crea el modelo, transfiere los pesos preentrenados de YOLO26 y ajústalo con tu conjunto de datos:

from ultralytics import YOLO

# Crea YOLO26n con activaciones Hard-Swish; la «n» del nombre selecciona la escala nano
model = YOLO("yolo26n-hswish.yaml").load("yolo26n.pt")  # transferir pesos preentrenados

# Ajusta el modelo para que la red se adapte a Hard-Swish
model.train(data="coco8.yaml", epochs=100, imgsz=640)

Las activaciones no tienen pesos, así que se transfieren todos los pesos preentrenados. El grafo ONNX exportado contiene entonces 87 operadores HardSwish y ningún SiLU. Sustituye coco8.yaml por tu propio conjunto de datos y compara la precisión con la del modelo SiLU mediante el modo Val antes de implementarlo.

Gestión de los bloques de atención en la DPU#

YOLO26 aplica atención en la resolución más baja (una cuadrícula de 20×20 con una entrada de 640) en dos ubicaciones: el bloque C2PSA de la capa 10 y el bloque C3k2 con atención de la capa 22. YOLO11 tiene un bloque C2PSA. En una DPU, sus operadores MatMul y Softmax se ejecutan en la CPU, lo que divide el modelo en subgrafos alternos de DPU y CPU. Tienes tres opciones:

1. Acepta los bloques de CPU. El .xmodel compilado contendrá subgrafos de CPU, así que ejecútalo con Graph Runner de AMD, que ejecuta juntos los subgrafos de DPU y CPU cuando existe una implementación en CPU para todos los operadores; de lo contrario, tendrás que implementar y registrar los operadores que falten. Con 20×20, el cálculo de atención es pequeño, pero cada transferencia adicional entre la DPU y la CPU añade latencia, así que mídelo en tu placa.

2. Usa un YAML sin atención. En tu YAML de Hard-Swish, sustituye la capa C2PSA por nn.Identity para que los índices de capa usados por Concat y Detect sigan siendo válidos, y desactiva la atención en la capa 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)

   El grafo ONNX exportado no contiene entonces operadores MatMul ni Softmax. Los pesos de atención dejan de ser aplicables (se transfieren 624 de los 666 pesos de YOLO26n), así que ajusta el modelo durante más tiempo y compara la precisión con el modo Val.

3. Usa un modelo sin atención, como YOLOv8, que AMD ha utilizado en sus propios ejemplos de DPU.

En Versal AI Edge Gen 2, los operadores de atención aparecen como compatibles con la NPU, por lo que estos cambios suelen ser innecesarios. Confirma su ubicación en el informe del compilador, ya que AMD advierte que los operadores compatibles pueden seguir ejecutándose en la CPU debido a restricciones de configuración o memoria.

Compatibilidad de modelos de un vistazo#

Implementación en otros destinos AMD Xilinx#

Las DPU Zynq UltraScale+ y Kria y la NPU Versal AI Edge de primera generación usan flujos Vitis AI que format="xilinx" no genera. Entrena con Ultralytics y, después, genera el artefacto del destino con las herramientas de AMD en sus imágenes Docker Linux x86-64. Elige la pestaña correspondiente a tu dispositivo:

Prepara la placa con un diseño de hardware y una imagen Linux que incluyan la configuración del acelerador para la que has compilado, además del entorno de ejecución Vitis AI correspondiente. Consulta las guías de configuración de AMD para los destinos DPU Zynq UltraScale+ y Kria y Versal AI Edge (VEK280); después, copia los artefactos que necesita tu entorno de ejecución:

En la DPU, los búferes VART contienen valores INT8 de punto fijo: consulta la forma y la escala fix_point de cada tensor, cuantiza las entradas y des cuantiza las salidas antes del posprocesamiento. Graph Runner devuelve las salidas del grafo completo, mientras que un ejecutor que solo use la DPU devuelve salidas intermedias de subgrafos de la DPU cuyo cálculo debe completar tu código. VART-ML en VEK280 usa de forma predeterminada vistas de tensores de hardware, cuya forma, tipo de datos y disposición en memoria pueden diferir de los formatos ONNX; por eso, configura los tipos de tensores de entrada y salida del ejecutor como vistas de CPU o convierte tú mismo el formato de hardware (consulta la descripción general de la arquitectura VART-ML de AMD).

Aplicaciones en el mundo real#

Los dispositivos AMD Xilinx son habituales cuando la IA de visión debe ejecutarse en tiempo real, con bajo consumo y cerca del sensor:

• Seguridad industrial y en la construcción: detecta personas y máquinas alrededor de equipos pesados y supervisa zonas de trabajo con la detección de objetos y el recuento de objetos.
• Visión para automoción y vehículos todoterreno: ejecuta percepción basada en cámaras en componentes homologados para automoción, compatible con los vehículos autónomos y la asistencia al conductor.
• Cámaras inteligentes y analítica de vídeo: combina la captura y codificación de vídeo con la inferencia de YOLO en un solo chip para sistemas de seguridad y analítica de vídeo.
• Visión artificial e inspección de calidad: combina la captura de imágenes de alta velocidad basada en FPGA con la segmentación de instancias o la clasificación de YOLO para detectar defectos en línea.
• Robótica y drones: utiliza módulos Kria KR260 o Versal para la estimación de pose, la detección de objetos orientados y la navegación con latencia determinista.

Resumen#

Al exportar con format="xilinx", los modelos Ultralytics YOLO se cuantizan con AMD Quark para las NPU AMD Versal AI Edge Series Gen 2, el cabezal se mantiene en BF16 y la configuración del compilador Vitis AI se guarda junto al modelo. Valida la precisión INT8 en cualquier equipo, compila el modelo .rai en la imagen Docker Vitis AI de AMD y ejecútalo en la placa con ONNX Runtime y el proveedor de ejecución Vitis AI.

Los dispositivos AMD Xilinx antiguos usan otros flujos. La DPU de Zynq UltraScale+ y Kria usa la cadena de herramientas Vitis AI 3.5, ya obsoleta, y archivos .xmodel; necesita activaciones nativas de la DPU, como Hard-Swish, y ejecuta la atención en la CPU. La NPU Versal AI Edge de primera generación usa el flujo snapshot, cuya cobertura de operadores depende de la versión de Vitis AI y de la precisión.

Para otros destinos de implementación, consulta la guía de opciones de implementación de modelos, las prácticas recomendadas de implementación y las integraciones de aceleradores, como Hailo, Rockchip RKNN y Axelera.

Preguntas frecuentes#