Exportación a Hailo para modelos YOLO de Ultralytics#

Los aceleradores de IA Hailo ejecutan modelos compilados en Hailo Executable Format (HEF) en dispositivos de borde como Raspberry Pi AI Kit y AI HAT+. Ultralytics exporta modelos de detección, segmentación, segmentación semántica, estimación de profundidad, clasificación, pose y OBB de YOLO directamente a HEF con el Hailo Dataflow Compiler (DFC).

El despliegue de Hailo está diseñado para visión artificial en el borde (edge): cámaras, robots, sistemas industriales, pasarelas y otros dispositivos que necesiten detección de objetos local sin enviar cada fotograma a la nube. Un HEF compilado contiene la red cuantizada, la asignación de hardware, la programación y el post-procesamiento de HailoRT opcional necesario para el acelerador seleccionado.

¿Por qué implementar Ultralytics YOLO en Hailo?#

Combinar Ultralytics YOLO con una unidad de procesamiento neuronal (NPU) de Hailo proporciona una ruta práctica desde el entrenamiento del modelo hasta la inferencia de IA en el borde (edge) de bajo consumo. Los casos de uso comunes incluyen:

• Cámaras inteligentes y analítica de vídeo: Ejecuta detección de objetos en tiempo real cerca de la cámara para aplicaciones de seguridad, venta al por menor, 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 constante a la nube.
• Visión artificial industrial: Implementa modelos YOLO personalizados para inspección, recuento, monitorización de seguridad y control de calidad.
• Proyectos de Raspberry Pi AI: Añade inferencia de visión acelerada a sistemas Raspberry Pi usando el AI Kit o el AI HAT+.
• Pasarelas de borde (edge) y PCs con IA: Procesa múltiples flujos de vídeo o sensores localmente 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 porque las imágenes permanecen en el dispositivo de despliegue. El rendimiento, la latencia y el consumo de energía reales 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 a Hailo#

Ultralytics gestiona todo el flujo de trabajo de exportación detrás de format="hailo":

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

El exportador realiza estas etapas automáticamente:

1. Exporta un gráfico ONNX estático con ajustes compatibles con el compilador.
2. Selecciona las salidas de las cabeceras para la arquitectura del modelo.
3. Genera directivas de normalización, activación y post-procesamiento.
4. Construye un flujo de calibración representativo y cuantiza el modelo a INT8.
5. Compila el gráfico 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 el pipeline compilado. Los modelos de detección YOLO26 utilizan sus salidas uno a uno sin NMS, por lo que el exportador selecciona automáticamente una ruta de salida y cuantización diferente. La segmentación, la pose y el OBB de YOLOv8/YOLO11 compilan los tensores de la cabecera sin procesar, que Ultralytics decodifica en la inferencia, y la clasificación de YOLOv8/YOLO11/YOLO26 ejecuta softmax en el chip para que el HEF devuelva las probabilidades de las clases directamente. Para la segmentación semántica de YOLO26, el exportador sigue al acelerador: Hailo-8/8L (DFC v3.x) devuelven logits del clasificador para el muestreo ascendente y la reducción en el host, mientras que Hailo-10/15 (DFC v5.x) compilan cabeceras ArgMax multiclase en el chip y devuelven un mapa de clases compacto. Las cabeceras de clase única utilizan la ruta de logits del host en todos los objetivos porque requieren un umbral en lugar de ArgMax. Los modelos de profundidad de YOLO26 compilan la convolución densa de logits en a16 y reconstruyen el mapa de profundidad métrica en el host (la restricción/exponencial y la calibración log-afín aprendida que siguen a la cabecera), de modo que el cuantizador mantiene su rango más amplio en el logit sin procesar. Los usuarios no necesitan buscar nodos finales de ONNX, escribir un script de modelo de Hailo (.alls) o crear un JSON de NMS manualmente.

Instalación#

Instala Ultralytics y descarga el archivo wheel del DFC para tu hardware objetivo desde la 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-10 y Hailo-15 utilizan DFC v5.x. Instala la generación del compilador que coincida con el acelerador de destino.

