DeepSeek R1 部署至 RK3588：RKLLM 转换与 Web 访问

DeepSeek R1 部署至 RK3588

本文介绍在瑞芯微 RK3588 SoC 上部署 DeepSeek R1 7B 模型的完整流程，涵盖开发板驱动适配、模型转换、板端推理及局域网 Web 访问。

一、项目背景介绍

项目基于空闲的 Firefly 出厂搭载瑞芯微 RK3588 SoC 的 arm64 开发板。随着大模型趋势发展，瑞芯微已针对各开源 LLM/VLM 完成适配工作，按照开发手册要求即可完成模型部署。

RK3588 开发板

二、所需工具介绍

1. 硬件工具

1. X86 PC 虚拟机 Ubuntu20.04

PC 上安装 VMware 虚拟机，推荐 Ubuntu20.04，较为稳定。

2. 准备 NPU 驱动为 0.9.8 的 RK3588 开发板

需检查开发板的 NPU 驱动版本。输出命令：

sudo cat /sys/kernel/debug/rknpu/version

早期驱动（如 0.8.2）调用 CV 模型的 .so 没问题，但瑞芯微 LLM 需调用最新的 librkllm.so，对 NPU 驱动最低版本要求是 0.9.8。

升级 NPU 驱动的原因：

支持 RKLLM：早期驱动主要针对传统 CV 模型。LLM 引入 Transformer 算子、KV Cache 优化等特性，需要底层驱动 0.9.6+ 甚至 0.9.8+ 的指令集支持。
性能提升：新版驱动优化了内存管理和多核调度。
修复 Bug：修复旧版本在高负载下可能出现的 NPU 挂死或内存泄漏问题。

若驱动版本较低，需重新烧录固件（会清除数据）。以下是 Firefly RK3588 的烧录流程：

访问 Firefly 官网下载页，选中'固件'的'Ubuntu 固件'。
下载 Ubuntu22.04/SDesktop/kernel-6.1 文件节下的压缩包（如 ROC-RK3588S-PC_Ubuntu22.04-Xfce-r31161_v1.3.0b_250801.7z）。注意这是开发板固件，与虚拟机 Ubuntu 版本不同。
解压后找到 .img 镜像文件。
下载并安装 RKDevTool 烧写工具和 RK 驱动助手。
打开 RKDevTool，连接开发板电源和数据线。若未识别设备，按住 RECOVERY 键接电，等待显示 LOADER 设备。
点击'升级固件'，选择对应的 .img 文件进行烧录。
重启完成后，再次输入 sudo cat /sys/kernel/debug/rknpu/version 确认驱动已升级至 0.9.8。

2. 软件工具

Hugging Face: DeepSeek-R1-Distill-Qwen-7B。建议逐个下载 .safetensors 文件以防 git clone 崩溃。
RKNN-LLM-release: GitHub 仓库。选择最新 tag (v1.2.3)。
- doc: 官方指导手册。
- example: 提供纯文本对话、多模态视觉理解等 Demo。
- rkllm-toolkit (PC 端): Python 包，用于加载 HF 格式模型、量化并导出为 .rkllm 格式。
- rkllm-runtime (板端): C/C++ 推理库，核心动态库为 librkllmrt.so。

三、获取.safetensors 模型权重

从 Hugging Face 下载模型权重。大模型通常切分为多个文件（如 model-00001-of-000002.safetensors），类似压缩包的 Part1 和 Part2。

四、safetensors 转 RKLLM

1. 转换环境搭建

确保虚拟机或服务器内存充足，必要时通过 SWAP 扩充虚拟内存。将下载的 RKNN-LLM-release 项目和模型文件移动到 x86 系统环境中。创建 conda 环境：

conda create -n rkllm123 python=3.10

进入 rknn-llm-release-v1.2.3/rkllm-toolkit/packages 路径，安装工具包：

pip install rkllm_toolkit-1.2.3-cp310-cp310-linux_x86_64.whl

2. 模型转换

在目录下创建 export_model.py 和 generate_data.py。

generate_data.py (生成量化校准数据):

import json
from transformers import AutoTokenizer

