Guía de conversión de modelos HEF de Hailo

Esta guía describe el flujo de trabajo para convertir un modelo de visión artificial en un archivo ejecutable de Hailo (.hef) para reComputer R Series (CM5 + Hailo-8) o reComputer R Series (CM5 + Hailo-10H).

Un archivo .hef es específico del hardware de destino. No despliegues un HEF de Hailo-8 en un Hailo-10H, ni un HEF de Hailo-10H en un Hailo-8. Compila, valida, etiqueta y publica cada destino como un artefacto independiente.

Antes de empezar

La conversión de modelos es diferente de la inferencia en tiempo de ejecución:

• HailoRT ejecuta un HEF existente en el dispositivo; no convierte ONNX.
• El Compilador Dataflow de Hailo (DFC) realiza el análisis, la optimización, la cuantización y la compilación del HEF.
• Ejecuta el DFC en el entorno de desarrollo soportado proporcionado por Hailo, no en el dispositivo de despliegue Raspberry Pi.

Antes de la conversión, prepara lo siguiente:

1. Un modelo ONNX con forma fija y una disposición de entrada y orden de colores explícitos.
2. Un conjunto de imágenes de calibración representativo que coincida con los datos de producción.
3. Requisitos de postprocesamiento: lista de clases, anclas, umbrales, modo NMS, disposición de puntos clave, decodificación de máscaras y cualquier operación del lado del host.
4. La versión del DFC y del Model Zoo que soporte el hardware de destino previsto.

La rama master actual del Model Zoo de Hailo está orientada a dispositivos Hailo-10/15. Para Hailo-8 o Hailo-8L, utiliza una versión compatible de Model Zoo v2.x junto con la versión correspondiente del DFC. No uses master para compilar un modelo para Hailo-8.

1. Instala el entorno de desarrollo oficial

Instala el Hailo Software Suite o el Dataflow Compiler desde la Hailo Developer Zone y luego activa el entorno de Python incluido en esa instalación. El DFC no se instala en el dispositivo de despliegue Raspberry Pi.

Clona el Model Zoo oficial y selecciona una versión compatible con tu DFC y tu hardware de destino. Reemplaza el marcador de versión por la versión documentada en el Hailo Software Suite que instalaste.

Hailo-10H

git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
git checkout <compatible-hailo10h-release>
pip install -e .

Hailo-8

git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
git checkout <compatible-v2.x-release>
pip install -e .

Verifica que la CLI esté disponible:

hailomz --version
hailomz info <model_name>

2. Compila una red del Model Zoo oficial

Para una red ya incluida en el Model Zoo de Hailo, el comando compile ejecuta las etapas de análisis y optimización necesarias y genera el HEF:

# Hailo-8: run this from a compatible Model Zoo v2.x environment
hailomz compile <model_name> --hw-arch hailo8

# Hailo-10H: run this from a compatible Hailo-10H environment
hailomz compile <model_name> --hw-arch hailo10h

Si necesitas inspeccionar las etapas por separado, la CLI oficial también expone:

hailomz parse <model_name> --hw-arch <hailo8-or-hailo10h>
hailomz optimize <model_name> --hw-arch <hailo8-or-hailo10h>
hailomz compile <model_name> --hw-arch <hailo8-or-hailo10h>

El nombre de la red, el conjunto de calibración, el preprocesamiento, el postprocesamiento y el script del modelo provienen de los archivos YAML y ALLS de esa red en el Model Zoo. Revísalos antes de aceptar el HEF generado.

3. Ejemplo práctico: Convertir YOLO11n

Hailo proporciona oficialmente la configuración yolov11n en el Model Zoo. La configuración v2.19.0 soporta Hailo-8/Hailo-8L, mientras que la configuración actual del Model Zoo para Hailo-10H soporta Hailo-10H. Utiliza el entorno y la rama que correspondan a tu hardware de destino.

Compila el YOLO11n preentrenado de Hailo

El Model Zoo descarga el punto de control referenciado y aplica su configuración YAML, nodos de análisis, script de modelo, flujo de calibración y configuración de NMS mantenidos:

# In a Hailo-8-compatible Model Zoo v2.x environment
hailomz info yolov11n
hailomz compile yolov11n --hw-arch hailo8

# In a Hailo-10H-compatible Model Zoo environment
hailomz info yolov11n
hailomz compile yolov11n --hw-arch hailo10h

El comando imprime la ruta del HEF generado cuando la compilación finaliza.

Compila tu propio YOLO11n entrenado

Primero exporta el punto de control de entrenamiento de Ultralytics a un modelo ONNX de 640 píxeles fijos. Ejecuta este paso en el entorno de entrenamiento, no en el entorno del DFC, a menos que los requisitos de Python sean compatibles.

pip install ultralytics
yolo export model=/path/to/best.pt format=onnx imgsz=640

Valida el ONNX exportado antes de la cuantización:

yolo predict model=/path/to/best.onnx source=/path/to/test.jpg

Luego activa el entorno correspondiente del DFC/Model Zoo de Hailo. Establece el hardware de destino y el número de clases de tu conjunto de datos entrenado y compila usando la configuración de red YOLO11n de Hailo:

# Use hailo8 in a compatible v2.x environment, or hailo10h in its matching environment.
TARGET_ARCH=hailo10h
NUM_CLASSES=3

