1. 为什么要在Ubuntu上折腾rknn-toolkit2如果你手头有一块瑞芯微的板子比如RK3566、RK3568、RK3588这些想把训练好的模型部署上去跑推理那rknn-toolkit2基本是绕不开的一环。它的定位很明确在PC端完成模型的转换、量化、精度分析、性能评估最后导出成板子能直接加载的rknn格式。换句话说它是模型从训练框架到NPU硬件之间的那座桥。但这座桥在Ubuntu上搭起来坑比想象中多。我自己前前后后在三台不同配置的机器上装过有Ubuntu 20.04的、22.04的也有在虚拟机里跑的每次都会遇到点不一样的问题。有的是Python版本对不上有的是依赖包版本冲突还有的是numpy版本太新导致推理结果全错。这些问题官方文档不会一条条告诉你只能自己踩。这篇内容适合两类人一类是刚拿到板子、准备做模型部署的嵌入式方向开发者另一类是在Ubuntu上做AI应用、需要把模型往端侧迁移的算法工程师。我会把安装流程、版本兼容性的判断逻辑、以及我实际踩过的坑都摊开讲尽量让你少走弯路。核心关键词就几个Ubuntu、rknn-toolkit2、安装、兼容性全文围绕这几个点展开。2. 安装前的环境盘点与版本选型逻辑2.1 先搞清楚你的板子和工具版本对应关系rknn-toolkit2不是万能适配的它和板子端的rknn-server、NPU驱动之间有严格的版本对应。我见过有人PC端装了1.5.0板子端还是1.3.0的驱动结果连不上报了一堆莫名其妙的错误。所以第一步不是急着pip install而是先确认三件事板子型号是什么对应的NPU驱动版本是多少你要用的rknn-toolkit2版本是哪个这个版本对Python和系统有什么要求一般来说RK3588系列建议用1.5.0以上的版本RK3566/3568用1.4.0或1.5.0都可以。如果你不确定去板子上跑一下cat /sys/kernel/debug/rknpu/version能看到驱动版本号。PC端的toolkit版本最好和板子端驱动版本保持一致或者略高一点点不要跨大版本。2.2 Ubuntu版本和Python版本的选择官方明确支持的是Ubuntu 18.04、20.04、22.04这三个LTS版本。我实测下来20.04是最稳的22.04也能跑但偶尔会有glibc版本相关的警告。如果你用的是24.04目前官方还没正式支持虽然有人硬装成功了但我不建议在生产环境这么干。Python版本这块rknn-toolkit2对Python 3.6到3.10都支持但不同版本对Python小版本的要求不一样。比如1.5.0要求Python 3.6/3.7/3.8/3.9/3.10而1.4.0只到3.9。这里有个关键点不要用系统自带的Python。Ubuntu 20.04自带的是3.822.04自带的是3.10看起来能用但系统Python里有一堆apt装的包版本很旧和rknn-toolkit2的依赖容易打架。我的建议是用conda或者miniconda建一个独立环境Python版本选3.8或3.9。为什么选这两个因为大多数依赖包在这两个版本上轮子最全尤其是onnx、torch这些3.10有时候会遇到某些包还没发布对应wheel的情况。2.3 依赖包的版本陷阱rknn-toolkit2的依赖里有几个包是出了名的容易出问题依赖包推荐版本踩坑说明numpy1.21.x - 1.23.x1.24以上会报np.int不存在因为numpy 1.24移除了这些别名onnx1.10.0 - 1.14.0太新的onnx可能不被toolkit识别太旧的不支持新opsettorch1.10.0 - 1.13.0主要是torchvision的版本要对应不然模型加载会报错opencv-python4.5.x - 4.7.x4.8以上在某些Ubuntu版本上缺libGL库protobuf3.20.x4.x版本和onnx的兼容性有问题这些版本不是随便定的是我在不同机器上反复试出来的交集。你可能会问为什么不用最新版因为rknn-toolkit2的底层用了很多C扩展这些扩展在编译时链接的库版本是固定的你换了新版本ABI对不上轻则warning重则直接segfault。提示如果你已经装了其他AI框架的环境强烈建议新建一个干净的conda环境不要混用。我试过在已有的pytorch环境里直接装rknn-toolkit2结果torch被降级原来的项目跑不了了。3. 手把手安装流程与关键步骤拆解3.1 创建独立Python环境先确保你装了miniconda或者anaconda。如果没有去官网下载对应Ubuntu版本的安装脚本一路回车就行。装完之后conda create -n rknn python3.8 conda activate rknn这里选3.8是因为它在兼容性和稳定性之间平衡得最好。3.9也可以但有些老版本的wheel只出到3.8。3.7稍微有点旧了部分新特性用不了。创建完环境后先升级一下pippip install --upgrade pip但注意pip不要升到24.x以上有些老包的metadata格式不兼容会报Invalid requirement。23.x是比较稳妥的。3.2 安装系统级依赖rknn-toolkit2在安装过程中需要编译一些C扩展所以系统里得有编译工具链和必要的开发库。在Ubuntu上sudo apt update sudo apt install -y build-essential cmake git wget sudo apt install -y libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev这几个库看着不起眼但缺了任何一个opencv-python导入时就会报错。特别是libgl1-mesa-glx在Ubuntu 22.04上默认可能没装而opencv 4.5以上都依赖它。另外如果你打算用toolkit里的可视化功能比如看量化后的精度分析图还需要装libgtk-3-0。不过这个不是必须的看个人需求。3.3 获取rknn-toolkit2的安装包rknn-toolkit2不是直接pip install就能装的它不在PyPI上。你需要从瑞芯微的官方资源里下载whl包。通常是在他们的开发者社区或者GitHub的release页面。下载的时候注意选对版本和Python版本文件名一般长这样rknn_toolkit2-1.5.0-cp38-cp38-linux_x86_64.whlcp38表示Python 3.8linux_x86_64表示64位Linux。如果你下的是cp36的在3.8环境里装不上。下载完之后先别急着装把whl文件放到一个路径里没有中文和空格的目录下。我见过有人放在~/下载/下面结果pip解析路径时因为中文编码问题报错。3.4 安装whl包及其依赖进入你放whl的目录执行pip install rknn_toolkit2-1.5.0-cp38-cp38-linux_x86_64.whl这时候pip会自动去拉依赖但拉下来的版本可能不是你想要的。所以更稳妥的做法是先手动装好关键依赖再装whlpip install numpy1.23.5 pip install onnx1.12.0 pip install onnxruntime1.14.0 pip install torch1.13.0 torchvision0.14.0 pip install opencv-python4.7.0.72 pip install protobuf3.20.3然后再装whl这时候pip会发现依赖已经满足了不会再去动它们。装完之后验证一下python -c from rknn.api import RKNN; print(ok)如果输出了ok说明基础安装没问题。如果报错看错误信息大概率是某个依赖的版本不对。3.5 验证安装是否完整光导入成功还不够得跑一个完整的流程。toolkit自带了一些示例在安装目录的examples文件夹里。你可以找一个简单的onnx模型走一遍加载、构建、导出的流程from rknn.api import RKNN rknn RKNN() ret rknn.load_onnx(modeltest.onnx) ret rknn.config(target_platformrk3588) ret rknn.build(do_quantizationFalse) ret rknn.export_rknn(test.rknn) rknn.release()如果这几步都能跑通说明环境基本可用了。如果卡在某一步看日志里的具体报错通常是某个op不支持或者输入shape不对。注意target_platform这个参数一定要和你实际的板子型号一致。填错了虽然能导出但板子上加载会失败。4. 兼容性问题排查与常见报错处理4.1 numpy版本导致的推理结果异常这是最隐蔽的一个坑。numpy 1.24把np.int、np.float这些别名移除了而rknn-toolkit2内部有些地方还在用。如果你装的是1.24以上导入时可能不报错但推理出来的结果全是乱的或者量化精度极差。我一开始以为是模型的问题换了几个模型都一样后来才发现是numpy版本。降回1.23.5之后结果就正常了。所以如果你发现推理结果和PC端模拟的差距很大先检查numpy版本。pip show numpy如果版本高于1.23.x直接降级pip install numpy1.23.54.2 onnx版本不匹配导致的模型加载失败onnx的版本兼容性主要体现在opset上。rknn-toolkit2 1.5.0支持的opset上限是17如果你用onnx 1.15导出的模型opset是19加载时就会报Unsupported opset version。解决办法有两个一是降onnx版本二是导出模型时指定opset。我一般是在导出onnx的时候就固定opsettorch.onnx.export(model, dummy_input, model.onnx, opset_version12)opset 12是个比较安全的版本大多数toolkit版本都支持。4.3 动态shape和自定义op的处理rknn-toolkit2对动态shape的支持有限尤其是batch维度。如果你的模型输入是[None, 3, 224, 224]加载时可能会报错。解决办法是在导出onnx时固定batch size或者在toolkit的config里指定rknn.config(target_platformrk3588, batch_size1)自定义op的话toolkit支持通过custom_op接口注册但需要你自己实现CPU端的计算逻辑。这个比较复杂一般建议在模型转换前就把自定义op替换成标准op。4.4 常见报错速查表报错信息可能原因解决方法ImportError: libGL.so.1缺libgl1-mesa-glxsudo apt install libgl1-mesa-glxAttributeError: module numpy has no attribute intnumpy版本过高降级到1.23.xUnsupported opset versiononnx opset过高导出时指定opset_version12Segmentation fault依赖ABI不匹配新建干净环境重装RKNN model version mismatchPC端和板子端版本不一致统一版本No module named rknnwhl没装成功检查whl文件名和Python版本是否匹配4.5 虚拟机环境的特殊处理如果你是在VMware或者VirtualBox里跑Ubuntu有几个额外注意点。一是USB设备直通板子连到虚拟机里需要设置USB过滤器不然toolkit连不上板子。二是虚拟机的CPU指令集可能不全某些依赖包在编译时会用到AVX指令如果虚拟机没开启AVX支持会报Illegal instruction。我一般建议在虚拟机里只做模型转换和量化连板子调试还是用物理机。如果非要在虚拟机里连板子确保USB 3.0控制器是开启的并且把板子的VID/PID加到USB过滤器里。5. 实操心得与效率提升技巧5.1 用requirements文件锁定环境每次新建环境都手动装依赖太麻烦而且容易漏。我的做法是第一次装好之后导出requirementspip freeze requirements.txt下次直接pip install -r requirements.txt但注意freeze出来的文件里有些包是系统级的换机器可能装不上。我一般会手动整理一下只保留核心的十几个包。5.2 模型转换的批处理脚本如果你有多个模型要转一个个跑python脚本效率太低。我写了一个简单的shell脚本遍历目录下的onnx文件自动转换#!/bin/bash for onnx_file in ./models/*.onnx; do name$(basename $onnx_file .onnx) python convert.py --model $onnx_file --output ./rknn/${name}.rknn doneconvert.py里就是标准的加载、config、build、export流程。这样一次能转一批省得守着。5.3 量化校准集的准备技巧量化精度很大程度上取决于校准集的质量。我的经验是校准集不用太多100到200张就够了但一定要有代表性。比如你做目标检测校准集里要包含各种场景、各种光照条件下的图片不能全是白天的。另外校准集的预处理要和推理时保持一致。我见过有人校准集用了归一化推理时忘了归一化结果精度掉了一大截。5.4 日志分析的小窍门toolkit的日志输出很详细但也很长。我一般会把日志重定向到文件然后用grep过滤关键信息python convert.py 21 | tee convert.log grep -E WARNING|ERROR|Unsupported convert.log这样能快速定位问题不用在一大堆INFO里翻。5.5 版本升级的注意事项如果你要从旧版本升级到新版本不要直接pip install覆盖。先把旧环境导出requirements然后新建一个环境装新版本。因为新旧版本之间的依赖差异可能很大直接覆盖容易把环境搞乱。升级之后原来的模型可能需要重新转换因为rknn格式在不同版本之间不一定兼容。板子端的驱动也要同步升级不然加载不了新格式的模型。6. 关于兼容性的一些个人体会我在实际使用中发现rknn-toolkit2的兼容性问题八成以上都出在依赖包的版本上。官方文档虽然列了依赖但没有给出具体的版本范围这就导致很多人直接pip install拉下来一堆最新版然后各种报错。踩过几次坑之后我的习惯是拿到一个新的toolkit版本先看它的release note里有没有提到依赖变更然后去它的setup.py或者requirements.txt里看它声明的版本范围。如果没写就按我上面表格里的版本来基本不会出大问题。还有一个体会是不要迷信最新版。瑞芯微的toolkit更新频率不算高但每次更新都可能引入新的兼容性问题。如果当前版本能满足需求没必要追新。我有一台机器到现在还在用1.4.0因为跑得好好的懒得升。最后分享一个小技巧如果你在安装过程中遇到莫名其妙的错误先试试pip install --no-deps只装whl本身然后手动一个个装依赖。这样能精确定位是哪个依赖出的问题比一股脑装完再排查要快得多。