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

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

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. 代表的な画像を使用して キャリブレーションと量子化 を実行
5. 展開可能なHEFファイルに コンパイル

サポートされているタスク

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

インスタンスセグメンテーション、セマンティックセグメンテーション、姿勢推定、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

このステップでは、量子化を考慮した微調整とレイヤーノイズ分析が行われます。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は同じ分離型検出ヘッドを共有しています。両ファミリー間でレイヤーインデックスが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",
]

その他のアーキテクチャ

その他の検出アーキテクチャについては、まず 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ハードウェアでの推論の実行

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.

ステップ 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. 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のデプロイパスを比較することもできます。

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() における量子化を意識した微調整には、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から入手できます。