Exportar 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="hailo8l")
print(output)  # yolo11n_hailo_model/

El comando CLI equivalente es:

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

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

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

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

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

Modelos y hardware compatibles#

El ecosistema de Hailo abarca una amplia gama de cargas de trabajo de visión artificial, pero el exportador format="hailo" de Ultralytics valida actualmente las cabeceras estándar de detección, segmentación, segmentación semántica, estimación de profundidad, clasificación, pose y OBB de YOLO. La tabla de tareas describe las rutas de exportación disponibles; la validación de hardware se enumera por separado a continuación.

Familias de detección especializadas como YOLOv10, YOLO-World, YOLOE y RT-DETR también están ❌ no soportadas. Ultralytics rechaza estas tareas y familias de modelos antes de la compilación en lugar de producir un HEF no validado.

Pose, OBB, clasificación, segmentación semántica de YOLO26 y estimación de profundidad de YOLO26 (ruta Hailo-8/8L) fueron validadas en Hailo-8L con HailoRT 4.23 y DFC 3.33. El exportador acepta los demás objetivos enumerados, pero esas nuevas rutas de tareas requieren validación con el compilador y el dispositivo correspondientes antes de su uso en producción.

Selecciona uno de estos valores de name:

hailo8l es el valor predeterminado. Instala la generación de DFC que coincida con el objetivo seleccionado.

Generaciones de hardware y SDK de Hailo#

Las familias de aceleradores de Hailo utilizan diferentes generaciones de compiladores. El HEF generado debe coincidir con el hardware de destino, así que elige name para el dispositivo que ejecutará la inferencia en lugar de la máquina que realiza la exportación.

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

Notas de compatibilidad#

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

• El valor de name seleccionado debe coincidir con el acelerador de implementación.
• Las imágenes de calibración deben representar la iluminación, los puntos de vista, los objetos y los fondos esperados en producción.
• Un HEF compilado con un imgsz no se vuelve de tamaño dinámicamente modificable en tiempo de ejecución.
• Los recuentos de clases personalizados son compatibles porque Ultralytics genera la configuración de post-procesamiento a partir de los metadatos del modelo.
• Se admiten modelos de detección con cabeceras estándar de Detect de Ultralytics, modelos de segmentación, pose y OBB de YOLOv8/YOLO11, modelos de clasificación de YOLOv8/YOLO11/YOLO26, y modelos de segmentación semántica y estimación de profundidad de YOLO26; actualmente no se admiten las exportaciones de segmentación de instancias, pose y cuadro delimitador orientado de YOLO26, junto con YOLO-World, YOLOE, YOLOv10 y RT-DETR.
• Los artefactos Hailo-8/8L y Hailo-10/15 son compilados por diferentes generaciones de DFC y no son intercambiables.

Calibración y cuantización INT8#

La exportación a HEF de Hailo utiliza cuantización INT8 para mapear la red YOLO eficientemente sobre el 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 específico para la tarea, como COCO128 para detección, cityscapes8 para segmentación semántica o depth8 para estimación de profundidad. La cabecera 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, y los conjuntos más grandes dentro del dominio mejoran la fidelidad. Para un modelo de visión artificial personalizado, apunta data al YAML de su conjunto de datos para que el compilador observe imágenes representativas del dominio de implementación real:

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

fraction selecciona la porción del conjunto de datos utilizada para la calibración. Más imágenes solo ayudan cuando representan el dominio de implementación; las imágenes fuera de dominio pueden reducir la precisión cuantizada y aumentar el tiempo de optimización. Si el HEF en INT8 pierde precisión en relación con el modelo de 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 modelo#

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

La retención compara ambos modelos con el mismo umbral de confianza. Los HEF de YOLOv8 y YOLO11 integran el valor de conf en el momento de la exportación (por defecto 0,25) 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-exhaustividad y exagera la brecha de cuantización.

Más allá 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 partición de validación, utilizando calibración in-domain:

La segmentación, la pose y el OBB se calibraron con el conjunto predeterminado dentro del dominio de cada tarea (COCO128-seg, COCO8-pose, DOTA128); la clasificación se calibró con ImageNet100. De estos valores predeterminados se desprenden dos salvedades: COCO8-pose consta de solo 8 imágenes, por lo que debes tratar la pose como algo indicativo y pasar un data= mayor para producción, y DOTA8 satura mAP50 cerca del 100 % para ambos modelos, razón por la cual el OBB se lee en DOTA128. La clasificación es también la única tarea en la que YOLO11 retiene más que YOLOv8; para las demás, el backbone de atención de YOLO11 es más sensible a INT8.

De las mediciones del dispositivo se derivan tres reglas prácticas:

1. Calibra siempre en dominio. El ajuste fino con imágenes fuera de dominio es equivalente a desactivar el ajuste fino por completo: un YOLO26n calibrado con 1,238 imágenes fuera de dominio retiene la misma precisión (85.7%) que uno compilado sin ajuste fino. Un conjunto pequeño en dominio supera a uno grande fuera de dominio.
2. Reduce conf en aproximadamente 0,05 para implementaciones de YOLO26. La cuantización desplaza las puntuaciones de YOLO26 hacia abajo en torno a 0,05 de media, por lo que un umbral ajustado en PyTorch descarta detecciones válidas en el HEF. El uso de conf=0.20 en el dispositivo coincide con el recuento de detecciones de PyTorch en conf=0.25, y reducirlo un poco más (alrededor de conf=0.15) recupera prácticamente toda la brecha de mAP50 restante a costa de más detecciones de baja confianza. La cuantización también reordena aproximadamente el 20 % de las detecciones —un efecto de ordenamiento permanente que ningún umbral deshace—, pero esa reordenación no bloquea la recuperación de mAP50 en el umbral más bajo.
3. La penalización por atención es estructural en Hailo-8/8L (DFC 3.33). Los bloques de atención se compilan en operaciones de matmul que mantienen las entradas de activación en INT8 en todos los modos que el compilador ofrece para ellas; el modo de salida de 16 bits falla en la asignación 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 de todos modos (proteger las convoluciones de profundidad y de salida a 16 bits dejó mAP sin cambios en nuestras pruebas). Cuando la prioridad es la precisión y el modelo es intercambiable, YOLO11 se cuantiza actualmente mejor que YOLO26 aquí; las generaciones más nuevas de Hailo (DFC 5.x) exponen más opciones de precisión mixta y pueden diferir.

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 cargado por HailoRT.
• metadata.yaml conserva los nombres de los modelos, la tarea, el tamaño de entrada, el salto (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, semántica, profundidad, clasificación, pose, OBB) no utilizan este archivo.

El gráfico ONNX intermedio se elimina tras la compilación.

Ejecutar inferencia en hardware Hailo#

Instala HailoRT en el dispositivo de destino. Los usuarios de Raspberry Pi AI Kit y AI HAT+ pueden seguir la guía de software de IA de Raspberry Pi:

sudo apt install hailo-all
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 la salida NMS de HailoRT de YOLOv8 y YOLO11 y decodifica las salidas uno a uno de YOLO26 automáticamente. Decodifica tensores sin procesar de segmentación, pose y OBB, devuelve probabilidades de clasificación en el chip y produce mapas de clases semánticas mediante la reducción en el host en Hailo-8/8L y todas las cabeceras de clase única, o un ArgMax en el chip para cabeceras multiclase de Hailo-10/15. TAPPAS, GStreamer y el asistente picamera2.devices.Hailo de Raspberry Pi siguen estando disponibles para pipelines específicos de aplicaciones.

Para una implementación en 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 en Hailo#

El HEF es el mismo artefacto de modelo desplegable a través de varias interfaces de tiempo de ejecución de Hailo. Elige la interfaz que se ajuste a la aplicación:

Conserva metadata.yaml junto con el HEF cuando la aplicación necesite los nombres de las clases, el tamaño de entrada, el salto (stride) u otra información del modelo de Ultralytics. El HEF por sí solo no sustituye la lógica a nivel de aplicación para la captura de cámara, la visualización, el seguimiento, las alertas o el almacenamiento.

