RKNN3 Toolkit 安装与使用

RKNN3 Toolkit 是 RKNN3 SDK 的 PC 端模型转换工具。

整体框图

PC 端 (x86_64 + Python 3.10/3.12)        板端 (aarch64 + Python 3.11)
┌──────────────────────────┐             ┌──────────────────────────┐
│ rknn3_toolkit-*.whl      │             │ rknn3_toolkit_lite-*.whl │
│ from rknn.api import RKNN│  ────→      │ from rknn3lite.api       │
│ config / build / export  │   scp/adb   │ load_rknn + inference    │
└──────────────────────────┘             └──────────────────────────┘

如仅需运行官方预转换模型，可跳过本章，直接参考应用开发相关章节。

• Python 模块名是 rknn，板端 Lite 是 rknn3lite
• SDK 内 whl 版本 1.0.0
• 板端均为 aarch64 架构（包括 RK3588 等宿主设备），无法安装 PC 端 x86_64 的 whl

1. SDK 自带的 whl

find /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit -name "*.whl"

输出：

.../rknn3-toolkit/packages/rknn3_toolkit-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.../rknn3-toolkit/packages/rknn3_toolkit-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.../rknn3-toolkit-lite/packages/rknn3_toolkit_lite-1.0.0-cp39-cp39-linux_aarch64.whl
.../rknn3-toolkit-lite/packages/rknn3_toolkit_lite-1.0.0-cp311-cp311-linux_aarch64.whl
.../rknn3-toolkit-lite/packages/rknn3_toolkit_lite-1.0.0-cp310-cp310-linux_aarch64.whl
.../rknn3-toolkit-lite/packages/rknn3_toolkit_lite-1.0.0-cp312-cp312-linux_aarch64.whl
.../rknn3-toolkit/docker/docker_file/ubuntu_22_04_cp310/rknn3_toolkit-0.5.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

最后一行是 docker/docker_file/ubuntu_22_04_cp310/ 下的 0.5.0 旧版 whl（老版本 SDK 自带 docker 镜像用），安装时不要误用；正常安装用 packages/ 下的 1.0.0。

目录结构：

ls -la /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/

输出：

CHANGELOG.md
doc
.git
LICENSE
README_EN.md
README.md
res
rknn3-toolkit
rknn3-toolkit-lite

包名对照：

用途	包名	版本	模块名	架构
PC 端转换	rknn3-toolkit	1.0.0（whl）	rknn	x86_64
板端推理	rknn3-toolkit-lite	1.0.0	rknn3lite	aarch64

PC 端 toolkit 大小：

