cleanlab Datalab 完整指南一站式数据与标签质量问题审计 API【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab导读Datalab是 cleanlab 库中面向数据质量审计的统一入口通过一个对象即可自动检测真实世界数据中的各类标签错误与数据问题标签错误、异常点、近似重复、非独立同分布、类不平衡、欠表现分组、空值、数据估值等。本文将围绕 datalab.py 中Datalab类的完整 API构造参数、find_issues、report、get_issues、issue_summary、save/load等展开并结合仓库源码说明底层实现原理与参数细节。读完本文你将掌握如何用几行代码对分类、回归、多标签及图像数据集发起一次完整的数据质量审计并能按需定制审计的问题类型与输出深度。一、Datalab 是什么统一审计入口的设计思想在 cleanlab 库中针对具体目标如仅查找标签问题、仅清洗标签可以使用cleanlab.classification、cleanlab.filter、cleanlab.rank等模块中的专门方法而Datalab则被官方文档明确推荐为如果你想审计数据质量并检测其中问题的首选接口见 datalab.py 类注释。Datalab的核心设计特点是单一对象、多类问题并行审计一次调用即可检查标签错误、异常点、近似重复、非 IID、类不平衡、欠表现分组、空值、数据估值等常见问题中间状态复用Datalab会跟踪某些 cleanlab 函数产生的中间状态例如 KNN 图等数据统计并在其他函数之间复用从而提升效率与模型解耦审计过程只通过模型的预测概率、特征向量或预计算的 KNN 图与模型交互可以配合任何你已经训练好的模型使用可扩展通过注册机制支持自定义问题类型见下文扩展机制。从源码看Datalab的构造过程实际上完成了一系列内部组件的装配datalab.py__init__Task任务类型枚举 └─ Data数据封装、校验、标签格式化 ├─ labels标签对象分类任务映射为 0..K-1 整数 └─ _imagelab可选图像数据集专用来自 CleanVision 适配层 └─ _DataIssuesBuilder → data_issuesDataIssues 结果容器其中Task枚举定义在 task.pyData负责把各种格式的数据统一转为 Hugging Facedatasets.Dataset并格式化标签data.py。二、构造 Datalab支持的参数与数据格式2.1 完整构造签名Datalab( data, # 必填 taskclassification, # classification | regression | multilabel label_nameNone, # 标签列名 image_keyNone, # 图像字段可选 verbosity1, # 0~4 的整数默认 1 )对应源码位于 datalab.py__init__。2.2 data五种受支持的输入格式data接受所有能被转换为 Hugging FaceDataset对象的类数据集对象完整支持列表见 data.pyData._load_data格式说明datasets.DatasetHugging Face 数据集对象直接使用pandas.DataFrame通过Dataset.from_pandas转换dict键为字符串值为等长数组/列表list由具有相同键的字典组成的列表str本地文件路径.txt/.csv/.json或 Hugging Face Hub 上的数据集标识符构造时Data还会做格式校验不支持的输入类型会抛出DataFormatError如果传入的是DatasetDict即包含多个 split 的数据集会抛出DatasetDictError提示应显式指定split例如datasets.load_dataset(dataset, splittrain)。注意两点使用约束分类任务下标签会被映射为[0, 1, ..., K-1]的整数多标签任务下标签被格式化为列表的列表如[[0, 1], [1, 2]]回归任务下标签保持连续数值使用Datalab需要datasets包它属于 cleanlab 的可选依赖可通过pip install cleanlab[all]一并安装。2.3 task三类受支持的任务Task枚举task.py目前支持三种任务取值含义标签处理classification默认多分类映射为整数regression回归连续值预测保持连续值multilabel多标签分类列表的列表传入非法任务字符串会抛出ValueError。2.4 image_key 与图像特定问题image_key用于图像数据集指向存放实际图片PIL 对象的字段。指定后Datalab会通过create_imagelabimagelab.py调用 CleanVision 包额外审计图像特有的问题类型。默认启用的图像问题类型定义在 constants.pyDEFAULT_CLEANVISION_ISSUESdark过暗light过亮low_information信息量低默认阈值 0.15odd_aspect_ratio宽高比异常odd_size尺寸异常grayscale灰度图blurry模糊限制image_key目前仅支持以 Hugging Facedatasets.Dataset对象形式传入的数据。2.5 verbosity输出详细程度verbosity取值为 0 到 4 的整数值越高审计时Datalab打印的信息越多默认 1。它同时影响find_issues的过程输出与report的默认详细程度report也可单独覆盖。三、发起审计find_issues 的四个可选输入find_issues是Datalab的核心方法签名如下datalab.pydatalab.find_issues( *, pred_probsNone, # 模型预测概率 featuresNone, # 特征向量/嵌入 knn_graphNone, # 预计算的 KNN 稀疏矩阵 issue_typesNone, # 自定义问题类型与参数 )重要说明审计结果保存在datalab.issues属性中find_issues本身不返回任何值issue_types与knn_graph等参数均为关键字参数keyword-only。3.1 输入与可检测问题类型的对应关系find_issues与模型之间只通过预测概率 / 嵌入 / 由它们衍生的 KNN 图交互。提供的输入越多能检测的问题类型越多如果只提供部分输入Datalab会基于有限信息输出它能得到的结论。各输入与问题类型的对应关系见 issue_finder.py_CLASSIFICATION_ARGS_DICT输入主要服务的问题类型pred_probslabel标签错误、outlier、non_iid、underperforming_groupfeaturesoutlier、near_duplicate、non_iid、data_valuation、null、label当没有 pred_probs 时用于拟合 KNN 模型生成预测knn_graphoutlier、near_duplicate、non_iid、data_valuation、underperforming_group无仅class_imbalance类不平衡检测不需要任何模型输入优先级规则源码 issue_finder.py 已明示同时提供knn_graph与features时knn_graph优先大多数问题管理器会优先使用 KNN 图以提高效率同时会打印警告只提供features时内部会基于欧氏或余弦距离构建knn_graph两者都不提供时near_duplicate近似重复等问题将不会被检测提供cluster_ids与knn_graph/features同时时cluster_ids优先于自动聚类。3.2 pred_probs三种任务的形状要求任务形状要求分类二维数组(num_examples, K)K为类别数列顺序必须与类别排序一致Datalab 采用按类别名词典序排列回归一维数组(num_examples,)每行是该样本的预测值多标签二维数组(num_examples, K)列顺序同样按类别名词典序要最准确地检测标签问题应提供你能训练出的最准确模型的样本外out-of-sample预测概率例如通过交叉验证产生。3.3 features特征嵌入的要求features是每个样本的特征向量表示必须是二维数组(num_examples, num_features)。它可以是来自预训练模型的嵌入也可以是对原始特征做数值化变换的结果。3.4 knn_graph预计算 KNN 图CSR 稀疏矩阵knn_graph是样本间距离的 K 近邻图必须以scipy 的 CSR 稀疏矩阵形式传入要求方阵形状(num_examples, num_examples)非零项总数约k * num_examplesk为每个样本的邻居数且均匀分布在各行每个非零项是两个样本间的距离对角线必须全零自距离省略邻居不含自身每行内的距离需按升序排列data数组的对应分段内indices保持同步重复样本距离为 0应存储显式零knn_graph[i, j] 0对于距离为 0 的重复样本对必须显式存零。CSR 格式的三个一维数组含义如下data按行存放矩阵全部非零元素每行内部已排序indices每个非零元素对应的列索引与data一一对应indptr每行非零元素在data中的起止下标第i行的元素位于data[indptr[i]]到data[indptr[i1]]。文档中的示例knn_graph.todense() # matrix([[0. , 0.3, 0.2], # [0.3, 0. , 0.4], # [0.2, 0.4, 0. ]]) knn_graph.data # array([0.2, 0.3, 0.3, 0.4, 0.2, 0.4]) # 第一行的升序距离为 0.2、0.3第二行为 0.3、0.4依此类推。 knn_graph.indices # array([2, 1, 0, 2, 0, 1]) # 与 data 中距离对应的邻居列索引。 knn_graph.indptr # array([0, 2, 4, 6]) # 第一行非零项存于 data[0]~data[2]第二行存于 data[2]~data[4]依此类推。这类矩阵可以直接由sklearn.neighbors.NearestNeighbors.kneighbors_graph(modedistance)生成。注意请直接传入稀疏矩阵本身不要传knn_graph.toarray()转换后的稠密矩阵。3.5 issue_types定制审计内容issue_types是一个字典的字典键是感兴趣的问题类型值是对应IssueManager构造参数组成的字典。不传则使用默认问题类型集合与推荐参数。最简单的定制——只审计标签问题issue_types {label: {}} lab.find_issues(pred_probspred_probs, issue_typesissue_types)进阶定制——向LabelIssueManager构造器传参例如指定CleanLearning的prune_methodissue_types { label: { clean_learning_kwargs: { prune_method: prune_by_noise_rate, }, }, } lab.find_issues(pred_probspred_probs, issue_typesissue_types)边界行为如果传入空的issue_types{}find_issues会打印警告未指定问题类型因此不会在数据集中找到任何问题并直接返回datalab.py。3.6 三个可直接运行的完整示例方式一只传 pred_probsfrom sklearn.linear_model import LogisticRegression import numpy as np from cleanlab import Datalab X np.array([[0, 1], [1, 1], [2, 2], [2, 0]]) y np.array([0, 1, 1, 0]) clf LogisticRegression(random_state0).fit(X, y) pred_probs clf.predict_proba(X) lab Datalab(data{X: X, y: y}, label_namey) lab.find_issues(pred_probspred_probs)方式二只传 featuresfrom sklearn.linear_model import LogisticRegression import numpy as np from cleanlab import Datalab X np.array([[0, 1], [1, 1], [2, 2], [2, 0]]) y np.array([0, 1, 1, 0]) lab Datalab(data{X: X, y: y}, label_namey) lab.find_issues(featuresX)方式三传预计算 knn_graphfrom sklearn.neighbors import NearestNeighbors import numpy as np from cleanlab import Datalab X np.array([[0, 1], [1, 1], [2, 2], [2, 0]]) y np.array([0, 1, 1, 0]) nbrs NearestNeighbors(n_neighbors2, metriceuclidean).fit(X) knn_graph nbrs.kneighbors_graph(modedistance) lab Datalab(data{X: X, y: y}, label_namey) lab.find_issues(knn_graphknn_graph)官方文档建议同时传pred_probs和features可以获得更全面的审计结果。3.7 find_issues 的底层执行流程从源码看find_issues最终委托给IssueFinderissue_finder.pyIssueFinder.find_issues其执行链路为根据传入输入解析每个问题类型所需的参数_resolve_required_args_for_*系列函数通过_IssueManagerFactory.from_list从注册表REGISTRY实例化对应的问题管理器逐个运行IssueManager.find_issues(**arg_dict)并将结果收集进DataIssuescollect_statisticscollect_issues_from_issue_manager单个问题管理器失败不会中断整体审计而是被记录并最终打印Failed to check for these issue types最后调用set_health_score()计算数据集整体健康分当前实现为各类问题 score 的均值见 data_issues.py。此外当数据集没有标签时label_name未提供label、class_imbalance等问题类型会被自动跳过并给出警告issue_finder.pyget_available_issue_types。四、默认审计的问题类型与任务相关注册表当issue_types未指定时Datalab使用各任务的默认问题类型集合issue_manager_factory.pylist_default_issue_types任务默认审计的问题类型分类null、label、outlier、near_duplicate、non_iid、class_imbalance、underperforming_group回归null、label、outlier、near_duplicate、non_iid多标签null、label、outlier、near_duplicate、non_iid而完整的可能问题类型注册表REGISTRY即list_possible_issue_types()返回的内容见 issue_manager_factory.py为任务全部已注册问题类型分类outlier、label、near_duplicate、non_iid、class_imbalance、underperforming_group、data_valuation、null回归label、outlier、near_duplicate、non_iid、data_valuation、null多标签label、outlier、near_duplicate、non_iid、data_valuation、null对于图像数据集指定了image_keylist_possible_issue_types()与list_default_issue_types()都会追加DEFAULT_CLEANVISION_ISSUES中的图像问题类型datalab.py。注意data_valuation数据估值属于可能但不在默认审计集合中的问题类型需要显式传入issue_types才会运行。4.1 每种问题类型的三种输出估计对每种问题类型以ISSUE_NAME代称Datalab会产出三类估计逐样本质量分ISSUE_NAME_score0~1 的数值越接近 0 表示该样本越严重地表现出此问题通过datalab.issues属性或datalab.get_issues(ISSUE_NAME)访问逐样本布尔标记is_ISSUE_NAME_issueTrue表示估计该样本存在此问题数据集整体分0~1量化该问题在整个数据集上的严重程度分数越高表示整体越健康通过datalab.issue_summary属性或datalab.get_issue_summary(ISSUE_NAME)访问。以outlier为例issue_name outlier # 代码中的引用名 issue_score outlier_score # 质量分列名越典型的异常点分数越低 is_issue is_outlier_issue # 布尔标记列名横向可比性提醒同一种问题类型的分数可以在不同样本、不同数据集之间比较但不同类型问题之间的分数不可互相比较例如标签质量用标签似然估计而异常点质量用特征空间 KNN 距离估计两者本质不可比。某些问题类型如non_iid的整体分并非逐样本分数的均值而是数据集的全局统计量如数据为 IID 这一假设检验的 p 值。数据集级 vs 样本级问题non_iid、class_imbalance、underperforming_group属于主要关乎整个数据集的问题应优先通过get_issue_summary的全局分来考察而label、outlier、near_duplicate、null属于主要关乎单个样本的问题可放心用get_issues逐样本查看。4.2 每种问题类型所需的模型输入不同问题类型的检测依赖不同的输入可从 issue_finder.py 参数表 归纳问题类型需要的输入label分类pred_probs或features回归features 预测值多标签pred_probsoutlier分类pred_probs/features/knn_graph之一其余任务features/knn_graphnear_duplicatefeatures或knn_graphnon_iid分类pred_probs/features/knn_graph其余任务features/knn_graphunderperforming_grouppred_probsfeatures/knn_graph/cluster_ids三者之一data_valuationfeatures或knn_graphclass_imbalance无仅需标签nullfeaturesIssueFinder会自动剔除输入不足的问题类型因此你可以放心只提供部分输入。五、查看审计结果属性与查询方法5.1 属性速查表属性类型内容datalab.issuespd.DataFrame逐样本问题标记与质量分datalab.issue_summarypd.DataFrame各问题类型整体汇总列issue_type、score、num_issuesdatalab.infodict每个问题类型的详细信息与统计含statistics键存放样本数、类别数、健康分等datalab.labelsnp.ndarray/List[List[int]]标签[0, ..., K-1]格式datalab.has_labelsbool是否有标签且为整数格式datalab.class_namesList[str]类别名列表无标签时为空列表datalab.dataDataset内部的 Hugging Face Datasetdatalab.cleanlab_versionstr创建该对象的 cleanlab 版本issue_summary示例 datalab.issue_summary issue_type score outlier 0.123 label 0.456info示例同时检测了 label 与 outlier datalab.info { label: { given_labels: [0, 1, 0, 1, 1, 1, 1, 1, 0, 1, ...], predicted_label: [0, 0, 0, 1, 0, 1, 0, 1, 0, 1, ...], ..., }, outlier: { nearest_neighbor: [3, 7, 1, 2, 8, 4, 5, 9, 6, 0, ...], distance_to_nearest_neighbor: [0.123, 0.789, 0.456, ...], ..., }, }5.2 查询方法方法说明get_issues(issue_nameNone)返回逐样本问题 DataFrame。issue_nameNone时返回全部类型指定时只返回该类型相关列label会附带given_label/predicted_label列near_duplicate会附带near_duplicate_sets/distance_to_nearest_neighbor列。非法名称抛出ValueErrorget_issue_summary(issue_nameNone)返回问题汇总 DataFrameNone时返回全部get_info(issue_nameNone)返回指定问题类型的详细信息字典未计算时抛出ValueErrorlist_possible_issue_types()返回所有已注册、可在find_issues中使用的问题类型list_default_issue_types()返回不指定issue_types时默认运行的问题类型get_issues的实现位于 data_issues.pyDataIssues.get_issues当issues为空未执行find_issues时会给出详细提示的ValueError。数据统计样本数、类别名、类别数、健康分则通过get_info(statistics)或DataIssues.statistics属性获取data_issues.pyget_data_statistics。六、生成可读报告report 方法datalab.report( *, num_examples5, # 每种问题展示的 top 样本数 verbosityNone, # 覆盖构造时的 verbosity默认沿用 include_descriptionTrue, # 是否包含每种问题的文字描述 show_summary_scoreFalse, # 是否显示整体严重度分数列 show_all_issuesFalse, # 是否展示所有被检查过的问题类型含未检测到的 )各参数行为datalab.pyreportnum_examples报告对每种问题类型展示受害最严重的 top N 个样本verbosity更高等级会向报告中加入更多信息每种IssueManager各自定义各等级追加的内容例如LabelIssueManager在第 3 级会加入classes_by_label_quality与overlapping_classes见 label.pyinclude_description熟悉各类问题定义后可设为False以精简输出show_summary_score是否显示每种问题的整体严重度分。注意这些分数在不同问题类型之间不可比较show_all_issues设为True时报告会包含所有被检查过的问题类型包括在数据中未检测到的问题类型。报告实现位于 report.pyReporter.get_report先按num_issues降序输出汇总表再逐一调用各问题管理器的report类方法拼接各问题详情。报告头部会打印数据集信息num_examples、num_classes当数据中没有任何问题时会输出 No issues found in the data. Good job!并建议用show_summary_scoreTrue与show_all_issuesTrue重跑以查看完整信息report.py。七、持久化save 与 loadDatalab支持将审计结果保存到磁盘并在之后重新加载datalab.save(pathmy_datalab/, forceFalse) datalab_loaded Datalab.load(pathmy_datalab/, dataNone)要点datalab.py 与 serialize.py_Serializersave会在path目录下生成datalab.pkl对象本身、issues.csv、summary.csv以及data/子目录数据集副本forceFalse且目录已存在时抛出FileExistsError数据集本身不会被保存在Datalab内如需保留数据请自行另存load时若传入data会校验数据哈希与长度是否与保存时一致不一致则报错cleanlab 不保证旧版本保存的Datalab能被未来版本加载版本不一致时load会打印警告Things may be broken!。八、扩展机制自定义问题类型Datalab通过工厂 注册表机制支持自定义问题类型issue_manager_factory.pyregister。任何IssueManager子类都可以被注册进REGISTRY之后即可像内置问题类型一样在find_issues(issue_types{...})中使用。from cleanlab.datalab.internal.issue_manager.issue_manager import IssueManager from cleanlab.datalab.internal.issue_manager_factory import register register class MyIssueManager(IssueManager): issue_name: str my_issue def find_issues(self, **kwargs): # 实现具体的问题检测逻辑 pass或采用函数调用式注册register(MyIssueManager, taskclassification)IssueManager基类issue_manager.py要求每个问题管理器为每个样本计算0~1 的严重度分数越接近 0 越严重布尔is_issue标记可通过阈值化分数得到或像 Confident Learning 那样用其他方式判定数据集整体严重度如所有样本分数均值或is_issueTrue的样本数其他有用的info例如标签问题的confident_thresholds、confident_joint、预测标签近似重复问题的重复样本集合等。注意注册表与工厂属于内部实现细节文档明确警告不应被普通用户直接使用register装饰器注册同名问题类型时会打印覆盖警告。九、从源码与测试看典型用法仓库测试 test_datalab.py 覆盖了Datalab的典型生命周期构造非法DatasetDict校验、print/__repr__输出、class_names、list_default_issue_types、get_info、get_issue_summary、get_issues、带pred_probs的find_issues、空issue_types警告、自定义超参数、重复find_issues后report、save/load/pickle往返、失败问题管理器容错、knn_graph与features的优先级等。最小可用流程总结如下from cleanlab import Datalab # 1. 构造 lab Datalab(datadataset, label_namelabel, taskclassification) # 2. 审计pred_probs 需为样本外预测概率 lab.find_issues(pred_probspred_probs, featuresfeatures) # 3. 查看结果 lab.report() # 人类可读报告 lab.get_issues(label) # 标签问题逐样本详情 lab.get_issue_summary() # 各问题类型汇总 lab.info[statistics] # 数据集统计与健康分 # 4. 持久化可选 lab.save(pathaudit_result/)一个实用的惯例是先用lab.find_issues(featuresX)做一次无需训练模型的初步审计覆盖异常点、近似重复、非 IID、空值等再补充pred_probs进行完整审计覆盖标签错误、类不平衡、欠表现分组等。十、适用前提与注意事项可选依赖Datalab依赖datasets包图像审计还依赖cleanvision请通过pip install cleanlab[all]安装全部可选依赖pred_probs 列序分类与多标签任务的pred_probs列必须按类别名词典序排列否则标签审计结果会错位knn_graph 格式必须是符合 CSR 规范、对角线为零、行内升序的稀疏矩阵重复样本对须显式存零输入不足时的问题降级不提供pred_probs/features/knn_graph相应问题类型会自动被跳过这是设计行为而非错误分数可比性边界同类型问题的分数可跨样本/跨数据集比较不同类型之间不可比较持久化兼容性save的结果不保证被未来 cleanlab 版本加载。结语Datalab将 cleanlab 的数据中心 AI 能力收敛为一个对象、一次调用覆盖从构造、审计、查询、报告到持久化的完整数据质量工作流。结合 datalab.py 源码及其内部组件issue_finder.py、data_issues.py、issue_manager_factory.py、report.py你可以按需定制审计内容甚至注册自己的问题类型将数据质量审计变成可复用、可解释、可扩展的标准流程。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 22:22:58 · 阅读 1.2k cleanlab Datalab 完整指南：一站式数据与标签质量问题审计 API
cleanlab Datalab 完整指南一站式数据与标签质量问题审计 API【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab导读Datalab是 cleanlab 库中面向数据质量审计的统一入口通过一个对象即可自动检测真实世界数据中的各类标签错误与数据问题标签错误、异常点、近似重复、非独立同分布、类不平衡、欠表现分组、空值、数据估值等。本文将围绕 datalab.py 中Datalab类的完整 API构造参数、find_issues、report、get_issues、issue_summary、save/load等展开并结合仓库源码说明底层实现原理与参数细节。读完本文你将掌握如何用几行代码对分类、回归、多标签及图像数据集发起一次完整的数据质量审计并能按需定制审计的问题类型与输出深度。一、Datalab 是什么统一审计入口的设计思想在 cleanlab 库中针对具体目标如仅查找标签问题、仅清洗标签可以使用cleanlab.classification、cleanlab.filter、cleanlab.rank等模块中的专门方法而Datalab则被官方文档明确推荐为如果你想审计数据质量并检测其中问题的首选接口见 datalab.py 类注释。Datalab的核心设计特点是单一对象、多类问题并行审计一次调用即可检查标签错误、异常点、近似重复、非 IID、类不平衡、欠表现分组、空值、数据估值等常见问题中间状态复用Datalab会跟踪某些 cleanlab 函数产生的中间状态例如 KNN 图等数据统计并在其他函数之间复用从而提升效率与模型解耦审计过程只通过模型的预测概率、特征向量或预计算的 KNN 图与模型交互可以配合任何你已经训练好的模型使用可扩展通过注册机制支持自定义问题类型见下文扩展机制。从源码看Datalab的构造过程实际上完成了一系列内部组件的装配datalab.py__init__Task任务类型枚举 └─ Data数据封装、校验、标签格式化 ├─ labels标签对象分类任务映射为 0..K-1 整数 └─ _imagelab可选图像数据集专用来自 CleanVision 适配层 └─ _DataIssuesBuilder → data_issuesDataIssues 结果容器其中Task枚举定义在 task.pyData负责把各种格式的数据统一转为 Hugging Facedatasets.Dataset并格式化标签data.py。二、构造 Datalab支持的参数与数据格式2.1 完整构造签名Datalab( data, # 必填 taskclassification, # classification | regression | multilabel label_nameNone, # 标签列名 image_keyNone, # 图像字段可选 verbosity1, # 0~4 的整数默认 1 )对应源码位于 datalab.py__init__。2.2 data五种受支持的输入格式data接受所有能被转换为 Hugging FaceDataset对象的类数据集对象完整支持列表见 data.pyData._load_data格式说明datasets.DatasetHugging Face 数据集对象直接使用pandas.DataFrame通过Dataset.from_pandas转换dict键为字符串值为等长数组/列表list由具有相同键的字典组成的列表str本地文件路径.txt/.csv/.json或 Hugging Face Hub 上的数据集标识符构造时Data还会做格式校验不支持的输入类型会抛出DataFormatError如果传入的是DatasetDict即包含多个 split 的数据集会抛出DatasetDictError提示应显式指定split例如datasets.load_dataset(dataset, splittrain)。注意两点使用约束分类任务下标签会被映射为[0, 1, ..., K-1]的整数多标签任务下标签被格式化为列表的列表如[[0, 1], [1, 2]]回归任务下标签保持连续数值使用Datalab需要datasets包它属于 cleanlab 的可选依赖可通过pip install cleanlab[all]一并安装。2.3 task三类受支持的任务Task枚举task.py目前支持三种任务取值含义标签处理classification默认多分类映射为整数regression回归连续值预测保持连续值multilabel多标签分类列表的列表传入非法任务字符串会抛出ValueError。2.4 image_key 与图像特定问题image_key用于图像数据集指向存放实际图片PIL 对象的字段。指定后Datalab会通过create_imagelabimagelab.py调用 CleanVision 包额外审计图像特有的问题类型。默认启用的图像问题类型定义在 constants.pyDEFAULT_CLEANVISION_ISSUESdark过暗light过亮low_information信息量低默认阈值 0.15odd_aspect_ratio宽高比异常odd_size尺寸异常grayscale灰度图blurry模糊限制image_key目前仅支持以 Hugging Facedatasets.Dataset对象形式传入的数据。2.5 verbosity输出详细程度verbosity取值为 0 到 4 的整数值越高审计时Datalab打印的信息越多默认 1。它同时影响find_issues的过程输出与report的默认详细程度report也可单独覆盖。三、发起审计find_issues 的四个可选输入find_issues是Datalab的核心方法签名如下datalab.pydatalab.find_issues( *, pred_probsNone, # 模型预测概率 featuresNone, # 特征向量/嵌入 knn_graphNone, # 预计算的 KNN 稀疏矩阵 issue_typesNone, # 自定义问题类型与参数 )重要说明审计结果保存在datalab.issues属性中find_issues本身不返回任何值issue_types与knn_graph等参数均为关键字参数keyword-only。3.1 输入与可检测问题类型的对应关系find_issues与模型之间只通过预测概率 / 嵌入 / 由它们衍生的 KNN 图交互。提供的输入越多能检测的问题类型越多如果只提供部分输入Datalab会基于有限信息输出它能得到的结论。各输入与问题类型的对应关系见 issue_finder.py_CLASSIFICATION_ARGS_DICT输入主要服务的问题类型pred_probslabel标签错误、outlier、non_iid、underperforming_groupfeaturesoutlier、near_duplicate、non_iid、data_valuation、null、label当没有 pred_probs 时用于拟合 KNN 模型生成预测knn_graphoutlier、near_duplicate、non_iid、data_valuation、underperforming_group无仅class_imbalance类不平衡检测不需要任何模型输入优先级规则源码 issue_finder.py 已明示同时提供knn_graph与features时knn_graph优先大多数问题管理器会优先使用 KNN 图以提高效率同时会打印警告只提供features时内部会基于欧氏或余弦距离构建knn_graph两者都不提供时near_duplicate近似重复等问题将不会被检测提供cluster_ids与knn_graph/features同时时cluster_ids优先于自动聚类。3.2 pred_probs三种任务的形状要求任务形状要求分类二维数组(num_examples, K)K为类别数列顺序必须与类别排序一致Datalab 采用按类别名词典序排列回归一维数组(num_examples,)每行是该样本的预测值多标签二维数组(num_examples, K)列顺序同样按类别名词典序要最准确地检测标签问题应提供你能训练出的最准确模型的样本外out-of-sample预测概率例如通过交叉验证产生。3.3 features特征嵌入的要求features是每个样本的特征向量表示必须是二维数组(num_examples, num_features)。它可以是来自预训练模型的嵌入也可以是对原始特征做数值化变换的结果。3.4 knn_graph预计算 KNN 图CSR 稀疏矩阵knn_graph是样本间距离的 K 近邻图必须以scipy 的 CSR 稀疏矩阵形式传入要求方阵形状(num_examples, num_examples)非零项总数约k * num_examplesk为每个样本的邻居数且均匀分布在各行每个非零项是两个样本间的距离对角线必须全零自距离省略邻居不含自身每行内的距离需按升序排列data数组的对应分段内indices保持同步重复样本距离为 0应存储显式零knn_graph[i, j] 0对于距离为 0 的重复样本对必须显式存零。CSR 格式的三个一维数组含义如下data按行存放矩阵全部非零元素每行内部已排序indices每个非零元素对应的列索引与data一一对应indptr每行非零元素在data中的起止下标第i行的元素位于data[indptr[i]]到data[indptr[i1]]。文档中的示例knn_graph.todense() # matrix([[0. , 0.3, 0.2], # [0.3, 0. , 0.4], # [0.2, 0.4, 0. ]]) knn_graph.data # array([0.2, 0.3, 0.3, 0.4, 0.2, 0.4]) # 第一行的升序距离为 0.2、0.3第二行为 0.3、0.4依此类推。 knn_graph.indices # array([2, 1, 0, 2, 0, 1]) # 与 data 中距离对应的邻居列索引。 knn_graph.indptr # array([0, 2, 4, 6]) # 第一行非零项存于 data[0]~data[2]第二行存于 data[2]~data[4]依此类推。这类矩阵可以直接由sklearn.neighbors.NearestNeighbors.kneighbors_graph(modedistance)生成。注意请直接传入稀疏矩阵本身不要传knn_graph.toarray()转换后的稠密矩阵。3.5 issue_types定制审计内容issue_types是一个字典的字典键是感兴趣的问题类型值是对应IssueManager构造参数组成的字典。不传则使用默认问题类型集合与推荐参数。最简单的定制——只审计标签问题issue_types {label: {}} lab.find_issues(pred_probspred_probs, issue_typesissue_types)进阶定制——向LabelIssueManager构造器传参例如指定CleanLearning的prune_methodissue_types { label: { clean_learning_kwargs: { prune_method: prune_by_noise_rate, }, }, } lab.find_issues(pred_probspred_probs, issue_typesissue_types)边界行为如果传入空的issue_types{}find_issues会打印警告未指定问题类型因此不会在数据集中找到任何问题并直接返回datalab.py。3.6 三个可直接运行的完整示例方式一只传 pred_probsfrom sklearn.linear_model import LogisticRegression import numpy as np from cleanlab import Datalab X np.array([[0, 1], [1, 1], [2, 2], [2, 0]]) y np.array([0, 1, 1, 0]) clf LogisticRegression(random_state0).fit(X, y) pred_probs clf.predict_proba(X) lab Datalab(data{X: X, y: y}, label_namey) lab.find_issues(pred_probspred_probs)方式二只传 featuresfrom sklearn.linear_model import LogisticRegression import numpy as np from cleanlab import Datalab X np.array([[0, 1], [1, 1], [2, 2], [2, 0]]) y np.array([0, 1, 1, 0]) lab Datalab(data{X: X, y: y}, label_namey) lab.find_issues(featuresX)方式三传预计算 knn_graphfrom sklearn.neighbors import NearestNeighbors import numpy as np from cleanlab import Datalab X np.array([[0, 1], [1, 1], [2, 2], [2, 0]]) y np.array([0, 1, 1, 0]) nbrs NearestNeighbors(n_neighbors2, metriceuclidean).fit(X) knn_graph nbrs.kneighbors_graph(modedistance) lab Datalab(data{X: X, y: y}, label_namey) lab.find_issues(knn_graphknn_graph)官方文档建议同时传pred_probs和features可以获得更全面的审计结果。3.7 find_issues 的底层执行流程从源码看find_issues最终委托给IssueFinderissue_finder.pyIssueFinder.find_issues其执行链路为根据传入输入解析每个问题类型所需的参数_resolve_required_args_for_*系列函数通过_IssueManagerFactory.from_list从注册表REGISTRY实例化对应的问题管理器逐个运行IssueManager.find_issues(**arg_dict)并将结果收集进DataIssuescollect_statisticscollect_issues_from_issue_manager单个问题管理器失败不会中断整体审计而是被记录并最终打印Failed to check for these issue types最后调用set_health_score()计算数据集整体健康分当前实现为各类问题 score 的均值见 data_issues.py。此外当数据集没有标签时label_name未提供label、class_imbalance等问题类型会被自动跳过并给出警告issue_finder.pyget_available_issue_types。四、默认审计的问题类型与任务相关注册表当issue_types未指定时Datalab使用各任务的默认问题类型集合issue_manager_factory.pylist_default_issue_types任务默认审计的问题类型分类null、label、outlier、near_duplicate、non_iid、class_imbalance、underperforming_group回归null、label、outlier、near_duplicate、non_iid多标签null、label、outlier、near_duplicate、non_iid而完整的可能问题类型注册表REGISTRY即list_possible_issue_types()返回的内容见 issue_manager_factory.py为任务全部已注册问题类型分类outlier、label、near_duplicate、non_iid、class_imbalance、underperforming_group、data_valuation、null回归label、outlier、near_duplicate、non_iid、data_valuation、null多标签label、outlier、near_duplicate、non_iid、data_valuation、null对于图像数据集指定了image_keylist_possible_issue_types()与list_default_issue_types()都会追加DEFAULT_CLEANVISION_ISSUES中的图像问题类型datalab.py。注意data_valuation数据估值属于可能但不在默认审计集合中的问题类型需要显式传入issue_types才会运行。4.1 每种问题类型的三种输出估计对每种问题类型以ISSUE_NAME代称Datalab会产出三类估计逐样本质量分ISSUE_NAME_score0~1 的数值越接近 0 表示该样本越严重地表现出此问题通过datalab.issues属性或datalab.get_issues(ISSUE_NAME)访问逐样本布尔标记is_ISSUE_NAME_issueTrue表示估计该样本存在此问题数据集整体分0~1量化该问题在整个数据集上的严重程度分数越高表示整体越健康通过datalab.issue_summary属性或datalab.get_issue_summary(ISSUE_NAME)访问。以outlier为例issue_name outlier # 代码中的引用名 issue_score outlier_score # 质量分列名越典型的异常点分数越低 is_issue is_outlier_issue # 布尔标记列名横向可比性提醒同一种问题类型的分数可以在不同样本、不同数据集之间比较但不同类型问题之间的分数不可互相比较例如标签质量用标签似然估计而异常点质量用特征空间 KNN 距离估计两者本质不可比。某些问题类型如non_iid的整体分并非逐样本分数的均值而是数据集的全局统计量如数据为 IID 这一假设检验的 p 值。数据集级 vs 样本级问题non_iid、class_imbalance、underperforming_group属于主要关乎整个数据集的问题应优先通过get_issue_summary的全局分来考察而label、outlier、near_duplicate、null属于主要关乎单个样本的问题可放心用get_issues逐样本查看。4.2 每种问题类型所需的模型输入不同问题类型的检测依赖不同的输入可从 issue_finder.py 参数表 归纳问题类型需要的输入label分类pred_probs或features回归features 预测值多标签pred_probsoutlier分类pred_probs/features/knn_graph之一其余任务features/knn_graphnear_duplicatefeatures或knn_graphnon_iid分类pred_probs/features/knn_graph其余任务features/knn_graphunderperforming_grouppred_probsfeatures/knn_graph/cluster_ids三者之一data_valuationfeatures或knn_graphclass_imbalance无仅需标签nullfeaturesIssueFinder会自动剔除输入不足的问题类型因此你可以放心只提供部分输入。五、查看审计结果属性与查询方法5.1 属性速查表属性类型内容datalab.issuespd.DataFrame逐样本问题标记与质量分datalab.issue_summarypd.DataFrame各问题类型整体汇总列issue_type、score、num_issuesdatalab.infodict每个问题类型的详细信息与统计含statistics键存放样本数、类别数、健康分等datalab.labelsnp.ndarray/List[List[int]]标签[0, ..., K-1]格式datalab.has_labelsbool是否有标签且为整数格式datalab.class_namesList[str]类别名列表无标签时为空列表datalab.dataDataset内部的 Hugging Face Datasetdatalab.cleanlab_versionstr创建该对象的 cleanlab 版本issue_summary示例 datalab.issue_summary issue_type score outlier 0.123 label 0.456info示例同时检测了 label 与 outlier datalab.info { label: { given_labels: [0, 1, 0, 1, 1, 1, 1, 1, 0, 1, ...], predicted_label: [0, 0, 0, 1, 0, 1, 0, 1, 0, 1, ...], ..., }, outlier: { nearest_neighbor: [3, 7, 1, 2, 8, 4, 5, 9, 6, 0, ...], distance_to_nearest_neighbor: [0.123, 0.789, 0.456, ...], ..., }, }5.2 查询方法方法说明get_issues(issue_nameNone)返回逐样本问题 DataFrame。issue_nameNone时返回全部类型指定时只返回该类型相关列label会附带given_label/predicted_label列near_duplicate会附带near_duplicate_sets/distance_to_nearest_neighbor列。非法名称抛出ValueErrorget_issue_summary(issue_nameNone)返回问题汇总 DataFrameNone时返回全部get_info(issue_nameNone)返回指定问题类型的详细信息字典未计算时抛出ValueErrorlist_possible_issue_types()返回所有已注册、可在find_issues中使用的问题类型list_default_issue_types()返回不指定issue_types时默认运行的问题类型get_issues的实现位于 data_issues.pyDataIssues.get_issues当issues为空未执行find_issues时会给出详细提示的ValueError。数据统计样本数、类别名、类别数、健康分则通过get_info(statistics)或DataIssues.statistics属性获取data_issues.pyget_data_statistics。六、生成可读报告report 方法datalab.report( *, num_examples5, # 每种问题展示的 top 样本数 verbosityNone, # 覆盖构造时的 verbosity默认沿用 include_descriptionTrue, # 是否包含每种问题的文字描述 show_summary_scoreFalse, # 是否显示整体严重度分数列 show_all_issuesFalse, # 是否展示所有被检查过的问题类型含未检测到的 )各参数行为datalab.pyreportnum_examples报告对每种问题类型展示受害最严重的 top N 个样本verbosity更高等级会向报告中加入更多信息每种IssueManager各自定义各等级追加的内容例如LabelIssueManager在第 3 级会加入classes_by_label_quality与overlapping_classes见 label.pyinclude_description熟悉各类问题定义后可设为False以精简输出show_summary_score是否显示每种问题的整体严重度分。注意这些分数在不同问题类型之间不可比较show_all_issues设为True时报告会包含所有被检查过的问题类型包括在数据中未检测到的问题类型。报告实现位于 report.pyReporter.get_report先按num_issues降序输出汇总表再逐一调用各问题管理器的report类方法拼接各问题详情。报告头部会打印数据集信息num_examples、num_classes当数据中没有任何问题时会输出 No issues found in the data. Good job!并建议用show_summary_scoreTrue与show_all_issuesTrue重跑以查看完整信息report.py。七、持久化save 与 loadDatalab支持将审计结果保存到磁盘并在之后重新加载datalab.save(pathmy_datalab/, forceFalse) datalab_loaded Datalab.load(pathmy_datalab/, dataNone)要点datalab.py 与 serialize.py_Serializersave会在path目录下生成datalab.pkl对象本身、issues.csv、summary.csv以及data/子目录数据集副本forceFalse且目录已存在时抛出FileExistsError数据集本身不会被保存在Datalab内如需保留数据请自行另存load时若传入data会校验数据哈希与长度是否与保存时一致不一致则报错cleanlab 不保证旧版本保存的Datalab能被未来版本加载版本不一致时load会打印警告Things may be broken!。八、扩展机制自定义问题类型Datalab通过工厂 注册表机制支持自定义问题类型issue_manager_factory.pyregister。任何IssueManager子类都可以被注册进REGISTRY之后即可像内置问题类型一样在find_issues(issue_types{...})中使用。from cleanlab.datalab.internal.issue_manager.issue_manager import IssueManager from cleanlab.datalab.internal.issue_manager_factory import register register class MyIssueManager(IssueManager): issue_name: str my_issue def find_issues(self, **kwargs): # 实现具体的问题检测逻辑 pass或采用函数调用式注册register(MyIssueManager, taskclassification)IssueManager基类issue_manager.py要求每个问题管理器为每个样本计算0~1 的严重度分数越接近 0 越严重布尔is_issue标记可通过阈值化分数得到或像 Confident Learning 那样用其他方式判定数据集整体严重度如所有样本分数均值或is_issueTrue的样本数其他有用的info例如标签问题的confident_thresholds、confident_joint、预测标签近似重复问题的重复样本集合等。注意注册表与工厂属于内部实现细节文档明确警告不应被普通用户直接使用register装饰器注册同名问题类型时会打印覆盖警告。九、从源码与测试看典型用法仓库测试 test_datalab.py 覆盖了Datalab的典型生命周期构造非法DatasetDict校验、print/__repr__输出、class_names、list_default_issue_types、get_info、get_issue_summary、get_issues、带pred_probs的find_issues、空issue_types警告、自定义超参数、重复find_issues后report、save/load/pickle往返、失败问题管理器容错、knn_graph与features的优先级等。最小可用流程总结如下from cleanlab import Datalab # 1. 构造 lab Datalab(datadataset, label_namelabel, taskclassification) # 2. 审计pred_probs 需为样本外预测概率 lab.find_issues(pred_probspred_probs, featuresfeatures) # 3. 查看结果 lab.report() # 人类可读报告 lab.get_issues(label) # 标签问题逐样本详情 lab.get_issue_summary() # 各问题类型汇总 lab.info[statistics] # 数据集统计与健康分 # 4. 持久化可选 lab.save(pathaudit_result/)一个实用的惯例是先用lab.find_issues(featuresX)做一次无需训练模型的初步审计覆盖异常点、近似重复、非 IID、空值等再补充pred_probs进行完整审计覆盖标签错误、类不平衡、欠表现分组等。十、适用前提与注意事项可选依赖Datalab依赖datasets包图像审计还依赖cleanvision请通过pip install cleanlab[all]安装全部可选依赖pred_probs 列序分类与多标签任务的pred_probs列必须按类别名词典序排列否则标签审计结果会错位knn_graph 格式必须是符合 CSR 规范、对角线为零、行内升序的稀疏矩阵重复样本对须显式存零输入不足时的问题降级不提供pred_probs/features/knn_graph相应问题类型会自动被跳过这是设计行为而非错误分数可比性边界同类型问题的分数可跨样本/跨数据集比较不同类型之间不可比较持久化兼容性save的结果不保证被未来 cleanlab 版本加载。结语Datalab将 cleanlab 的数据中心 AI 能力收敛为一个对象、一次调用覆盖从构造、审计、查询、报告到持久化的完整数据质量工作流。结合 datalab.py 源码及其内部组件issue_finder.py、data_issues.py、issue_manager_factory.py、report.py你可以按需定制审计内容甚至注册自己的问题类型将数据质量审计变成可复用、可解释、可扩展的标准流程。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考