RKLLM 设备端 LLM 推理

RKLLM 是瑞芯微提供的设备端 LLM 推理运行时，在 RK182X 上加载 RKNN 格式的大语言模型并执行推理。rkllm3-server 和 C API 推理 demo 都基于 RKLLM 运行时。

整体框图

应用进程
    ↓ OpenAI 兼容 API / C API
rkllm3-server / rknn3_llm_demo
    ↓
librknn3_api.so (RKNN3 运行时)
    ↓
rknn3_transfer_proxy (PCIe 代理)
    ↓
PCIe Gen3 x4 → RK1828 NPU

1. 实际组件

/usr/bin/ 可执行文件：

ls -lh /usr/bin/rkllm* /usr/bin/rknn3_* /usr/bin/rknn*

输出：

-rwxr-xr-x 1 root root 4.4M  8月19日 17:59 /usr/bin/rkllm3-server
-rwxr-xr-x 1 root root 1.1M  4月 9日 10:33 /usr/bin/rknn3_cnn_demo
-rwxr-xr-x 1 root root 921K  4月 9日 10:33 /usr/bin/rknn3_llm_demo
-rwxr-xr-x 1 root root  47K  4月 9日 10:33 /usr/bin/rknn3_model_test
-rwxr-xr-x 1 root root 735K  4月 9日 10:33 /usr/bin/rknn3_session_test
-rwxr-xr-x 1 root root 1.5K  4月 9日 10:33 /usr/bin/rknn3_startup
-rwxr-xr-x 1 root root 396K  8月19日 17:59 /usr/bin/rknn3_transfer_proxy
-rwxr-xr-x 1 root root  672  4月 9日 10:33 /usr/bin/rknn3_usb_startup.sh
-rwxr-xr-x 1 root root 1.8M  4月 9日 10:33 /usr/bin/rknn3_vlm_demo
-rwxr-xr-x 1 root root 6.0M  4月 9日 10:33 /usr/bin/rknn-console
-rwxr-xr-x 1 root root 6.2M  4月 9日 10:33 /usr/bin/rknn-smi

库文件和固件：

ls -lh /usr/lib/librknn*.so /lib/firmware/rknn3_rk1820.img

输出：

-rwxr-xr-x 1 root root 2.2M  8月19日 17:59 /lib/firmware/rknn3_rk1820.img
-rwxr-xr-x 1 root root 8.4M  8月19日 17:59 /usr/lib/librknn3_api.so
-rw-r--r-- 1 root root 7.4M  2025年 6月10日 /usr/lib/librknnrt.so
-rwxr-xr-x 1 root root 210K  8月19日 17:59 /usr/lib/librknnsmi.so

关键文件大小：

du -h /usr/bin/rkllm3-server /usr/lib/librknn3_api.so /lib/firmware/rknn3_rk1820.img

输出：

4.4M	/usr/bin/rkllm3-server
8.4M	/usr/lib/librknn3_api.so
2.2M	/lib/firmware/rknn3_rk1820.img

2. 安装

出厂已预装。手动安装方式：

# 文件已直接复制到 /usr/bin/ 和 /usr/lib/（没有 .deb 包）
sudo cp librknn*.so /usr/lib/
sudo cp rkllm3-server rknn3_* /usr/bin/
sudo cp rknn3_rk1820.img /lib/firmware/

3. NPU 状态查询

要查 NPU 状态用以下 4 种方法：

3.1 进程检查

ps aux | grep rknn3_transfer_proxy | grep -v grep

返回主进程 + 随机后缀进程两条记录，后缀 hash 每次启动随机生成，PID / CPU / 内存为动态字段——不要写死 ps -C rknn3_transfer_proxy_<hash> 查询。

3.2 服务检查

systemctl is-active rknn3.service

输出：

active

3.3 设备检查

ls -l /dev/pcie-rkep-*

输出：

crw------- 1 root root 10, 124  8月20日 16:56 /dev/pcie-rkep-0004:41:00.0

RK1828 PCIe 卡在板端有两个等价设备节点：
/dev/pcie-rkep-0004:41:00.0：PCIe EP（Endpoint）字符设备，由 PCIe 驱动创建
/dev/dri/renderD128：DRM 渲染节点，被 rknn3_transfer_proxy 用来与 NPU 通信
两者实际指向同一个 RK1828 PCIe 设备，任选其一即可。

3.4 PCIe BDF

lspci | grep -i 182a

