Exécuter des modèles CNN et Transformer sur un accélérateur RK182x

Ce guide utilise un PC Ubuntu x86_64 pour convertir les modèles et compiler les applications de façon croisée. Il déploie ensuite l’application via SSH/SCP sur un hôte RK3588 sous Debian, où un accélérateur RK182x M.2 relié par PCIe effectue l’inférence. Les composants fonctionnent ensemble comme suit :

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. Résoudre l’absence du pilote RK182x

#1.1 Identifier la couche en cause

À exécuter sur l’hôte RK3588 :

bash

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

Avant l’installation du pilote dans cet exemple, l’énumération PCIe produisait déjà le résultat suivant. Cependant, le périphérique ne comportait aucune entrée Kernel driver in use et /dev/pcie-rkep-* n’existait pas :

text

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

L’exécution du proxy produisait également :

text

List of ntb devices attached
No pcie-rkep devices found

Cela signifie que l’hôte a énuméré le point de terminaison PCIe, mais que le pilote pcie-rkep doit encore être installé et chargé. rknn-smi: command not found signifie que l’utilitaire de gestion n’est pas installé ou ne figure pas dans le PATH.

Remarque : Si le point de terminaison PCIe lui-même est absent, vérifiez d’abord l’alimentation, la connexion M.2 et la configuration PCIe de l’hôte. Les étapes suivantes supposent que le point de terminaison est déjà énuméré.

#1.2 Télécharger et installer le paquet M.2

Téléchargez le paquet suivant depuis le paquet logiciel précompilé RK1820/RK1828 officiel :

text

rknn3-rk182x-m2_1.1.0_arm64.deb

Sélectionnez m2 et arm64. Ne les remplacez pas par sodimm ou sodimm-net, et ne flashez pas sur le reComputer l’image de carte RK3588 EVB10 mentionnée dans la documentation du paquet.

Téléversez rknn3-rk182x-m2_1.1.0_arm64.deb dans le répertoire Downloads de l’appareil.

À exécuter sur l’hôte RK3588 :

bash

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

Lorsque le programme d’installation détecte DKMS, il doit afficher Engine: DKMS, compiler et installer le pilote pour le noyau en cours d’exécution, puis configurer son chargement au démarrage.

Ce paquet DEB contient le code source du pilote PCIe et sa configuration DKMS, le firmware M.2, les bibliothèques partagées du Runtime, rknn3_transfer_proxy, rknn-smi et le service de démarrage RKNN3. Il n’est pas nécessaire d’écraser de nouveau le Runtime système dans la section suivante.

#1.3 Vérifier le pilote et redémarrer

À exécuter sur l’hôte RK3588 :

bash

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

Sortie attendue :

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

Le PATH d’un utilisateur standard peut ne pas inclure /usr/sbin. Ce guide exécute donc dkms et modinfo avec sudo. Ne concluez pas que le logiciel est absent uniquement parce que l’une de ces commandes renvoie « command not found » sous un utilisateur standard.

Après avoir confirmé l’installation du pilote, redémarrez l’appareil :

bash

sudo reboot

#2. Installer et vérifier le Runtime et Toolkit Lite

#2.1 Runtime : installé par le paquet DEB M.2

Le paquet M.2 installé à la section 1 fournit déjà le Runtime requis par ce guide. Les principaux fichiers sont :

Fichier	Rôle
`/usr/lib/librknn3_api.so`	Point d’entrée de l’API Runtime
`/usr/lib/librknn3_api_rkcp.so`	Backend en mode coprocesseur
`/usr/bin/rknn3_transfer_proxy`	Proxy de communication entre le RK3588 et l’accélérateur
`/usr/lib/firmware/rknn3_rk1820.img`	Firmware de l’accélérateur installé par ce paquet
`/usr/bin/rknn-smi`	Utilitaire d’interrogation de l’état et de la version
`rknn3.service`	Chargement du firmware et service Runtime au démarrage

Le composant rk1820 du chemin du firmware correspond à la convention de nommage réelle du paquet. Utilisez le même paquet M.2 avec un accélérateur RK1828.

À exécuter sur l’hôte RK3588 :

bash

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

Sortie attendue :

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

Les indices de périphérique, les températures et l’utilisation de la mémoire varient selon l’état d’exécution. Chaque composant possède sa propre version ; les numéros n’ont donc pas besoin d’être identiques. Le Runtime C/C++ est maintenant prêt.

#2.2 Préparer les fichiers d’installation de Toolkit Lite

