Экспорт в Hailo для моделей Ultralytics YOLO

Набор инструментов Hailo использует файлы HEF для встраиваемых платформ, включая Raspberry Pi AI Kit и AI HAT+, промышленных камер, пограничных шлюзов и AI ПК.

Это руководство описывает процесс экспорта моделей обнаружения Ultralytics YOLO в формат HEF (Hailo Executable Format) с использованием SDK Hailo Dataflow Compiler (DFC). Рабочий процесс начинается с модели YOLO .pt, экспортируется в ONNX, компилируется с помощью инструментов Hailo и выдает файл .hef, готовый для ускорителей Hailo-8, Hailo-8L и Hailo-15.

Когда использовать Hailo HEF

HEF — это скомпилированный артефакт, потребляемый HailoRT на целевых устройствах Hailo. Используй это руководство только в том случае, если твое оборудование для развертывания специально требует Hailo HEF. Если ты все еще выбираешь пограничное оборудование или цели экспорта, начни с более новых форматов прямого экспорта Ultralytics, таких как Axelera AI или DeepX, которые обеспечивают поддерживаемый рабочий процесс model.export(...) и лучшие варианты производительности на ватт, чем старые развертывания Hailo.

HEF по своей роли при развертывании похож на аппаратные форматы, такие как RKNN для NPU Rockchip, IMX500 для камер Raspberry Pi AI и Qualcomm QNN для NPU Snapdragon, но в настоящее время он не генерируется напрямую Ultralytics.

Этот рабочий процесс актуален, когда тебе нужно:

• Совместимость с Raspberry Pi AI Kit: Hailo-8L используется в официальных Raspberry Pi AI Kit и AI HAT+.
• Постобработка HailoRT: HailoRT может включать YOLO немаксимальное подавление в скомпилированный конвейер вывода.
• Компиляция INT8: Hailo DFC квантует модель с помощью репрезентативных калибровочных изображений для создания графа INT8 для оборудования Hailo. Узнай больше о квантовании моделей.

Формат экспорта Hailo HEF

HEF — это исполняемый файл, специфичный для оборудования, генерируемый Hailo Dataflow Compiler. Он содержит квантованный граф модели, распределение памяти, планирование и дополнительную постобработку, настроенную для целевой архитектуры Hailo. В отличие от стандартных форматов режима экспорта YOLO, которые создаются напрямую с помощью model.export(format=...), компиляция HEF в настоящее время использует двухэтапный процесс:

1. Экспорт YOLO в ONNX с помощью Ultralytics.
2. Использование инструментов Hailo DFC для анализа, оптимизации, квантования и компиляции модели ONNX в HEF.

Полный рабочий процесс расширяется до следующего конвейера:

YOLO (.pt) -> ONNX -> HAR (parse) -> HAR (optimize/quantize) -> HEF (compile)

1. Экспорт в ONNX с использованием режима экспорта Ultralytics
2. Анализ модели ONNX в промежуточный формат HAR от Hailo
3. Загрузка скрипта модели (.alls) с директивами нормализации и постобработки
4. Калибровка и квантование с использованием репрезентативных изображений
5. Компиляция в развертываемый файл HEF

Поддерживаемые задачи

Это руководство посвящено моделям обнаружения объектов Ultralytics YOLO, поскольку скрипт модели Hailo и конфигурация NMS зависят от конкретной головы обнаружения.

Для развертывания сегментации экземпляров, семантической сегментации, позы, OBB и классификации сравни другие пограничные форматы в таблице режима экспорта или используй общий конвейер ONNX, если целевая среда выполнения поддерживает задачу.

Примечания о совместимости

Совместимость экспорта Hailo зависит от головы модели, размера входного изображения, количества классов, архитектуры Hailo, скрипта модели (.alls) и конфигурации NMS. Статические файлы из Hailo Model Zoo являются полезными справочными материалами, но они не являются универсальными шаблонами. Например, JSON NMS, созданный для модели YOLO11n с 80 классами COCO, не подходит для пользовательской модели с 3 классами или для другого фиксированного imgsz.

Установка

Шаг 1: Установи Ultralytics

pip install ultralytics

Шаг 2: Установи Hailo DFC SDK

Hailo DFC требуется для парсинга, оптимизации и компиляции. Загрузи Python wheel из Hailo Developer Zone (требуется бесплатная регистрация) и установи его:

pip install /path/to/hailo_sdk_client-*.whl

Пример экспорта YOLO11n HEF

