Exportación de modelos YOLO de Ultralytics para Hailo#

Los aceleradores de IA de Hailo ejecutan modelos compilados en el Formato ejecutable de Hailo (HEF) en dispositivos edge como la AI HAT+ de Raspberry Pi y la AI HAT+ 2. Ultralytics exporta directamente a HEF modelos YOLO de detección, segmentación, segmentación semántica, estimación de profundidad, clasificación, pose y OBB con el Compilador de flujo de datos de Hailo (DFC).

El despliegue de Hailo está diseñado para la visión artificial en el edge: cámaras, robots, sistemas industriales, gateways y otros dispositivos que necesitan detectar objetos localmente sin enviar cada fotograma a la nube. Un HEF compilado contiene la red cuantizada, la asignación de hardware, la planificación y el postprocesado opcional de HailoRT necesarios para el acelerador seleccionado.

¿Por qué desplegar Ultralytics YOLO en Hailo?#

Combinar Ultralytics YOLO con una unidad de procesamiento neuronal (NPU) de Hailo ofrece una vía práctica desde el entrenamiento del modelo hasta la inferencia de IA en el edge. Entre los casos de uso habituales se incluyen:

• Cámaras inteligentes y análisis de vídeo: Ejecuta detección de objetos en tiempo real cerca de la cámara para aplicaciones de seguridad, comercio minorista, tráfico y ocupación.
• Robótica y sistemas autónomos: Detecta personas, vehículos, paquetes, herramientas u obstáculos sin depender de una conexión continua a la nube.
• Visión artificial industrial: Despliega modelos YOLO personalizados para inspección, recuento, supervisión de la seguridad y control de calidad.
• Proyectos de IA con Raspberry Pi: Añade inferencia de visión acelerada a sistemas Raspberry Pi mediante AI HAT+ o AI HAT+ 2.
• Gateways edge y PC de IA: Procesa localmente varios flujos de vídeo o sensores mientras reduces los requisitos de ancho de banda y computación en la nube.

La inferencia local puede mejorar la privacidad y el tiempo de respuesta, ya que las imágenes permanecen en el dispositivo de despliegue. El rendimiento real, la latencia y el consumo energético dependen del tamaño del modelo YOLO, la resolución de entrada, la arquitectura de Hailo, el sistema anfitrión y la canalización de la aplicación.

Cómo funciona la exportación para Hailo#

Ultralytics controla todo el flujo de exportación que hay detrás de format="hailo":

YOLO (.pt) -> ONNX -> Hailo parse -> INT8 optimization -> HEF compile

El exportador realiza automáticamente estas etapas:

1. Exporta un grafo ONNX estático con ajustes compatibles con el compilador.
2. Selecciona las salidas de la cabeza correspondientes a la arquitectura del modelo.
3. Genera directivas de normalización, activación y postprocesado.
4. Construye un flujo de calibración representativo y cuantiza el modelo a INT8.
5. Compila el grafo optimizado para el acelerador Hailo seleccionado.
6. Guarda el HEF con metadatos de Ultralytics y elimina el archivo ONNX intermedio.

Los modelos de detección YOLOv8 y YOLO11 utilizan HailoRT YOLO NMS en la canalización compilada. Los modelos de detección YOLO26 utilizan sus salidas uno a uno sin NMS, por lo que el exportador selecciona automáticamente una salida y una ruta de cuantización diferentes. La segmentación, la pose y el OBB de YOLOv8/YOLO11 compilan los tensores sin procesar de la cabeza, que Ultralytics decodifica durante la inferencia, y la clasificación de YOLOv8/YOLO11/YOLO26 ejecuta softmax en el chip, de modo que el HEF devuelve directamente las probabilidades de clase. Para la segmentación semántica de YOLO26, el exportador sigue el acelerador: Hailo-8/8L (DFC v3.x) devuelve los logits del clasificador para el sobremuestreo y la reducción en el host, mientras que Hailo-10H/15 (DFC v5.x) compila cabezas ArgMax multiclase en el chip y devuelve un mapa de clases compacto. Las cabezas de una sola clase utilizan la ruta de logits en el host en todos los destinos porque requieren un umbral en lugar de ArgMax. Los modelos de profundidad YOLO26 compilan la convolución de logits densa en a16 y reconstruyen el mapa de profundidad métrica en el host (el clamp/exp y la calibración log-afín aprendida que siguen a la cabeza), por lo que el cuantizador conserva su rango más amplio en los logits sin procesar. No necesitas buscar nodos finales de ONNX, escribir un script de modelo de Hailo (.alls) ni crear manualmente un JSON de NMS.

Instalación#

Instala Ultralytics y descarga la wheel de DFC para tu hardware de destino desde Hailo Developer Zone (se requiere registro gratuito):

pip install ultralytics
pip install /path/to/hailo_dataflow_compiler-*.whl

Hailo-8 y Hailo-8L utilizan DFC v3.x. Hailo-10H y Hailo-15 utilizan DFC v5.x. Instala la generación del compilador que coincida con el acelerador de destino.

Exporta un modelo HEF de Hailo#

Usa format="hailo" y selecciona el acelerador de destino con name:

from ultralytics import YOLO

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

El comando equivalente de la CLI es:

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

La exportación para Hailo solo admite INT8. Ultralytics descarga automáticamente un conjunto de datos de calibración específico de la tarea cuando no se proporciona data. Para modelos personalizados, utiliza imágenes representativas de entrenamiento o validación:

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

La compilación utiliza una forma de entrada fija. Establece imgsz en la resolución utilizada en el dispositivo:

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

Modelos y hardware compatibles#

El ecosistema de Hailo cubre una amplia variedad de cargas de trabajo de visión artificial, pero el exportador format="hailo" de Ultralytics valida actualmente cabezas estándar de YOLO para detección, segmentación, segmentación semántica, estimación de profundidad, clasificación, pose y OBB. La tabla de tareas describe las rutas de exportación disponibles; la validación del hardware se indica por separado más abajo.

Las familias especializadas de detección, como YOLOv10, YOLO-World, YOLOE y RT-DETR, actualmente ❌ no son compatibles mediante la ruta format="hailo" de Ultralytics. Ultralytics rechaza estas tareas y familias de modelos antes de la compilación, en lugar de producir un HEF no validado.

La pose, el OBB, la clasificación, la segmentación semántica de YOLO26 y la estimación de profundidad de YOLO26 (ruta de Hailo-8/8L) se validaron en Hailo-8L con HailoRT 4.23 y DFC 3.33. El exportador acepta los demás destinos indicados, pero esas nuevas rutas de tareas requieren validación con el compilador y el dispositivo correspondientes antes de utilizarlas en producción.

Selecciona uno de estos valores de name:

Si se omite name, se utiliza hailo8l de forma predeterminada; establece name en el acelerador en el que vayas a desplegar. Instala la generación del DFC que coincida con el destino seleccionado.

Generaciones de hardware y SDK de Hailo#

Las familias de aceleradores Hailo utilizan diferentes generaciones de compiladores. El HEF generado debe coincidir con el hardware de destino, por lo que debes elegir name para el dispositivo que ejecutará la inferencia, no para el equipo que realiza la exportación.

El compilador se ejecuta en Linux x86_64, mientras que el HEF resultante se ejecuta en el dispositivo Hailo mediante HailoRT. Esta separación permite compilar en una estación de trabajo o en Ultralytics Platform y desplegar el pequeño artefacto de ejecución en un host edge ARM o x86.

Notas de compatibilidad#

La compilación de Hailo es específica del hardware y utiliza una forma de entrada fija. Ten en cuenta estas restricciones:

• El name seleccionado debe coincidir con el acelerador de despliegue.
• Las imágenes de calibración deben representar la iluminación, los puntos de vista, los objetos y los fondos previstos en producción.
• Cada HEF se compila para un imgsz fijo. Para servir varias resoluciones, cambia el tamaño de los fotogramas en el host al tamaño compilado o compila un HEF independiente para cada resolución.
• Se admite un número de clases personalizado porque Ultralytics genera la configuración del postprocesado a partir de los metadatos del modelo.
• Son compatibles los modelos de detección con cabezales estándar de Ultralytics Detect, los modelos de segmentación, pose y OBB de YOLOv8/YOLO11, los modelos de clasificación de YOLOv8/YOLO11/YOLO26 y los modelos de segmentación semántica y estimación de profundidad de YOLO26; actualmente no son compatibles la segmentación de instancias, la pose ni las cajas delimitadoras orientadas de YOLO26, ni las exportaciones de YOLO-World, YOLOE, YOLOv10 y RT-DETR.
• Los artefactos de Hailo-8/8L y Hailo-10H/15 se compilan con generaciones distintas de DFC y no son intercambiables.

Calibración y cuantización INT8#

La exportación HEF de Hailo utiliza cuantización INT8 para asignar eficazmente la red YOLO al acelerador. El conjunto de datos de calibración estima los rangos de activación; no reentrena el modelo ni requiere etiquetas durante la compilación.

