1. 为什么YOLOv8-seg的后处理比你想的更关键很多人在跑通YOLOv8-seg模型时都有过这样一个体验模型推理本身没花多少时间反而是从拿到输出张量到真正画出一张能看的mask图中间折腾了好几天。如果你只用过YOLOv8的检测模型第一次切到seg版本时面对输出张量的形状变化会明显懵一下——检测模型的输出是[1, 84, 8400]这类形状而seg模型的输出变成了[1, 116, 8400]甚至更复杂的结构多出来的那部分到底该怎么用网上很多教程一笔带过源码里又全是矩阵运算看起来头大。这篇内容就是要把这条链路彻底讲清楚从导出模型拿到的原始输出到最终生成和原图尺寸对齐的mask中间每一步在做什么、为什么这么做、有哪些典型的坑。无论你是刚接触实例分割的新手还是已经在用YOLOv8-seg做项目但一直被后处理细节折磨的工程师这篇文章都值得你完整看一遍。先说明一下我下面讲的流程基于YOLOv8-seg的官方实现在ONNX导出后的标准输出格式。用PyTorch直接推理的话输出结构略有差异但核心思路完全一致。我会把两边的差异点也在关键位置指出来。2. 输出解析先把张量掰开揉碎2.1 模型输出形状背后的设计逻辑先看一张图的标准情况。假设你训练时配置的类别数是nc比如coco就是80类YOLOv8-seg的检测头里每个anchor位置会输出4 nc nm个值其中nm是mask系数的数量默认是32。在推理模式下YOLOv8的检测头会把三个不同尺度的特征图拉平拼接所以最终输出是一个二维矩阵形状为[1, 4 nc nm, 总共的anchor数]。以coco的80类为例4 80 32 116所以输出就是[1, 116, 8400]。这个8400是怎么来的是三个检测层P3、P4、P5的anchor数量相加80x80 40x40 20x20 6400 1600 400 8400。如果你的输入尺寸不是640x640这个数会按比例变化。关键点在于这116维向量里前4个是检测框坐标格式为cx, cy, w, h接着80个是各类别的置信度分数最后32个才是mask系数。很多人拿到输出后直接拿整行去做softmax或者sigmoid这就是第一步就出错了。2.2 用代码把输出拆成三段这里我直接给出一段标准的输出拆分代码也是我实际项目中一直在用的写法import numpy as np def parse_yolov8_seg_output(output, nc80, nm32): output: (1, 4 nc nm, 8400) 的numpy数组来自ONNX推理 返回: (boxes, scores, classes, mask_coefficients) # 转成 (8400, 4 nc nm) preds output[0].transpose(1, 0) # 按列拆分 box preds[:, :4] # cx, cy, w, h cls_scores preds[:, 4:4 nc] # 各类别分数 mask_coeffs preds[:, 4 nc:] # mask系数32维 return box, cls_scores, mask_coeffs这里的transpose操作非常关键。ONNX导出的YOLOv8-seg模型输出维度是[1, 116, 8400]如果你直接按第一维去切拿到的会是按特征维度排列的数据没法直接和anchor一一对应。必须先转置成[8400, 116]让每一行对应一个anchor位置再去切列就对了。拆完之后接下来要做的就是把cx, cy, w, h转换成x1, y1, x2, y2的格式方便后续计算IOU和画框。这一步就是常规操作了def xywh_to_xyxy(boxes): x1 boxes[:, 0] - boxes[:, 2] / 2 y1 boxes[:, 1] - boxes[:, 3] / 2 x2 boxes[:, 0] boxes[:, 2] / 2 y2 boxes[:, 1] boxes[:, 3] / 2 return np.stack([x1, y1, x2, y2], axis-1)2.3 分数过滤和NMS的先后顺序接下来会面临一个顺序问题是先做类别分数过滤再做NMS还是先NMS再过滤我见过一些实现是先做一次全局的分数阈值过滤比如只保留score 0.25的anchor再做NMS。这样确实能减少NMS的计算量但要注意一个细节——YOLOv8的输出里每个anchor都有nc个类别分数正确的做法是先取每个anchor的最大类别分数和对应类别索引再拿这个最大分数去和阈值比较。# 取每个anchor的最大类别分数和对应索引 class_ids np.argmax(cls_scores, axis1) class_scores cls_scores[np.arange(len(cls_scores)), class_ids] # 阈值过滤这里的conf_thres是0.25为例 valid_mask class_scores 0.25 boxes boxes[valid_mask] class_scores class_scores[valid_mask] class_ids class_ids[valid_mask] mask_coeffs mask_coeffs[valid_mask]一句话总结别用整行的平均值或者单独某个类别的分数去做过滤要用每个anchor的最大类别分数。这个错误的隐蔽性在于如果某个anchor的多个类别分数都很低但恰好你选的类别的分数是这几个低分里相对最高的阈值过滤依然能通过导致输出一堆没意义的低置信度框白白增加后续处理的开销。2.4 NMS类别的处理细节YOLO系列的NMS有一个默认的类别处理方式每个类别单独做NMS。什么意思呢就是同一个位置上如果同时检测到“人”和“车”两个类别的框它们之间不做抑制因为它们属于不同类别可以共存。但如果同一个类别有两个高度重叠的框保留分数高的那个。在numpy里实现这个逻辑最简单的方式就是按类别分组循环from functools import partial def nms(boxes, scores, iou_thres0.45): 纯numpy实现的NMS返回保留的索引 x1 boxes[:, 0] y1 boxes[:, 1] x2 boxes[:, 2] y2 boxes[:, 3] areas (x2 - x1) * (y2 - y1) order scores.argsort()[::-1] keep [] while order.size 0: i order[0] keep.append(i) if order.size 1: break xx1 np.maximum(x1[i], x1[order[1:]]) yy1 np.maximum(y1[i], y1[order[1:]]) xx2 np.minimum(x2[i], x2[order[1:]]) yy2 np.minimum(y2[i], y2[order[1:]]) w np.maximum(0.0, xx2 - xx1) h np.maximum(0.0, yy2 - yy1) inter w * h iou inter / (areas[i] areas[order[1:]] - inter) inds np.where(iou iou_thres)[0] order order[inds 1] return np.array(keep) # 按类别分别做NMS final_boxes, final_scores, final_classes, final_coeffs [], [], [], [] for cls_id in np.unique(class_ids): cls_idx np.where(class_ids cls_id)[0] if len(cls_idx) 0: continue cls_boxes boxes[cls_idx] cls_scores class_scores[cls_idx] keep_idx nms(cls_boxes, cls_scores) final_boxes.append(cls_boxes[keep_idx]) final_scores.append(cls_scores[keep_idx]) final_classes.append(np.full(len(keep_idx), cls_id)) final_coeffs.append(mask_coeffs[cls_idx][keep_idx]) # 合并结果 final_boxes np.concatenate(final_boxes, axis0) final_scores np.concatenate(final_scores, axis0) final_classes np.concatenate(final_classes, axis0) final_coeffs np.concatenate(final_coeffs, axis0)这里我用的是纯numpy实现方便你理解原理。实际工程中建议直接用cv2.dnn.NMSBoxes或者torchvision.ops.nms效率和稳定性都更好。但理解这个循环过程非常重要因为你后面排查mask错位问题的时候大概率需要回看这个NMS步骤的索引对应关系。3. Mask生成从系数到像素的还原之路3.1 原型mask和系数的关系这是YOLOv8-seg和传统Mask R-CNN最本质的区别。Mask R-CNN是在每个ROI上单独分割而YOLOv8-seg更像是在整张图上预先分割出若干个“原型mask”然后每个检测框用一个32维的系数向量的线性组合来还原自己的分割结果。打个比方就像调色盘上预先调好了32种基础颜色每个检测目标用一组比例来混合这些颜色最终得到自己想要的那个特定颜色mask。原型mask是从特征图里解码出来的相当于网络已经学会了用32个基础模板去表达任意形状的分割区域。具体到代码层面原型mask的来源是YOLOv8-seg网络的一个额外分支它输出的特征图经过上采样后形状是[1, 32, 160, 160]输入640x640时。注意这里有个细节原型mask的尺寸是160x160不是原图尺寸。后面的所有mask生成操作都在这个尺度上进行最后再统一映射回原图坐标。3.2 从系数到mask的矩阵运算拿到NMS筛选后的检测框和对应的32维系数后生成单张mask的步骤如下def generate_masks(proto_masks, mask_coeffs, boxes, img_shape): proto_masks: (1, 32, 160, 160) 原型mask特征图 mask_coeffs: (N, 32) 每个检测框的mask系数 boxes: (N, 4) 格式为x1, y1, x2, y2坐标在640x640尺度 img_shape: 原图尺寸 (H, W) # 原型mask转成 (32, 160*160) proto proto_masks[0].reshape(32, -1) # 矩阵乘法: (N, 32) (32, 25600) - (N, 25600) masks mask_coeffs proto # reshape回 (N, 160, 160) N masks.shape[0] masks masks.reshape(N, 160, 160) return masks这个矩阵乘法的含义非常直观每个检测框的32个系数和32个原型mask特征图的对应像素位置做加权求和得到一个160x160的响应图。系数越大说明这个目标越依赖对应的原型mask。3.3 Sigmoid与阈值分割加权求和得到的响应图是一个实数矩阵词义上它是一个“未归一化的分数图”。要变成真正意义上的mask还需要做两步Sigmoid压缩将数值范围压缩到0~1之间表示每个像素属于前景的概率阈值二值化通常取0.5作为阈值大于等于0.5的像素为1前景小于0.5的为0背景import cv2 def process_raw_masks(raw_masks, boxes, img_shape, mask_thres0.5): raw_masks: (N, 160, 160) 矩阵乘法后的原始mask boxes: (N, 4) 检测框 img_shape: 原图尺寸 processed [] for i in range(raw_masks.shape[0]): # sigmoid mask 1 / (1 np.exp(-raw_masks[i])) # 阈值二值化 mask (mask mask_thres).astype(np.uint8) processed.append(mask) return processed这里有几个重要的工程细节需要提醒sigmoid不要自己用Python循环写数据量大的时候非常慢。上面的代码只是演示逻辑实际工程中直接用scipy.special.expit或者cv2的向量化操作。mask_thres参数非常敏感。默认0.5在大多数场景下表现不错但在目标边缘比较复杂、或者前景和背景对比度不高时可能需要微调。我见过一个焊缝检测项目把阈值降到0.35效果才好因为焊缝边缘的梯度变化太剧烈了0.5会把很多真正的边缘像素过滤掉。3.4 坐标还原到原图这是整个后处理流程里最容易出错的一步。模型输入的640x640图像通常经过了letterbox保持长宽比并填充处理因此模型输出的检测框坐标是相对于640x640的letterbox图像的。而mask生成在160x160分辨率上就相当于比640x640缩小了4倍。要把mask映射回原图需要经过两步缩放偏移还原。这里以YOLOv8官方推理代码里的process_mask函数为参考def scale_mask_to_orig(mask, box, orig_shape, input_shape(640, 640)): mask: (160, 160) 二值mask box: (x1, y1, x2, y2) 在640x640尺度上 orig_shape: 原图 (H, W) # 1. 先把mask从160x160缩放到640x640 mask cv2.resize(mask, (input_shape[1], input_shape[0]), interpolationcv2.INTER_LINEAR) # 2. 裁剪出检测框区域转换成xyxy格式并clip到边界内 x1, y1, x2, y2 box x1, y1 int(max(0, x1)), int(max(0, y1)) x2, y2 int(min(input_shape[1], x2)), int(min(input_shape[0], y2)) # 3. 裁剪 cropped mask[y1:y2, x1:x2] # 4. 缩放到原图对应区域大小 orig_h, orig_w orig_shape crop_h y2 - y1 crop_w x2 - x1 # 注意这里需要根据letterbox的比例做映射 # 假设原图到输入图的比例是 r # 这里简单演示直接拉伸到原图大小实际要做letterbox的逆操作 mask_resized cv2.resize(cropped, (crop_w, crop_h), interpolationcv2.INTER_LINEAR) return mask_resized上面这段代码为了展示步骤拆分了流程但实际实现时正确的做法是先把检测框坐标转换回原图坐标然后计算对应的mask区域再做resize。倒过来按我的示例这样先裁剪再放大在letterbox非等比缩放的情况下会出问题。标准的做法大概是这样的def crop_mask_from_orig(mask, box, orig_img_shape, input_shape, ratio, pad): mask: (160, 160) 二值mask box: (x1, y1, x2, y2) 在640x640尺度上的坐标 orig_img_shape: 原图 (H, W) ratio: letterbox缩放比例 (标量) pad: letterbox的pad宽度 (w_pad, h_pad) # 1. mask先缩放到640x640 mask cv2.resize(mask, (input_shape[1], input_shape[0]), interpolationcv2.INTER_LINEAR) # 2. 把检测框在原图上的坐标计算出来 x1, y1, x2, y2 box # 逆letterbox: 先减去pad再除以ratio orig_x1 (x1 - pad[0]) / ratio orig_y1 (y1 - pad[1]) / ratio orig_x2 (x2 - pad[0]) / ratio orig_y2 (y2 - pad[1]) / ratio # 3. 裁剪mask区域在原图尺度上的坐标但mask还是640x640分辨率 # 所以在裁剪时需要先按ratio把原图坐标转回640x640 crop_x1 int(max(0, orig_x1) * ratio pad[0]) crop_y1 int(max(0, orig_y1) * ratio pad[1]) crop_x2 int(min(orig_img_shape[1], orig_x2) * ratio pad[0]) crop_y2 int(min(orig_img_shape[0], orig_y2) * ratio pad[1]) cropped mask[crop_y1:crop_y2, crop_x1:crop_x2] # 4. 缩放到原图框大小 final_h int(orig_y2 - orig_y1) final_w int(orig_x2 - orig_x1) if final_h 0 or final_w 0: return None result cv2.resize(cropped, (final_w, final_h), interpolationcv2.INTER_LINEAR) return result这个步骤里最容易踩的坑是忘了逆letterbox。如果直接把640x640尺度上的mask裁剪区域套用原图尺寸结果就是mask和框的位置对不上物体轮廓整体偏移。这个问题我在后面常见问题章节会展开细说。3.5 单目标视角可视化验证每处理一个检测框拿到对应的mask后最直观的验证方式就是把框和mask叠加到原图上看看。def visualize_mask_on_img(img, box, mask, color(0, 255, 0), alpha0.5): img: 原图 BGR box: (x1, y1, x2, y2) 原图坐标 mask: (final_h, final_w) 二值mask # 在mask对应的位置填充颜色 x1, y1, x2, y2 [int(v) for v in box] roi img[y1:y2, x1:x2] colored_mask np.zeros_like(roi, dtypenp.uint8) colored_mask[mask 0] color # 混合 blended cv2.addWeighted(roi, 1 - alpha, colored_mask, alpha, 0) img[y1:y2, x1:x2] blended # 画框 cv2.rectangle(img, (x1, y1), (x2, y2), color, 2) return img我第一次调通YOLOv8-seg全流程的时候就是靠一行一行地打印中间尺寸来定位问题是出在mask本身的生成还是坐标映射。建议你调试时也把每一步的shape打出来尤其是mask缩放后的尺寸很多隐蔽bug靠肉眼找很难但打印shape一下就能看穿。4. 工程化实践写一版能直接落地的后处理实现4.1 整体流程串起来前面几节我们把每个环节拆开讲了原理现在该把这些步骤组装成一个完整的函数让读者可以直接拷进自己的项目里用。import cv2 import numpy as np class YOLOv8SegPostProcessor: def __init__(self, nc80, nm32, conf_thres0.25, iou_thres0.45, input_shape(640, 640), mask_thres0.5): self.nc nc self.nm nm self.conf_thres conf_thres self.iou_thres iou_thres self.input_shape input_shape self.mask_thres mask_thres self.output_channels 4 nc nm def preprocess(self, img): letterbox预处理返回处理后的图、ratio、pad h, w img.shape[:2] target_h, target_w self.input_shape ratio min(target_w / w, target_h / h) new_w, new_h int(w * ratio), int(h * ratio) resized cv2.resize(img, (new_w, new_h), interpolationcv2.INTER_LINEAR) pad_w (target_w - new_w) / 2 pad_h (target_h - new_h) / 2 canvas np.full((target_h, target_w, 3), 114, dtypenp.uint8) canvas[int(pad_h):int(pad_h) new_h, int(pad_w):int(pad_w) new_w] resized # 归一化并转为CHW input_tensor canvas[:, :, ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0 input_tensor np.expand_dims(input_tensor, axis0) return input_tensor, ratio, (pad_w, pad_h) def postprocess(self, output, proto, orig_shape, ratio, pad): output: (1, 4ncnm, 8400) proto: (1, 32, 160, 160) orig_shape: (H, W) # 1. 解析输出 preds output[0].transpose(1, 0) # (8400, 4ncnm) box preds[:, :4] cls_scores preds[:, 4:4 self.nc] mask_coeffs preds[:, 4 self.nc:] # 2. xywh转xyxy boxes_xyxy self.xywh_to_xyxy(box) # 3. 找最大类别分数 class_ids np.argmax(cls_scores, axis1) class_scores cls_scores[np.arange(len(cls_scores)), class_ids] # 4. 分数过滤 valid class_scores self.conf_thres boxes_xyxy boxes_xyxy[valid] class_scores class_scores[valid] class_ids class_ids[valid] mask_coeffs mask_coeffs[valid] # 5. 按类别做NMS final_boxes, final_scores, final_classes, final_coeffs [], [], [], [] for cls_id in np.unique(class_ids): cls_mask class_ids cls_id cls_boxes boxes_xyxy[cls_mask] cls_scores_tmp class_scores[cls_mask] keep_idx self.nms(cls_boxes, cls_scores_tmp) final_boxes.append(cls_boxes[keep_idx]) final_scores.append(cls_scores_tmp[keep_idx]) final_classes.append(np.full(len(keep_idx), cls_id)) final_coeffs.append(mask_coeffs[cls_mask][keep_idx]) if len(final_boxes) 0: return [] final_boxes np.concatenate(final_boxes) final_scores np.concatenate(final_scores) final_classes np.concatenate(final_classes).astype(int) final_coeffs np.concatenate(final_coeffs) # 6. 生成mask results [] raw_masks final_coeffs proto[0].reshape(self.nm, -1) raw_masks raw_masks.reshape(-1, 160, 160) for i in range(len(final_boxes)): mask self.process_single_mask(raw_masks[i], final_boxes[i], orig_shape, ratio, pad) results.append({ box: self.to_orig_coords(final_boxes[i], orig_shape, ratio, pad), score: float(final_scores[i]), class_id: int(final_classes[i]), mask: mask }) return results def xywh_to_xyxy(self, boxes): x1 boxes[:, 0] - boxes[:, 2] / 2 y1 boxes[:, 1] - boxes[:, 3] / 2 x2 boxes[:, 0] boxes[:, 2] / 2 y2 boxes[:, 1] boxes[:, 3] / 2 return np.stack([x1, y1, x2, y2], axis-1) def nms(self, boxes, scores): from cv2 import dnn indices cv2.dnn.NMSBoxes( boxes.tolist(), scores.tolist(), score_thresholdself.conf_thres, nms_thresholdself.iou_thres ) if len(indices) 0: return np.array([], dtypeint) return np.array(indices).flatten() def process_single_mask(self, raw_mask, box, orig_shape, ratio, pad): # sigmoid threshold mask 1 / (1 np.exp(-raw_mask)) mask (mask self.mask_thres).astype(np.uint8) # 缩放到640x640 mask cv2.resize(mask, self.input_shape, interpolationcv2.INTER_LINEAR) # 计算原图坐标 x1, y1, x2, y2 box orig_x1 (x1 - pad[0]) / ratio orig_y1 (y1 - pad[1]) / ratio orig_x2 (x2 - pad[0]) / ratio orig_y2 (y2 - pad[1]) / ratio # 裁剪 crop_x1 int(max(0, orig_x1) * ratio pad[0]) crop_y1 int(max(0, orig_y1) * ratio pad[1]) crop_x2 int(min(orig_shape[1], orig_x2) * ratio pad[0]) crop_y2 int(min(orig_shape[0], orig_y2) * ratio pad[1]) if crop_x2 crop_x1 or crop_y2 crop_y1: return np.zeros((1, 1), dtypenp.uint8) cropped mask[crop_y1:crop_y2, crop_x1:crop_x2] final_h int(orig_y2 - orig_y1) final_w int(orig_x2 - orig_x1) if final_h 0 or final_w 0: return np.zeros((1, 1), dtypenp.uint8) return cv2.resize(cropped, (final_w, final_h), interpolationcv2.INTER_LINEAR) def to_orig_coords(self, box, orig_shape, ratio, pad): x1, y1, x2, y2 box orig_x1 (x1 - pad[0]) / ratio orig_y1 (y1 - pad[1]) / ratio orig_x2 (x2 - pad[0]) / ratio orig_y2 (y2 - pad[1]) / ratio orig_x1 max(0, min(orig_shape[1], orig_x1)) orig_y1 max(0, min(orig_shape[0], orig_y1)) orig_x2 max(0, min(orig_shape[1], orig_x2)) orig_y2 max(0, min(orig_shape[0], orig_y2)) return [orig_x1, orig_y1, orig_x2, orig_y2]这段代码是我在实际项目中提炼出来的一个相对完整的版本直接在__init__里把阈值参数暴露出来方便调用时灵活调整。4.2 ONNX Runtime实际推理接驳后处理代码写好了还要和推理引擎接上。以onnxruntime为例完整的推理流程大概是这样的import onnxruntime as ort # 加载模型 session ort.InferenceSession(yolov8s-seg.onnx, providers[CUDAExecutionProvider, CPUExecutionProvider]) # 获取输入输出名 input_name session.get_inputs()[0].name output_names [o.name for o in session.get_outputs()] # 注意seg模型有两个输出第一个是检测头输出第二个是proto mask print(fOutput names: {output_names}) # 预处理 img cv2.imread(test.jpg) processor YOLOv8SegPostProcessor(nc80, nm32) input_tensor, ratio, pad processor.preprocess(img) # 推理 outputs session.run(output_names, {input_name: input_tensor}) # outputs[0] 形状 (1, 116, 8400) 或 (1, 4ncnm, N) # outputs[1] 形状 (1, 32, 160, 160) # 后处理 detections processor.postprocess( outputs[0], outputs[1], orig_shapeimg.shape[:2], ratioratio, padpad ) # 可视化 for det in detections: box det[box] mask det[mask] img visualize_mask_on_img(img, box, mask)这里需要特别注意的是不同版本的YOLOv8导出ONNX时输出顺序可能不同。有的版本把proto mask放前面有的放后面。稳妥的做法是运行时先打印输出名或者根据形状判断——检测头输出是[1, 4ncnm, 8400]这样的二维矩阵转置型proto mask是[1, 32, 160, 160]通过shape一眼就能认出来。4.3 关于PyTorch直接推理的差异如果你不用ONNX直接用Ultralytics的PyTorch模型推理输出结构会不一样。model(img)返回的结果是一个列表其中result[0].boxes有xyxy和conf和clsresult[0].masks直接就是分割好的mask对象。这种高层API确实方便但它屏蔽了底层细节遇到问题反而更难排查。我更建议你在自己的项目里走“导出ONNX 自写后处理”这条路。原因有三ONNX在部署时的推理速度通常优于PyTorch eager模式尤其在TensorRT加持下差距更明显自写后处理意味着你对每一步都有完全的控制权可以针对自己的业务场景做定制比如把mask_thres调低、给特定类别加单独的NMS策略不依赖Ultralytics的重型依赖部署更轻量5. 常见问题与排查技巧实录5.1 mask和检测框错位这个问题的典型表现是框的位置是对的但mask明显偏移或者方向不对。绝大多数情况是letterbox的逆操作写错了。排查思路很简单找一张只有单个目标且目标在图像中央的图打印出每一步的坐标值。先手动算一遍再用代码跑一遍对比中间结果。我遇到过最坑的一次是pad的方向搞反了——pad_w和pad_h传入的时候是(w_pad, h_pad)结果在逆操作时用了(h_pad, w_pad)导致所有mask整体偏移。另外还有一个容易忽略的点不要对裁剪出来的mask再做额外的resize。我这里说的resize是那种非等比例的拉伸比如把160x160的mask直接cv2.resize到(w, h)是没问题的但如果你中间多做了一次到640x640之外的其他尺寸的resize就很容易引入偏差。5.2 输出形状和预期不符如果你导出ONNX时用了dynamic_axes输出的anchor数量会随输入尺寸变化。比如输入1280x1280时输出会是(1, 116, 33600)。如果代码里写死了8400这个数字运行时会直接报索引错误。解决办法是动态获取anchor数量num_anchors output.shape[2] # 后续所有地方都用num_anchors不要写死另外YOLOv8官方导出ONNX时有几个参数需要注意yolo export modelyolov8s-seg.pt formatonnx opset12 simplifyTrue dynamicFalsedynamicFalse时输入固定为640x640输出就是(1, 116, 8400)dynamicTrue时输入可以是任意尺寸但你后处理的代码必须能自适应。5.3 生成的mask边缘粗糙或有大块空洞这个问题通常和mask_thres取值有关但也可能是原型mask的分辨率限制导致的。160x160的原型mask在放大到原图时如果原图很大比如4K分辨率边缘天然会显得锯齿感很强。两个改进方向使用YOLOv8-seg更大的模型如yolov8x-seg它的原型mask特征图表达能力更强对生成的mask做一次轮廓平滑比如用cv2.morphologyEx做开闭运算或者用cv2.GaussianBlur后重新阈值化。实际项目中我常用的是3x3的椭圆核开运算能把一些细小的噪点消除。kernel cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3)) mask cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel) mask cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)5.4 性能瓶颈排查如果后处理整体耗时明显偏高先profile一下通常瓶颈集中在这么几个地方numpy矩阵乘法N x 32乘32 x 25600在N很大时会卡。如果N超过几百考虑把这一步放到GPU上做sigmoid的Python实现千万不要用循环逐个元素算直接scipy.special.expit或者cv2不行就用1/(1np.exp(-x))的向量化写法逐框resizeN个框就要N次cv2.resize没法完全避免但可以统一先缩放到固定尺寸再一次性拼接到原图我在一个工业项目里测过纯Python后处理在CPU上单帧640x640的图大概耗时3~5ms其中mask生成占了接近一半。如果对速度有极致要求建议把mask生成部分用Cython或者C重写或者直接上TensorRT的自定义后处理插件。5.5 常见问题速查表现象可能原因解决方案mask整体偏移letterbox逆操作错误、pad顺序搞反打印坐标逐步对比检查逆操作公式mask尺寸和原图对不上缩放时用了非等比resize用ratio和pad做精确映射检测框正确但mask为空mask_thres过高或裁剪区域计算有误降低mask_thres检查crop坐标输出只有检测框没有maskONNX版本输出顺序不对或漏了proto打印输出名和shape确认proto拿到了NMS后框的数量异常多类别分数没有按最大值过滤检查是否用了np.max(cls_scores)推理报维度不匹配dynamic输入尺寸变了但后处理写死用动态获取anchor数量mask边缘锯齿严重原型mask分辨率不足开闭运算平滑轮廓或者用更大模型6. 我踩过的一些真坑写到这里该分享一些我实际做项目时踩到的坑了。这些细节在官方文档和大多数教程里都不会提到但恰恰是它们决定了你的后处理代码能不能真正跑通、跑稳。第一个坑是导出的ONNX模型输出节点顺序不稳定。同一个yolov8s-seg.pt在不同版本的ultralytics库下导出的ONNX输出顺序竟然会变化。我遇到过在Ultralytics 8.0.x下导出第一个输出是检测头升级到8.1.x后重新导出第一个输出变成了proto。如果代码里写死了outputs[0]是检测头升级完库之后整个后处理全废了。我的建议是每次导出后都打印一下输出名和对应shape在代码里加一个判断for idx, out in enumerate(session.get_outputs()): shape out.shape if len(shape) 3 and shape[1] 4 self.nc self.nm: det_idx idx elif len(shape) 4 and shape[1] self.nm: proto_idx idx第二个坑是mask的坐标和检测框的坐标不在同一个坐标系下。原型mask是160x160分辨率检测框是640x640分辨率很多人在做mask裁剪时直接在640x640的框上乘以4倍变成160x160的坐标这个思路本身没错但忽略了letterbox带来的偏移。如果输入图刚好是正方形比如很多公开数据集就是640x640这个bug根本不会暴露但一旦换成16:9的工业相机图mask就全部偏移了。所以我还是建议从一开始就把letterbox的逆变换逻辑写好不要等出了bug再临时补。第三个坑和性能有关numpy矩阵乘法在CPU上处理大batch时会吃掉大量内存。mask_coeffs proto这个操作当检测框数量N100时结果是(100, 25600)的float32数组也就是约10MB。看起来不大但在嵌入式设备上这可能是很大的开销。如果设备内存紧张可以考虑分batch处理比如每次只处理50个框的mask。第四个坑比较隐晦sigmoid后的mask分布通常是双峰的但偶尔会出现整体偏移。当目标的纹理和背景很像时sigmoid输出可能整体偏高即使背景像素也有0.6以上的响应。这时候0.5的固定阈值就会把大片背景误判成前景。我后来在项目里改用了一个自适应阈值策略——先看mask的直方图分布如果最大值和最小值之差小于0.3说明整体响应强度差异不大就把阈值往中位数方向偏移。不过这个方法不是通用方案如果你的项目只有固定的一类目标还是建议用验证集调一个最优的固定阈值。最后再说一个代码层面的小技巧。在写后处理时把中间结果都缓存到局部变量里而不是反复计算这听起来像是废话但真的有人会在循环里重复调用sigmoid函数或者重复做transpose。对于追求极致性能的部署场景这些重复计算累积起来可能就是1~2ms的差距。7. 后续还能怎么玩YOLOv8-seg的后处理这条链路本质上是从“网络输出的高维特征”到“用户可理解的像素级结果”的翻译过程。理解了它你可以做很多扩展把mask的结果直接转成多边形轮廓用cv2.findContours然后输出成JSON格式的标注文件用于数据标注工具的二次编辑利用mask做目标区域的颜色直方图统计实现基于实例分割的工业质检功能把mask和深度图结合计算目标物的体积或表面积在多目标跟踪场景下用mask的IOU替代box的IOU跟踪稳定性往往会好一个档次这些都是后话先把基础的后处理链路跑通再谈进阶。我从第一次成功跑出mask到现在中间踩了不少坑但这条路径基本是固定的只要按部就班理解每一层的作用你也能很快掌握。
YOLOv8-seg后处理全解析：从输出张量到像素级Mask生成实战
1. 为什么YOLOv8-seg的后处理比你想的更关键很多人在跑通YOLOv8-seg模型时都有过这样一个体验模型推理本身没花多少时间反而是从拿到输出张量到真正画出一张能看的mask图中间折腾了好几天。如果你只用过YOLOv8的检测模型第一次切到seg版本时面对输出张量的形状变化会明显懵一下——检测模型的输出是[1, 84, 8400]这类形状而seg模型的输出变成了[1, 116, 8400]甚至更复杂的结构多出来的那部分到底该怎么用网上很多教程一笔带过源码里又全是矩阵运算看起来头大。这篇内容就是要把这条链路彻底讲清楚从导出模型拿到的原始输出到最终生成和原图尺寸对齐的mask中间每一步在做什么、为什么这么做、有哪些典型的坑。无论你是刚接触实例分割的新手还是已经在用YOLOv8-seg做项目但一直被后处理细节折磨的工程师这篇文章都值得你完整看一遍。先说明一下我下面讲的流程基于YOLOv8-seg的官方实现在ONNX导出后的标准输出格式。用PyTorch直接推理的话输出结构略有差异但核心思路完全一致。我会把两边的差异点也在关键位置指出来。2. 输出解析先把张量掰开揉碎2.1 模型输出形状背后的设计逻辑先看一张图的标准情况。假设你训练时配置的类别数是nc比如coco就是80类YOLOv8-seg的检测头里每个anchor位置会输出4 nc nm个值其中nm是mask系数的数量默认是32。在推理模式下YOLOv8的检测头会把三个不同尺度的特征图拉平拼接所以最终输出是一个二维矩阵形状为[1, 4 nc nm, 总共的anchor数]。以coco的80类为例4 80 32 116所以输出就是[1, 116, 8400]。这个8400是怎么来的是三个检测层P3、P4、P5的anchor数量相加80x80 40x40 20x20 6400 1600 400 8400。如果你的输入尺寸不是640x640这个数会按比例变化。关键点在于这116维向量里前4个是检测框坐标格式为cx, cy, w, h接着80个是各类别的置信度分数最后32个才是mask系数。很多人拿到输出后直接拿整行去做softmax或者sigmoid这就是第一步就出错了。2.2 用代码把输出拆成三段这里我直接给出一段标准的输出拆分代码也是我实际项目中一直在用的写法import numpy as np def parse_yolov8_seg_output(output, nc80, nm32): output: (1, 4 nc nm, 8400) 的numpy数组来自ONNX推理 返回: (boxes, scores, classes, mask_coefficients) # 转成 (8400, 4 nc nm) preds output[0].transpose(1, 0) # 按列拆分 box preds[:, :4] # cx, cy, w, h cls_scores preds[:, 4:4 nc] # 各类别分数 mask_coeffs preds[:, 4 nc:] # mask系数32维 return box, cls_scores, mask_coeffs这里的transpose操作非常关键。ONNX导出的YOLOv8-seg模型输出维度是[1, 116, 8400]如果你直接按第一维去切拿到的会是按特征维度排列的数据没法直接和anchor一一对应。必须先转置成[8400, 116]让每一行对应一个anchor位置再去切列就对了。拆完之后接下来要做的就是把cx, cy, w, h转换成x1, y1, x2, y2的格式方便后续计算IOU和画框。这一步就是常规操作了def xywh_to_xyxy(boxes): x1 boxes[:, 0] - boxes[:, 2] / 2 y1 boxes[:, 1] - boxes[:, 3] / 2 x2 boxes[:, 0] boxes[:, 2] / 2 y2 boxes[:, 1] boxes[:, 3] / 2 return np.stack([x1, y1, x2, y2], axis-1)2.3 分数过滤和NMS的先后顺序接下来会面临一个顺序问题是先做类别分数过滤再做NMS还是先NMS再过滤我见过一些实现是先做一次全局的分数阈值过滤比如只保留score 0.25的anchor再做NMS。这样确实能减少NMS的计算量但要注意一个细节——YOLOv8的输出里每个anchor都有nc个类别分数正确的做法是先取每个anchor的最大类别分数和对应类别索引再拿这个最大分数去和阈值比较。# 取每个anchor的最大类别分数和对应索引 class_ids np.argmax(cls_scores, axis1) class_scores cls_scores[np.arange(len(cls_scores)), class_ids] # 阈值过滤这里的conf_thres是0.25为例 valid_mask class_scores 0.25 boxes boxes[valid_mask] class_scores class_scores[valid_mask] class_ids class_ids[valid_mask] mask_coeffs mask_coeffs[valid_mask]一句话总结别用整行的平均值或者单独某个类别的分数去做过滤要用每个anchor的最大类别分数。这个错误的隐蔽性在于如果某个anchor的多个类别分数都很低但恰好你选的类别的分数是这几个低分里相对最高的阈值过滤依然能通过导致输出一堆没意义的低置信度框白白增加后续处理的开销。2.4 NMS类别的处理细节YOLO系列的NMS有一个默认的类别处理方式每个类别单独做NMS。什么意思呢就是同一个位置上如果同时检测到“人”和“车”两个类别的框它们之间不做抑制因为它们属于不同类别可以共存。但如果同一个类别有两个高度重叠的框保留分数高的那个。在numpy里实现这个逻辑最简单的方式就是按类别分组循环from functools import partial def nms(boxes, scores, iou_thres0.45): 纯numpy实现的NMS返回保留的索引 x1 boxes[:, 0] y1 boxes[:, 1] x2 boxes[:, 2] y2 boxes[:, 3] areas (x2 - x1) * (y2 - y1) order scores.argsort()[::-1] keep [] while order.size 0: i order[0] keep.append(i) if order.size 1: break xx1 np.maximum(x1[i], x1[order[1:]]) yy1 np.maximum(y1[i], y1[order[1:]]) xx2 np.minimum(x2[i], x2[order[1:]]) yy2 np.minimum(y2[i], y2[order[1:]]) w np.maximum(0.0, xx2 - xx1) h np.maximum(0.0, yy2 - yy1) inter w * h iou inter / (areas[i] areas[order[1:]] - inter) inds np.where(iou iou_thres)[0] order order[inds 1] return np.array(keep) # 按类别分别做NMS final_boxes, final_scores, final_classes, final_coeffs [], [], [], [] for cls_id in np.unique(class_ids): cls_idx np.where(class_ids cls_id)[0] if len(cls_idx) 0: continue cls_boxes boxes[cls_idx] cls_scores class_scores[cls_idx] keep_idx nms(cls_boxes, cls_scores) final_boxes.append(cls_boxes[keep_idx]) final_scores.append(cls_scores[keep_idx]) final_classes.append(np.full(len(keep_idx), cls_id)) final_coeffs.append(mask_coeffs[cls_idx][keep_idx]) # 合并结果 final_boxes np.concatenate(final_boxes, axis0) final_scores np.concatenate(final_scores, axis0) final_classes np.concatenate(final_classes, axis0) final_coeffs np.concatenate(final_coeffs, axis0)这里我用的是纯numpy实现方便你理解原理。实际工程中建议直接用cv2.dnn.NMSBoxes或者torchvision.ops.nms效率和稳定性都更好。但理解这个循环过程非常重要因为你后面排查mask错位问题的时候大概率需要回看这个NMS步骤的索引对应关系。3. Mask生成从系数到像素的还原之路3.1 原型mask和系数的关系这是YOLOv8-seg和传统Mask R-CNN最本质的区别。Mask R-CNN是在每个ROI上单独分割而YOLOv8-seg更像是在整张图上预先分割出若干个“原型mask”然后每个检测框用一个32维的系数向量的线性组合来还原自己的分割结果。打个比方就像调色盘上预先调好了32种基础颜色每个检测目标用一组比例来混合这些颜色最终得到自己想要的那个特定颜色mask。原型mask是从特征图里解码出来的相当于网络已经学会了用32个基础模板去表达任意形状的分割区域。具体到代码层面原型mask的来源是YOLOv8-seg网络的一个额外分支它输出的特征图经过上采样后形状是[1, 32, 160, 160]输入640x640时。注意这里有个细节原型mask的尺寸是160x160不是原图尺寸。后面的所有mask生成操作都在这个尺度上进行最后再统一映射回原图坐标。3.2 从系数到mask的矩阵运算拿到NMS筛选后的检测框和对应的32维系数后生成单张mask的步骤如下def generate_masks(proto_masks, mask_coeffs, boxes, img_shape): proto_masks: (1, 32, 160, 160) 原型mask特征图 mask_coeffs: (N, 32) 每个检测框的mask系数 boxes: (N, 4) 格式为x1, y1, x2, y2坐标在640x640尺度 img_shape: 原图尺寸 (H, W) # 原型mask转成 (32, 160*160) proto proto_masks[0].reshape(32, -1) # 矩阵乘法: (N, 32) (32, 25600) - (N, 25600) masks mask_coeffs proto # reshape回 (N, 160, 160) N masks.shape[0] masks masks.reshape(N, 160, 160) return masks这个矩阵乘法的含义非常直观每个检测框的32个系数和32个原型mask特征图的对应像素位置做加权求和得到一个160x160的响应图。系数越大说明这个目标越依赖对应的原型mask。3.3 Sigmoid与阈值分割加权求和得到的响应图是一个实数矩阵词义上它是一个“未归一化的分数图”。要变成真正意义上的mask还需要做两步Sigmoid压缩将数值范围压缩到0~1之间表示每个像素属于前景的概率阈值二值化通常取0.5作为阈值大于等于0.5的像素为1前景小于0.5的为0背景import cv2 def process_raw_masks(raw_masks, boxes, img_shape, mask_thres0.5): raw_masks: (N, 160, 160) 矩阵乘法后的原始mask boxes: (N, 4) 检测框 img_shape: 原图尺寸 processed [] for i in range(raw_masks.shape[0]): # sigmoid mask 1 / (1 np.exp(-raw_masks[i])) # 阈值二值化 mask (mask mask_thres).astype(np.uint8) processed.append(mask) return processed这里有几个重要的工程细节需要提醒sigmoid不要自己用Python循环写数据量大的时候非常慢。上面的代码只是演示逻辑实际工程中直接用scipy.special.expit或者cv2的向量化操作。mask_thres参数非常敏感。默认0.5在大多数场景下表现不错但在目标边缘比较复杂、或者前景和背景对比度不高时可能需要微调。我见过一个焊缝检测项目把阈值降到0.35效果才好因为焊缝边缘的梯度变化太剧烈了0.5会把很多真正的边缘像素过滤掉。3.4 坐标还原到原图这是整个后处理流程里最容易出错的一步。模型输入的640x640图像通常经过了letterbox保持长宽比并填充处理因此模型输出的检测框坐标是相对于640x640的letterbox图像的。而mask生成在160x160分辨率上就相当于比640x640缩小了4倍。要把mask映射回原图需要经过两步缩放偏移还原。这里以YOLOv8官方推理代码里的process_mask函数为参考def scale_mask_to_orig(mask, box, orig_shape, input_shape(640, 640)): mask: (160, 160) 二值mask box: (x1, y1, x2, y2) 在640x640尺度上 orig_shape: 原图 (H, W) # 1. 先把mask从160x160缩放到640x640 mask cv2.resize(mask, (input_shape[1], input_shape[0]), interpolationcv2.INTER_LINEAR) # 2. 裁剪出检测框区域转换成xyxy格式并clip到边界内 x1, y1, x2, y2 box x1, y1 int(max(0, x1)), int(max(0, y1)) x2, y2 int(min(input_shape[1], x2)), int(min(input_shape[0], y2)) # 3. 裁剪 cropped mask[y1:y2, x1:x2] # 4. 缩放到原图对应区域大小 orig_h, orig_w orig_shape crop_h y2 - y1 crop_w x2 - x1 # 注意这里需要根据letterbox的比例做映射 # 假设原图到输入图的比例是 r # 这里简单演示直接拉伸到原图大小实际要做letterbox的逆操作 mask_resized cv2.resize(cropped, (crop_w, crop_h), interpolationcv2.INTER_LINEAR) return mask_resized上面这段代码为了展示步骤拆分了流程但实际实现时正确的做法是先把检测框坐标转换回原图坐标然后计算对应的mask区域再做resize。倒过来按我的示例这样先裁剪再放大在letterbox非等比缩放的情况下会出问题。标准的做法大概是这样的def crop_mask_from_orig(mask, box, orig_img_shape, input_shape, ratio, pad): mask: (160, 160) 二值mask box: (x1, y1, x2, y2) 在640x640尺度上的坐标 orig_img_shape: 原图 (H, W) ratio: letterbox缩放比例 (标量) pad: letterbox的pad宽度 (w_pad, h_pad) # 1. mask先缩放到640x640 mask cv2.resize(mask, (input_shape[1], input_shape[0]), interpolationcv2.INTER_LINEAR) # 2. 把检测框在原图上的坐标计算出来 x1, y1, x2, y2 box # 逆letterbox: 先减去pad再除以ratio orig_x1 (x1 - pad[0]) / ratio orig_y1 (y1 - pad[1]) / ratio orig_x2 (x2 - pad[0]) / ratio orig_y2 (y2 - pad[1]) / ratio # 3. 裁剪mask区域在原图尺度上的坐标但mask还是640x640分辨率 # 所以在裁剪时需要先按ratio把原图坐标转回640x640 crop_x1 int(max(0, orig_x1) * ratio pad[0]) crop_y1 int(max(0, orig_y1) * ratio pad[1]) crop_x2 int(min(orig_img_shape[1], orig_x2) * ratio pad[0]) crop_y2 int(min(orig_img_shape[0], orig_y2) * ratio pad[1]) cropped mask[crop_y1:crop_y2, crop_x1:crop_x2] # 4. 缩放到原图框大小 final_h int(orig_y2 - orig_y1) final_w int(orig_x2 - orig_x1) if final_h 0 or final_w 0: return None result cv2.resize(cropped, (final_w, final_h), interpolationcv2.INTER_LINEAR) return result这个步骤里最容易踩的坑是忘了逆letterbox。如果直接把640x640尺度上的mask裁剪区域套用原图尺寸结果就是mask和框的位置对不上物体轮廓整体偏移。这个问题我在后面常见问题章节会展开细说。3.5 单目标视角可视化验证每处理一个检测框拿到对应的mask后最直观的验证方式就是把框和mask叠加到原图上看看。def visualize_mask_on_img(img, box, mask, color(0, 255, 0), alpha0.5): img: 原图 BGR box: (x1, y1, x2, y2) 原图坐标 mask: (final_h, final_w) 二值mask # 在mask对应的位置填充颜色 x1, y1, x2, y2 [int(v) for v in box] roi img[y1:y2, x1:x2] colored_mask np.zeros_like(roi, dtypenp.uint8) colored_mask[mask 0] color # 混合 blended cv2.addWeighted(roi, 1 - alpha, colored_mask, alpha, 0) img[y1:y2, x1:x2] blended # 画框 cv2.rectangle(img, (x1, y1), (x2, y2), color, 2) return img我第一次调通YOLOv8-seg全流程的时候就是靠一行一行地打印中间尺寸来定位问题是出在mask本身的生成还是坐标映射。建议你调试时也把每一步的shape打出来尤其是mask缩放后的尺寸很多隐蔽bug靠肉眼找很难但打印shape一下就能看穿。4. 工程化实践写一版能直接落地的后处理实现4.1 整体流程串起来前面几节我们把每个环节拆开讲了原理现在该把这些步骤组装成一个完整的函数让读者可以直接拷进自己的项目里用。import cv2 import numpy as np class YOLOv8SegPostProcessor: def __init__(self, nc80, nm32, conf_thres0.25, iou_thres0.45, input_shape(640, 640), mask_thres0.5): self.nc nc self.nm nm self.conf_thres conf_thres self.iou_thres iou_thres self.input_shape input_shape self.mask_thres mask_thres self.output_channels 4 nc nm def preprocess(self, img): letterbox预处理返回处理后的图、ratio、pad h, w img.shape[:2] target_h, target_w self.input_shape ratio min(target_w / w, target_h / h) new_w, new_h int(w * ratio), int(h * ratio) resized cv2.resize(img, (new_w, new_h), interpolationcv2.INTER_LINEAR) pad_w (target_w - new_w) / 2 pad_h (target_h - new_h) / 2 canvas np.full((target_h, target_w, 3), 114, dtypenp.uint8) canvas[int(pad_h):int(pad_h) new_h, int(pad_w):int(pad_w) new_w] resized # 归一化并转为CHW input_tensor canvas[:, :, ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0 input_tensor np.expand_dims(input_tensor, axis0) return input_tensor, ratio, (pad_w, pad_h) def postprocess(self, output, proto, orig_shape, ratio, pad): output: (1, 4ncnm, 8400) proto: (1, 32, 160, 160) orig_shape: (H, W) # 1. 解析输出 preds output[0].transpose(1, 0) # (8400, 4ncnm) box preds[:, :4] cls_scores preds[:, 4:4 self.nc] mask_coeffs preds[:, 4 self.nc:] # 2. xywh转xyxy boxes_xyxy self.xywh_to_xyxy(box) # 3. 找最大类别分数 class_ids np.argmax(cls_scores, axis1) class_scores cls_scores[np.arange(len(cls_scores)), class_ids] # 4. 分数过滤 valid class_scores self.conf_thres boxes_xyxy boxes_xyxy[valid] class_scores class_scores[valid] class_ids class_ids[valid] mask_coeffs mask_coeffs[valid] # 5. 按类别做NMS final_boxes, final_scores, final_classes, final_coeffs [], [], [], [] for cls_id in np.unique(class_ids): cls_mask class_ids cls_id cls_boxes boxes_xyxy[cls_mask] cls_scores_tmp class_scores[cls_mask] keep_idx self.nms(cls_boxes, cls_scores_tmp) final_boxes.append(cls_boxes[keep_idx]) final_scores.append(cls_scores_tmp[keep_idx]) final_classes.append(np.full(len(keep_idx), cls_id)) final_coeffs.append(mask_coeffs[cls_mask][keep_idx]) if len(final_boxes) 0: return [] final_boxes np.concatenate(final_boxes) final_scores np.concatenate(final_scores) final_classes np.concatenate(final_classes).astype(int) final_coeffs np.concatenate(final_coeffs) # 6. 生成mask results [] raw_masks final_coeffs proto[0].reshape(self.nm, -1) raw_masks raw_masks.reshape(-1, 160, 160) for i in range(len(final_boxes)): mask self.process_single_mask(raw_masks[i], final_boxes[i], orig_shape, ratio, pad) results.append({ box: self.to_orig_coords(final_boxes[i], orig_shape, ratio, pad), score: float(final_scores[i]), class_id: int(final_classes[i]), mask: mask }) return results def xywh_to_xyxy(self, boxes): x1 boxes[:, 0] - boxes[:, 2] / 2 y1 boxes[:, 1] - boxes[:, 3] / 2 x2 boxes[:, 0] boxes[:, 2] / 2 y2 boxes[:, 1] boxes[:, 3] / 2 return np.stack([x1, y1, x2, y2], axis-1) def nms(self, boxes, scores): from cv2 import dnn indices cv2.dnn.NMSBoxes( boxes.tolist(), scores.tolist(), score_thresholdself.conf_thres, nms_thresholdself.iou_thres ) if len(indices) 0: return np.array([], dtypeint) return np.array(indices).flatten() def process_single_mask(self, raw_mask, box, orig_shape, ratio, pad): # sigmoid threshold mask 1 / (1 np.exp(-raw_mask)) mask (mask self.mask_thres).astype(np.uint8) # 缩放到640x640 mask cv2.resize(mask, self.input_shape, interpolationcv2.INTER_LINEAR) # 计算原图坐标 x1, y1, x2, y2 box orig_x1 (x1 - pad[0]) / ratio orig_y1 (y1 - pad[1]) / ratio orig_x2 (x2 - pad[0]) / ratio orig_y2 (y2 - pad[1]) / ratio # 裁剪 crop_x1 int(max(0, orig_x1) * ratio pad[0]) crop_y1 int(max(0, orig_y1) * ratio pad[1]) crop_x2 int(min(orig_shape[1], orig_x2) * ratio pad[0]) crop_y2 int(min(orig_shape[0], orig_y2) * ratio pad[1]) if crop_x2 crop_x1 or crop_y2 crop_y1: return np.zeros((1, 1), dtypenp.uint8) cropped mask[crop_y1:crop_y2, crop_x1:crop_x2] final_h int(orig_y2 - orig_y1) final_w int(orig_x2 - orig_x1) if final_h 0 or final_w 0: return np.zeros((1, 1), dtypenp.uint8) return cv2.resize(cropped, (final_w, final_h), interpolationcv2.INTER_LINEAR) def to_orig_coords(self, box, orig_shape, ratio, pad): x1, y1, x2, y2 box orig_x1 (x1 - pad[0]) / ratio orig_y1 (y1 - pad[1]) / ratio orig_x2 (x2 - pad[0]) / ratio orig_y2 (y2 - pad[1]) / ratio orig_x1 max(0, min(orig_shape[1], orig_x1)) orig_y1 max(0, min(orig_shape[0], orig_y1)) orig_x2 max(0, min(orig_shape[1], orig_x2)) orig_y2 max(0, min(orig_shape[0], orig_y2)) return [orig_x1, orig_y1, orig_x2, orig_y2]这段代码是我在实际项目中提炼出来的一个相对完整的版本直接在__init__里把阈值参数暴露出来方便调用时灵活调整。4.2 ONNX Runtime实际推理接驳后处理代码写好了还要和推理引擎接上。以onnxruntime为例完整的推理流程大概是这样的import onnxruntime as ort # 加载模型 session ort.InferenceSession(yolov8s-seg.onnx, providers[CUDAExecutionProvider, CPUExecutionProvider]) # 获取输入输出名 input_name session.get_inputs()[0].name output_names [o.name for o in session.get_outputs()] # 注意seg模型有两个输出第一个是检测头输出第二个是proto mask print(fOutput names: {output_names}) # 预处理 img cv2.imread(test.jpg) processor YOLOv8SegPostProcessor(nc80, nm32) input_tensor, ratio, pad processor.preprocess(img) # 推理 outputs session.run(output_names, {input_name: input_tensor}) # outputs[0] 形状 (1, 116, 8400) 或 (1, 4ncnm, N) # outputs[1] 形状 (1, 32, 160, 160) # 后处理 detections processor.postprocess( outputs[0], outputs[1], orig_shapeimg.shape[:2], ratioratio, padpad ) # 可视化 for det in detections: box det[box] mask det[mask] img visualize_mask_on_img(img, box, mask)这里需要特别注意的是不同版本的YOLOv8导出ONNX时输出顺序可能不同。有的版本把proto mask放前面有的放后面。稳妥的做法是运行时先打印输出名或者根据形状判断——检测头输出是[1, 4ncnm, 8400]这样的二维矩阵转置型proto mask是[1, 32, 160, 160]通过shape一眼就能认出来。4.3 关于PyTorch直接推理的差异如果你不用ONNX直接用Ultralytics的PyTorch模型推理输出结构会不一样。model(img)返回的结果是一个列表其中result[0].boxes有xyxy和conf和clsresult[0].masks直接就是分割好的mask对象。这种高层API确实方便但它屏蔽了底层细节遇到问题反而更难排查。我更建议你在自己的项目里走“导出ONNX 自写后处理”这条路。原因有三ONNX在部署时的推理速度通常优于PyTorch eager模式尤其在TensorRT加持下差距更明显自写后处理意味着你对每一步都有完全的控制权可以针对自己的业务场景做定制比如把mask_thres调低、给特定类别加单独的NMS策略不依赖Ultralytics的重型依赖部署更轻量5. 常见问题与排查技巧实录5.1 mask和检测框错位这个问题的典型表现是框的位置是对的但mask明显偏移或者方向不对。绝大多数情况是letterbox的逆操作写错了。排查思路很简单找一张只有单个目标且目标在图像中央的图打印出每一步的坐标值。先手动算一遍再用代码跑一遍对比中间结果。我遇到过最坑的一次是pad的方向搞反了——pad_w和pad_h传入的时候是(w_pad, h_pad)结果在逆操作时用了(h_pad, w_pad)导致所有mask整体偏移。另外还有一个容易忽略的点不要对裁剪出来的mask再做额外的resize。我这里说的resize是那种非等比例的拉伸比如把160x160的mask直接cv2.resize到(w, h)是没问题的但如果你中间多做了一次到640x640之外的其他尺寸的resize就很容易引入偏差。5.2 输出形状和预期不符如果你导出ONNX时用了dynamic_axes输出的anchor数量会随输入尺寸变化。比如输入1280x1280时输出会是(1, 116, 33600)。如果代码里写死了8400这个数字运行时会直接报索引错误。解决办法是动态获取anchor数量num_anchors output.shape[2] # 后续所有地方都用num_anchors不要写死另外YOLOv8官方导出ONNX时有几个参数需要注意yolo export modelyolov8s-seg.pt formatonnx opset12 simplifyTrue dynamicFalsedynamicFalse时输入固定为640x640输出就是(1, 116, 8400)dynamicTrue时输入可以是任意尺寸但你后处理的代码必须能自适应。5.3 生成的mask边缘粗糙或有大块空洞这个问题通常和mask_thres取值有关但也可能是原型mask的分辨率限制导致的。160x160的原型mask在放大到原图时如果原图很大比如4K分辨率边缘天然会显得锯齿感很强。两个改进方向使用YOLOv8-seg更大的模型如yolov8x-seg它的原型mask特征图表达能力更强对生成的mask做一次轮廓平滑比如用cv2.morphologyEx做开闭运算或者用cv2.GaussianBlur后重新阈值化。实际项目中我常用的是3x3的椭圆核开运算能把一些细小的噪点消除。kernel cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3)) mask cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel) mask cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)5.4 性能瓶颈排查如果后处理整体耗时明显偏高先profile一下通常瓶颈集中在这么几个地方numpy矩阵乘法N x 32乘32 x 25600在N很大时会卡。如果N超过几百考虑把这一步放到GPU上做sigmoid的Python实现千万不要用循环逐个元素算直接scipy.special.expit或者cv2不行就用1/(1np.exp(-x))的向量化写法逐框resizeN个框就要N次cv2.resize没法完全避免但可以统一先缩放到固定尺寸再一次性拼接到原图我在一个工业项目里测过纯Python后处理在CPU上单帧640x640的图大概耗时3~5ms其中mask生成占了接近一半。如果对速度有极致要求建议把mask生成部分用Cython或者C重写或者直接上TensorRT的自定义后处理插件。5.5 常见问题速查表现象可能原因解决方案mask整体偏移letterbox逆操作错误、pad顺序搞反打印坐标逐步对比检查逆操作公式mask尺寸和原图对不上缩放时用了非等比resize用ratio和pad做精确映射检测框正确但mask为空mask_thres过高或裁剪区域计算有误降低mask_thres检查crop坐标输出只有检测框没有maskONNX版本输出顺序不对或漏了proto打印输出名和shape确认proto拿到了NMS后框的数量异常多类别分数没有按最大值过滤检查是否用了np.max(cls_scores)推理报维度不匹配dynamic输入尺寸变了但后处理写死用动态获取anchor数量mask边缘锯齿严重原型mask分辨率不足开闭运算平滑轮廓或者用更大模型6. 我踩过的一些真坑写到这里该分享一些我实际做项目时踩到的坑了。这些细节在官方文档和大多数教程里都不会提到但恰恰是它们决定了你的后处理代码能不能真正跑通、跑稳。第一个坑是导出的ONNX模型输出节点顺序不稳定。同一个yolov8s-seg.pt在不同版本的ultralytics库下导出的ONNX输出顺序竟然会变化。我遇到过在Ultralytics 8.0.x下导出第一个输出是检测头升级到8.1.x后重新导出第一个输出变成了proto。如果代码里写死了outputs[0]是检测头升级完库之后整个后处理全废了。我的建议是每次导出后都打印一下输出名和对应shape在代码里加一个判断for idx, out in enumerate(session.get_outputs()): shape out.shape if len(shape) 3 and shape[1] 4 self.nc self.nm: det_idx idx elif len(shape) 4 and shape[1] self.nm: proto_idx idx第二个坑是mask的坐标和检测框的坐标不在同一个坐标系下。原型mask是160x160分辨率检测框是640x640分辨率很多人在做mask裁剪时直接在640x640的框上乘以4倍变成160x160的坐标这个思路本身没错但忽略了letterbox带来的偏移。如果输入图刚好是正方形比如很多公开数据集就是640x640这个bug根本不会暴露但一旦换成16:9的工业相机图mask就全部偏移了。所以我还是建议从一开始就把letterbox的逆变换逻辑写好不要等出了bug再临时补。第三个坑和性能有关numpy矩阵乘法在CPU上处理大batch时会吃掉大量内存。mask_coeffs proto这个操作当检测框数量N100时结果是(100, 25600)的float32数组也就是约10MB。看起来不大但在嵌入式设备上这可能是很大的开销。如果设备内存紧张可以考虑分batch处理比如每次只处理50个框的mask。第四个坑比较隐晦sigmoid后的mask分布通常是双峰的但偶尔会出现整体偏移。当目标的纹理和背景很像时sigmoid输出可能整体偏高即使背景像素也有0.6以上的响应。这时候0.5的固定阈值就会把大片背景误判成前景。我后来在项目里改用了一个自适应阈值策略——先看mask的直方图分布如果最大值和最小值之差小于0.3说明整体响应强度差异不大就把阈值往中位数方向偏移。不过这个方法不是通用方案如果你的项目只有固定的一类目标还是建议用验证集调一个最优的固定阈值。最后再说一个代码层面的小技巧。在写后处理时把中间结果都缓存到局部变量里而不是反复计算这听起来像是废话但真的有人会在循环里重复调用sigmoid函数或者重复做transpose。对于追求极致性能的部署场景这些重复计算累积起来可能就是1~2ms的差距。7. 后续还能怎么玩YOLOv8-seg的后处理这条链路本质上是从“网络输出的高维特征”到“用户可理解的像素级结果”的翻译过程。理解了它你可以做很多扩展把mask的结果直接转成多边形轮廓用cv2.findContours然后输出成JSON格式的标注文件用于数据标注工具的二次编辑利用mask做目标区域的颜色直方图统计实现基于实例分割的工业质检功能把mask和深度图结合计算目标物的体积或表面积在多目标跟踪场景下用mask的IOU替代box的IOU跟踪稳定性往往会好一个档次这些都是后话先把基础的后处理链路跑通再谈进阶。我从第一次成功跑出mask到现在中间踩了不少坑但这条路径基本是固定的只要按部就班理解每一层的作用你也能很快掌握。