Приведенный ниже скрипт компилирует модель обнаружения YOLO11n из .pt в .hef с фиксированным размером ввода 640 пикселей. Он экспортирует в ONNX с помощью Ultralytics, а затем компилирует с помощью Hailo DFC, используя COCO128 в качестве небольшого набора данных для калибровки.

Перед запуском скрипта загрузи соответствующий файл конфигурации NMS YOLO11n из Hailo Model Zoo или создай свой собственный JSON NMS Hailo для модели. Используй этот скрипт повторно как известную отправную точку для YOLO11n; пользовательские модели нуждаются в соответствующих конечных узлах, директивах .alls и настройках NMS.

import random

import numpy as np
from hailo_sdk_client import ClientRunner
from PIL import Image

from ultralytics import YOLO
from ultralytics.data.utils import check_det_dataset
from ultralytics.utils import DATASETS_DIR

# Configuration
MODEL = "yolo11n"
HW_ARCH = "hailo8"  # hailo8 | hailo8l | hailo15h
IMGSZ = 640
CALIB_IMAGES = 128
NMS_CONFIG = "yolo11n_nms_config.json"  # Download or generate for your exact model.

# YOLO11 detection head end nodes. See "Supported Models and End Nodes" for YOLOv8 and other families.
END_NODES = [
    "/model.23/cv2.0/cv2.0.2/Conv",
    "/model.23/cv3.0/cv3.0.2/Conv",
    "/model.23/cv2.1/cv2.1.2/Conv",
    "/model.23/cv3.1/cv3.1.2/Conv",
    "/model.23/cv2.2/cv2.2.2/Conv",
    "/model.23/cv3.2/cv3.2.2/Conv",
]

# Step 1: Export to ONNX
model = YOLO(f"{MODEL}.pt")
model.export(format="onnx", imgsz=IMGSZ, opset=11)  # creates an ONNX file named after MODEL

# Step 2: Parse ONNX with Hailo DFC
# The DFC prints the detected end nodes after parsing; use them if unsure.
runner = ClientRunner(hw_arch=HW_ARCH)
runner.translate_onnx_model(f"{MODEL}.onnx", end_node_names=END_NODES)

# Step 3: Load model script (normalization + HailoRT NMS)
# The conv layer names are generated by DFC and can change for other model sizes/families.
alls = (
    "normalization1 = normalization([0.0, 0.0, 0.0], [255.0, 255.0, 255.0])\n"
    "change_output_activation(conv54, sigmoid)\n"
    "change_output_activation(conv65, sigmoid)\n"
    "change_output_activation(conv80, sigmoid)\n"
    f'nms_postprocess("{NMS_CONFIG}", meta_arch=yolov8, engine=cpu)\n'
    "allocator_param(width_splitter_defuse=disabled)"
)
runner.load_model_script(alls)

# Step 4: Build calibration dataset (auto-downloads COCO128)
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, IMGSZ, IMGSZ, 3), dtype=np.float32)
for i in range(CALIB_IMAGES):
    img = Image.open(random.choice(image_files)).convert("RGB").resize((IMGSZ, IMGSZ))
    calibset[i] = np.array(img, dtype=np.float32)

# Step 5: Optimize and quantize
runner.optimize(calibset)
runner.save_har(f"{MODEL}.o.har")  # optional intermediate HAR

# Step 6: Compile to HEF
hef = runner.compile()
with open(f"{MODEL}.hef", "wb") as f:
    f.write(hef)

print(f"Compiled HEF saved to: {MODEL}.hef")

Полученный файл HEF, например yolo11n.hef, готов к развертыванию на совместимом устройстве Hailo. Если ты компилируешь для Raspberry Pi AI Kit, установи HW_ARCH = "hailo8l" перед выполнением шага компиляции.

Пошаговый разбор

Шаг 1: Экспорт в ONNX

Ultralytics экспортирует твою обученную модель в формат ONNX, который Hailo DFC принимает в качестве входных данных. Установи opset=11 для широкой совместимости с DFC.

from ultralytics import YOLO

MODEL = "yolo11n"
model = YOLO(f"{MODEL}.pt")
model.export(format="onnx", imgsz=640, opset=11)

Шаг 2: Анализ модели ONNX

Вызов translate_onnx_model преобразует граф ONNX в промежуточное представление HAR от Hailo. Список end_node_names указывает DFC, где обрезать граф перед NMS, чтобы Hailo мог присоединить свою собственную аппаратную постобработку.

from hailo_sdk_client import ClientRunner

runner = ClientRunner(hw_arch="hailo8")
runner.translate_onnx_model(f"{MODEL}.onnx", end_node_names=END_NODES)

