Введение
Уже некоторое время увлекаюсь машинным обучением и нейросетями. В какой‑то момент стало интересно снабдить имеющуюся Raspberry Pi 5 нейрочипом, который берет на себя нагрузку по работе с нейронными моделями. В качестве первого экземпляра для тренировки и опытов был приобретен модуль Pi AI Hat+ с чипом Hailo-8L на борту. Данная версия является младшей в линейке и характеризуется производтельностью 13 TOPS. На следующем по рангу модуле стоит уже чип Hailo-8 с 26 TOPS. Подробнее про разновидности, характеристики и первичные настройки можно прочитать тут.
Но дело в том, что просто так модельки запустить на этом чипе не получится, так как он не принимает стандартные экспорты типа onnx. Чипу нужен свой бинарник hef, который можно скомпилировать специальным ПО. Называется оно Hailo DataFlow Compiler (DFC). Скачать его можно с фирменного сайта Hailo, предварительно там зарегистрировавшись. К слову, DFC работает только на Linux, версии для Win нету. Для компиляции моделей само железо (Raspberry Pi) не обязательно, а скорее будет не очень подходяще, так как медленное. Процесс ресурсоемкий, поэтому лучше делать это на ПК с Ubuntu, в моем случае 24.04.
Установки DFC оказалось мало, при попытке двумя кликами скомпилировать нужный файл столкнулся с проблемами, чтобы решить которые пришлось покопаться. Собственно, чтобы самому не забыть в будущем (и можно было подсмотреть) и заодно чтобы следующим путникам было проще, решил написать статью. Пишу от руки, без ИИ, и если что, то нужно «понять и простить».
Итак, в этой статье мы разберем, как взять готовую модель (например, YOLO), оптимизировать ее и скомпилировать в проприетарный формат .hef для запуска на NPU Hailo. На сайте Hailo подробно описан процесс установки DFC, на нем останавливаться не будем. Тормознем только на процессе компиляции.
1. Экспорт модели в onnx.
Сначала нужно принять во внимание, что hef не понимает динамические входы, поэтому при экспорте сразу это учитываем.
from ultralytics import YOLO
print("Подгрузка модели")
model = YOLO("yolov8n.pt")
print("Экспорт модели")
model_onnx = model.export(
format="onnx",
imgsz=(480, 640),
dynamic=False,
simplify=True
)
print("Экспорт выполнен")
Для «своего» кода у меня в привычку вошло вместо закомментенных пояснений писать принты, так проще для отладки, посему их будет много.
В результате вышенаписанного кода у нас рождается файл yolov8n.onnx
2. Парсинг.
На следующем этапе нужно провести так называемый парсинг модели и создать специальный промежуточных архивный har‑ файл (Hailo Archive). Это некий предварительный контейнер для нейросети. И вот тут начинается интересное. Чип Hailo не может съесть всю модель целиком за один присест. Причины следующие:
Чип изначально рассчитан на статические матричные вычисления (свертки), а постобработка гибкая и быстрее выполнится в CPU.
Конечные слои модели содержат динамические слои типа Reshape/Transpose и алгоритм Non Maximum Supression (NMS), а чип Hailo не умеет работать с такими узлами.
Настройки уверенности (Confidence Threshold) иногда приходится корректировать, как и параметры NMS. И для любого изменения, если бы они жестко зашивались в скомпилированный бинарник hef, пришлось бы заново его компилировать.
Перед созданием har‑файла на модель нужно посмотреть через приложение Netron, которое доступно в виде web‑приложения. Открываем нашу onnx модель в этом приложении и почти в конце графа находим узлы свертки, на которых мы обрежем сеть для har‑файла.
Эти узлы нужно обозначить как конечные. Выглядит это так:
from hailo_sdk_client import ClientRunner
TARGET_CHIP = "hailo8l"
END_NODES = [
"/model.22/cv2.0/cv2.0.2/Conv",
"/model.22/cv3.0/cv3.0.2/Conv",
"/model.22/cv2.1/cv2.1.2/Conv",
"/model.22/cv3.1/cv3.1.2/Conv",
"/model.22/cv2.2/cv2.2.2/Conv",
"/model.22/cv3.2/cv3.2.2/Conv",
]
print("Формирование har")
runner = ClientRunner(hw_arch=TARGET_CHIP)
runner.translate_onnx_model(
"yolov8n.onnx",
end_node_names=END_NODES
)
Далее сохраняем har‑файл, он нам понадобится.
print("Сохранение har файла модели")
runner.save_har("yolov8n.har")
3. Подготовка конфигурации
Теперь нужно подготовить конфигурационные файлы для компиляции. Они включают в себя alls‑файл (Allocator Script) и json.
В alls‑файле нужно указать параметры нормализации и NMS. Но помимо этого нужно еще указать наши ветки классификации (их у нас три из разных слоев нейросети), для которых нужно применить сигмоидную функцию, чтобы в результате значения на выходе у них были в диапазоне [0, 1].
И чтобы получить правильные названия этих узлов классификации, какими они обзываются в подготовленном контейнере har, нам нужно этот har так же, как и перед этим onnx, открыть через Netron.
В приложении слева сразу выбираем пункт с характеристиками (Properties):
И справа видим нужную нам информацию:
Из этого сейчас нам потребуются только узлы с классификацией, у которых shape заканчивается на 80 (последняя размерность, указывающая на количество детектируемых классов модели).
Т.е. нам нужны conv42, conv53 и conv63
Создаем alls со следующим содержимым:
nomalization1 = normalization([0.0, 0.0, 0.0], [255.0, 255.0, 255.0])
change_output_activation(conv42, sigmoid)
change_output_activation(conv53, sigmoid)
change_output_activation(conv63, sigmoid)
nms_postprocess("yolov8n.json", meta_arch=yolov8, engine=cpu)
allocator_param(width_splitter_defuse=disabled)
Также создаем соответствующий json, в котором прописываем «динамические» параметры будущей модели:
{
"nms_scores_th": 0.2,
"nms_iou_th": 0.6,
"image_dims": [
480,
640
],
"max_proposals_per_class": 100,
"classes": 80,
"regression_length": 16,
"background_removal": false,
"bbox_decoders": [
{
"name": "bbox_decoder02",
"stride": 8,
"reg_layer": "conv41",
"cls_layer": "conv42"
},
{
"name": "bbox_decoder12",
"stride": 16,
"reg_layer": "conv52",
"cls_layer": "conv53"
},
{
"name": "bbox_decoder22",
"stride": 32,
"reg_layer": "conv62",
"cls_layer": "conv63"
}
]
}
В json также указываем названия наших нод (уже всех: и для регрессии рамок, и для классификации), соответствующие им страйды, количество классов и размерность входа с параметрами порогов.
Подгружаем эти данные в заготовку для компиляции:
print("Загружаем alls")
runner.load_model_script("yolov8n.alls")
4. Квантование модели
Для формирования целочесленных весов нам нужно прогнать приближенные к целевым изображения через модель, чтобы откалибровать правильные коэффициенты нейронов. Для этого можно использовать имеющийся в ultralytics датасет, предварительно сформировав из него нужный нам набор (обращаем внимание на размерности):
import numpy as np
from PIL import Image
from ultralytics.utils import DATASETS_DIR
from ultralytics.data.utils import check_det_dataset
CALIB_IMAGES = 128
print("Создаем датасет")
check_det_dataset("coco128.yaml")
calib_dir = DATASETS_DIR/"coco128"/"images"/"train2017"
image_files = list(calib_dir.glob("*.jpg")) + list(calib_dir.glob("*.png"))
if not image_files:
raise FileNotFoundError(f"No calibration images found in {calib_dir}")
calibset = np.zeros((CALIB_IMAGES, 480, 640, 3), dtype=np.float32)
for i in range(CALIB_IMAGES):
img = Image.open(np.random.choice(image_files)).convert("RGB").resize((640, 480))
calibset[i] = np.array(img, dtype=np.float32)
Этот датасет прогоняем через заготовку модели:
print("Оптимизируем веса к датасету")
runner.optimize(calibset)
После чего можно для себя сохранить уже оптимизированную модель:
print("Сохранение оптимизированного har-файла")
runner.save_har(f"{MODEL}.o.har")
5. Компиляция
Мы подошли к завершающему этапу. Теперь можно скомпилировать преследуемый бинарник соответствующим методом, компилятор распределяет веса модели по вычислительным элементам чипа Hailo.
hef = runner.compile()
После чего сохраняем наш скомпилированный hef.
with open(f"{MODEL}.hef", "wb") as f:
f.write(hef)
Также можно сделать командой:
# Компиляция через CLI (указываем архитектуру чипа, для RPi это hailo8l)
hailo compiler yolov8n_quantized.har --hw-arch hailo8l --output-edf yolov8n.hef
Но я сделал первым методом. Второй для справки.
Заключение
Файл yolov8n.hef готов к переносу на Raspberry Pi 5. Его можно запускать через hailortcli или использовать в пайплайнах GStreamer.
Если моя инструкция вам помогла, плюсаните.
Ниже полный листинг:
from hailo_sdk_client import ClientRunner
import numpy as np
from PIL import Image
from ultralytics.utils import DATASETS_DIR
from ultralytics.data.utils import check_det_dataset
# НАСТРОЙКИ
MODEL = "yolov8n"
model = "yolov8n.onnx"
TARGET_CHIP = "hailo8l"
END_NODES = [
"/model.22/cv2.0/cv2.0.2/Conv",
"/model.22/cv3.0/cv3.0.2/Conv",
"/model.22/cv2.1/cv2.1.2/Conv",
"/model.22/cv3.1/cv3.1.2/Conv",
"/model.22/cv2.2/cv2.2.2/Conv",
"/model.22/cv3.2/cv3.2.2/Conv",
]
CALIB_IMAGES = 128
print("Формирование har")
runner = ClientRunner(hw_arch=TARGET_CHIP)
runner.translate_onnx_model("yolov8n.onnx", end_node_names=END_NODES)
print("Сохранение har файла модели")
runner.save_har("yolov8n.har")
print("Выходные слои модели")
hn_model = runner.get_hn_model()
for layer in hn_model.get_output_layers():
print(layer.name)
print("Загружаем alls")
runner.load_model_script("yolov8n.alls")
print("Создаем датасет")
check_det_dataset("coco128.yaml")
calib_dir = DATASETS_DIR/"coco128"/"images"/"train2017"
image_files = list(calib_dir.glob("*.jpg")) + list(calib_dir.glob("*.png"))
if not image_files:
raise FileNotFoundError(f"No calibration images found in {calib_dir}")
calibset = np.zeros((CALIB_IMAGES, 480, 640, 3), dtype=np.float32)
for i in range(CALIB_IMAGES):
img = Image.open(np.random.choice(image_files)).convert("RGB").resize((640, 480))
calibset[i] = np.array(img, dtype=np.float32)
print("Оптимизируем веса к датасету")
runner.optimize(calibset)
print("Сохранение оптимизированного har-файла")
runner.save_har(f"{MODEL}.o.har")
hef = runner.compile()
with open(f"{MODEL}.hef", "wb") as f:
f.write(hef)