直接答案：mAP（mean Average Precision）是把目标检测模型在不同类别、置信度阈值，必要时再跨多个 IoU 阈值得到的 AP 取平均，用来概括“检得全不全、报得准不准、框得紧不紧”。但 mAP 不是一个脱离协议就能比较的数字：mAP@0.5、COCO AP@[0.50:0.95]、框检测 AP、掩码 AP、宏平均与微平均含义都不同。比较两个模型前，必须锁定数据集划分、标注版本、IoU 序列、最大检测数、面积范围和评测代码。
先把 IoU、Precision、Recall、AP 和 mAP 串起来
目标检测输出类别、置信度和位置。评测程序先用 IoU（交并比）判断预测框是否与某个真实框足够重合：IoU 等于交集面积除以并集面积，范围为 0 到 1。满足类别和 IoU 阈值、且对应真实对象尚未被更高分预测占用时，该预测通常记为真正例 TP；没有匹配上的预测记为假正例 FP；未被任何合格预测匹配的真实对象形成假负例 FN。
随后计算：
- Precision = TP / (TP + FP)：模型报出的对象里有多少是对的。
- Recall = TP / (TP + FN)：真实对象里有多少被找到了。
- AP：改变置信度截断后形成一系列 Precision–Recall 点，再按指定插值与采样规则汇总曲线下面积。
- mAP：对多个类别的 AP 求平均；COCO 主指标还会先在 0.50 到 0.95、步长 0.05 的十个 IoU 阈值上计算，再汇总。
想补齐概念背景，可以先看计算机视觉是什么和监督学习与标注数据。mAP 评估的是已定义数据和协议上的检测表现，不直接证明模型理解了现实世界。
一个最小例子：为什么置信度顺序会改变 AP
假设某类别有 3 个真实对象，模型按置信度从高到低给出 5 个预测。按 IoU=0.5 匹配后，结果依次为 TP、FP、TP、TP、FP。逐步加入预测时，累计 Precision 分别为 1/1、1/2、2/3、3/4、3/5，Recall 分别为 1/3、1/3、2/3、3/3、3/3。评测并不是在某一个置信度阈值上算一次 Precision，而是利用整条排序序列构建 PR 曲线。
如果把那个高分 FP 排到最后，模型的最终 TP、FP、FN 数量不变，但曲线前段的 Precision 更高，AP 通常也会提高。这解释了为什么 AP 同时考察检测能力和置信度排序质量。实际评测还要处理同一真实对象被多个预测重复命中、忽略区域、crowd 标注、没有真实样本的类别和每图最大检测数等边界，不能仅凭手算示例重写官方评测器。
mAP@0.5 与 mAP@0.5:0.95 有什么区别
| 常见写法 | IoU 规则 | 更关注什么 | 能否直接互比 |
|---|---|---|---|
| AP50 / mAP@0.5 | 固定 IoU=0.50 | 是否大体找到目标，定位要求相对宽松 | 只能与同数据、同类别平均和同评测实现比较 |
| AP75 | 固定 IoU=0.75 | 更严格的框位置与尺寸 | 不能拿来与 AP50 横比高低 |
| COCO AP / AP@[.50:.95] | 0.50、0.55…0.95 共十档 | 检测与精确定位的综合表现 | 只能与同一 COCO 式协议结果比较 |
| APs / APm / APl | COCO 式阈值，并限定对象面积区间 | 小、中、大对象的差异 | 面积定义和图像缩放必须相同 |
| Box AP / Mask AP | 分别按边界框 IoU 或掩码 IoU | 框检测或实例分割 | 两种任务不能混写成一个 mAP |
COCO 官方 COCOeval 默认检测参数明确列出 IoU 阈值 .50:.05:.95、101 个 Recall 阈值、面积范围和每图最大检测数 1/10/100。PASCAL VOC 的历史协议不同，VOC2010 还修改了 AP 的计算方式。因此，论文只写“mAP=0.72”而不写协议，信息是不完整的。
IoU 的代码也要固定。以 PyTorch 生态为例，torchvision.ops.box_iou 官方文档明确区分 xyxy、xywh 与 cxcywh。如果把中心点宽高误当成左右上下坐标，程序仍可能运行，却会得到完全错误的 IoU 和 mAP。坐标约定、像素缩放和边界是否含端点都应进入协议记录。
一份可比较的 mAP 报告必须带哪些字段
| 字段组 | 最低记录 | 遗漏后果 |
|---|---|---|
| 数据 | 数据集、train/val/test 划分、标注文件哈希、类别列表 | 无法判断是否数据泄漏或标注版本不同 |
| 任务 | bbox、segm、keypoints；类别感知或忽略类别 | 把 Box AP、Mask AP 或 proposal 指标混用 |
| 匹配 | IoU 阈值序列、ignore/crowd、最大检测数 | TP/FP 分配和召回上限改变 |
| 汇总 | Recall 采样、macro/micro、面积区间、空类别处理 | 相同预测得到不同平均值 |
| 实现 | 评测器、backend、依赖版本、完整参数 | 边界情况与默认值无法复现 |
| 运行 | 模型/代码提交、预测 JSON、NMS、图像缩放、硬件 | 离线成绩与部署管线无法对应 |
COCO Detection Evaluation 官方页面是协议入口，PASCAL VOC 官方主页还明确提醒，测试集只用于最终报告，不应用于反复调参。换言之，评测协议除了公式，还包含数据使用纪律。
协议参数改变时，分数为什么会变
评测器不是把预测文件放进去就只会产生一个固定真值。它先按协议筛选、排序和匹配，再对不同类别、尺度和 IoU 阈值汇总。只要其中一个步骤不同，同一份预测也可能得到不同结果。变化方向可以帮助排错，但不是数学保证：例如提高 IoU 阈值通常让 AP 降低，具体降幅仍取决于框的位置误差。
| 协议变化 | 常见影响 | 原因 | 正确比较方式 |
|---|---|---|---|
| IoU 从 0.50 提高到 0.75 | AP 通常下降 | 框必须更紧密重合才算 TP | 分别报告 AP50、AP75，不能相减后当误差率 |
| 每图 maxDets 从 100 改小 | 密集场景召回受限 | 低分候选在匹配前被截断 | 固定排序与 maxDets，再比较模型 |
| macro 改为 micro 平均 | 大类影响增大 | 类别等权变为样本/实例加权 | 同时给每类 AP、样本数与平均方法 |
| 评测前改变图像缩放 | 小目标和边界框波动 | 坐标舍入与面积分桶发生变化 | 保存原图尺寸、变换矩阵和反变换代码 |
| 更换 NMS 或置信度预筛 | 排序、重复框和召回改变 | 进入评测器的预测集合已不同 | 保存未截断预测及后处理配置 |
| 改变 ignore/crowd 处理 | 部分预测不再计为 FP 或匹配方式变化 | 可评对象与忽略区域不同 | 服从数据集官方逻辑，不自行简化 |
因此，复现论文或榜单时应先复现协议，再复现数字。如果新实现比旧实现高 0.3 个百分点，不能立刻称为模型改进；先把同一份冻结预测分别送入两套评测器，导出逐图、逐类和逐 IoU 的中间结果，定位第一处差异。只有协议与预测输入完全相同，分数差异才可能归因于评测实现。
PR 曲线应该怎么看
理想曲线尽量靠近右上角：在高 Recall 时仍保持高 Precision。但同一个 AP 可以由不同形状的曲线得到。安全告警系统可能宁愿多报也不能漏报，商品自动上架可能更怕误报；两者即使 mAP 相同，合适的部署阈值也不同。上线时应从业务代价选择工作点，再单独报告该阈值下的 Precision、Recall、每小时误报数和漏检类型。
数据标注会直接改变曲线。如果漏标了真实对象，模型正确预测它也可能被评测为 FP；类别边界不一致会制造系统性混淆；小框偏移几个像素就可能大幅改变 IoU。数据建设可参考站内的数据标注质量指南和数据集划分与版本管理。
mAP 用于排序，部署阈值用于做决定
AP 通常利用完整置信度排序构建 PR 曲线，而线上系统必须选择一个或一组阈值，把连续分数变成告警、拦截、复核或忽略动作。把验证集上使 F1 最大的阈值直接搬到生产环境并不稳妥：生产中的类别先验、误报成本、摄像头分布和人工审核容量可能不同。应先定义业务损失，再在未参与训练的校准集上选择工作点。
阈值验收至少包含四步：先画出关键类别的 Precision、Recall 与事件量随阈值变化的曲线；再按设备、时间、天气、遮挡和对象尺度切片；随后用真实审核容量检查每天会产生多少误报；最后在灰度流量中观察连续帧和事件级结果。阈值变化不能改写离线 mAP，但会直接改变线上 TP、FP 与 FN，所以模型版本与阈值版本必须分别记录、一起回滚。
硬件和服务管线也会改变可用工作点。追求低时延时，批量大小、解码、前后处理和加速器调度都要计入端到端预算；可参考Groq LPU 低延迟边界与生产测试理解“芯片峰值”为什么不等于服务时延。mAP、P95 时延、吞吐、内存和功耗必须在同一候选配置上验收。
用 TorchMetrics 复现 COCO 式 mAP
下面代码展示最小输入结构。预测列表中的每张图需要 boxes、scores 和 labels；真实标注需要 boxes 和 labels。默认框格式可设为 xyxy，默认 IoU 阈值序列为 0.50 到 0.95、步长 0.05。运行前应锁定 PyTorch、TorchMetrics 和 pycocotools 版本，并把完整配置随结果保存。
from torch import tensor
from torchmetrics.detection.mean_ap import MeanAveragePrecision
metric = MeanAveragePrecision(
box_format="xyxy",
iou_type="bbox",
class_metrics=True,
)
preds = [{
"boxes": tensor([[10., 10., 50., 50.], [60., 20., 100., 70.]]),
"scores": tensor([0.92, 0.61]),
"labels": tensor([1, 1]),
}]
target = [{
"boxes": tensor([[12., 12., 49., 51.]]),
"labels": tensor([1]),
}]
metric.update(preds, target)
result = metric.compute()
print(result["map"], result["map_50"], result["map_75"])代码只是接口示例，不是任何模型的实测成绩。实际项目还要确认坐标是绝对像素还是归一化值、框格式是 xyxy 还是 xywh、类别编号是否一致、无标注图片是否保留、预测是否在评测前做了额外 NMS，以及分布式推理是否完整聚合。PyTorch 的框架背景可参考PyTorch 原理与实践。
TorchMetrics 1.9.0 当前文档还提供 pycocotools 与 faster_coco_eval 两种 backend，并允许 average="macro" 或 "micro"。默认相似不意味着可以省略记录：采用替代 backend 时应固定版本并运行对照样本。可查看faster-coco-eval 项目及Torchvision detection 参考实现，但最终成绩仍要服从项目指定的评测器。
模型分数异常时，按什么顺序排查
- 先做完美预测测试：把真实标注复制成置信度为 1 的预测，理论上应接近满分；若不是，优先查 ID、类别、坐标和 ignore/crowd 字段。
- 再做单图单类手算：保存 IoU 矩阵、匹配顺序、TP/FP 和累计 PR 点，确认重复框怎样处理。
- 核对数据划分：训练集、验证集、测试集不能交叉；同一视频的相邻帧应按场景分组，避免泄漏。
- 检查类别分布：宏平均会让每个类别权重相同，少样本类别波动可能显著影响 mAP；同时报告每类 AP 和样本数。
- 拆分对象尺度与场景：查看 APs/APm/APl，以及夜间、遮挡、逆光、密集和设备来源等业务切片。
- 固定评测环境：记录代码提交、依赖锁、标注文件哈希、预测 JSON、参数和完整控制台输出。
从分数症状定位第一检查点
| 观察到的症状 | 第一检查点 | 需要保存的证据 | 通过后再做什么 |
|---|---|---|---|
| 完美预测也不能接近满分 | 图像 ID、框格式、类别映射、ignore/crowd | 单图 IoU、匹配和 TP/FP 明细 | 检查分布式聚合与评测参数 |
| AP50 尚可但 AP75 明显低 | 框中心、宽高、边界定义与标注一致性 | 匹配框 IoU 分布和误差可视化 | 再分析回归损失与输入分辨率 |
| 少数类别突然归零 | 类别编号、空类别、样本数与名称映射 | 类别表、标注计数和预测计数 | 检查训练采样和类别混淆 |
| 换 backend 后整体漂移 | IoU、Recall、maxDets、面积与平均方法 | 冻结预测的双实现逐项输出 | 确认边界行为和依赖版本 |
| 离线稳定但线上漏报增多 | 预处理一致性、数据漂移和阈值版本 | 线上切片、原图、模型与阈值哈希 | 重建校准集并灰度调整 |
| 总 mAP 上升但关键场景退化 | 关键类别与最坏切片 | 新旧版本逐切片差异及置信区间 | 按上线门禁决定拒绝或例外 |
排错结论也应进入审计记录，而不是只留在聊天消息里。可以借鉴AI 会议纪要中的决策、待办与核验方法：把异常、证据、负责人、结论和复测条件分开记录。这样下一次依赖升级或数据换版时，团队能判断是已知差异、回归还是新的数据问题。
用四个合成样本验证评测管线
| 合成样本 | 预期现象 | 主要验证 |
|---|---|---|
| 标注原样复制为预测，分数均为 1 | 相关类别和阈值接近满分 | 坐标、类别、图像 ID、ignore/crowd |
| 每个真实框复制两个相同预测 | 一个匹配为 TP，其余形成重复 FP | 一对一匹配与排序 |
| 框逐步平移，跨过 0.50/0.75 | AP75 先下降，随后 AP50 下降 | IoU 计算与阈值序列 |
| 加入无标注图片上的高分预测 | 产生 FP，Precision 下降 | 空图是否被错误过滤 |
| 每图产生超过 100 个预测 | COCO 默认 maxDets 截断生效 | 排序、截断和召回上限 |
每个合成样本都应保存预测、标注和预期结果，进入持续集成。这样在升级依赖、替换 backend、改变图像预处理或并行聚合方式时，可以先发现评测器漂移，而不是等模型排行异常后再追溯。
为什么 mAP 高，生产效果仍可能差
- 数据漂移：离线测试没有覆盖新摄像头、季节、工件、地区或用户行为。
- 类别代价不同：平均值掩盖了关键类别的漏检；低风险大类可能把总分抬高。
- 时延与吞吐缺失：mAP 不包含解码、预处理、网络传输、NMS 和硬件上的端到端时延。
- 校准不足：置信度用于排序不等于概率可信；部署阈值迁移到新分布后可能失效。
- 标注定义偏离业务：测试集把“可见一角”算目标，而生产规则可能要求完整可操作对象，反之亦然。
验收报告至少应同时给出主 mAP 协议、AP50/AP75、关键类别 AP、对象尺度、业务切片、所选阈值的 Precision/Recall、误报与漏报样例、端到端时延和硬件配置。只用一个 mAP 排名，无法决定模型是否适合部署。
| 生产目标 | mAP之外必须增加 | 示例停止条件 |
|---|---|---|
| 安全告警 | 关键类别漏检率、最坏切片、连续帧召回 | 任一高危类别漏检超过上限 |
| 自动上架/质检 | 误报率、人工复核量、缺陷类型混淆 | 每日误报超出审核能力 |
| 边缘设备 | 端到端 P50/P95 时延、内存、功耗、温度降频 | P95 时延或峰值内存超预算 |
| 视频流 | 解码、跟踪、丢帧、持续吞吐和事件级指标 | 长时间运行吞吐低于输入帧率 |
| 持续迭代 | 数据漂移、校准、版本回归与灰度监控 | 关键切片显著退化即回滚 |
NIST AI TEVV强调测量必须结合系统用途和运行情境；这不是 COCO 指标定义的一部分，但能解释为什么生产验收需要准确性、可靠性、鲁棒性和安全等多组证据。吞吐和时延若采用行业基准，还应明确规则版本；例如MLCommons Inference Policies把场景、精度约束、性能运行和提交规则分别定义，不能只复制一个 samples/s 数字。
mAP 提高多少才值得上线
“提高 0.2 个百分点”本身不能回答是否值得上线。首先确认新旧模型使用同一份冻结测试集、同一预测后处理和同一评测器；其次检查变化来自多少张图片、多少个类别和哪些场景。如果总体上升只由高频大类贡献，而安全关键类别或夜间切片下降，平均值改善仍可能不满足门禁。
可以按图片或场景组进行配对重采样，观察新旧差值的分布，但重采样单位必须尊重数据相关性：同一视频的相邻帧不能被当成完全独立样本。报告应同时给出点估计、重采样方法、组数、随机种子和差值区间，并把每类 AP、对象尺度与业务切片并列展示。区间跨过零不自动证明两个模型完全等价，只表示现有样本不足以稳定确认差异方向。
上线决策还应计算交换成本：模型文件、显存、端到端 P95 时延、吞吐、能耗、人工复核量和回滚复杂度。若 mAP 小幅提高却让关键设备超出时延预算，应拒绝或继续优化；若总 mAP 几乎不变，但高危类别漏检明显下降且其他门禁不退化，仍可能具有业务价值。最终规则要在测试前写入验收表，避免看完结果后临时选择对候选模型有利的指标，并保留拒绝上线的具体证据与复测条件并归档。
结果归档与复现清单
| 制品 | 必须保存 | 用途 |
|---|---|---|
| 数据身份 | 图片清单、split、标注哈希、类别映射 | 证明评测分母 |
| 模型身份 | 权重哈希、配置、代码提交、预处理 | 定位实际被测对象 |
| 预测原件 | 未截断预测、分数、坐标、图像 ID | 重跑不同协议和排查异常 |
| 评测环境 | 依赖锁、backend、参数、硬件与容器摘要 | 复现实现差异 |
| 完整输出 | COCOeval summary、每类/切片结果、日志 | 避免只保留主 mAP |
| 签发记录 | 复核人、日期、例外、是否允许上线 | 区分实验结果与生产决定 |
官方资料与复核范围
COCO 的评测参数、输入字段和汇总逻辑可直接查看官方 COCOeval 源码及COCO API 仓库；数据集与任务背景见Microsoft COCO 论文。VOC 历史协议和 AP 变更见PASCAL VOC2010 开发套件文档与VOC Challenge 论文页。代码接口与默认阈值见TorchMetrics MeanAveragePrecision 文档。
资料复核日期：2026 年 7 月 19 日。本文讨论边界框与实例分割常见 mAP；分类、信息检索、关键点和全景分割可能使用名称相似但定义不同的指标。运行任何基准前，应以具体挑战赛、数据集或监管验收文件的版本化协议为准。
编辑复核与纠错记录：本文由兰塞 AI 编辑流程于 2026 年 7 月 19 日复核。原稿混用公式 Markdown、固定结论和泛化的“2026 演进”叙述，缺少可执行的协议核对；本版回到 COCO API、VOC 文档、原始论文、Torchvision 和 TorchMetrics 当前接口，新增最小手算例、协议身份证、协议参数差异、阈值选型、异常诊断矩阵、合成评测管线测试、生产指标、复现制品与三张正文原创图。本文没有虚构模型成绩或亲自测试结果。本站更新与纠错原则见关于本站与编辑规范。
