4、环境搭建与依赖准备：在PC和RK工业网关上配置Python环境、安装RKNN-Toolkit2、交叉编译工具链及板端运行库
RKNN模型部署链路中，环境搭建是决定后续开发效率与调试成本的关键前置环节。本章聚焦于RK工业网关（以RK3568/RK3588系列为核心）的部署环境准备，涵盖PC端Python虚拟环境、RKNN-Toolkit2安装、交叉编译工具链配置，以及板端RKNN Runtime运行库的部署。我们将以“PC端负责模型转换与量化，板端负责推理执行”的双端架构为主线，梳理从零搭建到验证可用的完整流程。
上图展示了双端环境的核心组件与数据流向。PC端负责模型转换、量化及交叉编译，板端负责模型加载与NPU推理。两端通过SSH/scp传输模型文件，并通过串口或网络日志进行验证反馈。下面我们将分步骤详细展开每个环节的配置方法与注意事项。
4.1 PC端Python环境与RKNN-Toolkit2安装
4.1.1 核心原理：为什么必须使用虚拟环境
RKNN-Toolkit2依赖特定版本的Python、NumPy、OpenCV等库，且不同版本的RKNN-Toolkit2对Python版本有严格限制（如v1.6.0支持Python 3.8~3.11）。直接使用系统Python容易导致依赖冲突，尤其当开发机同时承担其他深度学习任务时。使用venv或conda创建独立虚拟环境，可以隔离依赖、避免版本污染，同时便于后续环境迁移与复现。
4.1.2 操作流程：从零创建虚拟环境并安装
# 1. 安装Python虚拟环境工具（如已安装可跳过）
sudo apt update
sudo apt install -y python3-venv python3-dev
# 2. 创建并激活虚拟环境
mkdir -p ~/rknn_env && cd ~/rknn_env
python3 -m venv rknn_venv
source rknn_venv/bin/activate
# 3. 升级pip并安装基础依赖
pip install --upgrade pip
pip install numpy==1.24.3 opencv-python==4.8.1.78
# 4. 安装RKNN-Toolkit2（以v1.6.0为例）
# 从Rockchip官方或Gitee获取wheel包
pip install rknn_toolkit2-1.6.0-cp38-cp38-linux_x86_64.whl
# 5. 验证安装
python -c "from rknn.api import RKNN; print('RKNN-Toolkit2 imported successfully')"4.1.3 案例拆解：版本不匹配导致的转换失败
某项目组在PC上安装了RKNN-Toolkit2 v1.5.2，而板端Runtime为v1.6.0。转换后的.rknn模型在板端加载时报错E RKNN: unsupported rknn version。排查过程：
- 初始现象：模型转换成功，但板端初始化失败，日志显示版本不兼容。
- 分析判断：检查两端版本号，发现Toolkit2与Runtime存在跨版本差异。
- 实际操作：将PC端Toolkit2升级至v1.6.0，重新转换模型，板端加载正常。
- 结果对比：升级后推理结果与PC端模拟输出一致，精度损失在预期范围内。
- 复盘经验：建立版本清单文档，每次部署前核对PC与板端版本一致性。
4.2 交叉编译工具链配置
4.2.1 核心原理：为什么需要交叉编译
RK工业网关通常采用ARM架构（aarch64），而开发机为x86_64。直接在板端编译C/C++程序效率低下且资源受限。交叉编译即在PC上使用aarch64-linux-gnu工具链，编译出可在ARM平台运行的可执行文件。对于RKNN应用，交叉编译主要针对C API的推理程序（如使用rknn_init、rknn_run等接口）。
4.2.2 操作流程：安装工具链与CMake配置
# 1. 安装交叉编译工具链
sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
# 2. 安装CMake（建议3.16以上）
sudo apt install -y cmake
# 3. 编写CMakeLists.txt示例
cat <<EOF > CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(rknn_demo)
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
include_directories(/path/to/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/include)
link_directories(/path/to/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/aarch64)
add_executable(rknn_demo main.cpp)
target_link_libraries(rknn_demo rknnrt)
EOF
# 4. 编译
mkdir build && cd build
cmake .. && make4.2.3 常见误区与总结
- 误区1：忘记链接
librknnrt.so，导致编译通过但运行时提示找不到符号。 - 误区2：使用PC端本地库路径，而非交叉编译的aarch64库路径。
- 误区3：未将
librknnrt.so拷贝至板端/usr/lib或程序同目录。
4.3 板端RKNN Runtime运行库部署
4.3.1 核心原理：Runtime的组成与作用
板端运行库包含两部分：librknnrt.so（核心推理库）和rknpu.ko（NPU内核驱动）。librknnrt.so负责解析.rknn模型、调度NPU执行、管理内存；rknpu.ko则提供硬件访问接口。两者必须与内核版本匹配，否则NPU无法正常工作。
4.3.2 操作流程：部署与验证
# 1. 将运行库拷贝至板端（通过scp或U盘）
scp librknnrt.so root@<板端IP>:/usr/lib/
scp rknpu.ko root@<板端IP>:/lib/modules/$(uname -r)/
# 2. 加载NPU驱动
insmod /lib/modules/$(uname -r)/rknpu.ko
# 3. 验证驱动加载
lsmod | grep rknpu
# 应输出：rknpu 相关模块信息
# 4. 设置库路径并运行测试程序
export LD_LIBRARY_PATH=/usr/lib:$LD_LIBRARY_PATH
./rknn_demo4.3.3 案例拆解：NPU驱动加载失败排查
某工业网关在部署时执行insmod rknpu.ko报错Invalid module format。分析过程：
- 初始现象：驱动模块无法加载，dmesg显示版本不匹配。
- 关键输入：板端内核版本为5.10.110，而rknpu.ko编译自5.10.198。
- 分析判断：内核版本不一致导致模块校验失败。
- 实际操作：从Rockchip官方获取与板端内核匹配的驱动源码，重新编译rknpu.ko。
- 结果对比：加载成功后，运行
rknn_demo推理时间从CPU的120ms降至NPU的8ms。 - 复盘经验：部署前先确认内核版本，使用
uname -r核对，避免盲目拷贝驱动。
4.4 环境验证与常见问题速查
| 验证项 | 命令/方法 | 预期结果 | 常见问题 |
|---|---|---|---|
| PC端Toolkit2导入 | python -c "from rknn.api import RKNN" |
无报错 | 依赖缺失，重新安装numpy/opencv |
| 板端Runtime库 | ldconfig -p | grep rknn |
显示librknnrt.so路径 | 库未拷贝或权限不足 |
| NPU驱动 | ls /dev/rknpu |
设备节点存在 | 驱动未加载或内核版本不匹配 |
| 交叉编译程序 | file rknn_demo |
显示ELF 64-bit ARM aarch64 | 使用了x86编译器 |
环境搭建是RKNN部署的“地基工程”。PC端与板端的版本一致性、交叉编译的库路径正确性、NPU驱动的内核匹配性，是三个最容易出错的环节。建议在项目启动初期就建立环境清单文档，记录所有组件的版本号与安装路径，并在每次环境变更后重新执行验证命令。只有两端环境完全就绪，后续的模型转换、量化调优和板端验证才能高效推进。