轻量级LLM模型QWen2.5-0.5B在RK3588上的适配流程记录

date

Mar 16, 2026

slug

2026-03-16-the-Qwen2.5-0.5B-model-deployment-on-RK3588

status

Published

category

AI summary

本文详细学习和总结基于瑞芯微的RKLLM工具及其官方的相关指导文档，把轻量级大语言模型Qwen2.5-0.5B适配到RK3588上的完整过程及其注意事项记录。

总体而言，在瑞芯微NPU上部署 LLM 和部署 YOLO 的核心逻辑与流程是一致的，都是：PC端转换模型 -> 推送模型和库到板端 -> 调用 API 运行。 但是，对于大语言模型的适配而言，不再使用 RKNN-Toolkit2 工具链，而是使用专门为大语言模型优化的 RKLLM-Toolkit 工具链。

RKNN-Toolkit2: 处理卷积神经网络（CNN）和简单的 Transformer（Vision Transformer）。

RKLLM-Toolkit: 专门处理大语言模型，支持权重量化（W4A16/W8A8）和 KV Cache 优化。

下图是瑞芯微RKLLM Toolkit及其软硬应用生态的框架图，与RKNN类似：

RKLLM-Toolkit：用于在PC上进行模型转换和量化。

RKLLM Runtime：为瑞芯微NPU平台提供C/C++编程接口，帮助用户在NPU上部署RKLLM模型，加速LLM应用的运行。

RKNPU内核驱动：负责与NPU硬件交互，可以在Rockchip的内核代码中找到。

环境搭建

从rkllm的Github仓库（airockchip/rknn-llm）上下载rkllm代码。

PC端环境

创建一个独立的rkllm环境，并进入rknn-llm仓库代码中的rkllm-toolkit/packages目录下，安装rkllm-toolkit及其依赖包：

板端环境

对于LLM大模型在瑞芯微NPU上的运行，在板端主要需要NPU驱动以及librkllmrt.so链接库（在rkllm-runtime/Linux/librkllm_api/aarch64下）的支持。

NPU驱动要求在v0.9.8版本以上，可以通过以下命令检查自己板端的驱动是否符合要求，否则就需要重新编译内核：

下载模型文件并在PC上推理测试

使用transformers从Huggingface上下载Qwen2.5-0.5B模型的模型文件，并在PC本机上执行推理测试，验证下载文件的正确性：

HuggingFace下载速度慢的问题可以通过设置国内镜像来解决，在执行以上下载脚本之前设置环境变量：

下载后的模型文件列表如下图所示：

模型转换

基于环境搭建部分安装的rkllm-toolkit包，调用以下代码完成模型的转换：

注意：在量化类型的支持上，RK3588不支持w4a16，可支持w8a8, w8a8_g128, w8a8_g256, w8a8_g512这四种。

以上模型转换结束后会在当前目录下生成一个qwen2_5_0_5b_w8a8.rkllm文件，大小800M的样子。

板端编译与推理

以上的板端模型转换完成以后，接下来就是准备板端的推理代码：

对于板端推理代码的交叉编译，可以按照常规的开发方法，在PC上编译好以后上传到板子上执行。但是我使用的1.2.3版本的RKLLM-Toolkit，在文档中明确推荐的交叉编译工具版本是GCC10.2，而我PC上的瑞芯微平台的编译工具链是gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu。所幸我用的瑞芯微RK3588板子上运行的Debian系统有满足条件的编译工具：

所以这样就比较简单了，可以直接把板端推理代码的源文件（main.cpp）、头文件（rkllm.h）、链接库（librkllmrt.so）以及前面转换好的板端模型上传到板子上，直接在板子的debian系统中使用g++进行编译：

执行后的打印信息如下：

可以看到，这个模型在RK3588上已经跑起来了。但是0.5B规模的大语言模型所生成的内容还是存在比较大的问题，不仅轻松的解决了西咸一体化这个困扰西安发展30年的痼疾，而且明显把榆林的资料张冠李戴到了咸阳头上。

推理过程中的内存占用上，这个模型只用到了680MB的内存，而实际上光是板端转换后的模型文件就已经800MB了，这就说明瑞芯微RKLLM在执行时并没有把完整的模型文件全部加载到内存中，而是按需加载，这样的话对于嵌入式设备这类内存非常紧张的应用还是非常实用的。

参考资料

airockchip/rknn-llm

RKLLM SDK User Guide v1.2.3