Ejecutar modelos CNN y Transformer en un acelerador RK182x

Esta guía utiliza un PC Ubuntu x86_64 para convertir modelos y compilar aplicaciones de forma cruzada. Después, despliega la aplicación mediante SSH/SCP en un host RK3588 con Debian, donde un acelerador RK182x M.2 conectado por PCIe realiza la inferencia. Los componentes funcionan juntos de la siguiente manera:

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. Resolver la ausencia del controlador RK182x

#1.1 Identificar la capa del problema

Ejecutar en el host RK3588:

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

Antes de instalar el controlador en este ejemplo, la enumeración PCIe ya mostraba el siguiente resultado. Sin embargo, el dispositivo no tenía una entrada Kernel driver in use y /dev/pcie-rkep-* no existía:

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

Al ejecutar el proxy también se obtuvo:

List of ntb devices attached
No pcie-rkep devices found

Esto significa que el host ha enumerado el extremo PCIe, pero todavía es necesario instalar y cargar el controlador pcie-rkep. rknn-smi: command not found significa que la utilidad de administración no está instalada o no se encuentra en PATH.

Nota: Si no aparece el propio extremo PCIe, comprueba primero la alimentación, la conexión M.2 y la configuración PCIe del host. Los pasos restantes suponen que el extremo ya se ha enumerado.

#1.2 Descargar e instalar el paquete M.2

Descarga el siguiente paquete desde el paquete de software precompilado para RK1820/RK1828 oficial:

rknn3-rk182x-m2_1.1.0_arm64.deb

Selecciona m2 y arm64. No los sustituyas por sodimm o sodimm-net, ni instales en el reComputer la imagen de placa RK3588 EVB10 mencionada en la documentación del paquete.

Sube rknn3-rk182x-m2_1.1.0_arm64.deb al directorio Downloads del dispositivo.

Ejecutar en el host RK3588:

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

Cuando el instalador detecta DKMS, debe mostrar Engine: DKMS, compilar e instalar el controlador para el kernel en ejecución y configurarlo para que se cargue al arrancar.

Este paquete DEB incluye el código fuente del controlador PCIe y su configuración DKMS, el firmware M.2, las bibliotecas compartidas de Runtime, rknn3_transfer_proxy, rknn-smi y el servicio de inicio de RKNN3. No es necesario volver a sobrescribir el Runtime del sistema en la siguiente sección.

#1.3 Verificar el controlador y reiniciar

Ejecutar en el host RK3588:

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

Salida esperada:

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

Es posible que el PATH de un usuario normal no incluya /usr/sbin, por lo que esta guía ejecuta dkms y modinfo con sudo. No concluyas que el software no está instalado solo porque alguno de los comandos muestre «command not found» al ejecutarse como usuario normal.

Después de confirmar que el controlador está instalado, reinicia el dispositivo:

sudo reboot

#2. Instalar y verificar Runtime y Toolkit Lite

#2.1 Runtime: instalado por el paquete DEB M.2

El paquete M.2 instalado en la sección 1 ya proporciona el Runtime necesario para esta guía. Los archivos principales son:

El componente rk1820 de la ruta del firmware es el nombre real utilizado por el paquete. Utiliza el mismo paquete M.2 cuando el acelerador sea un RK1828.

Ejecutar en el host RK3588:

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

Salida esperada:

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

Los índices de dispositivo, las temperaturas y el uso de memoria varían según el estado de ejecución. Cada componente tiene su propia versión, por lo que los números de versión no tienen que coincidir. El Runtime de C/C++ ya está preparado.

#2.2 Preparar los archivos de instalación de Toolkit Lite

Clona los repositorios oficiales en el PC y transfiere únicamente los archivos de instalación de Toolkit Lite al host RK3588. Los mismos repositorios se utilizan para instalar el Toolkit de PC en la siguiente sección.

Ejecutar en el PC:

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

Los repositorios están fijados a los commits verificados para esta guía, de modo que los cambios posteriores en nombres de archivo o API de main no afecten a la reproducibilidad. Clónalos solo una vez en un entorno nuevo; las siguientes secciones reutilizan ambos directorios.

Ejecutar en el PC:

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/

El host RK3588 de esta guía utiliza Debian 12 con Python 3.11, así que selecciona el paquete cp311 y aarch64.

#2.3 Instalar Toolkit Lite

Ejecutar en el host RK3588:

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

Salida del entorno verificado:

No broken requirements found.
RKNN3 Toolkit Lite import OK

A continuación, consulta el acelerador mediante la API de Python:

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

El entorno verificado devolvió:

[b'0000:01:00.0']

El comando utiliza deliberadamente la ruta absoluta al ejecutable de Python del entorno virtual. sudo python3 suele cambiar al Python del sistema, que no puede encontrar el paquete Toolkit Lite instalado en el entorno virtual. La sección 4 ejecuta una aplicación C++ y no depende de que el entorno de Toolkit Lite permanezca activo.

#3. Configurar Toolkit y convertir YOLOv6 en un PC Ubuntu

#3.1 Crear un entorno de Python 3.10

Ejecutar en el PC. Utiliza Miniforge para crear desde cero un entorno aislado. El PC empleado para la verificación ya tenía Conda en ~/miniconda3, y la conversión se realizó en su entorno 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

Después de abrir un terminal nuevo, ejecuta primero source ~/miniforge3/etc/profile.d/conda.sh y conda activate toolkit3. Si ya dispones de Conda, utiliza la ruta de instalación existente en lugar de instalar otra copia.

#3.2 Instalar RKNN3-Toolkit 1.1.0

Ejecutar en el PC:

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

Versiones y resultado de la comprobación de dependencias del entorno verificado:

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

En este commit fijado, el wheel se encuentra directamente en packages/, no en packages/x86_64/ como muestra el ejemplo del PDF. No instales Toolkit2 en este entorno dedicado. Este SDK sigue utilizando from rknn.api import RKNN como punto de importación en el PC, por lo que puede confundirse fácilmente con el toolkit anterior.

#3.3 Descargar el modelo ONNX YOLOv6n

Ejecutar en el PC:

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

De forma predeterminada, el script de descarga obtiene yolov6n_rknn3.onnx, optimizado para RK182X. La descarga verificada tenía 18,644,871 bytes.

Este modelo optimizado incorpora la decodificación YOLO, el filtrado y la ordenación de cuadros candidatos, NMS y otros procesos en el grafo de cálculo del modelo. Esta guía utiliza únicamente este modelo y no lo mezcla con el modelo estándar sin el sufijo _rknn3.

#3.4 Realizar la conversión INT8

Ejecutar en el PC:

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

Descripción de los parámetros:

El script configura la normalización de entrada, las propiedades de entrada uint8/NHWC y core_num=1. Mantén la configuración predeterminada durante la primera verificación; no modifiques previamente el formato de entrada ONNX.

Extracto del registro de conversión verificado:

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

Confirma que se hayan generado los dos archivos de modelo:

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

En la conversión verificada, el archivo .rknn ocupaba aproximadamente 249 KB y el archivo .weight aproximadamente 5.1 MB. Ambos deben desplegarse juntos.

#4. Compilar, desplegar mediante SCP y ejecutar la aplicación

#4.1 Instalar un compilador cruzado ARM64 en el PC

Ejecutar en el PC:

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

Versión del compilador utilizada para la verificación:

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

GCC_COMPILER es el prefijo del compilador y no incluye el -gcc final; el script de compilación lo añade. La versión de CMake incluida con Ubuntu 20.04 cumple el requisito mínimo de CMake 3.15 de este ejemplo.

#4.2 Compilar la demo C++ de YOLOv6

Ejecutar en el PC:

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

Extracto del registro de compilación verificado:

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

El directorio de despliegue es:

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

El script de compilación copia el modelo convertido en el directorio de despliegue. Por tanto, el orden necesario es: primero convertir y después compilar y empaquetar.

#4.3 Copiar todo el directorio de despliegue mediante SCP

Ejecutar en el PC:

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/

Copia el directorio completo, no solo el ejecutable o el archivo .rknn. Esta guía utiliza un directorio de despliegue nuevo para evitar sobrescribir archivos de otros proyectos.

#4.4 Ejecutar en el host RK3588

Ejecutar en el host RK3588:

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

El 1 final es core_mask=0x01, que corresponde al core_num=1 de este modelo. sudo env ... permite acceder al nodo de dispositivo y pasa explícitamente la ruta de bibliotecas de la demo. Si solo ejecutas export LD_LIBRARY_PATH en el shell del usuario antes de usar sudo, la variable podría eliminarse.

Este comando utiliza las bibliotecas compartidas de Runtime del directorio de despliegue de Model Zoo. El firmware del host y el servicio de comunicación siguen procediendo del paquete M.2 instalado en la sección 1. Esta combinación exacta de versiones se verificó conjuntamente.

Extracto de una ejecución de inferencia real:

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

Estos valores son mediciones de una sola ejecución, no un resultado de FPS sostenido ni una prueba de rendimiento. El proceso es correcto si la aplicación termina con normalidad, muestra detecciones razonables y crea out.png.

#4.5 Recuperar la imagen resultante

Ejecutar en el PC:

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

Abre el resultado directamente en el escritorio de Ubuntu. Si el host RK3588 tiene una pantalla conectada, puedes ver allí la imagen sin copiarla de vuelta.

La siguiente imagen se generó durante la verificación:

#5. Solución de problemas de la primera ejecución

Recopila la información de diagnóstico en el host RK3588:

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. Versiones y referencias

Los repositorios están fijados a los siguientes commits para este entorno verificado:

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

La guía utiliza de forma coherente ~/RKNN3_Project como directorio de trabajo.

• Repositorio oficial de RKNN3: relaciones entre los componentes de software y paquetes de instalación.
• Toolkit Lite en la versión fijada: wheel ARM64, requisitos y ejemplos de Python.
• Runtime en la versión fijada: bibliotecas de Runtime y componentes de comunicación.
• Ejemplo YOLOv6 en la versión fijada: descarga, conversión y código fuente del ejemplo C++.
• Extensiones de Armbian y repositorio de paquetes de Seeed: repositorio de paquetes del fabricante para la placa utilizada en este ejemplo; las cabeceras del kernel deben coincidir con el kernel del sistema en ejecución.