📚 课程目录第2章 RKNN-Toolkit2环境搭建

2、RKNN-Toolkit2环境搭建：安装RKNN-Toolkit2及其依赖，配置Python虚拟环境，验证安装成功

在开始batch size调整与精度验证之前，必须先搭建一个稳定、可复现的RKNN-Toolkit2运行环境。该工具链是Rockchip NPU（如RK3588、RK3566等）模型转换、量化、推理验证的核心软件栈，其环境配置的成败直接决定后续所有精度对比实验的可信度。本节将围绕Python虚拟环境隔离、依赖安装、工具包验证三个关键环节展开，确保读者在10分钟内获得一个干净、可用的模型转换工作台。

2.1 环境准备的核心原理与版本匹配

RKNN-Toolkit2本质上是一个Python包，它通过Rockchip提供的NPU驱动与硬件交互，完成模型解析、量化、编译和推理模拟。其环境搭建的核心原理在于版本匹配：工具链版本、Python版本、操作系统版本、NPU驱动版本四者必须形成兼容矩阵。例如，RKNN-Toolkit2 v1.6.0在Ubuntu 20.04 + Python 3.8下运行稳定，但若换成Ubuntu 22.04 + Python 3.10，则可能出现依赖冲突或API调用异常。

在动手安装前，建议先确认以下信息：

操作系统：推荐Ubuntu 18.04/20.04/22.04 LTS，避免使用Windows或macOS直接安装（官方仅提供Linux版本）。
Python版本：RKNN-Toolkit2支持Python 3.6~3.11，但不同小版本对numpy、onnx等依赖库的兼容性有差异。
目标NPU芯片：RK3588、RK3566、RK3568等芯片对应的驱动版本和工具链版本可能不同。
工具链版本：从Rockchip官方GitHub或百度网盘获取，注意区分v1.x和v2.x的API差异。

经验提醒：建议在项目初期就固定工具链版本，并在团队内共享版本信息。不同版本生成的RKNN模型文件格式可能不兼容，导致后续在板端部署时出现“模型版本不匹配”的错误。

2.2 操作流程：从零搭建RKNN-Toolkit2环境

以下操作流程以Ubuntu 20.04 + Python 3.8 + RKNN-Toolkit2 v1.6.0为例，读者可根据实际环境调整版本号。

更新系统包并安装基础工具

sudo apt update
sudo apt install -y python3-dev python3-pip git cmake
sudo apt install -y libxslt1-dev zlib1g-dev libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1

创建并激活Python虚拟环境
```
python3 -m venv rknn_env
source rknn_env/bin/activate
```
虚拟环境可以隔离不同项目的依赖，避免与系统Python或其他项目产生冲突。激活后，命令行前缀会显示(rknn_env)。
升级pip并安装基础依赖
```
pip install --upgrade pip
pip install numpy==1.24.4 onnx==1.14.1 onnxruntime==1.16.3
```
注意：numpy版本不宜过高，否则可能与RKNN-Toolkit2中的某些C扩展不兼容。

安装RKNN-Toolkit2

# 从官方渠道下载whl包，例如 rknn_toolkit2-1.6.0-cp38-cp38-linux_x86_64.whl
pip install rknn_toolkit2-1.6.0-cp38-cp38-linux_x86_64.whl

如果使用源码安装，则需先克隆仓库并执行pip install -r requirements.txt，再pip install .。

验证安装
```
python -c "from rknn.api import RKNN; print('RKNN-Toolkit2 imported successfully')"
```
若输出成功信息，说明工具包已正确安装。进一步可运行官方示例脚本，如examples/onnx/yolov5/test.py，验证模型转换流程是否通畅。

2.3 案例拆解：一次完整的安装验证过程

以下是一个实际项目中环境搭建的完整记录，帮助读者理解可能遇到的问题及排查思路。

步骤	操作	关键输出/日志	说明
1	检查系统版本	`Ubuntu 20.04.6 LTS`	确认系统满足要求
2	创建虚拟环境	`Successfully created virtual environment`	使用`python3 -m venv`创建
3	安装numpy	`Successfully installed numpy-1.24.4`	固定版本避免冲突
4	安装RKNN-Toolkit2	`Successfully installed rknn-toolkit2-1.6.0`	whl包安装成功
5	导入测试	`RKNN-Toolkit2 imported successfully`	基础导入正常
6	运行示例	`E RKNN: Cannot find librknnrt.so`	缺少运行时库，需设置`LD_LIBRARY_PATH`

在步骤6中，导入工具包成功但运行示例时报错Cannot find librknnrt.so，这是因为RKNN-Toolkit2在推理时需要加载NPU运行时库。解决方法是在~/.bashrc中添加环境变量：

export RKNN_TOOLKIT2_PATH=/path/to/rknn-toolkit2
export LD_LIBRARY_PATH=$RKNN_TOOLKIT2_PATH/rknpu2/runtime/Linux/librknn_api/aarch64:$LD_LIBRARY_PATH

重新加载配置后，示例脚本正常运行，输出模型转换成功的信息。这个案例说明，环境搭建不仅是pip安装，还需要关注运行时库的路径配置。

2.4 常见误区与总结复盘

在环境搭建过程中，以下误区最容易导致后续工作受阻：

忽略虚拟环境：直接在系统Python中安装，导致依赖冲突，且难以复现他人环境。
版本不匹配：盲目使用最新版Python或numpy，导致RKNN-Toolkit2的C扩展编译失败或运行崩溃。
忘记配置LD_LIBRARY_PATH：即使工具包安装成功，运行时仍可能因找不到NPU库而报错。
使用Windows子系统（WSL）：WSL2在USB设备透传和NPU驱动支持上存在限制，建议使用原生Linux或虚拟机。

风险提示：如果后续需要在RK3588开发板上进行板端推理验证，请确保宿主机（x86）与板端（aarch64）使用相同版本的RKNN-Toolkit2和runtime库。版本不一致可能导致模型在板端加载失败或精度异常。

总结复盘：环境搭建的核心是“版本锁定”和“路径配置”。建议在项目开始时，将以下信息记录在README中：操作系统版本、Python版本、RKNN-Toolkit2版本、numpy版本、LD_LIBRARY_PATH配置。这样，当batch size调整后需要重新验证精度时，可以快速复现环境，避免因环境差异导致的精度波动。