Verifica el dispositivo Hailo y el HEF#

Antes de integrar una cámara o una tubería de vídeo, verifica de forma independiente el tiempo de ejecución y el acelerador:

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

Las mediciones de rendimiento solo del dispositivo aíslan la inferencia de Hailo de la decodificación de vídeo, el redimensionamiento de imágenes, el dibujo y la E/S de la aplicación. Mide la aplicación completa por separado al estimar la latencia de extremo a extremo o los fotogramas por segundo.

Hailo en comparación con otros formatos de exportación de YOLO#

Elige un formato de exportación basado en el hardware que ejecutará el modelo:

HEF es la elección correcta cuando el dispositivo final contiene un acelerador Hailo. ONNX sigue siendo útil como formato de intercambio portátil, pero HailoRT ejecuta el HEF específico de hardware producido por el DFC en lugar del modelo ONNX original.

Optimiza el rendimiento de la visión artificial de Hailo#

Las elecciones de modelo y tubería a menudo importan más que las banderas del compilador:

• Comienza con un modelo YOLO pequeño y aumenta el tamaño del modelo solo cuando la precisión lo requiera.
• Elige el imgsz fijo más bajo que aún conserve los objetos importantes para la aplicación.
• Usa imágenes de calibración de la cámara y el entorno reales cuando sea posible.
• Mantén activa la red de Hailo a través de los fotogramas en lugar de volver a abrir el HEF para cada inferencia.
• Separa el tiempo de inferencia del dispositivo del preprocesamiento, la decodificación de vídeo, el posprocesamiento, la visualización y la E/S de red.
• Usa una tubería de streaming como GStreamer para cargas de trabajo de vídeo sostenidas.
• Valida el HEF exportado en el acelerador exacto y la versión de HailoRT utilizada en producción.

Argumentos de exportación#

Para la exportación de 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 el OBB utilizan tensores de cabecera sin procesar, la clasificación devuelve probabilidades en el chip y la segmentación semántica devuelve logits sin procesar en Hailo-8/8L y todas las cabeceras de clase única, o mapas de clases integrados para cabeceras multiclase de Hailo-10/15. La estimación de profundidad devuelve el logit de profundidad sin procesar, que Ultralytics decodifica en un mapa de profundidad métrica en la inferencia. No pases end2end; las anulaciones explícitas se rechazan. Tampoco se admiten formas dinámicas, lotes superiores a uno, NMS de Ultralytics incrustado, FP16 ni FP32.

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

Error de importación del compilador Hailo Dataflow#

Si la exportación informa que falta hailo_sdk_client, instala el archivo wheel de DFC para la generación de hardware de destino en el mismo entorno de Python que Ultralytics. Hailo-8/8L y Hailo-10/15 requieren diferentes generaciones de compiladores.

Sistema operativo o arquitectura no compatible#

La compilación de HEF es compatible con Linux x86_64. Realiza la exportación a través de Ultralytics Platform o utiliza una estación de trabajo compatible si el ordenador local es macOS, Windows, Raspberry Pi u otro sistema ARM.

La exportación tarda mucho tiempo#

La optimización del DFC es la etapa 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 solo con CPU puede ser sustancialmente más lenta.

La precisión del modelo cuantizado cae#

Utiliza imágenes de calibración que se parezcan a las entradas de producción e incluyan los objetos importantes, escalas, condiciones de iluminación y fondos. Compara el modelo de PyTorch original y el HEF exportado en el mismo conjunto de validación antes de la implementación. Sigue habiendo una brecha moderada dependiente de la familia incluso con una buena calibración; consulta Expectativas de precisión por familia de modelos para ver 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 mutuamente compatibles. Inspecciona el artefacto con hailortcli parse-hef y verifica el acelerador con hailortcli fw-control identify.

El análisis de salida parece incorrecto#

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

Resumen#

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

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

Para otros destinos de implementación de visión artificial, consulta el modo de exportación, el modo de evaluación comparativa y la guía de integraciones. Las guías de hardware relacionadas incluyen ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 y Qualcomm QNN.

FAQ#