Шаг 3: Загрузка скрипта модели

Скрипт модели (.alls) настраивает нормализацию ввода, активацию вывода и постобработку NMS. Настройка meta_arch=yolov8 применяется как к YOLOv8, так и к YOLO11, поскольку они имеют одинаковую компоновку головы обнаружения.

MODEL = "yolo11n"
NMS_CONFIG = "yolo11n_nms_config.json"
alls = (
    "normalization1 = normalization([0.0, 0.0, 0.0], [255.0, 255.0, 255.0])\n"
    "change_output_activation(conv54, sigmoid)\n"
    "change_output_activation(conv65, sigmoid)\n"
    "change_output_activation(conv80, sigmoid)\n"
    f'nms_postprocess("{NMS_CONFIG}", meta_arch=yolov8, engine=cpu)\n'
    "allocator_param(width_splitter_defuse=disabled)"
)
runner.load_model_script(alls)

Шаг 4: Построение калибровочного набора данных

Квантование INT8 требует репрезентативного набора изображений. В приведенном ниже скрипте используется COCO128, который Ultralytics загружает автоматически через check_det_dataset:

from ultralytics.data.utils import check_det_dataset
from ultralytics.utils import DATASETS_DIR

check_det_dataset("coco128.yaml")  # downloads to DATASETS_DIR if not present
calib_dir = DATASETS_DIR / "coco128" / "images" / "train2017"

Шаг 5: Оптимизация и квантование

runner.optimize(calibset)
runner.save_har(f"{MODEL}.o.har")  # optional intermediate checkpoint

Этот шаг применяет тонкую настройку с учетом квантования и анализ шума слоев. Настоятельно рекомендуется использовать GPU; без него этот шаг может занять несколько часов.

Шаг 6: Компиляция в HEF

hef = runner.compile()
with open(f"{MODEL}.hef", "wb") as f:
    f.write(hef)

Поддерживаемые модели и конечные узлы

Для моделей обнаружения end_node_names идентифицирует выходы головы обнаружения ONNX, которые Hailo должен скомпилировать перед присоединением своей постобработки NMS. Эти имена варьируются в зависимости от архитектуры и могут изменяться при изменении экспортированного графа.

YOLO11 и YOLOv8

YOLO11 и YOLOv8 имеют одинаковую разделенную голову обнаружения. Индекс слоя отличается на единицу между двумя семействами:

Конечные узлы YOLO11 (все размеры: n, s, m, l, x):

END_NODES = [
    "/model.23/cv2.0/cv2.0.2/Conv",
    "/model.23/cv3.0/cv3.0.2/Conv",
    "/model.23/cv2.1/cv2.1.2/Conv",
    "/model.23/cv3.1/cv3.1.2/Conv",
    "/model.23/cv2.2/cv2.2.2/Conv",
    "/model.23/cv3.2/cv3.2.2/Conv",
]

Конечные узлы YOLOv8 (все размеры: n, s, m, l, x):

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",
]

Другие архитектуры

Для других архитектур детектирования сначала выполни шаг анализа без указания end_node_names, прочитай предложенные узлы в логах DFC, а затем запусти повторно с этими узлами:

# First pass: let the DFC suggest end nodes
runner = ClientRunner(hw_arch=HW_ARCH)
runner.translate_onnx_model(f"{MODEL}.onnx")
# Check the printed log for: "[info] In order to use HailoRT post-processing..."

Предопределенные скрипты .alls и файлы конфигурации NMS для многих вариантов YOLO доступны в Hailo Model Zoo.

Поддерживаемые аппаратные архитектуры

Установи HW_ARCH в скрипте в соответствии с твоим целевым устройством перед компиляцией.

Запуск инференса на оборудовании Hailo

Как только у тебя будет файл .hef, скопируй его на устройство под управлением Hailo и запусти инференс с помощью Python API HailoRT (пакет hailo_platform). В отличие от этапов экспорта DFC, инференс выполняется непосредственно на edge-устройстве.

Шаг 1: Установка HailoRT на устройство

На целевом устройстве установи HailoRT и Python-биндинги. Для пользователей Raspberry Pi AI Kit и AI HAT+ официальное руководство по ПО Raspberry Pi AI устанавливает HailoRT, драйвер устройства и Python-биндинги с помощью:

sudo apt install dkms
sudo apt install hailo-all

Для устройств Hailo, отличных от Raspberry Pi, установи пакет HailoRT, соответствующий твоему устройству, драйверу и версии SDK из Hailo Developer Zone.

