Hailo HEF モデル変換ガイド

ONNX モデル、キャリブレーションデータ、および Hailo-8 または Hailo-10H 向けのターゲット固有 Hailo HEF を準備します。

このガイドでは、CV モデルを Hailo Executable File (.hef) に変換し、 reComputer R Series (CM5 + Hailo-8) または reComputer R Series (CM5 + Hailo-10H) 向けに用意する開発ワークフローを説明します。

.hef はターゲット固有です。Hailo-8 用の HEF を Hailo-10H に、または Hailo-10H 用の HEF を Hailo-8 にデプロイしないでください。ターゲットごとにビルド、検証、ラベル付け、パブリッシュを別々の成果物として行ってください。

事前準備

モデル変換とランタイム推論は異なります。

  • HailoRT はデバイス上で既存の HEF を実行します。ONNX の変換は行いません。
  • Hailo Dataflow Compiler (DFC) は、解析、最適化、 量子化、HEF コンパイルを実行します。
  • DFC は、Hailo が提供するサポート対象の開発ホスト環境で実行し、 Raspberry Pi のデプロイメントデバイス上では実行しないでください。

変換前に以下を準備してください。

  1. 固定形状の ONNX モデルと、明示的な入力レイアウト/カラー順序。
  2. 本番データと一致する、代表的なキャリブレーション画像セット。
  3. 後処理要件: クラスリスト、アンカー、閾値、NMS モード、 キーポイントレイアウト、マスクデコード、およびホスト側の操作。
  4. 対象ハードウェアターゲットをサポートする DFC および Model Zoo リリース。

Hailo の現在の Model Zoo master ブランチは、Hailo-10/15 デバイスを対象としています。 Hailo-8 または Hailo-8L の場合は、互換性のある Model Zoo v2.x リリースを、対応する DFC リリースと共に使用してください。Hailo-8 モデルのコンパイルに master を使用しないでください。

1. 公式開発環境のインストール

Hailo Developer Zone から Hailo Software Suite または Dataflow Compiler をインストールし、 そのインストールに付属する Python 環境をアクティベートします。 DFC は Raspberry Pi デプロイメントデバイスにはインストールされません。

公式の Model Zoo をクローンし、使用する DFC およびターゲットと互換性のあるリリースを選択します。 タグのプレースホルダーは、インストールした Hailo Software Suite に記載されているリリースに置き換えてください。

Hailo-10H

bash
git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
git checkout <compatible-hailo10h-release>
pip install -e .

Hailo-8

bash
git clone https://github.com/hailo-ai/hailo_model_zoo.git
cd hailo_model_zoo
git checkout <compatible-v2.x-release>
pip install -e .

CLI が利用可能であることを確認します。

bash
hailomz --version
hailomz info <model_name>

2. 公式 Model Zoo ネットワークのコンパイル

Hailo Model Zoo が既に提供しているネットワークの場合、compile は必要な解析と最適化のステージを実行し、 HEF を生成します。

bash
# Hailo-8: run this from a compatible Model Zoo v2.x environment
hailomz compile <model_name> --hw-arch hailo8

# Hailo-10H: run this from a compatible Hailo-10H environment
hailomz compile <model_name> --hw-arch hailo10h

各ステージを個別に検査する必要がある場合は、公式 CLI で以下も提供されています。

bash
hailomz parse <model_name> --hw-arch <hailo8-or-hailo10h>
hailomz optimize <model_name> --hw-arch <hailo8-or-hailo10h>
hailomz compile <model_name> --hw-arch <hailo8-or-hailo10h>

ネットワーク名、キャリブレーションデータセット、前処理、後処理、 モデルスクリプトは、そのネットワークの Model Zoo YAML および ALLS ファイルから取得されます。生成された HEF を 受け入れる前に、それらを確認してください。

3. 実例: YOLO11n の変換

Hailo は公式に yolov11n の Model Zoo 設定を提供しています。v2.19.0 設定は Hailo-8/Hailo-8L をサポートし、現在の Hailo-10H Model Zoo 設定は Hailo-10H をサポートします。ターゲットに合った環境とブランチを使用してください。

Hailo の事前学習済み YOLO11n のコンパイル

Model Zoo は参照されているチェックポイントをダウンロードし、メンテナンスされている YAML、パーサーノード、モデルスクリプト、キャリブレーションフロー、NMS 設定を適用します。

YAML, parser nodes, model script, calibration flow, and NMS configuration:

bash
# In a Hailo-8-compatible Model Zoo v2.x environment
hailomz info yolov11n
hailomz compile yolov11n --hw-arch hailo8
bash
# In a Hailo-10H-compatible Model Zoo environment
hailomz info yolov11n
hailomz compile yolov11n --hw-arch hailo10h

独自に学習させた YOLO11n のコンパイル

まず、Ultralytics の学習チェックポイントを固定 640 ピクセルの ONNX モデルにエクスポートします。 この手順は学習環境で実行してください。DFC 環境では、Python 要件が互換性がある場合を除き、 実行しないでください。

unless their Python requirements are compatible.

bash
pip install ultralytics
yolo export model=/path/to/best.pt format=onnx imgsz=640

Validate the exported ONNX before quantization:

bash
yolo predict model=/path/to/best.onnx source=/path/to/test.jpg

ターゲットとクラス数を設定し、Hailo の YOLO11n ネットワーク設定を使用してコンパイルします。

class count for your trained dataset and compile using Hailo's YOLO11n network configuration:

bash
# Use hailo8 in a compatible v2.x environment, or hailo10h in its matching environment.
TARGET_ARCH=hailo10h
NUM_CLASSES=3