hailomz compile \
  --ckpt /path/to/best.onnx \
  --calib-path /path/to/calibration/images \
  --yaml hailo_model_zoo/cfg/networks/yolov11n.yaml \
  --classes "$NUM_CLASSES" \
  --hw-arch "$TARGET_ARCH"

Utiliza imágenes representativas en formato .jpg, .jpeg o .png en el directorio de calibración. Si el entrenamiento cambió más que los pesos y el número de clases —por ejemplo, la resolución de entrada, la cabeza de detección, los nombres de capas o la disposición de salida—, los archivos YAML y ALLS estándar de YOLO11n pueden dejar de ser válidos. Actualiza y valida esos archivos en lugar de forzar la ejecución del comando.

Por último, copia el HEF al dispositivo de destino y verifica que se ejecuta:

scp /path/to/yolov11n.hef seeed@<BOARD_IP>:~/
ssh seeed@<BOARD_IP>
hailortcli fw-control identify
hailortcli benchmark ~/yolov11n.hef

La aplicación debe usar el mismo preprocesamiento de entrada, etiquetas de clase y contrato de NMS/salida de YOLO11 utilizados durante la compilación. Una prueba de rendimiento exitosa no valida por sí sola la decodificación de las cajas delimitadoras.

4. Compila otro punto de control ONNX personalizado soportado

Las guías de entrenamiento oficiales de Hailo utilizan el siguiente formato del Model Zoo cuando un modelo ONNX personalizado coincide con una definición de red existente en el Model Zoo:

hailomz compile \
  --ckpt /path/to/model.onnx \
  --calib-path /path/to/calibration/images \
  --yaml /path/to/hailo_model_zoo/cfg/networks/<network>.yaml \
  --hw-arch <hailo8-or-hailo10h>

Añade anulaciones de nodos de análisis solo cuando la guía oficial del modelo o una inspección verificada con Netron lo requieran:

hailomz compile \
  --ckpt /path/to/model.onnx \
  --calib-path /path/to/calibration/images \
  --yaml /path/to/<network>.yaml \
  --start-node-names <input_node> \
  --end-node-names <output_node_1> <output_node_2> \
  --hw-arch <hailo8-or-hailo10h>

Para una arquitectura completamente nueva que no tenga una configuración YAML y ALLS coincidente en el Model Zoo, utiliza el flujo de trabajo del Dataflow Compiler descrito en la Guía de usuario del DFC. Un comando genérico hailomz compile no puede determinar automáticamente los nodos finales, el preprocesamiento, la cuantización ni el postprocesamiento correctos.

5. Flujo de trabajo de conversión

1. Exporta y valida el ONNX. Congela el tamaño de entrada y el preprocesamiento. Comprueba el modelo ONNX con una imagen de prueba en el host antes de compilar.
2. Elige el hardware de destino. Crea espacios de trabajo de conversión separados para Hailo-8 y Hailo-10H. Mantén la trazabilidad del ONNX de origen y los datos de calibración.
3. Analiza la red. Usa el analizador del DFC para producir la representación intermedia de la red e inspecciona todos los nombres y formas de los tensores de entrada/salida.
4. Configura el preprocesamiento y el postprocesamiento. Prefiere la configuración de red correspondiente del Model Zoo de Hailo cuando esté disponible. Registra cada decisión de normalización, redimensionamiento, anclas, NMS y decodificación de salida en el README del modelo.
5. Optimiza con datos de calibración. Ejecuta la cuantización usando imágenes representativas. Revisa las advertencias y los resultados de precisión antes de compilar.
6. Compila el HEF. Compila por separado para el hardware seleccionado y luego nombra los artefactos de forma inequívoca, por ejemplo modelo_hailo8.hef y modelo_hailo10h.hef.
7. Valida en el hardware. Ejecuta el HEF con la versión correspondiente de HailoRT, compara los tensores de salida y los resultados postprocesados con la referencia del host, y verifica que /dev/hailo0 esté disponible.

6. Validar el HEF

Copia el HEF generado al hardware con el acelerador y la versión de HailoRT correspondientes, identifica el dispositivo y ejecuta el comando oficial de benchmark:

hailortcli fw-control identify
hailortcli benchmark /path/to/model.hef

El éxito del benchmark confirma que el HEF puede ejecutarse en el dispositivo. No valida el preprocesamiento de la aplicación ni la decodificación de salidas, por lo que también debes comparar el resultado integral con la implementación de referencia del modelo fuente.

7. Lista de verificación para publicación en Hailo-8 y Hailo-10H

8. Publicar y desplegar

Para cada nuevo modelo objetivo:

1. Agrega el HEF, el módulo fuente, el Dockerfile, los medios de demostración y el comando probado al repositorio Hailo CV correspondiente.
2. Construye y prueba la imagen GHCR en el hardware físico de destino.
3. Añade la entrada de despliegue del modelo en AI Lab y la página Wiki específica de la plataforma.
4. Agrega la URL del paquete en downloadSources para que se puedan mostrar los totales de descarga del modelo.

Una vez validado el HEF, consulta la página independiente Despliegue de modelos CV en Hailo-8 o Despliegue de modelos CV en Hailo-10H de esta sección para conocer el procedimiento completo de verificación del dispositivo, descarga de la imagen, comando Docker run y vista previa en el navegador.

Referencias oficiales:

• Hailo Model Zoo
• Model Zoo Getting Started
• Configuración de red de Hailo-8 YOLO11n
• Configuración de red de Hailo-10H YOLO11n
• Guía de instalación de Hailo Apps
• Guía de exportación ONNX de Ultralytics