Convertir un modelo ONNX a HEF con Docker

HEF (Hailo Executable Format) es un formato de archivo que usan los dispositivos Hailo para ejecutar modelos de deep learning de manera eficiente en hardware de edge. Hailo ofrece aceleración de AI especializada, lo que permite una inferencia optimizada de redes neuronales.

En este post vamos a recorrer el proceso de convertir un modelo ONNX en un modelo HEF usando Docker. Este método permite compatibilidad multiplataforma, es decir que puedes seguir el tutorial en cualquier sistema operativo. En este caso vamos a mostrar el proceso en Windows.

Requisitos previos

Antes de continuar, asegúrate de tener lo siguiente:

1. Modelo ONNX: el modelo tiene que ser uno de los incluidos en el Hailo Model Zoo. En este ejemplo usamos un modelo YOLOv8n de Ultralytics entrenado para detectar vehículos y patentes.

2. Docker: instala Docker siguiendo la guía de instalación oficial.

3. Imágenes de calibración: estas imágenes ayudan al compilador a optimizar el modelo para el hardware de Hailo, y pueden ser las mismas que se usaron para entrenarlo, siempre que representen el entorno donde se va a desplegar.

Según las recomendaciones de Hailo, el conjunto de calibración suele estar formado por entre 32 y 96 imágenes. Sin embargo, para mejorar la precisión de la cuantización, en los foros se recomienda usar un conjunto más grande, de 500 a 1000 imágenes.

1. Descargar la imagen de Docker del Hailo AI Software Suite

Ve a la página de Software Downloads (Hailo) y descarga el Hailo AI Suite - versión Docker para Linux:

En este caso descargamos la versión 2024-10 del archivo, pero cualquier versión debería funcionar. La descarga contiene un .zip con estos dos archivos: hailo_ai_sw_suite_2024-10.tar.gz y hailo_ai_sw_suite_docker_run.sh.

2. Cargar la imagen de Docker

Para cargar la imagen de Docker, abre la línea de comandos, ve a la carpeta descomprimida y ejecuta el siguiente comando:

docker load -i hailo_ai_sw_suite_2024-10.tar.gz

Después, verifica que la imagen se haya cargado ejecutando:

docker images

Deberías ver la imagen hailo_ai_sw_suite_<version> en la lista:

3. Crear un contenedor de Docker

Antes de crear el contenedor, guarda en un directorio los pesos del modelo ONNX que quieres convertir y algunas imágenes de muestra. En este ejemplo creamos C:\Users\tinte\Downloads\vehicle_detection con dos subdirectorios: models e images:

.\vehicle_detection
    |-- models
    |   |-- model.onnx
    |-- images
        |-- image1.jpg
        |-- image2.jpg
        |-- ...

Una vez que esté todo listo, ejecuta el siguiente comando:

docker run -it --name hailo_container \
    --privileged \
    --network host \
    -v /dev:/dev \
    -v /lib/firmware:/lib/firmware \
    -v /lib/udev/rules.d:/lib/udev/rules.d \
    -v /lib/modules:/lib/modules \
    -v //c/Users/tinte/Downloads/vehicle_detection:/workspace \
    hailo_ai_sw_suite_2024-10:1

La opción -v //c/Users/tinte/Downloads/vehicle_detection:/workspace le indica a Docker que monte el directorio local C:\Users\tinte\Downloads\vehicle_detection dentro del contenedor, en la carpeta /workspace. Esto significa que todo lo que esté dentro de la carpeta vehicle_detection (incluidos los subdirectorios models e images) va a ser accesible desde adentro del contenedor en /workspace.

Modifica la primera parte de la ruta (//c/Users/tinte/Downloads/vehicle_detection) para que apunte a la ubicación de tus propios archivos. También puedes modificar el directorio de destino (\workspace), aunque conviene mantener la consistencia con este tutorial.

Si el comando no funciona en Windows (es mi caso), prueba ejecutarlo en una sola línea:

docker run -it --name hailo_container --privileged --network host -v /dev:/dev -v /lib/firmware:/lib/firmware -v /lib/udev/rules.d:/lib/udev/rules.d -v /lib/modules:/lib/modules -v //c/Users/tinte/Downloads/vehicle_detection:/workspace hailo_ai_sw_suite_2024-10:1

Si todo salió bien, ahora estás dentro del contenedor. Navega a la carpeta workspace para encontrar tus imágenes y modelos:

Si no ves tus archivos, revisa la ruta (//c/Users/tinte/Downloads/vehicle_detection) que especificaste en el comando de Docker. Pregúntale a ChatGPT cómo especificar correctamente esa ruta en tu caso.

4. Convertir el modelo ONNX a HEF

Ya dentro del contenedor, navega al directorio de los modelos y ejecuta los siguientes comandos:

A. Parsear el modelo ONNX

hailomz parse --hw-arch hailo8l --ckpt model.onnx yolov8n

Reemplaza model.onnx por el nombre del archivo de tu modelo ONNX, y yolov8n por el nombre que quieras darle al modelo HEF. Esto crea un archivo .har, que es la representación del modelo en Hailo.

B. Optimizar el modelo

hailomz optimize --hw-arch hailo8l --calib-path ../images --resize 640 640 --classes 2 --har yolov8n.har yolov8n --performance

Este paso ajusta el modelo al hardware de Hailo aplicando optimizaciones basadas en el conjunto de calibración:

• Reemplaza ../images por la ruta a tu directorio de imágenes de calibración. No hace falta si seguiste la misma estructura que en este tutorial.
• Asegúrate de que --resize 640 640 coincida con la resolución usada durante el entrenamiento. En nuestro caso, el modelo YOLOv8 fue entrenado con imágenes de 640x640.
• --classes 2 especifica la cantidad de clases de objetos que detecta el modelo; modifícalo según el tuyo.
• --har yolov8n.har hay que reemplazarlo por el nombre del archivo .har que generaste.
• Reemplaza yolov8n por la arquitectura de modelo que uses en tu caso.
• El flag --performance prioriza la velocidad manteniendo la precisión.

Cuando el comando termina correctamente, deberías ver una salida parecida a esta:

Esto confirma que el proceso de optimización terminó y que el archivo .har actualizado se guardó.

C. Compilar el modelo a un archivo HEF

hailomz compile yolov8n --hw-arch hailo8l --calib-path ../images --resize 640 640 --classes 2 --har yolov8n.har --performance

Este último paso convierte el modelo optimizado en un archivo .hef, que ya se puede desplegar en hardware de Hailo.

• --hw-arch hailo8l especifica la arquitectura de hardware de destino. En este caso, el comando compila el modelo específicamente para el acelerador Hailo-8L. Si usas otro dispositivo Hailo, asegúrate de que este flag coincida con tu hardware.
• Reemplaza ../images por la ruta a tus imágenes de calibración.
• --har yolov8n.har especifica el archivo .har generado antes. Cambia el nombre para que coincida con el tuyo.
• Reemplaza yolov8n por la arquitectura de modelo que uses en tu caso.
• Modifica --resize 640 640 y --classes 2 según las especificaciones de tu modelo.
• El flag --performance hace que el modelo se compile para obtener la mejor velocidad de inferencia posible (opcional, lee más abajo).

Activar la optimización de rendimiento (con el flag --performance) inicia una búsqueda exhaustiva del mejor throughput, que puede alargar bastante el tiempo de compilación. Conviene compilar primero sin ese modo, para asegurarte de que la compilación funciona, y recién después activarlo.

Siguiendo estos pasos vas a convertir con éxito un modelo ONNX en un archivo HEF: