Cleanlab Datalab 指南：为 Underperforming Group 检测生成与传入预计算 Cluster IDs

Cleanlab Datalab 指南为 Underperforming Group 检测生成与传入预计算 Cluster IDs【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab本文讲解 Cleanlab Datalab 中underperforming_group欠拟合群体问题检测的核心进阶用法——如何为数据集预计算 Cluster IDs聚类编号并显式传入find_issues()以完全掌控“数据切片data slices”的划分方式。读完本文你将掌握使用 K-Means、DBSCAN、HDBSCAN 等算法生成 Cluster IDs 的方法、cluster_ids参数在源码层面的完整执行链路优先级、过滤规则、评分机制以及基于表格数据中类别型列做业务切片的最佳实践。一、为什么需要预计算 Cluster IDs在 Datalab 问题类型指南 中underperforming_group被定义为“数据集中模型预测表现特别差的一簇相似样本即一个切片”。检测它的完整输入组合有三种见 issue_finder.py 中的_CLASSIFICATION_ARGS_DICTpred_probsfeaturespred_probsknn_graphpred_probscluster_ids前两种方式下Cleanlab 会自动执行聚类来划分样本组而第三种方式则是把“如何分组”的决定权完全交给你——绕过自动聚类直接使用你预先计算好的聚类结果。官方文档将其标注为面向高级用户advanced users的选项原因在于自动聚类基于特征空间的几何距离而业务上真正有意义的“组”往往是按某个语义维度划分的例如表格数据中的某个类别型列。因此在 生成 Cluster IDs 指南 中官方给出的核心建议是先用聚类算法对特征向量聚类得到每个样本的cluster_ids再将其作为参数传给find_issues()。二、使用 K-Means 生成 Cluster IDs官方示例指南文档给出的完整示例逻辑如下原文中import datalab与Datalab未导入的问题这里给出可直接运行的修正版import numpy as np from sklearn.cluster import KMeans from cleanlab import Datalab # 假设你已准备好以下数据 features, labels your_data() # 特征矩阵与标签features 形状为 (n_samples, n_features) pred_probs get_pred_probs() # 每个样本的预测概率形状为 (n_samples, K) # 将特征聚成 5 个簇 clusterer KMeans(n_clusters5) clusterer.fit(features) cluster_ids clusterer.labels_ # 每个样本的簇编号形状为 (n_samples,) # 初始化 Datalab 并传入预计算的 cluster_ids lab Datalab(data{features: features, y: labels}, label_namey) issue_types {underperforming_group: {cluster_ids: cluster_ids}} lab.find_issues(featuresfeatures, pred_probspred_probs, issue_typesissue_types)这里的关键点是cluster_ids并非find_issues()的顶层参数而是issue_types字典中underperforming_group这一键的配置项。find_issues()会把这个字典作为关键字参数传递给对应的UnderperformingGroupIssueManager参见 datalab.py 中issue_types的说明。选择聚类算法时的注意事项指南文档明确提醒了两种常用算法各自的取舍算法必须指定的参数说明K-Meansn_clusters需要显式指定簇数量且对初始质心与数据尺度敏感适合簇形状接近球形、分布较均匀的数据DBSCANeps邻域半径与min_samples每簇最小样本数对这两个参数非常敏感eps过大会把不同簇合并过小会把一个簇拆散并产生大量噪声点除此之外你也可以使用 HDBSCAN 等基于密度的算法。无论采用哪种算法最终都要得到一维整数数组cluster_ids其中每个元素对应数据集中一个样本的簇编号。三、传入 cluster_ids 后源码中发生了什么理解了“怎么传”还要明白“传进去之后会发生什么”。UnderperformingGroupIssueManager.find_issues()见 underperforming_group.py的执行流程如下1. cluster_ids 的优先级与警告if cluster_ids is None: # 未提供时基于 features/knn_graph 自动构建 knn 图并执行 DBSCAN 聚类 ... cluster_ids self.perform_clustering(knn_graph) performed_clustering True else: if self.clustering_kwargs: warnings.warn( clustering_kwargs will not be used since cluster_ids have been passed. ) performed_clustering False即只要显式传入了cluster_ids内部的 DBSCAN 聚类就会被跳过并且不再需要features或knn_graph测试test_collect_info也验证了此时 info 中不会包含最近邻相关信息。同时注意两点如果你同时传了clustering_kwargs和cluster_ids会收到一条警告提示clustering_kwargs被忽略在更高一层的 issue_finder.py 中若cluster_ids与features/knn_graph同时出现也会发出警告并明确cluster_ids优先于特征计算出的簇标签。2. 簇过滤剔除噪声簇与过小簇unique_cluster_ids self.filter_cluster_ids(cluster_ids) if not unique_cluster_ids.size: raise ValueError( No meaningful clusters were generated for determining underperforming group. )filter_cluster_ids()underperforming_group.py执行两类过滤剔除噪声簇OUTLIER_CLUSTER_LABELS (-1,)。-1是 DBSCAN 约定俗成的噪声点标签传入的cluster_ids中所有值为-1的样本会被视为离群样本而排除剔除过小簇簇内样本数小于min_cluster_samples默认 5的簇会被过滤。测试test_min_cluster_samples验证了构造一个仅含 3 个样本的小簇后默认参数下它不会被纳入统计而将min_cluster_samples3后该簇恢复参与计算。如果过滤后没有任何有意义的簇会抛出ValueError: No meaningful clusters were generated...。测试test_no_meaningful_clusters覆盖了三种触发场景数据过于稀疏无法被 DBSCAN 聚类、传入的cluster_ids全部为-1全是噪声、传入空数组。3. 逐簇评分与最差簇判定get_underperforming_clusters()underperforming_group.py是核心算法用rank.get_self_confidence_for_each_label()rank.py计算每个样本的 self-confidence 分数即模型对给定标签的预测概率计算全数据集平均表现r与每个簇的平均表现q若某簇的q r记录其质量分数q / r找出比值最低的簇作为worst_cluster_id仅当worst_cluster_ratio threshold默认 0.1时才判定数据集存在欠拟合群体否则该值设为NO_UNDERPERFORMING_CLUSTER_ID -2表示不存在欠拟合簇。最终输出的underperforming_group_score属于最差簇的样本获得q / r其余样本一律为 1is_underperforming_group_issue列则只在该簇的样本上为True。这与 issue_type_description.rst 中对该 issue 输出的描述完全一致。4. 记录聚类信息到 infocollect_info()underperforming_group.py会把聚类过程沉淀到lab.get_info(underperforming_group)中其中clustering键的结构为{ algorithm: DBSCAN, # 自动聚类时为 DBSCAN传入 cluster_ids 时为 None params: {metric: precomputed}, # 传入 cluster_ids 时为 {} stats: { n_clusters: n_clusters, cluster_ids: cluster_ids, # 完整保留你传入的簇编号 underperforming_cluster_id: worst_cluster_id, # 无欠拟合簇时为 -2 }, }注意当你显式传入cluster_ids时algorithm与params分别为None和{}表明本次分组并非 Cleanlab 自动聚类所得。四、进阶用法用类别型列做业务切片指南文档与 issue_type_description.rst 都强调了一个非常实用的场景表格数据中按类别型列切分数据。例如你的数据集中有一列“地区”“设备类型”或“用户分组”只需将该列做整数编码作为cluster_ids传入即可让 Datalab 直接评估“模型在哪个地区/哪类设备上表现最差”import pandas as pd from sklearn.preprocessing import LabelEncoder from cleanlab import Datalab df pd.read_csv(your_dataset.csv) # 假设包含 region 类别列 features df.drop(columns[region, label]).values labels df[label].values pred_probs ... # 交叉验证得到的 out-of-sample 预测概率 encoder LabelEncoder() cluster_ids encoder.fit_transform(df[region].values) # 整数编码的切片编号 lab Datalab(data{features: features, y: labels}, label_namey) lab.find_issues( featuresfeatures, pred_probspred_probs, issue_types{underperforming_group: {cluster_ids: cluster_ids}}, ) # 查看每个切片的欠拟合情况 print(lab.get_info(underperforming_group)[clustering]) print(lab.get_issues(underperforming_group))由于cluster_ids本质上只是“样本分组标签”其具体数值大小没有意义只有分组关系有意义。仓库测试test_find_issues中专门验证了这一点将标签直接作为cluster_ids、或将标签整体加 10 得到偏移后的cluster_ids两者产生的 issues 与 summary 结果完全一致。因此你完全可以自由使用任意整数编码方案。五、underperforming_group 的完整参数参考综合 issue_type_description.rst 与构造函数实现underperforming_group.pyissue_types中可用的全部参数如下参数默认值类型作用cluster_idsNone一维 numpy 整数数组每个样本的簇标签。传入后跳过内部聚类直接用于欠拟合组判定本文核心参数threshold0.1float[0, 1]判定欠拟合组的灵敏度簇表现与全数据表现之比q/r低于该值才判定为欠拟合。若传入负数会被钳制为 0 并发出警告metricNonestr 或 callable仅在自动聚类时需要用于最近邻搜索的距离度量透传给sklearn.neighbors.NearestNeighborsk10int仅在自动聚类时需要构建 knn 图的近邻数min_cluster_samples5非负 int一个簇至少需要多少样本才会被纳入欠拟合组评估注意与sklearn.cluster.DBSCAN的min_samples参数含义不同源码 docstring 对此有专门提醒clustering_kwargs{}dict传给聚类算法构造器的关键字参数。内部自动聚类时使用DBSCAN(metricprecomputed)可用{eps: 0.5}等控制聚类粒度若同时传入cluster_ids则此参数被忽略并告警数据前提与限制标签必须是 numpy 数组UnderperformingGroupIssueManager要求self.datalab.labels为np.ndarray否则抛出TypeErrorunderperforming_group.pypred_probs必不可少在 issue_finder.py 中underperforming_group被定义为“需要pred_probs 其余三者之一”的组合只传cluster_ids而不传pred_probs时该 issue 不会被检查cluster_ids长度必须与数据集样本数一致每个样本都应属于某个非噪声簇若全部样本都被过滤如全为-1将抛出ValueError。六、如何验证你的实现仓库测试一览如果你想在自己的项目中复现或验证上述行为可以直接参考仓库中的单元测试 test_underperforming_group.py其中与本主题直接相关的用例包括test_find_issues分别用自动聚类与显式传入cluster_ids原始标签、偏移后的标签两种方式检测断言二者的 issues 与 summary 结果等价test_no_meaningful_clusters验证全为-1的簇编号、空数组等场景抛出ValueErrortest_min_cluster_samples验证min_cluster_samples对小簇的过滤行为test_collect_info验证传入cluster_ids后info[clustering][algorithm]为None、params为空字典且cluster_ids原样保留在 stats 中。这些测试同时也是一个很好的“行为规范文档”帮助你确认自己的传参方式与 Cleanlab 的预期完全一致。七、进一步阅读Datalab Issue Types 详解含 underperforming_group 输出字段说明官方 FAQ如何为欠拟合组检测指定预计算数据切片/簇UnderperformingGroupIssueManager 源码Datalab 快速上手教程Datalab workflows 教程含预计算切片在真实工作流中的更多用法【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考