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

Ce guide suit les étapes vérification du pilote NPU → installation de Runtime et Toolkit Lite2 → conversion sur PC → compilation et déploiement C++ → inférence sur la carte. Il utilise YOLO11n de RKNN Model Zoo sur le NPU intégré au RK3576, via SSH/SCP ou le terminal local de la carte.

#Avant de commencer

Lieu d’exécution : « Sur PC » désigne l’ordinateur Ubuntu de développement ; « Sur la carte », une session SSH ou son terminal local. BOARD_IP est un paramètre fictif : remplacez-le par l’adresse IP locale de votre carte.

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 rk3576@BOARD_IP

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

#1.1 Pilote du noyau et logiciel en espace utilisateur

Le pilote NPU du RK3576 est RKNPU dans le noyau, configuré par CONFIG_ROCKCHIP_RKNPU. Ni le fichier .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%,

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

renderD129 était le nœud NPU détecté lors de ce test, pas un numéro fixe. Repérez-le grâce au lien device/driver vers RKNPU. D’autres nœuds render peuvent appartenir à l’affichage ou au GPU ; la seule présence de /dev/dri ne prouve pas que le NPU fonctionne.

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 ensuite de consulter la version. L’absence du seul fichier de requête debugfs ne prouve pas l’absence du pilote ; vérifiez 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 RK3576. 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-rk3576 linux-dtb-vendor-seeed-rk3576

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-rk3576 linux-dtb-vendor-seeed-rk3576
sudo reboot

Cette maintenance change le noyau de démarrage et interrompt SSH. Après reconnexion, reprenez la section 1.2 ; le succès de la commande d’installation ne prouve pas que le pilote fonctionne.

Si ces paquets manquent, obtenez l’image du fabricant ou le BSP pour ce modèle précis de carte. N’installez pas le noyau d’une autre carte, ne copiez pas rknpu.ko au hasard et n’utilisez pas les paquets DKMS de RK182x. Pour un BSP personnalisé, activez CONFIG_ROCKCHIP_RKNPU=y dans le noyau adapté, conservez le bon arbre de périphériques NPU et suivez les étapes de compilation et de déploiement de ce BSP. Ces étapes dépendent de la carte et ne peuvent pas être remplacées par pip install de Toolkit.

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

#2.1 Rôle des trois composants

Sur le PC, importez from rknn.api import RKNN ; sur la carte, Lite2 s’importe avec from rknnlite.api import RKNNLite. Lite2 exécute l’inférence mais ne convertit pas ONNX en RKNN ; l’exemple C++ ne dépend pas de Lite2.

Ce guide transfère les fichiers par SCP et les exécute sur la carte. Il n’utilise pas l’inférence USB depuis le PC : 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 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/

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 exige cette étape. La version testée cherche /usr/lib/librknnrt.so ; définir LD_LIBRARY_PATH seulement pour le répertoire Demo ne remplace pas la vérification de la bibliothèque système. Sur RK3588, son absence a produit Can not find dynamic library on RK3588! ; l’installation du fichier a résolu l’erreur.

#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 \
  rk3576@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

Ne copiez pas sur la carte la roue x86_64 du PC. Si ensurepip is not available apparaît, installez python3.11-venv, puis recréez l’environnement virtuel. Un import réussi ne vérifie que le paquet Python ; la section 4 teste l’inférence NPU 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')"

L’environnement de conversion testé utilisait Python 3.11.14 et Toolkit2 2.3.2 ; après correction des dépendances, pip check a renvoyé No broken requirements found..

Fixer explicitement ONNX et protobuf évite les dépendances héritées d’anciens projets : la conversion utilise ONNX 1.16.1 et protobuf 4.25.4 dans un environnement isolé, sans modifier l’environnement Conda initial.

#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 cet ONNX adapté à Rockchip. Sa disposition de sortie correspond au post-traitement C++ officiel ; ne le remplacez pas par une exportation Ultralytics quelconque. Pour un modèle entraîné par vous, suivez les instructions officielles d’exportation YOLO11.

#3.4 Convertir en modèle INT8 pour RK3576

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 rk3576 i8 ../model/yolo11n_rk3576.rknn
ls -lh ../model/yolo11n_rk3576.rknn

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

Le script utilise datasets/COCO/coco_subset_20.txt du dépôt pour l’étalonnage. Exécutez-le depuis examples/yolo11/python afin que les chemins relatifs fonctionnent. Ce petit jeu de données sert au premier test ; étalonnez et évaluez un modèle 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

La première ligne du journal peut contenir des informations internes de compilation ; vérifiez surtout la création du fichier cible. L’avis indiquant que les types d’entrée/sortie par défaut deviennent int8 est normal pour cette quantification. Laissez l’exemple C++ correspondant gérer les entrées/sorties ; ne convertissez pas arbitrairement l’image en valeurs signées.

Cet exemple RKNN2 n’exige qu’un seul fichier de modèle .rknn sur la carte.

#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 RK3576

Sur PC :

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

Utilisez bash build-linux.sh pour éviter Permission denied si le script du dépôt n’est pas exécutable. Convertissez le modèle avant la compilation afin que le script ajoute le .rknn généré au répertoire de déploiement.

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

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

Si vous convertissez pour les deux plateformes dans le même dépôt, le répertoire d’installation peut contenir deux fichiers .rknn. Sélectionnez explicitement celui portant le suffixe rk3576 à l’exécution.

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

Sur 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/

Copiez lib/ et model/, pas seulement l’exécutable. Runtime est inclus dans lib/ ; la version testée était 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_rk3576.rknn model/bus.jpg

Extrait de la sortie réelle sur RK3576 :

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

Le test réussit si le processus se termine normalement, affiche les détections de bus et de personnes, et crée out.png dans le répertoire courant. Coordonnées et scores peuvent varier selon les versions et la quantification. Aucun FPS stable n’a été mesuré ; ce test fonctionnel n’est pas un banc d’essai de performance.

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

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

Ouvrez l’image sur le PC pour voir les cadres de détection. Si un écran est connecté à la carte, vous pouvez également l’ouvrir dans son interface graphique.

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

Après la détection C++, utilisez le même modèle pour tester la chaîne d’inférence Python.

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

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.