cleanlab 自定义 IssueManager 开发指南：为 Datalab 扩展专属数据质量检查

cleanlab 自定义 IssueManager 开发指南为 Datalab 扩展专属数据质量检查【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab本指南以 cleanlab 官方文档 custom_issue_manager.rst 为主线系统讲解如何编写自己的IssueManager问题检测器并将其注册到Datalab中与内置的 label、outlier、near_duplicate 等问题类型一起运行。读完本文你将掌握IssueManager的抽象接口约定、三类实现层级基础 / 中级 / 高级、运行时注册机制以及如何通过Datalab.find_issues()与Datalab.report()让自定义检查结果进入完整的数据质量报告。前置准备安装依赖与构造示例数据Datalab及其IssueManager框架位于 cleanlab 的可选依赖datalab扩展中使用前需要安装该扩展见 optional_dependencies.rst$ pip install cleanlab[datalab]然后导入所需模块并构造一份用于演示的哑数据集20 条带文本与二分类标签的记录import numpy as np import pandas as pd from cleanlab import IssueManager # Create a dummy dataset N 20 data pd.DataFrame( { text: [fexample {i} for i in range(N)], label: np.random.randint(0, 2, N), }, )认识 IssueManager 抽象基类自定义 IssueManager 的核心是继承抽象基类IssueManager定义于 issue_manager.py。该基类通过IssueManagerMeta元类在类创建阶段强制执行两条契约必须定义issue_name类变量如label、duplicate、outlier否则抛出TypeError自动生成issue_score_key其值恒为f{issue_name}_score例如issue_name basic时issue_score_key自动成为basic_score无需手动定义。每个IssueManager实例在初始化时获得三个与Datalab交互的核心属性issue_manager.py属性类型职责self.datalabDatalab关联的数据实验室实例通过self.datalab.data访问被检查的数据集self.issuespd.DataFrame逐样本检查结果布尔列is_{issue_name}_issue 分数列{issue_name}_scoreself.summarypd.DataFrame数据集整体健康度汇总含issue_type与score两列self.infodict关于该问题的补充信息如统计量、阈值、中间计算结果供报告展示基类还提供了若干重要的类级约定description一段说明该 IssueManager 处理何种问题的文本默认空字符串verbosity_levels一个Dict[int, List[str]]声明每个 verbosity 级别下应把info中的哪些键打印到报告里。元类会校验该字典的每个值必须是字符串列表issue_manager.py默认值形如{0: [], 1: [], 2: [], 3: []}make_summary(score)类方法用于构造summary数据帧且强制要求分数必须在[0, 1]区间内否则抛出ValueErrorissue_manager.py。测试 test_issue_manager.py 验证了0、0.5、1可正常通过而-0.3、1.5、nan、inf均会被拒绝。另外抽象方法find_issues(self, *args, **kwargs)必须实现其职责是计算issues与summary两个数据帧collect_info()则负责生成info字典基类会在find_issues设置好前两个属性后调用它issue_manager.py。注册自定义 IssueManager要让自定义检测器被Datalab.find_issues()识别必须先将其注册进全局REGISTRY。注册接口为register函数issue_manager_factory.py支持两种用法。方式一运行时函数调用注册默认任务为classificationfrom cleanlab.datalab.internal.issue_manager_factory import register register(MyIssueManager) # Defaults to taskclassification # register(MyIssueManagerForRegression, taskregression) # Alternative for regression tasks方式二作为类装饰器目前仅适用于分类任务register class MyIssueManager(IssueManager): ...注册背后的数据结构是REGISTRYissue_manager_factory.py一个以Task为外层键、以issue_name为内层键的字典。分类任务默认注册了outlier、label、near_duplicate、non_iid、class_imbalance、underperforming_group、data_valuation、null等内置检测器回归任务与多标签任务各有自己的注册表。register内部会校验传入类必须是IssueManager的子类否则抛ValueErrortask必须是Task.from_str可解析的合法任务字符串如classification、regression若目标issue_name已存在会打印覆盖警告Warning: Overwriting existing issue manager ...测试 test_issue_manager.py 对同名覆盖与跨任务注册均有断言。基础 Issue Check最小可用实现创建一个基础 IssueManager只需继承IssueManager、设置issue_name并实现find_issues。该方法应为数据集中每个样本输出一个布尔标记是否属于该问题与一个量化分数样本在该问题维度上的质量高低class Basic(IssueManager): # Assign a name to the issue issue_name basic def find_issues(self, **kwargs) - None: # Compute scores for each example scores np.random.rand(len(self.datalab.data)) # Construct a dataframe where examples are marked for issues # and the score for each example is included. self.issues pd.DataFrame( { fis_{self.issue_name}_issue : scores 0.1, self.issue_score_key : scores, }, ) # Score the dataset as a whole based on this issue type self.summary self.make_summary(score scores.mean())实现要点find_issues通过self.datalab.data读取数据集行数保证输出与样本一一对应issues必须包含is_basic_issue与basic_score两列后者正是元类自动注入的issue_score_keysummary用基类的make_summary构造分数取全体样本的均值——分数越低代表该问题越严重对应报告中的Note: A lower score indicates a more severe issue说明。中级 Issue Check携带info与verbosity_levels中级实现在前者基础上额外填充info字典并可通过verbosity_levels控制哪些信息进入Datalab.report()的报告内容还可为description赋值让报告输出关于该问题的说明文字class Intermediate(IssueManager): issue_name intermediate # Add a dictionary of information to include in the report verbosity_levels { 0: [], 1: [std], 2: [raw_scores], } # Add a description of the issue description Intermediate issues are a bit more involved than basic issues. def find_issues(self, *, intermediate_arg: int, **kwargs) - None: N len(self.datalab.data) raw_scores np.random.rand(N) std raw_scores.std() threshold min(0, raw_scores.mean() - std) sin_filter np.sin(intermediate_arg * np.arange(N) / N) kernel sin_filter ** 2 scores kernel * raw_scores self.issues pd.DataFrame( { fis_{self.issue_name}_issue : scores threshold, self.issue_score_key : scores, }, ) self.summary self.make_summary(score scores.mean()) # Useful information that will be available in the Datalab instance self.info { std: std, raw_scores: raw_scores, kernel: kernel, }值得注意的细节find_issues的签名是(*, intermediate_arg: int, **kwargs)——额外的关键字参数intermediate_arg由用户在调用find_issues(issue_types...)时传入见下文这印证了issue_types的值本质上是传给对应 IssueManager 的构造/调用参数info中的键与verbosity_levels关联verbosity1时报告展示stdverbosity2时额外展示raw_scores报告渲染逻辑见IssueManager.report()issue_manager.py其中对数组会截断为最多 4 个元素展示对 DataFrame 最多展示 5 行statistics键会被跳过description会在报告中以About this issue:段落呈现。高级 Issue Check区分局部问题与全局问题实际数据中的问题可以分成两类理解这一区分有助于设计更合理的自定义检测器局部问题local issue影响数据集中的个别数据点可通过Datalab.issues数据帧精确定位是哪些样本出了问题全局问题global issue影响整个数据集难以归因到单个样本很难说某个样本有问题而另一个没有。即便如此官方建议只要可能仍然尽量为每个样本给出分数与布尔标记NonIIDIssueManager非独立同分布检测器实现于 noniid.py就是这样一个全局问题 逐样本打分的范例——它通过置换检验判断数据分布是否满足 IID 假设同时为每个样本计算得分。另外有一条与报告展示相关的硬性规则全局问题必须保证其issue_summary中的num_issues大于 0否则默认不会出现在Datalab.report()中。与 Datalab 集成注册、检测与报告完成实现后即可把自定义检测器与内置检测器一同接入Datalab工作流from cleanlab.datalab.internal.issue_manager_factory import register from cleanlab import Datalab # Register the issue manager for issue_manager in [Basic, Intermediate]: register(issue_manager) # Instantiate a datalab instance datalab Datalab(data, label_namelabel) # Run the issue check issue_types {basic: {}, intermediate: {intermediate_arg: 2}} datalab.find_issues(issue_typesissue_types) # Print report datalab.report(verbosity0)issue_types是一个字典的字典外层键是issue_name内层字典是传给该 IssueManager 的参数find_issues的签名datalab.py 与 issue_finder.py 均对此有说明。因此这里intermediate: {intermediate_arg: 2}就是把intermediate_arg2传入Intermediate.find_issues。报告输出形如Here is a summary of the different kinds of issues found in the data: issue_type score num_issues basic 0.477762 2 intermediate 0.286455 0 (Note: A lower score indicates a more severe issue across all examples in the dataset.) ------------------------------------------- basic issues ------------------------------------------- Number of examples with this issue: 2 Overall dataset quality in terms of this issue: 0.4778 Examples representing most severe instances of this issue: is_basic_issue basic_score 13 True 0.003042 8 True 0.058117 11 False 0.121908 15 False 0.169312 17 False 0.229044 --------------------------------------- intermediate issues ---------------------------------------- About this issue: Intermediate issues are a bit more involved than basic issues. Number of examples with this issue: 0 Overall dataset quality in terms of this issue: 0.2865 Examples representing most severe instances of this issue: is_intermediate_issue intermediate_score kernel 0 False 0.000000 0.0 1 False 0.007059 0.009967 3 False 0.010995 0.087332 2 False 0.016296 0.03947 11 False 0.019459 0.794251报告按score升序展示最严重的若干样本默认 5 个由report(num_examples...)控制见 datalab.py。注意intermediate问题因num_issues 0未被默认报告只有当我们把它的num_issues提升到大于 0如调整阈值才会在默认报告中出现——这正是前面全局问题必须num_issues 0规则的体现。底层原理IssueFinder 如何调度自定义检测器Datalab.find_issues()内部委托给IssueFinder类issue_finder.py其工作流程为参数解析根据任务类型classification / regression / multilabel选择对应的_resolve_required_args_*策略把用户提供的pred_probs、features、knn_graph分发到各个 IssueManager 需要的参数上_CLASSIFICATION_ARGS_DICT等映射见 issue_finder.py类型筛选通过_IssueManagerFactory.from_list依据REGISTRY实例化所有命中的 IssueManager未注册的类型会抛出Invalid issue type: ... for task ...对应测试 test_datalab.py执行与容错逐个调用issue_manager.find_issues(**arg_dict)失败的管理器会被收集并打印Failed to check for these issue types: ...不影响其余检查结果收集通过data_issues.collect_statistics与collect_issues_from_issue_manager把issues、summary、info汇总到Datalab.data_issues。这意味着你的自定义 IssueManager 只要满足注册 实现find_issues两个条件就能自动享受与内置检测器完全一致的调度、容错与报告管线。通过测试用例验证自定义检测器行为仓库测试为我们提供了可复用的参考实现。tests/datalab/conftest.py中的custom_issue_managerfixtureconftest.py定义了一个接收自定义参数custom_argument的检测器按索引是否等于参数值来标记问题样本并计算分数。tests/datalab/datalab/test_datalab.pytest_datalab.py则验证了注册后调用lab.find_issues(issue_types{custom_issue: {}})lab.issues会精确生成预期的is_custom_issue_issue布尔列与custom_issue_score分数列传入自定义参数{custom_issue: {custom_argument: 3}}会改变检测结果证明issue_types的参数透传机制有效测试结束时从REGISTRY中弹出该类型以清理环境。这套测试直接对应了官方文档中的中级 Issue Check模式可作为你编写自己的find_issues时的验收模板。结语本文从零到一走完了 cleanlab 自定义 IssueManager 的完整生命周期继承抽象基类、满足元类契约issue_name必填、issue_score_key自动生成、实现find_issues并构造issues/summary/info、通过register挂入REGISTRY、最后由Datalab统一调度并输出报告。掌握这一框架后你既可以为特定业务场景定制局部问题检测如格式违规、字段缺失也可以参照NonIIDIssueManager设计全局性问题检测让 cleanlab 的数据质量审计能力无限贴近你的数据形态。如需进一步阅读可继续深入 IssueManager 源码、注册机制实现、IssueFinder 调度逻辑以及各内置检测器的实现如 noniid.py它们共同构成了 cleanlab Datalab 数据质量引擎的可扩展内核。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考