Cómo ejecutar modelos LLM en RK3588

Convierte DeepSeek-R1-Distill-Qwen-1.5B a RKLLM en un PC Ubuntu x86_64, despliégalo en RK3588 mediante SSH/SCP y ejecuta el ejemplo oficial de C++.

Inicio rápido: ejecutar modelos LLM en RK3588

ElementoEntorno utilizado en esta verificación
PCUbuntu 20.04.6 LTS, x86_64, Python 3.11, NVIDIA GTX 1070 8 GB
PlacareComputer RK3588, Debian 12 / Armbian 26.08.0-trunk
Kernel de la placa6.1.115-vendor-seeed-rk3588
Controlador RKNPUv0.9.8
SDKRKLLM-Toolkit / Runtime 1.3.0, commit del repositorio 878f936
Cuenta y dirección de ejemploBOARD_USER@BOARD_IP

Ejecutar en la terminal local de la placa:

bash
sudo apt update
sudo apt install -y openssh-server git
sudo systemctl enable --now ssh

Ejecutar en el PC:

bash
sudo apt update
sudo apt install -y git wget openssh-client
ssh BOARD_USER@BOARD_IP

#1. Resolver la ausencia del controlador RKNPU

Ejecutar en la placa:

bash
uname -m
uname -r
mountpoint -q /sys/kernel/debug || sudo mount -t debugfs debugfs /sys/kernel/debug
sudo cat /sys/kernel/debug/rknpu/version
sudo cat /sys/kernel/debug/rknpu/load
grep "^CONFIG_ROCKCHIP_RKNPU=" /boot/config-$(uname -r)
sudo dmesg | grep -i rknpu | tail -n 20
for node in /sys/class/drm/renderD*; do
  printf '%s -> ' "$node"
  readlink -f "$node/device/driver"
done

Extracto de la salida real de la placa:

text
RKNPU driver: v0.9.8
NPU load:  Core0:  0%, Core1:  0%, Core2:  0%
/sys/class/drm/renderD130 -> /sys/bus/platform/drivers/RKNPU
CONFIG_ROCKCHIP_RKNPU=y

renderD130 es el nodo de esta placa, no un número fijo. El SDK 1.3.0 requiere un controlador v0.9.8 o posterior; CONFIG_ROCKCHIP_RKNPU=y indica que está integrado en el kernel, por lo que es normal que no aparezca en lsmod. Si falta el archivo de versión, comprueba también dmesg y la asociación del controlador.

En el sistema Debian Seeed/Armbian de reComputer RK3588 utilizado aquí, inspecciona primero los paquetes correspondientes del kernel y del árbol de dispositivos:

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

Después de confirmar que las versiones candidatas de ambos paquetes proceden del repositorio de esta placa, instala o reinstala los paquetes adecuados si el controlador falta o es anterior a 0.9.8:

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

#2. Instalar y verificar RKLLM Runtime y RKLLM-Toolkit

ComponenteDónde se instalaFunción
Controlador del kernel RKNPUKernel de la placaAcceder al hardware NPU
RKLLM Runtime librkllmrt.soPlaca aarch64Cargar .rkllm y ofrecer una API de inferencia C/C++
RKLLM-Toolkit rkllm_toolkitPC Ubuntu x86_64Convertir, cuantizar y exportar .rkllm

#2.1 Obtener la misma versión del SDK en ambos equipos

Ejecutar en el PC:

bash
mkdir -p ~/RKLLM_Project
cd ~/RKLLM_Project
git clone --branch release-v1.3.0 --depth 1 https://github.com/airockchip/rknn-llm.git

Ejecutar en la placa: Este ejemplo obtiene solo los archivos necesarios para compilar y ejecutar, a fin de ahorrar espacio en la placa.

bash
mkdir -p ~/RKLLM_Project
cd ~/RKLLM_Project
git clone --filter=blob:none --sparse --depth 1 --branch release-v1.3.0 \
  https://github.com/airockchip/rknn-llm.git
cd rknn-llm
git sparse-checkout set examples/rkllm_api_demo/deploy rkllm-runtime/Linux

#2.2 Verificar Runtime en la placa

Ejecutar en la placa:

bash
cd ~/RKLLM_Project/rknn-llm
file rkllm-runtime/Linux/librkllm_api/aarch64/librkllmrt.so
ldd rkllm-runtime/Linux/librkllm_api/aarch64/librkllmrt.so

file debe indicar AArch64 ELF y ldd no debe mostrar not found. Runtime no necesita pip install. Al compilar el ejemplo en la sección 4, CMake copia la versión correspondiente de librkllmrt.so al directorio de despliegue lib/; configura LD_LIBRARY_PATH antes de ejecutar. En esta placa, ldd encontró dependencias como libgomp.so.1. Si aparece not found, instala primero las bibliotecas que falten en la placa.

#2.3 Instalar Toolkit en el PC

El ejemplo siguiente usa Ubuntu x86_64 y Python 3.11 en un entorno Conda aislado. Si ya tienes Miniforge, empieza por la línea source.

Ejecutar en el PC:

bash
cd ~/RKLLM_Project
wget -O Miniforge3-Linux-x86_64.sh \
  https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh -b -p "$HOME/miniforge3"
source "$HOME/miniforge3/etc/profile.d/conda.sh"
conda create -n rkllm-1.3.0 python=3.11 -y
conda activate rkllm-1.3.0
python -m pip install --upgrade pip
python -m pip install ./rknn-llm/rkllm-toolkit/packages/rkllm_toolkit-1.3.0-cp311-cp311-linux_x86_64.whl
python -m pip install huggingface_hub
python -m pip check
python -c 'from rkllm.api import RKLLM; print("RKLLM-Toolkit import OK")'
nvidia-smi --query-gpu=name,memory.total --format=csv,noheader
python -c 'import torch; print("CUDA available:", torch.cuda.is_available())'

En el nombre del wheel, cp311 indica Python 3.11 y linux_x86_64 indica la arquitectura del PC; no instales este wheel en la placa. Esta prueba utilizó ~/miniconda3 ya instalado y obtuvo No broken requirements found., RKLLM-Toolkit import OK y CUDA available: True. Los comandos de instalación nueva de arriba usan Miniforge. La sección 3 también requiere que el controlador NVIDIA funcione en el PC.

#3. Convertir el modelo LLM en un PC Ubuntu

#3.1 Descargar el modelo original

Ejecutar en el PC:

bash
source "$HOME/miniforge3/etc/profile.d/conda.sh"
conda activate rkllm-1.3.0
mkdir -p ~/RKLLM_Project/models
hf download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
  config.json tokenizer.json tokenizer_config.json generation_config.json model.safetensors \
  --local-dir ~/RKLLM_Project/models/DeepSeek-R1-Distill-Qwen-1.5B
ls -lh ~/RKLLM_Project/models/DeepSeek-R1-Distill-Qwen-1.5B/model.safetensors

Se descarga el modelo original de Hugging Face, que no puede entregarse directamente al Runtime de la placa. La conversión usa data_quant.json del directorio del ejemplo oficial como conjunto de calibración de demostración; en producción, sustitúyelo por preguntas y respuestas representativas de los casos de uso.

#3.2 Generar el modelo para RK3588

Ejecutar en el PC: Esta prueba usó un entorno CUDA con NVIDIA GTX 1070. Crea el script de conversión con los siguientes parámetros.

bash
cat > ~/RKLLM_Project/convert_rk3588.py <<'PY'
from pathlib import Path
from rkllm.api import RKLLM

root = Path.home() / 'RKLLM_Project'
model = root / 'models/DeepSeek-R1-Distill-Qwen-1.5B'
dataset = root / 'rknn-llm/examples/rkllm_api_demo/export/data_quant.json'
output = root / 'models/DeepSeek-R1-Distill-Qwen-1.5B_W8A8_rk3588.rkllm'

llm = RKLLM()
ret = llm.load_huggingface(model=str(model), model_lora=None,
                           device='cuda', dtype='float16',
                           custom_config=None, load_weight=True)
if ret != 0:
    raise RuntimeError(f'load_huggingface failed: {ret}')
ret = llm.build(do_quantization=True, optimization_level=1,
                quantized_dtype='W8A8', quantized_algorithm='normal',
                target_platform='RK3588', num_npu_core=3,
                extra_qparams=None, dataset=str(dataset),
                hybrid_rate=0, max_context=4096)