Clonez les dépôts officiels sur le PC, puis transférez uniquement les fichiers d’installation de Toolkit Lite vers l’hôte RK3588. Les mêmes dépôts serviront à installer le Toolkit PC dans la section suivante.

À exécuter sur le 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

Les dépôts sont épinglés aux commits vérifiés pour ce guide afin que les changements ultérieurs de noms de fichiers ou d’API sur main n’affectent pas la reproductibilité. Ne les clonez qu’une fois dans un nouvel environnement ; les sections suivantes réutilisent les deux répertoires.

À exécuter sur le 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/

L’hôte RK3588 de ce guide exécute Debian 12 avec Python 3.11 ; sélectionnez donc le paquet cp311 et aarch64.

#2.3 Installer Toolkit Lite

À exécuter sur l’hôte 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')"

Sortie de l’environnement vérifié :

text

No broken requirements found.
RKNN3 Toolkit Lite import OK

Interrogez ensuite l’accélérateur via l’API Python :

bash

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

L’environnement vérifié a renvoyé :

text

[b'0000:01:00.0']

La commande utilise volontairement le chemin absolu de l’exécutable Python de l’environnement virtuel. sudo python3 bascule généralement vers le Python système, qui ne trouve pas le paquet Toolkit Lite installé dans l’environnement virtuel. La section 4 exécute une application C++ et ne dépend pas de l’activation de l’environnement Toolkit Lite.

#3. Configurer le Toolkit et convertir YOLOv6 sur un PC Ubuntu

#3.1 Créer un environnement Python 3.10

À exécuter sur le PC. Utilisez Miniforge pour créer un environnement isolé. Le PC de vérification disposait déjà de Conda dans ~/miniconda3, et la conversion a été réalisée dans son environnement 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

Après l’ouverture d’un nouveau terminal, exécutez d’abord source ~/miniforge3/etc/profile.d/conda.sh et conda activate toolkit3. Si Conda est déjà disponible, utilisez son chemin existant au lieu d’en installer une autre copie.

#3.2 Installer RKNN3-Toolkit 1.1.0

À exécuter sur le 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')"

Versions et résultat de la vérification des dépendances dans l’environnement testé :

text

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

Dans ce commit épinglé, le wheel se trouve directement sous packages/, et non sous packages/x86_64/ comme dans l’exemple PDF. N’installez pas Toolkit2 dans cet environnement dédié. Ce SDK utilise toujours from rknn.api import RKNN comme point d’importation sur PC, ce qui peut facilement le faire confondre avec l’ancien toolkit.

#3.3 Télécharger le modèle ONNX YOLOv6n

À exécuter sur le PC :

bash

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

Par défaut, le script télécharge yolov6n_rknn3.onnx, optimisé pour RK182X. Le fichier vérifié faisait 18,644,871 octets.

Ce modèle optimisé intègre le décodage YOLO, le filtrage et le tri des boîtes candidates, la NMS et d’autres traitements dans le graphe de calcul. Ce guide utilise uniquement ce modèle et ne le mélange pas avec le modèle standard dépourvu du suffixe _rknn3.

#3.4 Effectuer la conversion INT8

À exécuter sur le 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

Description des paramètres :

Paramètre	Description
`../model/yolov6n_rknn3.onnx`	Modèle ONNX d’entrée
`rk1820`	Cible de conversion utilisée par l’exemple RK182X officiel ; vérifiée avec un RK1828 dans ce guide
`i8`	Active la quantification ; le script principal utilise `w8a8` et configure certains sous-graphes en `w16a16`

Le script configure la normalisation d’entrée, les propriétés d’entrée uint8/NHWC et core_num=1. Conservez la configuration par défaut lors de la première vérification ; ne modifiez pas au préalable la disposition d’entrée ONNX.

Extrait du journal de conversion vérifié :

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

Vérifiez que les deux fichiers de modèle ont été générés :

bash

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

Lors de la conversion vérifiée, le fichier .rknn faisait environ 249 Ko et le fichier .weight environ 5,1 Mo. Les deux fichiers doivent être déployés ensemble.

#4. Compiler, déployer avec SCP et exécuter l’application

#4.1 Installer un compilateur croisé ARM64 sur le PC

À exécuter sur le 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

Version du compilateur utilisée pour la vérification :

text

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

GCC_COMPILER est le préfixe du compilateur et n’inclut pas le -gcc final ; le script de compilation l’ajoute. La version de CMake fournie avec Ubuntu 20.04 satisfait l’exigence minimale CMake 3.15 de cet exemple.

