Démarrage rapide : exécuter des modèles CNN sur RK3588

Avec YOLO11n, ce guide couvre vérification du pilote NPU → installation de Runtime et Toolkit Lite2 → conversion sur PC → compilation et déploiement C++ → inférence sur la carte. Le modèle tourne sur le NPU intégré au RK3588 via SSH/SCP ou le terminal local.

#Avant de commencer

Lieu d’exécution : « Sur PC » désigne l’ordinateur Ubuntu ; « Sur la carte », SSH ou son terminal local. Remplacez BOARD_IP et l’utilisateur d’exemple rk3588 par l’adresse et le compte réels.

Si SSH n’est pas encore activé sur la carte, exécutez d’abord ceci sur son terminal local :

sudo apt update
sudo apt install openssh-server
sudo systemctl enable --now ssh
hostname -I

Connectez-vous ensuite depuis le PC. À la première connexion, vérifiez l’empreinte de l’hôte et saisissez le mot de passe demandé :

ssh rk3588@BOARD_IP

#1. Résoudre l’absence de pilote NPU

#1.1 Pilote du noyau et logiciel en espace utilisateur

Le pilote NPU du RK3588 est RKNPU dans le noyau, configuré par CONFIG_ROCKCHIP_RKNPU. Ni le .so de Runtime ni la roue Python de Toolkit Lite2 ne remplacent le pilote du noyau.

#1.2 Vérifier le pilote, le nœud de périphérique et la charge

Sur la carte :

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

Extrait de la sortie réellement obtenue :

RKNPU driver: v0.9.8
NPU load:  Core0:  0%, Core1:  0%, Core2:  0%,

/sys/class/drm/renderD130/device/driver -> .../bus/platform/drivers/RKNPU

Le nœud NPU était ici renderD130 ; son numéro peut changer. Repérez-le grâce à device/driver pointant vers RKNPU.

Si debugfs n’est pas monté, exécutez d’abord :

mountpoint -q /sys/kernel/debug || sudo mount -t debugfs debugfs /sys/kernel/debug

Réessayez après montage et évaluez aussi les journaux de démarrage et la liaison du pilote.

Vérifiez la configuration du noyau sur la carte :

grep '^CONFIG_ROCKCHIP_RKNPU=' /boot/config-$(uname -r)

Sortie réelle :

CONFIG_ROCKCHIP_RKNPU=y

=y indique une intégration au noyau : l’absence de rknpu dans lsmod ne signifie donc pas que le pilote manque. Le guide de démarrage officiel de RKNN SDK V2.3.2 recommande RKNPU 0.9.2 ou plus récent ; l’inférence a ici été vérifiée avec 0.9.8.

#1.3 Si le pilote manque ou doit être mis à jour

Ce guide utilise le noyau Seeed/Armbian pour reComputer RK3588. Si les contrôles passent, allez directement à la section 2 sans réinstaller le noyau.

Sur le même modèle de carte, avec le dépôt Seeed configuré, inspectez d’abord les paquets du noyau et de l’arbre de périphériques :

sudo apt update
apt-cache policy linux-image-vendor-seeed-rk3588 linux-dtb-vendor-seeed-rk3588

Après avoir confirmé que les deux paquets viennent du dépôt adapté à la carte et que leurs versions candidates correspondent, installez ou mettez à jour le noyau et l’arbre de périphériques correspondants :

sudo apt install --reinstall linux-image-vendor-seeed-rk3588 linux-dtb-vendor-seeed-rk3588
sudo reboot

Le redémarrage coupe SSH ; après reconnexion, vérifiez le pilote selon la section 1.2.

Si les paquets manquent, utilisez l’image du fabricant ou le BSP pour ce modèle de carte. Pour un noyau personnalisé, activez CONFIG_ROCKCHIP_RKNPU=y et utilisez la configuration de l’arbre de périphériques NPU propre à cette carte.

#2. Installer et vérifier Runtime et Toolkit Lite2

#2.1 Rôle des trois composants

