s1 项目中 lm-evaluation-harness 的基准数据去污染(Decontamination)完整指南:N-gram 重叠检测与 Pile 训练集清洗流水线

原创2026-10-08 14:32:56169 阅读
文章标签:大模型推理模型微调模型推理服务

s1 项目中 lm-evaluation-harness 的基准数据去污染(Decontamination)完整指南:N-gram 重叠检测与 Pile 训练集清洗流水线

导读

本文是围绕本仓库(s1: Simple test-time scaling)所集成的 lm-evaluation-harness 中「去污染(Decontamination)」机制的完整技术指南。它讲解如何判断一个下游评测基准(如 sciq、mmlu 等)的测试样本是否与模型训练语料(The Pile)发生重叠(即数据泄漏),如何在无法重新过滤训练集时量化污染影响、并产出「干净版」评测分数,以及如何从头生成 Pile 的 13-gram 索引并用于评测。读完本文,你将掌握:去污染的判定原理(源自 GPT-3 论文附录 C)、lm_eval/decontamination/ 模块的源码级算法、任务 YAML 中 should_decontaminate 与 doc_to_decontamination_query 的配置方法,以及 scripts/clean_training_data 三步流水线的完整命令行操作。

背景:为什么需要去污染

下游评测用于检验模型的泛化能力,但当测试集数据同时出现在训练集中时,评测结果就会失真,这种现象称为泄漏(leakage)或污染(contamination)。最理想的解决手段是在训练之前就对训练集做过滤(把测试集相关文本剔除),这是第一道防线。

然而,这种方式并不总是可行:例如一个新发布的基准,或一个在模型训练前未被考虑到的基准,都无法在训练阶段被预先过滤。此时就需要检测污染——找出被污染的测试样本,并产出一份「干净版」的基准用于重新评估,从而量化污染对模型分数的影响。

本仓库中 lm-evaluation-harness 的去污染判定基础,来自论文 Language Models are Few-Shot Learners(GPT-3 论文)的附录 C:OpenAI 将某个测试文档定义为「受污染」,当且仅当它与任意训练文档存在 N-gram 重叠。OpenAI 依据数据集不同在 N=8 到 13 之间取值,而本仓库的实现为简单起见统一使用 N=13。

实现总览:从检测到干净版评分

去污染的检测逻辑位于 lm_eval/decontamination/decontaminate.py,配套支撑代码位于 lm_eval/decontamination/(含 janitor.py 与 archiver.py)。

decontaminate.py 的核心函数 get_train_overlap() 完成三件事:

  1. 构建词典:为每个评测任务构建「所有 n-gram → 对应文档 id 集合」的反向索引(lookup)。该步骤先逐任务构建 {ngram: set(doc_ids)},再合并为全局索引 {ngram: [(task_name, task_set, doc_ids), ...]},这样同一 n-gram 匹配时可以同时标记多个任务/数据子集的文档。
  2. 扫描训练集 n-gram 文件:通过 ZStdTextReader 流式读取经过排序、zstd 压缩的训练集 n-gram 桶文件(*.bkt.txt.sorted.zst),逐行解析出 (ngram, document_id)。
  3. 标记污染:若训练集中的 n-gram 命中评测任务的 lookup,则将该 n-gram 对应的所有评测文档 id 记入 duplicates 字典,最终返回 {task_name: set(contaminated_doc_ids)}。

