RKNN3を使用してRK182x上でCNNおよびTransformerモデルを実行する

RK3588ホストに接続されたRK182x M.2アクセラレータ上で、RKNN3モデルを変換、クロスコンパイル、デプロイ、実行します。

RK182xアクセラレータ上でCNNおよびTransformerモデルを実行する

このガイドでは、Ubuntu x86_64 PCでモデル変換とアプリケーションのクロスコンパイルを行います。その後、SSH/SCPを使用してDebianを実行するRK3588ホストへアプリケーションをデプロイし、PCIe接続のRK182x M.2アクセラレータで推論を実行します。 各コンポーネントの関係は次のとおりです。

text
Ubuntu PC: ONNX → RKNN3-Toolkit → .rknn + .weight
                                      │ SCP
                                      ▼
RK3588: C++ Demo ────────────────→ RKNN3 Runtime
        Python / Toolkit Lite ──→ RKNN3 Runtime
                                      │ Communication service + PCIe driver
                                      ▼
                                RK182x M.2 accelerator

#1. RK182xドライバがない場合の対処

#1.1 問題のレイヤーを特定する

RK3588ホストで実行：

bash
uname -r
lspci -nnk
ls -l /dev/pcie-rkep-*

この例ではドライバをインストールする前からPCIeの列挙結果は次のように表示されていましたが、デバイスにKernel driver in useがなく、/dev/pcie-rkep-*も存在しませんでした。

text
0000:01:00.0 Processing accelerators [1200]:
Rockchip Electronics Co., Ltd Device [1d87:182a] (rev 01)

プロキシを実行した場合も次の出力になりました。

text
List of ntb devices attached
No pcie-rkep devices found

これは、ホストがPCIeエンドポイントを列挙できているものの、pcie-rkepドライバのインストールと読み込みが必要であることを示します。 rknn-smi: command not foundは、管理ユーティリティが未インストールか、PATHに含まれていないことを示します。

注意： PCIeエンドポイント自体が表示されない場合は、まず電源供給、M.2接続、ホストのPCIe設定を確認してください。以降の手順は、エンドポイントがすでに列挙されていることを前提とします。

#1.2 M.2パッケージをダウンロードしてインストールする

公式のRK1820/RK1828ビルド済みソフトウェアパッケージから次のパッケージをダウンロードします。

text
rknn3-rk182x-m2_1.1.0_arm64.deb

m2とarm64を選択してください。sodimmやsodimm-netで代用せず、パッケージ文書に記載されたRK3588 EVB10ボードイメージをreComputerへ書き込まないでください。

rknn3-rk182x-m2_1.1.0_arm64.debをデバイスのDownloadsディレクトリへアップロードします。

RK3588ホストで実行：

bash
sudo dpkg -i ~/Downloads/rknn3-rk182x-m2_1.1.0_arm64.deb

インストーラがDKMSを検出するとEngine: DKMSと表示され、実行中のカーネル向けにドライバをビルドおよびインストールし、起動時に読み込むよう設定されます。

このDEBパッケージには、PCIeドライバのソースとDKMS設定、M.2ファームウェア、Runtime共有ライブラリ、rknn3_transfer_proxy、rknn-smi、RKNN3起動サービスが含まれます。次のセクションでシステムRuntimeを再度上書きする必要はありません。

#1.3 ドライバを確認して再起動する

RK3588ホストで実行：

bash
sudo dkms status
sudo modinfo pcie-rkep
lspci -nnk -s 0000:01:00.0
ls -l /dev/pcie-rkep-*

想定される出力：

text
pcie-rkep/3.3.1, 6.1.115-vendor-seeed-rk3588, aarch64: installed

filename: /lib/modules/6.1.115-vendor-seeed-rk3588/updates/dkms/pcie-rkep.ko
vermagic: 6.1.115-vendor-seeed-rk3588 SMP mod_unload modversions aarch64

