Inicio rápido: ejecutar modelos CNN en RK3576

Esta guía recorre comprobación del controlador NPU → instalación de Runtime y Toolkit Lite2 → conversión del modelo en PC → compilación y despliegue C++ → inferencia en la placa. Utiliza YOLO11n de RKNN Model Zoo en la NPU integrada de RK3576, mediante SSH/SCP o la terminal local de la placa.

#Antes de empezar

Dónde ejecutar los comandos: «En PC» indica el equipo de desarrollo Ubuntu; «En la placa», una sesión SSH o su terminal local. BOARD_IP es un marcador: sustitúyelo por la IP local de tu placa.

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

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:

ssh rk3576@BOARD_IP

#1. Resolver la ausencia del controlador NPU

#1.1 Controlador del kernel frente a software de usuario

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

#1.2 Comprobar controlador, nodo de dispositivo y carga

En la placa:

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:

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

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

renderD129 fue el nodo NPU detectado en esta prueba, no un número fijo. Identifícalo porque device/driver apunta a RKNPU. Otros nodos render pueden pertenecer al controlador de pantalla o a la GPU; la existencia de /dev/dri no basta para confirmar que la NPU funciona.

Si debugfs no está montado, ejecuta primero:

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

Repite la consulta de versión. La ausencia aislada del archivo de debugfs no demuestra que falte el controlador; comprueba también el registro de arranque y la asociación del controlador.

Comprueba la configuración del kernel en la placa:

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

Salida real:

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 RK3576. Si las comprobaciones del controlador 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:

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

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:

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

Esta operación cambia el kernel de arranque y corta SSH. Tras reconectar, repite la sección 1.2; que el comando de instalación termine correctamente no verifica el controlador.

Si no están disponibles esos paquetes, obtén la imagen del fabricante o el BSP para este modelo exacto de placa. No instales el kernel de otra placa, copies rknpu.ko al azar ni utilices paquetes DKMS de RK182x. En un BSP propio, activa CONFIG_ROCKCHIP_RKNPU=y en el kernel apropiado, conserva el árbol de dispositivos NPU correcto y sigue las instrucciones de compilación e instalación de ese BSP. Estos pasos dependen de la placa y no se resuelven con pip install de Toolkit.

#2. Instalar y verificar Runtime y Toolkit Lite2

#2.1 Función de los tres componentes

En el PC se importa from rknn.api import RKNN; en la placa, Lite2 se importa con from rknnlite.api import RKNNLite. Lite2 ejecuta inferencia, pero no convierte ONNX a RKNN; el ejemplo C++ no depende de Lite2.

Esta guía transfiere archivos con SCP y los ejecuta en la placa; no usa inferencia USB desde el PC, por lo que 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:

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:

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/

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

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:

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

Lite2 necesita este paso. La versión probada busca /usr/lib/librknnrt.so; configurar LD_LIBRARY_PATH solo para el directorio Demo no sustituye la comprobación de la biblioteca del sistema. En RK3588, su ausencia produjo Can not find dynamic library on RK3588!; instalar el archivo resolvió el error.

#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:

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/

En la placa:

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:

No broken requirements found.
RKNN Toolkit Lite2 import OK

No copies el wheel x86_64 del PC a la placa. Si aparece ensurepip is not available, instala python3.11-venv y vuelve a crear el entorno virtual. Una importación correcta solo comprueba el paquete Python; la sección 4 verifica la inferencia NPU 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.

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:

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

El entorno de conversión probado usó Python 3.11.14 y Toolkit2 2.3.2; tras corregir dependencias, pip check devolvió No broken requirements found..

Fijar ONNX y protobuf explícitamente evita dependencias heredadas de otros proyectos: la conversión usa ONNX 1.16.1 y protobuf 4.25.4 en un entorno aislado, sin modificar el entorno Conda original.

#3.3 Descargar YOLO11n adaptado oficialmente

En PC:

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 este ONNX adaptado para Rockchip. Su disposición de salida coincide con el posprocesamiento C++ oficial; no lo sustituyas por cualquier exportación original de Ultralytics. Para un modelo entrenado por ti, sigue las instrucciones oficiales de exportación de YOLO11.

#3.4 Convertir a un modelo INT8 para RK3576

En 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

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

El script usa datasets/COCO/coco_subset_20.txt del repositorio para calibrar. Ejecútalo desde examples/yolo11/python para que resuelva las rutas relativas. Este conjunto pequeño sirve para la primera prueba; calibra y evalúa los modelos de producción con datos representativos de situaciones reales.

Extracto de la salida de conversión real:

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

La primera línea del registro puede incluir datos internos de compilación; comprueba que se genere el archivo de destino. El aviso de que las entradas y salidas predeterminadas pasan a int8 es normal en esta cuantización. Deja que el ejemplo C++ correspondiente procese la entrada y salida; no conviertas la imagen arbitrariamente a valores con signo.

Este ejemplo de RKNN2 solo necesita desplegar un archivo de modelo .rknn.

#4. Compilar, desplegar con SCP y ejecutar

#4.1 Preparar el compilador cruzado ARM64

En 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

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 RK3576

En PC:

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

Usa bash build-linux.sh para evitar Permission denied si el script del repositorio no tiene permiso de ejecución. Convierte el modelo antes de compilar para que el script incluya el .rknn generado en el directorio de despliegue.

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

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

Si conviertes para ambas plataformas en el mismo repositorio, el directorio de instalación puede contener dos archivos .rknn. Selecciona explícitamente el que termina en rk3576 al ejecutar.

#4.3 Desplegar el directorio completo con SCP

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

Copia lib/ y model/, no solo el ejecutable. El ejemplo incluye Runtime en lib/; la versión probada fue 2.3.2.

#4.4 Ejecutar detección de objetos en la placa

En la placa:

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

Extracto de la salida real de RK3576:

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

La prueba tiene éxito si el proceso termina normalmente, muestra detecciones de autobús y personas, y crea out.png en el directorio actual. Las coordenadas y puntuaciones pueden variar ligeramente según versiones y cuantización. No se midieron FPS estables; esta prueba funcional no es una referencia de rendimiento.

En PC, recuperar la imagen:

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

Abre la imagen en el PC para inspeccionar los recuadros de detección. Si la placa tiene pantalla, también puedes abrirla en su interfaz gráfica.

#4.5 Verificar que Lite2 ejecuta el mismo modelo

Después de la detección C++, usa el mismo modelo para comprobar la ruta de inferencia Python.

En la placa:

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

Resultado real:

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

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.