值得注意的实现细节(均有源码依据):

  • 去重优化:由于训练集 n-gram 已排序,扫描时相同 n-gram 只匹配一次(if ngram != current_ngram),命中后立即 del merged_lookup<a href="https://link.gitcode.com/i/50706a359baffb0615edb3d7795e301c" target="_blank">ngram],避免重复匹配,提升扫描速度(源码见 [decontaminate.py)。
  • 结果缓存:每个「任务 + 数据子集 + n-gram 大小 + limit」组合的 lookup 与 overlap 结果都会被 pickle 缓存到 data/{task_name}/ 目录(如 {task_set}_{n}grams_limit{limit}.lookup 与 .overlaps),重复评测时直接加载,无需重算(decontaminate.py)。
  • 运行统计:扫描过程会输出 Total Ngrams、Unique Ngrams、Unique Matching、Unique Non Matching、匹配到的 n-gram 明文列表及读取速度(MB/s),便于人工核查命中质量。

干净版评测结果的产出

检测出受污染文档集合后,lm_eval/evaluator.py 可以通过剔除受污染文档的评测结果来产出该基准的干净版:每个指标的结果中会额外展示一个带 decontaminate 后缀的分数版本。通过对比原始分数与 decontaminate 后缀分数,即可量化测试集泄漏对模型得分的影响幅度。

该功能默认对所有新任务关闭(TaskConfig.should_decontaminate 默认值为 False,见 task.py)。要为某个任务开启去污染,需要在任务配置中覆写 should_decontaminate 与 doc_to_decontamination_query 两个字段,详见下文及 task_guide.md。

文本规范化与 Janitor:去污染的质量保证

污染检测的匹配质量依赖于对文本的统一规范化处理。核心实现是 janitor.py 中的 Janitor 类,其设计目标是让 n-gram 匹配忽略大小写与标点:

  • normalize_string() 通过 str.maketrans 将大小写字母统一转为小写,并删除 string.punctuation 中的全部标点字符(janitor.py)。
  • word_ngrams() 按空白切分单词后生成连续的 n 元词组(janitor.py),其底层的 form_ngrams 借鉴自 NLTK 源码。

Janitor 同时提供纯 Python 与 C++ 双实现:加载时优先尝试导入 C++ 扩展模块 janitor_util(由 janitor_util.cpp 编译),失败则回退到 Python 模式并打印警告(janitor.py)。C++ 版本通过 pybind11 暴露 clean_ngram 与 clean_ngram_with_indices 两个函数,后者还会记录每个 n-gram 在原字符串中的起止索引,供训练集清洗(Janitor 清理)使用。

Janitor 还提供了在训练集侧移除污染文本的能力(register_contaminant + clean),其算法与参数在 scripts/clean_training_data/README.md 中有完整说明:

  1. 收集所有要从训练数据中移除的污染文本;
  2. 在训练数据中查找与污染文本重叠的 N-gram(忽略大小写、标点,按空白分词);
  3. 命中 N-gram 的子串连同其前后 window_to_remove 个字符的窗口一并移除,将训练文档切分成若干片段;
  4. 长度小于 minimum_slice_length 的片段被丢弃;
  5. 被切分出的片段数量超过 too_dirty_cutoff 的文档被视为整体污染,直接删除。

OpenAI 使用的参数为:ngram_n = 13、window_to_remove = 200、minimum_slice_length = 200、too_dirty_cutoff = 10,与 Janitor 构造函数 的默认值一致。如需启用 C++ 加速,可先 pip install pybind11,再按 README.md 中的命令编译 janitor_util.cpp(Linux 下若编译器未链接 Python,需将产物重命名为 janitor_util.so 并在代码中 sys.path.append 其路径)。

在评测任务中启用去污染

去污染默认关闭,开启需要两步配置。两个字段定义在 TaskConfig 中(task.py):

  • should_decontaminate: true:布尔开关,置为 true 时该任务的文档会参与去污染检测(读取逻辑见 task.py)。
  • doc_to_decontamination_query:指定「拿文档的哪个字段去做 n-gram 检测」。支持三种形式:不配置时默认回退到 doc_to_text 的提示文本;配置为数据集字段名时直接取 doc<a href="https://link.gitcode.com/i/6fd5ae0c90e91a06a4b5c9e5fe8ed06b" target="_blank">field];配置为可调用对象时调用之;也支持使用 {{...}} 模板表达式(见 [task.py)。

仓库中已有多个真实任务启用了该功能,可作配置范例:

配置完成后,运行标准评测命令即可:

python -m lm_eval \
    --model gpt2 \
    --device 0 \
    --tasks sciq

运行前提是「提供给去污染流程的目录中包含 Pile 的 n-gram 文件与 info.json」(该产物由下文的 Pile N-gram Generation 流水线生成)。info.json 中记录 ngram_size(即 13),get_train_overlap() 会先读取它来确定 n-gram 大小(decontaminate.py)。

Pile N-gram Generation:构建训练集 n-gram 索引的完整流水线

去污染的前提是先拥有一份「训练集(The Pile)全量 n-gram 索引」。相关脚本位于 scripts/clean_training_data,它们也会从 lm_eval/decontamination/ 导入 Janitor 与归档读写工具。完整流程如下。

准备工作

  1. git clone 本仓库(https://gitcode.com/gh_mirrors/s1/s1)或单独克隆 lm-evaluation-harness;
  2. pip install -r requirements.txt 安装依赖;
  3. 从 The Eye 站点下载 The Pile 的训练分片(https://the-eye.eu/public/AI/pile/train/);
  4. 将 Pile 文件放置于仓库下的 pile 目录(或创建符号链接)。

注意:generate_13_grams.py 启动时会检查 pile_statistics.json(内含 Pile 的 Document Count 与每个文件的 File Start Offsets),仓库根目录已提供 pile_statistics.json,也可通过 investigate_pile.py 自行统计生成。

步骤一:生成 13-gram 并分桶(约 4 天)

export PYTHONHASHSEED=0
python -m scripts/clean_training_data/generate_13_grams \
       -dir path/to/working/directory \
       -n 13 \
       -buckets 500

该脚本(generate_13_grams.py)遍历 Pile 全部文档,使用 Janitor.normalize_string 规范化文本后提取 13-gram,并按 hash(ngram) % bucket_count 分桶写入 output/ngrams_{i}.bkt.txt。每个 n-gram 会附带其 Pile 文档 id(形如 ngram document_id),以便后续过滤「出现在 10 个以上唯一文档中的通用 n-gram」。

三个关键参数:

参数 默认值 说明
-dir / --working_directory 当前目录 存放 Pile 分片的目录,output 子目录在其下生成
-n / --n_value 13 n-gram 的 n 值
-buckets / --bucket_count 500 分桶数量,用于支撑并行处理

脚本内置了两套可恢复机制,值得在生产环境复用:

  • checkpoint:每处理 1000 个文档保存一次进度(pile_offset.ckpt)与各桶文件偏移(bucket_offsets.ckpt),中断后重启会从上次 checkpoint 继续,桶文件在恢复点截断;
  • SIGINT 优雅退出:注册了 Ctrl-C 处理器,仅在 checkpoint 保存点允许终止,保证数据一致性。

同时,脚本在入口处强制校验 PYTHONHASHSEED=0(否则直接 sys.exit())。这是为了固定 Python 字符串哈希种子,保证 hash(ngram) % bucket_count 的分桶结果在多次运行间可复现——这样即使任务中途停止再重启,或在不同机器上做分片扫描后合并桶,也不会产生分桶不一致。官方经验是全程约需 4 天;若想加速,可让多个实例各自扫描部分 Pile 分片,最后合并对应桶。

脚本结束时会生成 info.json,记录 {"title": "dataset ngrams", "ngram_size": 13}——这是后续评测去污染流程读取的元数据(generate_13_grams.py)。

步骤二:排序 13-gram 桶(约 5 天)

python -m scripts/clean_training_data/sort_13_gram_buckets \
       -dir path/to/working/directory/output

sort_13_gram_buckets.py 对每个桶文件执行 GNU sort(sort {bucket}.bkt.txt > {bucket}.bkt.txt.sorted),排序后删除未排序的桶。排序的重要性在于:get_train_overlap() 扫描时依赖「相同 n-gram 连续出现」来做去重匹配,而 process_sorted_buckets.py 也依赖有序输入来统计「每个 n-gram 出现在多少个唯一文档中」。官方经验约需 5 天;可以通过把文件分发到多台机器分别排序后再汇总来加速。

步骤三:压缩并打包(约数小时)

python -m scripts/clean_training_data/compress_and_package \
       -dir path/to/working/directory \
       -output path/to/final/directory \
       -procs 8

compress_and_package.py 用多进程(-procs 控制进程数,默认 8)对每个排序后的桶执行 zstd 压缩,得到 ngrams_{x}.bkt.txt.sorted.zst,移入最终输出目录,并将 info.json 一并复制过去。最终产物即「提供给去污染流程的目录」:info.json + 一批 *.sorted.zst 文件,与 get_train_overlap() 中 glob.glob(os.path.join(ngrams_path, "*.sorted.zst")) 的扫描逻辑一一对应(decontaminate.py)。

可选中间步骤:排序之后、压缩之前,可通过 process_sorted_buckets.py(-dir / -move / -procs,默认 4 进程)流式统计每个 n-gram 的唯一文档数,并将「出现于超过 10 个唯一文档」的 n-gram 单独输出。这一步用于识别过于通用的 n-gram(更可能是自然语言中的常见搭配而非真正的泄漏证据),进一步收紧匹配精度。

流水线小结

阶段 命令 产物 官方耗时参考
1. 生成分桶 generate_13_grams -n 13 -buckets 500 output/ngrams_{i}.bkt.txt + info.json 约 4 天
2. 排序 sort_13_gram_buckets *.bkt.txt.sorted 约 5 天
3. 压缩打包 compress_and_package -procs 8 *.bkt.txt.sorted.zst + info.json 约数小时

三步的耗时都来自官方文档经验值,实际时长取决于机器性能与 Pile 分片数量;官方明确指出三步均可通过「多实例/多机器并行」水平扩展来压缩时间。

端到端工作流与结果解读

把整个体系串起来,一次完整的去污染评测流程是:

  1. (一次性)按上述三步生成 Pile 13-gram 索引目录;
  2. 在目标任务 YAML 中设置 should_decontaminate: true 与 doc_to_decontamination_query;
  3. 运行 python -m lm_eval --model ... --tasks ...;
  4. get_train_overlap() 构建任务 n-gram lookup → 扫描训练集 n-gram 桶 → 得到受污染文档集合;
  5. evaluator 剔除受污染文档后重算指标,输出带 decontaminate 后缀的干净版分数。

从源码结构可以推断,lm_eval/filters/decontamination.py 中注册了名为 decontaminate 的 DecontaminationFilter(name = "track_decontamination"),负责在结果层面区分「无污染子集」与「仅污染子集」,是评测流水线中挂载去污染后处理的一环。

实战建议与注意事项

  • 匹配强度与误报:N=13 是 OpenAI 区间的上限,较长的 n-gram 重叠更可能是真实泄漏而非巧合;但固定 N 也意味着对不同数据集没有针对性调整空间,长文本基准可能漏检较短的重叠片段。
  • 查询内容的选择:doc_to_decontamination_query 的字段选择直接影响检测覆盖面——只检测问题文本(如 afrimmlu 的 Question: {{question}})会比检测完整文档更保守,应根据基准的「可能泄漏来源」(如论文、网页正文)决定检测粒度。
  • 规范化一致性:评测侧与训练集生成侧必须使用同一套规范化规则(忽略大小写、删除标点、按空白分词),否则两侧 n-gram 无法对齐。两侧均复用 janitor.py 的同一实现,正是为此。
  • 缓存与可复现:PYTHONHASHSEED=0 与 checkpoint 机制让分桶结果可复现、可断点续跑;任务侧 lookup/overlap 缓存让重复评测免于重扫数 TB 训练集。
  • 定位:去污染解决的是「训练后评测」场景;如果模型尚未训练,优先在训练前用 Janitor.clean 直接清洗训练集(见 scripts/clean_training_data/README.md),两者互为补充而非替代。
登录后查看全文
s1