目录

一、RKNN核心基础认知（必学）

1.1 什么是RKNN

1.2 RKNN核心工具链组成

1.3 学习前提（必备基础）

二、环境搭建（分步实操，零踩坑）

2.1 PC端环境搭建（Ubuntu 20.04）

2.1.1 安装Miniforge Conda（环境隔离工具）

2.1.2 创建并激活RKNN-Toolkit2环境

2.1.3 安装RKNN-Toolkit2及依赖

2.1.4 下载官方仓库（示例代码+模型）

2.1.5 安装编译工具（可选，用于C/C++ Demo编译）

2.2 板端环境搭建（瑞芯微开发板，以RK3576为例）

2.2.1 硬件连接与固件烧录

2.2.2 安装ADB工具与NPU驱动检查

2.2.3 启动RKNN Server服务

三、RKNN核心操作（实操重点，必练）

3.1 模型转换（核心步骤）

3.2 量化优化（提升推理效率，必学）

3.3 仿真推理（PC端调试，无需硬件）

3.4 板端部署（实操落地，核心目标）

3.4.1 Python部署（简单快捷，适合调试）

3.4.2 C/C++部署（工业级，高效稳定）

四、实操案例（新手必练，快速上手）

4.1 案例准备

4.2 步骤拆解

五、进阶技巧与常见问题（避坑指南）

5.1 进阶技巧

5.2 常见问题与解决方案

六、学习资源推荐（进阶提升）

七、学习路线总结（新手必看）

---

一、RKNN核心基础认知（必学）

1.1 什么是RKNN

RKNN（Rockchip Neural Network）是瑞芯微（Rockchip）专为自家NPU（神经网络处理单元）开发的端侧神经网络计算框架，核心作用是提供“模型转换-部署-推理”全流程解决方案，帮助开发者将训练好的AI模型高效适配到瑞芯微系列芯片（如RK3588、RK3576、RK3566等）上运行，是瑞芯微边缘AI生态的核心工具。

简单来说，RKNN就像“模型翻译官”，将PyTorch、TensorFlow、ONNX等主流框架训练的模型，转换成瑞芯微NPU能直接识别的专属格式（.rknn），同时进行量化、优化，让模型在边缘设备上实现低延迟、低功耗推理。

1.2 RKNN核心工具链组成

RKNN工具链核心分为两大模块，二者协同完成模型部署全流程，新手需重点区分：

• RKNN-Toolkit2：运行在PC端（Ubuntu系统为主）的开发套件，核心功能包括模型转换、量化优化、仿真推理、性能评估、精度分析等，是模型部署前的核心调试工具，支持Python、C/C++接口，操作便捷且功能全面。

• RKNN Runtime：运行在瑞芯微芯片（开发板/边缘设备）上的推理引擎，负责加载.rknn格式模型，调用NPU驱动执行推理，提供通用API和零拷贝API两种推理流程，适配Linux、Android、Debian等多种系统。

1.3 学习前提（必备基础）

• 系统基础：熟悉Ubuntu系统（推荐20.04版本），掌握基本终端命令（cd、wget、git、conda等）。

• AI基础：了解基本的深度学习模型（如CNN、YOLO），知道模型训练与推理的基本流程。

• 硬件准备（可选但推荐）：瑞芯微系列开发板（如RK3576、RK3588开发板），便于实操部署验证；无硬件可先用PC端仿真推理。

二、环境搭建（分步实操，零踩坑）

环境搭建分为“PC端（RKNN-Toolkit2）”和“板端（RKNN Runtime）”两部分，优先完成PC端环境，再进行板端适配，步骤如下：

2.1 PC端环境搭建（Ubuntu 20.04）

2.1.1 安装Miniforge Conda（环境隔离工具）

使用Conda创建独立环境，避免依赖冲突，执行以下命令：

# 下载Miniforge Conda安装包 wget -c https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh # 赋予执行权限 chmod 777 Miniforge3-Linux-x86_64.sh # 执行安装（一路回车，最后输入yes确认） bash Miniforge3-Linux-x86_64.sh

2.1.2 创建并激活RKNN-Toolkit2环境

