📚 课程目录第4章环境搭建与依赖准备

4. 环境搭建与依赖准备

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创建独立虚拟环境，可以隔离依赖、避免版本污染，同时便于后续环境迁移与复现。

经验提醒：建议使用Python 3.8或3.10作为基准版本。3.8兼容性最广，3.10在性能与库支持上更均衡。避免使用Python 3.12+，因为部分RKNN-Toolkit2版本尚未适配。

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与板端版本一致性。

风险提示：不要混用不同版本的Toolkit2与Runtime。即使模型转换成功，板端也可能出现未知错误或精度异常。建议使用Rockchip官方发布的配套版本组合。

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 .. && make

4.2.3 常见误区与总结

误区1：忘记链接librknnrt.so，导致编译通过但运行时提示找不到符号。
误区2：使用PC端本地库路径，而非交叉编译的aarch64库路径。
误区3：未将librknnrt.so拷贝至板端/usr/lib或程序同目录。

  总结：交叉编译的关键在于工具链前缀（aarch64-linux-gnu-）与库路径的正确指向。建议将RKNN Runtime的include和lib目录单独存放，避免与PC端x86库混淆。

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_demo

4.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核对，避免盲目拷贝驱动。

风险提示：部分工业网关使用定制内核，官方预编译驱动可能不适用。务必从设备厂商或Rockchip SDK获取匹配的驱动源码进行编译。

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驱动的内核匹配性，是三个最容易出错的环节。建议在项目启动初期就建立环境清单文档，记录所有组件的版本号与安装路径，并在每次环境变更后重新执行验证命令。只有两端环境完全就绪，后续的模型转换、量化调优和板端验证才能高效推进。