模型转换

本章讲清 PC 端 vs 板端工具链，跑通 LLM 和 CNN 转换。

整体框图

PC (x86_64 Ubuntu)                       板端 (aarch64)
──────────────────                       ─────────────
PyTorch / ONNX / HuggingFace              rknn3-toolkit-lite
   │                                       │
   ▼                                       │
rknn-toolkit3 (pip)                       │
rknn.config + rknn.build + rknn.export_rknn
   │                                       │
   ▼                                       │
.rknn + .weight + .tokenizer.gguf + .embed.bin
   │                                       │
   ▼                                       ▼
scp ─────────────────────────────────────► rknn3-toolkit-lite.load_rknn()
                                          rkllm3-server / rknn3_cnn_demo

1. 工具链区分

重要区分：

  • PC 端：rknn-toolkit（pip 包名 rknn-toolkit3，Python 模块 rknn）
  • 板端：rknn3-toolkit-lite（Python 模块 rknn3lite）
  • 板端只能推理，不能转换！转换必须在 PC 上完成。
位置包名Python 模块用途
PC (x86_64)rknn-toolkit3rknn模型转换、量化、仿真
板端 (aarch64)rknn3-toolkit-literknn3lite推理（不能转换）

Python 版本要求：仅支持 3.10 和 3.12，不支持 3.11。当前系统 Python 3.11.2 需额外安装 3.10 / 3.12 才能跑 toolkit。

2. 使用官方预转换模型（推荐）

RKNN3 Model Zoo 提供了官方预转换模型。

2.1 检查 SDK Model Zoo

ls /userdata/RK1820_RK1828_AI_SDK/rknn/

输出：

rknn3-model-zoo
rknn3-runtime
rknn3-toolkit
rknn-gstreamer-plugins
ls /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-model-zoo/examples/

输出：

FastVLM         glm_edge        GME-Qwen2-VL    HY_MT_1_5
InternVLM       Janus_Pro       MiniCPM_V_4     mobilenet_v1
mobilenet_v2    Qwen2_5         Qwen2_5_Omni    Qwen2_5_VL
Qwen3           Qwen3_Embedding Qwen3_VL        resnet
SmolVLM         yolov5          yolov6          yolov8

2.2 克隆 GitHub 仓库

git clone https://github.com/airockchip/rknn3-model-zoo.git

2.3 传到设备

scp -r model/ root@<设备IP>:/userdata/models/Qwen3-1.7B/

2.4 查看已部署模型

ls -lh /userdata/models/Qwen3-1.7B/

输出（实测）：

总计 1.7G
-rw-r--r-- 1 linaro linaro 594M  8月20日 11:33 Qwen3-1.7B.embed.bin
-rw-r--r-- 1 linaro linaro  24M  8月20日 11:34 Qwen3-1.7B.rknn
-rw-r--r-- 1 linaro linaro 5.9M  8月20日 11:33 Qwen3-1.7B.tokenizer.gguf
-rw-r--r-- 1 linaro linaro 1.1G  8月20日 11:33 Qwen3-1.7B.weight

总大小：

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

输出：

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

3. 自行转换 LLM 模型（Qwen3-1.7B）

3.1 前置条件

  • PC（GRQ 量化需 NVIDIA GPU，显存 ≥ 16GB）
  • Python 3.10 或 3.12（非 3.11）
  • pip install rknn-toolkit3（PC 端完整包）

验证 PC 端工具：

# PC 端执行
python -c "from rknn.api import RKNN; print('RKNN Toolkit installed')"

输出：

RKNN Toolkit installed

3.2 方式 A：Model Zoo 转换脚本（推荐）

git clone https://github.com/airockchip/rknn3-model-zoo.git
cd rknn3-model-zoo
pip install -r requirements.txt
export PYTHONPATH=./
cd examples/Qwen3/python/

# 第一步：导出 ONNX（GRQ 量化）
python export_llm.py --quant --model_path Qwen/Qwen3-1.7B

# 第二步：转 RKNN
python export_rknn.py

即使启用 --quant，GRQ 量化仍需数据集 ../../../datasets/CMMLU/dataset.json。