输出：

0004:41:00.0 Processing accelerators: Rockchip Electronics Co., Ltd Device 182a (rev 01)

4. C API 函数清单

#include "rknn3_api.h"  // ← 头文件需向 Rockchip 索取

库文件类型：

file /usr/lib/librknn3_api.so

输出：

/usr/lib/librknn3_api.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (GNU/Linux), dynamically linked, BuildID[sha1]=c202427e4b11543df2fd52dcb1b8dea46e668946, stripped

函数	说明
`rknn3_init(&ctx, &ext)`	全局初始化（context 指针 + init_extend）
`rknn3_load_model_from_path(...)`	加载模型（3 参数：ctx, model, weight）
`rknn3_load_model_from_data(...)`	加载模型（内存数据）
`rknn3_model_init(ctx, &cfg)`	模型初始化（core_mask 经 `rknn3_config.run_core_mask` 传入）
`rknn3_run(...)`	CNN 推理（inputs/outputs 张量数组）
`rknn3_profile_mem(ctx)`	查看各 NPU 节点内存占用
`rknn3_session_destroy(...)`	session 销毁（LLM 专用）
`rknn3_session_run(...)`	LLM 同步推理（LLM 专用）
`rknn3_session_run_async(...)`	异步推理（LLM 专用）
`rknn3_session_clear_kvcache(...)`	清除 KV cache（LLM 专用）
`rknn3_session_enable_lora(...)`	启用 LoRA（LLM 专用）
`rknn3_session_disable_lora(...)`	关闭 LoRA（LLM 专用）
`rknn3_destroy(ctx)`	销毁 context

CNN 走 rknn3_run()，LLM 走 rknn3_session_*()，不要混用；实测签名以 SDK 内 rknn/rknn3-runtime/rknn3-api/include/rknn3_api.h 为准（实测可编译运行的 CNN 示例见 INT8 量化推理）。

5. OpenAI 兼容 API

端点	方法	说明
`/v1/models`	GET	列出模型
`/v1/chat/completions`	POST	对话推理
`--model2` 启动参数	—	多模态 VLM

启动命令：

rkllm3-server \
  -m /userdata/models/Qwen3-1.7B/Qwen3-1.7B.rknn \
  --weight /userdata/models/Qwen3-1.7B/Qwen3-1.7B.weight \
  --vocab /userdata/models/Qwen3-1.7B/Qwen3-1.7B.tokenizer.gguf \
  --embed /userdata/models/Qwen3-1.7B/Qwen3-1.7B.embed.bin \
  --embed-mmap \
  -a Qwen3-1.7B \
  --host 127.0.0.1 \
  --port 7878 \
  -c 0xff \
  -n 512

-c 实际按 NPU core mask 生效——Qwen3-1.7B 编译声明 8 核，须传 -c 0xff；传数值如 8192 会报 core_mask 8192 is not match with npu core number 8。上下文长度由模型编译时的 max_context_len 决定，详见 LLM 推理。

测试 API 端点：

curl -s http://127.0.0.1:7878/v1/models

输出：

{
  "object": "list",
  "data": [
    {
      "id": "Qwen3-1.7B",
      "object": "model",
      "created": 1787214642,
      "owned_by": "rknn",
      "meta": {
        "vocab_type": 2,
        "n_vocab": 151936,
        "n_ctx_train": -1,
        "n_embd": 2048,
        "n_params": 0,
        "size": 0
      }
    }
  ]
}

6. 常见问题

现象	原因	处理
`rknn-smi` 打印 usage 后退出	不支持 RK1828 PCIe	用 `ps` / `systemctl` / `lspci` 替代
找不到 `librknn3_api.so`	运行时 deb 没装	装 `rknn3-runtime` deb
`rknn3_init` 找不到头文件	没装 `rknn3_api.h`	向 Rockchip 索取
`core_mask 8192 is not match ...`	把上下文数值传给 `-c`	LLM 用 `-c 0xff`
`port 7878 already in use`	服务已起	`ss -tlnp \| grep 7878` 查占用
`/v1/models` 无响应	服务未启	后台跑启动命令

7. 下一步

INT8 量化推理 — 量化 + CNN 推理
MPP 多媒体框架 — 主控侧多媒体
NPU 概述 — NPU 硬件架构

8. 参考链接

RKNN3 Model Zoo
完整文档：SDK 内 docs/RK1820_RK1828_AI_Release-Note_CN.md