RK1828芯片LLM模型部署与全流程调试手册

RK1828 调试 LLM 核心是：PC 用 RKLLM-Toolkit 转模型→板端 NPU 环境校验→日志 / 性能 / 参数分层调试→解决 OOM / 乱序 / 驱动问题，全程基于RKNN3+RKLLM栈。

一、环境准备（PC + 板端）

1. PC 端（Ubuntu 20.04/22.04，x86_64）

# 1. 克隆RKNN-LLM仓库

git clone -b release-v1.2.3 https://github.com/airockchip/rknn-llm.git

cd rknn-llm

# 2. 创建Python虚拟环境（推荐3.8/3.12）

conda create -n rkllm python=3.8

conda activate rkllm

# 3. 安装RKLLM-Toolkit

cd rkllm-toolkit/packages

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

# 4. 验证安装

python -c "from rkllm.api import RKLLM; print('OK')"

2. 板端（RK1828，M.2 协处理器）

固件要求：RKNPU3 驱动≥v0.9.8

# 查看驱动版本

cat /sys/kernel/debug/rknpu/version

# 输出：RKNPU driver: v0.9.8+

# 查看NPU服务状态

systemctl status rknn3

# 正常：active (running)

# 查看设备信息

rknn-smi info

二、模型转换（PC 端，核心步骤）

支持 Hugging Face（Qwen2.5/3、DeepSeek、MiniCPM 等）→ .rkllm格式，W4A16 量化（平衡速度 / 精度）。

1. 下载模型（以 Qwen2.5-1.5B-Instruct 为例）

# 用huggingface-cli下载

huggingface-cli download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./qwen2.5-1.5b

2. 转换脚本（export\[_rkllm.py](_rkllm.py)）

from rkllm.api import RKLLM

# 1. 初始化RKLLM

rkllm = RKLLM()

# 2. 加载Hugging Face模型

model_path = "./qwen2.5-1.5b"

rkllm.load_huggingface_model(

    model_path=model_path,

    model_type="qwen2",  # 模型类型：qwen2/deepseek/minicpm

    device="cpu"

)

# 3. 量化与转换（关键参数）

rkllm.export_rkllm(

    output_path="./qwen2.5-1.5b-rk1828.rkllm",

    target_platform="rk1828",  # 必须指定rk1828

    quantized_dtype="W4A16",   # 4bit权重量化，16bit激活

    optimization_level=2,       # 优化等级0-3，越高越快

    num_npu_core=1              # RK1828为单NPU核心

)

3. 执行转换

python export_rkllm.py

# 成功：生成 qwen2.5-1.5b-rk1828.rkllm（约8GB）

三、板端部署与基础调试

1. 推送模型与程序到板端

# PC→板端（adb或scp）

adb push qwen2.5-1.5b-rk1828.rkllm /data/

adb push rknn-llm/examples/llm_demo/deploy/demo_Linux_aarch64 /data/

2. 运行推理（C++ demo，板端）

cd /data

# 启动推理（指定模型路径+上下文长度）

./demo_Linux_aarch64 --model qwen2.5-1.5b-rk1828.rkllm --ctx-size 1024

3. 基础调试（串口 + 日志）

串口配置：波特率 1500000，8N1（TX→RX，RX→TX）

开启详细日志：

# 板端设置日志级别（0=无，1=性能，2=详细）

export RKLLM_LOG_LEVEL=1

./demo_Linux_aarch64 ...

# 日志包含：NPU利用率、内存占用、token生成速度

四、分层调试（日志→性能→参数→模型）

1. 日志级调试（定位报错）

常见报错 1：ctx-size 超限

The value of '--ctx-size'(16384) is greater than the model's max_context_len(1024)

解决：--ctx-size 1024（与模型 config.json 一致）

常见报错 2：OOM（内存溢出）

解决：

改用W4A16 量化（模型体积减半）

降低上下文长度：--ctx-size 512

关闭板端后台进程：systemctl stop ...

常见报错 3：model version mismatch

解决：PC 端 Toolkit 与板端 Runtime版本一致（如 v1.2.3），重新转换模型

2. 性能调试（速度 / 利用率）

监控工具（板端）：

# CPU利用率

bash rknn-llm/scripts/eval_perf_watch_cpu.sh

# NPU利用率（关键！正常≥90%）

bash rknn-llm/scripts/eval_perf_watch_npu.sh

性能指标（合格线）：

token 生成速度：≥10 token/s（1.5B 模型）

首 token 延迟：≤2s

NPU 利用率：≥90%（否则驱动 / 模型未加载到 NPU）

3. 参数调试（输出质量）

核心参数（启动时设置）：

./demo_Linux_aarch64 \

  --model xxx.rkllm \

  --ctx-size 1024 \

  --temperature 0.7 \  # 随机性：0=固定，1=随机

  --max-tokens 512 \   # 最大生成长度

  --top-p 0.9           # 核采样

输出乱 / 幻觉：

改用W8A8 量化（精度更高）

提升optimization_level=3

检查 prompt 格式（需符合模型训练格式，如 Qwen 用<|im_start|>user\n...<|im_end|>）

4. 模型级调试（转换失败 / 架构不支持）

检查支持列表：RKLLM 支持Qwen2/3、DeepSeek、MiniCPM、GLM-Edge等

自定义模型：需适配 RKLLM 算子，修改modeling_xxx.py，避免不支持的算子（如动态 shape）

五、高级调试（Python API + 服务化）

1. Python API 调试（灵活控制）

from rkllm.api import RKLLM

# 初始化

rkllm = RKLLM()

# 加载模型

rkllm.load_model("./qwen2.5-1.5b-rk1828.rkllm")

# 推理（流式输出）

def callback(text):

    print(text, end="", flush=True)

rkllm.generate("你好，介绍一下自己", callback=callback)

2. 服务化调试（rkllm3-server）

# 板端启动服务

rkllm3-server --model xxx.rkllm --ctx-size 1024 --port 8080

# PC端测试

curl http://192.168.1.100:8080/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{"model":"rkllm","messages":[{"role":"user","content":"你好"}],"temperature":0.7}'

六、避坑总结

1. 驱动版本必须≥v0.9.8，否则 NPU 无法识别模型

2. 量化优先 W4A16，平衡速度与精度；OOM 时降 ctx-size

3. 日志级别设为 1，监控 NPU 利用率与内存占用

4. 模型转换必须指定 target_platform=rk1828

家具维修培训