Ultralytics YOLO 모델을 위한 Hailo 내보내기(Export)

Hailo 툴체인은 Raspberry Pi AI Kit 및 AI HAT+, 산업용 카메라, 엣지 게이트웨이, AI PC를 포함한 임베디드 플랫폼에서 HEF 파일을 사용합니다.

이 가이드는 Ultralytics YOLO 탐지 모델을 Hailo Dataflow Compiler (DFC) SDK를 사용하여 Hailo의 **HEF (Hailo Executable Format)**로 내보내는 과정을 안내합니다. 이 워크플로우는 YOLO .pt 모델에서 시작하여 ONNX로 내보낸 뒤, Hailo 도구로 컴파일하여 Hailo-8, Hailo-8L, Hailo-15 가속기에 적합한 .hef 파일을 생성합니다.

Hailo HEF 사용 시기

HEF is the compiled artifact consumed by HailoRT on Hailo target devices. Use this guide only when your deployment hardware specifically requires Hailo HEF. If you are still choosing edge hardware or export targets, start with newer direct Ultralytics export formats such as Axelera AI or DeepX, which provide a supported model.export(...) workflow and better performance-per-watt options than older Hailo deployments.

HEF는 Rockchip NPU용 RKNN, Raspberry Pi AI 카메라용 IMX500, Snapdragon NPU용 Qualcomm QNN과 같은 하드웨어 전용 형식과 배포 역할이 유사하지만, 현재 Ultralytics에서 직접 생성되지는 않습니다.

이 워크플로우는 다음과 같은 경우에 유용합니다:

• Raspberry Pi AI Kit 호환성: Hailo-8L은 공식 Raspberry Pi AI Kit 및 AI HAT+에 사용됩니다.
• HailoRT 후처리(Post-processing): HailoRT는 컴파일된 추론 파이프라인에 YOLO non-maximum suppression을 포함할 수 있습니다.
• INT8 컴파일: Hailo DFC는 대표 보정 이미지를 사용하여 모델을 양자화하고 Hailo 하드웨어를 위한 INT8 그래프를 생성합니다. model quantization에 대해 더 알아보십시오.

Hailo HEF 내보내기 형식

HEF is a hardware-specific executable generated by the Hailo Dataflow Compiler. It contains the quantized model graph, memory allocation, scheduling, and optional post-processing configured for a target Hailo architecture. Unlike standard YOLO Export mode formats that are produced directly by model.export(format=...), HEF compilation currently uses a two-stage flow:

1. Ultralytics를 사용하여 YOLO를 ONNX로 내보냅니다.
2. Hailo DFC 도구를 사용하여 ONNX 모델을 구문 분석, 최적화, 양자화 및 HEF로 컴파일합니다.

전체 워크플로우는 다음 파이프라인으로 확장됩니다:

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

1. Ultralytics Export mode를 사용하여 ONNX로 내보내기
2. ONNX 모델을 Hailo의 중간 HAR 형식으로 구문 분석(Parse)
3. 정규화 및 후처리 지시문이 포함된 모델 스크립트(.alls) 로드
4. 대표 이미지를 사용하여 보정(Calibrate) 및 양자화(Quantize)
5. 배포 가능한 HEF 파일로 컴파일

지원되는 작업

이 가이드는 Ultralytics YOLO 객체 탐지(object detection) 모델에 집중합니다. Hailo 모델 스크립트와 NMS 구성이 탐지 헤드(detection-head)에 특화되어 있기 때문입니다.

인스턴스 세분화, 의미론적 세분화, 포즈, OBB 및 분류 배포의 경우, Export mode 표에서 다른 엣지 형식을 비교하거나 대상 런타임이 해당 작업을 지원하는 경우 일반적인 ONNX 파이프라인을 사용하십시오.

호환성 참고 사항

Hailo 내보내기 호환성은 모델 헤드, 입력 이미지 크기, 클래스 수, Hailo 아키텍처, 모델 스크립트(.alls) 및 NMS 구성에 따라 달라집니다. Hailo Model Zoo의 정적 파일은 유용한 참조 자료이지만 범용 템플릿은 아닙니다. 예를 들어, COCO 80 클래스 YOLO11n 모델용으로 생성된 NMS JSON은 3 클래스 사용자 정의 모델이나 다른 고정 imgsz에는 올바르지 않습니다.

설치

1단계: Ultralytics 설치

pip install ultralytics

2단계: Hailo DFC SDK 설치

구문 분석, 최적화 및 컴파일을 위해서는 Hailo DFC가 필요합니다. Hailo Developer Zone에서 Python 휠을 다운로드(무료 등록 필요)하고 설치하십시오:

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

YOLO11n HEF 내보내기 예제

아래 스크립트는 고정된 640픽셀 입력 크기에서 YOLO11n 탐지 모델을 .pt에서 .hef로 컴파일합니다. Ultralytics를 사용하여 ONNX로 내보낸 다음, COCO128을 작은 보정 데이터셋으로 사용하여 Hailo DFC로 컴파일합니다.

스크립트를 실행하기 전에 Hailo Model Zoo에서 일치하는 YOLO11n NMS 구성 파일을 다운로드하거나 모델에 맞는 Hailo NMS JSON을 직접 만드십시오. 이 스크립트를 알려진 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")

yolo11n.hef와 같이 생성된 HEF 파일은 호환되는 Hailo 장치에 배포할 준비가 되었습니다. Raspberry Pi AI Kit용으로 컴파일하는 경우, 컴파일 단계를 실행하기 전에 HW_ARCH = "hailo8l"로 설정하십시오.

단계별 분석

1단계: ONNX로 내보내기

Ultralytics는 학습된 모델을 ONNX 형식으로 내보내며, Hailo DFC는 이를 입력으로 받아들입니다. 폭넓은 DFC 호환성을 위해 opset=11을 설정하십시오.

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 그래프를 Hailo의 중간 HAR 표현으로 변환합니다. end_node_names 목록은 Hailo가 고유한 하드웨어 후처리를 연결할 수 있도록 NMS 이전의 그래프를 어디서 끊을지 DFC에 알려줍니다.

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 양자화에는 대표적인 이미지 세트가 필요합니다. 아래 스크립트는 Ultralytics가 check_det_dataset을 통해 자동으로 다운로드하는 COCO128을 사용합니다:

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

이 단계는 양자화 인식 미세 조정(quantization-aware fine-tuning) 및 레이어 노이즈 분석을 적용합니다. GPU 사용을 강력히 권장합니다; GPU가 없으면 이 단계에 몇 시간이 걸릴 수 있습니다.

6단계: HEF로 컴파일

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

지원되는 모델 및 끝 노드

탐지 모델의 경우 end_node_names는 Hailo가 NMS 후처리를 연결하기 전에 컴파일해야 하는 ONNX 탐지 헤드 출력을 식별합니다. 이 이름들은 아키텍처에 따라 다르며 내보낸 그래프가 변경될 때 바뀔 수 있습니다.

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

많은 YOLO 변형을 위한 사전 정의된 .alls 스크립트와 NMS 구성 파일은 Hailo Model Zoo에서 확인할 수 있습니다.

지원되는 하드웨어 아키텍처

컴파일하기 전에 스크립트의 HW_ARCH를 대상 장치에 맞게 설정하십시오.

Hailo 하드웨어에서 추론 실행

.hef 파일을 확보한 후, 이를 Hailo 기반 장치에 복사하고 HailoRT Python API(hailo_platform 패키지)를 사용하여 추론을 실행하십시오. DFC 내보내기 단계와 달리, 추론은 엣지 장치에서 직접 실행됩니다.

1단계: 장치에 HailoRT 설치

대상 장치에 HailoRT와 Python 바인딩을 설치하십시오. Raspberry Pi AI Kit 및 AI HAT+ 사용자의 경우, 공식 Raspberry Pi AI 소프트웨어 가이드에 따라 다음 명령어로 HailoRT, 장치 드라이버 및 Python 바인딩을 설치할 수 있습니다:

sudo apt install dkms
sudo apt install hailo-all

Raspberry Pi가 아닌 Hailo 장치의 경우, Hailo Developer Zone에서 사용 중인 장치, 드라이버 및 SDK 버전에 맞는 HailoRT 패키지를 설치하십시오.

AI HAT+ 2 장치는 다른 Raspberry Pi 패키지(hailo-h10-all)와 Hailo-10H 워크플로를 사용합니다. 해당 하드웨어 세대에 대해서는 Raspberry Pi AI 소프트웨어 가이드를 따르십시오.

2단계: 빠른 정상 작동 확인

Python 추론을 실행하기 전에 Hailo 장치가 인식되는지 확인하십시오:

hailortcli fw-control identify

장치 유형, 펌웨어 버전 및 일련 번호가 출력되는지 확인해야 합니다.

3단계: 추론 실행

