Exportação Hailo para modelos Ultralytics YOLO

A cadeia de ferramentas Hailo usa arquivos HEF para plataformas embarcadas, incluindo o Raspberry Pi AI Kit e AI HAT+, câmeras industriais, gateways de borda e PCs com IA.

Este guia percorre a exportação de modelos de detecção Ultralytics YOLO para o HEF (Hailo Executable Format) da Hailo usando o SDK Hailo Dataflow Compiler (DFC). O fluxo de trabalho começa a partir de um modelo YOLO .pt, exporta para ONNX, compila com as ferramentas Hailo e produz um arquivo .hef pronto para os aceleradores Hailo-8, Hailo-8L e Hailo-15.

Quando utilizar Hailo HEF

HEF é o artefato compilado consumido pelo HailoRT em dispositivos alvo Hailo. Utilize este guia apenas quando o seu hardware de implementação exigir especificamente Hailo HEF. Se ainda estiver a escolher hardware de borda ou alvos de exportação, comece com formatos de exportação Ultralytics diretos mais recentes, como Axelera AI ou DeepX, que fornecem um fluxo de trabalho model.export(...) suportado e melhores opções de desempenho por watt do que as implementações Hailo mais antigas.

O HEF tem um papel de implementação semelhante a formatos específicos de hardware, como RKNN para NPUs Rockchip, IMX500 para câmeras Raspberry Pi AI e Qualcomm QNN para NPUs Snapdragon, mas não é atualmente gerado diretamente pela Ultralytics.

Este fluxo de trabalho é relevante quando precisa de:

• Compatibilidade com o Raspberry Pi AI Kit: O Hailo-8L é usado no Raspberry Pi AI Kit oficial e no AI HAT+.
• Pós-processamento HailoRT: O HailoRT pode incluir non-maximum suppression YOLO no pipeline de inferência compilado.
• Compilação INT8: O Hailo DFC quantiza o modelo com imagens de calibração representativas para produzir um grafo INT8 para hardware Hailo. Saiba mais sobre model quantization.

Formato de exportação Hailo HEF

HEF é um executável específico de hardware gerado pelo Hailo Dataflow Compiler. Ele contém o grafo do modelo quantizado, alocação de memória, agendamento e pós-processamento opcional configurado para uma arquitetura Hailo alvo. Ao contrário dos formatos padrão de Export mode YOLO que são produzidos diretamente por model.export(format=...), a compilação HEF usa atualmente um fluxo de duas etapas:

1. Exportar YOLO para ONNX com a Ultralytics.
2. Usar ferramentas Hailo DFC para analisar, otimizar, quantizar e compilar o modelo ONNX em HEF.

O fluxo de trabalho completo expande-se no seguinte pipeline:

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

1. Exportar para ONNX usando Export mode da Ultralytics
2. Analisar (Parse) o modelo ONNX no formato intermediário HAR da Hailo
3. Carregar um script de modelo (.alls) com diretrizes de normalização e pós-processamento
4. Calibrar e quantizar usando imagens representativas
5. Compilar para um arquivo HEF implementável

Tarefas suportadas

Este guia foca-se em modelos de detecção de objetos Ultralytics YOLO, pois o script do modelo Hailo e a configuração NMS são específicos da cabeça de detecção.

Para implementações de segmentação de instâncias, segmentação semântica, pose, OBB e classificação, compare outros formatos de borda na tabela Export mode ou use um pipeline ONNX genérico onde o seu runtime de destino suporte a tarefa.

Notas de compatibilidade

A compatibilidade de exportação Hailo depende da cabeça do modelo, tamanho da imagem de entrada, contagem de classes, arquitetura Hailo, script do modelo (.alls) e configuração NMS. Arquivos estáticos do Hailo Model Zoo são referências úteis, mas não são modelos universais. Por exemplo, um JSON NMS criado para um modelo YOLO11n de 80 classes COCO não é correto para um modelo personalizado de 3 classes ou para um imgsz fixo diferente.

Instalação

Passo 1: Instalar Ultralytics

pip install ultralytics

Passo 2: Instalar o SDK Hailo DFC

O Hailo DFC é necessário para análise, otimização e compilação. Transfira a wheel Python do Hailo Developer Zone (é necessário registro gratuito) e instale-a:

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

Exemplo de exportação HEF YOLO11n

