RK3576 で CNN モデルを実行する方法
Ubuntu PC で YOLO11n を変換し、SSH/SCP で RK3576 に配置して、内蔵 NPU による C++ と Python の推論を検証します。
クイックスタート:RK3576 で CNN モデルを実行する
このガイドでは、NPU ドライバーの確認 → Runtime と Toolkit Lite2 のインストール → PC でのモデル変換 → C++ のビルドと配置 → ボード上での推論を順に行います。RKNN Model Zoo の YOLO11n を RK3576 内蔵 NPU で実行し、SSH/SCP またはボードのローカル端末を使います。
#始める前に
| 項目 | このガイドの設定と検証環境 |
|---|---|
| PC | Ubuntu 20.04.6 LTS,x86_64,Python 3.11 |
| ボード | reComputer RK3576、aarch64 |
| ボード OS | Debian 12 / Armbian 26.05.0-trunk |
| ボードのカーネル | 6.1.115-vendor-seeed-rk3576 |
| NPU ドライバー | 検証済み 0.9.8 |
| ツールのバージョン | RKNN-Toolkit2 / Toolkit Lite2 2.3.2 |
| Runtime | このガイドでは librknnrt.so 2.3.2 をインストール |
| サンプル | YOLO11n、640 × 640、INT8 量子化 |
| 変換 / ビルド対象 | rk3576 / rk3576 + aarch64 |
コマンドの実行場所:「PC で実行」は Ubuntu 開発機、「ボードで実行」は SSH 接続後またはボードのローカル端末を指します。BOARD_IP はプレースホルダーです。ボードの LAN 内 IP アドレスに置き換えてください。
ボードで SSH が有効になっていない場合は、まずボードのローカル端末で実行します。
sudo apt update
sudo apt install openssh-server
sudo systemctl enable --now ssh
hostname -I続いて PC から接続します。初回接続時はホストのフィンガープリントを確認し、求められたらアカウントのパスワードを入力します。
ssh rk3576@BOARD_IP#1. NPU ドライバーがない場合の対処
#1.1 カーネルドライバーとユーザー空間ソフトウェアの違い
RK3576 の NPU ドライバーはカーネル内の RKNPU で、設定項目は CONFIG_ROCKCHIP_RKNPU です。Runtime の .so ファイルや Toolkit Lite2 の Python wheel はカーネルドライバーの代わりになりません。
#1.2 ドライバー、デバイスノード、負荷の確認
ボードで実行:
uname -r
sudo dmesg | grep -i rknpu
sudo cat /sys/kernel/debug/rknpu/version
sudo cat /sys/kernel/debug/rknpu/load
ls -l /sys/class/drm/renderD*/device/driver実機で得た出力の抜粋:
RKNPU driver: v0.9.8
NPU load: Core0: 0%, Core1: 0%,
/sys/class/drm/renderD129/device/driver -> .../bus/platform/drivers/RKNPUrenderD129 は今回列挙された NPU ノードで、固定番号ではありません。device/driver が RKNPU を指すことで識別します。他の render ノードはディスプレイコントローラーや GPU の場合があるため、/dev/dri の存在だけで NPU が正常とは判断できません。
debugfs が未マウントの場合は、先に次を実行します。
mountpoint -q /sys/kernel/debug || sudo mount -t debugfs debugfs /sys/kernel/debugその後、バージョン確認を再試行します。debugfs の照会ファイルだけがない場合、ドライバーの欠如は証明できません。起動ログとドライバーのバインドも確認してください。
ボードのカーネル設定を確認します。
grep '^CONFIG_ROCKCHIP_RKNPU=' /boot/config-$(uname -r)実際の出力:
CONFIG_ROCKCHIP_RKNPU=y=y はカーネルへの組み込みを意味します。したがって lsmod に rknpu がなくてもドライバーが欠けているとは限りません。公式 RKNN SDK V2.3.2 クイックスタートでは RKNPU ドライバー 0.9.2 以上を推奨し、今回は 0.9.8 で推論を検証しました。
#1.3 ドライバーがない、または更新が必要な場合
このガイドでは reComputer RK3576 用 Seeed/Armbian カーネルを使用します。ドライバー確認に問題がなければ、カーネルを再インストールせずにセクション 2 に進みます。
同じボードで Seeed のパッケージソースが設定済みなら、まずカーネルとデバイスツリーのパッケージを確認します。
sudo apt update
apt-cache policy linux-image-vendor-seeed-rk3576 linux-dtb-vendor-seeed-rk3576両パッケージがボードに対応するソースから提供され、候補バージョンが一致することを確認してから、対応するカーネルとデバイスツリーをインストールまたは更新します。
sudo apt install --reinstall linux-image-vendor-seeed-rk3576 linux-dtb-vendor-seeed-rk3576
sudo rebootこの保守作業は起動カーネルを変更し、SSH を切断します。再接続後にセクション 1.2 を確認してください。インストールコマンドの成功だけではドライバーの検証になりません。
パッケージがない場合は、このボードの型番に対応するメーカーのイメージまたは BSP を入手してください。別のボードのカーネルをインストールしたり、rknpu.ko を無作為にコピーしたり、RK182x の DKMS パッケージを流用したりしないでください。独自 BSP では、対応カーネルで CONFIG_ROCKCHIP_RKNPU=y を有効にし、正しい NPU デバイスツリーを保持して、その BSP の手順でビルド・配置します。カーネルとデバイスツリーはボード固有であり、Toolkit の pip install では補えません。
#2. Runtime と Toolkit Lite2 のインストールと検証
#2.1 3 つのコンポーネントの役割
| コンポーネント | インストール先 | 主な役割 |
|---|---|---|
| RKNN-Toolkit2 | Ubuntu PC の独立した Python 環境 | ONNX の変換と量子化、.rknn の生成 |
RKNN Runtime / librknnrt.so | RK3576 ボード | モデルの読み込みと NPU 推論を行う C/C++ API |
| RKNN-Toolkit-Lite2 | RK3576 ボードの Python 環境 | Python 推論 API。ボードの Runtime とドライバーが必要 |
PC では from rknn.api import RKNN、ボード上の Lite2 では from rknnlite.api import RKNNLite を使います。Lite2 は推論用であり、ONNX を RKNN に変換しません。C++ サンプルは Lite2 に依存しません。
このガイドでは SCP でファイルを転送してボード上で実行します。PC から USB 経由で推論しないため、rknn_server の起動は不要です。
#2.2 PC で公式リポジトリの固定リビジョンを取得
セクション 3 と 4 でも同じ 2 つのディレクトリを使います。新しい作業ディレクトリに一度だけクローンしてください。
PC で実行:
sudo apt update
sudo apt install git wget cmake make gcc g++ openssh-client
mkdir -p ~/RKNN2_Project
cd ~/RKNN2_Project
git clone https://github.com/airockchip/rknn-toolkit2.git
git -C rknn-toolkit2 checkout 59a913d172e7f5ff03c9076e2ec7b1b1288ffd08
git clone https://github.com/airockchip/rknn_model_zoo.git
git -C rknn_model_zoo checkout bad6c7334531becaf90a561988519b7bec34d0abこれは実機検証に使用したコミットで、Model Zoo は v2.3.2 に相当します。後日の更新でコマンドのパスが変わらないよう、コードとパッケージを固定します。
#2.3 ボードの Runtime をインストール
PC で実行:
ssh rk3576@BOARD_IP 'mkdir -p ~/RKNN2_Project/packages'
scp ~/RKNN2_Project/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/aarch64/librknnrt.so \
rk3576@BOARD_IP:~/RKNN2_Project/packages/ボードで実行: 既存のライブラリがあればバックアップしてから新しいライブラリをインストールします。
sudo apt update
sudo apt install binutils
if [ -e /usr/lib/librknnrt.so ]; then
sudo cp -a /usr/lib/librknnrt.so "/usr/lib/librknnrt.so.bak-$(date +%Y%m%d-%H%M%S)"
fi
sudo install -m 0644 ~/RKNN2_Project/packages/librknnrt.so /usr/lib/librknnrt.so
sudo ldconfig
strings /usr/lib/librknnrt.so | grep 'librknnrt version'このパッケージのバージョン文字列:
librknnrt version: 2.3.2 (429f97ae6b@2025-04-09T09:09:27)Lite2 にはこの手順が必要です。 今回検証した Lite2 は /usr/lib/librknnrt.so を探します。Demo ディレクトリの LD_LIBRARY_PATH を設定するだけではシステムライブラリの確認を代替できません。RK3588 ではファイルがないため Can not find dynamic library on RK3588! が発生し、配置後に解消しました。
#2.4 ボードに Toolkit Lite2 をインストール
ボードの Debian 12 は Python 3.11 を使用するため、cp311 と aarch64 の wheel を選びます。
PC で実行:
scp ~/RKNN2_Project/rknn-toolkit2/rknn-toolkit-lite2/packages/rknn_toolkit_lite2-2.3.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl \
rk3576@BOARD_IP:~/RKNN2_Project/packages/ボードで実行:
sudo apt install python3.11-venv
python3 -m venv ~/venvs/rknn-lite2
source ~/venvs/rknn-lite2/bin/activate
python -m pip install \
~/RKNN2_Project/packages/rknn_toolkit_lite2-2.3.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
python -m pip check
python -c "from rknnlite.api import RKNNLite; print('RKNN Toolkit Lite2 import OK')"2 つの確認で得た実際の出力:
No broken requirements found.
RKNN Toolkit Lite2 import OKPC 用の x86_64 wheel をボードに転送しないでください。ensurepip is not available が出る場合は python3.11-venv のインストールを確認し、仮想環境を作り直します。インポート成功は Python パッケージの確認にすぎず、実際の NPU 推論はセクション 4 で検証します。
#3. Ubuntu PC で Toolkit を設定して YOLO11n を変換
#3.1 PC に Python 3.11 環境を作成
PC で実行: 新しい PC 向けの Miniforge インストール手順です。Conda がすでにあれば、既存の Conda で同名の環境を作成できます。
mkdir -p ~/Downloads
cd ~/Downloads
wget -c https://github.com/conda-forge/miniforge/releases/download/25.3.0-1/Miniforge3-25.3.0-1-Linux-x86_64.sh
bash Miniforge3-25.3.0-1-Linux-x86_64.sh -b -p "$HOME/miniforge3"
source ~/miniforge3/etc/profile.d/conda.sh
conda create -n rknn2 python=3.11 -y
conda activate rknn2PC の新しい端末では、以降の Python コマンドの前に source ~/miniforge3/etc/profile.d/conda.sh と conda activate rknn2 を実行します。
#3.2 Toolkit2 2.3.2 をインストール
PC で実行:
cd ~/RKNN2_Project/rknn-toolkit2/rknn-toolkit2
python -m pip install \
-r packages/x86_64/requirements_cp311-2.3.2.txt \
packages/x86_64/rknn_toolkit2-2.3.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl \
'onnx==1.16.1' 'protobuf==4.25.4'
python -m pip check
python -m pip show rknn-toolkit2
python -c "from rknn.api import RKNN; print('RKNN Toolkit2 import OK')"検証した変換環境は Python 3.11.14 と Toolkit2 2.3.2 です。依存関係を修正した後、pip check は No broken requirements found. を返しました。
ONNX と protobuf を明示的に固定すると、古いプロジェクトの依存関係との混在を防げます。独立環境の ONNX 1.16.1 と protobuf 4.25.4 で変換し、元の Conda 環境は変更しません。
#3.3 公式に適合した YOLO11n をダウンロード
PC で実行:
cd ~/RKNN2_Project/rknn_model_zoo/examples/yolo11/model
bash download_model.sh
ls -lh yolo11n.onnxダウンロードした yolo11n.onnx のサイズは 10,527,859 バイトでした。
この Rockchip 向け ONNX を使用してください。出力レイアウトは公式 C++ 後処理に対応しており、任意の Ultralytics の元のエクスポートで置き換えないでください。独自学習モデルは公式の YOLO11 エクスポート手順 に従って調整します。
#3.4 RK3576 INT8 モデルに変換
PC で実行:
conda activate rknn2
cd ~/RKNN2_Project/rknn_model_zoo
export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"
ls datasets/COCO/coco_subset_20.txt
ls datasets/COCO/subset
cd examples/yolo11/python
python convert.py ../model/yolo11n.onnx rk3576 i8 ../model/yolo11n_rk3576.rknn
ls -lh ../model/yolo11n_rk3576.rknn4 つの引数は ONNX パス、対象プラットフォーム、量子化方式、出力パスの順です。このページでは必ず rk3576 を使用します。
変換スクリプトはリポジトリ内の datasets/COCO/coco_subset_20.txt を較正データに使用します。相対パスが正しく解決されるよう examples/yolo11/python から実行してください。この小規模データセットは初回確認用です。実運用モデルは実際のシーンを代表するデータで較正し、精度を評価してください。
実際の変換出力の抜粋:
I rknn-toolkit2 version: 2.3.2
...
--> Building model
...
I rknn building ...
I rknn building done.
done
--> Export rknn model
done最初のログ行にはツール内部のビルド情報が加わる場合があります。対象ファイルの生成を成功の基準とします。既定の入出力型が int8 になったという通知は量子化スクリプトの通常の表示です。対応する C++ サンプルで入出力を扱い、画像を独自に符号付き値へ変換しないでください。
この RKNN2 サンプルでは、ボードに配置する .rknn モデルファイルは 1 つだけです。
#4. ビルドし、SCP で配置して実行
#4.1 ARM64 クロスコンパイラーを準備
PC で実行:
cd ~/RKNN2_Project
wget -c https://dn.odroid.com/compiler/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar
tar -xf gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar
export GCC_COMPILER="$HOME/RKNN2_Project/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu"
"${GCC_COMPILER}-gcc" --version検証したコンパイラーは Linaro GCC 6.3.1 20170404 です。GCC_COMPILER は末尾の -gcc を含まない接頭辞で、ビルドスクリプトが追加します。
#4.2 RK3576 用 YOLO11 C++ サンプルをビルド
PC で実行:
cd ~/RKNN2_Project/rknn_model_zoo
bash build-linux.sh -t rk3576 -a aarch64 -b Release -d yolo11リポジトリのスクリプトに実行権限がなくても Permission denied とならないよう、bash build-linux.sh を使用します。モデルを先に変換してからビルドすると、生成した .rknn が配置ディレクトリに含まれます。
配置ディレクトリの構成例です。その他の同梱サンプルは残して構いません。
install/rk3576_linux_aarch64/rknn_yolo11_demo/
├── rknn_yolo11_demo
├── lib/
│ ├── librknnrt.so
│ └── librga.so
└── model/
├── yolo11n_rk3576.rknn
├── bus.jpg
└── coco_80_labels_list.txt同じリポジトリで両プラットフォーム向けに変換すると、インストール先に .rknn が 2 つ入る場合があります。実行時は rk3576 の接尾辞があるファイルを明示的に選びます。
#4.3 SCP でディレクトリ全体を配置
PC で実行:
ssh rk3576@BOARD_IP 'mkdir -p ~/RKNN2_Project'
cd ~/RKNN2_Project/rknn_model_zoo
scp -r install/rk3576_linux_aarch64/rknn_yolo11_demo \
rk3576@BOARD_IP:~/RKNN2_Project/実行ファイルだけでなく lib/ と model/ もコピーします。サンプルの Runtime は lib/ に同梱され、検証したバージョンは 2.3.2 です。
#4.4 ボード上で物体検出を実行
ボードで実行:
cd ~/RKNN2_Project/rknn_yolo11_demo
sudo env LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
./rknn_yolo11_demo model/yolo11n_rk3576.rknn model/bus.jpgRK3576 の実際の出力の抜粋:
model input num: 1, output num: 9
model is NHWC input fmt
model input height=640, width=640, channel=3
...
rknn_run
bus @ (95 136 553 438) 0.944
person @ (108 236 222 535) 0.898
person @ (212 240 284 509) 0.835
person @ (476 229 559 522) 0.831
person @ (79 358 117 515) 0.452
write_image path: out.png width=640 height=640 channel=3 ...プロセスが正常終了し、バスと人物の検出結果を表示して、現在のディレクトリに out.png を生成すれば成功です。座標とスコアはツールや量子化の結果で多少変わります。安定した FPS は測定しておらず、この機能確認は性能ベンチマークではありません。
PC で実行して画像を取得:
mkdir -p ~/RKNN2_Project/results
scp rk3576@BOARD_IP:~/RKNN2_Project/rknn_yolo11_demo/out.png \
~/RKNN2_Project/results/yolo11n-rk3576-out.pngPC で画像を開き、検出枠を確認します。ボードにディスプレイが接続されていれば、ボードの GUI でも開けます。
#4.5 Lite2 で同じモデルが動作することを確認
C++ 検出後、同じモデルで Python 推論経路を確認できます。
ボードで実行:
cd ~/RKNN2_Project/rknn_yolo11_demo
sudo "$HOME/venvs/rknn-lite2/bin/python" - <<'PYCODE'
import numpy as np
from rknnlite.api import RKNNLite
rknn = RKNNLite()
try:
ret = rknn.load_rknn('model/yolo11n_rk3576.rknn')
if ret != 0:
raise RuntimeError(f'load_rknn failed: {ret}')
ret = rknn.init_runtime()
if ret != 0:
raise RuntimeError(f'init_runtime failed: {ret}')
outputs = rknn.inference(inputs=[np.zeros((1, 640, 640, 3), dtype=np.uint8)])
if outputs is None:
raise RuntimeError('inference failed')
print('Lite2 inference OK; output count:', len(outputs))
finally:
rknn.release()
PYCODE実際の結果:
Lite2 inference OK; output count: 9仮想環境の Python を絶対パスで指定し、sudo python3 が Lite2 のないシステム Python を呼ばないようにします。
#4.6 よくある問題と完了条件
| 症状 | 確認事項 |
|---|---|
| NPU ドライバーが見つからない | セクション 1.2 の RKNPU バインドと起動ログを確認。内蔵ドライバーは lsmod に現れなくてもよい |
| Lite2 のインポートは成功するが初期化に失敗 | /usr/lib/librknnrt.so、NPU ドライバー、アクセス権を確認 |
Can not find dynamic library | セクション 2.3 に従いシステム Runtime を配置。Demo の lib/ だけでは不十分 |
pip check で依存関係が競合 | セクション 3.2 の独立した PC 環境を使い、他プロジェクトの古い ONNX/protobuf を使わない |
較正画像または py_utils が見つからない | 作業ディレクトリ、リポジトリの較正データ、PYTHONPATH を確認 |
| モデルのプラットフォームが違う | rk3576 向けに再変換し、yolo11n_rk3576.rknn を実行 |
| モデルまたはラベルファイルがない | 配置ディレクトリ全体をコピーし、先に rknn_yolo11_demo に移動 |
| 動的ライブラリがない | lib/librknnrt.so を確認し、セクション 4.4 のように LD_LIBRARY_PATH を指定 |
完了時には、NPU ドライバーの照会、Runtime/Lite2 の利用、PC での変換、C++ による検出画像の生成、Lite2 による 9 個の出力テンソルの取得ができるはずです。
#4.7 参考資料
- RKNN-Toolkit2 公式リポジトリ:Toolkit、Runtime、Lite2 と関連文書。
- RKNN SDK V2.3.2 クイックスタート:このガイドでは接続と転送に SSH/SCP を使用。
- 今回検証した YOLO11 サンプル:ONNX のダウンロード、変換スクリプト、C++ 後処理。
- Seeed Armbian 拡張とパッケージソース:reComputer 向けカーネルとデバイスツリーのパッケージの提供元。