#4.2 Compiler la démo C++ YOLOv6

À exécuter sur le PC :

bash

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

Extrait du journal de compilation vérifié :

text

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

Le répertoire de déploiement est :

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

Le script de compilation copie le modèle converti dans le répertoire de déploiement. L’ordre requis est donc : conversion, puis compilation et empaquetage.

#4.3 Copier tout le répertoire de déploiement avec SCP

À exécuter sur le 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/

Copiez l’intégralité du répertoire, et pas seulement l’exécutable ou le fichier .rknn. Ce guide utilise un nouveau répertoire de déploiement afin de ne pas écraser les fichiers d’autres projets.

#4.4 Exécuter sur l’hôte RK3588

À exécuter sur l’hôte 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

Le dernier 1 correspond à core_mask=0x01 et au core_num=1 de ce modèle. sudo env ... donne accès au nœud de périphérique tout en transmettant explicitement le chemin des bibliothèques de la démo. Si vous exécutez seulement export LD_LIBRARY_PATH dans le shell utilisateur avant sudo, la variable peut être supprimée.

Cette commande utilise les bibliothèques partagées du Runtime dans le répertoire de déploiement de Model Zoo. Le firmware de l’hôte et le service de communication restent fournis par le paquet M.2 installé à la section 1. Cette combinaison exacte de versions a été vérifiée ensemble.

Extrait d’une exécution d’inférence réelle :

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 ...

Ces valeurs proviennent d’une seule exécution et ne représentent ni un débit d’images soutenu ni une référence de performance. La réussite signifie que l’application se termine normalement, affiche des détections plausibles et crée out.png.

#4.5 Récupérer l’image de résultat

À exécuter sur le PC :

bash

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

Ouvrez directement le résultat sur le bureau Ubuntu. Si un écran est relié à l’hôte RK3588, vous pouvez y afficher l’image sans la recopier.

L’image suivante a été générée lors de la vérification :

Résultat de détection YOLOv6 sur RK3588 avec RK1828

#5. Dépannage de la première exécution

Symptôme	Résolution dans ce guide
`rknn-smi: command not found`	Installez le paquet DEB M.2 de la section 1 ; ne copiez pas seulement l’application proxy
PCIe affiche `1d87:182a`, mais aucun pilote ni nœud de périphérique n’est présent	Vérifiez que les en-têtes correspondent au noyau actif, puis examinez le résultat de compilation DKMS
`dpkg` se termine, mais DKMS n’indique pas `installed`	Examinez `/var/lib/dkms/pcie-rkep/3.3.1/build/make.log` ; n’ignorez pas les erreurs du pilote
`No pcie-rkep devices found`	Vérifiez d’abord la liaison du pilote et le nœud de périphérique, puis `rknn3.service`
`ensurepip is not available`	Installez `python3.11-venv`, puis recréez l’environnement virtuel Toolkit Lite
Le wheel n’est pas pris en charge	Sélectionnez `cp310/x86_64` sur le PC et `cp311/aarch64` sur l’hôte RK3588 de ce guide
`No module named py_utils`	Définissez `PYTHONPATH` à la racine de Model Zoo, puis entrez dans le répertoire de l’exemple
Le chemin du jeu de calibration n’existe pas	Lancez la conversion depuis `examples/yolov6/python` et vérifiez le répertoire `datasets/COCO` du dépôt
Python ne trouve pas Toolkit Lite après `sudo`	Utilisez le chemin absolu de l’exécutable Python de l’environnement virtuel
Le modèle ou la bibliothèque partagée est introuvable	Copiez le répertoire de déploiement complet, exécutez la démo depuis ce répertoire et définissez le chemin des bibliothèques avec `sudo env`

Collectez les informations de diagnostic sur l’hôte 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. Versions et références

Les dépôts sont épinglés aux commits suivants pour cette configuration vérifiée :

text

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

Le guide utilise systématiquement ~/RKNN3_Project comme répertoire de travail.

Dépôt officiel RKNN3 : relations entre les composants logiciels et paquets d’installation.
Toolkit Lite à la version épinglée : wheel ARM64, dépendances et exemples Python.
Runtime à la version épinglée : bibliothèques Runtime et composants de communication.
Exemple YOLOv6 à la version épinglée : téléchargement, conversion et code source de l’exemple C++.
Extensions Armbian et dépôt de paquets Seeed : dépôt de paquets du fabricant pour la carte utilisée dans cet exemple ; les en-têtes du noyau doivent correspondre au noyau du système en cours d’exécution.