RDK X5边缘计算实战：YOLOv5模型部署与推理性能调优指南

1. 为什么选择RDK X5这条技术路线

1.1 从一堆开发板的对比说起

我第一次拿到RDK X5的时候，手头已经堆了树莓派5、Jetson Nano、RK3588开发板好几块板子。说实话，每次有新板子出来，第一反应不是兴奋，而是"又要重新踩一遍环境的坑"。但RDK X5这块板子有点不一样，它把地平线自家的BPU（Brain Processing Unit）算力做到了10 TOPS，这个数字放在边缘计算场景里相当能打，关键是功耗控制得不错，不需要主动散热风扇就能跑推理。

为什么我最终决定用它来做YOLOv5部署？核心原因有三个。第一是算力与功耗的平衡，10 TOPS的INT8算力跑YOLOv5s这种轻量模型，帧率能稳定在30FPS以上，而整板功耗也就5W左右，这意味着你可以把它塞进一个很小的外壳里做产品原型。第二是工具链的完整度，地平线提供了从模型转换到板端推理的全套工具，虽然文档有些地方写得让人想骂人，但至少路子是通的。第三是价格，相比动辄上千的Jetson Orin系列，RDK X5的性价比对个人开发者和小团队非常友好。

这里要提醒一句，如果你之前只玩过树莓派，那RDK X5的软件生态会让你有点不适应。树莓派的Raspberry Pi OS是开箱即用的，而RDK X5的Ubuntu系统需要你自己配置不少东西。但反过来说，这也意味着你对系统的掌控力更强，不会遇到"系统里预装了一堆用不上的东西还删不掉"的尴尬。

1.2 目标读者与前置知识

这篇内容适合什么人看？如果你满足以下任意一条，那接下来的内容会对你有直接帮助：

• 手里已经有一块RDK X5，但不知道从哪开始折腾
• 想在边缘设备上部署自己训练的YOLOv5模型，但被环境配置卡住了
• 有Python和Linux基础，但对嵌入式部署流程不熟悉
• 做过树莓派项目，想升级到算力更强的平台

前置知识方面，你需要会基本的Linux命令操作，知道什么是SSH、什么是IP地址，Python能看懂代码就行，不需要你手写CUDA内核。如果你连ls和cd都没用过，建议先花半天时间补一下Linux基础，否则后面的操作会非常痛苦。

注意：RDK X5的官方系统是基于Ubuntu 22.04的，如果你之前用的是CentOS或者别的发行版，命令会有差异，别照搬网上的教程。

2. 硬件搭建与系统烧录的实操细节

2.1 开箱清单与配件选择

RDK X5的包装里通常只有一块板子，其他东西都得自己配。我列一下我实际用到的配件清单，以及哪些地方容易买错：

电源这块我要多说一句。我一开始图省事用了一个65W的氮化镓充电头，结果板子跑推理的时候会偶发性重启。后来换了一个标称5V/3A的电源适配器才稳定下来。原因是快充头会跟板子的电源管理芯片协商电压，协商过程中可能出现瞬时掉压。所以别在这上面省钱，一个靠谱的电源也就二三十块。

存储卡的选择同样重要。我试过用一张老旧的16GB卡，烧录系统花了将近40分钟，而换用A2级别的卡之后，烧录时间缩短到8分钟左右。这个差距在反复烧录调试阶段会被放大很多倍。

2.2 系统镜像烧录的完整流程

RDK X5的官方镜像可以从地瓜开发者社区下载，文件通常是一个.img格式的压缩包。烧录工具我推荐用balenaEtcher，跨平台且操作简单，比dd命令安全得多。

具体步骤：

1. 下载镜像后先解压，得到.img文件
2. 打开balenaEtcher，选择镜像文件
3. 选择目标存储卡（千万看仔细，别选成你的移动硬盘）
4. 点击Flash，等待写入完成
5. 写入完成后，把存储卡插入RDK X5底部的卡槽

这里有个细节：烧录完成后，Windows会提示"是否格式化磁盘"，千万别点格式化。那个提示是因为Windows不认识Linux的分区格式，点格式化就把系统毁了。

