简介：面向在RDK X5上初探YOLOv5部署的开发者，这份轻量源码包精准对应了从开发环境搭建、数据集训练到模型量化过程中的关键配置需求，尤其适合刚接触地瓜平台的新手对照官方文档快速起步。资源包含3个文件，涵盖inscode环境描述、HTML格式的说明页面以及Git忽略规则文件，整体压缩包仅6KB，虽小巧却为部署流程中最容易出错的工程化细节提供了直接参考。目前已有623人学习使用，是许多入门者边看教程边动手时的常用配套。通过该源码包，读者可以直观获得一套可复用的配置文件结构，了解如何在WSL2与Docker环境下组织项目文件，同时规避因.gitignore设置不当导致的路径混乱问题。对于希望将YOLOv5真正跑在RDK X5上并关注工程可维护性的初学者，这套源码能为开发者省去重复摸索底层配置的时间，更快聚焦算法本身。
1. 先别急着跑推理：RDK X5 部署 YOLO 前要先想清楚的事
说到 RDK X5 部署 YOLO，很多人的第一反应是“模型扔进去就能跑”，实际做下来最耗时间的反而不是推理代码，而是模型转换那一关。这块板子的推理主力是板载 BPU 加速单元，它只认识转换后的 .bin 模型，不认 .pt 也不认 .onnx；要让 YOLO 在 X5 上跑出实时帧率，得先在主机端把模型“翻译”成 BPU 能执行的指令和数据布局。本文按这条真实落地的路径来写：环境怎么铺、源码怎么组织、模型怎么量化、板端怎么推理、常见问题怎么排查，最后落到验证和调优。适合想在一块边缘 AI 开发板上跑实时 YOLO 的开发者，也适合已经拿到板子但一直没把工具链走通的人。先把路径看明白，再动手敲命令，能少走一大半弯路。
2. 铺好 RDK X5 + YOLO 的部署环境：工具链选型与源码目录规划
2.1 谁在跑模型：BPU 和 CPU 的分工决定了方案能不能成
部署前先想清楚一个核心问题：YOLO 到底跑在哪。RDK X5 上跑 YOLO 常见有两条路径，一是直接在 CPU 上推理，开发成本低，把模型用常规推理框架加载就能出结果，但性能上不去；二是把模型迁移到 BPU 上，让卷积类算子跑在神经网络加速单元里，推理耗时能降一个数量级，这是大多数一线方案的首选。
BPU 擅长卷积、激活、池化这类规整算子，但对动态形状、复杂控制流、某些特殊后处理算子支持有限。所以工程上最常见的做法是“异构”：模型的主干和检测头的卷积部分交给 BPU，后处理里的解码、NMS、坐标映射留给 CPU。这样既拿到 BPU 的高吞吐，又避开工具链对复杂算子的兼容性问题。
| 部署路径 | 开发成本 | 推理性能 | 适用场景 |
|---|---|---|---|
| CPU 直接推理 | 低 | 中等 | 功能验证、非实时检测 |
| BPU 部署（异构） | 高 | 高 | 连续视频流、多路实时检测 |
我一般会直接选 BPU 部署，哪怕前期多花两天搞工具链，后面跑视频流的时候就知道值了。源码工程的目录结构也应该按这个分工来设计，模型相关的一层，预处理和后处理单独一层，方便后面调试性能和替换模型。
2.2 板端环境检查：先确认系统状态再往下走
拿到 RDK X5 开发板，刷完系统镜像后先在板端终端执行三条命令，确认基础环境，再开始部署。这三条命令决定了后面几步能不能继续：
# 板端终端执行：先确认系统版本、内存余量和内存规划 cat /etc/os-release | grep VERSION= free -m dt_mem --show第一条看系统版本，确认当前镜像是不是 LTS 版本，有些新镜像工具链兼容性反而要单独确认。第二条看内存余量，部署 YOLO 后模型运行时会占一部分连续内存，如果 free 显示可用内存太少，后面推理大概率会报分配失败。第三条dt_mem --show是查看内存规划，能看到系统给 BPU 预留了多少连续内存；如果显示为 0 或者明显偏小，推理时加载 .bin 模型就会失败。
提示：dt_mem的用法在不同镜像里略有差异，看到命令找不到时先用dt_mem --help看当前镜像支持的子命令，别急着换工具。
2.3 用一个干净的源码工程组织部署：目录结构与各文件职责
标题里带 [源码]，这一步就得把源码工程组织好。很多新手习惯把所有脚本堆在一个目录里，模型、配置、测试数据混在一起，转换参数改一版丢一版，后面排查问题非常痛苦。我建议的工程结构如下：
rdk_yolo/ ├── configs/ # 模型转换与推理参数 │ ├── yolov8n_convert.yaml # 模型转换配置文件 │ └── infer_config.json # 板端推理参数 ├── models/ # 放导出的 onnx 与转换后的 bin │ ├── yolov8n.onnx │ └── yolov8n.bin ├── scripts/ │ ├── export_onnx.sh # 从训练仓库导出 onnx │ └── convert_bpu.sh # 调 OE 工具链做模型转换 ├── src/ │ ├── infer.py # 板端推理入口 │ ├── preprocess.py # 图像预处理 │ └── postprocess.py # 解码检测框与 NMS └── data/ # 测试图片和视频这个目录结构有几个讲究：configs 单独放，转换参数要纳入版本管理，不要直接改 models 目录里的配置；models 目录只放产物，不放训练代码；src 里把预处理、推理、后处理拆成三个模块，因为后面要调性能时，这三个环节的耗时是要分开统计的。scripts 里的两个脚本也要写成可重复执行的，不要手动敲长命令，不然换了模型就要重新查一遍参数。
把源码工程规划好，后面做模型量化、换 YOLO 版本、调帧率都会省很多事。这也是我从几个翻车项目里总结出来的习惯，目录乱的时候，出问题你根本不知道是配置过期了还是代码被改过。
2.4 主机端装好转换工具链：三分钟自检清单
RDK X5 的模型转换要在 x86_64 的 Linux 主机上完成，不是在板端转换，这是新手最容易理解错的一点。工具链通常以压缩包形式发布，解压后需要确认三件事：可执行文件在不在、Python 依赖装没装、示例工程能不能跑通。
# 主机端三分钟自检：任何一步报错都先停下来解决 oe_onnx_to_bpu --help > /dev/null 2>&1 && echo "tool ok" python3 -c "import sys; print(sys.version)" ls <OE包解压目录>/examples第一条检查转换命令是否可用，如果提示找不到命令，多半是环境变量没配或者解压路径不对。第二条确认主机 Python 版本满足工具链要求，版本不匹配时很多依赖包会装不进去。第三条看 examples 目录，这是最重要的自检项：先跑通工具链自带的 YOLO 示例，再转自己的模型，不要一上来就转自己的 .pt，否则你分不清是模型问题还是工具链问题。
工具链版本号不用纠结，当前拿到的是哪个版本就用哪个版本，关键是转换配置的格式要以这个版本自带的示例为准。后面所有配置文件的写法，我都建议先对照 examples 里的 yaml 改，而不是凭记忆手写。
3. 把 YOLO 模型变成 RDK X5 的 BPU 模型：ONNX 导出、量化配置与编译
3.1 从训练仓库导出 ONNX：输入尺寸先固定下来
把 YOLO 部署到 RDK X5，第一步是从训练仓库导出 ONNX。导出时最关键的一点是：把输入尺寸固定下来，不要用动态 shape。虽然 ONNX 支持动态输入，但 BPU 编译时对动态 shape 的支持很有限，强行用动态 shape 会导致转换失败或性能大幅下降。
# 用训练仓库自带的导出脚本导出固定尺寸 ONNX python3 export.py \ --weights yolov8n.pt \ --format onnx \ --img-size 640 640 \ --batch 1这段命令导出固定 640x640 输入、batch 为 1 的 ONNX 模型。--batch 1是因为实时视频流推理场景下，单帧处理是主流；如果有多路视频流并行，我一般会在板端开多个进程，而不是在模型里加大 batch。导出后先用可视化工具看一眼模型结构，确认检测头的输出节点是哪个，方便后面在转换配置里指定输出名。
提示：导出时如果训练仓库支持“不包含后处理”的选项，务必把后处理留在模型外面。后处理里的 NMS、坐标解码这类操作，在 BPU 工具链里往往不支持或支持得不彻底，强行留在模型里会导致转换失败。常见做法是先让模型只输出原始特征图，后处理全部放到板端 CPU 上做。
3.2 转换配置文件的三个必调参数：预处理一致性是第一原则
导出 ONNX 之后，模型转换的成败几乎全在配置文件里。下面是一份常见的模型转换配置，参数名在不同版本工具链里可能略有差异，但核心逻辑一致：
# 模型转换配置示例，参数名以你当前工具链的示例为准 input_shape: [1, 3, 640, 640] input_type: bgr # 板端输入是 bgr 还是 nv12，要和你实际输入一致 norm_type: mean_scale # 归一化方式：none / scale / mean_scale mean: [123.675, 116.28, 103.53] scale: [0.01712475, 0.017507, 0.01742919] batch: 1三个必调参数，我一个个说。第一个是input_type，它决定了板端喂给模型的图像格式。如果你板端用摄像头采集，走硬件解码得到的往往是 NV12 格式，那就配nv12；如果自己在 CPU 上做颜色转换，配bgr或rgb，但要注意顺序，BGR 和 RGB 弄反了推理结果会乱。
第二个是norm_type和配套的mean、scale。这里要强调一个血泪原则：转换配置里的预处理必须和训练时完全一致。YOLOv8 训练时用的均值方差是什么，转换配置就写什么；如果训练时没有归一化，就配none，不要在板端再额外做一次归一化。很多模型转换成功但推理结果全错，问题就出在这里——数据被归一化了两次，或者均值方差写错。
第三个是batch。实时推理场景下 batch 设为 1 最稳妥，因为 batch 大于 1 时，板端需要考虑多帧对齐和 DDR 带宽，性能不一定线性提升，反而增加内存压力。
| 参数 | 取值 | 影响 |
|---|---|---|
| input_type | bgr / rgb / nv12 | 决定板端输入图像格式，选错直接导致结果错乱 |
| norm_type | none / scale / mean_scale | 决定预处理方式，必须与训练一致 |
| batch | 1 / 2 / 4 | 影响吞吐与内存占用，实时场景默认 1 |
3.3 执行转换：读懂输出里的性能预估，识别不支持的算子
配置文件准备好后，执行转换命令：
# 执行模型转换，输出目录里会得到 bin 模型与相关日志 oe_onnx_to_bpu \ -i models/yolov8n.onnx \ -c configs/yolov8n_convert.yaml \ -o models/转换命令本身不难，难的是读懂输出。转换成功后，目录里至少会有三类产物：模型文件 .bin、模型描述信息、性能预估日志。性能预估日志一定要打开看，里面会写每一层的耗时和总耗时，这是判断模型能不能实时跑的第一个依据。
如果日志里出现UNSUPPORTED、Fallback、NOT_SUPPORT之类字样，说明模型里有 BPU 工具链不支持的算子。这时候不要硬转，先把模型结构打开，找到不支持算子的位置。最常见的处理方式是“拆头”：把检测头里的 DFL、某些特殊 slice 操作从模型里去掉，让模型只保留 backbone 和必要的卷积层，输出原始特征图，后处理全部放 CPU。
转换完成后，先别急着拷到板端，在主机端用工具链自带的模型校验工具跑一遍，输入一张测试图，确认输出结果和原始 PyTorch 模型的输出基本一致。这一步能挡住大部分低级错误，比如颜色顺序反了、归一化不一致。等主机端验证通过，再把 .bin 模型拷贝到板端，进入下一篇推理环节。
4. 在 RDK X5 上跑起 YOLO：加载 BPU 模型与推理代码实现
4.1 推理接口的三个核心对象：输入张量、输出张量、会话管理
板端推理代码不管用什么语言写，核心对象就三个：输入张量、输出张量、模型会话。拿到模型文件后，第一件事不是写业务逻辑，而是搞清楚模型的输入描述和输出描述：输入是 NCHW 还是 NHWC 布局、什么数据类型、有没有归一化要求；输出有几个节点、每个节点的 shape 是什么。这些信息在模型描述文件里有，也可以在运行时通过接口查出来。
我见过不少人在这一步翻车：模型转换配置里写的预处理是一套，板端代码里又按自己的理解做了一套，结果推理结果像随机数。正确做法是：以转换配置文件为准，板端代码严格按配置文件里的input_type和norm_type来准备数据，不要多归一化一次，也不要少做一次通道转换。
4.2 加载模型并完成一次推理：最小可运行骨架
下面是一份板端推理骨架代码。不同版本的运行时 Python 接口函数名会有差异，所以这里给的是通用工程骨架；拿到板子后，先跑通工具链自带示例里的真实调用，再替换成你手头的接口名。”这次部署就是按这个思路来的。
# 板端推理骨架，函数名以你当前运行时版本的示例为准 model = load_runtime_model("/data/models/yolov8n.bin") # 1. 加载 bin 模型 input_tensor = model.input(0) # 2. 取输入张量描述 print(input_tensor.shape, input_tensor.layout) # 打印 shape 与布局 blob = np.zeros((1, 3, 640, 640), dtype=np.uint8) # 3. 申请输入缓冲 blob[0, :, :, :] = preprocess(frame_bgr) # 4. 预处理：resize + 通道转换 input_tensor.copy_from(blob) # 5. 把数据写入模型输入 model.run() # 6. 执行 BPU 推理 out = model.output(0).copy_to_numpy() # 7. 取输出张量 boxes = decode_yolo_out(out) # 8. 后处理：解码+NMS代码逻辑拆开讲。第 1 步加载模型，这一步会做初始化、解析模型结构、申请 BPU 资源，所以耗时会比较长，不能放在循环里。第 2 步到第 5 步是数据准备链路，最关键的是preprocess(frame_bgr)这个函数，它必须和转换配置里的input_type、norm_type严格对应；比如配置里写了bgr + mean_scale，那这里就传 BGR 图像，并且在预处理里做均值方差归一化。第 6 步是真正的推理过程，BPU 执行完所有算子，耗时基本稳定。第 7 步取输出，输出 shape 通常类似(1, 84, 8400)或者拆成多个节点，具体以导出时的检测头结构为准。第 8 步后处理在 CPU 上完成，做坐标解码、置信度过滤和 NMS。
提示：输入缓冲blob要复用一个对象，不要每帧重新np.zeros。每帧重新申请大规模内存，会引入明显抖动，而且可能触发内存碎片，跑几小时后突然分配失败。
4.3 测试一张图片：从推理耗时到输出坐标完整走一遍
推理代码写好后，先用单张图片验证链路。我用一个测试脚本，输入一张包含目标的图片，打印检测框坐标和耗时：
# 单张图片测试：确认检测结果合理后再去测视频流 python3 src/infer.py \ --model models/yolov8n.bin \ --image data/test.jpg \ --config configs/infer_config.json输出里如果检测框能正确框住目标，置信度也和预期接近，说明整个链路通了。如果框的位置乱跑、置信度全部接近 0，先检查预处理，尤其是颜色通道顺序和归一化参数；如果输出 shape 和代码里解的不一致，回 3.1 重新确认导出 ONNX 时检测头的输出节点。单张测试通过后，模型的正确性基本就有保障了。
4.4 推理性能测量：别用 time 命令测第一帧
测帧率时新手容易犯一个错：用time命令测第一次加载模型加推理的耗时，然后拿这个数字当成实时帧率的依据。模型加载要初始化 BPU、申请连续内存、加载权重，这个过程可能要好几百毫秒甚至几秒，而稳定推理阶段单帧只要几十毫秒，两者差了十倍不止。
# 性能测量：排除前几帧初始化开销，统计稳定阶段耗时 import time # 先空跑 5 帧，让模型完成初始化 for _ in range(5): model.run() # 再统计 100 帧的平均耗时 start = time.perf_counter() for _ in range(100): model.run() elapsed = time.perf_counter() - start fps = 100 / elapsed print(f"stable fps: {fps:.2f}")这样测出来的帧率才是部署后的真实水平。如果稳定帧率和你预期差距较大，先回 3.3 看性能预估日志里的总耗时，如果预估耗时本身已经很高，说明模型太大或输入分辨率太高；如果预估正常但实际帧率低，问题多半在预处理链路，尤其是 resize 和颜色转换在 CPU 上耗时过高。性能优化这件事，先找准瓶颈在哪一层，再动手改。
5. RDK X5 部署 YOLO 的五个翻车点：从环境到结果的排查记录
5.1 转换时提示算子不支持，生成的 bin 加载失败
现象：oe_onnx_to_bpu转换过程中报UNSUPPORTED，或者转换成功但生成的 .bin 在板端加载时直接初始化失败。
原因：模型里包含 BPU 工具链不支持的算子，常见于检测头里的 DFL 解码、某些 reshape 和特殊切片操作。
处理：把不支持算子的部分从模型里剥离，只保留 backbone 和常规卷积算子，输出原始特征图。后处理里的解码和 NMS 全部移到板端 CPU 上做。具体操作是导出 ONNX 前，修改检测头代码，在 DFL 之前截断输出。
5.2 模型转换成功，但板端推理结果全错
现象：模型转换一切正常，板端加载正常，但推理输出的置信度全是 0，或者检测框乱飘。
原因：预处理不一致是最常见的原因。具体有两类：一是颜色通道顺序反了，配置里写bgr代码里传rgb；二是训练时的均值方差没有写进配置文件，导致数据分布完全不对。
处理：把训练时的预处理代码原样对照一遍，确认norm_type、mean、scale三个值完全一致。板端做完归一化后，不要再额外做标准化，也不要反过来在配置里做两次。检查方法很简单：用同一张测试图，分别跑原始 PyTorch 模型和板端模型，对比输出特征图的数值范围。
5.3 推理时内存分配失败，模型初始化报错
现象：model.run()时直接报内存分配失败，错误信息里带 cma 或连续内存相关字样。多路视频流场景下更容易出现。
原因：BPU 需要一段连续物理内存，板端系统剩余内存不足，或者同时加载多个模型把预留内存占满了。
处理：先执行dt_mem --show和free -m，确认当前内存规划。如果是系统预留给 BPU 的内存太小，需要调整启动参数，给 BPU 多分一些连续内存；如果是同时运行的进程太多，把推理进程错开，或者复用同一个模型会话，不要每个线程都加载一份模型。
5.4 帧率比预期低一半，BPU 疑似没干活
现象：性能预估日志里模型本身只有 20ms 左右，但实际跑视频流只有 10fps 出头。
原因：瓶颈不在 BPU，而在数据准备链路。最常见的是用 CPU 做 resize 和 BGR 转 NV12，每次预处理耗时超过模型推理耗时；另一个常见问题是每帧新申请输入缓冲，触发内存分配开销。
处理：把预处理里的颜色转换和缩放移到硬件编解码单元完成，视频流输入直接用 NV12 格式喂给模型，省掉一次颜色转换。输入缓冲只申请一次，循环复用。改完后用 4.4 的统计脚本重新测，往往会发现帧率接近性能预估。
5.5 模型加载要好几秒，进程启动太慢
现象：模型加载耗时 3 秒以上，服务启动超时，或者热重启时体验很差。
原因：bin 文件本身比较大，同时运行时初始化要申请多块 buffer，包括权重加载和临时计算缓冲区，这些操作都集中在加载阶段。
处理：把模型加载放到进程启动阶段，不要放在请求处理逻辑里；业务进程常驻，不要频繁重启。如果 bin 文件过大，考虑换更小尺寸的模型，比如从 YOLOv8n 换成更轻量的版本。另外，板端内存充足时可以预留一块固定的 buffer 池，减少加载时的动态申请。
6. 让 YOLO 部署结果真正可用：硬件解码与性能验证的收尾技巧
6.1 视频流别用 CPU 一帧帧读：解码交给硬件单元
单张图片跑通只是第一步，接入视频流后性能问题才会完全暴露。很多人的代码用通用图像库逐帧读视频文件或摄像头，这个做法在 CPU 直推时没问题，但在 BPU 部署场景下会拖垮整体帧率。RDK X5 自带视频编解码硬件单元，通过硬件解码接口取帧，可以把解码从 CPU 卸载掉，让 CPU 只做后处理和业务逻辑。
常见做法是：视频解码输出 NV12 格式的帧，NV12 正好是模型转换配置里input_type: nv12期望的输入格式。这意味着从解码到模型输入之间，不需要做 BGR 转换，直接把解码得到的数据裁剪、缩放后喂给模型。一步省掉两次内存拷贝，帧率提升非常明显。
我最早做视频流部署时，用的还是“通用图像库读帧 + CPU 转 BGR + 模型推理”的链路，结果 1080p 视频只跑到 12fps，后来把解码切到硬件单元，同样的模型直接到 26fps。性能差距不是玄学，是数据链路在 CPU 上堵塞了。
6.2 验证 BPU 是否真的在干活：日志与耗时分布
部署完成后，验证模型到底跑在哪个计算单元上，直接决定你对性能的判断是否可靠。把运行时的日志级别调高，启动时通常会打印模型的调度信息，比如当前模型被分配到哪个 BPU 核心、算子类型统计。如果日志里显示模型的大部分算子都走了 CPU，那你看到的高帧率就不是 BPU 的功劳，后面加一路视频流很快就会被打回原形。
验证时可以单独统计三个阶段耗时：取帧耗时、模型推理耗时、后处理耗时。取帧耗时高，优化硬件解码；模型推理耗时会随帧率波动，但整体应稳定；后处理耗时高，考虑精简 NMS 实现，比如用向量化计算替代纯 Python 循环。这三个数字分开打日志，线上定位问题时就清楚多了。
我现在的习惯是：部署完模型后的第一件事，不是看检测效果，而是把这三个耗时打出来，先确认数据链路没有在 CPU 上堵住。踩过好几次坑之后，我深刻体会到一件事：边缘部署的优化不是调单个环节，而是把每一段流水线的耗时都摊到最小，让 BPU、解码单元、CPU 各干各的活，别让任何一个单元闲着等数据。把这个思路带进你的部署过程，RDK X5 跑 YOLO 这件事，就不会只停留在 demo 阶段，而是能真正扛住连续的视频流负载。希望帮到你。
本文还有配套的精品资源，点击获取