0000:01:00.0 Processing accelerators [1200]: Rockchip Electronics Co., Ltd Device [1d87:182a] (rev 01)
        Kernel driver in use: pcie-rkep

/dev/pcie-rkep-0000:01:00.0

一般ユーザーのPATHには/usr/sbinが含まれない場合があるため、このガイドではdkmsとmodinfoをsudoで実行します。一般ユーザーで実行したときに「command not found」と表示されるだけで、ソフトウェアが未インストールだと判断しないでください。

ドライバのインストールを確認したら、デバイスを再起動します。

bash
sudo reboot

#2. RuntimeとToolkit Liteのインストールおよび確認

#2.1 Runtime：M.2 DEBパッケージによるインストール

セクション1でインストールしたM.2パッケージには、このガイドに必要なRuntimeが含まれています。主要ファイルは次のとおりです。

ファイル用途
/usr/lib/librknn3_api.soRuntime APIのエントリポイント
/usr/lib/librknn3_api_rkcp.soコプロセッサモードのバックエンド
/usr/bin/rknn3_transfer_proxyRK3588とアクセラレータ間の通信プロキシ
/usr/lib/firmware/rknn3_rk1820.imgこのパッケージがインストールするアクセラレータファームウェア
/usr/bin/rknn-smi状態およびバージョン確認ユーティリティ
rknn3.service起動時のファームウェア読み込みとRuntimeサービス

ファームウェアパスのrk1820はパッケージで実際に使用される命名です。RK1828アクセラレータでも同じM.2パッケージを使用します。

RK3588ホストで実行：

bash
systemctl status rknn3.service --no-pager -l
sudo rknn3_transfer_proxy devices
sudo rknn-smi info
sudo rknn-smi -v

想定される出力：

text
Active: active (running)

List of ntb devices attached
0000:01:00.0        b98e6c51    PCIE

Device: 0     Status: Online     Health: OK
Chip: RK1828  Bus-Id: 0000:01:00.0
Memory-Usage(MB): 36 / 5120

rknn-smi version              : 1.3.0
PCIe driver version           : 3.3.1
RC chips connect version      : 3.3.2
EP chips connect version      : 0.0.2
PCIe Device 0 firmware version: 1.1.0
rknn3 API version             : 1.1.0

デバイス番号、温度、メモリ使用量は実行状態によって変わります。各コンポーネントは独立してバージョン管理されるため、バージョン番号が一致する必要はありません。これでC/C++ Runtimeを使用できます。

#2.2 Toolkit Liteインストールファイルを準備する

PCで公式リポジトリをクローンし、Toolkit LiteのインストールファイルだけをRK3588ホストへ転送します。同じリポジトリを次のセクションのPC Toolkitインストールでも使用します。

PCで実行：

bash
sudo apt update
sudo apt install git wget cmake make gcc g++ openssh-client
mkdir -p ~/RKNN3_Project
cd ~/RKNN3_Project

git clone https://github.com/airockchip/rknn3-toolkit.git
git -C rknn3-toolkit checkout 2136cc54fa79ad289c43e56ed9cf7e63ef56439b

git clone https://github.com/airockchip/rknn3-model-zoo.git
git -C rknn3-model-zoo checkout 174e44c77230735b1458946debb62b3982c1ee58

このガイドで検証したコミットに固定し、今後main上でファイル名やAPIが変わっても再現性に影響しないようにしています。新しい環境では一度だけクローンし、以降のセクションで両方のディレクトリを再利用します。

PCで実行：

bash
ssh rk3588@ip 'mkdir -p ~/RKNN3_Project/lite-packages'
cd ~/RKNN3_Project/rknn3-toolkit/rknn3-toolkit-lite/packages

scp requirements.txt \
  rknn3_toolkit_lite-1.1.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl \
  rk3588@ip:~/RKNN3_Project/lite-packages/

このガイドのRK3588ホストはDebian 12とPython 3.11を使用するため、cp311およびaarch64パッケージを選択します。

#2.3 Toolkit Liteをインストールする

RK3588ホストで実行：