首次上电的时候，板子上的绿色LED会闪烁，表示系统正在启动。第一次启动会比较慢，因为系统要做分区扩展和初始化，大概需要2-3分钟。如果你等了5分钟还没反应，那就得用串口模块看启动日志了。

2.3 首次登录与网络配置

RDK X5默认的系统镜像通常已经配置好了SSH服务，默认用户名和密码在官方文档里有写。我拿到板子后的第一件事就是通过网线把它连到路由器上，然后在路由器的管理界面找到它的IP地址。

为什么优先用网线而不是WiFi？因为后续你要传模型文件、传数据集，WiFi的传输速度会让你崩溃。一个几百MB的模型文件，WiFi可能要传好几分钟，网线几秒钟就搞定了。

找到IP之后，在你的电脑上打开终端（Windows用PowerShell或者CMD），输入：

ssh username@192.168.1.xxx

第一次连接会提示确认指纹，输入yes，然后输入密码。登录成功后，你就能在终端里操作板子了。

如果你需要配置WiFi，可以用nmcli命令：

sudo nmcli dev wifi connect "你的WiFi名称" password "你的密码"

提示：配置完WiFi后，建议把网线也留着，双网络冗余，万一WiFi断了你还能通过网线连上去。

3. 远程开发环境搭建：SSH与VNC的配合使用

3.1 SSH密钥配置与免密登录

每次SSH都要输密码太麻烦了，而且有些自动化脚本没法交互式输入密码。配置SSH密钥是必须做的第一步。

在你的电脑上生成密钥对（如果还没有的话）：

ssh-keygen -t ed25519 -C "rdk-x5"

一路回车就行，默认保存在~/.ssh/id_ed25519。然后把公钥传到板子上：

ssh-copy-id username@192.168.1.xxx

输入一次密码后，以后SSH就不用再输了。

这里有个Windows用户常踩的坑：bad owner or permissions on c:\users\thinkpad/.ssh/config这个报错。原因是Windows的权限系统跟Linux不一样，SSH对配置文件的权限检查很严格。解决办法是右键点击.ssh文件夹，属性→安全→高级，把所有者改成你自己，然后禁用继承，只保留你自己的完全控制权限。

如果你用的是VS Code，装一个Remote-SSH插件，配置好之后可以直接在VS Code里打开板子上的文件夹，编辑代码的体验比在终端里用vim好太多了。配置方法是在VS Code左下角点击绿色图标，选择"Connect to Host"，输入username@192.168.1.xxx即可。

3.2 VNC远程桌面的安装与调优

SSH只能操作命令行，但有些操作（比如查看图片、调试GUI程序）需要桌面环境。VNC就是干这个的。

在板子上安装VNC Server：

sudo apt update sudo apt install tightvncserver

启动VNC服务：

vncserver :1 -geometry 1920x1080 -depth 24

第一次启动会让你设置一个VNC密码，这个密码跟系统登录密码是分开的，记牢。

然后在你的电脑上下载VNC Viewer，新建连接，地址填192.168.1.xxx:1，输入刚才设置的密码就能看到桌面了。

但这里有个常见问题：VNC桌面默认是灰底黑叉的，没有菜单栏和任务栏。这是因为VNC启动的是一个独立的X会话，没有加载桌面环境。解决办法是修改~/.vnc/xstartup文件，把里面的内容替换成：

#!/bin/sh unset SESSION_MANAGER unset DBUS_SESSION_BUS_ADDRESS exec startxfce4

然后重启VNC服务：

vncserver -kill :1 vncserver :1 -geometry 1920x1080 -depth 24

这样你就能看到一个完整的XFCE桌面了。

注意：VNC传输的是图像数据，网络带宽不够的时候会非常卡。如果你只是偶尔需要看个图，用scp把文件传到本地看更高效。VNC适合需要交互式操作GUI程序的场景。

3.3 文件传输的几种方式对比

部署过程中需要在电脑和板子之间来回传文件，我试过几种方式，各有适用场景：

我平时用得最多的是rsync，因为它支持断点续传，传大文件的时候万一网络断了不用从头再来。命令里的-avz参数分别是归档模式、显示详情、压缩传输，压缩对文本文件效果明显，对已经压缩过的模型文件效果不大。

4. YOLOv5环境配置与模型训练要点

4.1 Python环境与依赖安装

RDK X5的系统里通常预装了Python 3.8或3.10，但YOLOv5对版本有要求，建议用Python 3.8以上。先确认版本：

python3 --version

然后安装pip和虚拟环境工具：

sudo apt install python3-pip python3-venv

我强烈建议用虚拟环境，别在系统Python里直接装包。原因很简单：YOLOv5的依赖跟系统里其他工具的依赖可能冲突，一旦把系统Python搞坏了，恢复起来很麻烦。

创建虚拟环境：

python3 -m venv yolov5-env source yolov5-env/bin/activate

激活后命令行前面会出现(yolov5-env)的标识。然后克隆YOLOv5仓库：

git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt

这里有个坑：requirements.txt里的torch版本默认是GPU版本，但RDK X5上没有NVIDIA GPU，装了也用不了。你需要装CPU版本的torch：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

装完之后验证一下：

python3 -c "import torch; print(torch.__version__)"

能打印出版本号就说明装好了。

4.2 训练自己的数据集：从标注到超参数

YOLOv5训练自己的数据集，流程分四步：标注、转换格式、配置yaml、启动训练。

标注工具我用的是LabelImg，在电脑上装好之后，打开图片文件夹，框选目标，保存为YOLO格式的txt文件。每张图片对应一个txt，里面每行是类别 x_center y_center width height，坐标都是归一化到0-1之间的。

标注完成后，目录结构应该是这样的：

dataset/ ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/

然后创建一个data.yaml文件：

path: /home/user/dataset train: images/train val: images/val nc: 3 names: ['person', 'helmet', 'vest']

nc是类别数量，names是类别名称列表。这里要注意，类别名称的顺序必须跟标注时的类别索引一致，否则训练出来的模型会张冠李戴。

超参数方面，YOLOv5的默认配置在data/hyp.scratch.yaml里。对于小数据集（几千张图），我建议把lr0从0.01降到0.001，epochs设100-300，batch-size根据显存调整。RDK X5上训练是不现实的，算力不够，训练要在你的PC或者服务器上做，训练完再把模型转到板子上推理。

训练命令：

python train.py --img 640 --batch 16 --epochs 200 --data data.yaml --weights yolov5s.pt

--weights指定预训练权重，用yolov5s.pt做迁移学习，收敛快很多。训练过程中可以用TensorBoard看loss曲线：

tensorboard --logdir runs/train

4.3 模型导出与格式转换

训练完成后，最好的权重保存在runs/train/exp/weights/best.pt。这个.pt文件不能直接在RDK X5上跑，需要转换成地平线BPU支持的格式。

转换流程大致是：.pt→ ONNX → 地平线工具链 →.bin。具体步骤：

1. 导出ONNX：

python export.py --weights best.pt --include onnx --img 640

2. 用地平线的hb_mapper工具做模型转换。这一步需要安装地平线的Docker环境，因为工具链只支持在特定版本的Ubuntu上运行。

3. 转换过程中需要提供校准数据集，用来做INT8量化。校准集从你的训练集里随机抽100-200张图就行。

这里有个经验：量化后的模型精度通常会掉1-3个百分点。如果你的应用对精度要求高，可以在转换时选择--calibration_type max，用最大最小值校准，比默认的kl校准精度略好，但速度稍慢。

提示：模型转换是整个流程里最容易出问题的环节。常见错误包括算子不支持、输入尺寸不匹配、校准集格式不对。遇到报错先看日志里的具体算子名称，然后去地平线开发者社区搜，大概率有人踩过同样的坑。

5. 板端部署与推理性能调优

5.1 部署环境准备与依赖安装

模型转换完成后，你会得到一个.bin文件和一个hb_model相关的配置文件。在板子上部署需要安装地平线的推理库：

sudo apt install hobot-dnn

然后把.bin文件和配置文件传到板子上。地平线提供了Python和C++两种推理接口，Python接口上手快，C++接口性能好。我建议先用Python接口验证功能，再用C++做性能优化。

Python推理的核心代码大概长这样：