Le PC utilise from rknn.api import RKNN ; le Python de la carte utilise from rknnlite.api import RKNNLite. Lite2 ne convertit pas les modèles ; l’exemple C++ appelle directement Runtime.

Ce guide exécute l’inférence sur la carte ; rknn_server n’est pas nécessaire.

#2.2 Récupérer des révisions fixes des dépôts officiels sur le PC

Les sections 3 et 4 réutilisent ces deux répertoires ; clonez-les une seule fois dans un nouveau répertoire de travail.

Sur 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

Ce sont les commits utilisés dans ce test ; Model Zoo correspond à v2.3.2. Fixez code et paquets pour éviter que de futures mises à jour ne modifient les chemins des commandes.

#2.3 Installer Runtime sur la carte

Sur PC :

ssh rk3588@BOARD_IP 'mkdir -p ~/RKNN2_Project/packages'

scp ~/RKNN2_Project/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/aarch64/librknnrt.so \
  rk3588@BOARD_IP:~/RKNN2_Project/packages/

Sur la carte : sauvegardez l’éventuelle ancienne bibliothèque avant d’installer la nouvelle.

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'

La chaîne de version de ce paquet est :

librknnrt version: 2.3.2 (429f97ae6b@2025-04-09T09:09:27)

Lite2 nécessite /usr/lib/librknnrt.so ; définir LD_LIBRARY_PATH seulement pour le répertoire Demo ne remplace pas cette étape.

#2.4 Installer Toolkit Lite2 sur la carte

La carte utilise Debian 12 avec Python 3.11 ; choisissez donc la roue cp311 pour aarch64.

Sur 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 \
  rk3588@BOARD_IP:~/RKNN2_Project/packages/

Sur la carte :

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')"

Résultats réels des deux vérifications :

No broken requirements found.
RKNN Toolkit Lite2 import OK

Si ensurepip is not available apparaît, installez python3.11-venv et recréez l’environnement virtuel. La section 4 vérifie l’inférence réelle.

#3. Configurer Toolkit sur PC Ubuntu et convertir YOLO11n

#3.1 Créer un environnement Python 3.11 sur le PC

Sur PC : ces commandes installent Miniforge sur un nouveau PC. Si Conda est déjà présent, utilisez-le pour créer l’environnement du même nom.

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 rknn2

Dans chaque nouveau terminal du PC, exécutez source ~/miniforge3/etc/profile.d/conda.sh et conda activate rknn2 avant les commandes Python suivantes.

#3.2 Installer Toolkit2 2.3.2

Sur 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')"

La configuration testée utilisait Python 3.11.14, Toolkit2 2.3.2, ONNX 1.16.1 et protobuf 4.25.4 ; pip check a renvoyé No broken requirements found.. Fixez ces versions dans un environnement isolé pour éviter les conflits.

#3.3 Télécharger YOLO11n adapté officiellement

Sur PC :

cd ~/RKNN2_Project/rknn_model_zoo/examples/yolo11/model
bash download_model.sh
ls -lh yolo11n.onnx

Le fichier yolo11n.onnx téléchargé avait une taille de 10,527,859 octets.

Utilisez l’ONNX adapté à Rockchip dont la disposition de sortie correspond au post-traitement C++ de l’exemple. Exportez vos modèles entraînés selon les instructions d’exportation YOLO11.

#3.4 Convertir en modèle INT8 pour RK3588

Sur 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 rk3588 i8 ../model/yolo11n_rk3588.rknn
ls -lh ../model/yolo11n_rk3588.rknn

Les quatre arguments sont le chemin ONNX, la plateforme cible, le type de quantification et le chemin de sortie. Cette page doit utiliser rk3588.

Exécutez depuis examples/yolo11/python pour que le script trouve datasets/COCO/coco_subset_20.txt. Ce jeu sert à vérifier l’exemple ; étalonnez les modèles de production avec des données représentatives des situations réelles.

Extrait de la sortie de conversion réelle :

I rknn-toolkit2 version: 2.3.2
...
--> Building model
...
I rknn building ...
I rknn building done.
done
--> Export rknn model
done

