Snelstart: CNN-modellen uitvoeren op RK3588

Met YOLO11n behandelt deze handleiding NPU-stuurprogramma controleren → Runtime en Toolkit Lite2 installeren → conversie op pc → C++ bouwen en implementeren → inferentie op het board. Het model draait op de ingebouwde NPU van RK3588, via SSH/SCP of de lokale terminal.

#Voordat je begint

Waar voer je opdrachten uit: ‘Op pc’ is de Ubuntu-computer; ‘Op het board’ is SSH of de lokale terminal. Vervang BOARD_IP en voorbeeldgebruiker rk3588 door het echte adres en account.

Als SSH nog niet is ingeschakeld op het board, voer dan eerst lokaal op het board uit:

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

Maak daarna vanaf de pc verbinding. Controleer bij de eerste verbinding de hostvingerafdruk en voer op verzoek je wachtwoord in:

ssh rk3588@BOARD_IP

#1. Een ontbrekend NPU-stuurprogramma oplossen

#1.1 Kernelstuurprogramma versus gebruikerssoftware

Het NPU-stuurprogramma van RK3588 is RKNPU in de kernel, ingesteld via CONFIG_ROCKCHIP_RKNPU. Noch de Runtime-.so, noch het Python-wheel van Toolkit Lite2 vervangt het kernelstuurprogramma.

#1.2 Stuurprogramma, apparaatknooppunt en belasting controleren

Op het 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

Fragment uit de werkelijke testuitvoer:

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

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

Het NPU-knooppunt was hier renderD130; het nummer kan veranderen. Herken het aan device/driver dat naar RKNPU verwijst.

Als debugfs niet is aangekoppeld, voer dan eerst uit:

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

Probeer na het aankoppelen opnieuw en beoordeel ook het opstartlog en de stuurprogrammakoppeling.

Controleer de kernelconfiguratie op het board:

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

Werkelijke uitvoer:

CONFIG_ROCKCHIP_RKNPU=y

=y betekent ingebouwd in de kernel; als rknpu niet in lsmod staat, is het stuurprogramma dus niet noodzakelijk afwezig. De officiële snelstart van RKNN SDK V2.3.2 beveelt RKNPU 0.9.2 of hoger aan; hier is inferentie met 0.9.8 geverifieerd.

#1.3 Als het stuurprogramma ontbreekt of moet worden bijgewerkt

Deze handleiding gebruikt de Seeed/Armbian-kernel voor reComputer RK3588. Als de stuurprogrammacontroles slagen, ga dan zonder herinstallatie van de kernel direct naar sectie 2.

Controleer op hetzelfde boardmodel, met de Seeed-pakketbron ingesteld, eerst de kernel- en device-tree-pakketten:

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

Controleer of beide pakketten uit de juiste bron voor dit board komen en of hun kandidaatversies overeenkomen. Installeer of werk daarna de passende kernel en device tree bij:

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

Opnieuw opstarten verbreekt SSH; controleer na herverbinden het stuurprogramma volgens sectie 1.2.

Als de pakketten ontbreken, gebruik dan een fabrikantsimage of BSP voor dit boardmodel. Schakel in een eigen kernel CONFIG_ROCKCHIP_RKNPU=y in en gebruik de NPU-device-tree-configuratie van dit board.

#2. Runtime en Toolkit Lite2 installeren en controleren

#2.1 De drie componenten

De pc gebruikt from rknn.api import RKNN; Python op het board gebruikt from rknnlite.api import RKNNLite. Lite2 converteert geen modellen; het C++-voorbeeld roept Runtime direct aan.

Deze handleiding voert inferentie lokaal op het board uit; rknn_server hoeft niet te draaien.

#2.2 Vaste revisies van de officiële repositories op de pc ophalen

Secties 3 en 4 gebruiken dezelfde twee mappen; kloon ze eenmalig in een nieuwe werkmap.

Op 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

Dit zijn de tijdens de test gebruikte commits; Model Zoo komt overeen met v2.3.2. Zet code en pakketten vast zodat latere repository-updates de opdrachtpaden niet veranderen.

#2.3 Runtime op het board installeren

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

Op het board: maak een reservekopie van een eventuele oude bibliotheek voordat je de nieuwe installeert.

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'

De versietekst van dit pakket is:

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

Lite2 vereist /usr/lib/librknnrt.so; LD_LIBRARY_PATH alleen voor de Demo-map instellen vervangt deze stap niet.

#2.4 Toolkit Lite2 op het board installeren

Het board gebruikt Debian 12 met Python 3.11; kies daarom het cp311-wheel voor aarch64.

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

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

Werkelijke resultaten van de twee controles:

No broken requirements found.
RKNN Toolkit Lite2 import OK

Als ensurepip is not available verschijnt, installeer dan python3.11-venv en maak de virtuele omgeving opnieuw. Sectie 4 controleert de echte inferentie.

#3. Toolkit op de Ubuntu-pc instellen en YOLO11n converteren

#3.1 Een Python 3.11-omgeving op de pc maken

Op pc: deze opdrachten installeren Miniforge op een nieuwe pc. Als Conda al aanwezig is, maak daarmee een omgeving met dezelfde naam.

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

Voer in elke nieuwe pc-terminal source ~/miniforge3/etc/profile.d/conda.sh en conda activate rknn2 uit vóór de volgende Python-opdrachten.

#3.2 Toolkit2 2.3.2 installeren

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

De geteste omgeving gebruikte Python 3.11.14, Toolkit2 2.3.2, ONNX 1.16.1 en protobuf 4.25.4; pip check gaf No broken requirements found. terug. Zet afhankelijkheden vast in een geïsoleerde omgeving om conflicten te voorkomen.

#3.3 Officieel aangepast YOLO11n downloaden

Op pc:

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

Het gedownloade yolo11n.onnx was 10,527,859 bytes groot.

Gebruik de voor Rockchip aangepaste ONNX waarvan de uitvoerindeling past bij de C++-nabewerking. Exporteer eigen modellen volgens de YOLO11-exportinstructies.

#3.4 Converteren naar een RK3588 INT8-model

Op 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

De vier argumenten zijn ONNX-pad, doelplatform, kwantisatietype en uitvoerpad. Gebruik op deze pagina rk3588.

Voer uit vanuit examples/yolo11/python zodat het script datasets/COCO/coco_subset_20.txt vindt. Deze dataset is voor voorbeeldvalidatie; kalibreer productiemodellen met gegevens uit echte situaties.

Fragment uit de werkelijke conversie-uitvoer:

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

Geslaagde conversie maakt het .rknn-bestand. De melding dat invoer-/uitvoertypen naar int8 veranderen, hoort bij de kwantisatie; gebruik het bijbehorende C++-voorbeeld voor de verwerking.

#4. Bouwen, met SCP implementeren en uitvoeren

#4.1 ARM64-crosscompiler voorbereiden

Op 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

De geteste compiler was Linaro GCC 6.3.1 20170404. GCC_COMPILER is een voorvoegsel zonder afsluitende -gcc; het buildscript voegt dit toe.

#4.2 Het YOLO11 C++-voorbeeld voor RK3588 bouwen

Op pc:

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

Converteer het model vóór het bouwen zodat het script .rknn naar de implementatiemap kopieert.

Zo ziet de structuur van de implementatiemap eruit; andere meegeleverde voorbeelden mogen blijven staan:

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 De volledige map via SCP implementeren

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

Kopieer de volledige map, inclusief lib/ en model/; de meegeleverde Runtime is versie 2.3.2.

#4.4 Objectdetectie op het board uitvoeren

Op het 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

Fragment uit de werkelijke RK3588-uitvoer:

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

Detectie is voltooid als het proces normaal eindigt en out.png maakt; coördinaten en betrouwbaarheid kunnen met versie en kwantisatie verschillen.

Op pc de afbeelding ophalen:

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

Open de resultaatfoto op de pc voor de detectiekaders of open out.png in de grafische interface van het board.

#4.5 Controleren of Lite2 hetzelfde model uitvoert

Controleer met hetzelfde model en een invoer van nullen het Lite2-inferentiepad; deze stap voert geen nabewerking voor beelddetectie uit.

Op het 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

Werkelijk resultaat:

Lite2 inference OK; output count: 9

Gebruik het absolute pad naar Python in de virtuele omgeving, zodat sudo python3 niet per ongeluk de systeem-Python zonder Lite2 start.

#4.6 Veelvoorkomende problemen en acceptatiecriteria

Na afloop moet het NPU-stuurprogramma opvraagbaar zijn, Runtime/Lite2 werken, pc-conversie slagen, het C++-programma een detectieafbeelding kunnen maken en Lite2 negen uitvoertensoren teruggeven.

#4.7 Bronnen

• Officiële RKNN-Toolkit2-repository: Toolkit, Runtime, Lite2 en documentatie.
• RKNN SDK V2.3.2-snelstart: deze handleiding gebruikt SSH/SCP voor verbinding en overdracht.
• Hier getest YOLO11-voorbeeld: ONNX-download, conversiescript en C++-nabewerking.
• Seeed Armbian-uitbreiding en pakketbron: bron van de passende kernel- en device-tree-pakketten voor reComputer.