hailomz compile \
  --ckpt /path/to/best.onnx \
  --calib-path /path/to/calibration/images \
  --yaml hailo_model_zoo/cfg/networks/yolov11n.yaml \
  --classes "$NUM_CLASSES" \
  --hw-arch "$TARGET_ARCH"

入力解像度、検出ヘッド、レイヤー名、出力レイアウトなど）、標準の YOLO11n の YAML および ALLS ファイルは適用できなくなる可能性があります。コマンドを強制的に完了させるのではなく、 それらのファイルを更新して検証してください。

最後に、HEF をターゲットデバイスにコピーし、実行できることを確認します。

Finally, copy the HEF to the target device and verify that it executes:

bash
scp /path/to/yolov11n.hef seeed@<BOARD_IP>:~/
ssh seeed@<BOARD_IP>
hailortcli fw-control identify
hailortcli benchmark ~/yolov11n.hef

それだけではバウンディングボックスデコードが検証されたことにはなりません。

4. サポートされている別のカスタム ONNX チェックポイントのコンパイル

Hailo の公式トレーニングガイドでは、カスタム ONNX モデルが既存の Model Zoo ネットワーク定義と 一致する場合に、以下の Model Zoo 形式を使用します。

Hailo's official training guides use the following Model Zoo form when a custom ONNX model matches an existing Model Zoo network definition:

bash
hailomz compile \
  --ckpt /path/to/model.onnx \
  --calib-path /path/to/calibration/images \
  --yaml /path/to/hailo_model_zoo/cfg/networks/<network>.yaml \
  --hw-arch <hailo8-or-hailo10h>

Only add parser node overrides when the model's official guide or a verified Netron inspection requires them:

bash
hailomz compile \
  --ckpt /path/to/model.onnx \
  --calib-path /path/to/calibration/images \
  --yaml /path/to/<network>.yaml \
  --start-node-names <input_node> \
  --end-node-names <output_node_1> <output_node_2> \
  --hw-arch <hailo8-or-hailo10h>

正しいエンドノード、前処理、量子化、後処理を自動的に決定できません。

5. 変換ワークフロー

  1. ONNX のエクスポートと検証。 入力サイズと前処理を固定します。コンパイル前に、 ホスト側のテスト画像で ONNX モデルをチェックします。
  2. ハードウェアターゲットの選択。 Hailo-8 と Hailo-10H で別々の変換ワークスペースを 作成します。ソース ONNX とキャリブレーションデータを追跡可能な状態に保ちます。
  3. ネットワークの解析。 DFC パーサーを使用して中間ネットワーク表現を生成し、 すべての入出力テンソル名と形状を検査します。
  4. 前処理と後処理の設定。 可能な限り、対応する Hailo Model Zoo ネットワーク設定を 使用します。カスタムの正規化、リサイズ、アンカー、NMS、出力デコードの決定事項は、 すべてモデルの README に記録します。 5. キャリブレーションデータによる最適化。 代表的な画像を使用して量子化を実行します。 コンパイル前に警告と精度結果を確認します。 6. HEF のコンパイル。 選択したターゲット向けに個別にコンパイルし、 成果物に model_hailo8.hef や model_hailo10h.hef のように、明確な名前を付けます。 7. ハードウェアでの検証。 一致する HailoRT リリースで HEF を実行し、 出力テンソルと後処理結果をホストリファレンスと比較し、 /dev/hailo0 が利用可能であることを確認します。
  5. Compile the HEF. Compile separately for the selected target, then name artifacts unambiguously, for example model_hailo8.hef and model_hailo10h.hef.
  6. Validate on hardware. Run the HEF with the matching HailoRT release, compare output tensors and post-processed results with the host reference, and verify /dev/hailo0 is available.

6. HEFの検証

生成したHEFを、対応するアクセラレータとHailoRTリリースが導入されたハードウェアにコピーし、デバイスを認識させてから公式のベンチマークコマンドを実行します。

bash
hailortcli fw-control identify
hailortcli benchmark /path/to/model.hef

ベンチマークが成功すれば、HEFがデバイス上で実行可能であることが証明されます。ただし、アプリケーションの前処理や出力デコードまでは検証されないため、エンドツーエンドの結果をソースモデルのリファレンス実装と比較してください。

7. Hailo-8 / Hailo-10H リリースチェックリスト

チェック項目Hailo-8Hailo-10H
HEFターゲットHailo-8Hailo-10H
ランタイムデバイスのHailoRT 4.xリリースに合わせるデバイスのHailoRT 5.xリリースに合わせる
コンテナマウントlibhailort.so.4.x に一致libhailort.so.5.x に一致
検証hailortcli fw-control identify およびサービス推論hailortcli fw-control identify およびサービス推論

8. 公開とデプロイ

新規モデルターゲットごとに以下の作業を行います。

  1. 該当するHailo CVリポジトリに、HEF、ソースモジュール、Dockerfile、デモ用メディア、テスト済みコマンドを追加します。

  2. 実機ターゲットハードウェア上でGHCRイメージをビルドし、テストします。

  3. 対応するAI Labのモデルデプロイエントリとプラットフォーム固有のWikiを追加します。

  4. モデルのダウンロード総数を表示できるように、パッケージURLを downloadSources に追加します。

HEFの検証後は、本セクションの Hailo-8 CVモデルデプロイ または Hailo-10H CVモデルデプロイ のページを参照し、デバイスチェック、イメージプル、Docker実行コマンド、ブラウザプレビューまでの完全な手順を実施してください。

公式リファレンス: