supervision Legacy 评估 API 详解ConfusionMatrix 与 MeanAveragePrecision 的原理、用法与迁移指南【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision本篇聚焦 supervision 文档中的 Legacy Metrics遗留评估 API即 src/supervision/metrics/detection.py 中实现的ConfusionMatrix与MeanAveragePrecision两个对象检测评估类。文章覆盖二者的完整属性、构建方式、贪心匹配与 COCO 101 点插值等底层实现细节以及自0.23.0起引入的新 metrics 模块与遗留 API 的关系和迁移路径。读完后可独立完成安装 metrics 依赖、用from_detections/from_tensors/benchmark三种入口计算混淆矩阵与 mAP理解 TP/FP/FN 归属逻辑并判断何时应改用新版指标模块。Legacy Metrics 的定位与安装自 supervision0.23.0起项目引入了全新的 metrics 模块src/supervision/metrics/init.py 导出的MeanAveragePrecision、F1Score、Precision、Recall、MeanAverageRecall等。sv.ConfusionMatrix和顶层sv.MeanAveragePrecision来自supervision.metrics.detection则属于遗留评估 API文档明确说明其will be deprecated in the future见 docs/detection/metrics.md。使用本页 API 前需要安装 metrics 可选依赖pip install supervision[metrics]从 pyproject.toml 可以看到该 extra 目前只额外安装了pandas2。这两个类通过 src/supervision/init.py 暴露在顶层命名空间因此可直接以sv.ConfusionMatrix、sv.MeanAveragePrecision的方式引用。需要注意两者的废弃状态并不相同以当前仓库源码为准当前开发版本为0.31.0.dev0类废弃标记源码事实sv.ConfusionMatrix未加deprecated_class装饰器但被文档归为 legacy APIsv.MeanAveragePrecision有deprecated_class(deprecated_in0.27.0, remove_in0.31.0)且 docstring 明确提示其结果与 pycocotools 不一致推荐使用supervision.metrics.mean_average_precision.MeanAveragePrecisionConfusionMatrix按类统计 TP / FP / FNConfusionMatrix是一个 dataclass定义于 src/supervision/metrics/detection.py用于对象检测任务的混淆矩阵统计。其核心属性如下属性类型说明matrixnp.ndarray[np.int32]形状为(len(classes) 1, len(classes) 1)的二维矩阵最后多出的行列用于汇总 FP / FNclasseslist[str]模型类别名列表conf_thresholdfloat置信度阈值0~1低于该值的预测不计入矩阵iou_thresholdfloatIoU 阈值0~1低于该值的预测-真值对不会被匹配预测记为 FPmetric_targetMetricTargetIoU 计算所用坐标类型BOXES默认或ORIENTED_BOUNDING_BOXESMASKS不受支持MetricTarget枚举定义在 src/supervision/metrics/core.py取值BOXESxyxy 框、MASKS掩码、ORIENTED_BOUNDING_BOXESOBB 旋转框。ConfusionMatrix仅支持前两者之外的 BOXES 与 OBB 两种——传入MetricTarget.MASKS会抛出ValueError见detection.py中的_assert_supported_target。三种构建方式1.from_detections从sv.Detections列表构建import numpy as np import supervision as sv targets [ sv.Detections( xyxynp.array([[0, 0, 10, 10], [50, 50, 60, 60]]), class_idnp.array([0, 0]), ) ] predictions [ sv.Detections( xyxynp.array([[0, 0, 10, 10], [100, 100, 110, 110]]), class_idnp.array([0, 0]), confidencenp.array([0.9, 0.8]), ) ] confusion_matrix sv.ConfusionMatrix.from_detections( predictionspredictions, targetstargets, classes[person], conf_threshold0.3, # 默认值 0.3 iou_threshold0.5, # 默认值 0.5 ) print(confusion_matrix.matrix) # array([[1, 1], # [1, 0]], dtypeint32)from_detections内部先把每组Detections转换为张量再调用from_tensors。转换规则由detections_to_tensor实现src/supervision/metrics/detection.pyMetricTarget.BOXES预测张量行格式(x_min, y_min, x_max, y_max, class_id, confidence)即(M, 6)真值无 confidence为(N, 5)。MetricTarget.ORIENTED_BOUNDING_BOXES要求detections.data[ORIENTED_BOX_COORDINATES]中存有 float32 的 OBB 坐标形状(N, 8)扁平或(N, 4, 2)sv.Detections.from_ultralytics的存储形式内部统一规整为(N, 8)对应张量行为(x1, y1, x2, y2, x3, y3, x4, y4, class_id [, confidence])即预测(M, 10)、真值(N, 9)。class_id为None会报错with_confidenceTrue但confidence为None也会报错。2.from_tensors直接从 numpy 张量列表构建import numpy as np import supervision as sv targets [ np.array([ [0.0, 0.0, 3.0, 3.0, 0], [2.0, 2.0, 5.0, 5.0, 0], [6.0, 1.0, 8.0, 3.0, 1], ]) ] predictions [ np.array([ [0.0, 0.0, 3.0, 3.0, 0, 0.9], [0.1, 0.1, 3.0, 3.0, 0, 0.9], [6.0, 1.0, 8.0, 3.0, 1, 0.8], ]) ] confusion_matrix sv.ConfusionMatrix.from_tensors( predictionspredictions, targetstargets, classes[person, dog], ) print(confusion_matrix.matrix) # array([[1, 0, 1], # [0, 1, 0], # [1, 0, 0]], dtypeint32)_validate_input_tensors会校验预测与真值列表长度一致、元素必须是 numpy 数组、列数符合metric_target的期望BOXES 为 6/5 列OBB 为 10/9 列。3.benchmark数据集 回调函数一步到位import supervision as sv dataset sv.DetectionDataset.from_yolo( images_directory_path.../test/images, annotations_directory_path.../test/labels, data_yaml_path.../data.yaml, ) def callback(image: np.ndarray) - sv.Detections: return model.predict(image[:, :, ::-1]) confusion_matrix sv.ConfusionMatrix.benchmark( datasetdataset, callbackcallback, conf_threshold0.3, iou_threshold0.5, save_directory_path./results, # 可选 ) print(confusion_matrix.matrix)benchmark遍历DetectionDataset每轮产出image_name, image, annotation调用callback得到预测后汇总。可选参数save_directory_path关键参数仅benchmark支持会在该目录中为每张图写出一张 2x2 结果拼图按原图文件名直接落盘四个面板分别为Ground Truth、True Positives、False Positives、False Negatives。从源码看_save_detection_validation_visualizationsrc/supervision/metrics/detection.py该拼图通过_split_detections_by_outcome复用与evaluate_detection_batch相同的匹配逻辑划分 TP/FP/FN并用BoxAnnotator/LabelAnnotator按类别着色绘制若目录中已存在同名文件会发出UserWarning后覆盖。完整的基准测试工作流可参考 docs/how_to/benchmark_a_model.md。匹配算法TP / FP / FN 如何归属单张图的矩阵累加由静态方法evaluate_detection_batch完成流程可从源码逐段印证形状校验预测(M, 6)或 OBB 下(M, 10)真值(N, 5)或(N, 9)。置信度过滤predictions[confidence conf_threshold]留下参与匹配的预测。边界短路无有效预测时所有真值计入matrix[gt_class, num_classes]FN 汇总列真值为空时所有有效预测计入matrix[num_classes, det_class]FP 汇总行。IoU 矩阵BOXES 用box_iou_batchOBB 用oriented_box_iou_batch均来自 src/supervision/detection/utils/iou_and_nms.py。贪心匹配取所有iou iou_threshold的候选对用np.lexsort按同类优先、IoU 降序排序后逐一贪心分配每个真值与每个预测最多匹配一次。跨类空间匹配的特殊处理两个框空间重叠但类别不同时matrix[gt_class, det_class] 1——即该预测对目标类别是 FP错检对预测类别是 FN漏检同一笔错检同时体现在两个位置。汇总未匹配真值累加到 FN 列未匹配预测累加到 FP 行。矩阵语义因此是matrix[i, j]i ! j且均在类索引范围内 真值为类 i 但被预测成类 j 的数量对角线 TP最后一列 各类 FN最后一行 各类 FP。plot热力图可视化fig confusion_matrix.plot( save_pathNone, # 给路径则保存为 250 dpi 透明背景 PNG titleCorgi benchmark, # 可选标题 classesNone, # 自定义显示类别None 则显示全部 normalizeFalse, # True 时按列归一化 fig_size(12, 10), # 画布尺寸 )实现细节plot方法矩阵先转float64normalizeTrue时按列求和归一化小于0.005的单元格置为NaN以隐藏噪点坐标轴刻度默认显示类名并追加FN/FP两个汇总刻度格子数少于 30 个时会在每个单元格内标注数值颜色随数值大小在黑/白之间切换。MeanAveragePrecision遗留版mAP50:95 的计算sv.MeanAveragePrecisionfrozen dataclass定义于 src/supervision/metrics/detection.py的四个属性为属性含义map50_95IoU 阈值 0.50~0.95步长 0.05十个档位上的 mAP 均值map50仅 IoU 0.50 时的 mAPmap75仅 IoU 0.75 时的 mAPper_class_ap50_95每个类在 10 个 IoU 档位上的 AP 数组形状(num_classes, 10)再次强调源码 docstring 中的废弃提示该实现自0.27.0起被标记 deprecated计划于0.31.0移除官方理由是deprecated implementation provides results that are inconsistent with pycocotools建议改用新版supervision.metrics.mean_average_precision.MeanAveragePrecision该新实现与 pycocotools 结果一致。如果你的目标是与 COCO 评测对齐请优先走新模块下述内容用于理解遗留实现本身及已有代码。计算入口import supervision as sv # 方式一从 Detections 列表 mAP sv.MeanAveragePrecision.from_detections( predictionspredictions_list, # list[sv.Detections] targetstargets_list, # list[sv.Detections] ) # 方式二从张量列表每图 (M,6) / (N,5) mAP sv.MeanAveragePrecision.from_tensors( predictionsprediction_tensors, targetstarget_tensors, ) # 方式三数据集 回调 mAP sv.MeanAveragePrecision.benchmark( datasetdataset, callbackcallback, ) print(mAP.map50_95, mAP.map50, mAP.map75)一个最小示例单图单框完全重合且类别一致时map50为1.0若真值为空的背景图上存在预测这些预测全部计为 FP会压低 AP背景图语义在from_tensors的 docstring 中有明确说明。实现原理IoU 档位、贪心匹配与 101 点插值from_tensors的核心计算链可以从源码拆解为三步多档 IoU 匹配_match_detection_batchIoU 档位为np.linspace(0.5, 0.95, 10)即[0.50, 0.55, ..., 0.95]共 10 档。对每一档用box_iou_batch算整图 IoU 矩阵要求iou 档位值且类别一致再经_greedy_match来自 src/supervision/metrics/utils/matching.py保证每个真值与预测各只匹配一次。最终得到每图每档的 TP 布尔矩阵。按置信度排序累计 P/R_average_precisions_per_class所有图的匹配结果、预测置信度与类别被拼接后按预测置信度全局降序排列对每个类分别累加true_positives/false_positives得到 recall 与 precision 曲线。注意此处只统计至少在一个真值图中出现的类——从未出现在 GT 中的类会被跳过。COCO 101 点插值compute_average_precision将 precision 做从尾部起的最大值累积单调包络再在 recall 0, 0.01, ..., 1.0 的 101 个取整点采样求均值即标准 COCO AP 定义。边界情况同样有源码背书若所有图都没有真值函数返回0.0而非NaNmap50/map75/map50_95分别取平均精度数组的第 1 列、第 6 列0.75 档与全体均值。与新版指标的差异提示新版supervision.metrics中的指标采用update(...).compute()的两段式 API基类Metric定义于 src/supervision/metrics/core.py支持MetricTarget.BOXES / MASKS / ORIENTED_BOUNDING_BOXES与AveragingMethod.MACRO / MICRO / WEIGHTED三种平均方式并额外提供按对象尺寸small / medium / large的细分结果而遗留版MeanAveragePrecision仅支持 xyxy 框、固定按类宏平均。从 Legacy 迁移到新指标模块的对照结合 src/supervision/metrics/init.py 的导出与 docs/metrics/ 下的文档迁移对照关系如下Legacy本页新模块推荐替代关键差异sv.MeanAveragePrecisionsupervision.metrics.detectionsupervision.metrics.mean_average_precision.MeanAveragePrecision新版结果与 pycocotools 一致支持 MASKS / OBB、尺寸细分sv.ConfusionMatrix.from_detections(...)新模块未提供同名类可保留使用目前ConfusionMatrix源码中无废弃装饰器但仍属 legacy 页面范畴建议关注后续版本一次性from_tensorsmetric.update(predictions, targets).compute()新版支持流式累积便于大图集分批评估新模块各指标的详细说明可查阅仓库内文档mAP、F1 Score、Precision、Recall、MAR、常用数值。小结与适用前提本仓库当前开发版本为0.31.0.dev0见 pyproject.tomlsv.MeanAveragePrecision携带0.31.0 移除的废弃标记新增代码不应再依赖它sv.ConfusionMatrix则暂无源码级废弃标记但仍位于 legacy 文档页使用时应留意版本演进。使用任一 API 前先执行pip install supervision[metrics]ConfusionMatrix要求预测携带confidencebenchmark/from_detections路径、两者都要求class_id非空。conf_threshold与iou_threshold默认值分别为0.3与0.5直接决定 TP 判定口径跨配置比较指标时必须保持一致。若需要逐图定位错检/漏检原因sv.ConfusionMatrix.benchmark(..., save_directory_path...)会产出 GT/TP/FP/FN 四宫格拼图是与数值指标配合的最快排障手段。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 supervision Legacy 评估 API 详解：ConfusionMatrix 与 MeanAveragePrecision 的原理、用法与迁移指南
supervision Legacy 评估 API 详解ConfusionMatrix 与 MeanAveragePrecision 的原理、用法与迁移指南【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision本篇聚焦 supervision 文档中的 Legacy Metrics遗留评估 API即 src/supervision/metrics/detection.py 中实现的ConfusionMatrix与MeanAveragePrecision两个对象检测评估类。文章覆盖二者的完整属性、构建方式、贪心匹配与 COCO 101 点插值等底层实现细节以及自0.23.0起引入的新 metrics 模块与遗留 API 的关系和迁移路径。读完后可独立完成安装 metrics 依赖、用from_detections/from_tensors/benchmark三种入口计算混淆矩阵与 mAP理解 TP/FP/FN 归属逻辑并判断何时应改用新版指标模块。Legacy Metrics 的定位与安装自 supervision0.23.0起项目引入了全新的 metrics 模块src/supervision/metrics/init.py 导出的MeanAveragePrecision、F1Score、Precision、Recall、MeanAverageRecall等。sv.ConfusionMatrix和顶层sv.MeanAveragePrecision来自supervision.metrics.detection则属于遗留评估 API文档明确说明其will be deprecated in the future见 docs/detection/metrics.md。使用本页 API 前需要安装 metrics 可选依赖pip install supervision[metrics]从 pyproject.toml 可以看到该 extra 目前只额外安装了pandas2。这两个类通过 src/supervision/init.py 暴露在顶层命名空间因此可直接以sv.ConfusionMatrix、sv.MeanAveragePrecision的方式引用。需要注意两者的废弃状态并不相同以当前仓库源码为准当前开发版本为0.31.0.dev0类废弃标记源码事实sv.ConfusionMatrix未加deprecated_class装饰器但被文档归为 legacy APIsv.MeanAveragePrecision有deprecated_class(deprecated_in0.27.0, remove_in0.31.0)且 docstring 明确提示其结果与 pycocotools 不一致推荐使用supervision.metrics.mean_average_precision.MeanAveragePrecisionConfusionMatrix按类统计 TP / FP / FNConfusionMatrix是一个 dataclass定义于 src/supervision/metrics/detection.py用于对象检测任务的混淆矩阵统计。其核心属性如下属性类型说明matrixnp.ndarray[np.int32]形状为(len(classes) 1, len(classes) 1)的二维矩阵最后多出的行列用于汇总 FP / FNclasseslist[str]模型类别名列表conf_thresholdfloat置信度阈值0~1低于该值的预测不计入矩阵iou_thresholdfloatIoU 阈值0~1低于该值的预测-真值对不会被匹配预测记为 FPmetric_targetMetricTargetIoU 计算所用坐标类型BOXES默认或ORIENTED_BOUNDING_BOXESMASKS不受支持MetricTarget枚举定义在 src/supervision/metrics/core.py取值BOXESxyxy 框、MASKS掩码、ORIENTED_BOUNDING_BOXESOBB 旋转框。ConfusionMatrix仅支持前两者之外的 BOXES 与 OBB 两种——传入MetricTarget.MASKS会抛出ValueError见detection.py中的_assert_supported_target。三种构建方式1.from_detections从sv.Detections列表构建import numpy as np import supervision as sv targets [ sv.Detections( xyxynp.array([[0, 0, 10, 10], [50, 50, 60, 60]]), class_idnp.array([0, 0]), ) ] predictions [ sv.Detections( xyxynp.array([[0, 0, 10, 10], [100, 100, 110, 110]]), class_idnp.array([0, 0]), confidencenp.array([0.9, 0.8]), ) ] confusion_matrix sv.ConfusionMatrix.from_detections( predictionspredictions, targetstargets, classes[person], conf_threshold0.3, # 默认值 0.3 iou_threshold0.5, # 默认值 0.5 ) print(confusion_matrix.matrix) # array([[1, 1], # [1, 0]], dtypeint32)from_detections内部先把每组Detections转换为张量再调用from_tensors。转换规则由detections_to_tensor实现src/supervision/metrics/detection.pyMetricTarget.BOXES预测张量行格式(x_min, y_min, x_max, y_max, class_id, confidence)即(M, 6)真值无 confidence为(N, 5)。MetricTarget.ORIENTED_BOUNDING_BOXES要求detections.data[ORIENTED_BOX_COORDINATES]中存有 float32 的 OBB 坐标形状(N, 8)扁平或(N, 4, 2)sv.Detections.from_ultralytics的存储形式内部统一规整为(N, 8)对应张量行为(x1, y1, x2, y2, x3, y3, x4, y4, class_id [, confidence])即预测(M, 10)、真值(N, 9)。class_id为None会报错with_confidenceTrue但confidence为None也会报错。2.from_tensors直接从 numpy 张量列表构建import numpy as np import supervision as sv targets [ np.array([ [0.0, 0.0, 3.0, 3.0, 0], [2.0, 2.0, 5.0, 5.0, 0], [6.0, 1.0, 8.0, 3.0, 1], ]) ] predictions [ np.array([ [0.0, 0.0, 3.0, 3.0, 0, 0.9], [0.1, 0.1, 3.0, 3.0, 0, 0.9], [6.0, 1.0, 8.0, 3.0, 1, 0.8], ]) ] confusion_matrix sv.ConfusionMatrix.from_tensors( predictionspredictions, targetstargets, classes[person, dog], ) print(confusion_matrix.matrix) # array([[1, 0, 1], # [0, 1, 0], # [1, 0, 0]], dtypeint32)_validate_input_tensors会校验预测与真值列表长度一致、元素必须是 numpy 数组、列数符合metric_target的期望BOXES 为 6/5 列OBB 为 10/9 列。3.benchmark数据集 回调函数一步到位import supervision as sv dataset sv.DetectionDataset.from_yolo( images_directory_path.../test/images, annotations_directory_path.../test/labels, data_yaml_path.../data.yaml, ) def callback(image: np.ndarray) - sv.Detections: return model.predict(image[:, :, ::-1]) confusion_matrix sv.ConfusionMatrix.benchmark( datasetdataset, callbackcallback, conf_threshold0.3, iou_threshold0.5, save_directory_path./results, # 可选 ) print(confusion_matrix.matrix)benchmark遍历DetectionDataset每轮产出image_name, image, annotation调用callback得到预测后汇总。可选参数save_directory_path关键参数仅benchmark支持会在该目录中为每张图写出一张 2x2 结果拼图按原图文件名直接落盘四个面板分别为Ground Truth、True Positives、False Positives、False Negatives。从源码看_save_detection_validation_visualizationsrc/supervision/metrics/detection.py该拼图通过_split_detections_by_outcome复用与evaluate_detection_batch相同的匹配逻辑划分 TP/FP/FN并用BoxAnnotator/LabelAnnotator按类别着色绘制若目录中已存在同名文件会发出UserWarning后覆盖。完整的基准测试工作流可参考 docs/how_to/benchmark_a_model.md。匹配算法TP / FP / FN 如何归属单张图的矩阵累加由静态方法evaluate_detection_batch完成流程可从源码逐段印证形状校验预测(M, 6)或 OBB 下(M, 10)真值(N, 5)或(N, 9)。置信度过滤predictions[confidence conf_threshold]留下参与匹配的预测。边界短路无有效预测时所有真值计入matrix[gt_class, num_classes]FN 汇总列真值为空时所有有效预测计入matrix[num_classes, det_class]FP 汇总行。IoU 矩阵BOXES 用box_iou_batchOBB 用oriented_box_iou_batch均来自 src/supervision/detection/utils/iou_and_nms.py。贪心匹配取所有iou iou_threshold的候选对用np.lexsort按同类优先、IoU 降序排序后逐一贪心分配每个真值与每个预测最多匹配一次。跨类空间匹配的特殊处理两个框空间重叠但类别不同时matrix[gt_class, det_class] 1——即该预测对目标类别是 FP错检对预测类别是 FN漏检同一笔错检同时体现在两个位置。汇总未匹配真值累加到 FN 列未匹配预测累加到 FP 行。矩阵语义因此是matrix[i, j]i ! j且均在类索引范围内 真值为类 i 但被预测成类 j 的数量对角线 TP最后一列 各类 FN最后一行 各类 FP。plot热力图可视化fig confusion_matrix.plot( save_pathNone, # 给路径则保存为 250 dpi 透明背景 PNG titleCorgi benchmark, # 可选标题 classesNone, # 自定义显示类别None 则显示全部 normalizeFalse, # True 时按列归一化 fig_size(12, 10), # 画布尺寸 )实现细节plot方法矩阵先转float64normalizeTrue时按列求和归一化小于0.005的单元格置为NaN以隐藏噪点坐标轴刻度默认显示类名并追加FN/FP两个汇总刻度格子数少于 30 个时会在每个单元格内标注数值颜色随数值大小在黑/白之间切换。MeanAveragePrecision遗留版mAP50:95 的计算sv.MeanAveragePrecisionfrozen dataclass定义于 src/supervision/metrics/detection.py的四个属性为属性含义map50_95IoU 阈值 0.50~0.95步长 0.05十个档位上的 mAP 均值map50仅 IoU 0.50 时的 mAPmap75仅 IoU 0.75 时的 mAPper_class_ap50_95每个类在 10 个 IoU 档位上的 AP 数组形状(num_classes, 10)再次强调源码 docstring 中的废弃提示该实现自0.27.0起被标记 deprecated计划于0.31.0移除官方理由是deprecated implementation provides results that are inconsistent with pycocotools建议改用新版supervision.metrics.mean_average_precision.MeanAveragePrecision该新实现与 pycocotools 结果一致。如果你的目标是与 COCO 评测对齐请优先走新模块下述内容用于理解遗留实现本身及已有代码。计算入口import supervision as sv # 方式一从 Detections 列表 mAP sv.MeanAveragePrecision.from_detections( predictionspredictions_list, # list[sv.Detections] targetstargets_list, # list[sv.Detections] ) # 方式二从张量列表每图 (M,6) / (N,5) mAP sv.MeanAveragePrecision.from_tensors( predictionsprediction_tensors, targetstarget_tensors, ) # 方式三数据集 回调 mAP sv.MeanAveragePrecision.benchmark( datasetdataset, callbackcallback, ) print(mAP.map50_95, mAP.map50, mAP.map75)一个最小示例单图单框完全重合且类别一致时map50为1.0若真值为空的背景图上存在预测这些预测全部计为 FP会压低 AP背景图语义在from_tensors的 docstring 中有明确说明。实现原理IoU 档位、贪心匹配与 101 点插值from_tensors的核心计算链可以从源码拆解为三步多档 IoU 匹配_match_detection_batchIoU 档位为np.linspace(0.5, 0.95, 10)即[0.50, 0.55, ..., 0.95]共 10 档。对每一档用box_iou_batch算整图 IoU 矩阵要求iou 档位值且类别一致再经_greedy_match来自 src/supervision/metrics/utils/matching.py保证每个真值与预测各只匹配一次。最终得到每图每档的 TP 布尔矩阵。按置信度排序累计 P/R_average_precisions_per_class所有图的匹配结果、预测置信度与类别被拼接后按预测置信度全局降序排列对每个类分别累加true_positives/false_positives得到 recall 与 precision 曲线。注意此处只统计至少在一个真值图中出现的类——从未出现在 GT 中的类会被跳过。COCO 101 点插值compute_average_precision将 precision 做从尾部起的最大值累积单调包络再在 recall 0, 0.01, ..., 1.0 的 101 个取整点采样求均值即标准 COCO AP 定义。边界情况同样有源码背书若所有图都没有真值函数返回0.0而非NaNmap50/map75/map50_95分别取平均精度数组的第 1 列、第 6 列0.75 档与全体均值。与新版指标的差异提示新版supervision.metrics中的指标采用update(...).compute()的两段式 API基类Metric定义于 src/supervision/metrics/core.py支持MetricTarget.BOXES / MASKS / ORIENTED_BOUNDING_BOXES与AveragingMethod.MACRO / MICRO / WEIGHTED三种平均方式并额外提供按对象尺寸small / medium / large的细分结果而遗留版MeanAveragePrecision仅支持 xyxy 框、固定按类宏平均。从 Legacy 迁移到新指标模块的对照结合 src/supervision/metrics/init.py 的导出与 docs/metrics/ 下的文档迁移对照关系如下Legacy本页新模块推荐替代关键差异sv.MeanAveragePrecisionsupervision.metrics.detectionsupervision.metrics.mean_average_precision.MeanAveragePrecision新版结果与 pycocotools 一致支持 MASKS / OBB、尺寸细分sv.ConfusionMatrix.from_detections(...)新模块未提供同名类可保留使用目前ConfusionMatrix源码中无废弃装饰器但仍属 legacy 页面范畴建议关注后续版本一次性from_tensorsmetric.update(predictions, targets).compute()新版支持流式累积便于大图集分批评估新模块各指标的详细说明可查阅仓库内文档mAP、F1 Score、Precision、Recall、MAR、常用数值。小结与适用前提本仓库当前开发版本为0.31.0.dev0见 pyproject.tomlsv.MeanAveragePrecision携带0.31.0 移除的废弃标记新增代码不应再依赖它sv.ConfusionMatrix则暂无源码级废弃标记但仍位于 legacy 文档页使用时应留意版本演进。使用任一 API 前先执行pip install supervision[metrics]ConfusionMatrix要求预测携带confidencebenchmark/from_detections路径、两者都要求class_id非空。conf_threshold与iou_threshold默认值分别为0.3与0.5直接决定 TP 判定口径跨配置比较指标时必须保持一致。若需要逐图定位错检/漏检原因sv.ConfusionMatrix.benchmark(..., save_directory_path...)会产出 GT/TP/FP/FN 四宫格拼图是与数值指标配合的最快排障手段。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考