1. RDK X5 上 hobot_dnn 为什么装不上先看清这个坑如果你正在 RDK X5 上跑自己训练的轻量化语义分割模型大概率会撞上同一个问题hobot_dnn这个库pip 装不了conda 装不了网上搜到的第三方同名包也不是你要的东西。它到底是什么简单说hobot_dnn是地平线 RDK X5 系统镜像里预装的本地推理库负责把.bin模型加载到板端 BPU 上跑推理属于「官方预装、随系统走、不单独发 pypi」的那一类。适合谁适合所有需要在 RDK X5 ARM64 板端做模型部署验证的开发者尤其是从 PyTorch 一路转到 ONNX、再转 RKNN 的那条链路。问题出在哪你不想污染系统 Python 环境于是建了虚拟环境。结果一激活 venvimport hobot_dnn直接报ModuleNotFoundError。原因很直白虚拟环境默认只认自己的site-packages系统预装的库它根本看不见。而hobot_dnn恰恰只躺在系统 Python 的site-packages里不在任何可下载的包源里。你越是想「干净隔离」越是把这个官方库隔离掉了。更麻烦的是整条工具链的割裂。.pth → .onnx → .rknn这一步要用rknn_toolkit2而它只支持 Linux x86_64RDK X5 是 ARM64板端根本装不了。所以转换得在 PC 上做Windows 上装 Docker 拉官方工具链镜像是个可行路子转完把.rknn拷回板子板端只负责推理。推理这一步就绕不开hobot_dnn。这篇就聚焦一件事怎么让虚拟环境正确调用到系统预装的hobot_dnn以及怎么确认你没被第三方同名包覆盖。2. 前置准备定位官方库与 TaoToken 接入在动手改PYTHONPATH之前先把两件事理清楚官方库到底在哪以及后续调试模型时用什么工具链辅助。先说定位。RDK X5 系统 Python 通常是/usr/bin/python3它的site-packages一般在/usr/lib/python3.x/site-packages或/usr/lib/python3/dist-packages。hobot_dnn就在这里面。你可以先用系统 Python 确认它存在# 用系统 python3不是 venv 里的确认 hobot_dnn 存在 /usr/bin/python3 -c import hobot_dnn, inspect; print(inspect.getfile(hobot_dnn))如果这条能打印出路径说明官方库没问题问题纯粹是虚拟环境看不见它。如果这条也报错那要先检查系统镜像是否完整别急着往下走。再说调试辅助。模型转换完、板端推理跑起来之后你经常需要对照模型行为、验证输入输出、排查语义分割的 mask 是否正常。这类「验证模型」的活儿用 TaoToken 的模型对话入口会比较顺手把推理日志、张量形状、报错信息贴进去做交叉确认。地址是 https://taotoken.net/api 模型对话入口在 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。如果你后面要长期在板端做编码和 Agent 类调试可以看 Coding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。注意TaoToken 在这里的角色是辅助你调试和验证不是替代板端推理库hobot_dnn该用还得用。提示系统环境尽量保持干净少装第三方库。系统site-packages里包越少你把它塞进PYTHONPATH时引入的版本冲突就越少。这是后面所有操作的前提。3. 可复制配置把系统 site-packages 接进虚拟环境核心思路一句话在激活虚拟环境后把系统 Python 的site-packages临时追加到PYTHONPATH让 venv 既能用自己的包也能看见系统的hobot_dnn。第一步动态找出系统site-packages路径别硬编码因为 Python 小版本号会变# 找出系统 python3 的 site-packages优先 /usr 开头 SYSTEM_SP$(/usr/bin/python3 -c import site; print(next(p for p in site.getsitepackages() if p.startswith(/usr)))) echo $SYSTEM_SP第二步激活你的虚拟环境然后把上面这个路径塞进PYTHONPATH# 激活虚拟环境 source ~/venvs/rdk_x5/bin/activate # 把系统 site-packages 追加到 PYTHONPATH 最前面 export PYTHONPATH$SYSTEM_SP:$PYTHONPATH # 确认一下 echo $PYTHONPATH这里有个顺序讲究。把$SYSTEM_SP放在$PYTHONPATH前面意味着系统库优先被搜索。如果你希望虚拟环境自己的包优先、只在找不到时才回落到系统库那就反过来写成export PYTHONPATH$PYTHONPATH:$SYSTEM_SP。实测下来对于hobot_dnn这种只在系统里有的库放前面更省心避免被虚拟环境里某个同名包抢先命中。第三步验证import是否真的走到了官方库# 在 venv 里验证 hobot_dnn 来源 python -c import hobot_dnn, inspect; print(inspect.getfile(hobot_dnn))如果打印的路径是/usr/lib/python3.x/site-packages/hobot_dnn/...这类系统路径说明接对了。如果打印的是你 venv 里的路径那说明虚拟环境里混进了第三方同名包得处理掉见下一节。为了让这套配置每次开终端都生效可以写进虚拟环境的激活脚本bin/activate末尾或者单独放一个env.sh# env.sh —— 每次调试前 source 一下 source ~/venvs/rdk_x5/bin/activate SYSTEM_SP$(/usr/bin/python3 -c import site; print(next(p for p in site.getsitepackages() if p.startswith(/usr)))) export PYTHONPATH$SYSTEM_SP:$PYTHONPATH echo PYTHONPATH ready: $PYTHONPATH4. 验证请求与成功结果跑通一次板端推理配置对不对最终要靠一次真实推理来验证。假设你已经把.rknn模型拷到板子上写一个最小推理脚本# test_hobot_dnn.py import numpy as np import hobot_dnn from hobot_dnn import pyeasy_dnn as dnn # 加载模型 models dnn.load(your_model.rknn) print(模型输入:, models[0].inputs[0].properties) print(模型输出:, models[0].outputs[0].properties) # 构造一个符合输入形状的假数据按你模型实际输入改 input_shape models[0].inputs[0].properties.shape dummy np.random.rand(*input_shape).astype(np.float32) outputs models[0].forward(dummy) for i, out in enumerate(outputs): print(f输出{i} 形状:, out.buffer.shape)运行python test_hobot_dnn.py成功的话你会看到模型输入输出的张量属性被打印出来forward返回的buffer形状和你转换时的输出一致。这一步跑通说明三件事都对了hobot_dnn被正确 import、BPU 能加载模型、虚拟环境没有把官方库挡在外面。如果语义分割的 mask 看起来不对别急着怀疑库先确认输入预处理归一化、通道顺序、尺寸和转换时是否一致。这类对照验证可以把输入输出形状和日志丢到模型对话里做交叉检查https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。5. 本篇常见错排查第三方覆盖与多版本共存坑基本集中在这几类逐个对号入座。报错一ModuleNotFoundError: No module named hobot_dnn说明PYTHONPATH没生效或者路径找错了。先echo $PYTHONPATH确认系统site-packages在里面再ls $SYSTEM_SP | grep hobot确认库文件真的在那。注意别在没激活 venv 的情况下 export那样只对当前 shell 有效。报错二import 成功但行为异常或提示符号找不到大概率是虚拟环境里装了第三方同名hobot_dnn把官方库覆盖了。用这条查真实来源python -c import hobot_dnn, inspect; print(inspect.getfile(hobot_dnn))如果路径指向 venv 的site-packages直接卸载第三方包pip uninstall hobot_dnn报错三多版本共存某个依赖库版本冲突系统库和 venv 库可能装了同一个包的不同版本。查一下谁被真正加载pip list | grep 包名 python -c import 包名, inspect; print(inspect.getfile(包名))对照两个路径判断命中的是系统版还是 venv 版。必要时调整PYTHONPATH里系统路径和 venv 路径的先后顺序。报错四rknn_toolkit2在板端装不上这不是hobot_dnn的问题是工具链本身只支持 x86_64。转换在 PC 上做Windows 装 Docker 拉官方镜像板端只跑推理。别在 RDK X5 上硬装rknn_toolkit2方向就错了。现象根因动作import 失败PYTHONPATH 未含系统路径重新 export 并验证import 到错库第三方同名包覆盖查路径并卸载版本冲突系统/venv 双版本查加载路径调顺序工具链装不上架构不支持PC 端转换板端推理注意每次新开终端都要重新 source 激活脚本PYTHONPATH不会自动保留。这是最容易忘的一步。6. 后续接入与工具链衔接板端推理跑通之后如果你要继续做模型验证、日志分析、或者把调试流程串成长期可复用的编码工作流可以按需接入 TaoToken 的对应入口。验证模型行为、对照输入输出用模型对话https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。需要管理密钥、对接 API去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。长期在板端做编码和 Agent 调试看 Coding Planhttps://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入细节查文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。回到 RDK X5 本身这套「系统库 虚拟环境」的接法不只适用于hobot_dnn。任何官方预装、不发 pypi 的本地库思路都一样先定位系统site-packages再通过PYTHONPATH把它接进隔离环境最后用inspect.getfile确认命中的是官方版本而不是第三方覆盖。把这三步固化成脚本换板子、换 Python 版本时改一下路径就行。