ls -lh /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit/packages/*.whl

输出：

-rw-r--r-- 1 linaro linaro 181M  2026年 1月28日 rknn3_toolkit-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
-rw-r--r-- 1 linaro linaro 179M  2026年 1月28日 rknn3_toolkit-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

板端 lite 大小：

ls -lh /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit-lite/packages/*.whl | head -4

输出：

-rw-r--r-- 1 linaro linaro 303K  2026年 1月28日 rknn3_toolkit_lite-1.0.0-cp310-cp310-linux_aarch64.whl
-rw-r--r-- 1 linaro linaro 302K  2026年 1月28日 rknn3_toolkit_lite-1.0.0-cp311-cp311-linux_aarch64.whl
-rw-r--r-- 1 linaro linaro 274K  2026年 1月28日 rknn3_toolkit_lite-1.0.0-cp312-cp312-linux_aarch64.whl
-rw-r--r-- 1 linaro linaro 303K  2026年 1月28日 rknn3_toolkit_lite-1.0.0-cp39-cp39-linux_aarch64.whl

2. 安装

以下为 PC 端操作，当前设备为 aarch64 架构，无法执行。

当前环境：

python3 --version

输出：

Python 3.11.2

uname -m

输出：

aarch64

2.1 PC 端安装（x86_64 + Python 3.10/3.12）

# PC 端（从 SDK 内 whl）
pip install /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit/packages/rknn3_toolkit-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

# 验证
python -c "from rknn.api import RKNN; print('OK')"

2.2 板端（已装）

pip3 list | grep rknn

输出：

rknn3-toolkit-lite           1.0.0

3. LLM 模型转换

以下为 PC 端操作，需要 NVIDIA GPU 和 CUDA 环境（GRQ 量化）。

from rknn.api import RKNN
import os

os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com/'

rknn = RKNN(verbose=True)

# 第一步：ONNX 导出 + GRQ 量化（仍需 CMMLU 数据集）
# 通过 model-zoo 的 export_llm.py 完成
os.system('python examples/Qwen3/python/export_llm.py --quant --model_path Qwen/Qwen3-1.7B')

# 第二步：转 RKNN
rknn.config(target_platform='rk1820',
            quantized_dtype='w4a16',
            quantized_algorithm='grq',
            quantized_method='group32')

rknn.load_llm(model='Qwen3-1.7B.onnx', config='Qwen3-1.7B.config.pkl')
rknn.build(do_quantization=True, dataset='dataset.txt')
rknn.export_rknn('./Qwen3-1.7B.rknn')

4. CNN 模型转换

from rknn.api import RKNN

rknn = RKNN(verbose=True)

rknn.config(target_platform='rk1820',
            mean_values=[[0, 0, 0]],
            std_values=[[255, 255, 255]])

rknn.load_onnx(model='./mobilenet_v2.onnx')
rknn.build(do_quantization=True, dataset='./dataset.txt')
rknn.export_rknn('./mobilenet_v2.rknn')

5. 关键参数

参数	取值	说明
target_platform	'rk1820'	目标平台（不是 'rk1828'）
quantized_dtype	'w4a16'	量化数据类型
quantized_algorithm	'grq' / 'mmse'	量化算法
quantized_method	'group32' / 'channel'	量化粒度
max_context_len	在 export_llm.py 第一步设置	LLM 上下文长度

6. 环境要求

项	PC 端要求	板端要求
Python	3.10 / 3.12（不支持 3.11）	3.9 / 3.10 / 3.11 / 3.12
OS	Linux x86_64（whl 仅 Linux）	Linux aarch64
GPU	NVIDIA（CUDA 11.8+）— 仅 GRQ 量化需要	不需要
普通 load / build	CPU 即可	CPU 即可

7. LLM 转换产出

实际板端已部署的 Qwen3-1.7B：

ls /userdata/models/Qwen3-1.7B/ | grep -E "\.(onnx|pkl|rknn|weight|gguf|bin)$"

输出：

Qwen3-1.7B.embed.bin
Qwen3-1.7B.rknn
Qwen3-1.7B.tokenizer.gguf
Qwen3-1.7B.weight

总大小：

du -sh /userdata/models/Qwen3-1.7B/

输出：

1.7G	/userdata/models/Qwen3-1.7B/

转换文件说明：

Qwen3-1.7B.onnx            # ❌ 第一步：ONNX（中间文件，转换完成后删除）
Qwen3-1.7B.config.pkl      # ❌ 转换配置（中间文件，转换完成后删除）
Qwen3-1.7B.rknn            # ✅ RKNN 模型结构（24 MB）
Qwen3-1.7B.weight          # ✅ RKNN 模型权重（1.1 GB）
Qwen3-1.7B.tokenizer.gguf  # ✅ 分词器（5.7 MB）
Qwen3-1.7B.embed.bin       # ✅ 嵌入表（594 MB）

中间文件（onnx、pkl）仅在 PC 端转换过程中存在，最终部署时只需要最终的 4 个文件。

8. 常见问题

现象	原因	处理
Python 3.11 装不上 Toolkit	仅支持 3.10 / 3.12	装 Python 3.10 或 3.12
rknn-toolkit3 PyPI 找不到	仅 SDK / GitHub 分发	用 SDK 内 whl
GRQ 量化报缺 dataset	没下数据集	准备 CMMLU/dataset.json
误装 docker 0.5.0 whl	路径选错	用 packages/ 下 1.0.0
target_platform 报错	写成 'rk1828'	改成 'rk1820'
板端 Lite 装不上	pip / whl 不匹配	用 cp311 版

9. 下一步

• 模型转换 — PC 端实战
• NPU 概述 — NPU 架构
• RKNN3 SDK 概述 — SDK 总览

10. 参考链接

• RKNN3 Model Zoo（转换示例）
• RKNN-Toolkit2
• 完整文档：SDK 内 docs/RK1820_RK1828_AI_Release-Note_CN.md