Cuando se omite data, Ultralytics utiliza un conjunto de datos de calibración ligero y específico de la tarea, como COCO128 para detección, cityscapes8 para segmentación semántica o depth8 para estimación de profundidad. El cabezal de profundidad densa es especialmente sensible al dominio de calibración: calibrar un modelo de profundidad con imágenes de detección no relacionadas aplana el mapa predicho, mientras que los conjuntos más grandes del dominio mejoran la fidelidad. Para un modelo de visión por computador personalizado, indica con data el YAML de su conjunto de datos para que el compilador observe imágenes representativas del dominio real de despliegue:

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

fraction selecciona la proporción o el número de imágenes utilizado para la calibración. Las listas de dos elementos de [train, val, test] limitan cada división, las listas de dos elementos dejan test completo y 0 omite test. Un mayor número de imágenes solo ayuda cuando representan el dominio de despliegue. Las imágenes fuera del dominio pueden reducir la precisión cuantizada y aumentar el tiempo de optimización. Si el HEF INT8 pierde precisión con respecto al modelo PyTorch original, mejora primero los datos de calibración antes de cambiar la configuración del modelo o del entorno de ejecución.

Expectativas de precisión por familia de modelos#

Medidos en un Hailo-8L con calibración del dominio (COCO128, 128 imágenes), las exportaciones HEF INT8 conservan la siguiente proporción de su mAP50 de PyTorch con el mismo protocolo de evaluación:

La conservación compara ambos modelos con el mismo umbral de confianza. Los HEF de YOLOv8 y YOLO11 incorporan el conf del momento de la exportación (0,25 de forma predeterminada) en el NMS del chip, por lo que validar frente a una línea base de PyTorch con su umbral bajo predeterminado integra una parte mayor de la curva de precisión-recall y exagera la diferencia de cuantización.

Además de la detección, las rutas de exportación de segmentación, pose, OBB y clasificación se validaron en el mismo Hailo-8L (DFC 3.33, HailoRT 4.23). Cada HEF INT8 se comparó con su checkpoint de PyTorch en la misma división de validación, usando calibración del dominio:

La segmentación, la pose y OBB se calibraron con el conjunto predeterminado de cada tarea en el dominio (COCO128-seg, COCO8-pose, DOTA128); la clasificación se calibró con ImageNet100. De esos valores predeterminados se derivan dos advertencias: COCO8-pose solo tiene 8 imágenes, así que considera la pose indicativa y pasa un data= mayor para producción; además, DOTA8 satura el mAP50 cerca del 100 % para ambos modelos, por lo que OBB se evalúa con DOTA128. La clasificación también es la única tarea en la que YOLO11 conserva más que YOLOv8; en las demás, el backbone de atención de YOLO11 es más sensible a INT8.

De las mediciones en el dispositivo se desprenden tres reglas prácticas:

1. Calibra siempre en el dominio. Ajustar con imágenes fuera del dominio equivale a desactivar por completo el ajuste: un YOLO26n calibrado con 1.238 imágenes fuera del dominio conserva la misma precisión (85,7 %) que uno compilado sin ajuste. Un conjunto pequeño del dominio supera a uno grande fuera del dominio.
2. Reduce conf aproximadamente 0,05 para los despliegues de YOLO26. La cuantización desplaza las puntuaciones de YOLO26 hacia abajo aproximadamente 0,05 de media, por lo que un umbral ajustado en PyTorch descarta detecciones válidas en el HEF. Usar conf=0.20 en el dispositivo iguala el número de detecciones de PyTorch con conf=0.25, y reducirlo un poco más (aproximadamente a conf=0.15) recupera prácticamente toda la diferencia restante de mAP50, a costa de obtener más detecciones con baja confianza. La cuantización también reordena aproximadamente el 20 % de las detecciones —un efecto permanente en el orden que ningún umbral puede deshacer—, pero ese reordenamiento no impide recuperar el mAP50 con el umbral más bajo.
3. La penalización de la atención es estructural en Hailo-8/8L (DFC 3.33). Los bloques de atención se compilan en operaciones matmul que mantienen las entradas de activación INT8 en todos los modos que ofrece el compilador; el modo de salida de 16 bits no logra asignar memoria para este grafo, y aumentar la precisión de las capas circundantes no ayuda porque la multiplicación de matrices vuelve a cuantizar sus entradas a INT8 (proteger las convoluciones depthwise y de salida a 16 bits no modificó el mAP en nuestras pruebas). Cuando la precisión es prioritaria y el modelo es intercambiable, actualmente YOLO11 se cuantiza mejor que YOLO26 aquí; las generaciones más recientes de Hailo (DFC 5.x) ofrecen más opciones de precisión mixta y pueden comportarse de forma distinta.

Artefactos exportados#