O script abaixo compila um modelo de detecção YOLO11n de .pt para .hef com um tamanho de entrada fixo de 640 pixels. Ele exporta para ONNX usando a Ultralytics e, em seguida, compila com o Hailo DFC usando o COCO128 como um pequeno conjunto de dados de calibração.

Antes de executar o script, transfira o arquivo de configuração NMS do YOLO11n correspondente do Hailo Model Zoo ou crie o seu próprio JSON NMS Hailo para o modelo. Reutilize este script como um ponto de partida conhecido para o YOLO11n; modelos personalizados precisam de nós finais correspondentes, diretrizes .alls e configurações 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")

O arquivo HEF resultante, como yolo11n.hef, está pronto para ser implementado num dispositivo Hailo compatível. Se estiver a compilar para o Raspberry Pi AI Kit, defina HW_ARCH = "hailo8l" antes de executar o passo de compilação.

Detalhamento passo a passo

Passo 1: Exportar para ONNX

A Ultralytics exporta o seu modelo treinado para o formato ONNX, que o Hailo DFC ingere como entrada. Defina opset=11 para uma ampla compatibilidade com DFC.

from ultralytics import YOLO

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

Passo 2: Analisar o modelo ONNX

A chamada translate_onnx_model converte o grafo ONNX na representação HAR intermediária da Hailo. A lista end_node_names diz ao DFC onde cortar o grafo antes do NMS para que a Hailo possa anexar o seu próprio pós-processamento de hardware.

from hailo_sdk_client import ClientRunner

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

Passo 3: Carregar o Script do Modelo

O script do modelo (.alls) configura a normalização de entrada, ativação de saída e pós-processamento NMS. A configuração meta_arch=yolov8 aplica-se tanto ao YOLOv8 quanto ao YOLO11, uma vez que partilham o mesmo layout de cabeça de detecção.

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)

Passo 4: Construir o conjunto de dados de calibração

A quantização INT8 requer um conjunto representativo de imagens. O script abaixo usa o COCO128, que a Ultralytics transfere automaticamente via 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"

Passo 5: Otimizar e Quantizar

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

Este passo aplica ajuste fino consciente da quantização e análise de ruído de camada. Uma GPU é fortemente recomendada; sem uma, este passo pode levar várias horas.

Passo 6: Compilar para HEF

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

Modelos suportados e nós finais

Para modelos de detecção, end_node_names identifica as saídas da cabeça de detecção ONNX que a Hailo deve compilar antes de anexar o seu pós-processamento NMS. Estes nomes variam consoante a arquitetura e podem mudar quando o grafo exportado muda.

YOLO11 e YOLOv8

O YOLO11 e o YOLOv8 partilham a mesma cabeça de detecção desacoplada. O índice da camada difere em um entre as duas famílias:

Nós finais do YOLO11 (todos os tamanhos: 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",
]

Nós finais do YOLOv8 (todos os tamanhos: 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",
]

Outras arquiteturas

Para outras arquiteturas de detecção, execute a etapa de análise sem end_node_names primeiro, leia os nós sugeridos na saída do registro do DFC e, em seguida, execute novamente com esses nós:

# 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..."

Scripts .alls predefinidos e arquivos de configuração NMS para muitas variantes do YOLO estão disponíveis no Hailo Model Zoo.

Arquiteturas de Hardware Suportadas

Defina HW_ARCH no script para corresponder ao seu dispositivo alvo antes de compilar.

Executando Inferência em Hardware Hailo

Assim que você tiver o arquivo .hef, copie-o para o seu dispositivo com tecnologia Hailo e execute a inferência usando a API Python HailoRT (pacote hailo_platform). Ao contrário das etapas de exportação do DFC, a inferência é executada diretamente no dispositivo de borda.

Passo 1: Instale o HailoRT no Dispositivo

No dispositivo alvo, instale o HailoRT e os bindings Python. Para usuários do Raspberry Pi AI Kit e AI HAT+, o guia oficial de software Raspberry Pi AI instala o HailoRT, o driver do dispositivo e os bindings Python com:

sudo apt install dkms
sudo apt install hailo-all

Para dispositivos Hailo que não sejam Raspberry Pi, instale o pacote HailoRT que corresponda ao seu dispositivo, driver e versão do SDK a partir da Hailo Developer Zone.

Os dispositivos AI HAT+ 2 usam um pacote Raspberry Pi diferente (hailo-h10-all) e fluxo de trabalho do Hailo-10H. Siga o guia de software Raspberry Pi AI para essa geração de hardware.

Passo 2: Verificação Rápida

