最近在用 RK1828 做端侧 AI 部署，重点折腾了 RKNN3 Toolkit 这个 PC 端模型转换工具。从环境配置到 LLM/CNN 模型转换都跑了一遍，整理了一些踩坑经验和关键参数说明，分享给同样在折腾这块的同学。
（本文基于 V1.0.4 测试，不同版本 API 可能有差异，具体以为准。）
一、环境要求
先说环境，这块卡住的人应该不在少数：
| 项目 | 要求 |
|---|---|
| Python | 3.10 或 3.12 |
| 操作系统 | Linux / Windows（V1.0.4 起支持 Windows） |
| GPU | 建议有 NVIDIA GPU，加速模型加载和量化 |
| CUDA | 11.8+（推荐） |
特别注意：Python 只支持 3.10 和 3.12，不支持 3.11！ 别手欠装 3.11，装完 pip install 直接报错。
二、安装
去 下载对应系统的 whl 文件，然后 pip 装就行：
# Linux
pip install rknn3_toolkit-1.0.4-cp310-cp310-manylinux_4_64_x86_64.whl
# Windows
pip install rknn3_toolkit-1.0.4-cp310-cp310-win_amd64.whl
装完验证一下：
python -c "from rknn3.api import RKNN3; print('RKNN3 Toolkit installed')"
看到 RKNN3 Toolkit installed 就对了。
三、LLM 模型转换（以 Qwen3-1.7B 为例）
LLM 的转换流程相对简单，主要靠 load_huggingface 一步到位：
from rknn3.api import RKNN3
rknn3 = RKNN3()
# 从 HuggingFace 加载模型
rknn3.load_huggingface(model="Qwen/Qwen3-1.7B")
# 构建 RKNN 模型
rknn3.build(
target="rk1828",
quantization="w8a8",
max_context_len=2048,
)
# 导出
rknn3.export("Qwen3-1.7B.rknn")
四、CNN 模型转换（以 MobileNet V2 为例）
CNN 的流程稍微多一步，需要先 config 配置均值和方差，再 load_onnx 加载模型：
from rknn3.api import RKNN3
rknn3 = RKNN3()
# 配置输入预处理
rknn3.config(
mean_values=[[0, 0, 0]],
std_values=[[255, 255, 255]],
)
# 加载 ONNX 模型
rknn3.load_onnx(model='./mobilenet_v2.onnx')
# 构建（INT8 量化）
rknn3.build(
target="rk1828",
do_quantization=True,
dataset='.dataset.txt',
)
# 导出
rknn3.export_rknn('./mobilenet_v2.rknn')
五、关键参数说明（避坑重点）
LLM 模型参数
| 参数 | 说明 | 建议值 |
|---|---|---|
target |
目标芯片 | rk1828 |
quantization |
量化方式：w4a8 / w8a8 |
w8a8 质量更好，w4a8 更省空间 |
max_context_len |
最大上下文长度 | 建议 ≥ 32768（Agent 框架需要） |
这里有个大坑： max_context_len 在转换时就定死了，运行时改不了！如果你转换时设了 2048，那后面 rkllm3-server 的 -c 参数最大也只能传 2048。建议一开始就设大一点，按需调整。
CNN 模型参数
| 参数 | 说明 | 建议值 |
|---|---|---|
target |
目标芯片 | rk1828 |
do_quantization |
是否量化 | True（INT8 量化减小模型体积） |
dataset |
量化校准数据集 | 20~200 张代表性图片路径 |
六、LLM 转换完成后会生成哪些文件？
跑完 LLM 转换，目录里会多出几个文件：
Qwen3-1.7B.rknn # 模型结构
Qwen3-1.7B.weight # 模型权重
Qwen3-1.7B.tokenizer.gguf # 分词器
Qwen3-1.7B.embed.bin # Embedding
这几个文件全部要拷到 RK1828 设备的模型目录，少一个都跑不起来。
七、更多示例
RKNN3 Model Zoo 里还有更多模型的转换和部署 demo，常见类型都有覆盖：
| 类型 | 示例模型 |
|---|---|
| LLM | Qwen3-1.7B / Qwen3-4B / Qwen2.5-3B |
| VLM | Qwen3-VL-2B / InternVL3-2B |
| ASR | Qwen3-ASR / Whisper / SenseVoice |
| TTS | Qwen3 TTS / VITS |
| CNN | MobileNet V2 / YOLOv5 / YOLOv8 |
差不多就这些，如果有遇到什么坑，欢迎评论区一起讨论！
RKNN3 Toolkit GitHub：GitHub - airockchip/rknn3-toolkit · GitHub