Устройства AI HAT+ 2 используют другой пакет Raspberry Pi (hailo-h10-all) и рабочий процесс Hailo-10H. Следуй руководству по ПО Raspberry Pi AI для этого поколения оборудования.

Шаг 2: Быстрая проверка работоспособности

Перед запуском инференса на Python убедись, что устройство Hailo распознано:

hailortcli fw-control identify

Ты должен увидеть на экране тип устройства, версию прошивки и серийный номер.

Шаг 3: Запуск инференса

Приведенный ниже скрипт выполняет детекцию объектов на одном изображении, используя скомпилированный файл HEF и Python API hailo_platform. Он обрабатывает препроцессинг, инференс и отрисовку ограничивающих рамок (bounding boxes) на основе вывода NMS из HailoRT.

import numpy as np
from hailo_platform import (
    HEF,
    ConfigureParams,
    FormatType,
    HailoStreamInterface,
    InferVStreams,
    InputVStreamParams,
    OutputVStreamParams,
    VDevice,
)
from PIL import Image, ImageDraw

# Configuration
MODEL = "yolo11n"
HEF_PATH = f"{MODEL}.hef"  # path to your compiled HEF file
SOURCE = "bus.jpg"  # image path
IMGSZ = 640
CONF = 0.25

COCO_NAMES = [
    "person",
    "bicycle",
    "car",
    "motorcycle",
    "airplane",
    "bus",
    "train",
    "truck",
    "boat",
    "traffic light",
    "fire hydrant",
    "stop sign",
    "parking meter",
    "bench",
    "bird",
    "cat",
    "dog",
    "horse",
    "sheep",
    "cow",
    "elephant",
    "bear",
    "zebra",
    "giraffe",
    "backpack",
    "umbrella",
    "handbag",
    "tie",
    "suitcase",
    "frisbee",
    "skis",
    "snowboard",
    "sports ball",
    "kite",
    "baseball bat",
    "baseball glove",
    "skateboard",
    "surfboard",
    "tennis racket",
    "bottle",
    "wine glass",
    "cup",
    "fork",
    "knife",
    "spoon",
    "bowl",
    "banana",
    "apple",
    "sandwich",
    "orange",
    "broccoli",
    "carrot",
    "hot dog",
    "pizza",
    "donut",
    "cake",
    "chair",
    "couch",
    "potted plant",
    "bed",
    "dining table",
    "toilet",
    "tv",
    "laptop",
    "mouse",
    "remote",
    "keyboard",
    "cell phone",
    "microwave",
    "oven",
    "toaster",
    "sink",
    "refrigerator",
    "book",
    "clock",
    "vase",
    "scissors",
    "teddy bear",
    "hair drier",
    "toothbrush",
]

# Load HEF and connect to device
hef = HEF(HEF_PATH)
params = VDevice.create_params()
target = VDevice(params)

configure_params = ConfigureParams.create_from_hef(hef, interface=HailoStreamInterface.PCIe)
network_groups = target.configure(hef, configure_params)
network_group = network_groups[0]
network_group_params = network_group.create_params()

# Setup I/O virtual streams
input_vstreams_params = InputVStreamParams.make(network_group, quantized=False, format_type=FormatType.FLOAT32)
output_vstreams_params = OutputVStreamParams.make(network_group, quantized=False, format_type=FormatType.FLOAT32)

# Preprocess
orig = Image.open(SOURCE).convert("RGB")
ow, oh = orig.size
resized = orig.resize((IMGSZ, IMGSZ))
input_data = np.expand_dims(np.array(resized, dtype=np.float32), axis=0)  # (1,640,640,3)
input_name = hef.get_input_vstream_infos()[0].name

# Inference
with InferVStreams(network_group, input_vstreams_params, output_vstreams_params) as pipeline:
    with network_group.activate(network_group_params):
        pipeline.send({input_name: input_data})
        raw = pipeline.recv()

# Parse HailoRT NMS output and draw results
# When compiled with nms_postprocess the HEF outputs detections grouped by
# class: shape (batch, num_classes, max_dets, 5) where 5 = [y1,x1,y2,x2,score]
draw = ImageDraw.Draw(orig)
output_key = next(iter(raw.keys()))
batch_dets = raw[output_key][0]  # shape: (num_classes, max_dets, 5)

