Inicio rápido: ejecutar modelos CNN en RK3588

Con YOLO11n, esta guía cubre comprobación del controlador NPU → instalación de Runtime y Toolkit Lite2 → conversión en PC → compilación y despliegue C++ → inferencia en la placa. El modelo se ejecuta en la NPU integrada de RK3588 mediante SSH/SCP o la terminal local.

#Antes de empezar

Elemento	Configuración y entorno probado
PC	Ubuntu 20.04.6 LTS，x86_64，Python 3.11
Placa	reComputer RK3588, aarch64
Sistema de la placa	Debian 12 / Armbian `26.08.0-trunk`
Kernel de la placa	`6.1.115-vendor-seeed-rk3588`
Controlador NPU	Probado con `0.9.8`
Versiones de herramientas	RKNN-Toolkit2 / Toolkit Lite2 `2.3.2`
Runtime	Esta guía instala `librknnrt.so 2.3.2`
Ejemplo	YOLO11n, 640 × 640, cuantización INT8
Destino de conversión / compilación	`rk3588` / `rk3588 + aarch64`

Dónde ejecutar los comandos: «En PC» es el equipo Ubuntu; «En la placa» es una sesión SSH o su terminal local. Sustituye BOARD_IP y el usuario de ejemplo rk3588 por la dirección y cuenta reales.

Si SSH aún no está activado en la placa, ejecuta primero lo siguiente en su terminal local:

bash

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

Después, conéctate desde el PC. En la primera conexión, verifica la huella del host e introduce la contraseña cuando se solicite:

bash

ssh rk3588@BOARD_IP

#1. Resolver la ausencia del controlador NPU

#1.1 Controlador del kernel frente a software de usuario

El controlador NPU de RK3588 es RKNPU dentro del kernel, configurado por CONFIG_ROCKCHIP_RKNPU. Ni el .so de Runtime ni el wheel Python de Toolkit Lite2 sustituyen al controlador del kernel.

#1.2 Comprobar controlador, nodo de dispositivo y carga

En la placa:

bash

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

Extracto de la salida real de la prueba:

text

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

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

En esta prueba, el nodo NPU fue renderD130; el número puede cambiar. Identifícalo porque device/driver apunta a RKNPU.

Si debugfs no está montado, ejecuta primero:

bash

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

Repite la prueba tras montarlo y evalúa el estado junto con el registro de arranque y la asociación del controlador.

Comprueba la configuración del kernel en la placa:

bash

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

Salida real:

text

CONFIG_ROCKCHIP_RKNPU=y

=y significa que está integrado en el kernel; que rknpu no aparezca en lsmod no implica que falte el controlador. La guía oficial de inicio rápido de RKNN SDK V2.3.2 recomienda RKNPU 0.9.2 o superior; aquí se verificó la inferencia con 0.9.8.

#1.3 Si falta el controlador o hay que actualizarlo

Esta guía utiliza el kernel Seeed/Armbian para reComputer RK3588. Si las comprobaciones pasan, ve directamente a la sección 2 sin reinstalar el kernel.

En la misma placa, con el repositorio de Seeed configurado, inspecciona primero los paquetes del kernel y del árbol de dispositivos:

bash

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

Cuando confirmes que ambos paquetes proceden del repositorio correspondiente a la placa y que las versiones candidatas coinciden, instala o actualiza el kernel y el árbol de dispositivos adecuados:

bash

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

El reinicio interrumpe SSH; tras reconectar, verifica el controlador como en la sección 1.2.

Si no hay paquetes, usa la imagen del fabricante o el BSP para este modelo de placa. En un kernel propio, activa CONFIG_ROCKCHIP_RKNPU=y y usa la configuración del árbol de dispositivos NPU de esta placa.

#2. Instalar y verificar Runtime y Toolkit Lite2

#2.1 Función de los tres componentes

Componente	Dónde se instala	Función principal
RKNN-Toolkit2	Entorno Python aislado en el PC Ubuntu	Convertir y cuantizar ONNX para generar `.rknn`
RKNN Runtime / `librknnrt.so`	Placa RK3588	API C/C++ para cargar modelos y ejecutar inferencia NPU
RKNN-Toolkit-Lite2	Entorno Python en la placa RK3588	API de inferencia Python; requiere Runtime y controlador en la placa

El PC usa from rknn.api import RKNN; el Python de la placa usa from rknnlite.api import RKNNLite. Lite2 no convierte modelos; el ejemplo C++ llama directamente a Runtime.

Esta guía ejecuta la inferencia en la placa; no hay que iniciar rknn_server.

#2.2 Obtener revisiones fijas de los repositorios oficiales en el PC

Las secciones 3 y 4 reutilizan estos dos directorios; clónalos una sola vez en un directorio de trabajo nuevo.

En PC:

bash

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

Estos son los commits utilizados en la prueba; Model Zoo corresponde a v2.3.2. Fija código y paquetes para evitar que futuras actualizaciones cambien las rutas de los comandos.

#2.3 Instalar Runtime en la placa

En PC:

bash

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/

En la placa: guarda una copia de la biblioteca anterior, si existe, antes de instalar la nueva.

bash

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 cadena de versión de este paquete es:

text

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

Lite2 necesita /usr/lib/librknnrt.so; configurar LD_LIBRARY_PATH solo en el directorio Demo no sustituye este paso.

#2.4 Instalar Toolkit Lite2 en la placa

La placa usa Debian 12 con Python 3.11; por ello, selecciona el wheel cp311 para aarch64.

En PC:

bash

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/

En la placa:

bash

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

Resultados reales de las dos comprobaciones:

text

No broken requirements found.
RKNN Toolkit Lite2 import OK

Si aparece ensurepip is not available, instala python3.11-venv y recrea el entorno virtual. La sección 4 verifica la inferencia real.

#3. Configurar Toolkit en el PC Ubuntu y convertir YOLO11n

#3.1 Crear un entorno Python 3.11 en el PC

En PC: estos comandos instalan Miniforge en un PC nuevo. Si ya tienes Conda, úsalo para crear un entorno con el mismo nombre.

bash

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

En cada terminal nueva del PC, ejecuta source ~/miniforge3/etc/profile.d/conda.sh y conda activate rknn2 antes de los siguientes comandos Python.

#3.2 Instalar Toolkit2 2.3.2

En PC:

bash

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

La configuración probada usó Python 3.11.14, Toolkit2 2.3.2, ONNX 1.16.1 y protobuf 4.25.4; pip check devolvió No broken requirements found.. Fija las versiones en un entorno aislado para evitar conflictos con otros proyectos.

#3.3 Descargar YOLO11n adaptado oficialmente

En PC:

bash

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

El archivo yolo11n.onnx descargado ocupaba 10,527,859 bytes.

Usa el ONNX adaptado para Rockchip cuyo formato de salida coincide con el posprocesamiento C++ del ejemplo. Exporta modelos propios según las instrucciones de exportación de YOLO11.

#3.4 Convertir a un modelo INT8 para RK3588

En PC:

bash

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

Los cuatro argumentos son ruta ONNX, plataforma, tipo de cuantización y ruta de salida. En esta página hay que usar rk3588.

Ejecuta desde examples/yolo11/python para que el script encuentre datasets/COCO/coco_subset_20.txt. Este conjunto sirve para verificar el ejemplo; calibra modelos de producción con datos de situaciones reales.

Extracto de la salida de conversión real:

text

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

La conversión correcta crea el archivo .rknn. El aviso de cambio de entradas/salidas a int8 es un recordatorio de cuantización; usa el ejemplo C++ correspondiente para procesarlas.

#4. Compilar, desplegar con SCP y ejecutar

#4.1 Preparar el compilador cruzado ARM64

En PC:

bash

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

El compilador probado fue Linaro GCC 6.3.1 20170404. GCC_COMPILER es un prefijo sin el -gcc final; el script de compilación lo añade.

#4.2 Compilar el ejemplo YOLO11 C++ para RK3588

En PC:

bash

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

Convierte el modelo antes de compilar para que el script copie .rknn al directorio de despliegue.

La estructura del directorio de despliegue es la siguiente; pueden permanecer otros ejemplos incluidos:

text

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 Desplegar el directorio completo con SCP

En PC:

bash

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/

Copia el directorio completo, incluidos lib/ y model/; Runtime incluido es la versión 2.3.2.

#4.4 Ejecutar detección de objetos en la placa

En la placa:

bash

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

Extracto de la salida real de RK3588:

text

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

La detección termina cuando el proceso sale normalmente y crea out.png; coordenadas y confianza pueden variar con la versión y la cuantización.

En PC, recuperar la imagen:

bash

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

Abre la imagen en el PC para ver los recuadros, o abre out.png en la interfaz gráfica de la placa.

#4.5 Verificar que Lite2 ejecuta el mismo modelo

Usa el mismo modelo y una entrada de ceros para comprobar la inferencia Lite2; este paso no realiza posprocesamiento de detección de imágenes.

En la placa:

bash

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

Resultado real:

text

Lite2 inference OK; output count: 9

Usa la ruta absoluta de Python del entorno virtual para evitar que sudo python3 invoque el Python del sistema sin Lite2.

#4.6 Problemas frecuentes y criterios de aceptación

Síntoma	Qué comprobar
No se encuentra el controlador NPU	Revisa la asociación `RKNPU` y el registro de arranque de la sección 1.2; un controlador integrado no tiene que aparecer en `lsmod`
Lite2 se importa, pero falla la inicialización	Comprueba `/usr/lib/librknnrt.so`, el controlador NPU y los permisos de acceso
`Can not find dynamic library`	Instala Runtime del sistema según la sección 2.3; `lib/` del Demo no basta
`pip check` muestra conflictos	Usa el entorno aislado del PC y las dependencias de la sección 3.2, no ONNX/protobuf antiguos de otro proyecto
No se encuentran imágenes de calibración o `py_utils`	Comprueba el directorio de trabajo, el conjunto de calibración del repositorio y `PYTHONPATH`
Plataforma del modelo incorrecta	Convierte de nuevo para `rk3588` y ejecuta `yolo11n_rk3588.rknn`
Falta el modelo o las etiquetas	Copia todo el directorio de despliegue y entra primero en `rknn_yolo11_demo`
Falta una biblioteca dinámica	Comprueba `lib/librknnrt.so` y pasa `LD_LIBRARY_PATH` como en la sección 4.4

Al terminar, debe poder consultarse el controlador NPU, funcionar Runtime/Lite2, completarse la conversión en PC, generar la imagen de detección con C++ y obtener nueve tensores de salida con Lite2.

#4.7 Referencias

Repositorio oficial de RKNN-Toolkit2: Toolkit, Runtime, Lite2 y documentación.
Guía de inicio rápido de RKNN SDK V2.3.2: esta guía usa SSH/SCP para conexión y transferencia.
Ejemplo YOLO11 verificado aquí: descarga ONNX, script de conversión y posprocesamiento C++.
Extensión Armbian y repositorio de Seeed: origen de los paquetes de kernel y árbol de dispositivos para reComputer.