if ret != 0:
    raise RuntimeError(f'build failed: {ret}')
ret = llm.export_rkllm(str(output))
if ret != 0:
    raise RuntimeError(f'export_rkllm failed: {ret}')
print(output)
PY
python ~/RKLLM_Project/convert_rk3588.py
ls -lh ~/RKLLM_Project/models/DeepSeek-R1-Distill-Qwen-1.5B_W8A8_rk3588.rkllm

RK3588 utiliza cuantización W8A8, algoritmo normal y 3 núcleos NPU; es la combinación del ejemplo oficial. max_context=4096 coincide con el argumento de ejecución posterior. La conversión en PC tuvo éxito y produjo un modelo W8A8 de unos 2.0 GB. Coloca el archivo en la placa RK3588 correspondiente.

#4. Desplegar y ejecutar el ejemplo C++ en la placa

#4.1 Compilar el llm_demo oficial en la placa

Ejecutar en la placa: Usa el compilador aarch64 nativo de la placa en vez de la ruta de compilación cruzada del PC fijada en el build-linux.sh oficial.

bash
sudo apt update
sudo apt install -y cmake g++ make
cd ~/RKLLM_Project/rknn-llm
cmake -S examples/rkllm_api_demo/deploy \
  -B examples/rkllm_api_demo/deploy/build/native \
  -DCMAKE_BUILD_TYPE=Release
cmake --build examples/rkllm_api_demo/deploy/build/native -j2
cmake --install examples/rkllm_api_demo/deploy/build/native
ls -lh examples/rkllm_api_demo/deploy/install/demo_Linux_aarch64/llm_demo \
  examples/rkllm_api_demo/deploy/install/demo_Linux_aarch64/lib/librkllmrt.so

#4.2 Transferir y ejecutar el modelo

Ejecutar en el PC:

bash
scp ~/RKLLM_Project/models/DeepSeek-R1-Distill-Qwen-1.5B_W8A8_rk3588.rkllm \
  BOARD_USER@BOARD_IP:~/RKLLM_Project/rknn-llm/examples/rkllm_api_demo/deploy/install/demo_Linux_aarch64/
sha256sum ~/RKLLM_Project/models/DeepSeek-R1-Distill-Qwen-1.5B_W8A8_rk3588.rkllm
ssh BOARD_USER@BOARD_IP

Ejecutar en la placa:

bash
cd ~/RKLLM_Project/rknn-llm/examples/rkllm_api_demo/deploy/install/demo_Linux_aarch64
sha256sum ./DeepSeek-R1-Distill-Qwen-1.5B_W8A8_rk3588.rkllm
export LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
ldd ./llm_demo | grep -E 'librkllmrt|not found'
export RKLLM_LOG_LEVEL=1
./llm_demo ./DeepSeek-R1-Distill-Qwen-1.5B_W8A8_rk3588.rkllm 128 4096

Los valores SHA-256 del PC y la placa deben coincidir; en esta prueba ambos fueron 95fb13cf8287c2fa0e6338c550b0ceeea9eb2dfe752c55a2d0b519035bff78ee. En el indicador user:, introduce 1+1等于多少？请只回答数字。. Extracto de la salida real de RK3588:

text
rkllm init start
I rkllm: rkllm-runtime version: 1.3.0, rknpu driver version: 0.9.8, platform: RK3588
I rkllm: rkllm-toolkit version: 1.3.0, max_context_limit: 4096, npu_core_num: 3, target_platform: RK3588, model_dtype: W8A8
rkllm init success
...
因此，**1 + 1 等于** \(\boxed{2}\)。

La respuesta exacta del modelo puede variar. 128 es el número máximo de tokens generados en esta ejecución y 4096 es el límite de contexto; escribe exit para salir.

Si ldd muestra not found, corrige primero la biblioteca compartida que falte. Si falla la inicialización, revisa la versión del controlador, la integridad del modelo, los parámetros de plataforma y las versiones de Toolkit/Runtime. Los archivos .rkllm de RK3576 y RK3588 no son intercambiables.

#Referencias