La exportación crea un directorio que contiene el HEF desplegable y los metadatos de Ultralytics:

yolo11n_hailo_model/
├── yolo11n.hef
├── metadata.yaml
└── nms_config.json

• *.hef es el modelo compilado que carga HailoRT.
• metadata.yaml conserva los nombres del modelo, la tarea, el tamaño de entrada, el stride y la información del objetivo de Hailo.
• nms_config.json registra la configuración de NMS de HailoRT generada para los modelos de detección YOLOv8 y YOLO11. La detección de YOLO26 y todas las tareas que no son de detección (segmentación, segmentación semántica, profundidad, clasificación, pose y OBB) no utilizan este archivo.

El grafo ONNX intermedio se elimina después de la compilación.

Ejecuta inferencias en hardware de Hailo#

Instala HailoRT en el dispositivo de destino. Los usuarios de Raspberry Pi AI HAT+ y AI HAT+ 2 pueden seguir la guía de software de Raspberry Pi AI. En Raspberry Pi OS no se pueden instalar simultáneamente los dos conjuntos de paquetes, así que ejecuta solo el bloque que corresponda a tu hardware y reinicia después.

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

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

Para AI HAT+ 2 (Hailo-10H, Raspberry Pi OS Trixie o posterior):

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

Después de reiniciar, confirma que se detecta el acelerador:

hailortcli fw-control identify

Copia el directorio de exportación completo al dispositivo para que metadata.yaml permanezca junto al HEF. Ultralytics utiliza HailoRT para ejecutar predict y val directamente en el directorio exportado:

from ultralytics import YOLO

model = YOLO("yolo11n_hailo_model")
results = model.predict("path/to/image.jpg")

Para los modelos de detección, el backend convierte automáticamente la salida NMS de HailoRT de YOLOv8 y YOLO11 y descodifica las salidas one-to-one de YOLO26. Descifra los tensores sin procesar de segmentación, pose y OBB, devuelve las probabilidades de clasificación del chip y genera mapas de clases semánticas mediante reducción en el host en Hailo-8/8L y en todos los cabezales de una sola clase, o mediante un ArgMax en el chip para los cabezales multiclase de Hailo-10H/15. TAPPAS, GStreamer y el asistente picamera2.devices.Hailo de Raspberry Pi siguen disponibles para canalizaciones específicas de cada aplicación.

Para un despliegue con GStreamer, pasa el 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

Opciones de despliegue de Hailo#

El HEF es el mismo artefacto de modelo desplegable en varias interfaces de ejecución de Hailo. Elige la interfaz que mejor se adapte a la aplicación:

Conserva metadata.yaml junto al HEF cuando la aplicación necesite los nombres de clase de Ultralytics, el tamaño de entrada, el stride u otra información del modelo. El HEF por sí solo no sustituye la lógica de nivel de aplicación para capturar imágenes, visualizar, hacer seguimiento, generar alertas o almacenar datos.

Verifica el dispositivo Hailo y el HEF#

Antes de integrar una canalización de cámara o vídeo, verifica por separado el entorno de ejecución y el acelerador:

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

Las mediciones de rendimiento únicamente del dispositivo aíslan la inferencia de Hailo de la descodificación de vídeo, el redimensionado de imágenes, el dibujo y la E/S de la aplicación. Mide la aplicación completa por separado cuando estimes la latencia de extremo a extremo o los fotogramas por segundo.

Hailo comparado con otros formatos de exportación de YOLO#

Elige un formato de exportación en función del hardware que ejecutará el modelo. HEF es específico del hardware y debe seleccionarse cuando el dispositivo final ya contenga un acelerador Hailo, no como formato periférico de propósito general o automáticamente más rápido.

No des por hecho que Hailo es más rápido o consume menos energía solo por ser una NPU. Para nuevos despliegues M.2, DeepX es el candidato más sólido para obtener un mayor rendimiento de YOLO y un mejor rendimiento por vatio, mientras que Axelera se orienta a un rendimiento muy superior con varios flujos. Rockchip es una opción popular y económica para SBC y sistemas integrados. Las cifras de TOPS y consumo de los proveedores no son comparables directamente con las mediciones de rendimiento de las aplicaciones, así que valida el mismo checkpoint de YOLO, tamaño de entrada, precisión, host y canalización de vídeo completa en los dispositivos candidatos antes de comprar hardware.

Optimiza el rendimiento de visión por computador de Hailo#

Las decisiones sobre el modelo y la canalización suelen importar más que las opciones del compilador:

• Empieza con un modelo YOLO pequeño y aumenta su tamaño solo cuando la precisión lo requiera.
• Elige el imgsz fijo más bajo que siga conservando los objetos importantes para la aplicación.
• Utiliza imágenes de calibración de la cámara y el entorno reales siempre que sea posible.
• Mantén activa la red de Hailo entre fotogramas en lugar de volver a abrir el HEF para cada inferencia.
• Separa el tiempo de inferencia del dispositivo del preprocesamiento, la descodificación de vídeo, el posprocesamiento, la visualización y la E/S de red.
• Utiliza una canalización de transmisión, como GStreamer, para cargas de vídeo sostenidas.
• Valida el HEF exportado en el acelerador exacto y la versión de HailoRT que se utilizarán en producción.

Argumentos de exportación#

En la exportación para detección, YOLOv8 y YOLO11 reciben NMS de HailoRT, mientras que YOLO26 conserva sus salidas uno a uno sin NMS. La segmentación, la pose y OBB utilizan tensores sin procesar de la cabecera; la clasificación devuelve probabilidades en el chip; y la segmentación semántica devuelve logits sin procesar en Hailo-8/8L y en todas las cabeceras de una sola clase, o mapas de clases integrados para las cabeceras Hailo-10H/15 multiclase. La estimación de profundidad devuelve el logit de profundidad sin procesar, que Ultralytics decodifica en un mapa de profundidad métrico durante la inferencia. No pases end2end; se rechazan las anulaciones explícitas. No se admiten formas dinámicas, NMS de Ultralytics integrado, FP16 ni FP32.

Solución de problemas de la exportación a Hailo#

Error de importación del Compilador de flujo de datos de Hailo#

Si la exportación indica que falta hailo_sdk_client, instala la wheel de DFC correspondiente a la generación de hardware de destino en el mismo entorno de Python que Ultralytics. Hailo-8/8L y Hailo-10H/15 requieren generaciones de compilador diferentes.

Sistema operativo o arquitectura no compatibles#

La compilación de HEF es compatible con Linux x86_64. Exporta mediante Ultralytics Platform o utiliza una estación de trabajo compatible si el equipo local ejecuta macOS, Windows, Raspberry Pi u otro sistema ARM.

La exportación tarda mucho#

La optimización de DFC es la fase más costosa. El tiempo de compilación aumenta con el tamaño del modelo, la resolución de entrada y los datos de calibración. Una GPU compatible puede acelerar la optimización, mientras que la compilación utilizando solo la CPU puede ser considerablemente más lenta.

La precisión del modelo cuantizado disminuye#

Utiliza imágenes de calibración que se parezcan a las entradas de producción e incluyan los objetos, escalas, condiciones de iluminación y fondos importantes. Compara el modelo PyTorch original y el HEF exportado en el mismo conjunto de validación antes de la implementación. Incluso con una buena calibración, se mantiene una diferencia moderada que depende de la familia; consulta Expectativas de precisión por familia de modelos para conocer las líneas base medidas.

El HEF no se carga en el dispositivo#

Confirma que name coincide con la arquitectura física de Hailo y que el controlador del dispositivo, el firmware y los paquetes de HailoRT son compatibles entre sí. Inspecciona el artefacto con hailortcli parse-hef y verifica el acelerador con hailortcli fw-control identify.

El análisis de las salidas parece incorrecto#

Conserva metadata.yaml junto al HEF para que Ultralytics pueda seleccionar la ruta de posprocesamiento correspondiente a YOLOv8, YOLO11 o YOLO26. Las aplicaciones personalizadas de HailoRT también deben asociar el posprocesamiento con la familia de modelos exportada.

Resumen#

La exportación de Ultralytics a Hailo proporciona una ruta directa desde un modelo YOLO entrenado hasta un HEF listo para la implementación:

1. Carga un modelo de detección o clasificación YOLOv8, YOLO11 o YOLO26; un modelo de segmentación, pose u OBB YOLOv8/YOLO11; o un modelo de segmentación semántica o estimación de profundidad YOLO26.
2. Exporta con format="hailo" y selecciona la arquitectura de destino.
3. Realiza la calibración y la compilación localmente con el DFC correspondiente, o utiliza la exportación gestionada en Ultralytics Platform.
4. Copia el HEF y metadata.yaml al dispositivo periférico con tecnología Hailo.
5. Ejecuta la inferencia con HailoRT, Raspberry Pi Picamera2 o una canalización de vídeo de GStreamer.

Para otros destinos de implementación de visión artificial, consulta Modo de exportación, Modo de evaluación y la guía de integraciones. Entre las guías de hardware relacionadas se incluyen DeepX, Axelera, ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 y Qualcomm QNN.

Preguntas frecuentes#