bash
sudo apt update
sudo apt install python3.11-venv

python3 -m venv ~/venvs/rknn3-lite
source ~/venvs/rknn3-lite/bin/activate

cd ~/RKNN3_Project/lite-packages
python -m pip install -r requirements.txt
python -m pip install \
  ./rknn3_toolkit_lite-1.1.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

python -m pip check
python -c "from rknn3lite.api import RKNN3Lite; print('RKNN3 Toolkit Lite import OK')"

検証済み環境での出力：

text
No broken requirements found.
RKNN3 Toolkit Lite import OK

次に、Python APIからアクセラレータを照会します。

bash
sudo "$HOME/venvs/rknn3-lite/bin/python" - <<'PY'
from rknn3lite.api import RKNN3Lite
rknn = RKNN3Lite()
print(rknn.get_devices_id())
rknn.release()
PY

検証済み環境では次の値が返りました。

text
[b'0000:01:00.0']

このコマンドでは、仮想環境のPython実行ファイルを絶対パスで指定しています。sudo python3を実行すると通常はシステムPythonへ切り替わるため、仮想環境にインストールしたToolkit Liteを見つけられません。セクション4ではC++アプリケーションを実行するため、Toolkit Lite環境を有効にしておく必要はありません。

#3. Ubuntu PCでToolkitを設定してYOLOv6を変換する

#3.1 Python 3.10環境を作成する

PCで実行します。 Miniforgeを使用して分離環境を新規作成します。検証に使用したPCには~/miniconda3にCondaがすでにあり、そのtoolkit3環境で変換しました。

bash
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 toolkit3 python=3.10 -y
conda activate toolkit3

新しいターミナルを開いた後は、最初にsource ~/miniforge3/etc/profile.d/conda.shとconda activate toolkit3を実行します。すでにCondaを利用できる場合は、別のコピーをインストールせず既存のパスを使用してください。

#3.2 RKNN3-Toolkit 1.1.0をインストールする

PCで実行：

bash
cd ~/RKNN3_Project/rknn3-toolkit/rknn3-toolkit
python -m pip install -r packages/requirements_cp310-1.1.0.txt
python -m pip install \
  packages/rknn3_toolkit-1.1.0-cp310-cp310-manylinux2014_x86_64.whl

python --version
python -m pip show rknn3-toolkit
python -m pip check
python -c "from rknn.api import RKNN; print('RKNN3 Toolkit import OK')"

検証済み環境のバージョンと依存関係チェック出力：

text
Python 3.10.21
Name: rknn3-toolkit
Version: 1.1.0
Summary: Rockchip Neural Network Toolkit. (commit: cdbad21c1)
No broken requirements found.

この固定コミットでは、wheelはPDFの例にあるpackages/x86_64/ではなく、packages/直下にあります。この専用環境にToolkit2をインストールしないでください。このSDKのPC側インポート先もfrom rknn.api import RKNNであるため、旧ツールキットと混同しやすい点に注意してください。

#3.3 YOLOv6n ONNXモデルをダウンロードする

PCで実行：

bash
cd ~/RKNN3_Project/rknn3-model-zoo/examples/yolov6/model
bash download_model.sh
ls -lh yolov6n_rknn3.onnx

ダウンロードスクリプトは、RK182X向けに最適化されたyolov6n_rknn3.onnxを既定で取得します。検証時のファイルサイズは18,644,871バイトでした。

この最適化モデルは、YOLOデコード、候補ボックスのフィルタリング、並べ替え、NMSなどをモデルの計算グラフに組み込んでいます。このガイドではこのモデルだけを使用し、_rknn3サフィックスのない標準モデルとは混在させません。

#3.4 INT8変換を実行する

PCで実行：

bash
conda activate toolkit3
cd ~/RKNN3_Project/rknn3-model-zoo
export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"

# Quantization calibration list and image directory used by the official example
ls datasets/COCO/coco_subset_20.txt
ls datasets/COCO/subset

