CNN- und Transformer-Modelle auf einem RK182x-Beschleuniger ausführen

Diese Anleitung verwendet einen Ubuntu-x86_64-PC zur Modellkonvertierung und Kreuzkompilierung von Anwendungen. Anschließend wird die Anwendung per SSH/SCP auf einem RK3588-Host mit Debian bereitgestellt, auf dem ein über PCIe verbundener RK182x-M.2-Beschleuniger die Inferenz ausführt. Die Komponenten arbeiten wie folgt zusammen:

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. Einen fehlenden RK182x-Treiber beheben

#1.1 Die betroffene Ebene bestimmen

Auf dem RK3588-Host ausführen:

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

Vor der Treiberinstallation lieferte die PCIe-Erkennung in diesem Beispiel bereits das folgende Ergebnis. Für das Gerät gab es jedoch keinen Eintrag Kernel driver in use, und /dev/pcie-rkep-* war nicht vorhanden:

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

Auch der Proxy gab Folgendes aus:

List of ntb devices attached
No pcie-rkep devices found

Das bedeutet, dass der Host den PCIe-Endpunkt erkannt hat, der Treiber pcie-rkep jedoch noch installiert und geladen werden muss. rknn-smi: command not found bedeutet, dass das Verwaltungsprogramm nicht installiert ist oder sich nicht im PATH befindet.

Hinweis: Wenn der PCIe-Endpunkt selbst fehlt, prüfen Sie zuerst Stromversorgung, M.2-Verbindung und PCIe-Konfiguration des Hosts. Die weiteren Installationsschritte setzen voraus, dass der Endpunkt bereits erkannt wurde.

#1.2 Das M.2-Paket herunterladen und installieren

Laden Sie das folgende Paket aus dem offiziellen vorkompilierten RK1820/RK1828-Softwarepaket herunter:

rknn3-rk182x-m2_1.1.0_arm64.deb

Wählen Sie m2 und arm64. Verwenden Sie weder sodimm noch sodimm-net als Ersatz und flashen Sie das in der Paketdokumentation genannte RK3588-EVB10-Board-Image nicht auf den reComputer.

Laden Sie rknn3-rk182x-m2_1.1.0_arm64.deb in das Verzeichnis Downloads des Geräts hoch.

Auf dem RK3588-Host ausführen:

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

Wenn das Installationsprogramm DKMS erkennt, sollte es Engine: DKMS anzeigen, den Treiber für den laufenden Kernel bauen und installieren sowie das Laden beim Systemstart konfigurieren.

Dieses DEB-Paket enthält PCIe-Treiberquellen und DKMS-Konfiguration, M.2-Firmware, gemeinsam genutzte Runtime-Bibliotheken, rknn3_transfer_proxy, rknn-smi und den RKNN3-Startdienst. Die System-Runtime muss im nächsten Abschnitt nicht erneut überschrieben werden.

#1.3 Treiber prüfen und neu starten

Auf dem RK3588-Host ausführen:

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

Erwartete Ausgabe:

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

Der PATH eines normalen Benutzers enthält möglicherweise nicht /usr/sbin. Daher führt diese Anleitung dkms und modinfo mit sudo aus. Schließen Sie nicht allein aus einer Meldung „command not found“ unter einem normalen Benutzer, dass die Software fehlt.

Starten Sie das Gerät neu, nachdem Sie die Treiberinstallation bestätigt haben:

sudo reboot

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

#2.1 Runtime: durch das M.2-DEB-Paket installiert

Das in Abschnitt 1 installierte M.2-Paket stellt bereits die für diese Anleitung benötigte Runtime bereit. Die wichtigsten Dateien sind:

Der Bestandteil rk1820 im Firmwarepfad entspricht der tatsächlichen Benennung des Pakets. Verwenden Sie dasselbe M.2-Paket auch für einen RK1828-Beschleuniger.

Auf dem RK3588-Host ausführen:

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

Erwartete Ausgabe:

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

Geräteindizes, Temperaturen und Speichernutzung variieren je nach Betriebszustand. Jede Komponente wird unabhängig versioniert, daher müssen die Versionsnummern nicht übereinstimmen. Die C/C++-Runtime ist nun einsatzbereit.

#2.2 Installationsdateien für Toolkit Lite vorbereiten

