humanizer-data 是为 12B 文本重写模型 humanizer v2 准备的训练语料集，其中reference_only分片因版权限制不含原文文本。本文带你完整读懂官方重建脚本rebuild_reference_only.py：它如何按上游数据源逐条找回被扣下的原文，并用 SHA-256 校验确认取回的正是训练时用过的那份文本，帮助新手快速掌握训练数据重建的方法。

为什么 reference_only 里没有原文？

humanizer-data 把语料按许可证分成三个分片（split）：

reference_only的三套文件共约 2.8 万行，见 rewrite_sft/reference_only.jsonl、dpo/reference_only.jsonl、rl_prompts/reference_only.jsonl。每一行都保留了四个关键线索字段：

• upstream_dataset：来源数据集（如MedRAG/pubmed、OpenPipe/hacker-news）
• upstream_id：记录在来源中的定位 ID
• upstream_url：可人工打开的原始页面地址
• original_sha256/original_chars：训练所用文本的 SHA-256 哈希与字符数

所以“重建”= 拿着这些线索回到公开来源取回原文，再用哈希验证。README 中对此有明确说明，详见 README.md。

脚本总览：一条流水线，四步走

整个脚本只有约 260 行 Python，核心流程在 main() 中：

1. 读入行：从 Hugging Face 加载reference_only分片，或读入本地 jsonl
2. 路由：按upstream_dataset前缀匹配到对应的抓取器（fetcher）
3. 抓取 + 校验：取回原文，做归一化后与original_sha256比对
4. 逐行写出：输出 jsonl，每行记录抓取结果、是否哈希匹配、或错误信息

第一步：健壮的 HTTP 抓取

所有网络请求都经过 http() 封装：固定 User-Agent，最多重试 5 次，遇 429（限流）会等 45 秒，404 直接抛出。对新手来说，这是处理公开 API 时非常值得借鉴的重试写法——用指数式退避（3 * (a+1)秒）避免把上游打挂。

抓取 Hugging Face 数据集的一行数据则靠 hf_row()：调用 datasets-server 的/rowsAPI，按行号取一条。它还处理了一个坑：rows API 会截断超大单元格，遇到truncated_cells会提示你改下 parquet 文件。

行 ID 的解析在 parse_rowid()：形如default/train:3204的 ID 表示“数据集某 config 某 split 的第 N 行”（从 0 开始）。

第二步：RECIPES 路由表——一个前缀一个抓取器

这是脚本的精髓，见 RECIPES 列表：一个“(upstream_dataset 前缀, 抓取函数)”元组列表，resolve() 按顺序前缀匹配，把每行数据交给最合适的抓取器。不同来源的数据形态差异极大，脚本为它们分别写了策略：

• 通用行号索引get_rowindex()：适用于 aeslc、COIG-CQIA、imdb 等 Hugging Face 数据集，按行号直接取指定列
• Hacker News 评论get_hn()：用帖子 ID 查 Firebase API
• PubMed 摘要get_pubmed()：优先解析 MedRAG 分块文件，找不到时回退到 NCBI E-utilities
• CRS 国会报告get_crs()：先拉报告索引 CSV，再下载 HTML 并做去标签清洗
• pipermail 邮件列表get_pipermail()：按“列表|日期|主题”从 mbox 大文件中定位具体邮件，带内存缓存避免重复下载

注意脚本大量使用了模块级字典（_medrag、_small、_mbox等）做缓存：同一个上游文件只下载一次，后续行直接查内存，效率很高。

第三步：取不到的来源怎么办？manual 兜底

有些数据需要手动下载或先同意条款（Kaggle 数据、Enron 邮件归档、大型语料库等）。脚本用 manual() 生成一个会抛出NotImplementedError的抓取器，异常消息里直接写明“该怎么做”，例如：

manual('large: stream allenai/peS2o (v2) and filter by id; collect all ids first and scan once')

这样跑脚本不会中途崩溃，而是把操作指引写进输出文件，新手照着提示手动补齐即可。完全匹配不到 RECIPES 的行也会兜底为 manual，提示你打开upstream_url人工查找。

第四步：哈希校验为什么经常是 false？

校验逻辑在 main()：

• norm() 把文本转小写、压缩空白后再算 SHA-256
• 与行里的original_sha256比对，写入sha256_match字段

脚本头部的注释特别提醒：训练用的文本往往是上游记录的清洗后节选（去掉了引文回复、签名、硬换行等），所以即使取回的是正确的记录，sha256_match也可能为false。它是“确认证据”，不是“成功标准”。

实战：三条命令跑通重建

依赖只有四个（来自 脚本用法说明）：

pip install datasets requests pyarrow huggingface_hub

常用跑法：

# 重建整个 rewrite_sft 的 reference_only 分片 python scripts/rebuild_reference_only.py --config rewrite_sft --out rebuilt_sft.jsonl # 只重建某个来源（前缀匹配），并限制行数——强烈建议先这样小范围试跑 python scripts/rebuild_reference_only.py --config rewrite_sft --out rebuilt.jsonl --only MedRAG/pubmed --limit 100 # 直接处理本地下载的 reference_only.jsonl 副本 python scripts/rebuild_reference_only.py --input reference_only.jsonl --out rebuilt.jsonl

参数一览：

输出长什么样？

每行一个 JSON 对象，例如：

{"id": "dpo_2fae...", "upstream_dataset": "MedRAG/pubmed", "upstream_id": "pubmed23n0006_11585", "how": "MedRAG/pubmed", "text": "...", "sha256_match": false}

失败时则是"text": null加一个截断到 300 字符的error字段，最后终端会打印N rows, M fetched汇总。

注意事项：重建前必读的三点

1. 合规优先：这些行是 reference-only 是有原因的，抓取和使用请遵守每个来源的许可证与条款（脚本 docstring 专门强调了这一点）
2. 别被 false 吓到：如上所述，sha256_match为 false 很常见，需人工抽查文本内容确认
3. 上游可能变动：README 的 Limitations 一节点明，重建依赖上游站点持续在线，且训练文本多经过整理，重建结果可能与原始训练文本略有差异；行号型 ID 对应的是上游数据集的 0 基位置，上游数据更新后行号可能漂移

小结

rebuild_reference_only.py是一份教科书级的“数据找回”范例：前缀路由 + 来源专属抓取器 + 内存缓存 + manual 兜底 + 归一化哈希校验。理解这套机制后，你面对任何“只留引用不留正文”的训练语料，都能设计出类似的可重建方案。

• 重建脚本：scripts/rebuild_reference_only.py
• 分片说明与数据来源：README.md
• 三份 reference_only 语料：rewrite_sft/reference_only.jsonl · dpo/reference_only.jsonl · rl_prompts/reference_only.jsonl