Schnellstart: CNN-Modelle auf RK3576 ausführen

Diese Anleitung führt durch NPU-Treiber prüfen → Runtime und Toolkit Lite2 installieren → Modell auf dem PC konvertieren → C++-Programm erstellen und bereitstellen → Inferenz auf dem Board. Verwendet wird YOLO11n aus dem RKNN Model Zoo auf der integrierten NPU des RK3576, über SSH/SCP oder ein lokales Board-Terminal.

#Vorbereitungen

Ausführungsort: „Auf dem PC“ bezeichnet den Ubuntu-Entwicklungsrechner; „Auf dem Board“ eine SSH-Sitzung oder das lokale Terminal. BOARD_IP ist ein Platzhalter: durch die LAN-IP-Adresse des Boards 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 rk3576@BOARD_IP

#1. Fehlenden NPU-Treiber beheben

#1.1 Kernel-Treiber und Userspace-Software unterscheiden

Der NPU-Treiber des RK3576 ist RKNPU im Kernel, konfiguriert durch CONFIG_ROCKCHIP_RKNPU. Weder die Runtime-Datei .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%,

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

renderD129 war in diesem Test der NPU-Knoten, keine feste Nummer. Erkennbar ist er am Link device/driver auf RKNPU. Andere render-Knoten können zur Anzeigeeinheit oder GPU gehören; /dev/dri allein beweist keine funktionierende NPU.

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

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

Danach die Versionsabfrage wiederholen. Eine fehlende debugfs-Abfragedatei allein beweist keinen fehlenden Treiber; auch Startprotokolle und Treiberbindung prüfen.

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 RK3576. Wenn die Treiberprüfungen erfolgreich sind, ohne Neuinstallation des Kernels direkt mit Abschnitt 2 fortfahren.

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

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

Diese Treiberwartung ändert den Boot-Kernel und trennt SSH. Nach der erneuten Anmeldung Abschnitt 1.2 wiederholen; ein erfolgreicher Installationsbefehl ersetzt keine Treiberprüfung.

Wenn die Pakete nicht verfügbar sind, Hersteller-Image oder BSP für genau dieses Board-Modell beziehen. Keinen Kernel eines anderen Boards installieren, rknpu.ko nicht beliebig kopieren und keine RK182x-DKMS-Pakete verwenden. In einem eigenen BSP CONFIG_ROCKCHIP_RKNPU=y im passenden Kernel aktivieren, den richtigen NPU-Device-Tree beibehalten und den Build- und Deployment-Schritten des BSP folgen. Kernel und Device Tree sind boardabhängig und lassen sich nicht durch pip install von Toolkit ersetzen.

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

#2.1 Aufgaben der drei Komponenten

Auf dem PC from rknn.api import RKNN importieren, auf dem Board Lite2 mit from rknnlite.api import RKNNLite. Lite2 führt Inferenz aus, konvertiert aber ONNX nicht nach RKNN; das C++-Beispiel hängt nicht von Lite2 ab.

Diese Anleitung überträgt Dateien per SCP und führt sie auf dem Board aus. USB-Inferenz vom PC wird nicht verwendet; 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 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/

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 diesen Schritt. Die getestete Version sucht /usr/lib/librknnrt.so; LD_LIBRARY_PATH nur für das Demo-Verzeichnis zu setzen ersetzt die Systembibliotheksprüfung nicht. Auf RK3588 führte die fehlende Datei zu Can not find dynamic library on RK3588!; ihre Installation löste das Problem.

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

Das x86_64-Wheel des PCs nicht auf das Board kopieren. Bei ensurepip is not available python3.11-venv installieren und die virtuelle Umgebung neu erstellen. Ein erfolgreicher Import bestätigt nur das Python-Paket; Abschnitt 4 prüft die tatsächliche NPU-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')"

Die getestete Konvertierungsumgebung nutzte Python 3.11.14 und Toolkit2 2.3.2; nach Korrektur der Abhängigkeiten meldete pip check No broken requirements found..

Das explizite Fixieren von ONNX und protobuf verhindert Altlasten anderer Projekte: Die Konvertierung verwendet ONNX 1.16.1 und protobuf 4.25.4 in einer isolierten Umgebung und ändert die ursprüngliche Conda-Umgebung nicht.

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

Dieses für Rockchip angepasste ONNX verwenden. Sein Ausgabelayout passt zur offiziellen C++-Nachverarbeitung; es nicht durch einen beliebigen ursprünglichen Ultralytics-Export ersetzen. Für selbst trainierte Modelle die offiziellen YOLO11-Exportanweisungen beachten.

#3.4 In ein RK3576-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 rk3576 i8 ../model/yolo11n_rk3576.rknn
ls -lh ../model/yolo11n_rk3576.rknn

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

Das Konvertierungsskript verwendet datasets/COCO/coco_subset_20.txt aus dem Repository zur Kalibrierung. Aus examples/yolo11/python starten, damit relative Pfade stimmen. Dieser kleine Datensatz dient dem ersten Test; produktive Modelle mit repräsentativen Daten kalibrieren und auf Genauigkeit prüfen.

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

Die erste Protokollzeile kann interne Build-Informationen enthalten; entscheidend ist die erzeugte Zieldatei. Der Hinweis, dass Standard-Ein-/Ausgabetypen zu int8 wechseln, ist bei diesem Quantisierungsskript normal. Die Ein-/Ausgabe vom passenden C++-Beispiel verarbeiten lassen und das Bild nicht beliebig in vorzeichenbehaftete Werte umwandeln.

Für dieses RKNN2-Beispiel muss nur eine .rknn-Modelldatei bereitgestellt werden.

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

Auf dem PC:

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

bash build-linux.sh verwenden, um Permission denied zu vermeiden, falls das Repository-Skript nicht ausführbar ist. Erst das Modell konvertieren, dann bauen, damit das Skript die erzeugte .rknn im Deployment-Verzeichnis mitliefert.

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

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

Bei Konvertierung für beide Plattformen im selben Repository können zwei .rknn-Dateien im Installationsverzeichnis liegen. Bei der Ausführung ausdrücklich die Datei mit Suffix rk3576 auswählen.

#4.3 Komplettes Verzeichnis per SCP bereitstellen

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

lib/ und model/ mitkopieren, nicht nur die ausführbare Datei. Die Runtime des Beispiels liegt in lib/; getestet wurde 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_rk3576.rknn model/bus.jpg

Auszug aus der tatsächlichen RK3576-Ausgabe:

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

Erfolgreich ist der Test, wenn der Prozess normal endet, Bus und Personen erkennt und im aktuellen Verzeichnis out.png erzeugt. Koordinaten und Werte können je nach Tool-Version und Quantisierung leicht abweichen. Stabile FPS wurden nicht gemessen; diese Funktionsprüfung ist kein Performance-Benchmark.

Auf dem PC das Bild abrufen:

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

Das Bild auf dem PC öffnen und Erkennungsrahmen prüfen. Bei angeschlossenem Display kann es auch in der grafischen Oberfläche des Boards geöffnet werden.

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

Nach der C++-Erkennung mit demselben Modell den Python-Inferenzpfad prüfen.

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

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.