Klonen Sie die offiziellen Repositorys auf dem PC und übertragen Sie anschließend nur die Toolkit-Lite-Installationsdateien auf den RK3588-Host. Dieselben Repositorys werden im nächsten Abschnitt zur Installation des PC-Toolkits verwendet.

Auf dem PC ausführen:

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

Die Repositorys sind auf die für diese Anleitung geprüften Commits festgelegt, damit spätere Änderungen an Dateinamen oder APIs auf main die Reproduzierbarkeit nicht beeinträchtigen. Klonen Sie sie in einer neuen Umgebung nur einmal; spätere Abschnitte verwenden beide Verzeichnisse erneut.

Auf dem PC ausführen:

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/

Der RK3588-Host in dieser Anleitung verwendet Debian 12 mit Python 3.11. Wählen Sie daher das Paket cp311 und aarch64.

#2.3 Toolkit Lite installieren

Auf dem RK3588-Host ausführen:

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

Ausgabe der geprüften Umgebung:

No broken requirements found.
RKNN3 Toolkit Lite import OK

Fragen Sie anschließend den Beschleuniger über die Python-API ab:

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

Die geprüfte Umgebung lieferte:

[b'0000:01:00.0']

Der Befehl verwendet absichtlich den absoluten Pfad zum Python-Programm der virtuellen Umgebung. sudo python3 wechselt normalerweise zum System-Python, das das in der virtuellen Umgebung installierte Toolkit-Lite-Paket nicht findet. Abschnitt 4 führt eine C++-Anwendung aus und ist nicht von einer aktiven Toolkit-Lite-Umgebung abhängig.

#3. Toolkit konfigurieren und YOLOv6 auf einem Ubuntu-PC konvertieren

#3.1 Eine Python-3.10-Umgebung erstellen

Auf dem PC ausführen. Erstellen Sie mit Miniforge eine neue isolierte Umgebung. Auf dem Prüf-PC war Conda bereits unter ~/miniconda3 installiert; die Konvertierung erfolgte in dessen Umgebung toolkit3.

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

Führen Sie nach dem Öffnen eines neuen Terminals zuerst source ~/miniforge3/etc/profile.d/conda.sh und conda activate toolkit3 aus. Wenn Conda bereits verfügbar ist, verwenden Sie den vorhandenen Installationspfad, anstatt eine weitere Kopie zu installieren.

#3.2 RKNN3-Toolkit 1.1.0 installieren

Auf dem PC ausführen:

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

Versionen und Ausgabe der Abhängigkeitsprüfung aus der geprüften Umgebung:

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

In diesem festgelegten Commit liegt das Wheel direkt unter packages/ und nicht wie im PDF-Beispiel unter packages/x86_64/. Installieren Sie Toolkit2 nicht in dieser dedizierten Umgebung. Dieses SDK verwendet auf dem PC weiterhin from rknn.api import RKNN als Import-Einstiegspunkt und kann daher leicht mit dem älteren Toolkit verwechselt werden.

#3.3 Das YOLOv6n-ONNX-Modell herunterladen

Auf dem PC ausführen:

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

Das Downloadskript lädt standardmäßig die für RK182X optimierte Datei yolov6n_rknn3.onnx. Der geprüfte Download war 18,644,871 Byte groß.

Dieses optimierte Modell integriert YOLO-Decodierung, Filterung und Sortierung von Kandidatenrahmen, NMS und weitere Verarbeitungsschritte in den Modellberechnungsgraphen. Diese Anleitung verwendet ausschließlich dieses Modell und mischt es nicht mit dem Standardmodell ohne das Suffix _rknn3.

#3.4 INT8-Konvertierung ausführen

Auf dem PC ausführen:

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

Parameterbeschreibung:

Das Skript konfiguriert Eingabenormalisierung, uint8/NHWC-Eingabeeigenschaften und core_num=1. Behalten Sie für die erste Prüfung die Standardkonfiguration bei und ändern Sie das ONNX-Eingabelayout nicht vorab.

Auszug aus dem geprüften Konvertierungsprotokoll:

I version: rknn3-toolkit 1.1.0(cdbad21c1@2026-08-22T07:33:23)
...
I rknn building ...
...
I rknn building done.
...
--> Export rknn model
done