# 激活Conda基础环境 source ~/miniforge3/bin/activate # 创建RKNN-Toolkit2专属环境（Python 3.8为稳定版本） conda create -n RKNN-Toolkit2 python=3.8 # 激活该环境 conda activate RKNN-Toolkit2

2.1.3 安装RKNN-Toolkit2及依赖

# 安装RKNN-Toolkit2（通过官方PyPI源，稳定可靠） pip install rknn-toolkit2 -i https://pypi.org/simple # 安装额外依赖（用于模型转换、推理验证） pip install numpy opencv-python torch onnx # 验证安装是否成功（无报错即正常） python3 >>> from rknn.api import RKNN >>> exit()

2.1.4 下载官方仓库（示例代码+模型）

瑞芯微官方提供模型仓库和工具仓库，包含大量示例，便于学习：

# 创建项目目录 mkdir Projects && cd Projects # 下载RKNN-Toolkit2仓库（工具示例、API文档） git clone https://github.com/airockchip/rknn-toolkit2.git --depth 1 # 下载RKNN Model Zoo（预转换好的.rknn模型、实操案例） git clone https://github.com/airockchip/rknn_model_zoo.git --depth 1

2.1.5 安装编译工具（可选，用于C/C++ Demo编译）

# 安装cmake sudo apt install cmake # 下载GCC交叉编译器（用于板端C Demo编译，以aarch64架构为例） wget https://releases.linaro.org/components/toolchain/binaries/6.3-2017.05/aarch64-linux-gnu/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar.xz # 解压到Projects目录 tar -xvf gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar.xz -C ./

2.2 板端环境搭建（瑞芯微开发板，以RK3576为例）

2.2.1 硬件连接与固件烧录

1. 硬件连接：用Type-C线将开发板的OTG接口连接到PC（Ubuntu虚拟机），确保PC能识别开发板。

2. 烧录固件：下载适配开发板的系统固件（如Ubuntu 22.04、Android 14），使用瑞芯微官方工具RKDevTool烧录（Windows端操作更便捷），固件可从开发板厂商官网获取（如米尔电子、触觉智能）。

2.2.2 安装ADB工具与NPU驱动检查

# PC端安装ADB工具（用于连接开发板） sudo apt install adb # 检查开发板连接（出现设备ID即成功） adb devices # 进入开发板终端，检查NPU驱动版本 adb shell dmesg | grep -i rknpu

说明：默认出厂固件已集成NPU驱动，若查询不到驱动，需在开发板内核中开启配置：CONFIG_ROCKCHIP_RKNPU=y，重新编译内核即可。

2.2.3 启动RKNN Server服务

RKNN Server是板端后台代理服务，负责接收PC端数据并返回推理结果，必须启动才能正常部署：

# 开发板终端执行，启动服务 restart_rknn.sh # 检查服务版本与Runtime库版本一致性（避免兼容性问题） strings /usr/bin/rknn_server | grep -i "rknn_server version" strings /usr/lib/librknnrt.so | grep -i "librknnrt version"

若版本不一致，需从PC端的rknn-toolkit2仓库中拷贝对应版本的库文件到开发板，替换原有文件即可。

三、RKNN核心操作（实操重点，必练）

核心操作围绕“模型转换→量化优化→仿真推理→板端部署”展开，以最常用的Python API为例，结合RKNN Model Zoo中的示例模型实操。

3.1 模型转换（核心步骤）

将ONNX格式模型（最通用）转换为.rknn格式，以RKNN Model Zoo中的ResNet50模型为例：

from rknn.api import RKNN # 1. 初始化RKNN对象 rknn = RKNN() # 2. 加载ONNX模型（指定模型路径、输入尺寸等参数） onnx_model_path = "./rknn_model_zoo/models/classification/resnet50/resnet50.onnx" ret = rknn.load_onnx(model=onnx_model_path, input_size_list=[[3, 224, 224]]) if ret != 0: print("模型加载失败！") exit(ret) # 3. 构建RKNN模型（转换为.rknn格式） ret = rknn.build(do_quantization=False) # 先不量化，便于调试 if ret != 0: print("模型构建失败！") exit(ret) # 4. 保存.rknn模型 rknn.save_rknn("./resnet50.rknn") # 5. 释放资源 rknn.release() print("模型转换完成，保存路径：./resnet50.rknn")

