Link to this sectionUltralytics YOLOモデルのHailoエクスポート#

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 ファイルを生成します。

Link to this sectionHailo HEFを使用すべき場合#

HEFは、Hailoターゲットデバイス上でHailoRTによって使用されるコンパイル済みアーティファクトです。このガイドは、デプロイ先のハードウェアでHailo HEFが明示的に必要な場合にのみ使用してください。エッジハードウェアやエクスポートターゲットをまだ選定中の場合は、まず Axelera AI や DeepX といった新しいUltralytics直接エクスポートフォーマットの使用を検討してください。これらはサポートされた model.export(...) ワークフローを提供し、従来のHailoデプロイメントよりも優れたワットあたりパフォーマンスを実現できます。

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のポストプロセッシング: HailoRTは、コンパイル済みの推論パイプライン内にYOLOの 非最大値抑制 (NMS) を含めることができます。
• INT8コンパイル: Hailo DFCは、代表的なキャリブレーション画像を用いてモデルを量子化し、Hailoハードウェア用のINT8グラフを生成します。モデル量子化 の詳細についてはこちらを参照してください。

Link to this sectionHailo 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 エクスポートモード を使用して ONNXにエクスポート
2. ONNXモデルを解析してHailoの中間HAR形式に変換
3. 正規化およびポストプロセッシングディレクティブを含む モデルスクリプト (.alls) をロード
4. 代表的な画像を使用して キャリブレーションおよび量子化
5. デプロイ可能なHEFファイルへ コンパイル

Link to this sectionサポートされているタスク#

このガイドではUltralytics YOLOの 物体検知 モデルに焦点を当てています。これは、HailoモデルスクリプトとNMS設定が検知ヘッドに固有であるためです。

インスタンスセグメンテーション、セマンティックセグメンテーション、ポーズ、OBB、および分類のデプロイについては、エクスポートモード テーブルで他のエッジフォーマットを比較するか、ターゲットランタイムがそのタスクをサポートしている場合は汎用的なONNXパイプラインを使用してください。

Link to this section互換性に関する注意点#

Hailoエクスポートの互換性は、モデルヘッド、入力画像サイズ、クラス数、Hailoアーキテクチャ、モデルスクリプト (.alls)、およびNMS設定に依存します。Hailo Model Zoo の静的ファイルは有用な参照先ですが、万能なテンプレートではありません。例えば、COCO 80クラスのYOLO11nモデル用に作成されたNMS JSONは、カスタムの3クラスモデルや、異なる固定の imgsz には正しく機能しません。

Link to this sectionインストール#

Link to this sectionステップ1: Ultralyticsをインストール#

pip install ultralytics

Link to this sectionステップ2: Hailo DFC SDKをインストール#

解析、最適化、コンパイルにはHailo DFCが必要です。Hailo Developer Zone からPythonホイールをダウンロード（無料登録が必要）し、インストールしてください:

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

Link to this sectionYOLO11n HEFエクスポートの例#

以下のスクリプトは、YOLO11n検知モデルを .pt から .hef に固定の640ピクセル入力サイズでコンパイルします。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" を設定してください。

Link to this sectionステップバイステップの内訳#

Link to this sectionステップ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)

Link to this sectionステップ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)

Link to this sectionステップ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)

Link to this sectionステップ4: キャリブレーションデータセットを構築#

INT8量子化には代表的な画像セットが必要です。以下のスクリプトはCOCO128を使用しており、Ultralyticsが check_det_dataset を通じて自動的にダウンロードします:

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

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

Link to this sectionステップ5: 最適化および量子化#

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

このステップでは、量子化を考慮したファインチューニングとレイヤーノイズ分析を適用します。GPUの使用を強く推奨します。GPUがない場合、このステップには数時間かかることがあります。

Link to this sectionステップ6: HEFへコンパイル#

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

Link to this sectionサポートされているモデルとエンドノード#

検知モデルの場合、end_node_names はHailoがNMSポストプロセッシングを付加する前にコンパイルすべきONNX検知ヘッド出力を特定します。これらの名前はアーキテクチャによって異なり、エクスポートされたグラフが変更されると変わる可能性があります。

Link to this sectionYOLO11およびYOLOv8#

YOLO11とYOLOv8は同じ分離型検知ヘッドを共有しています。レイヤーインデックスは両ファミリー間で1つ異なります:

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

Link to this sectionその他のアーキテクチャ#

他の検知アーキテクチャについては、まず 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 で入手可能です。

