2. 环境搭建

RKNN-Toolkit2是Rockchip官方提供的模型转换、量化与推理验证工具链，它运行在x86 Linux主机上，通过Python接口将ONNX等格式的模型转换为RKNN格式，并支持在PC端模拟推理或在开发板上进行真机推理。环境搭建是整个部署流程的基石，如果这一步没有做扎实，后续的模型转换和板端调试都会陷入“能跑但不知道为何跑不通”的泥潭。本节将带你从零开始，完成工具安装、Python虚拟环境配置以及开发板/模拟器的连接验证。

核心原理：主机-板卡协同架构

理解RKNN工具链的工作模式，是避免环境混乱的前提。整个系统分为主机侧（x86 Linux）与板卡侧（ARM Linux）两部分。主机侧负责运行RKNN-Toolkit2，完成模型解析、量化、生成.rknn文件；板卡侧则通过RKNN Runtime加载该文件执行推理。两者之间通过USB或以太网连接，使用adb或ssh进行通信。

上图展示了主机与板卡之间的协作关系。在主机侧，Python虚拟环境隔离了不同项目的依赖冲突；转换脚本调用RKNN API完成模型转换；模拟器模式（target=None）可以在没有硬件的情况下验证模型正确性。板卡侧则通过adb push将生成的.rknn文件与推理程序部署到目标设备，由RKNN Runtime驱动NPU执行。

方法流程：从零搭建RKNN开发环境

环境搭建遵循“先装工具链，再配Python环境，最后验证连接”的顺序。下面以Ubuntu 20.04/22.04系统为例，逐步演示完整流程。

步骤1：安装系统依赖与Python虚拟环境

RKNN-Toolkit2要求Python版本为3.8~3.10，推荐使用venv创建独立环境，避免污染系统Python。首先安装必要的系统包：

# 更新apt源并安装基础依赖
sudo apt-get update
sudo apt-get install -y python3-dev python3-pip python3-venv git cmake
sudo apt-get install -y libxslt1-dev zlib1g-dev libgl1-mesa-dev libglib2.0-dev

# 创建并激活虚拟环境
python3 -m venv ~/rknn_env
source ~/rknn_env/bin/activate

激活虚拟环境后，命令行提示符前会出现(rknn_env)前缀，表示当前已进入隔离环境。后续所有pip安装操作都必须在此环境下执行。

步骤2：安装RKNN-Toolkit2

RKNN-Toolkit2的安装包可以从Rockchip官方仓库或百度网盘获取。推荐使用pip直接安装预编译的wheel包：

# 安装RKNN-Toolkit2（以rknn-toolkit2-1.6.0为例）
pip install rknn-toolkit2-1.6.0-cp38-cp38-linux_x86_64.whl

# 验证安装是否成功
python -c "from rknn.api import RKNN; print('RKNN-Toolkit2 imported successfully')"

如果输出RKNN-Toolkit2 imported successfully，说明核心工具已安装成功。若提示缺少依赖，可根据报错信息逐一安装：

# 常见依赖补充
pip install onnx==1.14.1 onnxruntime==1.14.1
pip install numpy==1.23.5 opencv-python==4.8.1.78
pip install torch==2.0.1 torchvision==0.15.1  # 仅当需要pytorch模型转换时

步骤3：连接开发板或模拟器

RKNN-Toolkit2支持两种推理验证方式：PC模拟器和开发板真机。模拟器适合快速验证模型转换正确性，但无法反映真实NPU性能；开发板则用于最终部署验证。

方式A：PC模拟器（无需硬件）

# 在转换脚本中指定target=None即可使用模拟器
rknn = RKNN()
ret = rknn.init_runtime(target=None)  # 模拟器模式
if ret != 0:
    print("模拟器初始化失败")

方式B：开发板真机连接

首先确保开发板已通过USB连接主机，并开启ADB调试模式：

# 检查ADB设备是否识别
adb devices
# 预期输出：设备序列号 device

# 如果设备未授权，在开发板上确认授权弹窗
# 如果设备显示offline，重启adb服务
adb kill-server
adb start-server

连接成功后，在转换脚本中指定目标平台：

# 以RK3588为例
rknn = RKNN()
ret = rknn.init_runtime(target='rk3588', device_id='你的设备序列号')
if ret != 0:
    print("开发板连接失败，请检查USB连接和ADB授权")

除了ADB，也可以通过SSH连接开发板，将主机上的.rknn文件手动拷贝到板卡上执行推理。这种方式适合批量部署或远程调试场景。

案例/场景：典型环境搭建完整流程

下面以一个实际项目为例，演示从零搭建环境到成功运行模拟推理的完整过程。假设目标平台为RK3588，主机为Ubuntu 22.04。

以下是一个完整的转换脚本示例，展示了模拟器与开发板两种模式的切换方式：

# convert.py
from rknn.api import RKNN

def convert_and_test(platform='rk3588', target=None):
    rknn = RKNN()
    
    # 配置模型输入
    rknn.config(mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]], target_platform=platform)
    
    # 加载ONNX模型
    ret = rknn.load_onnx(model='yolov5s.onnx')
    if ret != 0:
        print("模型加载失败")
        return
    
    # 构建RKNN模型
    ret = rknn.build(do_quantization=True, dataset='dataset.txt')
    if ret != 0:
        print("模型构建失败")
        return
    
    # 导出RKNN文件
    ret = rknn.export_rknn('yolov5s.rknn')
    if ret != 0:
        print("导出失败")
        return
    
    # 初始化运行时（模拟器或开发板）
    ret = rknn.init_runtime(target=target)  # target=None为模拟器
    if ret != 0:
        print("运行时初始化失败")
        return
    
    # 加载测试图像并推理
    import cv2
    import numpy as np
    img = cv2.imread('test.jpg')
    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    outputs = rknn.inference(inputs=[img])
    print("推理输出shape:", [o.shape for o in outputs])
    
    rknn.release()

if __name__ == '__main__':
    # 先模拟器验证
    convert_and_test(target=None)
    # 再开发板验证（需连接设备）
    # convert_and_test(target='rk3588')

误区/复盘：环境搭建中的常见陷阱

根据大量开发者反馈，环境搭建阶段最容易踩坑的地方集中在版本兼容性和连接配置两方面。下面梳理几个高频问题及解决方案。

另一个常见问题是模拟器与开发板结果不一致。这通常是因为模拟器使用CPU模拟NPU计算，浮点精度与真实NPU存在差异。如果模拟器推理正常但开发板输出异常，优先检查：

• 开发板的RKNN Runtime版本是否与主机工具链版本匹配（例如工具链1.6.0对应Runtime 1.6.0）
• 是否在rknn.config()中正确设置了target_platform（如'rk3588'）
• 量化数据集是否具有代表性，避免因量化误差导致输出偏差

最后，建议在完成环境搭建后，运行一个简单的全流程冒烟测试：将官方提供的yolov5s模型从ONNX转换为RKNN，分别在模拟器和开发板上推理同一张测试图片，对比输出结果。如果两者输出一致（允许微小浮点差异），说明环境搭建成功，可以开始正式的模型转换工作。