Cleanlab count 模块全解析估计标签噪声潜在结构的核心 API 指南【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab本篇技术指南以 cleanlab/count.py 模块及其文档 docs/source/cleanlab/count.rst 为主体系统讲解 Cleanlab 数据为中心的 AI 库中用于估计标签噪声潜在结构latent structures的全部核心 API潜在先验py、噪声矩阵nm、逆噪声矩阵inv与置信联合矩阵confident_joint。读完本文你将掌握置信学习Confident Learning统计引擎的完整调用链能够直接使用这些函数量化数据集中的标签错误数量、估计噪声转移概率并在多分类与多标签两种数据集上落地实践。模块定位置信学习流水线中的统计引擎在 Cleanlab 的整体架构中cleanlab.count负责回答一个根本性问题给定一堆可能带噪声的标签和模型的预测概率真实标签的潜在分布是什么标签被翻转的概率有多大该模块在整个库中处于基础地位其输出被多个上层模块复用cleanlab/filter.py 中的find_label_issues依赖count计算出的confident_joint来定位具体的问题样本cleanlab/rank.py 借助num_label_issues的输出确定评分排序的截断阈值cleanlab/classification.py 中的CleanLearning在训练阶段使用estimate_py_noise_matrices_and_cv_pred_proba估计噪声先验来修正损失函数cleanlab/internal/latent_algebra.py 提供矩阵代数运算cleanlab/internal/constants.py 提供数值裁剪常量二者共同支撑count的数值稳定性。从源码结构看count是典型的输入labels pred_probs→ 置信联合 → 潜在变量 → 标签问题数量的单向数据流引擎测试主要集中在 tests/test_filter_count.py。四个核心潜在量py、nm、inv、confident_joint模块 docstring 明确了其估计的四类潜在结构名称数学含义描述pyp(y)未观察到的、无错误标签的潜在先验真实类别的比例nmP(given label \| true label)噪声矩阵noise matrix刻画标签翻转率invP(true label \| given label)逆噪声矩阵刻画翻转过程的逆条件概率confident_joint未归一化计数矩阵在真实/给定标签联合分布下置信子集的标签错误计数其中confident_joint是其余三个量的计算基础先由它归一化得到联合分布再沿行/列求和推导出噪声矩阵与逆噪声矩阵最后通过代数关系反解出py。整个过程的核心假设是模型预测概率足够好能够对哪些样本的真实标签是什么产生置信判断。两类数据集支持多分类与多标签模块同时支持两种分类设定cleanlab/count.py 模块 docstring标准多类分类每个样本恰好属于 K 个类中的一个例如labels np.array([0, 0, 1, 0, 2, 1])多标签分类每个样本可同时属于多个类例如labels [[1, 2], [1], [0], [], ...]。所有公开 API 均提供multi_label: bool参数。多标签模式下labels必须是list类型传入 numpy 数组会抛出TypeError且置信联合、联合分布、阈值等矩阵一律采用形状(K, 2, 2)的one-vs-rest 格式对每个类c维护一个 2×2 矩阵四个元素分别计数含/不含类 c 的噪声标签 × 置信判定为属于/不属于类 c 的真实标签四种组合。多标签场景以样本的标签数量而非样本数量为计数基准因此置信联合的数值会更大。置信联合compute_confident_jointcompute_confident_joint是模块中最核心的函数它估算数据集样本中潜在真实标签 vs 观察到的噪声标签的置信计数矩阵形状为(K, K)from cleanlab.count import compute_confident_joint cj compute_confident_joint( labelslabels, # np.ndarray 或 listN 个样本的给定标签 pred_probspred_probs, # (N, K) 的模型预测概率 thresholdsNone, # 每类置信阈值形状 (K,) 或 (K, 1)高级用户可自定义 calibrateTrue, # 是否校准为有效计数估计 multi_labelFalse, # 多标签模式开关 return_indices_of_off_diagonalsFalse, # 是否同时返回 off-diagonal 样本索引 )参数与语义labels/pred_probs与filter.find_label_issues完全相同的格式约定。thresholds每类的阈值概率数组。若某样本对类k的预测概率超过该阈值则被计入true_label k。仅用于估计噪声率不用于剪枝/过滤。默认由get_confident_thresholds自动计算文档明确标注这是仅限高级用户的参数理论依据见 Northcutt 等 2021 年关于置信学习的论文Section 3.1 Equation 2。calibrate默认为True。校准后保证np.sum(cj) len(labels)且np.sum(cj, axis1) np.bincount(labels)使其成为噪声与真实标签联合分布的有效计数估计。return_indices_of_off_diagonals置True时函数返回元组(confident_joint, indices_off_diagonal)其中索引列表可作为标签问题的基线代理——文档指出这在某些情况下效果不亚于filter.find_label_issues(confident_joint)。算法本质文档中的简化伪代码函数 docstring 给出了一个便于理解的 for 循环版实现直观揭示了算法本质cj_ish np.zeros((K, K)) for k_s in range(K): # k_s 是噪声标签 s 的类值 for k_y in range(K): # k_y 是猜测的真实标签类 cj_ish[k_s][k_y] sum( (pred_probs[:, k_y] (thresholds[k_y] - 1e-8)) (labels k_s) )即逐对扫描噪声标签类置信真实类统计预测概率超过该类阈值且给定标签为该噪声类的样本数。docstring 还提供了一段 100% 等价的向量化教学实现对每个样本统计超过阈值的置信箱数量恰好 1 个时直接计入对应类多于 1 个时取最大概率的类。源码中的实际向量化实现要点生产代码cleanlab/count.py 中compute_confident_joint实现在此思想基础上做了数值与性能优化构造布尔矩阵pred_probs_bool pred_probs thresholds - 1e-61e-6即 cleanlab/internal/constants.py 中的FLOATING_POINT_COMPARISON对每行统计置信箱数量0 个往往是离群样本被排除、恰好 1 个直接采用该置信类、多于 1 个采用argmax的最大概率类用sklearn.metrics.confusion_matrix统计并转置得到(K, K)计数矩阵np.fill_diagonal(confident_joint, confident_joint.diagonal().clip(min1))保证每个类的对角元至少为 1确保每个真实类都有至少一个置信正确的样本若calibrateTrue交给calibrate_confident_joint做行和与总数校准。代码还专门处理了没有任何置信样本的空输入边界情况兼容 sklearn 不同版本的confusion_matrix行为对应测试为 tests/test_filter_count.py 中的test_compute_confident_joint_no_confident_examples。校准与联合分布calibrate_confident_joint 与 estimate_jointcalibrate_confident_joint把置信计数修正为有效计数from cleanlab.count import calibrate_confident_joint calibrated_cj calibrate_confident_joint( confident_jointcj, # (K, K) 或 (K, 2, 2) labelslabels, multi_labelFalse, )该函数对任何置信联合估计施加两个硬约束行方向np.sum(cj, axis1) np.bincount(labels)即每行的行和必须等于给定噪声标签的真实频数使置信联合携带正确的噪声先验p(labels)总量方向np.sum(cj) len(labels)单标签或总标签数多标签使矩阵成为真正的计数而非比例。实现上先按行归一化再乘label_counts随后整体归一化再乘样本总数最后用round_preserving_row_totals取整并保持行和不丢失。多标签版本_calibrate_confident_joint_multilabel对每个类单独执行一次 2×2 校准文档明确指出校准后每个类特定的 2×2 矩阵元素之和等于样本总数。estimate_joint归一化为联合分布from cleanlab.count import estimate_joint joint estimate_joint( labelslabels, pred_probspred_probs, confident_jointNone, # 不传则内部自动计算并校准 multi_labelFalse, )estimate_joint返回真实噪声标签的联合分布P(labeli, true_labelj)保证所有元素之和为 1np.sum(joint_estimate) 1行方向满足np.sum(joint_estimate, axis1) p(labels)。实现上若未提供confident_joint内部会先compute_confident_joint(calibrateTrue)再整体除以总和若提供则先经calibrate_confident_joint校准再归一化。测试 tests/test_filter_count.py 的test_estimate_joint断言了abs(np.sum(joint) - 1.0) 1e-6这一关键性质。潜在变量估计estimate_latentestimate_latent从置信联合出发一次性解出三个潜在量from cleanlab.count import estimate_latent py, noise_matrix, inv_noise_matrix estimate_latent( confident_jointcj, # 由 compute_confident_joint 得到 labelslabels, # 1D 数组元素为 0..K-1 的整数 py_methodcnt, # {cnt, eqn, marginal, marginal_ps} converge_latent_estimatesFalse, )py_method 四种先验估计策略py表示真实标签的类别比例先验p(true_labelk)。源码支持四种策略py_method说明cnt默认使用矩阵对角元估计先验即使噪声矩阵估计较差也能工作良好eqn基于闭式方程求解marginal基于边际分布估计marginal_ps基于噪声标签边际的变体默认cnt的鲁棒性来自它对噪声矩阵对角元即被正确标注的比例的依赖而非全部概率项。测试test_estimate_latent_py_method验证了三种方法均可正常收敛。数值一致性收敛converge_latent_estimatesTrue时py、noise_matrix、inv_noise_matrix三者在数学上存在闭式等价关系但由于各自独立估计会产生数值不一致函数通过_converge_estimates迭代强制它们互相吻合内部先迭代inv_noise_matrix_iterations5次收敛逆噪声矩阵与py交替更新再更新噪声矩阵外层循环noise_matrix_iterations3次。源码注释特别警告迭代次数不宜过高否则微小偏差会被反复扰动放大反而降低性能。收敛后还会再次将py裁剪到[1e-5, 1.0]并归一化、将两个矩阵裁剪为合法概率。需要说明的是estimate_latent不支持多标签分类多标签场景请使用estimate_joint(multi_labelTrue)。标签问题数量num_label_issuesnum_label_issues是面向只需数量、不需要索引场景的高频 API文档明确建议当不需要问题样本的下标时用它获得最准确的标签问题数估计。from cleanlab.count import num_label_issues num_issues num_label_issues( labelslabels, pred_probspred_probs, confident_jointNone, # 可选提供时配合 off_diagonal_custom 使用 estimation_methodoff_diagonal, multi_labelFalse, )三种估计方法对比estimation_method原理特点off_diagonal默认统计confident_joint非对角元中真实标签 ≠ 给定标签的样本数与sum(find_label_issues(filter_byconfident_learning))返回值一致off_diagonal_calibrated先校准使np.sum(cj) len(labels)且np.sum(cj, axis1) np.bincount(labels)再计数非对角元结果恒 ≥off_diagonal适合作为排序/评分截断阈值off_diagonal_custom直接对用户提供的confident_joint计数必须传入矩阵否则抛出ValueError方法选择建议来自文档off_diagonal在类别较少 4 类时可能低估问题数量此时优先考虑off_diagonal_calibrated。off_diagonal_calibrated的截断值还可配合 cleanlab/rank.py 的排序/评分函数使用既适用于未来新增的评分函数也适用于你自定义的标签质量评分——只需知道多少个样本最可能是问题样本即可。关键实现细节若传入confident_joint但方法不是off_diagonal_custom函数会发出警告并忽略该参数、内部基于labels和pred_probs重新计算off_diagonal路径中先取置信联合的 off-diagonal 索引再用_reduce_issues移除模型预测接近给定标签的样本该掩码对二进制分类在 0.5 附近设定容差容差常量为FLOATING_POINT_COMPARISON 1e-6避免把模型自身也拿不准的样本误判为标签错误off_diagonal_calibrated与off_diagonal_custom路径则通过1 - joint.trace()得到问题样本占比再乘以样本数取整多标签路径直接调用filter.find_label_issues(multi_labelTrue, filter_byconfident_learning)并求和以保证与非多标签的off_diagonal口径一致。对应测试 tests/test_filter_count.py 中的test_num_label_issues同时覆盖了三种方法及非法方法名、缺失confident_joint时的ValueError行为。置信阈值get_confident_thresholdsfrom cleanlab.count import get_confident_thresholds thresholds get_confident_thresholds( labelslabels, pred_probspred_probs, multi_labelFalse, )该函数返回每类的预期平均自置信度类j的置信阈值 在所有被标记为类j的样本上模型对类j预测概率的平均值。它构成了compute_confident_joint默认阈值的基础。源码实现有两个值得注意的细节若某类在标签中缺失训练集缺少某类样本其阈值被设为BIG_VALUE 2。由于 softmax 概率不超过 1任何样本的预测概率都不可能达到 2从而保证不会有样本被误计入缺失类test_missing_classes等测试专门覆盖了缺失类场景。阈值最终会被裁剪到下限CONFIDENT_THRESHOLDS_LOWER_BOUND 2 * 1e-6见 cleanlab/internal/constants.py避免除零与浮点比较问题。多标签模式下返回形状为(K, 2)的 one-vs-rest 阈值。端到端交叉验证系列免去手动生成 pred_probs所有count函数都要求pred_probs为样本外out-of-sample预测概率否则模型过拟合会严重污染估计文档强调可用交叉验证实现参见 docs/source/tutorials/pred_probs_cross_val.rst。为此模块提供了一批从原始特征矩阵一步到位的高层函数默认使用LogReg(solverlbfgs)作为内置分类器from cleanlab.count import ( estimate_cv_predicted_probabilities, estimate_confident_joint_and_cv_pred_proba, estimate_py_noise_matrices_and_cv_pred_proba, estimate_noise_matrices, estimate_py_and_noise_matrices_from_probabilities, ) # 只取 out-of-sample 概率 (N, K) pred_probs estimate_cv_predicted_probabilities(X, labels, cv_n_folds5, seed0) # 置信联合 概率 cj, pred_probs estimate_confident_joint_and_cv_pred_proba(X, labels) # 一次性得到 (py, noise_matrix, inv_noise_matrix, confident_joint, pred_probs) py, nm, inv, cj, pred_probs estimate_py_noise_matrices_and_cv_pred_proba(X, labels) # 仅取噪声矩阵与逆噪声矩阵 nm, inv estimate_noise_matrices(X, labels) # 已有 pred_probs 时直接从概率估计全部潜在量 py, nm, inv, cj estimate_py_and_noise_matrices_from_probabilities(labels, pred_probs)通用参数与内部机制这些函数共享一批参数clf实现 scikit-learn 估计器 API 的分类器、cv_n_folds5交叉验证折数、seed折叠随机状态None时使用np.random当前状态、thresholds高级用自动计算、clf_kwargs传给clf.fit()的关键字参数、validation_func自定义验证集映射签名与CleanLearning.fit文档一致。内部实现cleanlab/count.py 的estimate_confident_joint_and_cv_pred_proba值得关注的几点使用StratifiedKFold(n_splitscv_n_folds, shuffleTrue, random_stateseed)分层划分保留每个类中噪声正负样本的比例缺失类兜底若某折的训练集缺少某个类会从 holdout 集复制一个该类的样本进训练集并发出警告其预测概率被替换为对该类的 1.0 哑编码防止分类器训练失败clf必须可通过sklearn.base.clone(clf)克隆出全新未训练的副本否则抛出ValueError并提示你自行完成交叉验证后传入pred_probs文档说明了两种置信联合计算路线(1) 每折分别算再求和阈值更准、(2) 合并所有概率后统一计算小数据更稳生产实现选择了 (2)文件末尾保留了路线 (1) 的注释版本estimate_py_and_noise_matrices_from_probabilities是唯一不经过 CV的入口要求你已持有pred_probs它内部依次调用compute_confident_joint与estimate_latent返回(py, noise_matrix, inv_noise_matrix, confident_joint)四元组。内部代数支撑latent_algebra 与常量体系count的数值正确性依赖于 cleanlab/internal/latent_algebra.py 的三个闭式运算compute_inv_noise_matrix(py, noise_matrix, ps)由py与噪声矩阵按贝叶斯关系反解逆噪声矩阵compute_noise_matrix_from_inverse(ps, inverse_noise_matrix, py)逆运算用于_converge_estimates的迭代外环compute_py(ps, noise_matrix, inverse_noise_matrix, py_method, true_labels_class_counts)按py_method指定的策略默认cnt用对角元反解真实类先验。数值稳定性方面cleanlab/internal/constants.py 定义了三个关键常量FLOATING_POINT_COMPARISON 1e-6浮点模糊比较容差用于置信计数与_reduce_issues、CONFIDENT_THRESHOLDS_LOWER_BOUND 2e-6置信阈值下限、TINY_VALUE 1e-100裁剪下界防止除零。所有除法运算前都会用np.clip(..., a_minTINY_VALUE, a_maxNone)保护分母。测试验证与可靠性模块的可靠性在 tests/test_filter_count.py 中得到系统性验证关键测试包括test_num_label_issues/test_num_label_issues_different_estimation_types三种估计方法的一致性、警告行为与异常路径test_calibrate_joint/test_estimate_joint校准后行和与总数的硬约束、联合分布求和为 1test_compute_confident_joint/test_compute_confident_joint_no_confident_examples矩阵形状与空输入边界test_estimate_latent_py_method/test_estimate_latent_converge四种py_method与数值收敛test_estimate_noise_matricesCV 估计的噪声矩阵与真实噪声矩阵误差小于 0.1。此外count还被 tests/test_classification.py、tests/test_dataset.py、tests/test_multiannotator.py、tests/test_outlier.py、tests/test_rank.py 广泛导入使用印证了它在整个库中的基础地位。使用注意事项小结务必使用样本外概率所有依赖pred_probs的函数都假设概率来自交叉验证或独立验证集否则过拟合会导致估计失真数据量充足时建议cv_n_folds3以上。小类别数场景数据类别少于 4 个时num_label_issues优先选择off_diagonal_calibrated。多标签格式multi_labelTrue时labels必须为list各矩阵为(K, 2, 2)one-vs-rest 形状。高级阈值参数thresholds默认自动计算即可仅在需要精细控制置信判定边界时手动传入。estimate_latent与 CV 系列不支持多标签多标签请走multi_labelTrue的compute_confident_joint/estimate_joint/num_label_issues分支。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考