Ultralytics YOLO Modelleri için Hailo Dışa Aktarımı

Hailo araç zinciri; Raspberry Pi AI Kit, AI HAT+, endüstriyel kameralar, uç geçitler ve AI PC'ler dahil olmak üzere gömülü platformlar için HEF dosyalarını kullanır.

Bu kılavuz, Ultralytics YOLO algılama modellerini Hailo Dataflow Compiler (DFC) SDK'sını kullanarak Hailo'nun HEF (Hailo Executable Format) formatına aktarma sürecini adım adım açıklar. İş akışı bir YOLO .pt modelinden başlar, ONNX formatına aktarılır, Hailo araçlarıyla derlenir ve Hailo-8, Hailo-8L ve Hailo-15 hızlandırıcıları için hazır bir .hef dosyası üretir.

Hailo HEF Ne Zaman Kullanılır

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, dağıtım rolü açısından Rockchip NPU'lar için RKNN, Raspberry Pi AI Kameralar için IMX500 ve Snapdragon NPU'lar için Qualcomm QNN gibi donanıma özel formatlara benzer, ancak şu anda doğrudan Ultralytics tarafından oluşturulmamaktadır.

Bu iş akışı şu durumlarda geçerlidir:

• Raspberry Pi AI Kit uyumluluğu: Hailo-8L, resmi Raspberry Pi AI Kit ve AI HAT+'da kullanılır.
• HailoRT son işleme (post-processing): HailoRT, derlenmiş çıkarım hattına YOLO non-maximum suppression (NMS) işlemini dahil edebilir.
• INT8 derleme: Hailo DFC, Hailo donanımı için bir INT8 grafiği oluşturmak amacıyla modeli temsili kalibrasyon görüntüleriyle niceler. model quantization hakkında daha fazla bilgi edin.

Hailo HEF Dışa Aktarım Formatı

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 ile YOLO'yu ONNX formatına aktar.
2. ONNX modelini HEF'e ayrıştırmak, optimize etmek, nitelemek ve derlemek için Hailo DFC araçlarını kullan.

Tüm iş akışı şu aşamalardan oluşur:

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

1. Ultralytics Export mode kullanarak ONNX'e aktar
2. ONNX modelini Hailo'nun ara HAR formatına ayrıştır
3. Normalizasyon ve son işleme yönergelerini içeren bir model betiği (.alls) yükle
4. Temsili görüntüler kullanarak kalibre et ve nitele
5. Dağıtılabilir bir HEF dosyasına derle

Desteklenen Görevler

Bu kılavuz Ultralytics YOLO nesne algılama modellerine odaklanır, çünkü Hailo model betiği ve NMS yapılandırması algılama başlığına (detection-head) özeldir.

Örnek bölütleme, anlamsal bölütleme, poz, OBB ve sınıflandırma dağıtımları için, Export mode tablosundaki diğer uç formatları karşılaştır veya hedef çalışma zamanının görevi desteklediği genel bir ONNX hattı kullan.

Uyumluluk Notları

Hailo dışa aktarım uyumluluğu; model başlığına, giriş görüntüsü boyutuna, sınıf sayısına, Hailo mimarisine, model betiğine (.alls) ve NMS yapılandırmasına bağlıdır. Hailo Model Zoo üzerindeki statik dosyalar yararlı referanslardır, ancak bunlar evrensel şablonlar değildir. Örneğin, 80 sınıflı bir COCO YOLO11n modeli için oluşturulan bir NMS JSON, 3 sınıflı özel bir model veya farklı bir sabit imgsz için doğru değildir.

Kurulum

Adım 1: Ultralytics'i Kur

pip install ultralytics

Adım 2: Hailo DFC SDK'yı Kur

Ayrıştırma, optimizasyon ve derleme için Hailo DFC gereklidir. Python wheel dosyasını Hailo Developer Zone üzerinden indir (ücretsiz kayıt gereklidir) ve kur:

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

YOLO11n HEF Dışa Aktarım Örneği

Aşağıdaki betik, bir YOLO11n algılama modelini .pt dosyasından sabit 640 piksel giriş boyutunda .hef formatına derler. Ultralytics kullanarak ONNX'e aktarır, ardından küçük bir kalibrasyon veri seti olarak COCO128 kullanarak Hailo DFC ile derler.

Betiği çalıştırmadan önce, Hailo Model Zoo üzerinden eşleşen YOLO11n NMS yapılandırma dosyasını indir veya model için kendi Hailo NMS JSON'unu oluştur. Bu betiği bilinen bir YOLO11n başlangıç noktası olarak yeniden kullan; özel modellerin eşleşen uç düğümlere, .alls yönergelerine ve NMS ayarlarına ihtiyacı vardır.

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

