Cleanlab Token Classification 结果展示与问题汇总display_issues、common_label_issues 与 filter_by_token 实战指南【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab本文聚焦 cleanlab 数据质量工具链中面向词级token-level标注分类任务的结果呈现环节系统讲解cleanlab.token_classification.summary模块的三大核心函数用于在原始句子中高亮展示可疑 token 的display_issues、用于统计全数据集最常出错的词并返回结构化DataFrame的common_label_issues以及用于按指定词快速筛选问题的filter_by_token。读完本文你将掌握如何在完成标签质量问题检测filter与质量打分排序rank之后将检测结果以人类可读、可量化、可检索的形式落地从而系统化定位标注员系统性误标的高频词支撑 NER、词性标注等文本任务的清洗决策。一、summary 模块在 token 分类数据质量流程中的定位cleanlab 对 token 分类如命名实体识别 NER、词性标注 POS提供了一整套检测—排序—汇总流水线summary模块处于链路的末端展示环节filter.find_label_issues基于 Confident Learning 估计哪些 token 的标签最可能是错误的返回形如(i, j)的元组列表其中i为句子索引、j为该句子内 token 索引rank.get_label_quality_scores为每个 token 与每句话计算 0~1 的质量分issues_from_scores可按阈值把低分 token 转成同样的(i, j)问题列表summary模块接收上述两类函数输出的issues列表负责可视化、统计与筛选。从模块 docstring 可见其定位十分明确Methods to display sentences and their label issues in a token classification dataset (text data), as well as summarize the types of issues identified.——即展示带问题的句子、并汇总已识别的问题类型。因此只要你的数据满足以下输入约定即可直接使用本模块issues(i, j)元组列表表示第i句话的第j个 token 存在标签问题与find_label_issues/issues_from_scores输出格式完全一致tokens嵌套列表tokens[i]是组成第i句话的 token单词列表labels可选与tokens同构的嵌套标签列表类别须为0, 1, ..., K-1整数pred_probs可选列表pred_probs[i]为形状(T, K)的数组T为该句 token 数、K为类别数列顺序对应类别0, 1, ..., K-1。该输入约定在 filter.py 与 rank.py 的 docstring 中完全一致保证三个模块可以无缝串联。二、display_issues在原始句子中高亮问题 tokendisplay_issues(issues, tokens, *, labelsNone, pred_probsNone, exclude[], class_namesNone, top20)是问题可视化的核心入口。它会在控制台逐条打印问题 token 所在的完整句子并用红色高亮该 token同时视传入参数附带给定标签与模型预测标签。2.1 参数说明参数类型默认值含义issueslist必填(i, j)元组列表来自find_label_issues或issues_from_scorestokensList[List[str]]必填嵌套 token 列表tokens[i]为第i句话labelsOptional[list]None嵌套给定标签列表提供后打印问题 token 的给定标签pred_probsOptional[list]None模型预测概率列表提供后打印问题 token 的预测标签取argmaxexcludeList[Tuple[int, int]][]需要忽略的给定/预测标签互换组合如[(0, 1), (1, 0)]表示忽略在类 0 与类 1 之间被互换的 tokenclass_namesOptional[List[str]]None长度为K的类别名字列表提供后以字符串显示标签否则显示整数索引topint20最多打印的问题数量两个容易忽视的行为细节均有源码佐证见 summary.pytop会被钳制实现中执行top min(top, len(issues))即使传入大于问题总数的top也只会打印全部问题不会报错未提供class_names时的提示只要提供了labels或pred_probs但缺少class_names会先打印一行提示告知类别将以整数索引显示并建议指定class_names查看类别字符串名exclude仅在同时提供labels与pred_probs时生效因为互换判断依赖(given, prediction)二元组缺少任一方时该参数不会参与过滤。2.2 输出格式与示例以模块 docstring 中的官方示例为例from cleanlab.token_classification.summary import display_issues issues [(2, 0), (0, 1)] tokens [ [A, ?weird, sentence], [A, valid, sentence], [An, sentence, with, a, typo], ] display_issues(issues, tokens)输出为Sentence index: 2, Token index: 0 Token: An ---- An sentence with a typo Sentence index: 0, Token index: 1 Token: ?weird ---- A ?weird sentence每条问题输出四部分信息句子索引与 token 索引定位、该 token 原文、分隔线、以及还原后的完整句子其中问题 token 在真实终端中会以红色显示。若同时传入labels与pred_probs输出会额外包含Given label: 0, predicted label according to provided pred_probs: 1仅传入其一则单独打印 Given label: 或 Predicted label according to provided pred_probs:。值得注意该函数也兼容句子级问题列表——当issues的元素不是元组而是整数句子索引时即未提供token_scores时issues_from_scores的返回形式函数会退化为打印整句Sentence issue: ...见源码中is_tuple分支summary.py。三、common_label_issues定位标注员系统性误标的高频词common_label_issues(issues, tokens, *, labelsNone, pred_probsNone, class_namesNone, top10, exclude[], verboseTrue)统计全数据集中哪些词最频繁地卷入标签问题并返回可进一步分析的pandas.DataFrame。它的价值在于发现模糊词或被标注员系统性误解的词——例如 NER 中反复被标错的实体边界词、词性标注中常被误判的多义词。3.1 返回的 DataFrame 结构返回结构取决于是否同时提供labels与pred_probs见 summary.py 与 summary.py 两分支输入条件DataFrame 列行语义排序依据仅issues与tokens[token, num_label_issues]每个词一行按该词卷入的问题总数降序同时提供labels与pred_probs[token, given_label, predicted_label, num_label_issues]每个词 × 给定/预测标签互换组合一行按该互换类型的问题数降序当提供了class_names时given_label/predicted_label列显示类别字符串名否则显示整数索引。若提供class_names但缺少labels或pred_probs会先打印提示信息。3.2 参数细节top默认10最多统计并打印多少词。源码通过np.argsort(freq)[::-1][:top]取问题数最高的前top个词summary.pyexclude与display_issues同格式的互换对列表忽略特定类型互换仅在同时提供labels与pred_probs时生效summary.pyverbose默认True控制是否在打印每个词的同时逐行输出其最频繁的标签互换明细格式为labeled as class X but predicted to actually be class Y N timessummary.py。3.3 示例from cleanlab.token_classification.summary import common_label_issues issues [(2, 0), (0, 1)] tokens [ [A, ?weird, sentence], [A, valid, sentence], [An, sentence, with, a, typo], ] df common_label_issues(issues, tokens)控制台输出Token ?weird is potentially mislabeled 1 times throughout the dataset Token An is potentially mislabeled 1 times throughout the dataset返回的dftoken num_label_issues 0 An 1 1 ?weird 1当数据规模较大时返回的DataFrame可以直接交给 pandas 进行二次分析如按num_label_issues阈值过滤、与词频表关联、导出清洗清单这是该函数相比纯打印输出更具工程价值的地方。测试用例 tests/test_token_classification.py 验证了无论是否传入labels/pred_probs/class_names返回对象均为pandas.DataFrame且必含token与num_label_issues两列传入完整参数时额外包含given_label、predicted_label两列。四、filter_by_token按词快速筛选问题子集filter_by_token(token, issues, tokens)从完整问题列表中筛出涉及指定词的所有问题返回与输入issues相同格式的子列表。典型应用场景在common_label_issues中发现某高频问题词后立刻取回它所有的(i, j)定位再交给display_issues逐句复查上下文。官方示例from cleanlab.token_classification.summary import filter_by_token token ?weird issues [(2, 0), (0, 1)] tokens [ [A, ?weird, sentence], [A, valid, sentence], [An, sentence, with, a, typo], ] filter_by_token(token, issues, tokens) # 输出: [(0, 1)]实现细节summary.py大小写不敏感匹配判断条件为token.lower() tokens[i][j].lower()因此cleanlab也能匹配到Cleanlab不修改原始列表返回的是新构建的returned_issues列表原issues不受影响保持原排序结果顺序与输入issues中的出现顺序一致不会重排。测试用例 tests/test_token_classification.py 给出了(Hello, [])与(#I, [(1, 0)])两组验证确认匹配与空结果两种情形均符合预期。五、底层实现原理句子还原与红色高亮display_issues展示效果背后依赖cleanlab.internal.token_classification_utils中的两个内部函数理解它们有助于预判展示效果5.1 get_sentence从 token 列表还原可读句子get_sentence(words)将分词后的 token 列表拼接为完整句子token_classification_utils.py其处理规则为普通单词前加一个空格拼接标点符号string.punctuation前不加空格但-与(两个特例除外保持前后空格最后执行 .replace与( .replace微调并strip()去除首尾空白。例如[This, is, a, sentence, .]还原为This is a sentence.。测试用例 tests/test_token_classification.py 还验证了连字符[Heading, -, Title] → Heading - Title与括号[Some, reason, (, Explanation, )] → Some reason (Explanation)两种特殊情形。5.2 color_sentence 与 _replace_sentence终端红色高亮color_sentence(sentence, word)借助termcolor.colored将句子中所有匹配的word染成红色并输出 ANSI 转义序列token_classification_utils.py。其核心替换逻辑在_replace_sentencetoken_classification_utils.py中先用正则\b{word}\b做整词边界匹配re.escape保证(、?等特殊字符被安全转义避免把I误染进If若正则一次都没匹配上number_of_substitions 0退化为朴素的sentence.replace(word, new_word)兜底。tests/test_token_classification.py 通过十组参数化用例含ignore_subwords、case_sensitive、multi-token_match、正则特殊字符转义等边界场景完整覆盖了这两种替换策略。六、完整工作流从原始数据到问题汇总报告将上述能力串联起来可以得到一个端到端的 token 分类数据质量检查流程import numpy as np from cleanlab.token_classification.filter import find_label_issues from cleanlab.token_classification.summary import ( display_issues, common_label_issues, filter_by_token, ) # 假设已从模型取得逐 token 的预测概率 labels [[0, 0, 1], [0, 1]] # 每句一个标签列表 pred_probs [ np.array([[0.9, 0.1], [0.7, 0.3], [0.05, 0.95]]), np.array([[0.8, 0.2], [0.8, 0.2]]), ] tokens [[Cleanlab, is, great], [I, agree]] class_names [O, ORG] # 示例类别名 # 第 1 步Confident Learning 检测标签问题 issues find_label_issues(labels, pred_probs) # 第 2 步逐句高亮查看问题 token display_issues(issues, tokens, labelslabels, pred_probspred_probs, class_namesclass_names, top20) # 第 3 步统计全数据集最常出错的词含标签互换明细 df common_label_issues(issues, tokens, labelslabels, pred_probspred_probs, class_namesclass_names, top10, verboseTrue) # 第 4 步针对特定高频词复查全部上下文 subset filter_by_token(Cleanlab, issues, tokens) display_issues(subset, tokens, labelslabels, pred_probspred_probs)关于第 1 步有两点补充见 filter.py 实现find_label_issues内部会把嵌套的 token 标签展平后调用通用 cleanlab.filter.find_label_issues再通过句子长度与(i, j)坐标的双向映射还原为元组列表若数据规模很大可传low_memoryTrue走find_label_issues_batched分批路径此时部分kwargs参数会被忽略并给出警告。另外若不使用 Confident Learning也可改用rank.get_label_quality_scores打分后用rank.issues_from_scores按阈值默认threshold0.1得到问题列表再接入上述第 2~4 步rank.py 中明确说明这一路径是为将最严重误标样本转换为与summary兼容的格式而设计的。七、使用注意事项小结输入格式必须对齐issues必须为(i, j)元组列表tokens[i]的第j个元素必须存在否则展示或统计会出现索引错误pred_probs[i]的行数须与tokens[i]的 token 数一致标签需为 0 起始整数labels与pred_probs的列顺序均按类别0, 1, ..., K-1约定class_names长度须为Kexclude的前提条件互换过滤依赖给定标签 预测标签二元组仅在同时传入labels与pred_probs时生效输出依赖终端支持红色高亮基于 ANSI 颜色码在支持彩色的终端中可见函数本身是纯打印/纯 DataFrame 返回不修改任何输入数据展示数量可控display_issues的top与common_label_issues的top分别控制打印/统计上限建议在大型数据集上先用common_label_issues定位高频问题词再定向复查避免被海量问题输出淹没。通过display_issues、common_label_issues与filter_by_token三件套cleanlab 让 token 分类任务的标签质量审查从拿到一堆索引变成直接看到句子、看到高频错误词、看到具体的标签互换模式配合 tests/test_token_classification.py 中的行为契约可以在任何基于 token 标注的文本任务NER、POS、槽位填充等中快速落地数据清洗闭环。【免费下载链接】cleanlabCleanlabs open-source library is the standard>项目地址: https://gitcode.com/GitHub_Trending/cl/cleanlab创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考