Link to this sectionサポートされているハードウェアアーキテクチャ#

コンパイル前に、スクリプト内の HW_ARCH をターゲットデバイスに合わせて設定してください。

Link to this sectionHailo ハードウェア上での推論実行#

Once you have the .hef file, copy it to your Hailo-powered device and run inference using the HailoRT Python API (hailo_platform package). Unlike the DFC export steps, inference runs directly on the edge device.

Link to this sectionステップ 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 ソフトウェアガイドに従ってください。

Link to this sectionステップ 2: 簡単な動作確認#

Python 推論を実行する前に、Hailo デバイスが認識されていることを確認してください。

hailortcli fw-control identify

デバイスの種類、ファームウェアバージョン、シリアル番号が表示されるはずです。

Link to this sectionステップ 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")

Link to this sectionRaspberry Pi AI Kit および AI HAT+#

Raspberry Pi AI Kit および 13 TOPS AI HAT+ は Hailo-8L を使用します。いずれのデバイスを使用する場合も、以下の手順を行います。

1. x86 マシン上で HEF をコンパイルする前に HW_ARCH = "hailo8l" を設定します。
2. Copy the .hef to your Raspberry Pi.
3. 公式 Raspberry Pi AI ソフトウェアガイド に従って HailoRT をインストールします。
4. 上記の推論スクリプトを実行します。

Raspberry Pi 上でのカメラを用いた推論には、picamera2 Hailo サンプル があり、カメラモジュールを使用したリアルタイム検出用のスクリプトがすぐに利用可能です。また、Coral Edge TPU on Raspberry Pi ガイド や Sony IMX500 統合ガイド で Raspberry Pi のデプロイパスを比較することもできます。

Link to this sectionTAPPAS を用いたビデオ推論#

高スループットのビデオパイプライン向けに、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 ドキュメント を参照してください。

Link to this section要約#

このガイドでは、Ultralytics YOLO 検出モデルを Hailo HEF フォーマットにエクスポートする一連のワークフローを説明しました。

1. Ultralytics を使用して ONNX にエクスポートする (model.export(format="onnx"))。
2. Hailo DFC で ONNX モデルをパースし、検出ヘッドのエンドノードを指定する。
3. モデルスクリプトを介して正規化と NMS を設定する。
4. キャリブレーションデータセット（Ultralytics 経由の COCO128）を使用して量子化する。
5. Compile to a .hef file ready for Hailo-8, Hailo-8L, or Hailo-15.

詳細については、Hailo Developer Zone、Hailo ドキュメント、および Hailo Model Zoo を参照してください。その他の Ultralytics エクスポートターゲットについては、関連する ONNX、OpenVINO、TensorRT、NCNN、TFLite Edge TPU、RKNN、Sony IMX500、Qualcomm QNN ガイドを参照してください。エクスポートされたモデルの速度と精度を比較するには、ベンチマークモード を使用してください。利用可能な全フォーマットとオプションについては、エクスポートモード ドキュメントおよび 統合ガイドページ を参照してください。

Link to this sectionよくある質問 (FAQ)#

Link to this sectionどの 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.

Link to this sectionどの Ultralytics モデルをエクスポートできますか？#

このガイドは検出モデルに焦点を当てています。タスクレベルの範囲については サポートされるタスク、モデルの互換制限については 互換性に関する注意点、YOLO11 および YOLOv8 のエンドノード例については サポートされるモデルとエンドノード を参照してください。

Link to this sectionなぜ YOLO11 のモデルスクリプトで meta_arch=yolov8 を使用するのですか？#

YOLO11 は YOLOv8 と同じデカップリング検出ヘッドアーキテクチャを使用しているためです。Hailo DFC は両方のモデルファミリーの NMS 設定に meta_arch=yolov8 を使用します。

Link to this section最適化ステップに GPU は必要ですか？#

runner.optimize() での量子化を意識した微調整（fine-tuning）には、GPU を強く推奨します。GPU がなくても処理は可能ですが、大幅に時間がかかります（数時間対 GPU 使用時の約 10～20 分）。

Link to this sectionモデルの正しいエンドノードを見つけるにはどうすればよいですか？#

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.

Link to this sectionHailo DFC SDK と NMS 設定ファイルはどこで入手できますか？#

The Hailo DFC SDK Python wheel is available from the Hailo Developer Zone, while predefined .alls scripts and NMS config files are available from the Hailo Model Zoo.