Ortaya çıkan yolo11n.hef gibi HEF dosyası, uyumlu bir Hailo cihazında dağıtılmaya hazırdır. Raspberry Pi AI Kit için derleme yapıyorsan, derleme adımını çalıştırmadan önce HW_ARCH = "hailo8l" olarak ayarla.

Adım Adım İnceleme

Adım 1: ONNX'e aktar

Ultralytics, eğitilmiş modelini Hailo DFC'nin giriş olarak aldığı ONNX formatına aktarır. Geniş DFC uyumluluğu için opset=11 olarak ayarla.

from ultralytics import YOLO

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

Adım 2: ONNX Modelini ayrıştır

translate_onnx_model çağrısı, ONNX grafiğini Hailo'nun ara HAR temsiline dönüştürür. end_node_names listesi, Hailo'nun kendi donanım son işlemesini ekleyebilmesi için grafiğin NMS öncesinde nerede kesileceğini DFC'ye bildirir.

from hailo_sdk_client import ClientRunner

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

Adım 3: Model betiğini yükle

Model betiği (.alls); giriş normalizasyonunu, çıktı aktivasyonunu ve NMS son işlemesini yapılandırır. meta_arch=yolov8 ayarı, aynı algılama başlığı düzenini paylaştıkları için hem YOLOv8 hem de YOLO11 için geçerlidir.

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)

Adım 4: Kalibrasyon veri setini oluştur

INT8 nicelleştirme, temsili bir görüntü seti gerektirir. Aşağıdaki betik, Ultralytics'in check_det_dataset aracılığıyla otomatik olarak indirdiği COCO128'i kullanır:

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"

Adım 5: Optimize et ve nitele

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

Bu adım, nicelleştirme duyarlı ince ayar ve katman gürültüsü analizi uygular. Bir GPU şiddetle önerilir; bir GPU olmadan bu adım birkaç saat sürebilir.

Adım 6: HEF dosyasına derle

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

Desteklenen Modeller ve Uç Düğümler

Algılama modelleri için end_node_names, Hailo'nun NMS son işlemesini eklemeden önce derlemesi gereken ONNX algılama başlığı çıktılarını tanımlar. Bu adlar mimariye göre değişir ve dışa aktarılan grafik değiştiğinde değişebilir.

YOLO11 ve YOLOv8

YOLO11 ve YOLOv8 aynı ayrıştırılmış algılama başlığını paylaşır. Katman indeksi iki aile arasında bir fark gösterir:

YOLO11 uç düğümleri (tüm boyutlar: 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 uç düğümleri (tüm boyutlar: 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",
]

Diğer Mimariler

Diğer tespit mimarileri için önce end_node_names olmadan ayrıştırma adımını çalıştır, DFC günlük çıktısından önerilen düğümleri oku, ardından bu düğümlerle tekrar çalıştır:

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

Birçok YOLO varyantı için önceden tanımlanmış .alls betikleri ve NMS yapılandırma dosyalarına Hailo Model Zoo üzerinden ulaşabilirsin.

Desteklenen Donanım Mimarileri

Derlemeden önce betikteki HW_ARCH değerini hedef cihazınla eşleşecek şekilde ayarla.

Hailo Donanımında Çıkarım Çalıştırma

.hef dosyasını elde ettikten sonra, onu Hailo destekli cihazına kopyala ve HailoRT Python API'sini (hailo_platform paketi) kullanarak çıkarımı çalıştır. DFC dışa aktarma adımlarının aksine, çıkarım doğrudan uç cihaz üzerinde çalışır.

Adım 1: Cihaza HailoRT Yükleme

Hedef cihaz üzerinde HailoRT ve Python bağlamalarını kur. Raspberry Pi AI Kit ve AI HAT+ kullanıcıları için resmi Raspberry Pi AI yazılım kılavuzu ile HailoRT, cihaz sürücüsü ve Python bağlamaları şu şekilde kurulur:

sudo apt install dkms
sudo apt install hailo-all

Raspberry Pi dışındaki Hailo cihazları için, Hailo Developer Zone üzerinden cihazına, sürücüne ve SDK sürümüne uygun HailoRT paketini yükle.

AI HAT+ 2 cihazları farklı bir Raspberry Pi paketi (hailo-h10-all) ve Hailo-10H iş akışı kullanır. O donanım nesli için Raspberry Pi AI yazılım kılavuzunu takip et.

Adım 2: Hızlı Sağlamlık Kontrolü

Python çıkarımını çalıştırmadan önce Hailo cihazının tanındığından emin ol:

hailortcli fw-control identify

Cihaz türünün, aygıt yazılımı sürümünün ve seri numarasının yazdırıldığını görmelisin.

Adım 3: Çıkarım Çalıştırma

Aşağıdaki betik, derlenmiş HEF dosyasını ve hailo_platform Python API'sini kullanarak tek bir görüntü üzerinde nesne tespiti yapar. Ön işleme, çıkarım ve HailoRT NMS çıktısından sınırlayıcı kutuların (BBox) çizilmesi işlemlerini yönetir.

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 ve AI HAT+

Raspberry Pi AI Kit ve 13 TOPS AI HAT+ cihazları Hailo-8L kullanır. Bu cihazlardan birini kullanmak için:

1. HEF dosyanı x86 makinesinde derlemeden önce HW_ARCH = "hailo8l" olarak ayarla.
2. .hef dosyasını Raspberry Pi cihazına kopyala.
3. Resmi Raspberry Pi AI yazılım kılavuzunu izleyerek HailoRT kurulumunu yap.
4. Yukarıdaki çıkarım betiğini çalıştır.

Raspberry Pi'de kamera tabanlı çıkarım için picamera2 Hailo örnekleri, Camera Module ile canlı tespit için kullanıma hazır betikler sunar. Ayrıca Coral Edge TPU on Raspberry Pi kılavuzu ve Sony IMX500 entegrasyon kılavuzundaki Raspberry Pi dağıtım yollarını karşılaştırabilirsin.

TAPPAS ile Video Çıkarımı

Yüksek verimli video işleme hatları için TAPPAS, videoyu gerçek zamanlı olarak Hailo çipi üzerinden aktaran GStreamer öğeleri sağlar:

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

Tam işleme hattı yapılandırma seçenekleri için TAPPAS belgelerine bak.

Özet

Bu kılavuz, Ultralytics YOLO tespit modellerini Hailo HEF formatına dışa aktarmak için gereken tüm iş akışını ele aldı:

1. Ultralytics ile ONNX formatına dışa aktar (model.export(format="onnx")).
2. ONNX modelini Hailo DFC ile ayrıştır ve tespit başlığı uç düğümlerini belirt.
3. Bir model betiği ile normalleştirme ve NMS yapılandırması yap.
4. Kalibrasyon veri kümesi (Ultralytics üzerinden COCO128) ile nicemleme (quantization) yap.
5. Hailo-8, Hailo-8L veya Hailo-15 için hazır olan .hef dosyasına derle.

Daha fazla ayrıntı için Hailo Developer Zone, Hailo belgeleri ve Hailo Model Zoo kaynaklarına bak. Diğer Ultralytics dışa aktarma hedefleri için ONNX, OpenVINO, TensorRT, NCNN, TFLite Edge TPU, RKNN, Sony IMX500 ve Qualcomm QNN kılavuzlarını incele. Dışa aktarılan model hızını ve doğruluğunu formatlar arasında karşılaştırmak için Benchmark modunu kullan. Formatların ve seçeneklerin tam listesi için Dışa aktarma modu belgelerini ve entegrasyon kılavuzu sayfasını ziyaret et.

SSS

Hangi Hailo cihazları destekleniyor?

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.

Hangi Ultralytics modelleri dışa aktarılabilir?

Bu kılavuz tespit modellerine odaklanır. Görev düzeyindeki kapsam için Desteklenen Görevler, model uyumluluk sınırları için Uyumluluk Notları ve YOLO11 ile YOLOv8 uç düğüm örnekleri için Desteklenen Modeller ve Uç Düğümler bölümlerine bak.

Model betiği YOLO11 için neden meta_arch=yolov8 kullanıyor?

YOLO11, YOLOv8 ile aynı ayrıştırılmış tespit başlığı mimarisini kullanır. Hailo DFC, her iki model ailesi için NMS yapılandırmasında meta_arch=yolov8 değerini kullanır.

Optimizasyon adımı için GPU'ya ihtiyacım var mı?

runner.optimize() içinde nicemleme farkındalıklı ince ayar (quantization-aware fine-tuning) için GPU şiddetle önerilir. GPU olmadan süreç çalışır ancak önemli ölçüde daha yavaştır (bir GPU ile yaklaşık 10-20 dakika sürerken GPU'suz birkaç saat sürebilir).

Modelim için doğru uç düğümleri nasıl bulurum?

runner.translate_onnx_model(...) fonksiyonunu end_node_names belirtmeden çalıştır, ardından DFC tarafından yazdırılan önerilen tespit başlığı düğümlerini kullan. Örnek komut için Diğer Mimariler kısmına bak.

Hailo DFC SDK ve NMS yapılandırma dosyalarını nereden alabilirim?

Hailo DFC SDK Python dosyası Hailo Developer Zone adresinden temin edilebilir, önceden tanımlanmış .alls betikleri ve NMS yapılandırma dosyaları ise Hailo Model Zoo üzerinden alınabilir.