★ FEATURED ARTICLE 作为长期折腾边缘计算设备和模型部署的开发者地平线RDK X5这块板子我前后用了快两个月从最初的官方示例跑通到最终把自己训练的YOLOv5模型完整部署上去中间踩了不少坑也沉淀了一套稳定的转换流程。这篇文章就是把整个链路——从PyTorch训练YOLOv5到导出ONNX再到地平线工具链做量化和转换最后在RDK X5的BPU上跑推理——完整拆解出来把我试过的可行方案、关键参数和排查思路全部记录在这里。无论你是刚开始接触模型部署还是已经拿到板子不知道怎么把自己的模型放上去这篇指南都能帮你省下大量摸索时间。1. 整体设计与方案思路1.1 为什么选用地平线RDK X5搭配YOLOv5这套组合先说说选型的逻辑。RDK X5开发板搭载的是地平线旭日5芯片核心算力集中在自研的BPU上标称算力达到10 TOPS并且支持INT8量化模型的高效推理。这块板子最大的特点是它的BPU是专门为神经网络计算设计的尤其适合跑视觉类的目标检测、分类、分割模型。和树莓派这类通用ARM板卡相比同样跑一个YOLOv5s帧率和功耗表现完全不在一个水平线上。YOLOv5虽然已经被YOLOv8甚至YOLOv11抢去了不少风头但在实际部署场景中YOLOv5的生态成熟度、文档完备性以及第三方工具链的兼容性都是目前最好的。特别是针对地平线RDK系列官方示例代码、社区案例、工具链适配资料几乎都是以YOLOv5为基准的。哪怕你最终想用YOLOv8先把YOLOv5这条链路跑通再迁移过去也会顺畅得多。所以我个人建议第一次接触这个平台不要选最新最酷的模型而是要选最稳、最能跑通的模型。这套方案能解决的问题很明确把开发者从训练完模型不知道怎样让它上板子跑起来的困境里解放出来。整个流程的核心链路是PyTorch训练YOLOv5模型导出为通用ONNX格式再通过地平线提供的hb_mapper工具链把ONNX模型转换成BPU可执行的INT8量化模型最后通过地平线的runtime API在RDK X5上调用BPU完成推理。1.2 转换链路全景从PyTorch权重到BPU可执行文件整个转换流程可以抽象为四个阶段。第一阶段是模型训练这个阶段在PC上完成使用标准的PyTorch框架训练YOLOv5模型最终得到PyTorch权重文件.pt格式。第二阶段是格式中转将.pt权重导出为ONNX格式ONNX在这里扮演一个中间表示的角色——它相当于一个通用语言让不同深度学习框架和不同芯片工具链之间能对话。第三阶段是模型转换与量化这是地平线平台最关键的一步通过hb_mapper工具读入ONNX模型进行算子映射、图优化、INT8量化等操作最终输出一个.bin格式的模型文件。第四阶段是部署推理将.bin文件放到RDK X5上通过Python或C的runtime API调起来输入图像数据输出检测结果。这里有个核心概念需要理解为什么一定要量化。BPU虽然算力强但它本质上是为定点的低精度计算优化的主要支持INT8这种量化后的数据格式。所以如果你的模型是FP32精度的BPU无法直接运行。量化过程就是把网络中的权重和激活值从32位浮点数压缩到8位整数这个压缩会带来少量精度损失但能换来几倍的推理速度提升和更低的显存带宽占用。对YOLOv5这种检测模型来说只要量化校准做得好mAP掉点可以控制在2-3个百分点以内对于大多数应用场景完全可接受。整体方案还有一个值得注意的设计点开发和部署最好分离。模型训练和转换在PC上完成推荐GPU机器RDK X5只负责最终的推理。这样分工清晰调试效率也更高。你不需要在开发板上装PyTorch或训练环境板子上只需要地平线的runtime库和对应的Python包就够了。2. 环境准备与模型训练实操2.1 开发机环境配置YOLOv5训练环境搭建在开始之前先把环境明确一下。训练和转换模型建议使用一台配备NVIDIA GPU的Linux机器我使用的是Ubuntu 20.04系统。PyTorch版本推荐不低于1.10我在实际操作中使用的是PyTorch 1.13.0配合Python 3.8CUDA 11.7。YOLOv5建议直接从官方GitHub仓库拉取选一个稳定release分支。不要用最新的master代码因为有些更新可能会带来兼容性问题。创建好环境之后依次安装依赖。在YOLOv5根目录下有requirements.txt直接执行pip安装即可。需要注意如果你的GPU驱动版本较低最好根据官方表格安装对应版本的PyTorch我最初直接在默认源安装最新版PyTorch结果CUDA版本不匹配程序能跑但训练速度很慢后来换成匹配版本才正常。数据集准备是训练环节的基石。YOLOv5要求数据集目录按特定结构组织images目录存放图片labels目录存放yolo格式的txt标注文件每个txt文件中每行代表一个目标格式是类别id x_center y_center width height前两个值是中心点坐标归一化结果后两个值是宽和高归一化结果取值范围都在0到1之间。训练集和验证集分别放在train和val子目录下并通过一个data yaml文件来引用。2.2 修改YOLOv5源码配置类别数和超参数调整拿到自己的数据集后需要修改YOLOv5源码中的两处配置。第一处是数据配置在data目录下新建一个自己的yaml文件比如我建的是custom_data.yaml内容包含train和val路径、类别数量nc、以及类别名字列表names。第二处是模型配置YOLOv5根据模型大小分成了yolov5s、yolov5m、yolov5l等规格这些配置在models目录下。我用的yolov5s.yaml只需要把里面的nc改成自己的类别数其他结构参数如深度倍数和宽度倍数保持不变即可。还有一个常被忽略的点是预训练权重。如果你从零开始训练训练收敛速度会非常慢。建议下载YOLOv5官方提供的COCO预训练权重由于知识蒸馏和迁移学习的存在用预训练权重微调能让模型在更少的epoch内达到更好的精度。下载完把yolov5s.pt放到YOLOv5根目录训练时会自动加载。这里有个坑预训练权重是COCO 80类的模型你的nc如果不同训练代码会自动丢弃最后的检测层权重并随机初始化这个机制是YOLOv5内置的不用手动处理。超参数方面训练命令中关键参数包括--data指定数据配置--weights指定预训练权重--epochs指定训练轮数--batch-size指定批次大小。batch-size要根据GPU显存调整我使用GTX 1080Ti11GB显存batch-size设置为16时刚好合适。初始学习率默认是0.01训练过程中会通过余弦退火策略自动调整一般不需要手动干预。图片尺寸--img默认是640这个值直接关系到后续部署时的输入尺寸我建议训练和部署统一使用640省去后续resize带来的精度损失。我需要特别强调一下这个统一输入尺寸的概念。很多人在训练时用640部署时为了追求速度把输入改成320或416导致检测精度明显下降。原因在于模型对训练时的分辨率有适应性训练时看到的是640尺寸下的目标特征推理时突然降低分辨率小目标可能就检测不到了。所以我的建议是训练和部署的输入尺寸保持一致要么都用640要么都用你确定部署时能接受的最小尺寸。2.3 训练过程监控与模型评估训练命令执行后训练过程会输出每一轮的loss和mAP指标。常见的输出包括box_loss、obj_loss、cls_loss以及precision、recall、mAP50、mAP50-95等。我个人习惯重点看验证集mAP50和mAP50-95mAP50指IoU阈值取0.5时的平均精度mAP50-95则是从0.5到0.95以0.05为步长取多个阈值计算的平均精度后者对模型定位精度要求更高。训练结束后在runs/train目录下会生成exp文件夹里面保存了best.pt和last.pt两个权重。best.pt是验证集上表现最好的模型权重last.pt是最后一个epoch的权重。部署时务必使用best.pt不要用last.pt这是很多新手会犯的错误。此外exp目录下还生成了很多可视化图表包括confusion_matrix.png混淆矩阵、results.png训练曲线图、val_batch0_labels.jpg和val_batch0_pred.jpg检测效果图等。我一般先看results.png确认训练正常收敛再看几张检测效果图确认模型确实学到了有效特征最后才进入导出部署环节。一个值得留意的训练细节是如果数据集中目标尺寸比较大且分布均匀训练100个epoch左右就足够了但如果包含较多小目标建议训练200到300个epoch并且打开--multi-scale数据增强选项让模型在不同输入尺寸下都能学到目标特征这会显著提升小目标检测能力。3. 模型转换核心环节详解3.1 ONNX导出步骤与参数选择模型训练完成拿到best.pt之后第一步是把PyTorch模型导出为ONNX格式。YOLOv5官方提供了现成的export.py脚本省去了手写torch.onnx.export的麻烦。在YOLOv5根目录执行以下命令python export.py --weights runs/train/exp/best.pt --include onnx --opset 11 --img 640 --simplify这里面有几个参数要想清楚。--opset是ONNX算子集版本地平线工具链对ONNX算子集有版本要求我建议用11兼容性好且功能覆盖足够。--simplify参数会调用onnx-simplifier对计算图做简化移除冗余节点这对后续工具链的解析有帮助。如果系统提示缺少onnxsim直接pip install onnxsim即可。导出完成后会生成best.onnx文件。在转换之前强烈建议先用onnxruntime在PC上验证导出是否正确排除ONNX本身的问题。验证的核心代码思路是用cv2读取一张测试图做与训练时相同的前处理resize到640x640、归一化到0到1之间然后输入onnxruntime的session运行推理检查输出张量的维度。YOLOv5导出的ONNX输出形状通常是(1,25200,85)其中25200是三个检测层在不同尺度上预测的锚框总数85等于5(四个坐标加一个物体置信度)加上80个类别置信度。如果你的类别数是自定义的这个维度会相应变化。3.2 地平线工具链安装与hb_mapper配置编写ONNX验证通过后终于进入地平线工具链的环节。RDK X5对应的是地平线OpenExplorer工具链官方提供了完整的docker镜像推荐在docker内完成模型转换这样环境隔离最干净。把下载好的OE工具链docker镜像导入并启动容器将best.onnx和校准图片目录挂载进去然后进入转换环节。hb_mapper的核心输入是一个yaml格式的配置文件。这个配置分为三大块模型参数、校准参数、编译参数。模型参数部分最关键指定onnx模型路径、输入节点的名称和输入张量的尺寸[1,3,640,640]这里有一个你必须注意的坑输入尺寸的维度顺序是NCHW也就是第一个维度是batch1第二个是通道3第三个和第四个是高和宽640,640。很多人在写这个地方时弄反成NHWC导致转换出来的模型根本无法推理。校准参数部分需要指定校准数据集路径和预处理方法。地平线工具链通过校准数据统计激活值的分布范围为INT8量化确定合适的量化参数。校准数据集建议从训练集中随机抽取200到500张图片覆盖不同光照、不同角度、不同目标大小的场景。不要直接用整个训练集当校准集那样校准时间太长也没有必要。编译参数部分需要指定BPU的架构类型。RDK X5使用旭日5芯片对应的BPU架构是伯努利架构。在配置中要填写正确的架构参数同时可以设置优化等级比如开启模型压缩级别的优化。3.3 校准数据集准备与INT8量化原理量化原理其实可以这样理解一个神经网络在前向推理时层与层之间的特征图数据是一个连续的浮点数分布INT8量化就是找到合适的缩放因子把这个浮点数范围压缩到-128到127之间的整数。关键在于找缩放因子的过程这叫校准。校准的做法是给模型喂一批有代表性的输入图片统计每一层输出的实际数值分布范围然后根据这个分布确定每个张量的量化比例系数。校准数据的选择直接决定量化质量。我用过一次全用纯色背景图的校准集结果量化后的模型检测效果一塌糊涂几乎什么都检测不出来。原因是纯色图没有覆盖到特征图激活值的真实分布范围量化参数完全偏离。后来换成从训练集随机抽300张真实场景图效果立刻正常了。所以校准数据一定要有代表性宁可数量少一点也要保证种类的多样性。实际执行校准命令非常简单在容器内执行hb_mapper makertbin --config hb_mapper_config.yaml命令执行后工具链会先进行模型解析和算子映射检查如果遇到不支持的算子会报错这一步常见于某些自定义层或较新的激活函数。如果报错需要回到源码替换不支持的算子或者修改模型的局部结构。YOLOv5相对保守的模型结构在地平线工具链中兼容性很好基本不会遇到算子不支持的致命问题。转换完成后输出目录中会生成model.hbm文件也可能命名为xxx.hbm这个文件就是可以在RDK X5上被BPU加载执行的最终模型。同时生成的还有模型信息json文件里面有算子部署的详细统计包括哪些算子在BPU上跑哪些算子回退到了CPU。转换完成后仍然建议在PC端做一次精度验证。具体做法是使用地平线提供的仿真器接口加载.bin模型跑一遍验证集对比原始PyTorch模型的mAP。如果量化后的mAP掉点在5%以内属于正常范围如果超过这个值就需要调整校准数据或考虑使用量化感知训练不过后者复杂度较高非必要不建议一上来就上。4. 部署推理与性能调优实战4.1 RDK X5板卡环境准备与runtime库安装模型转换成.hbm文件后把它拷贝到RDK X5上部署工作才算正式开始。RDK X5到手后建议先使用官方系统镜像烧录SD卡并完成基础网络配置。地平线RDK X5出厂系统镜像中通常已经预装了大部分运行时环境但为了保险起见我建议通过SSH连接开发板之后检查一下关键包是否安装。需要确认的Python包包括hobot_dnn模型推理接口、hobot_codec编解码接口用于处理摄像头数据、hobot_visual可视化组件。如果没有安装可以通过pip安装对应的whl包。安装完这些用官方自带的示例模型先做一次推理测试确认BPU驱动和runtime工作正常再投入自己的模型调试。这一步能有效缩小问题范围——如果官方模型能跑说明平台没问题问题在模型转换环节如果官方模型都跑不通那就要先检查系统环境和runtime安装。部署推理我采用的是Python接口。hobot_dnn提供了简单直观的API核心代码逻辑是创建模型句柄读取图像进行预处理调用推理解析输出。下面是一段最简化的推理代码骨架用于说明整个调用流程from hobot_dnn import pyeasy_dnn as dnn model dnn.load(/path/to/your/model.hbm) # 读取图像并预处理 img cv2.imread(test.jpg) img_resized cv2.resize(img, (640, 640)) input_data img_resized.astype(np.float32) / 255.0 # 根据模型输入要求调整数据布局 input_data np.transpose(input_data, (2, 0, 1)) input_tensor np.expand_dims(input_data, axis0) # 推理 outputs model.run(input_tensor)这段代码只展示了推理主干真实项目中还需要处理模型输入的具体格式要求。这里要说一个非常关键的细节地平线工具链转换模型时输出模板的维度顺序不一定和你训练时ONNX的输出一致。YOLOv5的ONNX输出是(1,25200,85)但在BPU上可能被拆分成多个输出张量分别对应不同的属性。这种情况下加载模型后需要打印model.outputs的信息了解每个输出张量的shape和layout再对应写后处理代码。4.2 输出后处理从BPU输出到检测框后处理是部署中最容易让人栽跟头的一环。YOLOv5的原始输出是密集的预测结果需要经过解码和NMS非极大值抑制才能得到最终的检测框。解码过程需要知道锚框信息。YOLOv5有三个检测层每层的锚框尺寸是预定义的分别对应不同尺度的目标。在PyTorch推理中这些锚框在模型内部自动生成和处理但在BPU部署中模型输出的是经过解码前的原始特征这些锚框的计算需要你在后处理代码中手动实现。我在第一次部署时因为没有正确处理锚框解码输出的检测框比实际目标大了一圈。排查后发现是解码公式中的归一化方式没对应上。YOLOv5的解码逻辑是预测框中心坐标 (sigmoid(tx) * 2 - 0.5 grid_x) * stride宽高 (sigmoid(tw) * 2)^2 * anchor。这个公式必须在后处理中严格复现。有几个前人的部署方式是在导出ONNX时修改模型结构把解码和NMS集成到模型内部这样部署端就简单很多。但水下工具体链对这种结构的兼容性我没实际验证过建议还是使用标准导出方式、在后处理中解码虽然代码量多一些但排错更容易。实际项目中如果对实时性要求高建议把后处理写成numpy向量化版本避免Python层面的循环。我自己写的后处理流程包括遍历三个输出层的张量解析类别置信度过滤低置信度候选框经过坐标变换还原到原图尺寸最后执行加权NMS去重。这个过程在RDK X5的CPU上执行对于单帧640x640的图像大约需要10到15毫秒可以接受。4.3 摄像头实时推理demo与性能提升方向如果只是跑单张图片那么部署工作已经完成一大半。但实际项目更常见的是摄像头实时视频流检测。RDK X5上有现成的摄像头接入方案用hobot_codec对接MIPI摄像头或USB摄像头采集的视频帧经过JPEG或NV12编解码后送入BPU推理再在视频流上绘制检测结果。性能方面我在RDK X5上跑YOLOv5s量化模型固态单帧耗时在25到35毫秒之间对应帧率大约在30到40 FPS这个性能对大多数实时检测场景已经够用。如果想进一步榨取性能可以从几个方向优化。第一是预处理优化图像resize和格式转换尽可能使用ROI或GPU加速不要在Python循环里逐像素处理。第二是共享内存和零拷贝机制地平线runtime支持零拷贝输入能省掉数据在CPU和BPU之间的拷贝时间。第三是流水线设计把采集、推理、后处理放到独立线程中用队列连接各个阶段让整体吞吐量最大化。第四是减少NMS的冗余计算比如通过下采样策略降低候选框数量。还有一个容易忽略的优化点是输入图像的分辨率。如果你的业务场景中目标普遍比较大可以尝试把输入尺寸从640降低到416或384推理速度会有明显提升。代价是精度损失这个权衡需要你根据自己的场景和需求反复测试。5. 常见问题排查与避坑经验实录5.1 转换失败类问题速查我把实际操作中遇到的高频问题整理成一张速查表这些问题几乎每一个做模型转换的人都会遇到。问题现象可能原因解决方案hb_mapper报Model parse failedONNX模型结构异常或使用了不支持的算子检查ONNX导出的opset版本尝试重新导出用netron查看模型结构定位问题节点转换成功但精度大幅下降校准数据缺乏代表性或数量不足重新抽取覆盖更多场景的校准图数量控制在200到500张输入输出维度报错配置文件中shape写错或预处理与训练时不一致核对NCHW顺序、输入尺寸、归一化方式转换过程报内存不足docker容器内存限制或图片过大给docker分配更多资源缩小校准图片尺寸推理结果全为0或全为背景后处理解码错误或预处理偏差确认数据归一化、通道顺序、均值方差参数5.2 精度与性能的平衡策略关于量化后的精度损失我观察到的一个规律是YOLOv5s模型量化后mAP掉点通常比YOLOv5m更明显原因是模型越小表达能力越弱对量化的容错空间越小。如果你的业务对精度要求很高可以考虑直接训练YOLOv5m虽然推理速度慢一档但量化后的精度表现会更稳。还有一个值得尝试的方向是使用地平线提供的混合量化能力即对某些敏感层保持FP16或FP32推理只对大部分算子做INT8量化。这需要对工具链有更深入的理解但对于那些就差两三个点精度的场景这是一根重要的救命稻草。不过这个功能需要确认当前工具链版本是否支持以及BPU架构是否具备混合精度计算能力。5.3 独家避坑技巧最后分享几条实操中得到的独家经验。第一条模型转换的docker镜像版本务必与板卡上的runtime版本配套。曾经有一次我用了新版工具链转换模型但板卡系统镜像里的runtime库是旧版导致模型加载直接报版本不匹配。应对方法是在转换前先确认板卡系统的工具链版本下载对应配套的OE镜像。第二条保存好每一步的中间产物。我习惯的目录结构是原始.pt文件、导出的.onnx文件、转换用的config.yaml、校准图片集、量化后的.hbm文件全部归档放在同一个项目目录并记录版本。这样一旦出现问题可以快速定位是哪个环节产生的问题不用从头重新跑。第三条也是最重要的一条模型训练阶段就要考虑部署约束。训练时启用YOLOv5的--hyp参数调整数据增强强度不要用过强的马赛克增强或旋转增强因为过度增强会让模型学到的特征分布与真实场景偏差过大量化时分布校准困难量化后的精度损失会更明显。我踩过一次坑训练时开了很强的Mosaic增强部署后发现模型对正常场景的检测效果反而比测试集表现差不少后来降低了增强强度问题才缓解。第四条关于板卡的散热问题。RDK X5在跑实时推理时发热比较明显如果不加散热片或风扇长时间高负载运行可能会触发降频导致推理速度下降。实测中我加装一个小型散热风扇后持续运行4小时以上推理帧率稳定没有出现性能衰减。这个细节虽然和模型转换无关但对于想长期稳定运行的部署项目至关重要。做了这么多轮模型部署实验我的感受是模型转换这件事工具链和平台能力越来越成熟但真正决定部署效果好坏、效率高低的还是你对模型结构细节的掌握程度和对工具链配置参数的敏感度。跑通第一个模型靠的是运气跑通第二个、第三个模型靠的就是对整个流程的深入理解。这套从训练到部署的流程我现在一个下午就能完整走一遍希望这篇指南也能帮你达到同样的效率。
阅读完成 · 觉得有帮助？
