2. 环境搭建

在完成ONNX模型导出之后，下一步便是将其部署到瑞芯微（Rockchip）NPU上运行。而RKNN-Toolkit2正是连接ONNX模型与NPU硬件之间的关键桥梁。本章将系统讲解如何从零开始搭建RKNN-Toolkit2的开发环境，包括Python虚拟环境的配置、依赖库的安装与验证，以及如何将开发板或模拟器接入PC端，为后续的模型转换、量化与推理验证打下坚实的工具链基础。环境搭建的成败直接决定了后续开发效率，因此本章内容将遵循“原理先行、步骤细化、案例复盘”的思路展开。

上图清晰地展示了RKNN-Toolkit2环境搭建的整体架构：左侧为PC端需要安装的Python环境与工具包，中间为工具链的核心功能（模型转换、量化、推理），右侧为目标端（开发板或模拟器）。三者通过USB或网络连接，形成一个完整的开发闭环。下面我们将分模块详细展开。

2.1 核心原理：RKNN-Toolkit2的软件栈与运行机制

RKNN-Toolkit2是瑞芯微官方提供的NPU开发工具包，它运行在x86_64架构的Linux或Windows PC上，通过Python接口调用底层C/C++库，完成模型解析、优化、量化、序列化以及推理模拟。其核心设计思想是“PC端编译，板端运行”：开发者在PC上使用RKNN-Toolkit2将ONNX模型转换为RKNN格式，并生成可在NPU上执行的二进制指令；随后将RKNN模型文件推送到开发板，由板端的rknn_server或RKNN Runtime加载执行。

理解这一机制对排障至关重要。例如，当模型在PC模拟器上推理正常，但部署到开发板后精度下降，往往是因为模拟器与真实NPU在算子实现细节上存在差异。此外，RKNN-Toolkit2依赖的Python版本、numpy版本、onnx版本都有严格对应关系，版本不匹配会导致API调用失败或转换结果异常。

2.2 操作流程：从零安装RKNN-Toolkit2与配置Python环境

以下操作以Ubuntu 20.04/22.04系统为例，Windows环境下的WSL2方案类似。整个流程分为四个阶段：准备Python环境、安装RKNN-Toolkit2、验证依赖库、连接目标端。

阶段一：创建独立的Python虚拟环境

强烈建议使用虚拟环境，避免系统Python环境被污染。推荐使用Python 3.8或3.10版本，RKNN-Toolkit2官方对这两个版本支持最好。

# 安装python3-venv（如未安装）
sudo apt update
sudo apt install python3.8-venv python3.8-dev -y

# 创建虚拟环境
python3.8 -m venv ~/rknn_env

# 激活虚拟环境
source ~/rknn_env/bin/activate

# 升级pip
pip install --upgrade pip

阶段二：安装RKNN-Toolkit2

RKNN-Toolkit2的安装包可以从瑞芯微官方GitHub仓库或百度网盘获取。推荐使用pip直接安装预编译的wheel包，避免源码编译带来的麻烦。

# 方式一：从GitHub Release下载wheel后安装
wget https://github.com/airockchip/rknn-toolkit2/archive/refs/tags/v2.0.0.tar.gz
tar -xzf v2.0.0.tar.gz
cd rknn-toolkit2/packages
pip install rknn_toolkit2-2.0.0-cp38-cp38-linux_x86_64.whl

# 方式二：直接pip安装（需确认版本号）
pip install rknn-toolkit2==2.0.0

安装完成后，可以通过以下命令验证是否安装成功：

python -c "from rknn.api import RKNN; print('RKNN-Toolkit2 imported successfully')"

阶段三：验证依赖库（onnx、numpy、opencv）

RKNN-Toolkit2在模型转换时需要解析ONNX模型，因此必须安装onnx库。同时，numpy和opencv用于数据预处理与后处理。建议安装以下版本组合：

注意：numpy版本过高（如1.24+）可能导致RKNN-Toolkit2内部某些API调用报错，因为其依赖的旧版C扩展可能不兼容。如果遇到 module 'numpy' has no attribute 'bool' 之类的错误，请降级numpy。

阶段四：连接开发板或模拟器

RKNN-Toolkit2支持两种目标端：模拟器（Simulator）和开发板（Board）。模拟器集成在PC工具包中，无需额外硬件，适合快速验证模型转换结果；开发板则需要通过ADB或网络连接。

模拟器使用：在初始化RKNN对象时，指定 target='rk3588' 即可使用模拟器进行推理，无需任何额外配置。

开发板连接：首先确保开发板已烧录系统并启动，然后通过USB线连接PC。使用ADB命令检查设备是否识别：

adb devices
# 输出示例：
# List of devices attached
# 0123456789ABCDEF    device

如果设备未显示，请检查USB驱动或尝试更换USB端口。连接成功后，需要在开发板上启动 rknn_server 服务（通常系统已预装），然后PC端通过ADB forward命令建立通信通道：

adb forward tcp:6000 tcp:6000

在Python代码中，初始化RKNN对象时指定 target='rk3588' 和 device_id='0123456789ABCDEF' 即可。

2.3 案例拆解：一次完整的依赖验证与模拟器推理测试

下面通过一个实际案例，演示如何验证环境是否搭建成功，并完成一次简单的ONNX模型模拟推理。假设我们有一个训练好的YOLOv5s.onnx模型（输入尺寸640x640）。

背景与目标：验证RKNN-Toolkit2环境可用性，并确认ONNX模型能被正确解析和转换。

操作步骤：

1. 编写验证脚本 test_env.py，内容如下：

import numpy as np
import cv2
import onnx
from rknn.api import RKNN

# 1. 检查依赖库版本
print("numpy:", np.__version__)
print("opencv:", cv2.__version__)
print("onnx:", onnx.__version__)

# 2. 创建RKNN对象，使用模拟器
rknn = RKNN(verbose=True)
rknn.config(target_platform='rk3588')

# 3. 加载ONNX模型
ret = rknn.load_onnx(model='yolov5s.onnx')
if ret != 0:
    print("模型加载失败")
    exit(1)

# 4. 构建RKNN模型（模拟器模式）
ret = rknn.build(do_quantization=False)
if ret != 0:
    print("模型构建失败")
    exit(1)

# 5. 初始化模拟器运行时
ret = rknn.init_runtime(target='rk3588')
if ret != 0:
    print("模拟器初始化失败")
    exit(1)

# 6. 构造输入数据并推理
img = np.random.randint(0, 255, (640, 640, 3), dtype=np.uint8)
outputs = rknn.inference(inputs=[img])
print("推理输出shape:", [o.shape for o in outputs])

# 7. 释放资源
rknn.release()
print("环境验证通过！")

执行与结果分析：运行 python test_env.py，如果输出各依赖库版本号、模型加载成功、推理输出shape为 [(1, 25200, 85)]，则说明环境完全正常。如果出现 ImportError 或 RuntimeError，则根据错误信息回溯排查。

常见问题与处理：

• 错误：libGL.so.1: cannot open shared object file —— 缺少OpenCV的图形库依赖，执行 sudo apt install libgl1 libglib2.0-0 解决。
• 错误：onnx version mismatch —— 检查onnx版本是否在支持范围内，必要时降级。
• 错误：E RKNN: rknn_init_runtime failed —— 模拟器初始化失败，可能是目标平台设置错误，或模型构建时量化参数异常。

复盘经验：在正式项目开始前，务必先跑通此最小验证流程。它能在10分钟内暴露80%的环境问题，避免后续在模型转换阶段浪费时间。

2.4 常见误区与总结复盘

在环境搭建过程中，开发者常陷入以下误区，导致后续开发受阻：

总结复盘：环境搭建的本质是建立一条“PC工具链 → 目标端运行时”的可靠通道。建议按照以下清单逐项确认：