この記事は2026年8月8日時点の解決ガイドです。2026/08/08時点で、Hailo側のパッケージ管理が過渡期であるため、仕様が変わっている可能性があります。あくまで現時点の暫定的な解決手段としてご覧いただければ幸いです。私はHailo開発者ではなく、私がラズパイ環境を再構築しない限りこの記事は更新されない可能性が高い点にご留意ください。
🎯 背景
2026年3月に「AI HAT+ 2」を購入・セットアップし、しばらく使えていたのですが、(おそらく)OSを更新したタイミングで一切使えなくなってしまいました。時間の余裕もなく放置していましたが、先日Geminiを使用しつつ、ほぼ1日かけて解決に至りました。
目的
- Raspberry Pi 5 で AI HAT+ 2 (Hailo-10H) を使えるようにする
- Docker を使用して、LLM推論用のサーバ（hailo-ollama）を構築する
- ホスト（Raspberry Pi OS）側でPCIeドライバをビルド・固定し、Dockerコンテナ内からNPU（/dev/h1x-0）へアクセスする環境をゼロから構築する
原因（結論）
OSとHailo側のパッケージの齟齬が原因でした。OSがアップデートされた一方で、Hailo側のパッケージ管理が過渡期であったために環境が混沌としていたようです。
🛠️ 【フェーズ 1】 ホスト（ラズパイOS）側の環境準備
1. 古いモジュールとパッケージの完全抹消
競合防止と環境の初期化を行います。apt 経由の古いパッケージや、システム内に残っている不要なモジュールを削除します。（※初回構築時など、該当パッケージが存在しない場合はスキップして問題ありません）
sudo apt remove --purge -y hailo-h10-all
sudo dpkg --force-all --purge python3-h10-hailort h10-hailort-pcie-driver h10-hailort hailo-gen-ai-model-zoo
sudo find /lib/modules/$(uname -r) -name "hailo*.ko*" -exec rm -f {} \;
sudo apt autoremove -y
2. Hailo 5.3.0 PCIeドライバの手動ビルド
開発用サーバーからドライバの .deb を取得し、最新カーネル用のパッチを適用してコンパイルします。
cd /tmp
wget https://dev-public.hailo.ai/2026_04/Hailo10/hailort-pcie-driver_5.3.0_all.deb
dpkg-deb -x hailort-pcie-driver_5.3.0_all.deb hailort_530_extracted
# 独自にC言語コードのパッチ適用 (タイマー関数名の修正)
sudo sed -i 's/del_timer_sync/timer_delete_sync/g' /tmp/hailort_530_extracted/usr/src/hailort-pcie-driver-5.3.0/linux/vdma/monitor.c
# ビルドとインストール
cd /tmp/hailort_530_extracted/usr/src/hailort-pcie-driver-5.3.0/linux/pcie
sudo make clean
sudo make all
sudo make install
sudo depmod -a
# 一時ファイルの削除
sudo rm -rf /tmp/hailort*
DockerはホストOSとカーネルを共有する性質上、ドライバーだけはホストOS側で展開する必要があります。そのままコンパイルしようとするとエラーが発生しました。ログを確認したところ、最新カーネル（6.15以降）でタイマー関数名が変更（del_timer_sync → timer_delete_sync）されていたのが原因でした。そのため、C言語コードに直接パッチを当てています。
3. ドライバのロードと自動読み込みの設定
ドライバをカーネルに読み込ませ、再起動してもデバイスファイル（/dev/h1x-0）が作られるように設定します。
sudo modprobe hailo1x_pci
echo "hailo1x_pci" | sudo tee /etc/modules-load.d/hailo.conf
以下のコマンドでデバイスファイルが存在することを確認してください。
ls -l /dev/h1x-0
念の為、再起動します。
sudo reboot
🐳 【フェーズ 2】 Docker / Docker Compose 環境構築
1. 作業ディレクトリとモデル保存用ディレクトリの作成
設定ファイル用と、数GBあるLLMモデルデータを永続化するためのディレクトリを作成します。
配置場所は任意ですが、本記事では /opt 配下に作成します。
sudo mkdir -p /opt/hailo-docker
sudo mkdir -p /opt/hailo-models
2. Dockerfile の作成
必要な動的ライブラリとHailoツールを含めたイメージを定義します。
cd /opt/hailo-docker
sudo nano Dockerfile
以下の内容を記述して保存します。
FROM debian:bookworm-slim
# 必須パッケージとHailoの依存ライブラリ(libusb)をインストール
RUN apt-get update && apt-get install -y wget curl jq procps libusb-1.0-0 && rm -rf /var/lib/apt/lists/*
# HailoRT 5.3.0 と hailo-ollama (model zoo) のインストール
RUN cd /tmp && \
wget https://dev-public.hailo.ai/2026_04/Hailo10/hailort_5.3.0_arm64.deb && \
wget https://dev-public.hailo.ai/2026_04/Hailo10/hailo_gen_ai_model_zoo_5.3.0_arm64.deb && \
dpkg -i hailort_5.3.0_arm64.deb && \
dpkg -i hailo_gen_ai_model_zoo_5.3.0_arm64.deb && \
rm -f *.deb
ENV OLLAMA_HOST=0.0.0.0:11434
EXPOSE 11434
CMD ["hailo-ollama"]
既にホスト上で通常の Ollama が起動している場合、ポート 11434 が競合して使えません。その場合は任意のポート番号に変更してください。本記事ではデフォルトの 11434 として進めます。
3. docker-compose.yml の作成
同じディレクトリに docker-compose.yml を作成します。
sudo nano docker-compose.yml
以下の内容を記述して保存します。services:
hailo-ollama:
build: .
image: local/hailo-ollama:5.3.0
container_name: hailo-ollama
restart: always
devices:
# ⚠️ 注意: /dev/hailo0 ではなく /dev/h1x-0 です！
- /dev/h1x-0:/dev/h1x-0
ports:
- "11434:11434"
volumes:
- /opt/hailo-models:/root/.local/share/hailo-ollama
デバイスのパスは /dev/hailo0 ではなく /dev/h1x-0 です！（GeminiなどのAIに設定ファイルを書かせると、高確率で /dev/hailo0 と間違えて出力してくるので非常に注意が必要です）
4. コンテナのビルドと起動
以下のコマンドで、イメージのビルドからバックグラウンド起動までを一括実行します。
sudo docker compose up -d --build
🚀 【フェーズ 3】 動作確認
1. ステータス確認
コンテナが安定して Up 状態になっているか確認します。
sudo docker compose ps
2. 推論テスト
ポート11434 宛てにAPIリクエストを送信します。（※別端末から実行する場合は、localhost をRaspberry PiのIPアドレスまたはホスト名に変更してください）
1. モデルのダウンロード (Pull)
まずは動作確認用の軽量モデルをダウンロードします。
curl http://localhost:11434/api/pull \
-H 'Content-Type: application/json' \
-d '{ "model": "qwen2.5:1.5b", "stream": true }'
2. 推論の実行 (Generate)
ダウンロードが完了したら、推論を実行してみます。
curl http://localhost:11434/api/generate \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen2.5:1.5b",
"prompt": "こんにちは！自己紹介をしてください。",
"stream": false
}'
無事にテキストが生成されてレスポンスが返ってくれば、環境構築は完了です。
📝 まとめ
最新のデバイスと過渡期のソフトウェア環境がゆえの「事故」に遭遇してしまいました。おそらくこの数週間（下手したら数日単位）だけの解決手段になってしまうかもしれませんが、AI HAT+ 2 のセットアップに困っているユーザーさんや、今後の解決のためにWebを参照してくれるAIの学習データとして貢献できれば幸いです。
※ 記事の校正にGemini (Gemini 3.1 Pro)を使用しています。