model_path = '/xxx/RKNN-LLM/rkllm/DeepSeek-R1-Distill-Qwen-7B'
prompts = [
    "你好，请介绍一下你自己。",
    "Explain the theory of relativity in simple terms.",
    "写一首关于春天的七言绝句。",
    "Solve the equation: 2x + 5 = 15.",
    "瑞芯微 RK3588 芯片的主要特点是什么？",
    "What implies 'DeepSeek-R1'?",
    "将以下 JSON 字符串转换为 Python 字典：{'a': 1, 'b': 2}",
    "请帮我写一个 Python 脚本，实现快速排序算法。"
]
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
data_list = []
for prompt in prompts:
    messages = [{"role": "user", "content": prompt}]
    text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    data_list.append({"input": text, "target": """})
with open('data_quant.json', 'w', encoding='utf-8') as f:
    json.dump(data_list, f, ensure_ascii=False, indent=4)
print("量化数据已生成：data_quant.json")

export_model.py (执行转换):

from rkllm.api import RKLLM
import os

model_path = '/xxx/RKNN-LLM/rkllm/DeepSeek-R1-Distill-Qwen-7B'
platform = 'rk3588'
export_path = f'DeepSeek-R1-Distill-Qwen-7B_W8A8_{platform}.rkllm'

llm = RKLLM()
print(">>> Loading model...")
ret = llm.load_huggingface(
    model=model_path,
    device='cpu',
    dtype='float16'
)
if ret != 0:
    print("Model Load Failed!")
    exit(ret)

print(">>> Building model (Quantization W8A8)...")
dataset = './data_quant.json'
ret = llm.build(
    do_quantization=True,
    optimization_level=1,
    quantized_dtype='w8a8',
    quantized_algorithm='normal',
    target_platform=platform,
    num_npu_core=3,
    dataset=dataset
)
if ret != 0:
    print("Model Build Failed!")
    exit(ret)

print(f">>> Exporting model to {export_path}...")
ret = llm.export_rkllm(export_path)
if ret != 0:
    print("Model Export Failed!")
    exit(ret)
print("\n\n转换成功！请将 .rkllm 文件推送到板端进行测试。")

先运行 generate_data.py 生成 data_quant.json，再运行 export_model.py。

五、RKLLM 模型板端部署及推理

将生成的 .rkllm 模型复制到开发板路径下（例如 /home/firefly/rkllm_model_zoo_selfconvert/DeepSeek-R1-Distill-Qwen-7B_W8A8_rk3588.rkllm）。

进入 rknn-llm-release-v1.2.3/examples/rkllm_api_demo/deploy 路径。

1. 修改 llm_demo.cpp

适配 DeepSeek-R1 / Qwen 的 ChatML 模板：

// 【修改开始】适配 DeepSeek-R1 / Qwen 的 ChatML 模板
// 参数顺序：handle, system_prompt, user_prefix, assistant_prefix
rkllm_set_chat_template(llmHandle,"<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n","<|im_start|>user\n","<|im_end|>\n<|im_start|>assistant\n");
// 【修改结束】

2. 修改编译脚本 build-linux.sh

确保编译器设置正确：

#!/bin/bash
set -e
if [[ -z ${BUILD_TYPE} ]]; then
    BUILD_TYPE=Release
fi
# 在板端本地编译，直接使用简写，系统会自动在 /usr/bin 下找到它们
C_COMPILER=gcc
CXX_COMPILER=g++
TARGET_ARCH=aarch64
TARGET_PLATFORM=linux
# ... (其余配置保持不变)

3. 设置环境变量

export LD_LIBRARY_PATH=~/rknn-llm-release-v1.2.3/rkllm-runtime/Linux/librkllm_api/aarch64/lib:$LD_LIBRARY_PATH

4. 运行模型

cd /xxx/rknn-llm-release-v1.2.3/examples/rkllm_api_demo/deploy/install/demo_Linux_aarch64
./llm_demo <模型路径> <最大生成长度> <上下文长度>
# 示例
./llm_demo /home/firefly/models/DeepSeek-R1-Distill-Qwen-7B_W8A8_rk3588.rkllm 512 2048

此时终端应显示 user: 提示符。

六、集成开源 gradio 工具实现 web 访问

根据《Rockchip RKLLM SDK User Guide V1.2.3》手册，官方提供了 Gradio 网页端部署方案。

以下操作均在开发板上执行：

安装 Gradio：
```
pip3 install gradio
```

进入服务目录：

cd ~/rknn-llm-release-v1.2.3/examples/rkllm_server_demo/rkllm_server

复制依赖库：

cp ~/rknn-llm-release-v1.2.3/rkllm-runtime/Linux/librkllm_api/aarch64/librkllmrt.so ./lib/

修改 gradio_server.py：确保 chatRKLLM.launch() 函数中设置 server_name="0.0.0.0" 以允许局域网访问。
```
chatRKLLM.launch(server_name="0.0.0.0", server_port=8080)
```

启动服务：

python3 gradio_server.py --model_path /home/firefly/rkllm_model_zoo_selfconvert/DeepSeek-R1-Distill-Qwen-7B_W8A8_rk3588.rkllm --target_platform rk3588

在局域网内通过 http://<开发板 IP>:8080 即可访问 Web 界面进行对话测试。

DeepSeek R1 部署至 RK3588：RKLLM 转换与 Web 访问