RKNN Toolkit2 安装与使用

1. 概述

1.1 功能简介

RKNN Toolkit2 是 Rockchip 官方提供的 NPU 开发工具套件，覆盖模型转换、量化、推理测试等完整开发环节。在 RK3588 平台上，它完整支持这颗 6 TOPS 算力 NPU 的开发流程。

它的核心功能有：

• 模型格式转换：把主流深度学习框架的模型（ONNX、PyTorch、TensorFlow、Caffe、Darknet）转成 RKNN 格式（Rockchip NPU 专用模型格式，NPU 只认这一种）
• 模型量化：支持 FP32 到 INT8/INT16 的量化压缩（量化即把 32 位浮点权重压成低位整数，模型更小、推理更快），降低模型体积并提升推理速度
• 板端推理：在 RK3588 目标板上执行模型推理，提供 Python 和 C/C++ 两套 API
• 性能评估：评估模型在 NPU 上的推理性能（延迟、吞吐量等指标）
• 模型部署：支持多 NPU 核心协同工作，满足不同算力需求

套件包含两个主要组件，一个装在宿主机上、一个装在开发板上：

组件	运行环境	功能
rknn-toolkit2	宿主机（x86/ARM64）	模型转换、量化、导出
rknn-lite2	RK3588 目标板	板端模型加载与推理执行

1.2 应用场景

RKNN Toolkit2 在 RK3588 平台上适合这些典型应用：

• 图像分类：ResNet、MobileNet、EfficientNet 等分类模型部署
• 目标检测：YOLOv5/YOLOv8、SSD、Faster R-CNN 等检测模型
• 语义分割：DeepLabV3、UNet 等分割模型
• 人脸识别：人脸检测、特征提取、活体检测
• 姿态估计：多人姿态估计、手部关键点检测
• 超分辨率：Real-ESRGAN 等图像超分辨率模型

RK3588 的 6 TOPS NPU 算力允许同时运行多个 AI 模型，适合智能摄像头、智能零售、工业质检这类边缘 AI 应用。

1.3 工作原理

RKNN 开发流程分两个阶段：宿主机上做模型转换，目标板上做推理执行。

宿主机（x86/ARM64）                        目标板（RK3588）
┌──────────────────┐                    ┌──────────────────┐
│  RKNN Toolkit2   │                    │  rknpu2 驱动     │
│  ┌────────────┐  │    scp / adb       │  ┌────────────┐  │
│  │ 模型加载   │  │  ───────────→      │  │ 模型加载   │  │
│  │ (ONNX/     │  │   .rknn 文件       │  │ (RKNN格式) │  │
│  │  PyTorch/  │  │                    │  └────────────┘  │
│  │  TF/Caffe) │  │                    │        ↓         │
│  └────────────┘  │                    │  ┌────────────┐  │
│        ↓         │                    │  │ NPU 推理   │  │
│  ┌────────────┐  │                    │  │ (三核6TOPS)│  │
│  │ 量化构建   │  │                    │  └────────────┘  │
│  │ (INT8/16)  │  │                    │        ↓         │
│  └────────────┘  │                    │  ┌────────────┐  │
│        ↓         │                    │  │ 后处理     │  │
│  ┌────────────┐  │                    │  └────────────┘  │
│  │ 导出.rknn  │  │                    │                  │
│  └────────────┘  │                    │                  │
└──────────────────┘                    └──────────────────┘

对应到具体步骤：

1. 模型转换：宿主机上的 rknn-toolkit2 将原始模型解析为内部计算图，经过图优化、算子融合等操作后生成 RKNN 格式模型
2. 量化压缩：转换过程中可选择做 INT8 或 INT16 量化，需要提供校准数据集
3. 模型部署：把生成的 .rknn 文件传到 RK3588 目标板
4. NPU 推理：目标板上的 rknpu2 驱动加载模型，分配到 3 个 NPU 核心上执行推理计算
5. 结果输出：推理结果通过 API 返回给用户程序做后处理

---

2. 硬件准备

2.1 硬件需求

组件	型号/规格	数量	备注
主控板	C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板	1	已烧录 Linux 系统
调试串口线	USB 转 TTL（3.3V）	1	波特率 1500000（1.5Mbps）
网线	标准 RJ45 网线	1	用于 SSH 登录和文件传输
电源适配器	4V/5A DC	1	误差 ±5%，建议使用标配电源
电脑	Windows/Linux/Mac	1	安装 rknn-toolkit2

2.2 NPU 硬件规格

RK3588 内置 NPU 的规格如下：

参数	规格
算力	6 TOPS（INT8）
NPU 核心数	3 个独立核心
支持精度	INT8、INT16、FP16
内存接口	共享 DDR 内存
单核算力	约 2 TOPS（INT8）

2.3 引脚连接

调试串口（UART2）的引脚定义：

主控板引脚	功能	连接调试器
UART2_TX_M0_DEBUG	发送	调试器 RX
UART2_RX_M0_DEBUG	接收	调试器 TX
GND	地	调试器 GND

串口网络标注来源于底板原理图第 6 页（Sheet 6/21），对应 GPIO0_B6_D、GPIO0_B5_D。 注意：TX/RX 不要反接，VCC 引脚不用连接。

---

3. 软件准备

3.1 宿主机安装 rknn-toolkit2

宿主机环境要求：

项目	要求
操作系统	Ubuntu 18.04/20.04/22.04（x86_64）或 ARM64 Linux
Python 版本	3.6 ~ 3.12
内存	建议 8GB 以上

方法一：pip 安装（推荐）

python3 -m venv rknn-env
source rknn-env/bin/activate
pip3 install rknn-toolkit2==2.3.2 -i https://pypi.org/simple

平台支持情况（PyPI 2.3.2）：只有 Linux wheel（x86_64 + aarch64，cp36~cp312），Windows 没有官方 wheel。国内镜像源（tuna 等）未收录此包，必须加 -i https://pypi.org/simple 走官方源。

方法二：直接装在 RK3588 板上（可行）

sudo pip3 install --break-system-packages onnx          # aarch64 有 wheel
sudo pip3 install --break-system-packages --no-deps rknn-toolkit2==2.3.2
python3 -c "from rknn.api import RKNN; print('OK')"
# 输出: TK2 import OK

踩过的坑：直接 pip3 install rknn-toolkit2 会先去编译 onnxoptimizer，而 PyPI 上没有它的 aarch64 wheel，cmake 构建报 CalledProcessError。fp16 转换其实不需要 onnxoptimizer，用 --no-deps 绕过后，load/build/export 均正常（mobilenetv2 fp16 转换 4.8s 成功）。

验证安装

python3 -c "from rknn.api import RKNN; print('RKNN Toolkit2 安装成功')"

打印出「RKNN Toolkit2 安装成功」即说明装好了。

3.2 目标板运行时安装

RK3588 的 Debian 系统通常已预装 rknpu2 驱动和运行时库，装之前先逐项确认：

# 检查 rknpu 驱动（内建非模块；本机 lsmod 会挂死，勿用）
ls /sys/module/ | grep rknpu
# 输出: rknpu

# 检查 NPU 初始化日志
dmesg | grep -i rknpu
# 输出: [drm] Initialized rknpu 0.9.8 20240828 for fdab0000.npu on minor 1

# 检查运行时库
ls /usr/lib/librknnrt.so
# 存在

# 查看运行时版本
strings /usr/lib/librknnrt.so | grep -m1 "librknnrt version"
# 输出: librknnrt version: 2.3.2 (429f97ae6b@2025-04-09T09:09:27)

# 检查 NPU 设备节点
ls -la /dev/dri/renderD*
#  renderD128 (Mali-G610 GPU) + renderD129 (RKNPU)

如果目标板确实缺 rknpu2 驱动，再安装：

dpkg -i rknpu2-driver-*.deb

3.3 Python 运行时环境

板端 Python 推理要用 rknn-lite2（toolkit2 的板端精简版，只保留推理功能）：

# 包名是 rknn-toolkit-lite2（PyPI 可装），版本与 librknnrt 匹配（本机 2.3.2）
sudo pip3 install --break-system-packages rknn-toolkit-lite2==2.3.2

验证：

python3 -c "from rknnlite.api import RKNNLite; print('RKNNLite 安装成功')"
# 输出: RKNNLite 安装成功

3.4 C/C++ 开发环境

用 C/C++ API 推理时，先确认头文件和库文件是否就位：

ls -la /usr/include/rknn_api.h
#  不存在（头文件需从 rknn-toolkit2 仓库 include/ 目录自取）
ls -la /usr/lib/librknnrt.so
#  存在

结论是：库已在系统里，头文件要自己从 rknn-toolkit2 仓库的 include/ 目录拷一份。

---

4. 操作步骤

4.1 RKNN API 基本使用流程

4.1.1 ONNX 模型转换示例

from rknn.api import RKNN

rknn = RKNN()

# 配置模型参数
# target_platform 必须指定为 'rk3588'
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3588',
    quantized_dtype='asymmetric_quantized-8'
)

# 加载原始模型
ret = rknn.load_onnx(model='model.onnx')
if ret != 0:
    print('加载模型失败')
    exit(ret)

# 量化构建
# dataset 指定校准数据文件（每行一个样本路径）
ret = rknn.build(do_quantization=True, dataset='calibration_data.txt')
if ret != 0:
    print('构建模型失败')
    exit(ret)

# 导出 RKNN 模型
ret = rknn.export_rknn('model.rknn')
if ret != 0:
    print('导出模型失败')
    exit(ret)

rknn.release()

mobilenetv2 fp16 转换的输出（build(do_quantization=False) 无需校准集）：

[3] load_onnx() ret=0  0.3s
[4] build(do_quantization=False) ret=0  4.8s
[5] export_rknn() ret=0  4.8s
[6] model size = 7665073 bytes (7.3 MB)  total 4.8s

踩过的坑：ONNX 模型输入若是动态维度（如 mobilenetv2 的 ['batch_size',3,224,224]），load_onnx 会直接报 The input shape ... is not support!。要先用 onnx 库把 batch 固定为 1 再转（见 ch01 4.4 节）。

4.1.2 PyTorch 模型转换示例

from rknn.api import RKNN

rknn = RKNN()
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3588'
)

# 加载 PyTorch 模型（需先导出为 ONNX）
ret = rknn.load_pytorch(model='model.pth', input_size_list=[[1, 3, 224, 224]])
if ret != 0:
    print('加载模型失败')
    exit(ret)

ret = rknn.build(do_quantization=True, dataset='calibration_data.txt')
if ret != 0:
    print('构建模型失败')
    exit(ret)

ret = rknn.export_rknn('model.rknn')
if ret != 0:
    print('导出模型失败')
    exit(ret)

rknn.release()

4.1.3 量化校准数据文件格式

校准数据文件（calibration_data.txt）的格式很简单，每行写一个样本的绝对路径：

/path/to/sample1.jpg
/path/to/sample2.jpg
/path/to/sample3.jpg

推荐用 20-100 个有代表性的样本做量化校准。

4.2 板端 Python 推理

4.2.1 基本推理流程

from rknnlite.api import RKNNLite
import numpy as np

rknn = RKNNLite()

# 加载 RKNN 模型
ret = rknn.load_rknn('model.rknn')
if ret != 0:
    print('加载模型失败')
    exit(ret)

# 初始化运行时
# core_mask 指定 NPU 核心分配
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)

# 准备输入数据（224x224 RGB 图像，NHWC 格式）
input_data = np.random.randint(0, 255, (1, 224, 224, 3), dtype=np.uint8)

# 执行推理
outputs = rknn.inference(inputs=[input_data])
print('推理输出 shape:', outputs[0].shape)

# 后处理（softmax + argmax）
logits = outputs[0][0]
probs = np.exp(logits) / np.sum(np.exp(logits))
pred = np.argmax(probs)
print('预测类别:', pred)

rknn.release()

下面的输出取自实机（mobilenetv2 fp16 @224×224，随机输入）：

[1] load_rknn() ret=0  0.01s
[2] init_runtime(NPU_CORE_0) ret=0  0.07s
[3] 首次推理 9.0 ms, output shape=(1, 1, 1000)
[4] 20 次平均 9.28 ms/帧 (~107.8 FPS)
[5] output[0] shape=(1, 1000) dtype=float32
[7] release() done

关键发现：调用顺序必须是 load_rknn() → init_runtime()。顺序反了 init_runtime 返回 -1，日志报 E Model is not loaded yet, this interface should be called after load_rknn!

4.2.2 NPU 核心分配模式

RK3588 有 3 个 NPU 核心，通过 init_runtime 的 core_mask 参数选择分配方式：

# 单核模式（约 2 TOPS）
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)

# 双核模式（约 4 TOPS）
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1)

# 三核模式（约 6 TOPS，全部算力）
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)

# 自动分配
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_AUTO)

怎么选可以参考这张表：

场景	推荐模式	说明
单模型低延迟	NPU_CORE_0	单核推理延迟最低
单模型高吞吐	NPU_CORE_0_1_2	三核并行提升吞吐量
多模型并发	各模型分别绑定不同核心	避免核心争用
不确定场景	NPU_CORE_AUTO	运行时自动优化

三种模式对比（mobilenetv2 fp16，30 次平均）：

core_mask	耗时/帧	帧率
NPU_CORE_0	10.51 ms	95.2 FPS
NPU_CORE_0_1_2	5.28 ms	189.2 FPS
NPU_CORE_AUTO	8.89 ms	112.5 FPS

三核并行对单模型有约 1.99 倍加速；实际收益取决于模型算子可切分性，小模型收益递减。

4.3 C/C++ 推理

4.3.1 完整 C 推理示例

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "rknn_api.h"

int main(int argc, char *argv[]) {
    rknn_context ctx;
    rknn_input inputs[1];
    rknn_output outputs[1];
    rknn_input_output_num io_num;

    // 读取 RKNN 模型文件
    FILE *fp = fopen("model.rknn", "rb");
    fseek(fp, 0, SEEK_END);
    int model_size = ftell(fp);
    fseek(fp, 0, SEEK_SET);
    void *model_data = malloc(model_size);
    fread(model_data, 1, model_size, fp);
    fclose(fp);

    // 初始化 RKNN 上下文
    int ret = rknn_init(&ctx, model_data, model_size, 0, NULL);
    if (ret < 0) {
        printf("rknn_init 失败: %d\n", ret);
        free(model_data);
        return -1;
    }
    free(model_data);

    // 查询输入输出数量
    ret = rknn_query(ctx, RKNN_QUERY_IN_OUT_NUM, &io_num, sizeof(io_num));
    printf("输入数量: %d, 输出数量: %d\n", io_num.n_input, io_num.n_output);

    // 设置输入
    memset(inputs, 0, sizeof(inputs));
    inputs[0].index = 0;
    inputs[0].type = RKNN_TENSOR_UINT8;
    inputs[0].size = 224 * 224 * 3;
    inputs[0].fmt = RKNN_TENSOR_NHWC;
    inputs[0].buf = input_data;
    ret = rknn_inputs_set(ctx, io_num.n_input, inputs);

    // 执行推理
    ret = rknn_run(ctx, NULL);

    // 获取输出（want_float=1 表示输出为浮点数）
    memset(outputs, 0, sizeof(outputs));
    outputs[0].index = 0;
    outputs[0].want_float = 1;
    ret = rknn_outputs_get(ctx, io_num.n_output, outputs, NULL);

    // 后处理
    float *output_buf = (float *)outputs[0].buf;
    int output_size = outputs[0].size / sizeof(float);
    for (int i = 0; i < output_size; i++) {
        printf("output[%d] = %.6f\n", i, output_buf[i]);
    }

    // 释放资源
    rknn_outputs_release(ctx, io_num.n_output, outputs);
    rknn_destroy(ctx);
    return 0;
}

编译命令注意两点：链接的是 librknnrt 而不是 librknn_api；头文件要自备（见 3.4 节）：

gcc -O2 -o rknn_demo rknn_demo.c -I<rknn_api.h所在目录> -lrknnrt

（mobilenetv2 fp16，板上编译运行）：

$ gcc -O2 -o rknn_c_demo rknn_c_demo.c -I. -lrknnrt
$ ./rknn_c_demo /var/tmp/mobilenetv2_fp16.rknn
[1] model /var/tmp/mobilenetv2_fp16.rknn (7665073 bytes)
[2] rknn_init ret=0
[3] rknn_query ret=0 n_input=1 n_output=1
    input[0]: n_dims=4 dims=[1,224,224,3] size=301056 type=1 fmt=1
[5] rknn_run ret=0 6.40 ms
[6] rknn_outputs_get ret=0 size=4000
    n_elems=1000 argmax=904 val=9.1953
[7] 20 次平均 9.69 ms/帧 (~103.2 FPS)
[8] rknn_destroy done

说明：

1. input[0] 的 dims=[1,224,224,3]、type=1（UINT8）、fmt=1（NHWC），说明 C API 拿到的是转换后的 NHWC 布局，喂图直接用 HWC 排列的 uint8 数据。
2. C API 20 次平均 9.69 ms/帧（含 inputs_set+outputs_get 开销），与 Python RKNNLite 的 9.28 ms 同量级。
3. outputs[0].size 是字节数（4000 = 1000×float32），除以 sizeof(float) 才是元素数。

4.4 命令行工具

模型信息查看

toolkit2 没有内置 rknn.tool.show 模块，查看模型信息要走 Python 接口：

from rknn.api import RKNN
rknn = RKNN()
rknn.load_rknn('model.rknn')
rknn.build()   # 或用 rknn.load_rknn 后直接 init
# 输入输出信息:
from rknnlite.api import RKNNLite
r = RKNNLite()
r.load_rknn('model.rknn')
r.init_runtime()
r.release()

运行日志会打印模型信息（version / target / framework），例如：

I RKNN Model Information, version: 6, toolkit version: 2.3.2,
  target: RKNPU v2, target platform: rk3588, framework name: ONNX

板端性能评估

板上没有 rknn-lite-perf 命令。性能评估有两种可行的方式：

# 方式1: Python RKNNLite eval_perf（toolkit2 端，连板测）
# 在装有 toolkit2 的环境（可就在板上）:
python3 -c "
from rknn.api import RKNN
rknn = RKNN()
rknn.load_rknn('/var/tmp/mobilenetv2_fp16.rknn')
rknn.build(do_quantization=False)   # 已是 rknn 可省略
# eval_perf 需要 target 连接，详见官方 examples
"

# 方式2: 直接计时不依赖任何工具（最可靠）
time python3 infer_test.py   # 见 4.2.1 脚本

4.5 完整部署工作流

# 步骤1：宿主机上执行模型转换
python3 convert_model.py

# 步骤2：传输模型到目标板（板子 IP）
scp model.rknn linaro@192.168.49.60:/var/tmp/    # Debian 镜像；Ubuntu 镜像用 root@

# 步骤3：板端执行推理测试
ssh linaro@192.168.49.60    # Debian 镜像；Ubuntu 镜像用 root@
python3 inference.py

# 步骤4：性能评估
rknn-lite-perf model.rknn

注意：步骤 4 的 rknn-lite-perf 在本机镜像上并不存在（见 4.4 节的结论），性能评估请用 4.4 节的两种可行方式替代。

---

5. 代码详解

5.1 RKNN API 调用流程

宿主机端的转换流程固定是这五步：

RKNN()
  → config()       设置量化参数、目标平台
  → load_xxx()     加载原始模型（ONNX/PyTorch/TF/Caffe/Darknet）
  → build()        量化 + 构建 RKNN 图
  → export_rknn()  导出 .rknn 文件
  → release()      释放资源

5.2 板端运行时流程

板端推理流程同样固定四步：

RKNNLite()
  → load_rknn()    加载 .rknn 模型
  → init_runtime() 初始化 NPU 核心
  → inference()    执行推理
  → release()      释放资源

5.3 NPU 核心分配策略

RK3588 的 3 个 NPU 核心各自约 2 TOPS（INT8），三核并行可达 6 TOPS，按需分配即可：

分配模式	算力	适用场景
NPU_CORE_0	约 2 TOPS	单模型低延迟应用
NPU_CORE_0_1	约 4 TOPS	中等规模模型
NPU_CORE_0_1_2	约 6 TOPS	大规模模型、高吞吐量需求
NPU_CORE_AUTO	自动	不确定场景

多模型并发示例：

# 两个模型并发，各占一个核心
rknn1.init_runtime(core_mask=RKNNLite.NPU_CORE_0)
rknn2.init_runtime(core_mask=RKNNLite.NPU_CORE_1)

# 模型1 高优先级 + 模型2 低优先级
rknn1.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1)  # 4 TOPS
rknn2.init_runtime(core_mask=RKNNLite.NPU_CORE_2)    # 2 TOPS

5.4 输入数据预处理

RKNN 模型的输入预处理要和训练时保持一致。如果在 config() 中设置了 mean_values 和 std_values，输入数据就传 uint8 原始像素值，归一化由 RKNN 自动完成：

import cv2
import numpy as np

def preprocess(image_path, input_size=224):
    """图像预处理：Resize → BGR → RGB → uint8"""
    img = cv2.imread(image_path)
    img = cv2.resize(img, (input_size, input_size))
    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    img = img.astype(np.uint8)  # RKNN 会自动归一化
    img = np.expand_dims(img, axis=0)  # HWC → NHWC
    return img

5.5 输出后处理

import numpy as np

def postprocess_classification(outputs, top_k=5):
    """分类模型后处理：softmax + top-k"""
    logits = outputs[0][0]
    exp_logits = np.exp(logits - np.max(logits))
    probs = exp_logits / np.sum(exp_logits)
    top_indices = np.argsort(probs)[::-1][:top_k]
    return [(idx, probs[idx]) for idx in top_indices]

---

6. 常见问题

6.1 rknn-toolkit2 安装失败

现象：pip install 报错，提示依赖不满足或找不到匹配的 wheel 文件。

排查与解决：

# 检查 Python 版本（需要 3.6-3.10）
python3 --version

# 安装基础依赖
pip3 install numpy flatbuffers protobuf

# 使用指定版本 wheel 安装
pip3 install rknn_toolkit2-2.3.0-cp38-cp38-*.whl

6.2 模型转换报 "not support op"

现象：模型转换过程中提示某些算子不被支持。

先查算子支持列表，确认到底是哪个算子挂了：

# 查看支持的算子列表
python3 -c "from rknn.api import RKNN; r=RKNN(); print(r.get_support_op_list())"

对策是改用更简单的等效算子，或用 ONNX opset 11-13 重新导出模型。

6.3 推理结果全为 0

现象：板端推理输出全部为 0 或异常值。

多数是预处理没对齐，逐项检查：

# 检查输入数据格式和预处理是否与训练一致
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3588',
    quantized_dtype='asymmetric_quantized-8'  # 确认量化类型
)

# 检查输入 tensor shape（应为 NHWC 格式）
print("输入 shape:", input_data.shape)

# 检查输入数据类型（应为 uint8）
print("输入 dtype:", input_data.dtype)

6.4 板端推理报错 "init runtime failed"

现象：RKNNLite.init_runtime() 返回 -1。

第一嫌疑（踩坑）是调用顺序错了：init_runtime() 必须放在 load_rknn() 之后：

# 错误顺序（init_runtime 返回 -1）:
r = RKNNLite()
r.init_runtime()          # ← 报 "Model is not loaded yet..."

# 正确顺序:
r = RKNNLite()
r.load_rknn('model.rknn') # 先加载
r.init_runtime()          # 后初始化，返回 0

如果顺序没问题，再按下面几项排查：

# 确认 rknpu2 驱动已加载
ls /sys/module/ | grep rknpu   # 不要用 lsmod（本机会挂死；驱动是内建的）

# 确认 NPU 设备节点存在
ls -la /dev/dri/renderD*

# 确认运行时库存在
ls -la /usr/lib/librknnrt.so*

# 检查 NPU 错误日志
dmesg | grep -i npu

6.5 模型转换后精度下降严重

现象：量化后的模型精度相比 FP32 模型下降明显。

三个方向逐步尝试：增加校准数据量（建议 50-200 个样本）、使用混合精度量化、干脆不量化改用 FP16。

# 不量化，使用 FP16
rknn.build(do_quantization=False)

6.6 推理速度不符合预期

现象：推理延迟远高于预期。

先用性能评估工具确认实际性能：

# 使用性能评估工具确认实际性能
rknn-lite-perf model.rknn

再检查是否用了多核模式、是否启用了预编译：

rknn.build(do_quantization=True, pre_compile=True)
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)

6.7 多模型并发推理时部分失败

现象：多个模型同时推理时，部分模型报错。

依次确认：每个模型分配了独立的 NPU 核心；内存是否充足（多个大模型同时加载可能超出 DDR 容量）；并发访问是否加锁。

import threading
lock = threading.Lock()

def safe_inference(rknn, inputs):
    with lock:
        return rknn.inference(inputs=inputs)

---

相关文档

• ch01 NPU架构与性能概览：RK3588 NPU 架构和算力介绍
• ch03 模型转换与量化：模型转换和量化详细教程
• ch04 分类模型部署(LeNet-ResNet)：图像分类模型部署实战
• ch09 NPU性能调优与调试：NPU 性能调优和问题排查