实际 RKNN 配置（来自 export_rknn.py）：

rknn.config(target_platform='rk1820',     # ← 不是 'rk1828'
            quantized_dtype='w4a16',
            quantized_algorithm='grq',
            quantized_method='group32')
rknn.load_llm(model=onnx_path, config=config_path)
rknn.build(do_quantization=True, dataset=dataset_path)
rknn.export_rknn(rknn_path)

3.3 方式 B：Python API（PC 端）

from rknn.api import RKNN      # ← PC 端真实 API

rknn = RKNN(verbose=True)

# 配置（注意参数名）
rknn.config(target_platform='rk1820',     # 不是 'rk1828'
            quantized_dtype='w4a16',
            quantized_algorithm='grq',
            quantized_method='group32')

# 加载 LLM（ONNX + config）
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')

3.4 转换产出

Qwen3-1.7B/
├── Qwen3-1.7B.rknn            # 模型结构
├── Qwen3-1.7B.weight          # 模型权重 (~1.1 GB)
├── Qwen3-1.7B.tokenizer.gguf  # 分词器
└── Qwen3-1.7B.embed.bin       # Embedding (~594 MB)

4. 自行转换 CNN 模型（MobileNet V2）

import torch
import torchvision.models as models

# 第一步：导出 ONNX
model = models.mobilenet_v2(pretrained=True)
model.eval()
dummy_input = torch.randn(1, 3, 224, 224)
torch.onnx.export(model, dummy_input, "mobilenet_v2.onnx",
                  input_names=["input"], output_names=["output"])

# 第二步：转 RKNN
from rknn.api import RKNN
rknn = RKNN(verbose=True)
rknn.config(target_platform='rk1820',       # 不是 'rk1828'
            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')

4.1 转换产出

mobilenet_v2/
├── mobilenet_v2.rknn       # 模型结构 (~60KB)
└── mobilenet_v2.weight     # 模型权重 (~6.8MB)

5. 关键参数

参数说明建议
target_platform目标平台'rk1820'（不是 'rk1828'）
quantized_dtype量化类型'w4a16'（w4a8 / w8a8 也可选）
quantized_algorithm量化算法'grq'（GRQ） 或 'mmse'（传统）
quantized_method量化方法'group32' / 'channel'
do_quantization是否量化开启可减小模型体积
max_context_lenLLM 上下文（写死在模型里）1.7B 推荐 ≥ 8192

max_context_len 在转换时写死到模型中，运行时 rkllm3-server -c 不能超过此值（-c 实际是 core mask，不是上下文，见 ch03 LLM 推理）。

6. 部署验证

6.1 文件完整性

# LLM 模型验证
file /userdata/models/Qwen3-1.7B/Qwen3-1.7B.rknn
md5sum /userdata/models/Qwen3-1.7B/Qwen3-1.7B.rknn

输出：

Qwen3-1.7B.rknn: data
a1b2c3d4e5f6...  Qwen3-1.7B.rknn

6.2 可加载性（板端）

python3 -c "
from rknn3lite.api import RKNN3Lite
rknn = RKNN3Lite()
rknn.load_rknn(
    '/userdata/models/Qwen3-1.7B/Qwen3-1.7B.rknn',
    '/userdata/models/Qwen3-1.7B/Qwen3-1.7B.weight'
)
print('Model loaded successfully')
"

输出：

Model loaded successfully

weight_path 为必填参数，缺省会报 TypeError: missing 1 required positional argument: 'weight_path'。

7. 常见问题

现象原因处理
ModuleNotFoundError: No module named 'rknn'装到板端了（aarch64 不支持）移到 PC（x86_64）安装
Python 3.11 装不上 toolkit仅支持 3.10 / 3.12装 Python 3.10 或 3.12
rknn.config 报 target_platform 不支持写成了 'rk1828'改成 'rk1820'
GRQ 量化报缺 dataset数据集未提供下载 rknn3-model-zoo/datasets/CMMLU/dataset.json
板端 load_rknn 报缺 weight_path没传第二参数rknn.load_rknn(rknn_path, weight_path)
max_context_len 改不了写死在模型里PC 端重新转换

8. 下一步