Schnellstart: CNN-Modelle auf RK3588 ausführen

Mit YOLO11n werden NPU-Treiber prüfen → Runtime und Toolkit Lite2 installieren → Modell auf dem PC konvertieren → C++-Programm erstellen und bereitstellen → Inferenz auf dem Board durchgeführt. Das Modell läuft auf der integrierten NPU des RK3588 per SSH/SCP oder lokalem Board-Terminal.

#Vorbereitungen

Ausführungsort: „Auf dem PC“ ist der Ubuntu-Rechner, „Auf dem Board“ eine SSH-Sitzung oder das lokale Terminal. BOARD_IP und Beispielbenutzer rk3588 durch tatsächliche Adresse und Konto ersetzen.

Falls SSH auf dem Board noch nicht aktiviert ist, zuerst lokal auf dem Board ausführen:

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

Dann vom PC aus verbinden. Bei der ersten Verbindung den Host-Fingerabdruck prüfen und das Kontopasswort eingeben:

ssh rk3588@BOARD_IP

#1. Fehlenden NPU-Treiber beheben

#1.1 Kernel-Treiber und Userspace-Software unterscheiden

Der NPU-Treiber des RK3588 ist RKNPU im Kernel, konfiguriert durch CONFIG_ROCKCHIP_RKNPU. Weder Runtime-.so noch das Python-Wheel von Toolkit Lite2 ersetzen den Kernel-Treiber.

#1.2 Treiber, Geräteknoten und Last prüfen

Auf dem Board:

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

Auszug aus der tatsächlich ermittelten Ausgabe:

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

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

Der NPU-Knoten war hier renderD130; die Nummer kann wechseln. Am Link device/driver auf RKNPU erkennen.

Wenn debugfs noch nicht eingehängt ist, zuerst ausführen:

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

Nach dem Einhängen erneut prüfen und Startprotokolle sowie Treiberbindung einbeziehen.

Kernel-Konfiguration auf dem Board prüfen:

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

Tatsächliche Ausgabe:

CONFIG_ROCKCHIP_RKNPU=y

=y bedeutet fest in den Kernel eingebaut. Deshalb bedeutet ein fehlendes rknpu in lsmod nicht, dass der Treiber fehlt. Der offizielle RKNN SDK V2.3.2-Schnellstart empfiehlt RKNPU 0.9.2 oder neuer; hier wurde die Inferenz mit 0.9.8 geprüft.

#1.3 Falls der Treiber fehlt oder aktualisiert werden muss

Diese Anleitung verwendet den Seeed/Armbian-Kernel für reComputer RK3588. Bei erfolgreicher Treiberprüfung ohne Kernel-Neuinstallation direkt zu Abschnitt 2 gehen.

Beim gleichen Board-Modell mit konfigurierter Seeed-Paketquelle zuerst Kernel- und Device-Tree-Pakete prüfen:

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

Erst wenn beide Pakete aus der passenden Paketquelle stammen und ihre Kandidatenversionen zusammenpassen, den zugehörigen Kernel und Device Tree installieren bzw. aktualisieren:

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

Ein Neustart trennt SSH; nach erneuter Anmeldung den Treiber wie in Abschnitt 1.2 prüfen.

Wenn die Pakete fehlen, Hersteller-Image oder BSP für dieses Board-Modell verwenden. Bei einem eigenen Kernel CONFIG_ROCKCHIP_RKNPU=y aktivieren und die NPU-Device-Tree-Konfiguration dieses Boards nutzen.

#2. Runtime und Toolkit Lite2 installieren und prüfen

#2.1 Aufgaben der drei Komponenten

Der PC verwendet from rknn.api import RKNN, Board-Python from rknnlite.api import RKNNLite. Lite2 konvertiert keine Modelle; das C++-Beispiel ruft Runtime direkt auf.

Diese Anleitung führt Inferenz lokal auf dem Board aus; rknn_server muss nicht gestartet werden.

#2.2 Feste Stände der offiziellen Repositories auf dem PC holen

Abschnitte 3 und 4 verwenden dieselben zwei Verzeichnisse. In einem neuen Arbeitsverzeichnis nur einmal klonen.

Auf dem 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

Dies sind die im Test verwendeten Commits; Model Zoo entspricht v2.3.2. Code und Pakete fixieren, damit spätere Repository-Updates keine Befehlspfade ändern.

#2.3 Runtime auf dem Board installieren

Auf dem 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/

Auf dem Board: Eine eventuell vorhandene alte Bibliothek sichern und dann die neue installieren.

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'

Die Versionszeichenfolge dieses Pakets lautet:

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

Lite2 benötigt /usr/lib/librknnrt.so; LD_LIBRARY_PATH nur für das Demo-Verzeichnis zu setzen ersetzt diesen Schritt nicht.

#2.4 Toolkit Lite2 auf dem Board installieren

Auf dem Board läuft Debian 12 mit Python 3.11; daher das cp311-Wheel für aarch64 wählen.

Auf dem 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/

Auf dem Board:

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

Tatsächliche Ergebnisse der beiden Prüfungen:

No broken requirements found.
RKNN Toolkit Lite2 import OK

Bei ensurepip is not available python3.11-venv installieren und die virtuelle Umgebung neu erstellen. Abschnitt 4 prüft die tatsächliche Inferenz.

#3. Toolkit auf dem Ubuntu-PC einrichten und YOLO11n konvertieren

#3.1 Python-3.11-Umgebung auf dem PC erstellen

Auf dem PC: Die folgenden Befehle installieren Miniforge auf einem neuen PC. Falls Conda bereits vorhanden ist, damit eine gleichnamige Umgebung erstellen.

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

In jedem neuen PC-Terminal vor den folgenden Python-Befehlen source ~/miniforge3/etc/profile.d/conda.sh und conda activate rknn2 ausführen.

#3.2 Toolkit2 2.3.2 installieren

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

Getestet wurden Python 3.11.14, Toolkit2 2.3.2, ONNX 1.16.1 und protobuf 4.25.4; pip check meldete No broken requirements found.. Abhängigkeiten in einer isolierten Umgebung fixieren, um Projektkonflikte zu vermeiden.

#3.3 Offiziell angepasstes YOLO11n herunterladen

Auf dem PC:

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

Die heruntergeladene Datei yolo11n.onnx war 10,527,859 Bytes groß.

Das für Rockchip angepasste ONNX verwenden, dessen Ausgabelayout zur C++-Nachverarbeitung passt. Eigene Modelle nach den YOLO11-Exportanweisungen exportieren.

#3.4 In ein RK3588-INT8-Modell konvertieren

Auf dem 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

Die vier Argumente sind ONNX-Pfad, Zielplattform, Quantisierungstyp und Ausgabepfad. Auf dieser Seite muss rk3588 verwendet werden.

Aus examples/yolo11/python ausführen, damit das Skript datasets/COCO/coco_subset_20.txt findet. Dieser Datensatz ist für die Beispielprüfung; produktive Modelle mit realitätsnahen Daten kalibrieren.

Auszug aus der tatsächlichen Konvertierungsausgabe:

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

Erfolgreiche Konvertierung erzeugt die .rknn-Datei. Der Hinweis zur Änderung der Ein-/Ausgabetypen auf int8 gehört zur Quantisierung; diese mit dem passenden C++-Beispiel verarbeiten.

#4. Erstellen, mit SCP bereitstellen und ausführen

#4.1 ARM64-Cross-Compiler vorbereiten

Auf dem 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

Getestet wurde Linaro GCC 6.3.1 20170404. GCC_COMPILER ist ein Präfix ohne abschließendes -gcc; das Build-Skript ergänzt es.

#4.2 YOLO11-C++-Beispiel für RK3588 erstellen

Auf dem PC:

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

Das Modell vor dem Build konvertieren, damit das Skript .rknn ins Deployment-Verzeichnis kopiert.

So sieht das Deployment-Verzeichnis aus; weitere mitgelieferte Beispiele können bleiben:

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 Komplettes Verzeichnis per SCP bereitstellen

Auf dem 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/

Das ganze Verzeichnis einschließlich lib/ und model/ kopieren; die mitgelieferte Runtime hat Version 2.3.2.

#4.4 Objekterkennung auf dem Board ausführen

Auf dem Board:

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

Auszug aus der tatsächlichen RK3588-Ausgabe:

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

Die Erkennung ist abgeschlossen, wenn der Prozess normal endet und out.png erzeugt; Koordinaten und Konfidenz können sich mit Version und Quantisierung ändern.

Auf dem PC das Bild abrufen:

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

Das Ergebnisbild auf dem PC öffnen und Erkennungsrahmen ansehen oder out.png in der grafischen Board-Oberfläche öffnen.

#4.5 Prüfen, ob Lite2 dasselbe Modell ausführt

Dasselbe Modell und eine Nulleingabe prüfen den Lite2-Inferenzpfad; Bildnachverarbeitung für die Erkennung erfolgt dabei nicht.

Auf dem Board:

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

Tatsächliches Ergebnis:

Lite2 inference OK; output count: 9

Den absoluten Pfad zum Python der virtuellen Umgebung nutzen, damit sudo python3 nicht versehentlich das System-Python ohne Lite2 aufruft.

#4.6 Häufige Probleme und Abnahmekriterien

Danach sollten NPU-Treiber abfragbar, Runtime/Lite2 nutzbar, PC-Konvertierung erfolgreich, das C++-Programm zur Erzeugung eines Erkennungsbildes fähig und Lite2 zur Rückgabe von neun Ausgabetensoren fähig sein.

#4.7 Referenzen

• Offizielles RKNN-Toolkit2-Repository: Toolkit, Runtime, Lite2 und Dokumentation.
• RKNN SDK V2.3.2-Schnellstart: Diese Anleitung nutzt SSH/SCP für Verbindung und Übertragung.
• Hier geprüftes YOLO11-Beispiel: ONNX-Download, Konvertierungsskript und C++-Nachverarbeitung.
• Seeed-Armbian-Erweiterung und Paketquelle: Quelle der passenden Kernel- und Device-Tree-Pakete für reComputer.