在边缘端跑 YOLOv11n 不是难事难的是把模型真正高效跑在 BPU 上。这篇文章记录我在地瓜派 RDK X5上部署YOLOv11n的完整过程重点拆解两个最坑的地方Softmax 瓶颈和INT8 量化掉点。整个过程踩了不少坑最后终于把模型稳定跑起来推理速度也达到了预期。如果你正准备在 RDK X5、旭日 X5 这类平台上部署 YOLO 系列模型这篇文章大概率能帮你少走两周弯路。我尽量把步骤写到可以直接照着做包括 ONNX 导出姿势、模型结构裁剪、校准数据集准备、hb_mapper 配置、量化精度修复、BPU 推理代码全部给出来。1. 项目背景与整体设计思路1.1 为什么选 RDK X5 跑 YOLOv11n先交代一下选型逻辑。地瓜派 RDK X5 本质上是一块面向端侧 AI 的开发板核心优势是集成了地平线的 BPUBrain Processing Unit神经网络加速单元算力大概在 10 TOPS 这个级别功耗友好适合做边缘视觉类应用。相比 GPU 推理BPU 的核心价值是低功耗、高能效比、确定性延迟尤其适合机器人、工业质检、智能摄像机这类场景。YOLOv11n 是 YOLO 系列里 nano 版本参数量只有 2.6M 左右计算量在 640x640 输入下大约是 6.5 GFLOPs非常适合在端侧跑。对比 YOLOv8nYOLOv11 在检测头里改进了 C3k2 模块和分类头结构精度更高一些但代价是网络结构更复杂对工具链的算子支持要求也更高。我最终选择这个组合的原因其实很朴素RDK X5 性能足够、工具链成熟、社区资料多YOLOv11n 精度和速度的平衡点很好。但实际上手之后才发现模型能跑和跑得快完全是两码事中间至少隔着一个 Softmax 瓶颈和一个量化的门槛。1.2 YOLOv11n 结构里藏着的部署坑先说说我踩的最大的坑Softmax。你可能觉得 Softmax 很常见随手写个算子就完了但 BPU 对 Softmax 的处理方式和 GPU/CPU 完全不同。YOLOv11n 的检测头中有一个关键结构叫 DFLDistribution Focal Loss它内部的积分过程需要用到 Softmax 操作。如果直接把原始的 YOLOv11n ONNX 模型丢给地平线工具链编译工具链会把包含 Softmax 的 DFL 子图切到 CPU 上执行导致整张图只能频繁在 BPU 和 CPU 之间交换数据推理延迟直接翻倍甚至更高。这就是我标题里说的Softmax 瓶颈。后面我会详细讲怎么分析、怎么绕过。另外YOLOv11n 的输出格式也是坑。原始模型输出两个特征图分支分类分支和回归分支尺寸是1x80x8400和1x64x8400。这里的 8400 是三个尺度下的 anchor 总数80 是 COCO 类别数64 是 4 个回归参数乘以 DFL 的 16 个 bins。如果不做解码优化一个 8400 的循环在 CPU 上跑一遍也要吃掉不少时间。1.3 整体部署流程拆解我的落地路径可以分为下面几个阶段后续章节会逐一展开环境准备RDK X5 开发板系统、宿主机 OE 工具链装好ONNX 导出用 ultralytics 导出 ONNX并对 Detect 头做合理裁剪模型改造把 DFL 解码从模型里拆出去避免 Softmax 进 BPU量化校准准备校准集写 hb_mapper 配置生成 INT8 模型编译与性能分析用 hb_perf 分析算子类型和耗时板端推理用 Python API 跑通推理并做后处理解码每一阶段都有坑我把我踩过的都记下来了。2. 开发环境搭建与工具链准备2.1 硬件与版本选型先说硬件。我用的核心板是地瓜派 RDK X5配套底板带网口、USB 3.0、HDMI 输出开发阶段我直接通过 SSH 连进板子操作。板端系统用的是官方 Ubuntu 镜像Python 3.10自带地平线的 runtime 环境。宿主机我用的是一台 x86 的 Linux 工作站主要用来跑模型转换和量化。为什么要在宿主机上做转换因为 hb_mapper、hb_perf 这些工具链需要跑在 x86 上板子只负责推理执行。这个架构要提前搞清楚不然很容易在板子上瞎折腾半天发现根本没装编译工具链。版本方面我建议统一用地平线 OEOpenExplorer平台提供的最新 release 版本。不同版本对算子支持、量化算法、编译优化策略都有差异版本混用最容易出幺蛾子。我当时用的是 OE 2.0 工具链对应 hb_mapper 版本 2.x大家下载时注意看发行说明。2.2 地平线 OE 工具链安装宿主机上需要安装的是地平线的 OE 工具链一般是一个 Docker 镜像或者 Python wheel 包。我图省事用 Docker 方式保证依赖干净避免污染宿主机环境。安装后确认一下核心命令hb_mapper --help hb_perf --help python3 -c from horizon_tc_ui import HB; print(ok)这里的horizon_tc_ui是模型转换与评测的 Python 接口hb_mapper负责把 ONNX 模型转成 board 上可执行的.bin模型hb_perf则用来分析模型编译后的算子分布和耗时估计。注意宿主机工具链版本和板端 runtime 版本一定要匹配。版本不匹配最常见的表现是.bin文件在板子上加载失败报错信息还很难看懂。2.3 模型与训练权重的准备我用的是 ultralytics 官方发布的yolo11n.pt预训练权重。这里有个知识点权重来源一定要可靠。虽然 YOLOv11 的权重有多种渠道但 ultralytics 官方权重在预处理、类别顺序、输出格式上都是标准化的方便后续排查问题。在开始转换前先在宿主机上用 PyTorch 跑一遍推理记录一张测试图的输出结果作为后续 ONNX 输出、板端输出验证的基准。这一步非常关键能帮你在后面快速定位“到底是模型转换出了问题还是后处理解码出了问题”。3. 从 PyTorch 到 ONNX模型导出与起点优化3.1 导出 ONNX 的正确姿势这一步看起来简单其实坑很多。直接用 ultralytics 导出是最快的from ultralytics import YOLO model YOLO(yolo11n.pt) model.export(formatonnx, opset11, simplifyTrue, dynamicFalse)参数选择上opset11是地平线工具链适配性最好的版本simplifyTrue会调用 onnxsim 做一些常量折叠和图优化能去掉很多多余的节点。dynamicFalse必须显式固定BPU 推理不支持动态 shape。导出完成后别急着下一步先用onnxruntime跑一张图验证输出是否和 PyTorch 对齐python3 -c import onnxruntime as ort; sess ort.InferenceSession(yolo11n.onnx); print(sess.get_inputs()[0])检查输入是1x3x640x640输出两个分支。如果输出结构不对或者名字看不懂先用 netron 打开看一眼模型结构再说。3.2 输出端结构分析与 DFL 层去向打开 ONNX 的结构你会看到检测头部分是一堆 Conv、Reshape、Transpose、Softmax 的组合。最核心的一个结构是Conv - Reshape - Transpose - Softmax - Conv - ...这个就是 DFL 的积分过程。回归分支输出的 64 维通道被 reshape 成[N, 4, 16, H*W]然后在 16 这个维度上做 Softmax再和[0..15]的投影向量做加权求和最后得到 4 个回归参数。问题就出在这个 Softmax 上。BPU 不是不能做 Softmax而是地平线工具链在编译时对 Softmax 的实现效率非常差经常直接切到 CPU 执行。一旦切 CPUBPU 和 CPU 之间的数据搬运开销会直接拖垮整条推理链路。我后来的做法是把 DFL 解码从模型里完全拆出去模型只输出原始回归分支的 64 维张量Softmax 和积分放到板端的后处理代码里做。这样模型里就没有 Softmax 节点了整个模型可以完整编译进 BPU效率最高。3.3 用 Python 验证 ONNX 输出正确性拆完模型后我写了一个简单的 Python 脚本用同一张图分别跑 PyTorch 模型和裁剪后的 ONNX对比回归分支输出是否一致。这一步是防止裁剪过程意外改动了前面的权重。关键代码结构如下import onnxruntime as ort import numpy as np # 预处理图片 img preprocess(test.jpg) # 1x3x640x640 float32, RGB, /255 # 原始 ONNX sess1 ort.InferenceSession(yolo11n.onnx) out1 sess1.run(None, {images: img}) # 裁剪后的 ONNX sess2 ort.InferenceSession(yolo11n_crop.onnx) out2 sess2.run(None, {images: img}) for i, (a, b) in enumerate(zip(out1, out2)): print(i, np.abs(a - b).max())如果前面几层输出一致只有检测头被裁剪掉的部分有差异那说明裁剪是安全的。我当时跑出来的结果是裁剪后的输出和原始回归分支输出完全一致这说明权重没有被动过放心进入下一步。4. Softmax 瓶颈深度剖析真正卡脖子的地方4.1 YOLOv11 的 DFL 与 Softmax 到底在哪先把这个结构彻底讲透。YOLOv11 的回归头不是直接输出x1, y1, x2, y2而是输出一个 16 个 bin 的概率分布通过 DFL 积分得到最终的坐标偏移。具体流程回归分支输出形状[N, 64, H, W]Reshape 成[N, 4, 16, H*W]在 16 这个维度上 Softmax得到每个 bin 的概率与固定的投影向量[0, 1, ..., 15]加权求和得到[N, 4, H*W]的坐标偏移量其中第 3 步就是瓶颈的根源。Softmax 本身计算量不大但它对硬件实现不友好。在 GPU 上这是成熟的高优化算子但在 BPU 上工具链支持得很勉强经常被识别为低效算子最终编译到 CPU 上执行。4.2 为什么 BPU 对 Softmax 不友好从硬件架构角度看BPU 是为卷积、ReLU、Pooling 这类规律性强、访存友好的算子设计的。而 Softmax 涉及三件事求最大值、指数、求和、除法。这个计算过程需要跨通道比较数据密集型操作很多并且涉及到非线性的指数运算。BPU 的指令集对这类操作的支持有限工具链必须用一堆基础指令模拟效率远不如 CPU 上经过优化过的实现。更麻烦的是一旦模型里存在 CPU 算子工具链会把整个计算图切成多个子图BPU 子图和 CPU 子图交替执行。每次切换都要搬运中间张量数据量越大开销越大。YOLOv11n 在这个位置的 feature map 是[N, 4, 16, 8400]宽度不大但切来切去也非常影响延迟。4.3 三种绕过瓶颈的改造实践针对这个瓶颈我试验了三种方案最终选了第三种分享给大家参考。方案一保留模型内的 DFL用混合精度编译。优点是不用改模型结构但问题是你得接受 Softmax 被切到 CPU推理速度不理想。实测下来的延迟大约是完整 BPU 推理的两倍多基本不能忍。方案二用 Softmax 的近似替换。用 ReLU 归一化或者乘性近似替换 Softmax精度损失可控但实现复杂而且要重新训练或者至少微调一下才能保证精度。时间成本太高我放弃了。方案三推荐把 DFL 解码挪到后处理。模型输出原始的[N, 64, H, W]回归分支在板端解码循环里做 Softmax 和积分。这样模型内部是干净的卷积 ReLU 结构整图可以全部放进 BPU。CPU 后处理端多出来的计算量在板载 CPU 上跑也就几毫秒完全值得。方案三的代价是你必须在板端实现一段 DFL 解码代码但这段代码逻辑固定写一次到处复用后期调试也更方便。5. 量化实战校准、配置与精度调优5.1 校准数据集与预处理方式模型结构搞定了接下来是量化。地平线的量化方式是 PTQPost Training Quantization也就是用一批校准图片在 INT8 范围内统计激活值的分布据此确定缩放因子。校准集的质量直接决定量化精度。我的经验是图片数量800~1000 张左右是性价比最高的范围。太少容易过拟合到少量样本的分布精度掉得厉害太多收益递减。图片内容一定要覆盖推理阶段可能遇到的实际场景不能全用网络爬的风景图。我做的是行人检测校准集里就专门多选了行人、遮挡、夜间场景的图。图片尺寸统一预处理成 640x640和模型输入保持一致。格式JPEG 或 PNG 均可但预处理代码必须和训练时一致包括 RGB 顺序、归一化方式、letterbox 方式。校准集要单独放一个目录比如calibration_data/hb_mapper 会自动读取。5.2 hb_mapper 配置参数逐项说明接下来是核心环节写 hb_mapper 的 YAML 配置文件。我把关键配置贴出来逐行解释model_parameters: onnx_model: yolo11n_crop.onnx march: bayes-e layer_out_dump: False working_dir: model_output output_model_file_prefix: yolo11n_640 input_parameters: input_type_rt: bgr input_layout_rt: nhwc input_type_train: rgb input_layout_train: nchw norm_type: data_scale scale_value: 0.0039215686 calibration_parameters: cal_data_dir: calibration_data/ cal_data_type: float calibration_type: max max_percentile: 0.9999 per_channel: False compiler_parameters: compile_mode: latency optimize_level: O3 debug: False core_num: 1几个关键点march: bayes-e表示目标 BPU 架构RDK X5 对应的是 bayes 这一代架构。不要填错填错直接编译失败。input_type_rt和input_layout_rt是指板端推理时的输入类型和布局。如果你在板端直接把HWC的 BGR 图喂进去这里就写bgr nhwc如果你按NCHW喂工具链也会帮你转但效率不如直接用 NHWC。norm_type: data_scale scale_value: 0.0039215686表示把 uint8 的像素值乘以 1/255 变为 float。如果你训练时用的是/255归一化这里配置成这样就对。calibration_type: max是量化校准方法。我一开始用默认的 KLD结果精度掉得厉害后来换成max配合max_percentile: 0.9999效果明显改善。原因是 KLD 对激活值分布的形状敏感而max是对绝对值范围的统计在检测任务里更稳。per_channel: False激活值量化用 per-tensor实测更稳定。配置好后执行转换hb_mapper makertbin --model-type onnx --model yolo11n_crop.onnx --config config.yaml如果一切顺利model_output/目录下会出现yolo11n_640.bin和一堆分析文件。第一次跑大概率会有 warning 和 error下面一节讲怎么处理。5.3 量化精度掉点的排查与修复量化之后精度掉点是最常见的坑。我梳理一下排查思路按优先级排序。第一步检查校准集是否过小或单一。如果只用了几十张图激活值统计就不准。先扩充到 500 张以上试试。第二步调整量化方法。从 KLD 换成 max / max_percentile或者反过来试试。这个没有绝对最优要针对你的数据分布做实验。第三步用 hb_perf 看每层的量化误差。hb_perf 可以输出每个节点的耗时、量化前后输出差异。做法是把有问题的节点dump出来找到误差最大的层确认是不是某个 conv 层对量化特别敏感。第四步考虑混合精度。如果只是某些敏感层掉点可以对特定层设置高精度比如 FP16。但混合精度会牺牲一部分性能我建议能不动就不动。我当时的问题很简单校准集质量太差。后来换了一批场景更丰富的图重新校准模型在验证集上的 mAP 从掉点 6% 收窄到 1.5% 以内这就完全够用了。6. 模型编译与 BPU 加速部署6.1 编译产出与 hb_perf 分析转换完成之后除了.bin文件工具链还会生成一个.html或者文本报告里面是模型在 BPU 上的算子信息和预估性能。这个时候一定要用 hb_perf 看一遍hb_perf onnx -m yolo11n_crop.onnx -c config.yaml重点关注两个指标算子类型分布卷积应该占大头Softmax、Einsum、Gather 这类算子数量最好为 0。预估耗时看模型主体推理延迟是否在可接受范围。我第一次跑完 hb_perf发现里面还有 Reshape 和 Transpose 被标成了 CPU 执行后来调整了输入布局从 NCHW 改成 NHWC这些搬运算子才被优化掉了。经验就是尽量让模型的中间张量布局保持四个维度的连续内存不要频繁做转置。6.2 Python 推理示例代码模型编译好之后在 RDK X5 板子上跑推理就简单了。地平线提供了一个 Python 接口horizon_tc_ui可以直接加载.bin并推理。核心代码from horizon_tc_ui import HB import numpy as np import cv2 # 加载模型 model HB(yolo11n_640.bin) # 读取图片并预处理到模型输入格式 img cv2.imread(test.jpg) img cv2.resize(img, (640, 640)) # 简化实际要用letterbox img img[..., ::-1].copy() # BGR - RGB img img.astype(np.float32) / 255.0 img np.expand_dims(img, 0) # 1x640x640x3 NHWC # 推理 outputs model.run([img]) reg_out, cls_out outputs[0], outputs[1]注意这里输入的 shape 是1x640x640x3也就是 NHWC和前面配置里的input_layout_rt: nhwc是对应的。预处理完直接 run输出就是两个张量。后面就是后处理解码。由于我们裁剪掉了 DFL这里需要自己补上def softmax(x, axis-1): e np.exp(x - np.max(x, axisaxis, keepdimsTrue)) return e / np.sum(e, axisaxis, keepdimsTrue) # reg_out: [1, 64, 8400] - [1, 4, 16, 8400] reg reg_out.reshape(1, 4, 16, 8400) reg softmax(reg, axis2) proj np.arange(0, 16, dtypenp.float32).reshape(1, 1, 16, 1) dist np.sum(reg * proj, axis2) # [1, 4, 8400] # cls_out: [1, 80, 8400] - sigmoid cls_score 1.0 / (1.0 np.exp(-cls_out)) # 对每个anchor取最大类别的置信度并做阈值过滤这段代码逻辑不复杂但要注意数据类型板端 CPU 是 float32 比较好算。之后再做 anchor decode也就是把 dist 从偏移量换算成真实坐标这个过程和 YOLOv5/v8 的思路一样不再赘述。6.3 性能调优与实测数据最后说说性能。我实测的纯 BPU 部分推理延迟大概在 11ms 左右640x640INT8单核 BPU加上预处理、后处理、NMS 之后整体端到端延迟约 18~22ms完全可以满足 30FPS 的实时需求。想进一步提升的话有几个方向开启 BPU 双核运行在配置里core_num: 2延迟能再降一些但功耗也会上来。预处理优化把 resize 和 letterbox 改成在板端用 DMA 或者硬件加速方式实现不过这个要看具体 BSP 版本。后处理向量化NMS 用 vectorized numpy 写法替代纯 Python 循环性能提升非常明显。我建议普通应用先别折腾双核单核跑 30FPS 已经够用多花的功耗和发热不值当。7. 常见问题速查与实操经验我把这次踩过的坑整理成一张速查表方便大家定位问题现象可能原因解决方案编译报march错误芯片架构填错确认 RDK X5 对应bayes-e输出结果全 0预处理顺序不对检查 RGB/BGR、NHWC/NCHW 是否和配置一致量化后 mAP 掉很多校准集太小或太单一扩到 800 张以上覆盖实际场景模型里出现 CPU 算子含有 Softmax/DynamicResize裁剪 DFL 解码到后处理.bin在板子加载失败宿主机工具链和板端 runtime 版本不匹配统一工具链版本推理延迟比预期高很多输入布局导致 Transpose 进 CPU板端输入直接用 NHWC别用 NCHW另外几个我从实操里总结的小技巧每次改配置前先清空 working_dir。hb_mapper 会缓存中间结果不清空容易用旧数据覆盖新输出。保存好 ONNX 原始版本。裁剪出错时用来对比输出排查效率翻倍。校准集不要选带大量背景噪点的图。这类图会导致激活值范围异常大量化缩放因子被拉偏。8. 我的实操体会与建议整个项目做下来我最大的体会是在 BPU 上部署模型真正的工作量不在“跑通”而在“让模型结构适配硬件特性”。YOLOv11n 在 PyTorch 里只是几行推理代码但到了 BPU 上一个 Softmax 就能让你从“看起来能跑”变成“跑得很慢”。裁剪 DFL、调整输入布局、精心设计校准集这三件事做好了整个部署项目就成功了一大半。如果你正准备在 RDK X5 或者类似的地平线平台部署 YOLO 模型我建议你从一开始就把 DFL 解码从模型里拆出去把注意力放在量化质量上。不要迷信“端到端导出”也不要盲目堆校准图数量先把配置参数理解透再针对自己的数据集做实验。最后再分享一个小技巧保存你的 yaml 配置和 calibration 预处理脚本到 git 仓库每次实验记录下 mAP 和延迟。量化调优本质上是个实验活没有日志就等于白做。这篇指南里的方法我后来在 YOLOv8s、YOLOv9t 上也验证过思路完全通用只是需要根据具体输出层结构微调裁剪逻辑。希望这些踩坑经验能帮你少走点弯路。