아래 스크립트는 컴파일된 HEF 파일과 hailo_platform Python API를 사용하여 단일 이미지에 대해 객체 탐지를 실행합니다. 이 스크립트는 전처리, 추론, 그리고 HailoRT NMS 출력에서 바운딩 박스를 그리는 과정을 처리합니다.

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와 13 TOPS AI HAT+는 Hailo-8L을 사용합니다. 두 장치를 모두 사용하려면:

1. x86 머신에서 HEF를 컴파일하기 전에 HW_ARCH = "hailo8l"로 설정하십시오.
2. .hef 파일을 Raspberry Pi로 복사하십시오.
3. 공식 Raspberry Pi AI 소프트웨어 가이드에 따라 HailoRT를 설치하십시오.
4. 위의 추론 스크립트를 실행하십시오.

Raspberry Pi에서 카메라 기반 추론을 수행하려면 picamera2 Hailo 예제에서 카메라 모듈을 사용한 실시간 탐지용 스크립트를 제공합니다. 또한 Coral Edge TPU on Raspberry Pi 가이드 및 Sony IMX500 통합 가이드에서 Raspberry Pi 배포 경로를 비교할 수 있습니다.

TAPPAS를 이용한 비디오 추론

고처리량 비디오 파이프라인의 경우, TAPPAS는 실시간으로 Hailo 칩을 통해 비디오를 스트리밍하는 GStreamer 요소를 제공합니다:

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. Ultralytics를 사용하여 ONNX로 내보내기 (model.export(format="onnx")).
2. Hailo DFC로 ONNX 모델을 파싱하고 탐지 헤드 엔드 노드 지정.
3. 모델 스크립트를 통해 정규화 및 NMS 구성.
4. 보정 데이터세트(Ultralytics를 통한 COCO128)로 양자화.
5. Hailo-8, Hailo-8L 또는 Hailo-15용 .hef 파일로 컴파일.

추가 세부 정보는 Hailo Developer Zone, Hailo 문서 및 Hailo Model Zoo를 참조하십시오. 다른 Ultralytics 내보내기 대상은 관련 ONNX, OpenVINO, TensorRT, NCNN, TFLite Edge TPU, RKNN, Sony IMX500 및 Qualcomm QNN 가이드를 참조하십시오. 형식 간의 내보낸 모델 속도와 정확도를 비교하려면 벤치마크 모드를 사용하십시오. 전체 형식 및 옵션 목록은 내보내기 모드 문서와 통합 가이드 페이지를 방문하십시오.

자주 묻는 질문(FAQ)

지원되는 Hailo 장치는 무엇입니까?

The Hailo DFC supports Hailo-8 (hailo8), Hailo-8L (hailo8l), and Hailo-15H (hailo15h). See the Supported Hardware Architectures table for the matching HW_ARCH value.

내보낼 수 있는 Ultralytics 모델은 무엇입니까?

이 가이드는 탐지 모델에 중점을 둡니다. 작업 수준 범위는 지원되는 작업을, 모델 호환성 제한은 호환성 참고 사항을, YOLO11 및 YOLOv8 엔드 노드 예제는 지원되는 모델 및 엔드 노드를 참조하십시오.

모델 스크립트에서 YOLO11에 meta_arch=yolov8을 사용하는 이유는 무엇입니까?

YOLO11은 YOLOv8과 동일한 디커플링된 탐지 헤드 아키텍처를 사용합니다. Hailo DFC는 두 모델 제품군 모두에 대해 NMS 구성 시 meta_arch=yolov8을 사용합니다.

최적화 단계에 GPU가 필요합니까?

runner.optimize()에서 양자화 인식 미세 조정(quantization-aware fine-tuning)을 수행할 때는 GPU 사용을 강력히 권장합니다. GPU 없이도 프로세스는 작동하지만 훨씬 느립니다(GPU 사용 시 약 10~20분 소요되는 것과 비교하여 수 시간 소요).

모델에 적합한 엔드 노드는 어떻게 찾습니까?

Run runner.translate_onnx_model(...) without specifying end_node_names, then use the suggested detection-head nodes printed by the DFC. See Other Architectures for the example command.

Hailo DFC SDK와 NMS 구성 파일은 어디에서 얻을 수 있습니까?

Hailo DFC SDK Python 휠은 Hailo Developer Zone에서 제공되며, 사전 정의된 .alls 스크립트와 NMS 구성 파일은 Hailo Model Zoo에서 사용할 수 있습니다.