from hobot_dnn import pyeasy_dnn as dnn import numpy as np import cv2 models = dnn.load('model.bin') model = models[0] img = cv2.imread('test.jpg') img = cv2.resize(img, (640, 640)) img = img.transpose(2, 0, 1) img = np.expand_dims(img, axis=0).astype(np.float32) outputs = model.forward(img)

输出的格式跟YOLOv5的原始输出略有不同，需要做后处理，包括解码边界框、NMS抑制等。地平线的示例代码里有完整的后处理实现，可以直接参考。

5.2 推理性能实测与优化手段

我在RDK X5上实测了YOLOv5s模型在不同输入尺寸下的帧率：

这个数据是在板子只跑推理、没有其他负载的情况下测的。如果你同时跑其他程序，帧率会下降。

优化手段有几个方向。第一是降低输入分辨率，从640降到416，帧率能翻倍，但小目标的检测精度会下降。第二是使用多线程流水线，把图像采集、预处理、推理、后处理分到不同线程，能提升整体吞吐量。第三是模型剪枝，把YOLOv5s里冗余的通道剪掉，模型变小，推理更快，但需要重新训练微调。

我实际项目里用的是512x512输入加多线程流水线，稳定在45FPS左右，满足实时检测需求。

5.3 常见部署问题排查

部署过程中我遇到过的典型问题：

问题一：模型加载失败，报"invalid model"

原因通常是模型转换时用的工具链版本跟板端推理库版本不匹配。解决办法是确认两边版本一致，地平线每个版本的工具链和推理库是配套的。

问题二：推理结果全是乱框

检查预处理是否跟训练时一致。YOLOv5训练时用的是RGB通道，如果你用OpenCV读图默认是BGR，需要转换。另外归一化参数也要一致，通常是除以255。

问题三：帧率远低于预期

先确认板子没有降频。用cat /sys/class/thermal/thermal_zone0/temp看温度，超过80度会触发降频。加个散热风扇能解决。另外检查是不是在跑其他占用CPU的程序。

问题四：SSH连接不稳定，频繁断开

可能是电源供电不足导致的网络模块重启。换一个电流更大的电源试试。也可能是WiFi信号弱，改用网线。

6. 从原型到产品的扩展思路

6.1 模型迭代与数据闭环

部署上线只是开始，真正让模型越用越准的关键是数据闭环。我的做法是在推理程序里加一个"难例保存"逻辑：当检测置信度在0.3到0.6之间时，把这张图保存下来，定期人工标注后加入训练集重新训练。

这个策略的效果非常明显。我做一个安全帽检测的项目，第一版模型mAP只有0.72，经过三轮数据闭环迭代后，mAP提升到了0.89。关键是这些难例数据是模型自己"挑"出来的，比随机采样效率高得多。

6.2 多模型协同与业务逻辑编排

RDK X5的算力跑一个YOLOv5s绰绰有余，但实际项目里往往需要多个模型协同。比如先跑一个人体检测，再对检测到的人跑姿态估计，最后根据姿态判断是否违规。

这种场景下，你需要设计一个任务调度逻辑。我的做法是用一个主循环，按优先级依次调用不同模型，高优先级的模型每帧都跑，低优先级的隔帧跑。这样能在有限算力下平衡多个任务的需求。

6.3 长期运行的稳定性保障

产品原型和实际部署最大的区别是运行时长。原型跑几个小时就关了，实际部署可能要7x24小时运行。长期运行要关注几个点：

• 内存泄漏：Python程序长时间运行容易内存增长，定期重启进程能缓解
• 日志轮转：日志文件不清理会占满存储卡
• 看门狗：加一个硬件看门狗或者软件心跳检测，程序卡死时自动重启
• 温度监控：夏天高温环境下要确保散热

我在实际项目里加了一个简单的shell脚本，每小时检查一次程序是否在运行，不在就拉起来。同时用logrotate配置日志轮转，保留最近7天的日志。

最后分享一个我在调试阶段常用的小技巧：在板子上开一个tmux会话跑推理程序，这样即使SSH断了，程序也不会停。重新连上后tmux attach就能回到之前的会话。这个习惯帮我省了很多次重新启动程序的时间。