Elinizde bir Hailo-8 M.2 modülü ya da 26 TOPS'luk Raspberry Pi AI HAT+ var ve ilk YOLO modelini çalıştırmak istiyorsunuz. Belki de henüz satın almadınız ve Hailo-8, Hailo-8L ile Hailo-10H arasında karar veriyorsunuz. Bu rehber sırasıyla şunları ele alıyor: doğru donanımı seçmek, PCIe sürücüsünü (driver) ve HailoRT çalışma zamanını x86-64 Ubuntu'ya ya da Raspberry Pi 5'e kurmak, aygıtın görüldüğünü doğrulamak, hazır derlenmiş bir YOLOv8 modeliyle ilk çıkarımı (inference) yapmak ve gerçekçi bir verim (throughput) beklentisi kurmak. Komutları ve paket adlarını Hailo'nun GitHub depoları, Hailo Model Zoo ve Raspberry Pi belgeleriyle karşılaştırdık. Sürüm numaraları Ekim 2026 durumunu yansıtıyor ve hızlı değişiyor; kurulumdan önce kendi sürümlerinizi kontrol edin.
Hailo-8 nedir, nasıl çalışır?
Hailo-8, veri akışı (dataflow) mimarisine dayanan bir yapay zeka hızlandırıcısıdır (AI accelerator, NPU). Hailo yongayı 26 TOPS olarak listeler (Raspberry Pi bu değeri INT8 için verir) ve tipik güç tüketimini 2,5 W olarak belirtir. GPU'dan farkı şudur: sinir ağının katmanları yonga üzerindeki hesaplama ve bellek birimlerine yerleştirilir, veri de bu birimler arasında akar. Hailo-8 harici DRAM kullanmaz; ihtiyaç duyduğu bellek yonganın içindedir.Bu tasarımın pratikte üç sonucu var:
- Yalnızca derlenmiş model çalışır. Yongaya ONNX ya da PyTorch dosyası veremezsiniz. Model, Hailo Dataflow Compiler (DFC) ile nicemlenmeli (quantization) ve hedef yonga için bir HEF (Hailo Executable Format) dosyasına derlenmelidir.
- Ana işlemciye yine iş düşer. Video çözme (decode), yeniden boyutlandırma, renk dönüşümü ve çoğu zaman son işlem (post-processing) ana makinede (host) yapılır. Model Zoo'daki YOLOv8 HEF'lerinde bile NMS (non-maximum suppression) adımını HailoRT ana işlemcide çalıştırır; modelin .alls betiğinde engine=cpu yazar.
- Sığmayan model bölünür. Büyük bir ağ birden çok bağlama (context) ayrılır ve yonga bu bağlamlar arasında geçiş yapar. Bu durum verimi düşürür ve PCIe bant genişliğini önemli hale getirir; batch boyutu konusunda buna döneceğiz.
Hailo-8 farklı biçimlerde satılıyor: dört hatlı (x4) PCIe Gen 3 arayüzlü M.2 Key M modül, iki hatlı (x2) M.2 Key B+M ve 2230 boyutlu Key A+E modüller, birden çok Hailo-8 taşıyan ve Hailo'nun 52-208 TOPS aralığında listelediği Century PCIe kartları ve Raspberry Pi AI HAT+ 26 TOPS. Mini PCIe modülü ise Hailo-8R adıyla 13 TOPS ve PCIe Gen 3 x1 olarak listeleniyor; mPCIe kart alırken bu farka dikkat edin. Hailo-10H farklı bir yol izler ve modül üzerinde kendi LPDDR4/4X belleğiyle gelir (Hailo'nun M.2 modülünde 4 veya 8 GB). Büyük dil modellerini (LLM) mümkün kılan da bu bellektir.
Hailo-8, Hailo-8L ve Hailo-10H karşılaştırması
| Özellik | Hailo-8 | Hailo-8L | Hailo-10H |
|---|---|---|---|
| Hailo'nun verdiği tepe değer | 26 TOPS (INT8) | 13 TOPS (INT8) | 40 TOPS (INT4), 20 TOPS (INT8) |
| Tipik güç (Hailo) | 2,5 W | 1,5 W | 2,5 W (M.2 modül) |
| Bellek | Yonga içi, harici DRAM yok | Yonga içi, harici DRAM yok | Modül üzerinde 4 veya 8 GB LPDDR4/4X |
| HailoRT serisi | 4.x (hailo8 dalı) | 4.x (hailo8 dalı) | 5.x |
| Raspberry Pi ürünü | AI HAT+ 26 TOPS | AI HAT+ 13 TOPS, AI Kit (üretimi durdu) | AI HAT+ 2 (8 GB) |
| Raspberry Pi paketi | hailo-all | hailo-all | hailo-h10-all |
| LLM ve VLM | Hayır | Hayır | Evet (Raspberry Pi belgelerine göre yaklaşık 6 milyar parametreye kadar) |
Seçimi kabaca şöyle yapabilirsiniz. Birden çok kamerada nesne tespiti, aynı anda iki ya da üç model (örneğin tespit ve sınıflandırma) veya YOLOv8m gibi orta boy modeller hedefliyorsanız Hailo-8 alın. Hailo-8L aynı yazılım yığınını kullanır, ama Hailo topluluk forumundaki yanıtlara göre Hailo-8'in yarısı kadar hesaplama birimine sahiptir; tek kamera ve hafif modeller için çoğu zaman yeterlidir. Raspberry Pi'da küçük bir dil modeli ya da görüntü-dil modeli (VLM) çalıştıracaksanız seçenek Hailo-10H tabanlı AI HAT+ 2'dir; Raspberry Pi belgeleri AI HAT+ için LLM desteğini "Not supported" (desteklenmiyor) olarak listeler. INT8'de Hailo-10H'nin 20 TOPS'u kâğıt üzerinde Hailo-8'in 26 TOPS'unun altında kalır; yalnızca görüntü işleyecekseniz Hailo-10H'yi hız gerekçesiyle seçmeyin, kendi modelinizi iki yonganın Model Zoo tablolarında karşılaştırın. Son olarak, HEF belirli bir yonga için derlenir: Hailo-8 için derlenmiş bir dosya Hailo-8L'de yüklenmez. Tersi mümkündür; Hailo-8L için derlenmiş bir HEF Hailo-8'de de yüklenir, ancak daha düşük performansla çalışır.
Kurulumdan önce donanım kontrol listesi
- Ana makine: x86-64 tarafında Ubuntu 22.04 veya 24.04 LTS (desteklenen listeyi kuracağınız HailoRT sürümünün belgelerinden doğrulayın; LTS dışı sürümlerin daha yeni çekirdeklerinde sürücünün DKMS derlemesi başarısız olabilir). Raspberry Pi tarafında 64 bit Raspberry Pi OS çalışan bir Raspberry Pi 5; Raspberry Pi belgeleri artık Trixie'yi esas alıyor.
- Yuva ve hat sayısı: Key M modül, PCIe (NVMe) destekli bir M.2 M yuvası ister; yalnızca SATA destekleyen M.2 yuvalarında modül hiç görünmez. B+M modül x2 çalışır, ancak bazı B yuvalarına PCIe hiç bağlanmamıştır (yalnızca USB ya da SATA). Gerçek bağlantı genişliğini kurulumdan sonra lspci ile doğrulayacağız.
- Raspberry Pi 5 PCIe ayarı: Raspberry Pi 5'in PCIe bağlantısı tek hatlıdır (x1) ve varsayılan olarak Gen 2.0 (5 GT/s) hızında çalışır. AI HAT+ ve AI HAT+ 2'de Gen 3.0 kendiliğinden açılır. AI Kit'te ya da M.2 HAT+ üzerine taktığınız bir modülde Gen 3.0'ı elle açarsınız: sudo raspi-config ile Advanced Options > PCIe Speed menüsünden ya da /boot/firmware/config.txt dosyasına dtparam=pciex1_gen=3 satırını ekleyerek. HAT+ uyumlu olmayan üçüncü taraf adaptörlerde bağlantıyı açmak için ayrıca dtparam=pciex1 gerekir. Raspberry Pi, kartın Gen 3.0 için sertifikalı olmadığını ve bağlantının kararsız olabileceğini belirtiyor; açıklanamayan hatalarda Gen 2'ye dönüp deneyin.
- Soğutma: Yük altında yonga ısınır ve sıcaklık koruması devreye girdiğinde saat frekansını düşürür. Raspberry Pi 5 için Active Cooler, AI HAT+ 2 için kutudan çıkan ısı emici (heatsink) öneriliyor. M.2 modüllerde üreticinin ısı emicisini kullanın ve kapalı kutularda hava akışını hesaba katın.
- Güç bütçesi: Raspberry Pi 5 için resmi 27 W USB-C güç kaynağı (5 V'ta 5 A verebilir) önerilir; M.2 HAT+ bağlı aygıta en fazla 3 A verir. Hailo-8'in 2,5 W'ı tipik değerdir; tepe tüketim için modülün veri sayfasına bakın.
Sürüm uyumu: hataların çoğu buradan çıkar
Kurulum adımlarına geçmeden önce dört bileşenin birbiriyle ilişkisini bilmek sonradan saatler kazandırır:- PCIe sürücüsü ile HailoRT birebir aynı sürümde olmalıdır. HailoRT aygıtı açarken sürücünün sürümünü sorgular; ana, ara ya da yama numarasından biri farklıysa "Driver version (...) is different from library version (...)" hatasıyla durur.
- Ürün yazılımı (firmware) sürücüyle gelir. Sürücü, aygıtı tanırken (probe) Hailo-8'in ürün yazılımını /lib/firmware/hailo/hailo8_fw.bin dosyasından yükler. Yongadaki ürün yazılımının ana ve ara sürümü HailoRT ile eşleşmezse çoğu işlem reddedilir. Pratikte sürücü paketini güncellemek ürün yazılımını da günceller.
- Hailo-8 için 4.x serisi kullanılır. HailoRT deposunun ana dalı (master, 5.x serisi) yalnızca Hailo-10 ve Hailo-15 ailelerini destekler. Hailo-8, Hailo-8L ve Hailo-8R için hailo8 dalı geçerlidir; bu yazı hazırlanırken bu daldaki son sürüm 4.24.0.
- HEF, çalışma zamanından yeni olmamalıdır. Daha yeni bir DFC ile derlenmiş HEF eski HailoRT'de genellikle yüklenmez. Hailo'nun hailo-apps deposundaki eşleme şöyle: HailoRT 4.23 için Model Zoo v2.18, HailoRT 4.24 için v2.19. v2.20 ise aynı yazılım yığınına (HailoRT 4.24) yalnızca yeni modeller ekliyor.
x86-64 Ubuntu'da kurulum
Ubuntu için hazır paketler Hailo Developer Zone'un yazılım indirme sayfasındadır ve indirmek için hesapla giriş yapmanız gerekir. Aynı sürüm numarasını taşıyan üç dosya indirin; 4.24.0 için bunlar PCIe sürücüsü (hailort-pcie-driver_4.24.0_all.deb), çalışma zamanı (hailort_4.24.0_amd64.deb) ve Python sürümünüze uyan wheel (.whl) dosyasıdır. İndirirken mimariyi (x86-64), işletim sistemini ve Python sürümünü doğru seçin.
Bash:
# 1) DKMS ve çalışan çekirdeğin başlık dosyaları
sudo apt update
sudo apt install -y build-essential dkms linux-headers-$(uname -r)
# 2) Önce sürücü, sonra HailoRT; sürüm numaraları aynı olmalı
HRT=4.24.0
sudo dpkg -i hailort-pcie-driver_${HRT}_all.deb # "Do you wish to use DKMS?" -> Y
sudo dpkg -i hailort_${HRT}_amd64.deb # "activate hailort service?" -> y (çoklu süreç hizmeti)
sudo reboot
# 3) Python API'si için sanal ortam
python3 -m venv ~/hailo-venv && source ~/hailo-venv/bin/activate
python -V # 3.12 ise cp312 wheel dosyasını seçin
pip install ./hailort-${HRT}-cp312-cp312-*.whl
python -c "import hailo_platform as hp; print(hp.__version__)"DKMS, çekirdek güncellendiğinde sürücünün kendiliğinden yeniden derlenmesini sağlar; atlarsanız bir sonraki çekirdek güncellemesinden sonra aygıt kaybolur. Secure Boot açık makinelerde Ubuntu, DKMS modülünü imzalamak için bir MOK anahtarı oluşturur ve sizden bir parola ister. Yeniden başlatmada açılan MOK Manager ekranında "Enroll MOK" adımını tamamlamazsanız modül yüklenmez.
Yeniden başlattıktan sonra aygıtı katman katman doğrulayın:
Bash:
lspci -nn | grep -i hailo # PCIe veri yolunda görünüyor mu?
sudo lspci -vv -d 1e60: | grep -E "LnkCap|LnkSta" # bağlantı hızı ve hat sayısı
sudo dmesg | grep -i hailo # sürücü ve ürün yazılımı yüklendi mi?
hailortcli scan
hailortcli fw-control identifyBeklenen çıktı buna benzer; adres ve sürüm sisteminize göre değişir, alanlar da sürümden sürüme küçük farklar gösterebilir:
Kod:
04:00.0 Co-processor [0b40]: Hailo Technologies Ltd. Hailo-8 AI Processor [1e60:2864] (rev 01)
Hailo Devices:
[-] Device: 0000:04:00.0
Executing on device: 0000:04:00.0
Identifying board
Control Protocol Version: 2
Firmware Version: 4.24.0 (release,app,extended context switch buffer)
Logger Version: 0
Device Architecture: HAILO8
Serial Number: ...
Part Number: ...
Product Name: ...Raspberry Pi 5'te kurulum
Raspberry Pi'da Developer Zone hesabı gerekmez; sürücü, ürün yazılımı, HailoRT, HailoRT'nin Python API'si ve TAPPAS çekirdek kütüphaneleri Raspberry Pi OS'in apt deposundan gelir.
Bash:
sudo apt update && sudo apt full-upgrade -y
sudo rpi-eeprom-update -a
sudo reboot
# Yalnızca AI Kit ve M.2 HAT+ için PCIe Gen 3:
# sudo raspi-config -> Advanced Options > PCIe Speed > Yes
# ya da /boot/firmware/config.txt içine: dtparam=pciex1_gen=3
sudo apt install dkms
sudo apt install hailo-all # AI HAT+ (Hailo-8/8L) ve AI Kit
# sudo apt install hailo-h10-all # yalnızca AI HAT+ 2; hailo-all ile birlikte kurulamaz
sudo reboot
hailortcli fw-control identify # 26 TOPS kartta: Device Architecture: HAILO8
dmesg | grep -i hailohailo-all bir üst pakettir (metapackage): hailort, hailort-pcie-driver, python3-hailort, hailo-tappas-core, python3-hailo-tappas ve rpicam-apps-hailo-postprocess paketlerini kurar; demo modelleri de hailo-models paketiyle gelir. Kamera bağlıysa ilk görsel test için Raspberry Pi belgelerindeki hazır demo yeterlidir:
Bash:
sudo apt install rpicam-apps
rpicam-hello -t 0 --post-process-file /usr/share/rpi-camera-assets/hailo_yolov8_inference.jsonAynı dizinde YOLOv6, YOLOX, YOLOv5 ile kişi ve yüz tespiti, YOLOv5 segmentasyonu ve YOLOv8 poz tahmini için de JSON dosyaları var; adımların tamamı Raspberry Pi yapay zeka belgesinde anlatılıyor. Kendi uygulamanıza geçerken Hailo'nun hailo-apps deposundan başlayın; eski hailo-rpi5-examples deposu güncelliğini yitirdiğini belirtip hailo-apps'e yönlendiriyor. hailo-apps'teki GStreamer uygulamaları (örneğin hailo-detect --input rpi) HailoRT'nin hailonet öğesi ve TAPPAS öğeleriyle kurulur: hailonet modeli çalıştırır, hailofilter derlenmiş bir .so dosyasıyla son işlemi uygular, hailooverlay sonuçları çizer, hailoroundrobin de birden çok kamera akışını sırayla tek bir hailonet'e besler. Raspberry Pi OS, sistem Python'unu pip'e karşı koruduğu için sanal ortamınızı python3 -m venv --system-site-packages .venv ile oluşturun; aksi halde apt ile gelen hailo_platform modülünü göremezsiniz.
İlk çıkarım: hazır YOLOv8 HEF'i ile ölçüm
Hailo Model Zoo'daki hazır HEF dosyaları sürüm klasörlerinde tutulur. HailoRT 4.24 için v2.20.0, Raspberry Pi'daki 4.23 için v2.18.0 klasörünü kullanın; Hailo-8L için yoldaki hailo8 yerine hailo8l yazın.
Bash:
wget https://hailo-model-zoo.s3.eu-west-2.amazonaws.com/ModelZoo/Compiled/v2.20.0/hailo8/yolov8s.hef
hailortcli parse-hef yolov8s.hef # mimari, giriş/çıkışlar, Single ya da Multi Context
hailortcli run yolov8s.hef # rastgele girdiyle çıkarım (varsayılan 5 sn) ve FPS
hailortcli benchmark yolov8s.hef # hw_only FPS, streaming FPS, donanım gecikmesi
hailortcli run yolov8s.hef --measure-temp --measure-latencybenchmark her ölçüm kipini varsayılan olarak 15 saniye çalıştırır ve sonunda şu özeti yazar; güç satırları yalnızca güç ölçümünü destekleyen kartlarda eklenir:
Kod:
=======
Summary
=======
FPS (hw_only) = ...
(streaming) = ...
Latency (hw) = ... msPython ile en küçük çıkarım iskeleti
HailoRT 4.24'te önerilen Python arayüzü InferModel'dir ve aşağıdaki iskelet Hailo'nun kendi öğreticisindeki akışı izler. NMS'li YOLOv8 HEF'lerinde get_buffer() her sınıf için bir dizi döndürür; her satırda 0-1 aralığına normalize edilmiş (y_min, x_min, y_max, x_max, skor) değerleri bulunur.
Python:
# Gerekenler: numpy ve OpenCV (Raspberry Pi'da: sudo apt install python3-opencv)
import cv2
import numpy as np
from hailo_platform import VDevice, HailoSchedulingAlgorithm
params = VDevice.create_params()
params.scheduling_algorithm = HailoSchedulingAlgorithm.ROUND_ROBIN
with VDevice(params) as vdevice:
model = vdevice.create_infer_model("yolov8s.hef")
model.set_batch_size(1)
in_h, in_w, _ = model.input().shape # yolov8s: 640, 640, 3
with model.configure() as configured:
bindings = configured.create_bindings()
frame = cv2.imread("ornek.jpg") # OpenCV görüntüyü BGR okur
img_h, img_w = frame.shape[:2]
rgb = cv2.cvtColor(cv2.resize(frame, (in_w, in_h)), cv2.COLOR_BGR2RGB)
bindings.input().set_buffer(np.ascontiguousarray(rgb))
bindings.output().set_buffer(np.empty(model.output().shape, dtype=np.float32))
configured.run([bindings], 10000) # zaman aşımı: ms
for class_id, dets in enumerate(bindings.output().get_buffer()):
for y0, x0, y1, x1, score in dets: # 0-1 aralığında normalize
if score >= 0.5:
print(class_id, round(float(score), 2),
int(x0 * img_w), int(y0 * img_h),
int(x1 * img_w), int(y1 * img_h))Verim ve gecikme: benchmark FPS'i neden uygulamanızın FPS'i değil?
Batch ve bağlamlar. hailortcli parse-hef çıktısı, modelin tek bağlamlı (Single Context) mı yoksa çok bağlamlı (Multi Context) mı olduğunu söyler. HailoRT'nin başlık dosyasına göre yığın (batch) boyutu yalnızca çok bağlamlı ağlarda kullanılır. Hailo'nun profil raporlarına göre yolov8s tek, yolov8m üç bağlamlıdır; yukarıdaki tabloda yolov8s'in batch 1 ve 8'de aynı kalması, yolov8m'in ise iki kattan fazla hızlanması bundandır. Büyük batch verimi artırırken gecikmeyi (latency) uzatır; kamera başına düşük gecikme istiyorsanız batch 1 ile başlayın.Zamanlayıcı ve çoklu süreç. Model zamanlayıcı (Model Scheduler), VDevice oluşturulurken ROUND_ROBIN seçildiğinde etkinleşir ve aynı yongayı birden çok model ya da akış arasında kendiliğinden paylaştırır; öncelik, zaman aşımı ve eşik değerleri set_scheduler_priority, set_scheduler_timeout ve set_scheduler_threshold ile ayarlanır. Zamanlayıcı açıkken batch boyutu, başka bir modele geçmeden önce işlenecek en fazla kare sayısı anlamına gelir. Aygıtı farklı süreçler kullanacaksa hailort.service'i etkinleştirin (sudo systemctl enable --now hailort.service) ve uygulamada multi_process_service seçeneğini açın; komut satırındaki karşılığı --multi-process-service bayrağıdır (bu kipte --measure-temp ve --measure-power gibi ölçüm bayrakları kullanılamaz).
PCIe bant genişliği. 640x640 boyutlu, 8 bit RGB bir kare en az 1,2 MB eder. yolov8s'in 491 FPS'i yalnızca girdi için saniyede yaklaşık 600 MB demektir. Raspberry Pi 5'in varsayılan Gen 2 x1 bağlantısının tepe değeri 500 MB/s olduğu için bu hızı kâğıt üzerinde bile besleyemez; Gen 3 ise hat başına yaklaşık 985 MB/s sunar. Çok bağlamlı modeller PCIe üzerinden daha fazla veri geçirdiği için dar bağlantıdan en çok onlar etkilenir. Raspberry Pi'da x4 tablosundaki değerleri beklemeyin, kendi sisteminizde ölçün.
Ana işlemci darboğazı. Raspberry Pi 5'in BCM2712 yongası donanımda yalnızca HEVC çözer; Raspberry Pi belgelerine göre H.264 1080p24 çözme işlemcinin yaklaşık yüzde 10-20'sini tutar. Dört H.264 kamera, çıkarım daha başlamadan işlemcinin önemli bir bölümünü tüketebilir; yeniden boyutlandırma, renk dönüşümü, ana işlemcideki NMS ve sonuç çizimi de buna eklenir. Darboğazı görmek için uygulamayı HAILO_MONITOR=1 ortam değişkeniyle başlatıp ikinci bir terminalde hailortcli monitor çalıştırın (monitor, Model Zamanlayıcı ile çalışan uygulamaları gösterir): aygıt kullanımı düşük, işlemci yüksekse sorun yongada değildir.
Boyutlandırma. Kaba bir üst sınır için Hailo'nun tablo değerini kamera başına hedef FPS'e bölün: 491 FPS, 15 FPS'lik kameralar için kâğıt üzerinde 30'dan fazla akış demektir. Gerçek sayıyı ise çoğunlukla ana işlemci ve PCIe belirler. Güvenilir yöntem şudur: tek akışla uçtan uca ölçün, akış ekledikçe aygıt kullanımını ve işlemciyi izleyin, hangisinin önce doyduğuna bakın.
Kendi modelinizi çalıştırmak: ONNX'ten HEF'e
Kendi eğittiğiniz modeli HEF'e çevirmek için Hailo Dataflow Compiler (DFC) gerekir. DFC yalnızca x86-64 Linux'ta çalışır (Model Zoo belgeleri Ubuntu 22.04/24.04 ile Python 3.10-3.12'yi listeler; Windows'ta WSL2 altında desteklenir), Developer Zone'dan indirilir ve nicemleme adımı için NVIDIA GPU önerilir. Hailo-8 ve Hailo-8L için DFC 3.x, Hailo-10H için 5.x serisi kullanılır. Akış üç adımdır: ONNX dosyasını ayrıştırıp (parse) Hailo arşivi (HAR) üretmek, kalibrasyon görüntüleriyle INT8'e nicemlemek (optimize) ve derleyip HEF üretmek (compile). DFC bu adımları Python API'si (hailo_sdk_client paketindeki ClientRunner) ve hailo komut satırı aracıyla sunar; komut ve bayrak adları sürüme göre değiştiği için kurduğunuz sürümün kılavuzunu ve hailo --help çıktısını esas alın. YOLO modelleri için iki kısa yol var:
Bash:
# Yol 1: Ultralytics (DFC wheel dosyası aynı Python ortamına kurulu olmalı)
pip install ultralytics
pip install /yol/hailo_dataflow_compiler-*.whl
yolo export model=best.pt format=hailo name=hailo8 imgsz=640 data=veri.yaml
# Yol 2: Hailo Model Zoo
yolo export model=best.pt imgsz=640 format=onnx opset=11
hailomz compile --ckpt best.onnx --calib-path ./kalibrasyon/ --yaml hailo_model_zoo/cfg/networks/yolov8s.yaml --classes 3Model Zoo varsayılan olarak Hailo-8 için derler; Hailo-8L için --hw-arch hailo8l ekleyin. Ultralytics'te ise name parametresinin varsayılanı hailo8l'dir, bu yüzden Hailo-8 için name=hailo8 yazmayı unutmayın. Hailo da Ultralytics de kalibrasyon için en az 1024 görüntü öneriyor ve bu görüntülerin sahadaki ışığı, açıyı ve arka planı temsil etmesi şart. HEF sabit bir giriş boyutuyla derlenir; farklı çözünürlükler için ya kareyi ana makinede yeniden boyutlandırın ya da her çözünürlük için ayrı HEF derleyin. Nicemlemeden sonra doğruluğun neden düştüğünü ve nasıl toparlanacağını ONNX, INT8 ve QAT yazımızda ayrıntılı anlattık. Bir de lisans notu: Ultralytics'in açık kaynak YOLO modelleri AGPL-3.0 lisanslıdır; kapalı kaynaklı bir ürüne gömmeden önce lisans durumunuzu netleştirin.
Sorun giderme tablosu
| Belirti | Olası neden | Çözüm |
|---|---|---|
| lspci'de Hailo görünmüyor | Modül ya da PCIe şerit kablosu tam oturmamış; yuvada PCIe yok (yalnızca SATA); HAT+ olmayan adaptörde bağlantı kapalı; Gen 3 bağlantısı kararsız | Gücü kesip yeniden takın, yuvanın PCIe desteğini kontrol edin, gerekiyorsa dtparam=pciex1 ekleyin, Gen 2 ile deneyin |
| lspci görüyor ama hailortcli scan "Hailo devices not found" diyor | Sürücü yüklenmemiş: DKMS derlemesi düşmüş (çekirdek başlık dosyaları eksik) ya da Secure Boot imzasız modülü reddediyor ("Key was rejected by service") | sudo dkms status ve sudo modprobe hailo_pci çıktısına bakın, başlık dosyalarını kurun, MOK anahtarını kaydedin |
| "Driver version (...) is different from library version (...)" | Sürücü ile HailoRT farklı sürümde; genellikle yalnızca biri güncellenmiştir | İkisini aynı sürüme getirip yeniden başlatın, ardından sürümleri sabitleyin |
| "Unsupported firmware operation" uyarısı ya da HAILO_UNSUPPORTED_FW_VERSION | Yongadaki ürün yazılımı eski sürücüden kalmış | Sürücü paketini HailoRT ile aynı sürüme getirip yeniden başlatın |
| HAILO_HEF_NOT_SUPPORTED (92) ya da HAILO_HEF_NOT_COMPATIBLE_WITH_DEVICE (93) | HEF daha yeni bir DFC ile ya da başka bir yonga için derlenmiş | Çalışma zamanınıza uyan Model Zoo sürümünü indirin ya da doğru mimari için yeniden derleyin; parse-hef ile kontrol edin |
| /dev/hailo0 için "permission denied" | udev kuralı kurulmamış | Sürücü deposundaki 51-hailo-udev.rules dosyasını (SUBSYSTEM=="hailo_chardev", MODE="0666") /etc/udev/rules.d altına kopyalayın; sudo udevadm control --reload-rules ve sudo udevadm trigger çalıştırın |
| HAILO_OUT_OF_PHYSICAL_DEVICES (74) ya da HAILO_DEVICE_IN_USE (73) | Aygıtı başka bir süreç tutuyor ya da önceki süreç temiz kapanmamış | sudo lsof /dev/hailo0 ile süreci bulun; birden çok süreç gerekiyorsa çoklu süreç hizmetini kullanın |
| FPS birkaç dakika sonra düşüyor | Termal kısıtlama (thermal throttling) | --measure-temp ile sıcaklığı izleyin, ısı emiciyi ve hava akışını iyileştirin |
| benchmark yüksek, uygulama düşük | İşlemcide çözme, yeniden boyutlandırma, NMS ya da çizim; senkron run() döngüsü | Eşzamansız (async) çıkarım, Raspberry Pi 5'te HEVC kamera akışı, HAILO_MONITOR ile ölçüm |
| pip: "is not a supported wheel on this platform" ya da import hatası | Wheel etiketi (cp310, cp312) Python sürümünüze ya da mimarinize uymuyor | python -V çıktısına uyan dosyayı kurun; Raspberry Pi'da sanal ortamı --system-site-packages ile oluşturun |
Sahaya çıkmadan önce
- Sürümleri sabitleyin. Raspberry Pi'da sudo apt-mark hold hailort hailort-pcie-driver python3-hailort hailo-tappas-core python3-hailo-tappas komutu, otomatik bir güncellemenin sürücüyle çalışma zamanını birbirinden ayırmasını engeller. Eski Bookworm kurulumlarında sürücü paketi hailo-dkms adını taşıyordu; apt list --installed | grep -i hailo ile kontrol edin. Güncellemeleri önce bir test cihazında doğrulayın, sonra filoya yayın.
- Bekçi (watchdog) ekleyin. Uygulamayı Restart=on-failure içeren bir systemd hizmeti olarak çalıştırın ve belirli bir süre çıkarım sonucu üretmezse sıfırdan farklı bir kodla çıkmasını sağlayın; daha sıkı bir seçenek WatchdogSec ile uygulamadan sd_notify sinyali beklemektir.
- Sıcaklığı kaydedin. Devreye almadan önce günün en sıcak saatinde, kapalı kutuda bir yük testi yapın; --measure-temp çıktısını ya da Python API'sinde Device.control.get_chip_temperature() değerini günlüğe yazın.
Sık sorulan sorular
Hailo-8 büyük dil modeli (LLM) çalıştırabilir mi?Pratikte hayır. Hailo-8 CNN'leri ve bazı transformer tabanlı görüntü modellerini çalıştırır, ama harici belleği olmadığı için milyarlarca parametrelik bir dil modeli yongaya sığmaz. Raspberry Pi belgeleri de AI HAT+ için LLM desteğini "Not supported" (desteklenmiyor) olarak listeler. Küçük LLM ve VLM'ler için tasarlanan parça Hailo-10H'dir (AI HAT+ 2).
Windows'ta kullanılabilir mi?
Evet. Hailo, M.2 modüller için Linux ve Windows desteği listeler; Windows'ta HailoRT bir MSI paketiyle kurulur ve Python wheel dosyası C:\Program Files\HailoRT\python altına gelir. Ancak DFC yalnızca Linux'ta (ya da WSL2'de) çalışır; hailo-apps'teki GStreamer uygulamaları ve hailortcli monitor komutu da Windows'ta desteklenmez.
Jetson'ın yanında ya da yerine kullanılabilir mi?
Yanında kullanmak teknik olarak mümkün: HailoRT ARM64 Linux'u destekler ve sürücü çalışan çekirdeğe göre derlenir. Hailo topluluk forumunda M.2 Hailo-8'i bir Jetson Orin Nano Super'a (JetPack 6.2) kurup etkinleştirdiğini bildiren bir kullanıcı var, ancak resmi bir Jetson kurulum kılavuzu bulamadık; bu birleşimi kendi donanımınızda doğrulamadan plan yapmayın. Yerine kullanmak iş yüküne bağlı: INT8'e nicemlenmiş görüntü modelleri için Hailo-8 ve küçük bir ana makine yetebilir; CUDA, FP16, TensorRT ya da LLM gerekiyorsa Jetson daha doğru seçimdir.
Hangi modeller destekleniyor?
Model Zoo'nun Hailo-8 nesne tespiti tablosunda YOLOv3'ten YOLOv12'ye uzanan sürümlerin yanında YOLO26 ve YOLOX da var; sınıflandırma, segmentasyon, poz ve derinlik tahmini, yüz tanıma, OCR, nesne takibi ve konuşma tanıma için de hazır HEF'ler bulunuyor. Kendi modelinizde belirleyici olan, katmanlarının DFC tarafından desteklenmesidir; ayrıştırma adımı desteklenmeyen katmanlarda kalibrasyona geçmeden hata verir.
Developer Zone hesabı şart mı?
Raspberry Pi'da hayır, her şey apt deposundan gelir. x86 için hazır .deb ve .whl paketleri ile DFC'yi indirmek için giriş gerekir. İleri bir seçenek olarak HailoRT'nin kütüphanesi, komut satırı aracı ve Python API'si (MIT lisanslı) ile PCIe sürücüsü (GPL-2.0) GitHub'daki kaynak koddan derlenebilir; sürücü deposundaki download_firmware.sh betiği ürün yazılımını Hailo'nun herkese açık depolama alanından indirir.
Sonuç ve sonraki adımlar
Çalışan bir Hailo-8 kurulumu üç kurala dayanır: sürücü ile HailoRT aynı sürümde olacak, HEF çalışma zamanınıza ve yonganıza uyacak, PCIe bağlantısı beklediğiniz hızda ve hat sayısında çalışacak. Sıradaki adımlar: hailortcli benchmark ile kendi sisteminizin taban değerini kaydedin, aynı modeli gerçek bir kamera akışıyla uçtan uca ölçüp aradaki farkın nereye gittiğini bulun, ardından kendi veri setinizle bir model derleyip doğruluğunu sahadan alınmış görüntülerle doğrulayın. AIOR'un Hailo tabanlı uçta çıkarım çözümü proje sayfasında anlatılıyor. Kurulumda takıldığınız noktayı lspci ve hailortcli çıktılarıyla birlikte bu konuya yazabilirsiniz.You have a Hailo-8 M.2 module or the 26 TOPS Raspberry Pi AI HAT+ on the desk and want a YOLO model running on it, or you are still choosing between Hailo-8, Hailo-8L and Hailo-10H. This guide covers the whole path: picking the right part, installing the PCIe driver and the HailoRT runtime on x86-64 Ubuntu or a Raspberry Pi 5, confirming the device is detected, running a pre-compiled YOLOv8 model, and setting realistic throughput expectations. We checked commands and package names against Hailo's GitHub repositories, the Hailo Model Zoo and the Raspberry Pi documentation. Version numbers reflect October 2026 and change quickly, so check yours before you install.
What Hailo-8 is and how it works
Hailo-8 is an AI accelerator (NPU) built on a dataflow architecture. Hailo rates it at 26 TOPS (Raspberry Pi specifies INT8) with a typical power consumption of 2.5 W. The difference from a GPU is that the network's layers are mapped onto compute and memory resources across the chip, and data flows between them. Hailo-8 has no external DRAM; the memory it needs is on the die.That design has three practical consequences:
- It only runs compiled models. You cannot hand it an ONNX or PyTorch file. The model must be quantized and compiled for the target chip by the Hailo Dataflow Compiler (DFC) into a HEF (Hailo Executable Format) file.
- The host CPU still has work to do. Video decode, resizing, colour conversion and usually post-processing run on the host. Even for the YOLOv8 HEFs in the Model Zoo, HailoRT runs NMS (non-maximum suppression) on the host CPU; the model's .alls script says engine=cpu.
- Models that do not fit get split. A large network is divided into several contexts and the chip switches between them. That costs throughput and makes PCIe bandwidth matter, which explains how batch size behaves (more on that below).
Hailo-8 ships in several form factors: an M.2 Key M module with a four-lane (x4) PCIe Gen 3 interface, two-lane (x2) M.2 Key B+M and 2230-size Key A+E modules, Century PCIe cards that carry several Hailo-8 chips (Hailo lists 52 to 208 TOPS), and the Raspberry Pi AI HAT+ 26 TOPS. The mini PCIe module is sold as Hailo-8R and listed at 13 TOPS over PCIe Gen 3 x1, so read the spec before buying an mPCIe card. Hailo-10H takes a different route: it carries its own LPDDR4/4X memory on the module (4 or 8 GB on Hailo's M.2 module), and that memory is what makes large language models (LLMs) possible.
Hailo-8 vs Hailo-8L vs Hailo-10H
| Attribute | Hailo-8 | Hailo-8L | Hailo-10H |
|---|---|---|---|
| Peak rating (Hailo) | 26 TOPS (INT8) | 13 TOPS (INT8) | 40 TOPS (INT4), 20 TOPS (INT8) |
| Typical power (Hailo) | 2.5 W | 1.5 W | 2.5 W (M.2 module) |
| Memory | On-chip, no external DRAM | On-chip, no external DRAM | 4 or 8 GB LPDDR4/4X on the module |
| HailoRT line | 4.x (hailo8 branch) | 4.x (hailo8 branch) | 5.x |
| Raspberry Pi product | AI HAT+ 26 TOPS | AI HAT+ 13 TOPS, AI Kit (discontinued) | AI HAT+ 2 (8 GB) |
| Raspberry Pi package | hailo-all | hailo-all | hailo-h10-all |
| LLMs and VLMs | No | No | Yes (Raspberry Pi: up to about 6 billion parameters) |
How to choose: for object detection across several cameras, two or three models at once (detection plus classification, say) or mid-size models such as YOLOv8m, buy Hailo-8. Hailo-8L runs the same software stack with half the compute elements (according to answers on the Hailo community forum) and is often enough for one camera and light models. If you want a small language model or a vision-language model (VLM) on a Raspberry Pi, the answer is the Hailo-10H-based AI HAT+ 2; Raspberry Pi's documentation marks LLM support on AI HAT+ as "Not supported". At INT8, Hailo-10H's 20 TOPS sits below Hailo-8's 26 on paper, so do not choose it for pure vision on speed grounds; compare your model in both chips' Model Zoo tables. Finally, a HEF is compiled for a specific chip: a Hailo-8 HEF will not load on a Hailo-8L. The reverse works, but a Hailo-8L HEF runs on a Hailo-8 at lower performance.
Hardware checklist before you install
- Host: on x86-64, Ubuntu 22.04 or 24.04 LTS (confirm the supported list in the documentation for the HailoRT release you install; the newer kernels of non-LTS releases can break the driver's DKMS build). On the Pi side, a Raspberry Pi 5 running 64-bit Raspberry Pi OS; the Raspberry Pi documentation now assumes Trixie.
- Slot and lanes: a Key M module needs an M.2 M slot wired for PCIe (NVMe); in a SATA-only M.2 slot it simply never appears. A B+M module runs at x2, but some B-key slots carry only USB or SATA and no PCIe at all. We will confirm the negotiated link with lspci after installation.
- Raspberry Pi 5 PCIe setting: the Pi 5 exposes a single PCIe lane (x1) that runs at Gen 2.0 (5 GT/s) by default. On AI HAT+ and AI HAT+ 2, Gen 3.0 is applied automatically. With the AI Kit, or a module on an M.2 HAT+, you enable it yourself: run sudo raspi-config and choose Advanced Options > PCIe Speed, or add dtparam=pciex1_gen=3 to /boot/firmware/config.txt. Third-party adapters that are not HAT+ compliant also need dtparam=pciex1 to enable the connector. Raspberry Pi notes that the Pi 5 is not certified for Gen 3.0 and the link may be unstable; if you see unexplained errors, try Gen 2.
- Cooling: under load the chip heats up, and its temperature protection lowers the clock. Raspberry Pi recommends the Active Cooler on the Pi 5 and the heatsink supplied with AI HAT+ 2. On M.2 modules, fit the vendor's heatsink and account for airflow inside a closed enclosure.
- Power budget: Raspberry Pi recommends its official 27 W USB-C power supply (it can deliver 5 A at 5 V) for the Pi 5, and the M.2 HAT+ delivers up to 3 A to the M.2 device. Hailo-8's 2.5 W is a typical figure; take the peak from your module's datasheet.
Version matching: where most failures start
Knowing how four components relate to each other saves hours later:- The PCIe driver and HailoRT must be the same version. When it opens the device, HailoRT queries the driver version, and if the major, minor or revision number differs it stops with "Driver version (...) is different from library version (...)".
- The firmware ships with the driver. The driver loads the Hailo-8 firmware from /lib/firmware/hailo/hailo8_fw.bin when it probes the device. If the major and minor firmware version on the chip do not match HailoRT, most operations are refused. In practice, updating the driver package updates the firmware too.
- Hailo-8 uses the 4.x line. The master branch of the HailoRT repository (the 5.x line) supports only the Hailo-10 and Hailo-15 families. Hailo-8, Hailo-8L and Hailo-8R use the hailo8 branch, whose latest release at the time of writing is 4.24.0.
- The HEF must not be newer than the runtime. A HEF built with a newer DFC usually fails to load on an older HailoRT. Hailo's hailo-apps repository maps HailoRT 4.23 to Model Zoo v2.18 and HailoRT 4.24 to v2.19; v2.20 only adds models on the same stack (HailoRT 4.24).
Install on x86-64 Ubuntu
Prebuilt packages for Ubuntu are on the software downloads page of the Hailo Developer Zone, which requires signing in. Download three files with the same version number; for 4.24.0 they are the PCIe driver (hailort-pcie-driver_4.24.0_all.deb), the runtime (hailort_4.24.0_amd64.deb) and the Python wheel (.whl) that matches your Python version. When downloading, pick the right architecture (x86-64), operating system and Python version.
Bash:
# 1) DKMS and headers for the running kernel
sudo apt update
sudo apt install -y build-essential dkms linux-headers-$(uname -r)
# 2) Driver first, then HailoRT; the versions must match
HRT=4.24.0
sudo dpkg -i hailort-pcie-driver_${HRT}_all.deb # "Do you wish to use DKMS?" -> Y
sudo dpkg -i hailort_${HRT}_amd64.deb # "activate hailort service?" -> y (multi-process service)
sudo reboot
# 3) A virtual environment for the Python API
python3 -m venv ~/hailo-venv && source ~/hailo-venv/bin/activate
python -V # Python 3.12 -> pick the cp312 wheel
pip install ./hailort-${HRT}-cp312-cp312-*.whl
python -c "import hailo_platform as hp; print(hp.__version__)"DKMS rebuilds the driver whenever the kernel is updated; skip it and the device disappears after the next kernel upgrade. With Secure Boot enabled, Ubuntu creates a MOK key to sign the DKMS module and asks you for a password. Complete the "Enroll MOK" step in the MOK Manager screen on the next boot, or the module will not load.
After the reboot, check each layer in turn:
Bash:
lspci -nn | grep -i hailo # is it on the PCIe bus?
sudo lspci -vv -d 1e60: | grep -E "LnkCap|LnkSta" # link speed and width
sudo dmesg | grep -i hailo # driver and firmware loaded?
hailortcli scan
hailortcli fw-control identifyExpect something like the following. The address and version depend on your system, and the fields vary slightly between releases:
Kod:
04:00.0 Co-processor [0b40]: Hailo Technologies Ltd. Hailo-8 AI Processor [1e60:2864] (rev 01)
Hailo Devices:
[-] Device: 0000:04:00.0
Executing on device: 0000:04:00.0
Identifying board
Control Protocol Version: 2
Firmware Version: 4.24.0 (release,app,extended context switch buffer)
Logger Version: 0
Device Architecture: HAILO8
Serial Number: ...
Part Number: ...
Product Name: ...Install on Raspberry Pi 5
No Developer Zone account is needed on a Pi: the driver, firmware, HailoRT, Python bindings and TAPPAS core libraries all come from the Raspberry Pi apt repository.
Bash:
sudo apt update && sudo apt full-upgrade -y
sudo rpi-eeprom-update -a
sudo reboot
# AI Kit and M.2 HAT+ only - PCIe Gen 3:
# sudo raspi-config -> Advanced Options > PCIe Speed > Yes
# or add to /boot/firmware/config.txt: dtparam=pciex1_gen=3
sudo apt install dkms
sudo apt install hailo-all # AI HAT+ (Hailo-8/8L) and AI Kit
# sudo apt install hailo-h10-all # AI HAT+ 2 only; cannot coexist with hailo-all
sudo reboot
hailortcli fw-control identify # 26 TOPS board: Device Architecture: HAILO8
dmesg | grep -i hailohailo-all is a metapackage that pulls in hailort, hailort-pcie-driver, python3-hailort, hailo-tappas-core, python3-hailo-tappas and rpicam-apps-hailo-postprocess; the demo models arrive with the hailo-models package. With a camera attached, Raspberry Pi's own demo is the quickest visual test:
Bash:
sudo apt install rpicam-apps
rpicam-hello -t 0 --post-process-file /usr/share/rpi-camera-assets/hailo_yolov8_inference.jsonThe same folder holds JSON files for YOLOv6, YOLOX, YOLOv5 person and face detection, YOLOv5 segmentation and YOLOv8 pose estimation; the Raspberry Pi AI documentation walks through each one. For your own application, start from Hailo's hailo-apps repository; the older hailo-rpi5-examples repository is marked as outdated and points there. The GStreamer apps in hailo-apps (hailo-detect --input rpi, for example) are built from HailoRT's hailonet element and TAPPAS elements: hailonet runs the model, hailofilter applies post-processing from a compiled .so, hailooverlay draws the results, and hailoroundrobin feeds several camera streams into a single hailonet in turn. Raspberry Pi OS protects the system Python from pip, so create your virtual environment with python3 -m venv --system-site-packages .venv, otherwise the apt-installed hailo_platform module stays invisible.
First inference: benchmark a pre-compiled YOLOv8 HEF
Pre-compiled HEFs in the Hailo Model Zoo are grouped by release. Use v2.20.0 with HailoRT 4.24, and v2.18.0 with the 4.23 build on Raspberry Pi; for Hailo-8L, replace hailo8 with hailo8l in the path.
Bash:
wget https://hailo-model-zoo.s3.eu-west-2.amazonaws.com/ModelZoo/Compiled/v2.20.0/hailo8/yolov8s.hef
hailortcli parse-hef yolov8s.hef # architecture, inputs/outputs, Single or Multi Context
hailortcli run yolov8s.hef # inference on random input (5 s by default), prints FPS
hailortcli benchmark yolov8s.hef # hw_only FPS, streaming FPS, hardware latency
hailortcli run yolov8s.hef --measure-temp --measure-latencybenchmark runs each measurement mode for 15 seconds by default and prints a summary like the one below; power lines are added only on boards that support power measurement:
Kod:
=======
Summary
=======
FPS (hw_only) = ...
(streaming) = ...
Latency (hw) = ... msA minimal Python inference skeleton
In HailoRT 4.24 the recommended Python interface is InferModel, and the skeleton below follows the flow of Hailo's own tutorial. For YOLOv8 HEFs with NMS, get_buffer() returns one array per class, and each row holds (y_min, x_min, y_max, x_max, score) normalized to the 0-1 range.
Python:
# Needs numpy and OpenCV (on Raspberry Pi: sudo apt install python3-opencv)
import cv2
import numpy as np
from hailo_platform import VDevice, HailoSchedulingAlgorithm
params = VDevice.create_params()
params.scheduling_algorithm = HailoSchedulingAlgorithm.ROUND_ROBIN
with VDevice(params) as vdevice:
model = vdevice.create_infer_model("yolov8s.hef")
model.set_batch_size(1)
in_h, in_w, _ = model.input().shape # yolov8s: 640, 640, 3
with model.configure() as configured:
bindings = configured.create_bindings()
frame = cv2.imread("sample.jpg") # OpenCV loads images as BGR
img_h, img_w = frame.shape[:2]
rgb = cv2.cvtColor(cv2.resize(frame, (in_w, in_h)), cv2.COLOR_BGR2RGB)
bindings.input().set_buffer(np.ascontiguousarray(rgb))
bindings.output().set_buffer(np.empty(model.output().shape, dtype=np.float32))
configured.run([bindings], 10000) # timeout in ms
for class_id, dets in enumerate(bindings.output().get_buffer()):
for y0, x0, y1, x1, score in dets: # normalized to 0-1
if score >= 0.5:
print(class_id, round(float(score), 2),
int(x0 * img_w), int(y0 * img_h),
int(x1 * img_w), int(y1 * img_h))Throughput and latency: why benchmark FPS is not your app's FPS
Batch and contexts. hailortcli parse-hef tells you whether a model is Single Context or Multi Context. According to the HailoRT header, the batch size is only used by multi-context networks. Hailo's profiler reports show one context for yolov8s and three for yolov8m, which is why yolov8s scores the same at batch 1 and 8 in the table above while yolov8m more than doubles. A bigger batch raises throughput and adds latency, so start at batch 1 if per-camera latency matters.Scheduler and multiple processes. The Model Scheduler is enabled when you create the VDevice with ROUND_ROBIN, and it shares the chip between models or streams automatically; set_scheduler_priority, set_scheduler_timeout and set_scheduler_threshold tune it. With the scheduler on, batch size becomes the maximum number of frames processed before it switches to another model. If separate processes will use the device, enable hailort.service (sudo systemctl enable --now hailort.service) and turn on multi_process_service in your application; the CLI equivalent is the --multi-process-service flag (in that mode, measurement flags such as --measure-temp and --measure-power are not available).
PCIe bandwidth. A 640x640 frame in 8-bit RGB is at least 1.2 MB, so yolov8s at 491 FPS needs about 600 MB/s for input alone. The Pi 5's default Gen 2 x1 link peaks at 500 MB/s and cannot feed that rate even on paper; Gen 3 offers roughly 985 MB/s per lane. Multi-context models push more data across PCIe and suffer most from a narrow link. Do not expect the x4 table figures on a Pi; measure on your own system.
Host bottlenecks. The Raspberry Pi 5's BCM2712 decodes only HEVC in hardware, and Raspberry Pi's documentation puts H.264 1080p24 decode at roughly 10-20% of the CPU. Four H.264 cameras can consume a large share of the CPU before any inference happens, and resizing, colour conversion, NMS on the host and drawing come on top. To find the bottleneck, start your application with the environment variable HAILO_MONITOR=1 and run hailortcli monitor in a second terminal (the monitor reports applications that use the Model Scheduler): low device utilisation alongside a busy CPU means the chip is not the problem.
Sizing. For a rough upper bound, divide Hailo's table figure by the per-camera FPS you need: 491 FPS is more than 30 streams at 15 FPS on paper. The real number is usually set by the host CPU and PCIe. The reliable method is to measure one stream end to end, add streams while watching device utilisation and CPU load, and see which one saturates first.
Running your own model: from ONNX to HEF
Turning your own model into a HEF requires the Hailo Dataflow Compiler (DFC). It runs only on x86-64 Linux (the Model Zoo documentation lists Ubuntu 22.04/24.04 and Python 3.10-3.12, with WSL2 supported on Windows), is downloaded from the Developer Zone, and an NVIDIA GPU is recommended for the optimization step. Hailo-8 and Hailo-8L use DFC 3.x; Hailo-10H uses the 5.x line. The flow has three steps: parse the ONNX file into a Hailo archive (HAR), optimize it (quantize to INT8 with calibration images) and compile it into a HEF. The DFC exposes these steps through its Python API (ClientRunner in the hailo_sdk_client package) and the hailo command-line tool; command and flag names change between releases, so follow the guide for the version you installed and the hailo --help output. For YOLO models there are two shortcuts:
Bash:
# Option 1: Ultralytics (the DFC wheel must be installed in the same Python environment)
pip install ultralytics
pip install /path/to/hailo_dataflow_compiler-*.whl
yolo export model=best.pt format=hailo name=hailo8 imgsz=640 data=data.yaml
# Option 2: Hailo Model Zoo
yolo export model=best.pt imgsz=640 format=onnx opset=11
hailomz compile --ckpt best.onnx --calib-path ./calib/ --yaml hailo_model_zoo/cfg/networks/yolov8s.yaml --classes 3The Model Zoo compiles for Hailo-8 by default; add --hw-arch hailo8l for Hailo-8L. In Ultralytics the name argument defaults to hailo8l, so remember to pass name=hailo8 for a Hailo-8. Hailo and Ultralytics both recommend at least 1024 calibration images, and those images must represent the lighting, angles and backgrounds of the real site. A HEF is compiled for a fixed input size, so either resize frames on the host or compile one HEF per resolution. Why accuracy drops after quantization, and how to recover it, is covered in our ONNX, INT8 and QAT article. One licensing note: Ultralytics' open-source YOLO models are licensed under AGPL-3.0, so settle your licence position before shipping one inside a closed-source product.
Troubleshooting table
| Symptom | Likely cause | Fix |
|---|---|---|
| Hailo missing from lspci | Module or PCIe ribbon cable not fully seated; slot has no PCIe (SATA only); connector disabled on a non-HAT+ adapter; unstable Gen 3 link | Power off and reseat, check that the slot carries PCIe, add dtparam=pciex1 if needed, retry at Gen 2 |
| lspci sees it, but hailortcli scan says "Hailo devices not found" | Driver not loaded: DKMS build failed (missing kernel headers) or Secure Boot rejected the unsigned module ("Key was rejected by service") | Check sudo dkms status and sudo modprobe hailo_pci, install the headers, enroll the MOK key |
| "Driver version (...) is different from library version (...)" | Driver and HailoRT on different versions; usually only one of them was upgraded | Bring both to the same version, reboot, then pin the versions |
| "Unsupported firmware operation" warning or HAILO_UNSUPPORTED_FW_VERSION | Firmware on the chip came from an older driver | Update the driver package to the HailoRT version and reboot |
| HAILO_HEF_NOT_SUPPORTED (92) or HAILO_HEF_NOT_COMPATIBLE_WITH_DEVICE (93) | HEF built with a newer DFC or for a different chip | Download the Model Zoo release that matches your runtime or recompile for the right architecture; check with parse-hef |
| "Permission denied" on /dev/hailo0 | udev rule not installed | Copy 51-hailo-udev.rules (SUBSYSTEM=="hailo_chardev", MODE="0666") from the driver repository to /etc/udev/rules.d, then run sudo udevadm control --reload-rules and sudo udevadm trigger |
| HAILO_OUT_OF_PHYSICAL_DEVICES (74) or HAILO_DEVICE_IN_USE (73) | Another process holds the device, or a previous one did not exit cleanly | Find it with sudo lsof /dev/hailo0; if several processes need the chip, use the multi-process service |
| FPS drops after a few minutes | Thermal throttling | Watch temperature with --measure-temp, improve the heatsink and airflow |
| benchmark is fast, the application is slow | Decode, resize, NMS or drawing on the CPU; a synchronous run() loop | Async inference, HEVC camera streams on a Raspberry Pi 5, measure with HAILO_MONITOR |
| pip: "is not a supported wheel on this platform", or the import fails | Wheel tag (cp310, cp312) does not match your Python version or architecture | Install the file that matches python -V; on a Raspberry Pi create the venv with --system-site-packages |
Before you go to production
- Pin versions. On a Pi, sudo apt-mark hold hailort hailort-pcie-driver python3-hailort hailo-tappas-core python3-hailo-tappas stops an unattended upgrade from splitting the driver and the runtime. Older Bookworm installs named the driver package hailo-dkms, so check with apt list --installed | grep -i hailo. Validate upgrades on a test unit before rolling them out to the fleet.
- Add a watchdog. Run the application as a systemd service with Restart=on-failure, and make it exit with a non-zero code when no inference result has arrived for a set time; the stricter variant is WatchdogSec with sd_notify pings from the application.
- Log temperature. Before commissioning, run a load test inside the closed enclosure at the hottest time of day and log the --measure-temp output or, from the Python API, Device.control.get_chip_temperature().
FAQ
Can Hailo-8 run LLMs?Not in practice. Hailo-8 runs CNNs and some transformer-based vision models, but without external memory a language model with billions of parameters does not fit. Raspberry Pi's documentation also marks LLM support on AI HAT+ as "Not supported". Hailo-10H (AI HAT+ 2) is the part designed for small LLMs and VLMs.
Does it work on Windows?
Yes. Hailo lists Linux and Windows support for its M.2 modules; on Windows, HailoRT installs from an MSI package and the Python wheel lands in C:\Program Files\HailoRT\python. The DFC runs only on Linux (or WSL2), and the GStreamer apps in hailo-apps and the hailortcli monitor command are not supported on Windows.
Can I use it next to, or instead of, a Jetson?
Next to one is technically possible: HailoRT supports ARM64 Linux and the driver is built against the running kernel. A user on the Hailo community forum reports installing and activating an M.2 Hailo-8 on a Jetson Orin Nano Super (JetPack 6.2), but we could not find an official Jetson install guide, so validate the combination on your own hardware before you plan around it. Whether it can replace one depends on the workload: for INT8 vision models a Hailo-8 with a small host may be enough; if you need CUDA, FP16, TensorRT or LLMs, a Jetson is the better fit.
Which models are supported?
The Hailo-8 object detection table in the Model Zoo covers YOLOv3 through YOLOv12 plus YOLO26 and YOLOX, and there are pre-compiled HEFs for classification, segmentation, pose and depth estimation, face recognition, OCR, object tracking and speech recognition. For your own model, what matters is whether the DFC supports its layers; the parse step fails on unsupported layers before you spend any time on calibration.
Do I need a Developer Zone account?
Not on a Raspberry Pi, where everything comes from apt. On x86, downloading the prebuilt .deb and .whl packages and the DFC requires signing in. As an advanced route, HailoRT's library, CLI and Python API (MIT licence) and the PCIe driver (GPL-2.0) can be built from source on GitHub, and the driver repository's download_firmware.sh script fetches the firmware from Hailo's public storage.
Conclusion and next steps
A working Hailo-8 setup comes down to three rules: the driver and HailoRT share a version, the HEF suits both your runtime and your chip, and the PCIe link runs at the speed and width you expect. Next steps: record a baseline for your own system with hailortcli benchmark, measure the same model end to end on a real camera stream and find out where the difference goes, then compile a model on your own dataset and check its accuracy on images taken on site. AIOR's Hailo-based edge inference solution is described on its project page. If you get stuck, post your lspci and hailortcli output in this thread.
Son düzenleyen:
