1. IoU的第一性原理：为什么所有评测都绕不开这个比值
先说一个我在带新手时经常遇到的场面：很多人看目标检测论文，一上来就盯着mAP、mIoU这些花哨指标，结果发现代码改来改去精度就是上不去，最后排查了半天，问题竟然出在IoU计算上。这个IoU（Intersection over Union），中文一般叫交并比，是目标检测和语义分割这两个领域里最基础、最不起眼、却又最要命的一个量。
IoU的定义其实一句话就能说完：两个区域交集面积与并集面积的比值。数学上叫Jaccard系数，上世纪就已经提出了，跟深度学习没什么关系。可正因为它太基础，很多人手写实现时反而容易想当然，坐标约定搞混、像素统计口径出偏差、边界情形没处理，一步错步步错，最后整个评测指标全是错的。
1.1 从Jaccard系数说起：交并比不是什么新鲜概念
IoU背后就是Jaccard系数，公式特别简单：
J(A, B) = |A ∩ B| / |A ∪ B|分子是两个集合的交集大小，分母是两个集合的并集大小。Jaccard系数的取值范围是[0, 1]，等于1说明两个集合完全重合，等于0说明完全没有重叠。
在目标检测里，这两个"集合"就是预测框和真实框在图像上覆盖的像素区域；在语义分割里，这两个"集合"就是预测类别区域和真实类别区域。所以从数学本质上看，检测和分割中的IoU没有任何区别，都是Jaccard系数在不同数据结构上的具体应用。
但这里有个很容易被忽略的微妙点：检测框是规则的矩形，交集和并集都能用坐标加减直接算出来；分割掩码是不规则区域，交并集得通过逐像素统计。数据结构不同，实现思路就完全不同。这也就是为什么我说"手写IoU"不能只查一个公式，得把两个场景分开来想。
1.2 框的表示方式：坐标约定写错一切白搭
目标检测里，框的表示方式不止一种，最常见的就有两种：
[x1, y1, x2, y2]：左上角坐标和右下角坐标，注意x2、y2到底是开区间还是闭区间，这直接决定面积会不会差1。[cx, cy, w, h]：中心点坐标加宽高，YOLO系列用得多，算IoU前要先转成对角坐标。
手写IoU时第一件事就是统一坐标格式。我自己习惯统一转成[x1, y1, x2, y2]，因为后续求交集的逻辑最直观：x1取两个框的较大值，y1取较大值，x2取较小值，y2取较小值。如果x2 - x1 <= 0或者y2 - y1 <= 0，说明两个框没有重叠，交集面积就是0。
还有归一化坐标的问题。很多训练管线里框的坐标是除以图像宽高归一化过的，范围在0到1之间。手写测试代码的时候倒是无所谓，但一旦要跟没有归一化的标签混在一起算，就全乱了。我见过不只是新手，甚至一些开源仓库里都有这种错误：预测框是归一化的，真实框是像素坐标，直接拿来算IoU，结果交集永远算不对，mAP曲线看起来诡异得很。
1.3 IoU阈值如何决定目标检测的评价基调
IoU本身是一个比值，但真正让它发挥威力的是后面的阈值。检测任务中默认把IoU大于某个阈值（常见0.5）的预测框判定为"命中"真实框，这个判定结果直接进入precision和recall的计算，最后汇总成AP、mAP。
阈值不同，指标含义就完全不同。0.5的阈值算出来的mAP，对框的定位精度要求很宽松；而COCO数据集上常用的0.5:0.95的mAP，则是对多个阈值取平均，要求模型在每个阈值下都表现好。所以说，IoU不只是一个相似度度量，它实际上是整个评测体系的"裁判标准"，阈值怎么选，直接决定了模型"好不好"的定义。
语义分割里的mIoU也是一样的逻辑，只不过判定变成了逐像素。
2. 目标检测场景的手写实现：边界框IoU的几何推演与代码细节
既然要手动实现，那就不能只调库，得把每一步几何逻辑写明白。前后动手推过一次之后，以后无论换什么语言、什么深度学习框架，都能顺手写出来，这才是"手写"的意义所在。
2.1 交集区域计算的数学拆解：重叠部分怎么求
两个矩形框，各自用对角线坐标表示，假设预测框是[x1p, y1p, x2p, y2p]，真实框是[x1g, y1g, x2g, y2g]。交集区域也是一个矩形，它的四条边分别是：
- 左边界：
max(x1p, x1g) - 上边界：
max(y1p, y1g) - 右边界：
min(x2p, x2g) - 下边界：
min(y2p, y2g)
这个逻辑很好理解：交集要同时落在两个框内，所以左边界得取两个框里面更靠右的那一个，即取最大值；右边界得取两个框里面更靠左的那一个，即取最小值。如果右边界小于等于左边界，说明横向没有重叠；下边界小于等于上边界，说明纵向没有重叠。
有了交集的宽和高，面积就好算了：
inter_w = max(0, min(x2p, x2g) - max(x1p, x1g)) inter_h = max(0, min(y2p, y2g) - max(y1p, y1g)) inter_area = inter_w * inter_h并集面积则是两个框面积之和减去交集面积：
area_p = (x2p - x1p) * (y2p - y1p) area_g = (x2g - x1g) * (y2g - y1g) union_area = area_p + area_g - inter_area iou = inter_area / union_area这里有个细节值得多说一句：如果两个框正好完全一样，那么交集等于面积，并集也等于面积，IoU正好是1。如果两个框只是接了一条边，交集面积为0，IoU就是0，这通常不被视为有效检测，但如果评测方用的是带边缘容差的指标，就得额外处理。
2.2 基于NumPy的手写实现与向量化技巧
单算一对框的IoU很简单，但训练时要一次性计算成千上万个预测框和真实框两两之间的IoU，就得向量化。这也是手写实现最有价值的地方。
一个常见的需求是：预测框张量preds形状为[N, 4]，真实框张量targets形状为[M, 4]，想得到[N, M]的IoU矩阵。如果用双重循环，N和M一大就跑得慢；用广播机制，就快得多。
import numpy as np def compute_iou_matrix(preds, targets, eps=1e-6): """ preds: [N, 4] 预测框，格式 [x1, y1, x2, y2] targets: [M, 4] 真实框，格式 [x1, y1, x2, y2] 返回: [N, M] IoU矩阵 """ preds = np.asarray(preds, dtype=np.float32) targets = np.asarray(targets, dtype=np.float32) # 展成 [N, 1, 4] 和 [1, M, 4] 再利用广播 preds = preds[:, None, :] # [N, 1, 4] targets = targets[None, :, :] # [1, M, 4] # 交集坐标 inter_x1 = np.maximum(preds[:, :, 0], targets[:, :, 0]) inter_y1 = np.maximum(preds[:, :, 1], targets[:, :, 1]) inter_x2 = np.minimum(preds[:, :, 2], targets[:, :, 2]) inter_y2 = np.minimum(preds[:, :, 3], targets[:, :, 3]) inter_w = np.maximum(0, inter_x2 - inter_x1) inter_h = np.maximum(0, inter_y2 - inter_y1) inter_area = inter_w * inter_h # 各自面积 area_pred = (preds[:, :, 2] - preds[:, :, 0]) * (preds[:, :, 3] - preds[:, :, 1]) area_target = (targets[:, :, 2] - targets[:, :, 0]) * (targets[:, :, 3] - targets[:, :, 1]) union_area = area_pred + area_target - inter_area iou = inter_area / np.maximum(union_area, eps) return iou这段代码的核心就是None索引加广播，把NxM的矩阵一次性算完，不用写任何循环。加了一个eps是防止并集面积为0导致除零报错，虽然两个面积为0的框在正常检测里不太可能出现，但保个底没坏处。
2.3 边界情形：完全包含、完全分离与贴边相邻
手写IoU最考验人的不是常规情形，而是边界情形。
第一种是包含关系：预测框整个在真实框内部，或者反过来。这时候交集区域就是小的那个框本身，并集区域就是大的那个框，IoU等于小框面积除以大框面积。如果预测框远小于真实框，IoU会接近0；如果预测框完整包住真实框但大出很多，IoU同样很低。这说明IoU对"框得准不准"非常敏感，这也是它成为检测指标的原因。
第二种是完全分离：交集宽或高计算出来是0或者负数，说明两个框根本没有重叠区域。代码里的np.maximum(0, ...)就是干这个的，把负值截断为0，交集面积自然就是0。
第三种是贴边相邻：边刚好接触，既没有重叠也没有空隙。inter_w和inter_h严格等于0，IoU为0。直观上会觉得两个框已经很接近了，但在标准IoU的定义下就是0命中。如果你的项目要求检测贴边的目标，可能得在评测逻辑里加入边距容差，否则指标对轻微偏移的惩罚非常狠。
这些边界情形在测试的时候一定要刻意构造，我后面专门用一节来写测试用例。
3. 语义分割场景的手写实现：像素级交并比与类别统计的坑
语义分割跟目标检测的IoU计算思路完全不同。检测面对的是规则矩形，分割面对的是任意形状的掩码，而且往往涉及多个类别。手写分割IoU时，很多人照搬检测的几何方法，那就错到家了。
3.1 分割标签的组织方式：掩码、类别索引与one-hot
语义分割的常见标签形式是类别索引图：一张和原图一样大的单通道图，每个像素的取值代表该像素属于哪个类别（0通常代表背景，1代表某个物体类，等等）。模型输出的预测结果则通常是一个[C, H, W]的概率图，经过argmax之后变成一个[H, W]的类别索引图。
评测时要算的是每一类的IoU，而不是把所有像素混在一起算。对第k类来说：
- 交集 = 预测结果为k且真实标签为k的像素数
- 并集 = 真实标签为k的像素数 + 预测结果为k的像素数 - 交集像素数
也就是：先构造两个布尔矩阵，一个是pred == k，一个是gt == k，然后做逻辑与和逻辑或，统计True的数量。
import numpy as np def compute_per_class_iou(pred_mask, gt_mask, num_classes, ignore_index=255): """ pred_mask: [H, W] 模型argmax后的类别索引图 gt_mask: [H, W] 真实类别索引图 num_classes: 类别总数（含背景） ignore_index: 需要忽略的像素值，比如未标注区域 """ pred_mask = pred_mask.ravel() gt_mask = gt_mask.ravel() # 需要先处理忽略像素 valid = gt_mask != ignore_index pred_valid = pred_mask[valid] gt_valid = gt_mask[valid] ious = [] for cls in range(num_classes): pred_cls = (pred_valid == cls) gt_cls = (gt_valid == cls) intersection = np.logical_and(pred_cls, gt_cls).sum() union = np.logical_or(pred_cls, gt_cls).sum() if union == 0: ious.append(float('nan')) # 该类别在gt中没有出现，也不预测 else: ious.append(intersection / union) return ious这个版本用了循环遍历类别，类别数通常不超过几百，循环代价完全可接受。很多实现会直接用矩阵运算一次性统计所有类别，速度更快，但可读性差一些，我下面会讲更好用的混淆矩阵方案。
3.2 像素级IoU的正确计算顺序：先汇总还是先求平均
在实际评测中，我们通常不是在一张图上算IoU，而是在整个验证集上算mIoU。这里就有一个非常关键的统计口径问题：先算每张图的IoU再取平均，还是先汇总所有像素再算IoU？
两个做法在数学上不一样，得到的结果也不同。正规的评测标准，比如语义分割领域常用的mIoU指标，用的是后者：把整个数据集所有类别对应的交集像素总数和并集像素总数分别累加起来，最后再除。这样才能保证类别面积大的图像在指标中的权重与其像素数成正比，避免小图的偶然性干扰。
实现上最稳妥的方法是维护一个全局的混淆矩阵。对每个像素，按真实标签和预测标签在类别数维度的二维矩阵对应位置加1：
def accumulate_confusion(pred_mask, gt_mask, num_classes): conf = np.zeros((num_classes, num_classes), dtype=np.int64) pred_mask = pred_mask.ravel() gt_mask = gt_mask.ravel() # 用np.add.at避免索引重复时的覆盖问题 np.add.at(conf, (gt_mask, pred_mask), 1) return conf有了混淆矩阵之后，第k类的IoU就是conf[k, k] / (sum(conf[k, :]) + sum(conf[:, k]) - conf[k, k])。全局汇总的时候，只需要把所有样本的混淆矩阵累加，再做一次除法即可，非常清晰，也不容易出错。
3.3 缺失类别的处理：分母为零如何安全兜底
分割任务中经常有某个类别在整个验证集里压根没出现的情况，比如验证集里没有"椅子"这个类。此时该类的分子分母都是0，直接计算就是0/0。处理策略有两种：
一种是把它当作一个IoU为0的类别参与平均，这会让mIoU偏低，对类别缺失比较敏感。另一种是直接跳过这个类别，只对出现的类别求平均。很多开源评测代码默认用跳过的方式，也就是我在上面代码里返回nan的用意，最后用np.nanmean求平均来忽略那些不存在的类。
两种做法没有绝对的对错，取决于任务需求，但手写实现时一定要明确记录自己用的是哪种，否则横向对比不同文献结果时会出现莫名其妙的差异。我个人更推荐跳过缺失类，同时对类别分布做一次统计，把覆盖率写进实验报告里，否则mIoU的数值会让人误判模型能力。
4. 从单类IoU到全局指标：mIoU、mAP与匹配逻辑的联动
很多人以为手写IoU就是算一个比值，其实IoU真正的威力体现在它作为"匹配依据"参与整个评估体系的时候。目标检测的mAP和分割的mIoU，本质上是不同聚合方式下的IoU应用。
4.1 目标检测中IoU如何参与标签匹配和NMS
在检测任务中，预测框和真实框之间并没有天然的对应关系，评测时需要一个匹配规则。最常用的规则就是贪心匹配：对每个真实框，在所有预测框里挑IoU最大且超过阈值的那个作为命中。匹配完成之后，一个预测框要么被标记为TP（命中某个真实框），要么被标记为FP（没命中任何真实框），没有匹配到的真实框就是FN。
这里的IoU同时还是NMS（非极大值抑制）cnúcleo依赖。NMS的流程是：先把所有预测框按置信度排序，选最高分的框，然后删除掉所有与它IoU大于某个阈值（通常0.5或0.45）的其他框，循环往复。手写NMS的时候，核心就是反复调用IoU计算，所以IoU实现得快不快、准不准，直接决定了整个后处理管线的效率。
如果IoU计算有1%的偏差，看起来不多，但在大量框参与的NMS里，可能导致某些被误删的框保留下来，或者该保留的被删掉，最后的mAP差别可能很大。
4.2 分割评价中mIoU的两种聚合口径
分割中计算全局mIoU时，要区分两种聚合方式。刚才说的混淆矩阵全局累加法是一种；还有一种是对每一张图单独算出各类别IoU，然后先按类别平均得到这张图的mIoU，再对所有图像取平均。这两种方法在很多开源代码和论文里混着用，导致复现结果对不上。
严格来说，全局累加法更符合"每个像素平等"的思想，它对大物体、小物体的统计权重与像素数成正比。而每图平均法会放大那些物体很小、但背景占比很高的图像的影响。在做模型改进对比时，最好固定一种口径，否则常常出现代码没变、指标变了的诡异情况。
4.3 手写实现中容易被忽略的数据类型与内存问题
分割数据集动辄几万张图，每张图几百个类别，如果不加注意，混淆矩阵累加的过程可能吃掉好几个G的内存。我建议用int64来累加，因为像素数量级很容易超过int32上限；类别数很多时，混淆矩阵是num_classes * num_classes，要考虑稀疏存储或者分批累加。
目标检测那边也有类似的坑。一次性计算[N, M]的IoU矩阵，如果N和M都是几千，这个矩阵就是几百万甚至几千万个浮点数，内存轻松破百MB。所以在实际写评测代码时，可以分块计算IoU矩阵，不要一次全算；或者对每张图片限制最大预测框数量，这些工程细节虽然不起眼，但跑大规模实验时非常关键。
5. 手写IoU的工程化细节与常见误区复盘
到了这一节，我想把自己和周围人实际踩过的坑集中复盘一下。这些问题单看都不难，但它们互相叠加之后，能让一个看起来正确的实现跑到最后都发现不了错在哪。
5.1 坐标系的混乱：左上角原点、中心坐标与归一化坐标
我曾经在一个练手项目里调试一个检测模型，训练loss降得很漂亮，验证mAP却始终在低位徘徊。排查了很久，最后发现数据加载管线把真实框从归一化坐标转回像素坐标的时候，用的图像尺寸是旧版预处理之前的，导致所有真实框都发生了偏移。IoU本身没有错，错的是坐标在不同坐标系之间转换时的"基准"没对齐。
所以这里我给个建议：无论写训练还是评测代码，先在最前面定一个全局约定——所有框一律用什么样坐标表示，进模型之前统一转换，出模型之后统一还原，中途绝不做隐式的临时转换。这条规矩看着死板，但真的能省下大量调试时间。
5.2 数值精度：浮点误差与整型除法陷阱
IoU的计算经常遇到两个非常接近的大数相减，在浮点数里这叫灾难性抵消。比如两个框都特别大，坐标值动辄几千像素，宽高差一点，面积差很多，浮点误差会被放大。这种情况下最好把所有坐标先转成float64再算，GPU上训练时用float32没问题，但离线评估阶段没有必要省这一点精度。
另一个更隐蔽的陷阱是整型除法。Python里如果交集面积和并集面积都是整数，用/没问题；但在某些语言或者用了//的地方，会得到0或1的截断值。用NumPy时，如果两个数组都是int类型，除法结果是float64，一般没事，但在一些框架的Tensor上做除法，要留意类型会不会被转成整型。加一个astype(np.float64)就能避免。
5.3 把IoU写成损失函数的技巧与梯度注意事项
手写IoU还有一种常见场景是把它当作训练损失，尤其是IoU loss、GIoU、DIoU、CIoU这一族。很多人的入门写法是loss = 1 - iou，但这里有个大坑：IoU本身对坐标的梯度极不稳定，尤其是两个框没有重叠时，IoU为0，梯度也为0，模型直接学不动。
为了解决这个问题，才衍生出了GIoU（引入最小外接框的惩罚项）和DIoU/CIoU（引入中心点距离和宽高比约束）。所以如果你打算手写IoU loss，不要停留在1 - iou，至少要引入一个在无重叠时不为0的惩罚项，否则训练过程会非常痛苦。我自己一开始就是栽在这个地方，loss曲线笔直得跟一条直线似的，换GIoU之后才有变化。
如果只是用于离线评测，就不需要关心梯度，但如果你在写可微IoU，务必检查一下梯度不回传的那些分支，避免整个loss变成常数。
6. 常见的边界场景测试集与典型错误速查
作为收尾，我想给出一套我自己用来验证IoU实现正确性的测试用例，以及我在评审别人代码时最常看到的几个错误。把这部分内容存下来，以后手写或者review代码时，至少不会在基础环节上翻车。
6.1 一组用于自测的边界测试用例
- 同一个框完全与自身比较，IoU必须等于1。
- 两个完全不相交的框，IoU必须等于0。
- 一个框完全包含另一个框，IoU等于小框面积除以大框面积。
- 两个大小相同且完全重合的框，IoU等于1。
- 两个大小相同的框横向错开一半，IoU应等于现有的重叠面积与总面积的比值。
- 两个框有一条边恰好重合，IoU等于0。
- 将坐标换成分数或者归一化表示，结果应当等价。
这些用例可以用第2节的compute_iou_matrix逐一验证，再跟sklearn.metrics或者某些成熟库的结果做对照。特别是归一化坐标和像素坐标混在一起的情况，很多人手写实现能通过前几条用例，却挂在这一条上，因为坐标尺度不一致会让所有IoU值失真。
6.2 我见过的手写实现中最典型的三个错误
第一，交集宽高判断用了>而不是>=。哪怕只差一个边界，在某些严格评测里会把刚好贴边的框误判为有重叠，导致IoU虚高。
第二，忘记了并集需要减去交集。从公式上看union = area1 + area2 - intersection，但有些人会顺手写成area1 + area2，这在大框重叠较多时，会让IoU虚低。
第三，分割中把背景类也算进mIoU平均，而评测协议里往往不计算背景类。背景类面积巨大，几乎总是被正确预测，如果把它也算进去，mIoU会被严重拉高，给人造成模型很强的假象。
这三个错误我都亲眼见到过，而且它们都藏在几百行代码里，不构造边界测试根本发现不了。
最后再分享一个我的习惯：所有涉及IoU的代码，我都会额外写一个用纯Python加循环实现的"朴素版本"用于对照。朴素版本慢，但逻辑直接；向量化版本快，但一步错整个矩阵都错。把两者的结果在少量数据上做assert，两边一致再进入后续流程。这种做法虽然多花几分钟，但能帮我把大部分低级错误挡在测试阶段之外。如果你目前正好在写检测或分割的评测代码，我强烈建议你从一开始就把这套对照测试加上。
