1. Ubuntu 虚拟机里搭 rknn-toolkit 到底在解决什么问题如果你手上有一块 RK3588、RK3568 或者更早的 RK1808 开发板想把训练好的 ONNX、PyTorch、Caffe 模型丢上去跑推理中间必须经过一步把通用模型转成瑞芯微自家格式的.rknn文件。这个转换动作不是在板子上做的而是在一台 x86 的 Ubuntu 机器上用rknn-toolkit或rknn-toolkit2完成。所以「Ubuntu 虚拟机 rknn-toolkit 环境搭建」这件事本质是给自己准备一台能稳定做模型转换的 PC 端工作机。为什么强调虚拟机因为很多人主力是 Windows直接装双系统麻烦用 WSL 又会碰到 USB、图形库、Python 编译链的兼容问题。开一台 Ubuntu 虚拟机快照随时回滚装崩了直接还原对反复折腾 Python 版本和依赖的人来说是最省心的方案。我自己的做法是 VMware 或 VirtualBox 开一个 Ubuntu 20.04分配 4 核 8G 内存、60G 磁盘转换中小模型完全够用。这里要先分清两个工具选错了后面全白搭。rknn-toolkit面向 RK1808、RK3399Pro 这类老芯片Python 版本偏旧3.6/3.7rknn-toolkit2面向 RK3562、RK3566、RK3568、RK3588 这一代Python 支持到 3.9 甚至更高。判断标准很简单看你的板子型号然后去对应的 GitHub release 页面确认。本文以rknn-toolkit2为主线因为它覆盖现在绝大多数新板子同时把老版本的差异点标出来。还有一个新手最容易忽略的坑PC 端转换用的 toolkit 版本必须和板端 runtime 版本一致。比如你 PC 上用 2.3.0 转出来的 rknn板端rknn_toolkit_lite2或librknnrt也得是 2.3.0差一个小版本都可能报版本不匹配。所以搭环境时第一件事不是急着 pip install而是先确定你要锁定的版本号后面所有依赖都围绕这个版本走。适合谁看这篇刚拿到 RK 板子、准备跑第一个自训练模型的嵌入式/AI 应用开发者被 Python 编译、SSL 报错、依赖冲突折磨过的同学以及想把这套环境做成可复用、能写进 CI 或团队文档的人。下面从零开始命令都能直接复制。2. TaoToken 前置准备把模型转换和调试链路先打通搭 rknn 环境本身是纯本地操作但实际做模型转换时你大概率会遇到两类需要外部模型服务的场景一是拿一个现成的对话模型帮你解释报错、生成转换脚本二是做多模态 demo 时需要调用云端大模型 API 做结果比对。这时候如果本地没有稳定的 API 入口调试节奏会被打断。我习惯在开始折腾环境前先把 API 侧的东西配好避免中途来回切换。TaoToken 在这里的角色是一个统一的模型 API 接入层它把不同厂商的模型能力收敛成一套 OpenAI 兼容的接口。对做 RKNN 转换的人来说最实用的点在于你可以用同一套base_url和 key去调用对话模型帮你排查 Python 依赖冲突也可以在写转换脚本时让模型帮你补全rknn.config()的参数。它不是什么神秘工具就是一个能省掉多平台注册、多 key 管理的入口。具体怎么接核心就三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址后面不加任何多余路径OpenAI 兼容的客户端会自动拼/v1/chat/completions。API Key 在控制台生成生成后只显示一次记得立刻存到环境变量里别硬编码进脚本。Model ID 按你需要的模型填比如做代码解释就选对应的代码模型。我建议把 key 写进 shell 配置而不是每次 exportecho export TAOTOKEN_API_KEYsk-你的key ~/.bashrc source ~/.bashrc这样在虚拟机里开任何终端都能直接用。如果你用的是 Python 的 openai 库可以这样验证连通性from openai import OpenAI import os client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api ) resp client.chat.completions.create( model你的模型ID, messages[{role: user, content: 用一句话解释 rknn 是什么}] ) print(resp.choices[0].message.content)跑通这段说明你的 API 链路没问题。后面转换脚本报错时直接把 traceback 贴给模型让它帮你定位是 numpy 版本还是 onnx opset 的问题比纯靠搜索引擎快很多。需要生成 key 的话去控制台页面接入细节看官方文档这两个入口在下面 CTA 里都有。这里要提醒一句API 只是辅助调试别把它当成转换流程的一部分。rknn 转换是纯本地计算不依赖网络。把 API 配好是为了让你在遇到 Python 环境问题时有个随叫随到的帮手而不是让转换过程去联网。3. 可复制配置conda 环境、依赖锁定与 rknn-toolkit2 安装这一节是全文的核心目标是一次装好、可复用。我强烈建议用 conda 而不是系统自带 Python因为 rknn-toolkit2 对 Python 版本和 numpy 版本很敏感conda 能给你一个干净隔离的环境装崩了删掉重建就行不会污染系统。先装 Miniconda虚拟机里没有的话wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3 $HOME/miniconda3/bin/conda init bash source ~/.bashrc然后创建专用环境。RK3588 这一代建议 Python 3.8 或 3.9我实测 3.8 兼容性最稳conda create -n rknn python3.8 -y conda activate rknn接下来锁定关键依赖。rknn-toolkit2 官方 requirements 里对 numpy、onnx、protobuf 都有版本要求直接pip install rknn-toolkit2有时会拉最新版导致冲突。我的做法是先手动钉住几个基础库pip install numpy1.23.5 protobuf3.20.3 onnx1.14.0 -i https://pypi.tuna.tsinghua.edu.cn/simplenumpy 别上 2.x很多转换脚本还停留在 1.x 的 APIprotobuf 3.20.x 是兼容性最好的区间4.x 经常和 onnx 打架。装完基础库再装 toolkitpip install rknn-toolkit22.3.0 -i https://pypi.tuna.tsinghua.edu.cn/simple如果你拿到的是官方 whl 包而不是走 pip 源直接本地安装pip install rknn_toolkit2-2.3.0-cp38-cp38-linux_x86_64.whl注意 whl 文件名里的cp38必须和你的 Python 版本对应linux_x86_64对应你的平台。如果文件名平台标识和系统不匹配比如带linux2014而系统只认linux_x86_64可以手动改名后再装这个技巧在老版本 toolkit 上很常用。为了可复用把环境导出成文件团队其他人或换机器时一键还原conda env export rknn_env.yaml还原时conda env create -f rknn_env.yaml如果你更习惯用 requirements 锁定可以生成一份精简版pip freeze requirements_lock.txt这里给一个我实测可用的requirements_lock.txt关键片段供对照numpy1.23.5 onnx1.14.0 protobuf3.20.3 opencv-python4.8.1.78 rknn-toolkit22.3.0装 opencv 时如果报libGL.so.1找不到补一个系统库sudo apt-get install -y libgl1 libglib2.0-0这一步做完python -c from rknn.api import RKNN不报错环境就算立住了。如果报ImportError八成是 numpy 或 protobuf 版本不对回退到上面钉住的版本即可。4. 验证请求与成功结果用 ONNX 模型跑通一次完整转换环境装好不代表能用必须拿一个真实模型走一遍转换 推理才算验证通过。我用一个极简的 ONNX 模型做演示你可以用自己手头的模型替换。先准备一个测试 ONNX。如果没有可以用 PyTorch 现导一个import torch import torch.nn as nn class TinyNet(nn.Module): def __init__(self): super().__init__() self.fc nn.Linear(10, 2) def forward(self, x): return self.fc(x) model TinyNet().eval() dummy torch.randn(1, 10) torch.onnx.export(model, dummy, tiny.onnx, input_names[input], output_names[output], opset_version12) print(onnx exported)然后写转换脚本convert.pyfrom rknn.api import RKNN rknn RKNN(verboseTrue) # 配置目标平台RK3588 填 rk3588 ret rknn.config( mean_values[[0] * 10], std_values[[1] * 10], target_platformrk3588 ) print(config ret:, ret) # 加载 ONNX ret rknn.load_onnx(modeltiny.onnx) print(load ret:, ret) # 构建 rknn 模型 ret rknn.build(do_quantizationFalse) print(build ret:, ret) # 导出 ret rknn.export_rknn(tiny.rknn) print(export ret:, ret) # 模拟推理验证 import numpy as np input_data np.random.randn(1, 10).astype(np.float32) ret rknn.init_runtime() print(init_runtime ret:, ret) outputs rknn.inference(inputs[input_data]) print(inference output:, outputs) rknn.release()逐段解释关键点。config里的mean_values和std_values要和训练时的归一化一致长度对应输入通道或特征维度填错会导致推理结果偏差巨大。target_platform必须和你的板子一致填错虽然能转出来但板端加载会失败。do_quantizationFalse表示不做量化先用浮点模型验证流程跑通后再开量化。运行python convert.py成功的输出会依次打印config ret: 0、load ret: 0、build ret: 0、export ret: 0最后inference output是一个 list里面是 numpy 数组。只要这几个 ret 都是 0且 inference 有数值输出说明你的环境完全可用。当前目录会生成tiny.rknn文件这就是能推到板子上跑的模型。如果你要验证和板端一致性把tiny.rknn拷到板子用rknn_toolkit_lite2加载喂同样的输入对比输出。两边数值接近浮点模型误差在 1e-3 量级内正常就说明 PC 端和板端版本匹配、转换无误。这一步是很多人跳过但最容易出问题的地方。5. 本篇常见报错排查401、SSL、版本冲突与依赖失败搭这套环境报错基本集中在几个固定位置我把真实遇到过的列出来对照着查。报错一ImportError: libGL.so.1: cannot open shared object file这是 opencv 的经典问题虚拟机最小安装没带图形库。解决sudo apt-get update sudo apt-get install -y libgl1 libglib2.0-0报错二pip 安装时报SSLError或SSL: CERTIFICATE_VERIFY_FAILED虚拟机时间不对或源证书有问题。先校准时间sudo apt-get install ntpdate sudo ntpdate ntp.aliyun.com再换源并加 trusted-hostpip install rknn-toolkit22.3.0 -i http://mirrors.cloud.tencent.com/pypi/simple --trusted-host mirrors.cloud.tencent.com报错三ERROR: Could not find a version that satisfies the requirement rknn-toolkit2多半是 Python 版本或平台不匹配。确认python --version是 3.8/3.9uname -m是 x86_64。如果用的是官方 whl检查文件名里的cp38和平台标识。报错四AttributeError: module numpy has no attribute floatnumpy 装成 2.x 了。降级pip install numpy1.23.5 --force-reinstall报错五TypeError: Descriptors cannot be created directlyprotobuf 相关protobuf 版本过高。钉住pip install protobuf3.20.3 --force-reinstall报错六转换时E build: Catch exception when building RKNN model!看 verbose 日志里具体哪一层不支持。常见是 ONNX opset 太高导出时用opset_version12或更低。也可能是某个算子 RKNN 不支持需要替换或自定义。报错七板端加载报rknn_init fail! ret-6版本不匹配。PC 端 toolkit 和板端 runtime 版本必须一致去两边分别查版本号对齐。报错八API 调用返回 401如果你在用 TaoToken 辅助调试401 一般是 key 没读到或写错。确认echo $TAOTOKEN_API_KEY有值且 base_url 是https://taotoken.net/api不带多余路径。key 泄露了就去控制台重新生成。报错九local proxy failed或连接超时虚拟机网络模式问题。NAT 模式下检查 DNS桥接模式检查网段。这类问题先ping一下外网确认基础连通性再排查 pip 源。报错十reading choices相关解析错误如果你在脚本里解析 API 返回字段路径写错了。OpenAI 兼容格式是resp.choices[0].message.content别漏了[0]。排查顺序建议先看报错关键词定位是环境问题还是模型问题环境问题优先查 numpy/protobuf/opencv 三件套版本模型问题看 verbose 日志的具体算子。把完整 traceback 贴给模型辅助定位比盲猜快得多。6. 把环境固化成可复用资产版本对齐与后续接入环境搭好只是开始真正省时间的是把它变成可复用资产。我自己的做法是每个项目建一个 conda 环境导出rknn_env.yaml和requirements_lock.txt一起进 git换机器或同事接手时两条命令还原。虚拟机本身打一个快照装崩了 30 秒回滚。版本对齐是贯穿始终的红线。PC 端rknn-toolkit2、板端rknn_toolkit_lite2、板端librknnrt三者版本要一致建议在项目 README 里写死版本号比如「本工程锁定 rknn-toolkit2 2.3.0」。转换脚本里也可以加一行版本打印方便排查from rknn.api import RKNN rknn RKNN() print(rknn.get_sdk_version())后续做模型转换时量化是下一个大坑。先用浮点跑通再开do_quantizationTrue准备校准数据集观察量化后精度掉多少。如果掉太多考虑混合量化或换量化算法。这些内容等环境稳定后再展开。如果你在团队里推这套流程建议把 API 辅助调试也标准化统一用 TaoToken 的 base_url 和 key 管理把常见报错的排查 prompt 存成模板新人遇到问题直接套。需要生成 key 去控制台接入方式看文档长期做编码和 Agent 的可以考虑 Coding Plan。环境搭好之后把精力留给模型本身别在 Python 依赖上反复消耗。