for cls_idx, cls_dets in enumerate(batch_dets):
    for det in cls_dets:
        score = float(det[4])
        if score < CONF:
            continue
        y1, x1, y2, x2 = det[:4]
        # Scale from model coords (0-640) back to original image size
        x1 = int(x1 * ow / IMGSZ)
        y1 = int(y1 * oh / IMGSZ)
        x2 = int(x2 * ow / IMGSZ)
        y2 = int(y2 * oh / IMGSZ)
        label = f"{COCO_NAMES[cls_idx]} {score:.2f}"
        draw.rectangle([x1, y1, x2, y2], outline="red", width=2)
        draw.text((x1 + 2, y1 + 2), label, fill="red")

orig.save("output.jpg")
print("Saved output.jpg")

Raspberry Pi AI Kit и AI HAT+

Raspberry Pi AI Kit и AI HAT+ на 13 TOPS используют Hailo-8L. Чтобы использовать любое из этих устройств:

1. Установи HW_ARCH = "hailo8l" перед компиляцией HEF на x86-машине.
2. Скопируй .hef на свою Raspberry Pi.
3. Установи HailoRT, следуя официальному руководству по ПО Raspberry Pi AI.
4. Запусти скрипт инференса, приведенный выше.

Для инференса на основе камеры на Raspberry Pi примеры Hailo для picamera2 предоставляют готовые скрипты для детекции в реальном времени с использованием модуля камеры. Ты также можешь сравнить пути развертывания на Raspberry Pi в руководстве по Coral Edge TPU на Raspberry Pi и руководстве по интеграции Sony IMX500.

Видео-инференс с TAPPAS

Для высокопроизводительных видеоконвейеров TAPPAS предоставляет элементы GStreamer, которые передают видео через чип Hailo в режиме реального времени:

MODEL=yolo11n
gst-launch-1.0 filesrc location=video.mp4 ! decodebin ! \
  hailonet hef-path=${MODEL}.hef ! \
  hailofilter function-name=yolov8 ! \
  hailooverlay ! autovideosink

Смотри документацию TAPPAS для получения полных вариантов настройки конвейера.

Резюме

В этом руководстве мы рассмотрели полный рабочий процесс экспорта моделей детекции Ultralytics YOLO в формат Hailo HEF:

1. Экспорт в ONNX с помощью Ultralytics (model.export(format="onnx")).
2. Анализ модели ONNX с помощью Hailo DFC и указание конечных узлов (end nodes) голов детекции.
3. Настройка нормализации и NMS с помощью скрипта модели.
4. Квантование с использованием калибровочного набора данных (COCO128 через Ultralytics).
5. Компиляция в файл .hef, готовый для Hailo-8, Hailo-8L или Hailo-15.

Для получения дополнительных подробностей посети Hailo Developer Zone, документацию Hailo и Hailo Model Zoo. Информацию о других целях экспорта Ultralytics см. в соответствующих руководствах: ONNX, OpenVINO, TensorRT, NCNN, TFLite Edge TPU, RKNN, Sony IMX500 и Qualcomm QNN. Чтобы сравнить скорость и точность экспортированных моделей между форматами, используй режим Benchmark. Полный список форматов и параметров представлен в документации по режиму экспорта и на странице руководства по интеграциям.

Часто задаваемые вопросы

Какие устройства Hailo поддерживаются?

Hailo DFC поддерживает Hailo-8 (hailo8), Hailo-8L (hailo8l) и Hailo-15H (hailo15h). См. таблицу Поддерживаемые аппаратные архитектуры для получения соответствующего значения HW_ARCH.

Какие модели Ultralytics можно экспортировать?

Это руководство посвящено моделям детекции. См. Поддерживаемые задачи для понимания охвата задач, Заметки о совместимости для ограничений совместимости моделей и Поддерживаемые модели и конечные узлы для примеров конечных узлов YOLO11 и YOLOv8.

Почему в скрипте модели используется meta_arch=yolov8 для YOLO11?

YOLO11 использует ту же архитектуру разделенной головы детекции, что и YOLOv8. Hailo DFC использует meta_arch=yolov8 для конфигурации NMS для обоих семейств моделей.

Нужен ли мне GPU для этапа оптимизации?

GPU настоятельно рекомендуется для точной настройки с учетом квантования в runner.optimize(). Без него процесс тоже работает, но значительно медленнее (несколько часов против 10-20 минут с GPU).

Как найти правильные конечные узлы для моей модели?

Запусти runner.translate_onnx_model(...) без указания end_node_names, затем используй предложенные узлы голов детекции, выведенные DFC. Смотри Другие архитектуры для примера команды.

Где я могу получить Hailo DFC SDK и файлы конфигурации NMS?

Python-wheel для Hailo DFC SDK доступен в Hailo Developer Zone, а предопределенные скрипты .alls и файлы конфигурации NMS доступны в Hailo Model Zoo.