cd examples/yolov6/python
python convert.py ../model/yolov6n_rknn3.onnx rk1820 i8

パラメータの説明：

パラメータ説明
../model/yolov6n_rknn3.onnx入力ONNXモデル
rk1820公式RK182Xサンプルで使用する変換ターゲット。このガイドではRK1828で検証済み
i8量子化を有効化。メインスクリプトはw8a8を使用し、選択したサブグラフをw16a16に設定

スクリプトは入力の正規化、uint8/NHWC入力属性、core_num=1を設定します。最初の検証では既定設定を維持し、事前にONNXの入力レイアウトを変更しないでください。

検証済み変換ログの抜粋：

text
I version: rknn3-toolkit 1.1.0(cdbad21c1@2026-08-22T07:33:23)
...
I rknn building ...
...
I rknn building done.
...
--> Export rknn model
done

両方のモデルファイルが生成されたことを確認します。

bash
ls -lh ../model/yolov6n_rknn3.rknn ../model/yolov6n_rknn3.weight

検証時の.rknnファイルは約249 KB、.weightファイルは約5.1 MBでした。両方を一緒にデプロイする必要があります。

#4. アプリケーションのビルド、SCPによるデプロイ、実行

#4.1 PCにARM64クロスコンパイラをインストールする

PCで実行：

bash
cd ~/RKNN3_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/RKNN3_Project/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu"
"${GCC_COMPILER}-gcc" --version
cmake --version

検証に使用したコンパイラのバージョン：

text
aarch64-linux-gnu-gcc (Linaro GCC 6.3-2017.05) 6.3.1 20170404

GCC_COMPILERはコンパイラのプレフィックスで、末尾の-gccを含みません。ビルドスクリプトが付加します。Ubuntu 20.04付属のCMakeは、この例の最小要件であるCMake 3.15を満たします。

#4.2 YOLOv6 C++デモをビルドする

PCで実行：

bash
cd ~/RKNN3_Project/rknn3-model-zoo
./build-linux.sh -t rk3588 -a aarch64 -b Release -d yolov6

検証済みビルドログの抜粋：

text
[ 68%] Built target rknn_yolov6_demo
...
[100%] Built target cnpy
Install the project...
-- Install configuration: "Release"

デプロイディレクトリは次のとおりです。

text
install/rk3588_linux_aarch64/rknn_yolov6_demo/
├── rknn_yolov6_demo
├── dataset_eval
├── lib/
│   ├── librknn3_api.so
│   ├── librknn3_api_rkcp.so
│   ├── librga.so
│   └── libpostprocess_yolov6_rk182x.so
└── model/
    ├── yolov6n_rknn3.rknn
    ├── yolov6n_rknn3.weight
    ├── bus.jpg
    └── coco_80_labels_list.txt

ビルドスクリプトは変換済みモデルをデプロイディレクトリへコピーします。そのため、変換してからビルドおよびパッケージ化する順序が必要です。

#4.3 SCPでデプロイディレクトリ全体をコピーする

PCで実行：

bash
ssh rk3588@ip 'mkdir -p ~/RKNN3_Project'

cd ~/RKNN3_Project/rknn3-model-zoo
scp -r install/rk3588_linux_aarch64/rknn_yolov6_demo \
  rk3588@ip:~/RKNN3_Project/

実行ファイルや.rknnだけでなく、ディレクトリ全体をコピーしてください。このガイドでは、他のプロジェクトのファイルを上書きしないよう新しいデプロイディレクトリを使用します。

#4.4 RK3588ホストで実行する

RK3588ホストで実行：

bash
cd ~/RKNN3_Project/rknn_yolov6_demo

sudo env LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
  ./rknn_yolov6_demo \
  ./model/yolov6n_rknn3.rknn \
  ./model/yolov6n_rknn3.weight \
  ./model/bus.jpg \
  1

