Cleanlab 目标检测模块实战用 ObjectLab 方法检测目标检测数据集中的标注错误【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab本文基于 cleanlab 仓库中 object_detection 模块文档及其下属 rank / filter / summary 三个子模块的 API 文档并结合 filter.py、rank.py、summary.py 等源码实现展开。目标检测数据集的标注远比单标签分类复杂——每张图片包含多个物体每个物体都有自己的边界框和类别标签任何一个框漏标、类别标错或框的位置不准确都会污染训练数据。cleanlab 的object_detection模块正是为此设计它接收你的目标检测模型预测与原始标注自动识别存在标注错误的图片、为每张图片计算标签质量分数并提供数据探索与可视化工具。读完本文你将掌握find_label_issues、get_label_quality_scores、visualize等核心 API 的完整用法、输入数据格式要求以及 ObjectLab 评分算法在底层的工作机制。模块定位与文档脉络object_detection是 cleanlab 中专门面向目标检测Object Detection场景的数据质量子包其官方文档描述为Methods to detect label issues in object detection datasets检测目标检测数据集中的标注问题的方法。整个模块在 cleanlab/object_detection/init.py 中仅做三行导入由三个职责清晰的子模块组成子模块文档文件核心职责cleanlab.object_detection.rankrank.rst为每张图片计算标签质量分数0~1并按严重程度排序cleanlab.object_detection.filterfilter.rst识别哪些图片存在标签问题漏检 / 错类 / 框位不准cleanlab.object_detection.summarysummary.rst数据探索统计、类别分布与标注可视化三者的调用关系在源码中清晰可见filter.py 在判定问题时内部调用 rank.py 的compute_overlooked_box_scores、compute_badloc_box_scores、compute_swap_box_scores与get_label_quality_scores而 summary.py 又复用 filter 中的 TP/FP/FN 计算逻辑。理解这条链路就能理解整个模块的设计思想。核心概念目标检测中的三类标注错误与分类任务中标签是否为错的二元判断不同目标检测标注包含位置bounding box与类别class label两个维度。根据 rank.py 中get_label_quality_scores的文档说明标注者可能在三个方面犯错overlooked漏检图片中存在某个属于已知类别的物体但标注中没有对应的边界框。这是目标检测标注中最常见也最隐蔽的错误之一。swap类别错标边界框的位置正确但被标注成了错误的类别即该框的类别应换成另一个类。badloc位置不准确类别正确但边界框坐标不精确未能完整框住目标物体。模块会为每张图片分别评估这三类子分数subtype score再聚合成一个 0~1 的整体标签质量分数1 表示标签很可能正确clean0 表示标签很可能有误dirty。分数越低图片越可能被错误标注。输入数据格式labels 与 predictions所有核心 APIfind_label_issues、get_label_quality_scores、summary 系列函数都接受两个关键参数其格式在 filter.py 中有严格定义。labels原始标注假设数据集有N张图片、K个类别labels是一个长度为N的字典列表labels[i]对应第i张图片的标注格式为{ bboxes: np.ndarray((L, 4)), # L 个边界框坐标 labels: np.ndarray((L,)), # 每个框对应的类别 image_name: str # 可选用于后续定位具体图片 }其中L是第i张图片的标注框数量。每个边界框使用[x1, y1, x2, y2]格式(x1, y1)为框的左上角、(x2, y2)为右下角相对图像矩阵坐标与 Keras CV 的 XYXY 格式、Detectron2 一致。predictions模型预测predictions是长度为N的np.ndarray列表predictions[i]对应第i张图片的模型输出。对于每个类别k0, 1, ..., K-1predictions[i][k]是一个形状为(M, 5)的数组M是该类别下模型预测的框数量五个列依次为[x1, y1, x2, y2, pred_prob]pred_prob表示模型认为该框包含类别k物体的置信度。文档特别强调为了获得最准确的结果预测应当是样本外out-of-sample的例如通过交叉验证得到避免模型过拟合导致误判可参考仓库中的 pred_probs_cross_val.rst。输入校验机制在计算开始前object_detection_utils.py 中的assert_valid_inputs会做严格校验labels与predictions长度必须一致否则抛出ValueErrorlabels必须是字典列表每个预测框数组的第二维必须是 5 列[x1,y1,x2,y2,pred_prob]格式若传入threshold其值必须 ≤ 1评分方法目前仅支持objectlab。用 find_label_issues 找出有标注问题的图片filter.py 中find_label_issues是模块的门面 API只要一张图片中任意一个边界框被判定为标注有误该图片就会被标记为存在标签问题包括应标注却缺失的框、类别标错的框、位置不准的框。from cleanlab.object_detection.filter import find_label_issues # labels: List[Dict]predictions: List[np.ndarray]格式见上文 has_label_issue find_label_issues(labels, predictions)参数说明参数默认值含义labels必填原始标注含错误的可能predictions必填目标检测模型输出return_indices_ranked_by_scoreFalse为False时返回长度为N的布尔掩码True表示该图有标签问题为True时返回被标记图片的下标数组按最可能被错标的顺序排序overlapping_label_checkTrue为True时被多个不同类别标注的几乎重合框其 swap 分数会被惩罚若你不关心两个非常相似的框被标成了不同类别这种情况可设为False实际使用中先拿到布尔掩码做整体概览再通过return_indices_ranked_by_scoreTrue获取按严重程度排序的问题图片下标是常见的组合方式# 布尔掩码哪些图片有问题 mask find_label_issues(labels, predictions) # 问题图片下标按最可能错标优先排序 issue_idx find_label_issues(labels, predictions, return_indices_ranked_by_scoreTrue)从源码看filter.pyfind_label_issues的内部判定流程是计算每张图片三类子分数overlooked / badloc / swap基于每个类别的平均精度AP得到 per-class 阈值再乘以对应的阈值因子OVERLOOKED_THRESHOLD_FACTOR、BADLOC_THRESHOLD_FACTOR、SWAP_THRESHOLD_FACTOR三者默认均为 0.8见 constants.py凡分数 ≤ 阈值的框标记为问题框将 per-box 问题标记池化为 per-image 问题任一框有问题则该图有问题见_pool_box_scores_per_imagefilter.py三类问题做并集得到最终的图片级判定。值得注意的细节是问题框的判定阈值是类别自适应的。_get_per_class_apfilter.py在 IoU 从 0.5 到 0.95、步长 0.05 的 10 个阈值上计算每个类别的平均精度AP取均值后再乘以AP_SCALE_FACTOR默认 0.25见 constants.py作为该类的分数阈值基准。这意味着模型表现好的类别与表现差的类别会有不同的判定标准一定程度上实现了按类别自适应。用 get_label_quality_scores 给图片打质量分如果说find_label_issues给出的是是与否的判定那么 rank.py 的get_label_quality_scores给出的是有多严重的连续分数。from cleanlab.object_detection.rank import get_label_quality_scores label_quality_scores get_label_quality_scores(labels, predictions) # 返回形状为 (N,) 的数组取值 0~1分数语义1 表示标签干净很可能正确0 表示标签脏很可能有误。返回数组按输入顺序与图片一一对应。核心参数参数默认值含义labels必填原始标注predictions必填模型预测verboseTrue设为False可抑制所有打印信息aggregation_weights见下文指定三类子分数在聚合为整体分数时的权重overlapping_label_checkTrue与find_label_issues同名参数语义一致aggregation_weights自定义三类错误的权重aggregation_weights是一个可选字典键为overlooked、swap、badloc值为非负且和为 1的权重。增大某一项的权重意味着更看重包含该类错误的图片。若不提供默认使用 constants.py 中的三等分权重{ overlooked: 1/3, # 漏检物体 swap: 1/3, # 类别标错 badloc: 1/3, # 框的位置不准 }自定义示例更关注漏检问题label_quality_scores get_label_quality_scores( labels, predictions, aggregation_weights{overlooked: 0.5, swap: 0.25, badloc: 0.25}, )如果传入的权重不合法存在负值或和不为 1object_detection_utils.py 中的assert_valid_aggregation_weights会抛出ValueError。用 issues_from_scores 把分数转成问题下标rank.py 还提供了issues_from_scores辅助函数把分数数组转换为问题图片下标按最严重到最轻微排序from cleanlab.object_detection.rank import issues_from_scores issue_indices issues_from_scores(label_quality_scores, threshold0.1)threshold默认0.1分数高于该阈值的图片不被视为有问题对应下标被省略若threshold 1.0会抛出ValueError分数本身最大为 1返回的下标按分数从小到大即问题从重到轻排序。底层原理相似度矩阵、softmin 池化与分数聚合了解 ObjectLab 方法的内部机制有助于你正确解释结果。核心逻辑集中在 rank.py 的后半部分。相似度矩阵IoU 与距离的加权融合所有子分数都建立在预测框与标注框的相似度之上。_get_valid_inputs_for_compute_scores_per_imagerank.py中定义了相似度矩阵的计算方式similarity_matrix iou_matrix * alpha (1 - alpha) * (1 - dist_matrix)其中iou_matrix是预测框与标注框两两之间的 IoU交并比由_get_iou计算rank.pydist_matrix基于两框中心点的欧氏距离经指数衰减得到_euc_disrank.py。alpha默认ALPHA 0.9constants.py即相似度以 IoU 为主、距离为辅。此外EUC_FACTOR 0.1constants.py控制距离衰减的速率。三类子分数的计算逻辑overlooked 分数compute_overlooked_box_scoresrank.py对每个高置信度预测框pred_prob ≥ HIGH_PROBABILITY_THRESHOLD 0.95计算其与同类标注框的最高相似度。若某类完全没有标注框则分数退化为min_possible_similarity * (1 - pred_prob)。分数越低越可能是被漏检的物体。badloc 分数compute_badloc_box_scoresrank.py对每个标注框寻找置信度高于LOW_PROBABILITY_THRESHOLD 0.5且与它有交集的预测框取最高相似度。若找不到符合条件的预测框分数为 1.0不认为有问题。swap 分数compute_swap_box_scoresrank.py对每个标注框寻找其他类别中置信度高于 0.95 且与它相似度最高的预测框分数取max(min_possible_similarity, 1 - 最高相似度)。若开启overlapping_label_check被多个类别标注的重叠框IoU ≥LABEL_OVERLAP_THRESHOLD 0.95会直接获得很低的分min_possible_similarity见_has_overlaprank.py。softmin 池化与最终聚合每个图片通常有多个框需要把 per-box 分数聚合成 per-image 分数这一步骤由pool_box_scores_per_imagerank.py完成对每个框分数数组执行softmin池化softmin1d实现于 object_detection_utils.py。temperature默认TEMPERATURE 0.1constants.py温度越低softmin 越接近取最小值最差框主导温度越高越接近均值池化。最终的整体标签质量分数在_get_subtype_label_quality_scoresrank.py中按如下公式聚合三类子分数scores exp( w_overlooked * log(TINY_VALUE overlooked_score) w_badloc * log(TINY_VALUE badloc_score) w_swap * log(TINY_VALUE swap_score) )即三类子分数在 log 空间按aggregation_weights加权求和后取指数回到 0~1 区间TINY_VALUE 1e-100constants.py仅用于数值裁剪防除零/取对数溢出。高级 API逐框分数的精细控制对于高级用户rank.py 还公开了三个直接计算逐框per-box子分数的函数它们返回长度为N的 numpy 数组列表函数返回语义每个元素对应compute_overlooked_box_scores每个预测框被漏检的可能性0~1越低越可能是漏检scores_overlooked[i]形状(M,)compute_badloc_box_scores每个标注框位置不准的可能性0~1scores_badloc[i]形状(L,)compute_swap_box_scores每个标注框类别被标错的可能性0~1scores_swap[i]形状(L,)这三个函数都支持alpha相似度中 IoU 与距离的权重、概率阈值high_probability_threshold/low_probability_threshold等可选项且都接受可选的auxiliary_inputs参数——这是一个包含pred_labels、pred_label_probs、pred_bboxes、lab_labels、lab_bboxes、similarity_matrix、min_possible_similarity等键的字典列表格式详见 rank.py。当需要同时计算多种子分数时预计算并复用auxiliary_inputs可以显著减少重复计算。min_possible_similarity表示整个数据集中标签与预测之间大于 0 的最小可能相似度作为分数下界参与多类运算。summary 子模块数据探索与可视化summary.py 提供数据集层面的统计与可视化工具帮助你理解数据整体状况、发现异常并直观审视问题图片。数据集统计函数功能object_counts_per_image(labels, predictions)返回每张图片的标注物体数量与预测物体数量两个(N,)列表可发现物体数量异常多/少的图片bounding_box_size_distribution(labels, predictions, class_namesNone, sortFalse)按类别统计标注框与预测框的尺寸分布可发现某类异常偏大/偏小的框class_label_distribution(labels, predictions, class_namesNone)返回标注与预测中各类别的频率字典归一化到 0~1可了解哪些类别稀有、哪些被模型过/欠预测get_sorted_bbox_count_idxs(labels, predictions)返回按框数量从多到少排序的下标, 数量列表get_average_per_class_confusion_matrix(labels, predictions, num_procs1, class_namesNone)在 IoU 0.5~0.95步长 0.05范围内平均的逐类混淆矩阵给出每个类的平均 TP/FP/FN 次数calculate_per_class_metrics(labels, predictions, num_procs1, class_namesNone)由平均混淆矩阵计算每个类别的平均 precision / recall / F1其中class_names参数用于把 one-hot 类别下标映射回原始类别名格式为{整数标签: 原始类别名}例如{0: cat, 1: dog}。统计函数均支持可选的auxiliary_inputs复用机制。可视化函数visualizesummary.py用于在单张图片上展示标注框与预测框from cleanlab.object_detection.summary import visualize visualize( image_path, # 图片路径或已加载的 np.ndarray / PIL.Image labellabels[i], # 单张图片的标注 predictionpredictions[i], # 单张图片的预测 class_namesclass_names, # 可选类别名映射用于图例 overlayFalse, # False: 左右并排对比True: 叠加显示 prediction_threshold0.5, # 可选低于该置信度的预测框不显示 save_path./example_image.png, # 可选保存图片 figsize(14, 10), # 可选画布大小 )视觉约定红色实线框为给定标注given label蓝色虚线框为模型预测predicted label。overlayTrue时二者叠加在一张图上overlayFalse时左右并排展示。save_path支持png、pdf、ps、eps、svg五种格式通过文件扩展名识别。绘制过程会把[x1,y1,x2,y2]坐标转换为 matplotlib 的[x, y, w, h]见bbox_xyxy_to_xywhobject_detection_utils.py。plot_class_size_distributions与plot_class_distribution则分别绘制各类别框尺寸分布的直方图与类别占比饼图class_to_show默认MAX_CLASS_TO_SHOW 10constants.py超出部分的类别会被截断。这两个绘图函数依赖 matplotlib若未安装会提示pip install matplotlib。完整实战示例综合以上 API一个典型的目标检测数据质量分析流程如下与仓库 object_detection.ipynb 教程的用法一致import numpy as np from cleanlab.object_detection.filter import find_label_issues from cleanlab.object_detection.rank import get_label_quality_scores, issues_from_scores from cleanlab.object_detection.summary import ( object_counts_per_image, class_label_distribution, visualize, ) # 假设已有 labels 与 predictions格式见输入数据格式一节 # labels [{bboxes: np.ndarray((L,4)), labels: np.ndarray((L,)), image_name: str}, ...] # predictions [np.array([class0_boxes, class1_boxes, ...]), ...] # 每类 (M,5) # 1) 找出有标注问题的图片布尔掩码 排序下标 has_label_issue find_label_issues(labels, predictions) issue_idx find_label_issues(labels, predictions, return_indices_ranked_by_scoreTrue) # 2) 计算每张图片的标签质量分数 scores get_label_quality_scores(labels, predictions) print(最低分图片下标:, np.argsort(scores)[:10]) # 3) 用阈值把分数转成问题下标 indices_below_threshold issues_from_scores(scores, threshold0.1) # 4) 数据探索每张图片的物体数量、类别分布 ann_counts, pred_counts object_counts_per_image(labels, predictions) ann_dist, pred_dist class_label_distribution(labels, predictions) # 5) 可视化被标记为有问题的图片左右对比标注与预测 class_names {0: cat, 1: dog} # 按你的数据集定义 for idx in issue_idx[:3]: visualize( image_path, # 该图片的文件路径 labellabels[idx], predictionpredictions[idx], class_namesclass_names, overlayFalse, )参数默认值速查表ObjectLab 方法涉及的全部关键常量集中定义在 constants.py 中汇总如下常量默认值作用ALPHA0.9相似度矩阵中 IoU 与距离的权重越高越看重 IoUEUC_FACTOR0.1欧氏距离衰减因子越大距离影响衰减越快LOW_PROBABILITY_THRESHOLD0.5计算 badloc 分数时考虑预测框的最低置信度HIGH_PROBABILITY_THRESHOLD0.95计算 overlooked / swap 分数时视为高置信度的阈值TEMPERATURE0.1softmin 池化温度越低越接近最小值池化LABEL_OVERLAP_THRESHOLD0.95判定两个框重叠且类别冲突的 IoU 阈值OVERLOOKED_THRESHOLD_FACTOR0.8find_label_issues中 overlooked 问题框的阈值缩放因子BADLOC_THRESHOLD_FACTOR0.8find_label_issues中 badloc 问题框的阈值缩放因子SWAP_THRESHOLD_FACTOR0.8find_label_issues中 swap 问题框的阈值缩放因子AP_SCALE_FACTOR0.25per-class AP 的缩放因子用于构造类别自适应阈值MAX_ALLOWED_BOX_PRUNE0.97预测框剪枝比例上限超过则警告CUSTOM_SCORE_WEIGHT_*1/3overlooked / swap / badloc 三类子分数的默认聚合权重MAX_CLASS_TO_SHOW10可视化时图例中最多展示的类别数这些常量大多可以通过各 API 的可选参数覆盖如alpha、temperature、high_probability_threshold等传入None时才会回落到上述默认值见_get_valid_subtype_score_paramsrank.py。使用注意事项样本外预测更可靠文档明确建议 predictions 通过交叉验证等途径获得样本外输出以降低过拟合带来的误判。置信度剪枝影响性能get_label_quality_scores内部会根据预测概率对低置信度框做剪枝_prune_by_thresholdrank.py。当剪枝比例超过MAX_ALLOWED_BOX_PRUNE 0.97时会发出警告提示降低阈值剪掉过多框会显著影响问题识别的效果。权重必须合法自定义aggregation_weights时须满足非负且和为 1否则抛ValueError。overlapping_label_check 的取舍开启后被多个类别标注的几乎重叠的框会被判定为 swap 问题。这在多数数据集上是合理的同一物体不应有两个不同的类别标签但如果你的标注习惯允许这种歧义框存在可以关闭。阈值默认值针对 0~1 分数issues_from_scores的threshold默认 0.1 且不能超过 1.0请结合你数据集的分数分布可用np.histogram(scores)观察调整。进一步阅读模块文档索引docs/source/cleanlab/object_detection/index.rstrank / filter / summary 三个子模块的 API 文档入口完整教程docs/source/tutorials/object_detection.ipynb包含从数据准备、问题发现到可视化的端到端演示源码实现cleanlab/object_detection/filter.py、cleanlab/object_detection/rank.py、cleanlab/object_detection/summary.py内部工具与常量cleanlab/internal/object_detection_utils.py、cleanlab/internal/constants.py测试用例tests/test_object_detection.py展示了各类输入生成方式与函数行为验证总而言之cleanlab 的object_detection模块把数据中心的 AI 方法论扩展到了目标检测领域通过模型预测与原始标注的交叉比对在框级别识别漏检、错类与定位不准三类错误再聚合为图片级别的质量分数。无论你是在训练前清洗数据集还是在模型迭代后审计标注质量这套 rank / filter / summary 三件套都能给出可量化、可追溯的结论。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cleanlab 目标检测模块实战：用 ObjectLab 方法检测目标检测数据集中的标注错误
Cleanlab 目标检测模块实战用 ObjectLab 方法检测目标检测数据集中的标注错误【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab本文基于 cleanlab 仓库中 object_detection 模块文档及其下属 rank / filter / summary 三个子模块的 API 文档并结合 filter.py、rank.py、summary.py 等源码实现展开。目标检测数据集的标注远比单标签分类复杂——每张图片包含多个物体每个物体都有自己的边界框和类别标签任何一个框漏标、类别标错或框的位置不准确都会污染训练数据。cleanlab 的object_detection模块正是为此设计它接收你的目标检测模型预测与原始标注自动识别存在标注错误的图片、为每张图片计算标签质量分数并提供数据探索与可视化工具。读完本文你将掌握find_label_issues、get_label_quality_scores、visualize等核心 API 的完整用法、输入数据格式要求以及 ObjectLab 评分算法在底层的工作机制。模块定位与文档脉络object_detection是 cleanlab 中专门面向目标检测Object Detection场景的数据质量子包其官方文档描述为Methods to detect label issues in object detection datasets检测目标检测数据集中的标注问题的方法。整个模块在 cleanlab/object_detection/init.py 中仅做三行导入由三个职责清晰的子模块组成子模块文档文件核心职责cleanlab.object_detection.rankrank.rst为每张图片计算标签质量分数0~1并按严重程度排序cleanlab.object_detection.filterfilter.rst识别哪些图片存在标签问题漏检 / 错类 / 框位不准cleanlab.object_detection.summarysummary.rst数据探索统计、类别分布与标注可视化三者的调用关系在源码中清晰可见filter.py 在判定问题时内部调用 rank.py 的compute_overlooked_box_scores、compute_badloc_box_scores、compute_swap_box_scores与get_label_quality_scores而 summary.py 又复用 filter 中的 TP/FP/FN 计算逻辑。理解这条链路就能理解整个模块的设计思想。核心概念目标检测中的三类标注错误与分类任务中标签是否为错的二元判断不同目标检测标注包含位置bounding box与类别class label两个维度。根据 rank.py 中get_label_quality_scores的文档说明标注者可能在三个方面犯错overlooked漏检图片中存在某个属于已知类别的物体但标注中没有对应的边界框。这是目标检测标注中最常见也最隐蔽的错误之一。swap类别错标边界框的位置正确但被标注成了错误的类别即该框的类别应换成另一个类。badloc位置不准确类别正确但边界框坐标不精确未能完整框住目标物体。模块会为每张图片分别评估这三类子分数subtype score再聚合成一个 0~1 的整体标签质量分数1 表示标签很可能正确clean0 表示标签很可能有误dirty。分数越低图片越可能被错误标注。输入数据格式labels 与 predictions所有核心 APIfind_label_issues、get_label_quality_scores、summary 系列函数都接受两个关键参数其格式在 filter.py 中有严格定义。labels原始标注假设数据集有N张图片、K个类别labels是一个长度为N的字典列表labels[i]对应第i张图片的标注格式为{ bboxes: np.ndarray((L, 4)), # L 个边界框坐标 labels: np.ndarray((L,)), # 每个框对应的类别 image_name: str # 可选用于后续定位具体图片 }其中L是第i张图片的标注框数量。每个边界框使用[x1, y1, x2, y2]格式(x1, y1)为框的左上角、(x2, y2)为右下角相对图像矩阵坐标与 Keras CV 的 XYXY 格式、Detectron2 一致。predictions模型预测predictions是长度为N的np.ndarray列表predictions[i]对应第i张图片的模型输出。对于每个类别k0, 1, ..., K-1predictions[i][k]是一个形状为(M, 5)的数组M是该类别下模型预测的框数量五个列依次为[x1, y1, x2, y2, pred_prob]pred_prob表示模型认为该框包含类别k物体的置信度。文档特别强调为了获得最准确的结果预测应当是样本外out-of-sample的例如通过交叉验证得到避免模型过拟合导致误判可参考仓库中的 pred_probs_cross_val.rst。输入校验机制在计算开始前object_detection_utils.py 中的assert_valid_inputs会做严格校验labels与predictions长度必须一致否则抛出ValueErrorlabels必须是字典列表每个预测框数组的第二维必须是 5 列[x1,y1,x2,y2,pred_prob]格式若传入threshold其值必须 ≤ 1评分方法目前仅支持objectlab。用 find_label_issues 找出有标注问题的图片filter.py 中find_label_issues是模块的门面 API只要一张图片中任意一个边界框被判定为标注有误该图片就会被标记为存在标签问题包括应标注却缺失的框、类别标错的框、位置不准的框。from cleanlab.object_detection.filter import find_label_issues # labels: List[Dict]predictions: List[np.ndarray]格式见上文 has_label_issue find_label_issues(labels, predictions)参数说明参数默认值含义labels必填原始标注含错误的可能predictions必填目标检测模型输出return_indices_ranked_by_scoreFalse为False时返回长度为N的布尔掩码True表示该图有标签问题为True时返回被标记图片的下标数组按最可能被错标的顺序排序overlapping_label_checkTrue为True时被多个不同类别标注的几乎重合框其 swap 分数会被惩罚若你不关心两个非常相似的框被标成了不同类别这种情况可设为False实际使用中先拿到布尔掩码做整体概览再通过return_indices_ranked_by_scoreTrue获取按严重程度排序的问题图片下标是常见的组合方式# 布尔掩码哪些图片有问题 mask find_label_issues(labels, predictions) # 问题图片下标按最可能错标优先排序 issue_idx find_label_issues(labels, predictions, return_indices_ranked_by_scoreTrue)从源码看filter.pyfind_label_issues的内部判定流程是计算每张图片三类子分数overlooked / badloc / swap基于每个类别的平均精度AP得到 per-class 阈值再乘以对应的阈值因子OVERLOOKED_THRESHOLD_FACTOR、BADLOC_THRESHOLD_FACTOR、SWAP_THRESHOLD_FACTOR三者默认均为 0.8见 constants.py凡分数 ≤ 阈值的框标记为问题框将 per-box 问题标记池化为 per-image 问题任一框有问题则该图有问题见_pool_box_scores_per_imagefilter.py三类问题做并集得到最终的图片级判定。值得注意的细节是问题框的判定阈值是类别自适应的。_get_per_class_apfilter.py在 IoU 从 0.5 到 0.95、步长 0.05 的 10 个阈值上计算每个类别的平均精度AP取均值后再乘以AP_SCALE_FACTOR默认 0.25见 constants.py作为该类的分数阈值基准。这意味着模型表现好的类别与表现差的类别会有不同的判定标准一定程度上实现了按类别自适应。用 get_label_quality_scores 给图片打质量分如果说find_label_issues给出的是是与否的判定那么 rank.py 的get_label_quality_scores给出的是有多严重的连续分数。from cleanlab.object_detection.rank import get_label_quality_scores label_quality_scores get_label_quality_scores(labels, predictions) # 返回形状为 (N,) 的数组取值 0~1分数语义1 表示标签干净很可能正确0 表示标签脏很可能有误。返回数组按输入顺序与图片一一对应。核心参数参数默认值含义labels必填原始标注predictions必填模型预测verboseTrue设为False可抑制所有打印信息aggregation_weights见下文指定三类子分数在聚合为整体分数时的权重overlapping_label_checkTrue与find_label_issues同名参数语义一致aggregation_weights自定义三类错误的权重aggregation_weights是一个可选字典键为overlooked、swap、badloc值为非负且和为 1的权重。增大某一项的权重意味着更看重包含该类错误的图片。若不提供默认使用 constants.py 中的三等分权重{ overlooked: 1/3, # 漏检物体 swap: 1/3, # 类别标错 badloc: 1/3, # 框的位置不准 }自定义示例更关注漏检问题label_quality_scores get_label_quality_scores( labels, predictions, aggregation_weights{overlooked: 0.5, swap: 0.25, badloc: 0.25}, )如果传入的权重不合法存在负值或和不为 1object_detection_utils.py 中的assert_valid_aggregation_weights会抛出ValueError。用 issues_from_scores 把分数转成问题下标rank.py 还提供了issues_from_scores辅助函数把分数数组转换为问题图片下标按最严重到最轻微排序from cleanlab.object_detection.rank import issues_from_scores issue_indices issues_from_scores(label_quality_scores, threshold0.1)threshold默认0.1分数高于该阈值的图片不被视为有问题对应下标被省略若threshold 1.0会抛出ValueError分数本身最大为 1返回的下标按分数从小到大即问题从重到轻排序。底层原理相似度矩阵、softmin 池化与分数聚合了解 ObjectLab 方法的内部机制有助于你正确解释结果。核心逻辑集中在 rank.py 的后半部分。相似度矩阵IoU 与距离的加权融合所有子分数都建立在预测框与标注框的相似度之上。_get_valid_inputs_for_compute_scores_per_imagerank.py中定义了相似度矩阵的计算方式similarity_matrix iou_matrix * alpha (1 - alpha) * (1 - dist_matrix)其中iou_matrix是预测框与标注框两两之间的 IoU交并比由_get_iou计算rank.pydist_matrix基于两框中心点的欧氏距离经指数衰减得到_euc_disrank.py。alpha默认ALPHA 0.9constants.py即相似度以 IoU 为主、距离为辅。此外EUC_FACTOR 0.1constants.py控制距离衰减的速率。三类子分数的计算逻辑overlooked 分数compute_overlooked_box_scoresrank.py对每个高置信度预测框pred_prob ≥ HIGH_PROBABILITY_THRESHOLD 0.95计算其与同类标注框的最高相似度。若某类完全没有标注框则分数退化为min_possible_similarity * (1 - pred_prob)。分数越低越可能是被漏检的物体。badloc 分数compute_badloc_box_scoresrank.py对每个标注框寻找置信度高于LOW_PROBABILITY_THRESHOLD 0.5且与它有交集的预测框取最高相似度。若找不到符合条件的预测框分数为 1.0不认为有问题。swap 分数compute_swap_box_scoresrank.py对每个标注框寻找其他类别中置信度高于 0.95 且与它相似度最高的预测框分数取max(min_possible_similarity, 1 - 最高相似度)。若开启overlapping_label_check被多个类别标注的重叠框IoU ≥LABEL_OVERLAP_THRESHOLD 0.95会直接获得很低的分min_possible_similarity见_has_overlaprank.py。softmin 池化与最终聚合每个图片通常有多个框需要把 per-box 分数聚合成 per-image 分数这一步骤由pool_box_scores_per_imagerank.py完成对每个框分数数组执行softmin池化softmin1d实现于 object_detection_utils.py。temperature默认TEMPERATURE 0.1constants.py温度越低softmin 越接近取最小值最差框主导温度越高越接近均值池化。最终的整体标签质量分数在_get_subtype_label_quality_scoresrank.py中按如下公式聚合三类子分数scores exp( w_overlooked * log(TINY_VALUE overlooked_score) w_badloc * log(TINY_VALUE badloc_score) w_swap * log(TINY_VALUE swap_score) )即三类子分数在 log 空间按aggregation_weights加权求和后取指数回到 0~1 区间TINY_VALUE 1e-100constants.py仅用于数值裁剪防除零/取对数溢出。高级 API逐框分数的精细控制对于高级用户rank.py 还公开了三个直接计算逐框per-box子分数的函数它们返回长度为N的 numpy 数组列表函数返回语义每个元素对应compute_overlooked_box_scores每个预测框被漏检的可能性0~1越低越可能是漏检scores_overlooked[i]形状(M,)compute_badloc_box_scores每个标注框位置不准的可能性0~1scores_badloc[i]形状(L,)compute_swap_box_scores每个标注框类别被标错的可能性0~1scores_swap[i]形状(L,)这三个函数都支持alpha相似度中 IoU 与距离的权重、概率阈值high_probability_threshold/low_probability_threshold等可选项且都接受可选的auxiliary_inputs参数——这是一个包含pred_labels、pred_label_probs、pred_bboxes、lab_labels、lab_bboxes、similarity_matrix、min_possible_similarity等键的字典列表格式详见 rank.py。当需要同时计算多种子分数时预计算并复用auxiliary_inputs可以显著减少重复计算。min_possible_similarity表示整个数据集中标签与预测之间大于 0 的最小可能相似度作为分数下界参与多类运算。summary 子模块数据探索与可视化summary.py 提供数据集层面的统计与可视化工具帮助你理解数据整体状况、发现异常并直观审视问题图片。数据集统计函数功能object_counts_per_image(labels, predictions)返回每张图片的标注物体数量与预测物体数量两个(N,)列表可发现物体数量异常多/少的图片bounding_box_size_distribution(labels, predictions, class_namesNone, sortFalse)按类别统计标注框与预测框的尺寸分布可发现某类异常偏大/偏小的框class_label_distribution(labels, predictions, class_namesNone)返回标注与预测中各类别的频率字典归一化到 0~1可了解哪些类别稀有、哪些被模型过/欠预测get_sorted_bbox_count_idxs(labels, predictions)返回按框数量从多到少排序的下标, 数量列表get_average_per_class_confusion_matrix(labels, predictions, num_procs1, class_namesNone)在 IoU 0.5~0.95步长 0.05范围内平均的逐类混淆矩阵给出每个类的平均 TP/FP/FN 次数calculate_per_class_metrics(labels, predictions, num_procs1, class_namesNone)由平均混淆矩阵计算每个类别的平均 precision / recall / F1其中class_names参数用于把 one-hot 类别下标映射回原始类别名格式为{整数标签: 原始类别名}例如{0: cat, 1: dog}。统计函数均支持可选的auxiliary_inputs复用机制。可视化函数visualizesummary.py用于在单张图片上展示标注框与预测框from cleanlab.object_detection.summary import visualize visualize( image_path, # 图片路径或已加载的 np.ndarray / PIL.Image labellabels[i], # 单张图片的标注 predictionpredictions[i], # 单张图片的预测 class_namesclass_names, # 可选类别名映射用于图例 overlayFalse, # False: 左右并排对比True: 叠加显示 prediction_threshold0.5, # 可选低于该置信度的预测框不显示 save_path./example_image.png, # 可选保存图片 figsize(14, 10), # 可选画布大小 )视觉约定红色实线框为给定标注given label蓝色虚线框为模型预测predicted label。overlayTrue时二者叠加在一张图上overlayFalse时左右并排展示。save_path支持png、pdf、ps、eps、svg五种格式通过文件扩展名识别。绘制过程会把[x1,y1,x2,y2]坐标转换为 matplotlib 的[x, y, w, h]见bbox_xyxy_to_xywhobject_detection_utils.py。plot_class_size_distributions与plot_class_distribution则分别绘制各类别框尺寸分布的直方图与类别占比饼图class_to_show默认MAX_CLASS_TO_SHOW 10constants.py超出部分的类别会被截断。这两个绘图函数依赖 matplotlib若未安装会提示pip install matplotlib。完整实战示例综合以上 API一个典型的目标检测数据质量分析流程如下与仓库 object_detection.ipynb 教程的用法一致import numpy as np from cleanlab.object_detection.filter import find_label_issues from cleanlab.object_detection.rank import get_label_quality_scores, issues_from_scores from cleanlab.object_detection.summary import ( object_counts_per_image, class_label_distribution, visualize, ) # 假设已有 labels 与 predictions格式见输入数据格式一节 # labels [{bboxes: np.ndarray((L,4)), labels: np.ndarray((L,)), image_name: str}, ...] # predictions [np.array([class0_boxes, class1_boxes, ...]), ...] # 每类 (M,5) # 1) 找出有标注问题的图片布尔掩码 排序下标 has_label_issue find_label_issues(labels, predictions) issue_idx find_label_issues(labels, predictions, return_indices_ranked_by_scoreTrue) # 2) 计算每张图片的标签质量分数 scores get_label_quality_scores(labels, predictions) print(最低分图片下标:, np.argsort(scores)[:10]) # 3) 用阈值把分数转成问题下标 indices_below_threshold issues_from_scores(scores, threshold0.1) # 4) 数据探索每张图片的物体数量、类别分布 ann_counts, pred_counts object_counts_per_image(labels, predictions) ann_dist, pred_dist class_label_distribution(labels, predictions) # 5) 可视化被标记为有问题的图片左右对比标注与预测 class_names {0: cat, 1: dog} # 按你的数据集定义 for idx in issue_idx[:3]: visualize( image_path, # 该图片的文件路径 labellabels[idx], predictionpredictions[idx], class_namesclass_names, overlayFalse, )参数默认值速查表ObjectLab 方法涉及的全部关键常量集中定义在 constants.py 中汇总如下常量默认值作用ALPHA0.9相似度矩阵中 IoU 与距离的权重越高越看重 IoUEUC_FACTOR0.1欧氏距离衰减因子越大距离影响衰减越快LOW_PROBABILITY_THRESHOLD0.5计算 badloc 分数时考虑预测框的最低置信度HIGH_PROBABILITY_THRESHOLD0.95计算 overlooked / swap 分数时视为高置信度的阈值TEMPERATURE0.1softmin 池化温度越低越接近最小值池化LABEL_OVERLAP_THRESHOLD0.95判定两个框重叠且类别冲突的 IoU 阈值OVERLOOKED_THRESHOLD_FACTOR0.8find_label_issues中 overlooked 问题框的阈值缩放因子BADLOC_THRESHOLD_FACTOR0.8find_label_issues中 badloc 问题框的阈值缩放因子SWAP_THRESHOLD_FACTOR0.8find_label_issues中 swap 问题框的阈值缩放因子AP_SCALE_FACTOR0.25per-class AP 的缩放因子用于构造类别自适应阈值MAX_ALLOWED_BOX_PRUNE0.97预测框剪枝比例上限超过则警告CUSTOM_SCORE_WEIGHT_*1/3overlooked / swap / badloc 三类子分数的默认聚合权重MAX_CLASS_TO_SHOW10可视化时图例中最多展示的类别数这些常量大多可以通过各 API 的可选参数覆盖如alpha、temperature、high_probability_threshold等传入None时才会回落到上述默认值见_get_valid_subtype_score_paramsrank.py。使用注意事项样本外预测更可靠文档明确建议 predictions 通过交叉验证等途径获得样本外输出以降低过拟合带来的误判。置信度剪枝影响性能get_label_quality_scores内部会根据预测概率对低置信度框做剪枝_prune_by_thresholdrank.py。当剪枝比例超过MAX_ALLOWED_BOX_PRUNE 0.97时会发出警告提示降低阈值剪掉过多框会显著影响问题识别的效果。权重必须合法自定义aggregation_weights时须满足非负且和为 1否则抛ValueError。overlapping_label_check 的取舍开启后被多个类别标注的几乎重叠的框会被判定为 swap 问题。这在多数数据集上是合理的同一物体不应有两个不同的类别标签但如果你的标注习惯允许这种歧义框存在可以关闭。阈值默认值针对 0~1 分数issues_from_scores的threshold默认 0.1 且不能超过 1.0请结合你数据集的分数分布可用np.histogram(scores)观察调整。进一步阅读模块文档索引docs/source/cleanlab/object_detection/index.rstrank / filter / summary 三个子模块的 API 文档入口完整教程docs/source/tutorials/object_detection.ipynb包含从数据准备、问题发现到可视化的端到端演示源码实现cleanlab/object_detection/filter.py、cleanlab/object_detection/rank.py、cleanlab/object_detection/summary.py内部工具与常量cleanlab/internal/object_detection_utils.py、cleanlab/internal/constants.py测试用例tests/test_object_detection.py展示了各类输入生成方式与函数行为验证总而言之cleanlab 的object_detection模块把数据中心的 AI 方法论扩展到了目标检测领域通过模型预测与原始标注的交叉比对在框级别识别漏检、错类与定位不准三类错误再聚合为图片级别的质量分数。无论你是在训练前清洗数据集还是在模型迭代后审计标注质量这套 rank / filter / summary 三件套都能给出可量化、可追溯的结论。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考