关键说明：load_onnx支持指定输入尺寸、均值、标准差等参数；build函数中do_quantization=True可开启量化，后续会详细讲解。

3.2 量化优化（提升推理效率，必学）

量化是将FP32精度模型转换为INT8/INT16精度，在保证精度损失可控的前提下，减小模型体积、提升推理速度、降低功耗，是边缘部署的关键优化步骤。

from rknn.api import RKNN rknn = RKNN() # 加载ONNX模型（同上） onnx_model_path = "./resnet50.onnx" ret = rknn.load_onnx(model=onnx_model_path, input_size_list=[[3, 224, 224]]) # 构建模型（开启INT8量化，需指定校准数据集） # 校准数据集：10-20张与模型输入尺寸一致的图片，用于计算量化参数 calib_dataset = "./calib_images" # 校准图片目录 ret = rknn.build(do_quantization=True, dataset=calib_dataset, quantization_accuracy_level=1) # quantization_accuracy_level：精度等级（0-3），等级越高精度越好，速度稍慢 # 保存量化后的模型 rknn.save_rknn("./resnet50_int8.rknn") # 精度分析（查看量化后的精度损失） rknn.accuracy_analysis(dataset=calib_dataset, output_dir="./accuracy_result") rknn.release() print("量化完成，精度分析报告已保存")

注意：校准数据集需与模型训练时的预处理方式一致（如归一化、尺寸缩放），否则会导致精度严重下降；若精度损失过大，可提升quantization_accuracy_level等级，或增加校准图片数量。

3.3 仿真推理（PC端调试，无需硬件）

在PC端模拟NPU推理，验证模型转换和量化的正确性，避免直接板端部署踩坑：

from rknn.api import RKNN import cv2 import numpy as np rknn = RKNN() # 加载量化后的.rknn模型 ret = rknn.load_rknn("./resnet50_int8.rknn") # 初始化仿真环境（模拟瑞芯微NPU） ret = rknn.init_runtime(target="rk3576", device_id=None) # target指定芯片型号 # 预处理输入图片（与模型要求一致） img = cv2.imread("./test.jpg") img = cv2.resize(img, (224, 224)) # 缩放至输入尺寸 img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # 转换通道（BGR→RGB） img = img / 255.0 # 归一化 img = np.expand_dims(img, axis=0) # 增加batch维度 # 执行仿真推理 outputs = rknn.inference(inputs=[img]) # 解析输出结果（ResNet50为分类模型，输出概率最大的类别） pred_label = np.argmax(outputs[0]) print(f"仿真推理结果：类别 {pred_label}，概率 {outputs[0][pred_label]:.4f}") rknn.release()

3.4 板端部署（实操落地，核心目标）

将转换好的.rknn模型部署到开发板，分为Python部署和C/C++部署（工业场景优先C/C++，效率更高）。

3.4.1 Python部署（简单快捷，适合调试）

1. 将.rknn模型和推理脚本传到开发板： # PC端执行，通过ADB传文件 adb push ./resnet50_int8.rknn /home/root/ adb push ./rknn_inference.py /home/root/

2. 开发板终端执行推理脚本： # 进入开发板终端 adb shell cd /home/root/ # 执行推理（确保板端已安装rknn-toolkit2） python3 rknn_inference.py

3.4.2 C/C++部署（工业级，高效稳定）

1. PC端编译C Demo：使用之前下载的交叉编译器，编译rknn-toolkit2仓库中的C示例（以resnet50为例）： cd ./rknn-toolkit2/examples/rknn_resnet50_demo # 修改Makefile，指定交叉编译器路径 vim Makefile # 编译 make # 生成可执行文件 rknn_resnet50_demo

2. 将可执行文件和.rknn模型传到开发板，执行推理： adb push ./rknn_resnet50_demo /home/root/ adb push ./resnet50_int8.rknn /home/root/ adb shell cd /home/root/ chmod +x rknn_resnet50_demo ./rknn_resnet50_demo ./resnet50_int8.rknn ./test.jpg

四、实操案例（新手必练，快速上手）

以“RK3576开发板部署YOLO V10目标检测模型”为例，完整演示从模型转换到板端推理的全流程，贴合实际应用场景。

4.1 案例准备