Antes de executar a inferência em Python, confirme se o dispositivo Hailo foi reconhecido:

hailortcli fw-control identify

Você deve ver o tipo de dispositivo, a versão do firmware e o número de série impressos.

Passo 3: Executar Inferência

O script abaixo executa a detecção de objetos em uma única imagem usando o arquivo HEF compilado e a API Python hailo_platform. Ele lida com o pré-processamento, a inferência e o desenho das caixas delimitadoras (bounding boxes) a partir da saída NMS do 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 e AI HAT+

O Raspberry Pi AI Kit e o AI HAT+ de 13 TOPS usam o Hailo-8L. Para usar qualquer um dos dispositivos:

1. Defina HW_ARCH = "hailo8l" antes de compilar seu HEF na máquina x86.
2. Copie o .hef para o seu Raspberry Pi.
3. Instale o HailoRT seguindo o guia oficial de software Raspberry Pi AI.
4. Execute o script de inferência acima.

Para inferência baseada em câmera no Raspberry Pi, os exemplos picamera2 Hailo fornecem scripts prontos para uso para detecção ao vivo com o Módulo de Câmera. Você também pode comparar os caminhos de implementação do Raspberry Pi no guia Coral Edge TPU no Raspberry Pi e no guia de integração Sony IMX500.

Inferência de Vídeo com TAPPAS

Para pipelines de vídeo de alto rendimento, o TAPPAS fornece elementos GStreamer que transmitem vídeo através do chip Hailo em tempo real:

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

Consulte a documentação do TAPPAS para obter opções completas de configuração de pipeline.

Resumo

Este guia cobriu o fluxo de trabalho completo para exportar modelos de detecção Ultralytics YOLO para o formato Hailo HEF:

1. Exportação para ONNX com Ultralytics (model.export(format="onnx")).
2. Analise o modelo ONNX com o Hailo DFC e especifique os nós finais da cabeça de detecção.
3. Configure a normalização e o NMS através de um script de modelo.
4. Quantize com um conjunto de dados de calibração (COCO128 via Ultralytics).
5. Compile para um arquivo .hef pronto para Hailo-8, Hailo-8L ou Hailo-15.

Para mais detalhes, consulte a Hailo Developer Zone, a documentação da Hailo e o Hailo Model Zoo. Para outros destinos de exportação do Ultralytics, consulte os guias relacionados de ONNX, OpenVINO, TensorRT, NCNN, TFLite Edge TPU, RKNN, Sony IMX500 e Qualcomm QNN. Para comparar a velocidade e precisão do modelo exportado entre formatos, use o modo Benchmark. Para a lista completa de formatos e opções, visite a documentação do modo de exportação e a página do guia de integrações.

FAQ

Quais dispositivos Hailo são suportados?

O Hailo DFC suporta Hailo-8 (hailo8), Hailo-8L (hailo8l) e Hailo-15H (hailo15h). Veja a tabela Arquiteturas de Hardware Suportadas para o valor HW_ARCH correspondente.

Quais modelos Ultralytics podem ser exportados?

Este guia foca em modelos de detecção. Veja Tarefas Suportadas para o escopo em nível de tarefa, Notas de Compatibilidade para limites de compatibilidade de modelo e Modelos Suportados e Nós Finais para exemplos de nós finais do YOLO11 e YOLOv8.

Por que o script do modelo usa meta_arch=yolov8 para o YOLO11?

O YOLO11 usa a mesma arquitetura de cabeça de detecção desacoplada do YOLOv8. O Hailo DFC usa meta_arch=yolov8 para configuração de NMS para ambas as famílias de modelos.

Preciso de uma GPU para a etapa de otimização?

Uma GPU é fortemente recomendada para o ajuste fino sensível à quantização em runner.optimize(). Sem ela, o processo ainda funciona, mas é significativamente mais lento (várias horas contra cerca de 10-20 minutos com uma GPU).

Como encontro os nós finais corretos para o meu modelo?

Execute runner.translate_onnx_model(...) sem especificar end_node_names, em seguida use os nós de cabeça de detecção sugeridos e impressos pelo DFC. Veja Outras Arquiteturas para o comando de exemplo.

Onde posso obter o SDK Hailo DFC e os arquivos de configuração NMS?

O Python wheel do SDK Hailo DFC está disponível na Hailo Developer Zone, enquanto os scripts .alls predefinidos e arquivos de configuração NMS estão disponíveis no Hailo Model Zoo.