Une conversion réussie crée le fichier .rknn. L’avis sur le passage des types d’entrée/sortie à int8 est un rappel de quantification ; utilisez l’exemple C++ correspondant pour les traiter.

#4. Compiler, déployer par SCP et exécuter

#4.1 Préparer le compilateur croisé ARM64

Sur 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

Le compilateur testé était Linaro GCC 6.3.1 20170404. GCC_COMPILER est un préfixe sans le -gcc final, ajouté par le script de compilation.

#4.2 Compiler l’exemple YOLO11 C++ pour RK3588

Sur PC :

cd ~/RKNN2_Project/rknn_model_zoo
bash build-linux.sh -t rk3588 -a aarch64 -b Release -d yolo11

Convertissez le modèle avant la compilation pour que le script copie .rknn dans le répertoire de déploiement.

Voici la structure du répertoire de déploiement ; les autres exemples fournis peuvent rester :

install/rk3588_linux_aarch64/rknn_yolo11_demo/
├── rknn_yolo11_demo
├── lib/
│   ├── librknnrt.so
│   └── librga.so
└── model/
    ├── yolo11n_rk3588.rknn
    ├── bus.jpg
    └── coco_80_labels_list.txt

#4.3 Déployer tout le répertoire par SCP

Sur PC :

ssh rk3588@BOARD_IP 'mkdir -p ~/RKNN2_Project'
cd ~/RKNN2_Project/rknn_model_zoo
scp -r install/rk3588_linux_aarch64/rknn_yolo11_demo \
  rk3588@BOARD_IP:~/RKNN2_Project/

Copiez tout le répertoire, dont lib/ et model/ ; Runtime fourni est en version 2.3.2.

#4.4 Exécuter la détection d’objets sur la carte

Sur la carte :

cd ~/RKNN2_Project/rknn_yolo11_demo
sudo env LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
  ./rknn_yolo11_demo model/yolo11n_rk3588.rknn model/bus.jpg

Extrait de la sortie réelle sur RK3588 :

model input num: 1, output num: 9
model is NHWC input fmt
model input height=640, width=640, channel=3
...
rknn_run
bus @ (91 135 552 435) 0.948
person @ (109 236 223 536) 0.898
person @ (212 240 285 509) 0.843
person @ (477 230 559 521) 0.827
person @ (79 359 116 515) 0.448
write_image path: out.png width=640 height=640 channel=3 ...

La détection est terminée lorsque le processus sort normalement et crée out.png ; les coordonnées et la confiance peuvent varier avec la version et la quantification.

Sur PC, récupérer l’image :

mkdir -p ~/RKNN2_Project/results
scp rk3588@BOARD_IP:~/RKNN2_Project/rknn_yolo11_demo/out.png \
  ~/RKNN2_Project/results/yolo11n-rk3588-out.png

Ouvrez l’image sur le PC pour voir les cadres, ou ouvrez directement out.png dans l’interface graphique de la carte.

#4.5 Vérifier que Lite2 exécute le même modèle

Utilisez le même modèle et une entrée entièrement nulle pour tester l’inférence Lite2 ; cette étape ne réalise pas le post-traitement de détection d’image.

Sur la carte :

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

Résultat réel :

Lite2 inference OK; output count: 9

Utilisez le chemin absolu du Python de l’environnement virtuel pour éviter que sudo python3 n’appelle celui du système sans Lite2.

#4.6 Problèmes courants et critères de validation

À la fin, le pilote NPU doit être interrogeable, Runtime/Lite2 utilisables, la conversion sur PC réussie, le programme C++ capable de créer l’image de détection et Lite2 capable de renvoyer neuf tenseurs de sortie.

#4.7 Références

• Dépôt officiel RKNN-Toolkit2 : Toolkit, Runtime, Lite2 et documentation.
• Guide de démarrage RKNN SDK V2.3.2 : ce guide utilise SSH/SCP pour la connexion et le transfert.
• Exemple YOLO11 vérifié ici : téléchargement ONNX, script de conversion et post-traitement C++.
• Extension Armbian et dépôt Seeed : source des paquets de noyau et d’arbre de périphériques pour reComputer.