简介面向有一定深度学习基础的开发者这套资源提供了基于YOLOv8的目标检测与实例分割实战项目使用ONNXRuntime完成高效推理借助OpenCV处理图像输入输出覆盖模型加载、预处理、推理到结果可视化的完整链路。压缩包内共52个文件大小约7.46MB主要包含cpp源码、h头文件、sample示例、CMake构建脚本、README说明及测试图片其中yolov8_onnx、yolov8_seg_onnx、yolov8_obb_onnx等模块可分别实现检测、实例分割和旋转框检测main.cpp作为统一入口工具类封装了前处理与后处理逻辑便于按需裁剪或扩展。项目还附有模型放置说明与示例图像用户只需放置对应ONNX模型即可运行示例配合zidane.jpg、bus.jpg等图像快速验证效果代码采用模块化设计注释清晰适合作为YOLOv8工程化入门的参考模板或二次开发基础。目前已有508人学习下载能帮助读者理解C环境下ONNXRuntime与OpenCV的协作方式以及从模型部署到实际推理的完整流程。1. 拿到这个项目实战包先明白ONNXRuntime和OpenCV在这里各自站什么岗这个标题把部署路线写得很直白YOLOv8负责模型能力ONNXRuntime负责推理引擎OpenCV负责图像侧的一切杂活。把训练好的pt权重转成ONNX再搭配ONNXRuntime和OpenCV实现目标检测与实例分割是CPU机器、Windows工控机、边缘盒子上最干净的一套配合。部署机不需要装PyTorch不需要GPU模型导完后只剩一个onnx文件加一个推理动态库无论做上位机还是嵌入式都容易集成。本文面向两种情况一是你已经用YOLOv8训练过模型想把推理部分抽出来接到自己的图像处理程序里二是正在Ubuntu 20.04这类环境里做CPU评估想知道这条路线能不能跑通、快不快、坑在哪里。我会把目标检测和实例分割分开讲因为它们的ONNX输出结构完全不同后处理写错一个维度结果就是框能出但mask全黑。2. 把ONNXRuntime和OpenCV装到能跑模型选型依据、版本配套和验证命令2.1 为什么部署阶段要换掉PyTorch一张对比表看清分工常见做法是把模型权重视作一个黑匣子部署机上只留推理引擎和图像库。PyTorch推理不是不行而是它在产线机器上太重装完torch、torchvision以及一堆传递依赖体积大到让人头疼如果现场机器没有GPUCPU上的表现也未必比ONNXRuntime好。另一个更现实的问题是你的采集程序、界面程序不一定用Python写而ONNXRuntime有C接口OpenCV更是图像处理的事实标准两者可以直接嵌进一套C工程里。OpenCV在这个标题里的定位是做推理之外的所有杂事读图、缩放、填充、颜色通道转换、画框、画mask甚至NMS都能用cv2.dnn.NMSBoxes解决。ONNXRuntime只负责把ONNX模型跑起来两者不冲突。方案部署机依赖CPU推理表现后处理适合场景PyTorch直接推理torch全家桶体积大算子没有专门优化自己写或用ultralytics内置函数训练机调试、快速验证ONNXRuntime CPU只有一个动态库线程池、算子融合后表现务实OpenCV或numpy工控机、服务器、边缘盒OpenCV DNNopencv自带dnn模块看版本部分算子支持不全OpenCV一条龙简单demo复杂模型容易受限选ONNXRuntime还有个额外收益模型一旦导出成ONNX训练框架和推理框架就解耦了。今天用YOLOv8明天换YOLOv5一样导成ONNX后处理逻辑几乎不用动。2.2 版本配套关系onnxruntime、onnx、opencv之间别各装各的这里最容易翻车的是onnx和onnxruntime的版本错位。ONNX文件里带了IR版本和opset版本ONNXRuntime解析模型时对算子版本有要求opset太低新算子不认opset太高旧版runtime不认。我一般会把组合锁在一个区间里组件建议区间原因Python3.93.11onnxruntime对新版本Python的预编译包发布速度慢半拍onnxruntime1.161.18CPU版直接pip安装aarch64也有官方包onnx1.141.16和onnxruntime的IR解析配套opencv-python4.84.10新版本NMSBoxes返回值有变化后面专门讲ultralytics8.08.2训练和导出保持同版本最省事注意onnxruntime和onnxruntime-gpu是两个包标题里这套方案大概率不需要GPU。如果你在GPU机器上导出、在CPU机器上推理完全没有问题甚至推荐这么做导出机器跑一次就行部署机只装runtime。Ubuntu 20.04上只用CPU搭这套环境和Windows没有本质区别pip安装即可。如果遇到鲲鹏920这类ARM服务器优先看onnxruntime官方有没有对应的aarch64 wheel没有的话再走源码编译编译时用CMAKE_BUILD_TYPERelease这一步不是必须的多数场景下官方预编译包够用。2.3 最小依赖安装和验证命令先确认三个库能一起工作依赖清单里不需要装ultralytics除非你要在部署机上导出模型。给一份我常用的requirements.txtonnxruntime1.17.3 onnx1.16.1 opencv-python4.9.0.80 numpy1.26.4安装命令pip install -r requirements.txt装完先跑一个就绪检查确认onnxruntime能正常创建会话、OpenCV能正常读图import onnxruntime as ort import cv2 import numpy as np print(onnxruntime:, ort.__version__) print(opencv:, cv2.__version__) print(providers:, ort.get_available_providers())get_available_providers()会打印CPUExecutionProvider如果有GPU机器还会看到CUDAExecutionProvider。这一步的意义在于提前暴露动态库冲突问题很多人装完opencv后import报错多半是之前装过opencv-contrib-python或老版本残留建议在虚拟环境里重装一遍。2.4 拿到onnx文件后先做一次空跑把输入输出shape打出来从模型包或训练目录拿到yolov8.onnx后先别急着写完整推理代码写个几行脚本把模型的输入输出结构打出来import onnxruntime as ort sess ort.InferenceSession(yolov8n.onnx, providers[CPUExecutionProvider]) for inp in sess.get_inputs(): print(input:, inp.name, inp.shape, inp.type) for out in sess.get_outputs(): print(output:, out.name, out.shape, out.type)这一步能直接回答两个问题输入是不是[1,3,640,640]输出是几个分支。目标检测模型通常只有一个输出实例分割模型会有两个输出形状大概像[1,116,8400]和[1,32,160,160]。看到这两个数字后面后处理就好写了。3. 目标检测从模型文件到可信框导出ONNX、letterbox和输出解码3.1 导出ONNX和第一步检查输入输出的shape暴露了后处理细节如果你手上还没有onnx文件在装有ultralytics的训练机上执行导出yolo export modelyolov8n.pt formatonnx opset12 imgsz640 dynamicFalse导出参数里最值得留意的是imgsz640和dynamicFalse。固定输入尺寸能帮ONNXRuntime在加载模型时做更多的图优化推理省心很多。opset12是兼容性较好的档位ONNXRuntime 1.17对opset 12的支持很成熟。导出完成后用2.4节的脚本打印shape。YOLOv8检测模型的输出一般是[1,84,8400]这里的84由4个框坐标加80个COCO类别得分组成8400是三个尺度特征图上的候选框总数。如果打印出来是[1,8400,84]也不用慌只是不同版本导出时转置差异后面代码里统一转一下就好。3.2 letterbox预处理等比例缩放加灰边一个函数把坐标映射也带出来YOLOv8训练时会把输入图等比缩放到640x640多余部分用灰色114填充。推理时也必须做同样的操作否则物体比例变了检测框会跟着偏。这里有个关键点直接用cv2.resize把图片拉到640x640会破坏长宽比必须用letterbox。import cv2 import numpy as np def letterbox(img, new_shape(640, 640), color114): h, w img.shape[:2] r min(new_shape[0] / h, new_shape[1] / w) new_w, new_h int(round(w * r)), int(round(h * r)) dw (new_shape[1] - new_w) / 2 dh (new_shape[0] - new_h) / 2 top, bottom int(round(dh - 0.1)), int(round(dh 0.1)) left, right int(round(dw - 0.1)), int(round(dw 0.1)) if (new_w, new_h) ! (w, h): img cv2.resize(img, (new_w, new_h), interpolationcv2.INTER_LINEAR) img cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, valuecolor) return img, r, left, top函数返回三个值letterbox后的图、缩放比例r、左边的padding像素数left和上边的padding像素数top。为什么要返回padding因为模型输出的框坐标是在letterbox后的图像坐标系里算的回到原图时必须减去padding再除以r。这个映射关系留着后面画框和画mask都要用。注意round(dh - 0.1)和round(dh 0.1)是为了处理奇数像素填充时的对称问题属于YOLO系列一贯的写法照用即可。3.3 推理解码YOLOv8没有objectness别照着旧教程找错列旧版YOLOv5的ONNX输出第一列是objectness置信度许多网上教程会教你取pred[:, 4]当物体得分。YOLOv8把anchor-based结构改成了anchor-free输出里没有objectness这一列84列就是4个坐标加80个类别得分直接取类别维度的最大值作为置信度。def detect_infer(sess, img_path, conf_thres0.25, iou_thres0.45): img0 cv2.imread(img_path) img, r, left, top letterbox(img0) blob cv2.dnn.blobFromImage(img, 1/255.0, (640, 640), (0, 0, 0), swapRBTrue) outputs sess.run(None, {sess.get_inputs()[0].name: blob}) pred outputs[0] if pred.shape[1] pred.shape[2]: pred pred.transpose((0, 2, 1)) pred pred[0] # (8400, 84) boxes pred[:, :4] # cx, cy, w, h cls_scores pred[:, 4:] # 80类得分 scores cls_scores.max(axis1) class_ids cls_scores.argmax(axis1) keep scores conf_thres boxes, scores, class_ids boxes[keep], scores[keep], class_ids[keep] boxes_xyxy np.zeros_like(boxes) boxes_xyxy[:, 0] boxes[:, 0] - boxes[:, 2] / 2 boxes_xyxy[:, 1] boxes[:, 1] - boxes[:, 3] / 2 boxes_xyxy[:, 2] boxes[:, 0] boxes[:, 2] / 2 boxes_xyxy[:, 3] boxes[:, 1] boxes[:, 3] / 2 indices cv2.dnn.NMSBoxes(boxes_xyxy.tolist(), scores.tolist(), conf_thres, iou_thres) if len(indices) 0: return [] indices np.array(indices).reshape(-1) result [] for i in indices: x1, y1, x2, y2 boxes_xyxy[i] x1 (x1 - left) / r y1 (y1 - top) / r x2 (x2 - left) / r y2 (y2 - top) / r result.append((int(x1), int(y1), int(x2), int(y2), int(class_ids[i]), float(scores[i]))) return result这段代码里blobFromImage一步完成了三件事缩放、BGR转RGB、除以255归一化。缩放尺寸传640x640但前面letterbox已经把图处理成640x640所以这里不会二次变形。坐标还原公式x (x_letter - left) / r必须和letterbox一一对应。如果导出时用了imgsz1280代码里的640都要同步改最稳的做法是从session.get_inputs()[0].shape动态读出来。4. 实例分割的后处理116维的mask系数和160x160的proto怎么用对4.1 输出结构检测模型的84维和分割模型的116维差在哪里实例分割模型导出后打印shape会看到两个输出。以yolov8n-seg为例输出通常是output0: (1, 116, 8400) output1: (1, 32, 160, 160)output0的前84维含义和检测模型完全一样4个坐标加80个类别得分。后面多出来的32维是每个候选框对应的mask系数。output1是原型mask可以把它理解成一张特征图32个通道存储了图像区域的基础分割信息。最终某个框的mask等于它的32个系数和原型mask做线性组合再经过sigmoid激活。打印shape这一步非常值得做因为不同版本导出的维度顺序可能变。只要看到116这个数字就知道要用84到116之间的数据。4.2 先做NMS再算mask分割后处理顺序决定你用CPU还是干等新手常见的写法是先把8400个候选框全部和proto做矩阵乘法跑完再筛框。这意味着8400次32x25600的矩阵运算在CPU上会卡到怀疑人生。正确顺序是先按置信度过滤再NMS最后只对保留下来的框算mask。def seg_postprocess(pred, proto, boxes_xyxy, class_ids, scores, img_size640, conf_thres0.25): mask_coeffs pred[:, 84:116] keep scores conf_thres boxes_xyxy, class_ids, scores boxes_xyxy[keep], class_ids[keep], scores[keep] mask_coeffs mask_coeffs[keep] indices cv2.dnn.NMSBoxes(boxes_xyxy.tolist(), scores.tolist(), conf_thres, 0.45) if len(indices) 0: return [], [], [], [] indices np.array(indices).reshape(-1) boxes boxes_xyxy[indices] class_ids class_ids[indices] scores scores[indices] coeffs mask_coeffs[indices] proto proto[0] # (32, 160, 160) proto proto.reshape(32, -1) # (32, 25600) masks coeffs proto # (N, 25600) masks 1.0 / (1.0 np.exp(-masks)) masks masks.reshape(-1, 160, 160) return boxes, class_ids, scores, masksproto的160x160分辨率对应输入图的1/4尺度所以mask的空间分辨率天然比检测框低。后面还要做一次resize把它还原到原图框大小。批量矩阵运算coeffs proto一次把N个候选框的mask全算出来比for循环逐个算快得多。这也是ONNXRuntime CPU推理时很值得保留的优化习惯。注意这里没有在proto上加sigmoid而是在coeffs proto之后对整个mask做sigmoid。顺序错了mask数值范围就不对。4.3 把mask贴回原图crop、resize和阈值化附最小可视化代码每个mask是160x160对应整张letterbox后的画布。要把它贴回原图需要先按检测框在640坐标系下的位置裁出区域再缩放回原图框的实际尺寸最后以0.5为阈值转成二值maskdef paste_masks(masks, boxes_xyxy, left, top, r, orig_shape): # boxes_xyxy 是 640 画布坐标系下的框 h, w orig_shape[:2] canvas np.zeros((h, w), dtypenp.uint8) mask_h, mask_w masks.shape[1:] scale_w mask_w / 640.0 scale_h mask_h / 640.0 for i in range(len(masks)): x1, y1, x2, y2 boxes_xyxy[i].astype(int) x1 max(0, min(mask_w, int(x1 * scale_w))) y1 max(0, min(mask_h, int(y1 * scale_h))) x2 max(0, min(mask_w, int(x2 * scale_w))) y2 max(0, min(mask_h, int(y2 * scale_h))) if x2 - x1 1 or y2 - y1 1: continue crop masks[i, y1:y2, x1:x2] # 转回原图坐标系 ox1 int((boxes_xyxy[i][0] - left) / r) oy1 int((boxes_xyxy[i][1] - top) / r) ox2 int((boxes_xyxy[i][2] - left) / r) oy2 int((boxes_xyxy[i][3] - top) / r) bw, bh max(1, ox2 - ox1), max(1, oy2 - oy1) crop cv2.resize(crop, (bw, bh), interpolationcv2.INTER_LINEAR) crop (crop 0.5).astype(np.uint8) * 255 roi canvas[oy1:oy2, ox1:ox2] canvas[oy1:oy2, ox1:ox2] np.maximum(roi, crop) return canvas这段代码的关键在于两套坐标别混boxes_xyxy是letterbox画布坐标裁mask时直接用贴回原图时先减去left/top再除以r。如果忘了减padding物体位置会整体向右下偏移。mask值在resize之后用0.5做阈值是为了容忍插值产生的过渡像素。叠加可视化时可以用cv2.addWeighted或直接按位赋值canvas是单通道灰度转成BGR后再与原图合成即可。5. 避坑手册ONNX推理不出框、mask全黑和CPU慢的五个现场5.1 onnxruntime报Unsupported operator模型加载直接失败现象InferenceSession创建时报Unsupported operator或No Op registered for ...。原因导出ONNX时opset版本太高低版本onnxruntime不认新算子或者模型里带了一些自定义算子没有注册对应kernel。解决导出时固定opset12低版本runtime配低opset最省事。如果模型来自别人先用onnx.version_converter降级或重新导出。我也遇到过因为onnxsimplify过度优化导致算子碎片化的情况这类问题可以回到原始onnx文件保留一份没有simplify的版本作对照。5.2 检测框整体偏移物体位置不对但分类正确现象框能框住东西但整体往右下或左上偏框得不准。原因坐标映射时忘了减letterbox的padding或者预处理用了blobFromImage但后处理还按手动归一化的偏移量算。解决回到3.3节的公式(x_letter - left) / r并且确认letterbox返回的left、top和真正fill的像素一致。可以在调试时把letterbox后的图直接保存下来看一眼检查原图目标在画布上的位置和框的位置关系。5.3 mask全黑或整片错位现象检测框正常但分割mask输出全0或者mask贴在完全错的位置。原因把检测模型的84维输出当成分割模型的输出没截取116维后边的32维mask系数或者proto的通道维度和mask_coeffs的乘法方向搞反维度对不上计算结果成了噪声。解决打印outputs[0].shape确认是(1,116,8400)而不是(1,84,8400)。mask_coeffs取pred[:, 84:116]proto取outputs[1][0].reshape(32, -1)两者做矩阵乘法时注意把proto放到右边。输出结果先可视化中间态确认sigmoid后mask最大值在0到1之间。5.4 CPU推理慢到怀疑人生五六帧都跑不动现象同样的pt模型在PyTorch里跑视频还能忍转成ONNX反而更慢。原因导出时dynamicTrue导致ONNXRuntime无法做shape相关的图优化或者创建Session时没开线程池也可能模型保留了大量NMS以外的冗余节点。解决导出固定dynamicFalse和imgsz640。创建Session时加配置sess_options ort.SessionOptions() sess_options.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL sess_options.intra_op_num_threads 8 sess ort.InferenceSession(yolov8n.onnx, sess_options, providers[CPUExecutionProvider])intra_op_num_threads根据实际CPU核数设不是越大越好超过物理核反而因线程切换掉性能。5.5 OpenCV的NMSBoxes返回值时好时坏解包时常报错现象cv2.dnn.NMSBoxes返回的indices有时是一维数组有时是[[0]]这种二维嵌套直接flatten有时报错有时又是空元组。原因OpenCV 4.5到4.10之间改过NMSBoxes的返回类型不同版本对空结果的表现也不一样。解决做一层防御式处理统一转成numpy数组再reshapeindices cv2.dnn.NMSBoxes(boxes.tolist(), scores.tolist(), 0.25, 0.45) if indices is None or len(indices) 0: detections [] else: indices np.array(indices).reshape(-1).tolist()这套写法在4.8和4.10里都能跑不会因为版本差异翻车。6. 验证与提速拿ultralytics结果当标尺再谈批量推理和量化6.1 与官方predict结果对比IoU确认后处理没跑偏后处理代码写完第一件事不是接摄像头而是拿一张验证集图片和ultralytics的官方predict结果对比。写一个简单的IoU函数把自己的检测框和官方结果逐对比较IoU大于0.7就算对。def iou(a, b): x1 max(a[0], b[0]) y1 max(a[1], b[1]) x2 min(a[2], b[2]) y2 min(a[3], b[3]) inter max(0, x2 - x1) * max(0, y2 - y1) area_a (a[2] - a[0]) * (a[3] - a[1]) area_b (b[2] - b[0]) * (b[3] - b[1]) return inter / (area_a area_b - inter 1e-6)对比时要注意两边用同一张原图、同一个输入尺寸。如果IoU整体都低先检查letterbox参数是否一致如果只有个别框对不上多半是NMS阈值没对齐。6.2 动态量化、批量推理和线程数从单张图提速到可接视频流CPU上最实惠的提速手段是动态量化。用onnxruntime自带的量化工具不需要准备校准数据集from onnxruntime.quantization import quantize_dynamic, QuantType quantize_dynamic(yolov8n.onnx, yolov8n_quant.onnx, weight_typeQuantType.QUInt8)量化后的模型体积大约缩到四分之一CPU推理延迟通常能降20%到40%代价是mAP轻微下降。实例分割模型也可以量化但mask分支的输出精度敏感一些建议量化后专门跑一遍mask可视化确认没退化。批量推理是另一个方向。把多帧图合成一个batch送给ONNXRuntime线程利用率更充分但前提是导出时dynamicFalse只固定了输入尺寸batch维度可以用动态。我自己的教训是第一次接视频流时贪图省事导出开了dynamicTrue结果单帧延迟翻了一倍排查了两天才意识到是动态shape破坏了图优化。从那以后我固定imgsz只在最后一个版本确认效果后再提量化。目标检测和实例分割这套ONNX推理链路只要你把输出维度弄明白、letterbox坐标公式写对剩下的就是不断量化、对比IoU、调整线程数的体力活。希望帮到你。本文还有配套的精品资源点击获取