简介：这份资源聚焦语义分割任务中的精度评估环节，面向正在使用 PyTorch 训练分割模型、需要量化各类别表现的学生与算法工程师。它解决的是「模型整体指标尚可、却难以定位具体类别分割效果」的问题，通过脚本演示如何从预测结果出发，逐类计算 mIoU 并汇总整个测试集的 mIoU，帮助读者建立从预测图到评估指标的完整链路。压缩包共 2 个文件，均为 py 脚本，体积约 4KB，其中一个负责生成 8 位预测图，另一个负责与 mask 比对并输出各类别及整体 mIoU 值，两者在 PyCharm 中直接运行即可。目前已有 7160 人学习下载，说明该评估思路在分割实践中具有较高参考价值。读者可借此掌握 mIoU 的计算流程与实现细节，理解预测图与标注 mask 的对应关系，并可将脚本迁移到自己的数据集上，快速获得可解释的类别级评估结果。
1. 语义分割里的 mIoU：为什么你的类别得分总是被背景吞掉
跑完一个语义分割模型，pixel_acc看着挺漂亮，0.92、0.94 都有，可一到验收环节，甲方或者导师盯着mIoU问“小目标那几类怎么才 0.3”，这时候才发现自己被像素准确率骗了。语义分割里真正能反映模型对每个类别分割质量的指标是 mIoU（mean Intersection over Union），它先算每一类的 IoU，再对所有类别取平均。问题在于，很多开源训练框架默认只打印一个总的 mIoU，或者干脆把背景类也算进去，导致你根本不知道是哪一类拖了后腿。这篇笔记就围绕 mIoU 的 PyTorch 实现展开，从混淆矩阵的构建、逐类 IoU 的计算，到多卡、多尺度、忽略标签这些工程细节，把一套能直接抄进自己项目里的评估代码拆开讲清楚。适合正在做分割任务、需要自己写验证脚本或者想搞明白框架里mean_iou到底怎么算的从业者。
2. 从混淆矩阵到逐类 IoU：PyTorch 里的计算链路
2.1 为什么不能直接对预测和标签做逐像素比较
新手最容易写出的 mIoU 计算是这样的：把预测结果和标签展平，对每个类别算(pred == label == c).sum()当作交集，再除以(pred == c).sum() + (label == c).sum()。这个写法在单张图上勉强能跑，但一旦进入验证循环就会出问题。首先，逐像素比较无法处理“预测为 c 但标签是 d”这种交叉情况，你算出来的交集只是对角线上的命中数，而 IoU 的分母需要的是预测为 c 的全体像素加上标签为 c 的全体像素再减去交集。其次，这种写法每张图都要重新遍历所有类别，验证集大了以后速度会明显拖慢。
常见做法是先把整个验证集的预测结果和标签累积到一个num_classes × num_classes的混淆矩阵里，矩阵的[i, j]位置表示“标签为 i、预测为 j”的像素总数。有了这个矩阵，每一类的 IoU 就是矩阵[i, i] / (矩阵[i, :].sum() + 矩阵[:, i].sum() - 矩阵[i, i])。这样只需要在验证循环里更新矩阵，最后一次性算指标，既准确又快。
2.2 混淆矩阵的 PyTorch 实现
下面这段代码是我在多个分割项目里反复用过的混淆矩阵更新逻辑，核心是用bincount把二维的标签-预测对映射到一维索引上。
import torch def update_confusion_matrix(conf_matrix, pred, label, num_classes, ignore_index=255): """ conf_matrix: (num_classes, num_classes) 的累积矩阵 pred: 模型输出经过 argmax 后的预测，形状 (N, H, W) 或 (N,) label: 对应的标签，形状与 pred 一致 num_classes: 类别数 ignore_index: 需要忽略的标签值，常见做法是 255 """ # 把 pred 和 label 展平成一维 pred = pred.flatten() label = label.flatten() # 过滤掉 ignore_index 的像素，这些像素不参与任何类别的统计 valid_mask = (label != ignore_index) pred = pred[valid_mask] label = label[valid_mask] # 把 (label, pred) 组合成一个唯一索引：label * num_classes + pred # 这样每个组合落在 [0, num_classes*num_classes) 区间内 indices = label * num_classes + pred # 用 bincount 统计每个组合出现的次数，minlength 保证长度固定 count = torch.bincount(indices, minlength=num_classes * num_classes) # 累加到混淆矩阵，reshape 回二维 conf_matrix += count.reshape(num_classes, num_classes).to(conf_matrix.dtype) return conf_matrix逻辑说明：bincount是这里的关键，它把“标签-预测”对当成一个整数索引来计数，避免了 Python 层面的循环。参数上，ignore_index通常设为 255，因为很多分割数据集用 255 表示边界或未标注区域，这些像素如果参与计算会严重拉低某些类的 IoU。minlength必须显式指定，否则当某个组合在 batch 里没出现时，bincount返回的长度会短于num_classes * num_classes，reshape 就会报错。
2.3 从混淆矩阵算逐类 IoU 和 mIoU
拿到混淆矩阵后，逐类 IoU 的计算就是一行的事，但有几个边界情况要处理。
def compute_iou_from_confusion(conf_matrix): """ conf_matrix: (num_classes, num_classes) 的累积矩阵 返回: 每一类的 IoU 列表，以及 mIoU """ # 对角线是每一类被正确预测的像素数 intersection = torch.diag(conf_matrix) # 每一类的真实像素总数（按行求和） label_sum = conf_matrix.sum(dim=1) # 每一类的预测像素总数（按列求和） pred_sum = conf_matrix.sum(dim=0) # 并集 = 真实总数 + 预测总数 - 交集 union = label_sum + pred_sum - intersection # 防止除零：某一类在验证集里完全没出现时，union 为 0 # 常见做法是给 union 加一个极小值，或者把这类标记为 nan 后跳过 iou = intersection / (union + 1e-10) # 只对在验证集中出现过的类别求平均，避免 nan 拉低 mIoU valid = label_sum > 0 miou = iou[valid].mean().item() return iou.tolist(), miou参数说明：valid这个掩码很重要。如果验证集里某个类别一个像素都没有，它的label_sum为 0，union也为 0，算出来的 IoU 是 0 或者 nan。直接对所有类别取平均会把这种“不存在的类”也算进去，导致 mIoU 偏低。我一般会同时打印valid为 True 的类别数和总类别数，方便判断验证集是否覆盖了所有类。
2.4 在验证循环里串起来
把上面两个函数放进验证循环，整体结构大概是这样：
def validate(model, dataloader, num_classes, device): model.eval() conf_matrix = torch.zeros(num_classes, num_classes, dtype=torch.int64, device=device) with torch.no_grad(): for images, labels in dataloader: images = images.to(device) labels = labels.to(device) outputs = model(images) # 输出通常是 (N, C, H, W)，取 argmax 得到 (N, H, W) preds = outputs.argmax(dim=1) conf_matrix = update_confusion_matrix( conf_matrix, preds, labels, num_classes, ignore_index=255 ) iou_list, miou = compute_iou_from_confusion(conf_matrix) return iou_list, miou这里有个容易忽略的点：conf_matrix的 dtype 用int64，因为bincount返回的是 int64，如果矩阵是 float 类型，累加时会有精度损失。另外，如果用了多卡验证，每个卡上的混淆矩阵需要先all_reduce求和再算指标，否则你拿到的是单卡的局部结果。
3. 多卡、多尺度与忽略标签：工程实现里的参数细节
3.1 多卡验证时混淆矩阵怎么同步
用DataParallel或者DistributedDataParallel做验证时，每张卡各自维护一个混淆矩阵，验证结束后需要跨卡求和。常见做法是用torch.distributed.all_reduce：
import torch.distributed as dist def sync_confusion_matrix(conf_matrix): """ 在多卡环境下把各卡的混淆矩阵求和，返回同步后的矩阵 """ if dist.is_available() and dist.is_initialized(): # 确保矩阵在 GPU 上且为连续内存 conf_matrix = conf_matrix.cuda() dist.all_reduce(conf_matrix, op=dist.ReduceOp.SUM) return conf_matrix注意all_reduce是原地操作，调用后所有卡的conf_matrix都会变成全局求和的结果。如果你只想在 rank 0 上算指标，可以在all_reduce之后判断dist.get_rank() == 0再执行compute_iou_from_confusion。另外，all_reduce要求张量在 GPU 上，如果混淆矩阵一直放在 CPU 上，需要先.cuda()，否则会报错或者走很慢的 CPU 通信路径。
3.2 多尺度推理对 mIoU 的影响
很多分割模型在验证时会做多尺度推理（multi-scale inference），把输入缩放到不同尺寸分别预测再融合。这个操作对 mIoU 的影响不是线性的，我实测下来有几个经验点：缩放尺度一般选[0.75, 1.0, 1.25, 1.5]这几档，再大对小目标反而有害；融合方式用平均概率图再 argmax，比直接对预测结果投票更稳；多尺度会让验证时间增加 3 到 5 倍，如果只是日常跑验证，单尺度就够了，只有在最终汇报或者对比实验时才值得开。
def multi_scale_inference(model, image, scales=[0.75, 1.0, 1.25, 1.5]): """ image: (1, C, H, W) 的单张输入 返回: 融合后的预测 (1, H, W) """ _, _, H, W = image.shape prob_sum = None for scale in scales: new_h, new_w = int(H * scale), int(W * scale) scaled = torch.nn.functional.interpolate( image, size=(new_h, new_w), mode='bilinear', align_corners=False ) with torch.no_grad(): out = model(scaled) # 把输出缩回原尺寸 out = torch.nn.functional.interpolate( out, size=(H, W), mode='bilinear', align_corners=False ) prob = torch.softmax(out, dim=1) prob_sum = prob if prob_sum is None else prob_sum + prob return (prob_sum / len(scales)).argmax(dim=1)参数上，align_corners=False是分割任务里的常见选择，和训练时的 resize 方式保持一致，否则插值带来的偏移会累积到 mIoU 上。mode='bilinear'对概率图融合足够，如果追求更平滑可以用bicubic，但速度会慢一些。
3.3 ignore_index 和类别权重的取舍
ignore_index设成 255 是很多数据集的惯例，但有些数据集用 0 表示背景、用 255 表示忽略区域，这时候如果你把ignore_index设成 0，背景类就整个被丢掉了，mIoU 会虚高。我一般会在数据加载阶段先统计一下标签里各个值的分布，确认哪些值是真实类别、哪些是忽略标记。
另一个坑是类别权重。有些框架在算 mIoU 时会按类别频率加权，但标准的 mIoU 是不加权的，每一类权重相同。如果你在论文或者报告里写的是 mIoU，就不要偷偷加权，否则和别人的结果没法比。如果确实想关注小目标，可以额外报告frequency weighted IoU或者per-class IoU表格，把每一类的数值都列出来。
4. 避坑与排查：mIoU 算不对时先查这五处
4.1 现象：mIoU 比框架自带指标高出一大截
原因：最常见的是ignore_index没设对，把本该忽略的边界像素算进了某些类的分母里，或者反过来，把背景类整个排除了。另一个可能是验证集里某些类根本没出现，你的代码把这些类的 IoU 当 0 算进平均，而框架可能直接跳过了。
解决：先打印混淆矩阵的对角线和每类的label_sum，确认哪些类有像素、哪些类没有。然后检查ignore_index的值是否和数据集的标注约定一致。如果框架用的是mmsegmentation或者segmentation_models_pytorch，直接看它mean_iou的实现里ignore_index默认值是多少，和自己的代码对齐。
4.2 现象：单卡验证正常，多卡验证 mIoU 掉点
原因：多卡时每张卡的混淆矩阵没有同步，你拿到的只是 rank 0 上的局部统计。如果验证集划分不均匀，rank 0 上的类别分布和全局差异很大，算出来的 mIoU 自然对不上。
解决：在验证循环结束后、算指标之前，对所有卡的混淆矩阵做all_reduce求和。注意all_reduce之后所有卡上的矩阵都是全局值，如果只想在 rank 0 上打印，加一个 rank 判断即可。
4.3 现象：mIoU 在训练过程中波动很大
原因：验证集的 batch size 太小，或者验证时没有用model.eval()，导致 BatchNorm 层还在用 batch 统计量。另外，如果验证时开了数据增强（比如随机裁剪），每次验证看到的样本分布不一样，指标也会抖。
解决：验证时固定model.eval()和torch.no_grad()，验证集的预处理只保留 resize 和 normalize，去掉随机翻转、随机裁剪这些增强。如果显存够，把验证 batch size 调到 4 或 8，让每批覆盖更多类别。
4.4 现象：某一类的 IoU 始终为 0
原因：可能是这一类在验证集里样本极少，模型完全没学到；也可能是标签映射错了，比如训练时类别 3 是“车”，验证时类别 3 变成了“人”，混淆矩阵的对角线自然对不上。
解决：先确认训练和验证的类别映射表是同一份。然后单独把这一类的小图拿出来可视化，看模型到底预测成了什么。如果确实是样本太少，考虑在损失函数里给这一类加权重，或者用过采样。
4.5 现象：混淆矩阵累加后数值溢出
原因：用了int32或者float16来存混淆矩阵，验证集大了以后像素总数超过类型上限。int32上限约 21 亿，一般分割验证集不至于超，但如果做了多尺度融合或者测试时增强，累加次数会翻好几倍。
解决：混淆矩阵统一用int64，显存占用可以忽略不计。如果用了混合精度训练，注意bincount的输出是 int64，累加时不要被自动转成 float16。
5. 进阶技巧：把 per-class IoU 做成可追踪的验证报告
5.1 用表格记录每一轮的逐类 IoU
只盯着一个 mIoU 数字，很难判断模型到底在哪些类上进步了。我习惯在验证脚本里把每一类的 IoU 存成一个字典，训练结束后导出成表格，方便对比不同 epoch 或者不同模型。
import pandas as pd def build_iou_report(iou_list, class_names, epoch): """ iou_list: 每一类的 IoU 列表 class_names: 类别名称列表，长度与 iou_list 一致 epoch: 当前轮次 """ df = pd.DataFrame({ 'epoch': [epoch] * len(class_names), 'class': class_names, 'iou': iou_list }) return df # 假设有 5 个类别 class_names = ['background', 'road', 'car', 'person', 'tree'] all_reports = [] for epoch in range(num_epochs): # ... 训练和验证 ... iou_list, miou = validate(model, val_loader, num_classes, device) report = build_iou_report(iou_list, class_names, epoch) all_reports.append(report) final_report = pd.concat(all_reports, ignore_index=True) final_report.to_csv('iou_per_class.csv', index=False)这个表格跑完训练后直接丢进 Excel 或者 pandas 里画折线图，哪一类在涨、哪一类在跌一目了然。参数上，class_names的顺序必须和混淆矩阵的行列顺序严格一致，否则表格里的类别名会对错行。
5.2 用 per-class IoU 反推数据问题
有一次我跑一个道路分割的任务，road类的 IoU 一直在 0.6 左右上不去，但car和person都正常。把 per-class IoU 表格拉出来看，发现road的label_sum比预期少了一个数量级。回头查数据加载，发现标注图里road的像素值被错误地映射成了 255，也就是被当成忽略区域丢掉了。修正映射后，road的 IoU 直接跳到 0.85。这件事之后，我每次拿到新数据集，第一件事就是统计标签里各个值的像素占比，和类别定义表对一遍，确认没有类别被误标成忽略值。
5.3 验证脚本的检查清单
在把验证脚本交给别人用之前，我会强制走一遍下面这几项：
| 检查项 | 确认内容 |
|---|---|
| ignore_index | 和数据集标注约定一致，常见为 255 |
| 混淆矩阵 dtype | int64，避免累加溢出 |
| 多卡同步 | 验证结束后 all_reduce 求和 |
| 类别映射 | 训练和验证使用同一份类别表 |
| 空类别处理 | 验证集中未出现的类不参与 mIoU 平均 |
| 可视化抽查 | 随机抽 3 张图，叠加预测和标签对比 |
这套流程跑下来，mIoU 的数值基本不会出现“玄学”波动。从那以后我每次新写一个分割验证脚本，都会先把混淆矩阵打印出来，确认对角线上的数值分布合理，再去看 mIoU 的数字。希望帮到你。
本文还有配套的精品资源，点击获取