Prüfen Sie, ob beide Modelldateien erzeugt wurden:

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

Bei der geprüften Konvertierung war die .rknn-Datei etwa 249 KB und die .weight-Datei etwa 5,1 MB groß. Beide Dateien müssen gemeinsam bereitgestellt werden.

#4. Anwendung bauen, per SCP bereitstellen und ausführen

#4.1 Einen ARM64-Cross-Compiler auf dem PC installieren

Auf dem PC ausführen:

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

Für die Prüfung verwendete Compilerversion:

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

GCC_COMPILER ist das Compilerpräfix und enthält nicht das abschließende -gcc; das Buildskript ergänzt es. Die mit Ubuntu 20.04 gelieferte CMake-Version erfüllt die Mindestanforderung CMake 3.15 dieses Beispiels.

#4.2 Die YOLOv6-C++-Demo bauen

Auf dem PC ausführen:

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

Auszug aus dem geprüften Buildprotokoll:

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

Das Bereitstellungsverzeichnis lautet:

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

Das Buildskript kopiert das konvertierte Modell in das Bereitstellungsverzeichnis. Die erforderliche Reihenfolge lautet daher: zuerst konvertieren, dann bauen und paketieren.

#4.3 Das gesamte Bereitstellungsverzeichnis per SCP kopieren

Auf dem PC ausführen:

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/

Kopieren Sie das gesamte Verzeichnis, nicht nur die ausführbare Datei oder die .rknn-Datei. Diese Anleitung verwendet ein neues Bereitstellungsverzeichnis, damit Dateien anderer Projekte nicht überschrieben werden.

#4.4 Auf dem RK3588-Host ausführen

Auf dem RK3588-Host ausführen:

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

Die abschließende 1 ist core_mask=0x01 und entspricht core_num=1 dieses Modells. sudo env ... ermöglicht den Zugriff auf den Geräteknoten und übergibt zugleich ausdrücklich den Bibliothekspfad der Demo. Wenn Sie vor sudo nur export LD_LIBRARY_PATH in der Benutzershell ausführen, kann die Variable entfernt werden.

Dieser Befehl verwendet die gemeinsam genutzten Runtime-Bibliotheken aus dem Model-Zoo-Bereitstellungsverzeichnis. Host-Firmware und Kommunikationsdienst werden weiterhin vom in Abschnitt 1 installierten M.2-Paket bereitgestellt. Diese genaue Versionskombination wurde gemeinsam geprüft.

Auszug aus einem tatsächlichen Inferenzlauf:

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

Diese Werte stammen aus einer einzelnen Messung und stellen weder eine dauerhafte FPS-Angabe noch einen Leistungsbenchmark dar. Erfolgreich ist der Ablauf, wenn die Anwendung normal beendet wird, plausible Erkennungen ausgibt und out.png erzeugt.

#4.5 Das Ergebnisbild abrufen

Auf dem PC ausführen:

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

Öffnen Sie das Ergebnis direkt auf dem Ubuntu-Desktop. Wenn am RK3588-Host ein Bildschirm angeschlossen ist, können Sie das Bild dort ansehen, ohne es zurückzukopieren.

Das folgende Bild wurde während der Prüfung erzeugt:

#5. Fehlerbehebung beim ersten Lauf

Sammeln Sie Diagnoseinformationen auf dem RK3588-Host:

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. Versionen und Referenzen

Für diese geprüfte Konfiguration sind die Repositorys auf folgende Commits festgelegt:

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

Die Anleitung verwendet durchgehend ~/RKNN3_Project als Arbeitsverzeichnis.

• Offizielles RKNN3-Repository: Beziehungen der Softwarekomponenten und Installationspakete.
• Toolkit Lite in der festgelegten Version: ARM64-Wheel, Abhängigkeiten und Python-Beispiele.
• Runtime in der festgelegten Version: Runtime-Bibliotheken und Kommunikationskomponenten.
• YOLOv6-Beispiel in der festgelegten Version: Download, Konvertierung und C++-Beispielquellcode.
• Seeed-Armbian-Erweiterungen und Paket-Repository: Hersteller-Paket-Repository für das in diesem Beispiel verwendete Board; die Kernel-Header müssen zum laufenden Systemkernel passen.