• 模型：YOLO V10.onnx模型（可从RKNN Model Zoo下载，或自行训练转换）。

• 硬件：RK3576开发板（如米尔MYD-LR3576）、PC（Ubuntu 20.04）。

• 工具：RKNN-Toolkit2、ADB、RKDevTool。

4.2 步骤拆解

1. 模型转换与量化：参考3.1、3.2节，将YOLO V10.onnx转换为INT8量化的.rknn模型，确保精度损失在可接受范围（如mAP下降不超过5%）。

2. PC端仿真推理：参考3.3节，验证模型能正确检测目标（如行人、车辆），调整预处理参数（如输入尺寸、置信度阈值）。

3. 板端部署：将模型和推理脚本传到开发板，执行推理，查看检测结果（可通过HDMI连接显示器，实时显示检测画面）。

4. 性能优化：开启零拷贝API推理（替换通用API），提升推理速度，参考代码片段： # 零拷贝API初始化（替换init_runtime） ret = rknn.init_runtime(target="rk3576", runtime_mode="zero_copy") # 零拷贝输入（无需CPU预处理，直接传入原始数据） ret = rknn.set_input_tensor(inputs[0], input_tensor) ret = rknn.run() outputs = rknn.get_output_tensor()

说明：零拷贝API将数据预处理、量化等操作转移到NPU执行，比通用API推理效率提升20%-50%，适合对延迟要求高的场景（如实时目标检测）。

五、进阶技巧与常见问题（避坑指南）

5.1 进阶技巧

• 模型加密：使用rknn.build(encrypt_key="your_key")对模型进行加密，防止模型泄露，板端推理时需传入对应密钥。

• 多模型协同部署：通过RKNN Runtime同时加载多个模型（如目标检测+图像分类），实现复杂AI场景（如菜品识别+数量统计）。

• 性能调优：通过rknn.performance_analysis()分析模型推理耗时，针对性优化模型结构（如剪枝）或调整NPU频率。

• 多设备调试：RKNN-Toolkit2支持同时连接多个开发板，批量部署和测试模型，提升开发效率。

5.2 常见问题与解决方案

• 问题1：模型转换失败，提示“不支持的算子”？ 解决方案：检查模型中是否有RKNN不支持的算子，可通过rknn.list_supported_ops()查看支持的算子；若有不支持的算子，需修改模型结构（如替换算子），或使用ONNX Simplifier简化模型。

• 问题2：板端推理报错“rknn_server未启动”？ 解决方案：执行restart_rknn.sh启动服务，若启动失败，检查NPU驱动是否正常，或重新烧录固件。

• 问题3：量化后模型精度严重下降？ 解决方案：增加校准数据集数量（至少20张），提升量化精度等级，或调整模型预处理方式，确保校准数据与训练数据分布一致。

• 问题4：推理速度达不到预期？ 解决方案：开启INT8量化、使用零拷贝API、提升NPU频率，或简化模型结构（如使用轻量级模型）。

六、学习资源推荐（进阶提升）

• 官方文档：瑞芯微RKNN官方文档（包含API详细说明、工具使用指南），可在瑞芯微开发者官网下载。

• 官方仓库：RKNN-Toolkit2（https://github.com/airockchip/rknn-toolkit2）、RKNN Model Zoo（https://github.com/airockchip/rknn_model_zoo），包含大量示例代码和预转换模型。

• 实操视频：触觉智能、米尔电子等开发板厂商，提供免费的RKNN部署实操视频，适合新手跟着学。

• 社区交流：瑞芯微开发者社区、CSDN、知乎，可搜索相关问题，获取其他开发者的避坑经验。

七、学习路线总结（新手必看）

1. 基础阶段：掌握RKNN核心概念、工具链组成，完成PC端和板端环境搭建，能独立完成简单模型（如ResNet50）的转换和仿真推理。

2. 实操阶段：练习量化优化、板端部署，完成YOLO等实际模型的部署，掌握常见问题排查方法。

3. 进阶阶段：学习模型加密、多模型协同、性能调优，结合实际场景（如工业视觉、智能助手）开发完整应用。

提示：RKNN学习的核心是“多实操、多调试”，建议结合开发板反复练习，重点掌握模型转换和量化优化，这是边缘AI部署的核心技能。