最後の1はcore_mask=0x01で、このモデルのcore_num=1に対応します。sudo env ...はデバイスノードへのアクセスを可能にすると同時に、デモのライブラリパスを明示的に渡します。ユーザーシェルでexport LD_LIBRARY_PATHした後にsudoを使用するだけでは、変数が削除される場合があります。

このコマンドはModel ZooのデプロイディレクトリにあるRuntime共有ライブラリを使用します。ホストのファームウェアと通信サービスは、セクション1でインストールしたM.2パッケージから引き続き提供されます。このバージョンの組み合わせで検証済みです。

実際の推論実行ログの抜粋：

text
model input num: 1, output num: 1
model is NHWC input fmt
model input height=640, width=640, channel=3
...
Pre-process time: 4.08 ms
Inference time: 18.10 ms
Post-process time: 0.06 ms
Total time: 22.23 ms
--> inference model done
bus @ (97 138 553 438) 0.947
person @ (109 237 223 535) 0.936
person @ (211 240 285 511) 0.928
person @ (478 232 560 522) 0.920
person @ (79 326 118 514) 0.450
write_image path: out.png width=640 height=640 channel=3 ...

これらは1回の実行で測定した値であり、継続的なFPSや性能ベンチマークではありません。アプリケーションが正常終了し、妥当な検出結果を表示してout.pngを生成すれば成功です。

#4.5 結果画像を取得する

PCで実行：

bash
mkdir -p ~/RKNN3_Project/results
scp rk3588@ip:~/RKNN3_Project/rknn_yolov6_demo/out.png \
  ~/RKNN3_Project/results/yolov6-out.png

Ubuntuデスクトップで結果を直接開けます。RK3588ホストにディスプレイが接続されている場合は、コピーせずホスト側で表示できます。

検証時に生成された画像を以下に示します。

RK3588とRK1828によるYOLOv6検出結果

#5. 初回実行のトラブルシューティング

症状このガイドでの対処
rknn-smi: command not foundセクション1のM.2 DEBパッケージをインストールし、プロキシアプリケーションだけをコピーしない
PCIeには1d87:182aが表示されるが、ドライバやデバイスノードがないヘッダーが実行中のカーネルと一致することを確認し、DKMSのビルド結果を調べる
dpkgは完了するが、DKMSがinstalledを報告しない/var/lib/dkms/pcie-rkep/3.3.1/build/make.logを確認し、ドライバエラーを無視しない
No pcie-rkep devices foundまずドライバのバインドとデバイスノードを確認し、次にrknn3.serviceを確認する
ensurepip is not availablepython3.11-venvをインストールし、Toolkit Lite仮想環境を作り直す
wheelがサポートされないPCではcp310/x86_64、このガイドのRK3588ホストではcp311/aarch64を選択する
No module named py_utilsModel ZooルートでPYTHONPATHを設定してからサンプルディレクトリへ移動する
キャリブレーションデータセットのパスが存在しないexamples/yolov6/pythonから変換を実行し、リポジトリのdatasets/COCOディレクトリを確認する
sudo実行後にPythonがToolkit Liteを見つけられない仮想環境のPython実行ファイルを絶対パスで指定する
モデルまたは共有ライブラリが見つからない完全なデプロイディレクトリをコピーし、その中からデモを実行して、sudo envでライブラリパスを設定する

RK3588ホストで診断情報を収集します。

bash
sudo dkms status
sudo modinfo pcie-rkep
lspci -nnk -s 0000:01:00.0
ls -l /dev/pcie-rkep-*
systemctl status rknn3.service --no-pager -l
sudo journalctl -u rknn3.service -b --no-pager -n 100
sudo dmesg | grep -Ei 'pcie|rkep|rknn|firmware' | tail -n 100

#6. バージョンと参考資料

この検証済み環境では、リポジトリを次のコミットに固定しています。

text
rknn3-toolkit   2136cc54fa79ad289c43e56ed9cf7e63ef56439b
rknn3-model-zoo 174e44c77230735b1458946debb62b3982c1ee58

このガイドでは、作業ディレクトリとして一貫して~/RKNN3_Projectを使用します。