RKNN Toolkit 安装与部署：x86 宿主机转换 + 目标板推理
二、安装与部署：x86 宿主机转换 + 目标板推理
推荐的组织方式是「两台机器」：一台 x86_64 的 Ubuntu PC 做转换，一块 Rockchip 开发板做推理。两者的关系可以概括为：
| 角色 | 平台要求 | 装什么 | 产出 |
|---|
| 转换宿主机 | x86_64，Ubuntu（以官方文档给出的版本要求为准） | RKNN-Toolkit2 whl 包、Python 环境 | .rknn 模型、量化结果 |
| 目标开发板 | Rockchip 板卡，ARM64 Linux | rknpu2 驱动、librknnrt.so、rknnlite | 推理进程、逐层输出 |
安装步骤（转换宿主机）
- 确认系统架构与 Python 版本。转换工具是预编译 whl，架构和 Python 小版本对不上会直接装不上：
uname -m
python3 --version
- 建虚拟环境，避免污染系统 Python（工具链对 numpy 等依赖版本敏感）：
python3 -m venv rknn_env
source rknn_env/bin/activate
pip install --upgrade pip
- 从 Rockchip 官方发布的 rknn-toolkit2 仓库/包源取得与你的工具链版本对应的 whl，然后安装。文件名里通常带 Python 版本与平台标记，务必选对：
pip install rknn_toolkit2-xxx-cp38-cp38-linux_x86_64.whl
- 验证安装是否成功。能 import 且打印出版本号即可：
python3 -c "from rknn.api import RKNN; print(RKNN.__name__)"
- 安装 adb，用于把 PC 和开发板连起来做连板调试：
sudo apt-get install -y adb
adb devices
板端准备
- 确认板子上 NPU 驱动已就位。不同内核/固件版本路径可能不同，以官方文档为准：
ls /dev/rknpu*
dmesg | grep -i rknpu
- 把与板端固件版本匹配的
librknnrt.so 放到系统库路径，版本不匹配是最常见的「模型加载失败」根因：
sudo cp librknnrt.so /usr/lib/
sudo ldconfig
- Python 侧装 rknnlite（板端只有推理，没有转换）：
pip3 install rknn_toolkit_lite2-xxx-cp3x-cp3x-linux_aarch64.whl
常见报错与排查
| 现象 | 常见原因 | 排查方向 |
|---|
| 安装 whl 报平台不匹配 | Python 小版本或架构不对 | 核对 cp 标记与 uname -m 输出 |
| 加载模型报版本不匹配 | 转换工具与板端 Runtime 版本不一致 | 统一工具链与 librknnrt.so 版本 |
| 转换时报不支持的算子 | 模型用了 NPU 未实现的算子 | 换等价算子、拆分图或让该层跑 CPU |
| 板端推理结果全错 | 输入 layout、归一化或均值方差与转换时不一致 | 逐层比对，先查预处理 |
| adb 连不上 | USB 权限或 adb 版本问题 | 检查 udev 规则、换线、重启 adb server |
