如何快速上手ExtractBench:3步跑通第一次文档抽取评测的完整新手教程
如何快速上手ExtractBench:3步跑通第一次文档抽取评测的完整新手教程
ExtractBench 是一个面向真实企业文档的文档抽取评测基准(benchmark):给定一份 PDF 和一份 JSON Schema,评测你的抽取系统能否返回既准确、又带来源页码与坐标证据(evidence)的结构化 JSON。本文带你用 3 个步骤完成第一次文档抽取评测:下载数据、读懂测试用例、运行评测并看懂 F1 分数,全程无需从零搭建环境。
为什么选择ExtractBench做抽取评测
一句话概括它的价值:
- 规模真实:370 份文档、4,869 页,覆盖 8 个业务领域、67 种文档类型(SEC 13F 申报、水电账单、海关表单、保险理赔等)
- 难度分级:按三大任务挑战标注——T1 长列表完整性、T2 大海捞针、T3 密集文档
- 五维标签:任务难度、感知挑战、表格结构、文档长度、业务领域相互独立,低分能追溯到真正原因
- 评分确定:同一份预测结果永远得到同一分数,评测过程中不引入任何模型
每个文档类型对应唯一一份 Schema,由用户撰写,系统输出的 JSON 必须通过该 Schema 校验。
第1步:下载评测数据集(一条命令)
ExtractBench 按文档长度分为 3 个切分(split),首次上手建议从 short 开始:
| 切分 | 文件 | 用例数 | 页数 | 单文档页数 |
|---|---|---|---|---|
| short | short.jsonl | 252 | 615 | ≤ 10 页 |
| medium | medium.jsonl | 98 | 2,438 | 11–50 页 |
| long | long.jsonl | 20 | 1,816 | > 50 页 |
用 Hugging Face datasets 库加载(推荐,无需手动下载):
from datasets import load_dataset
import json
ds = load_dataset("llamaindex/ExtractBench", split="short")
case = ds[0]
schema = json.loads(case["data_schema"])
expected = json.loads(case["expected_output"])
如果你要运行完整的抽取流水线评测,用官方评测框架下载目录结构:
uv run extract-bench download # 得到 data/<split>/<doc>.pdf + <doc>.test.json
对应的源 PDF 按切分存放在 docs/short/、docs/medium/、docs/long/ 三个目录中,每个测试用例都能找到它对应的原始文档,例如 docs/short/grafton_isotrope_invoice_19503.pdf。需要锁定特定版本时,加载时可传 revision 参数,如 revision="v1.0"。
第2步:读懂一个测试用例(5个关键字段)
打开任意一个 jsonl 文件,每行就是一个「文档 + Schema」测试用例,共 8 个字段:
| 字段 | 作用 | 新手提示 |
|---|---|---|
id |
用例唯一标识,格式为 <split>/<stem> |
可精确定位到某个文档 |
category |
所属切分(short / medium / long) | 与目录层级一致 |
pdf |
源 PDF 相对路径 | 例如 docs/short/xxx.pdf |
data_schema |
输出必须通过的 JSON Schema | JSON 编码字符串,需 json.loads 解码 |
expected_output |
人工标注的标准抽取结果 | 评分的 ground truth |
field_rules |
每个字段的比对与证据规则 | 最大可达 21 MB,在线预览仅供查看,下载文件是完整的 |
repeated_structure |
记录数组的身份键(如发票按 description + amount 对齐) |
数组顺序不影响得分 |
tags |
五维标签列表 | 如 ["source:real", "challenge:T3.b", ...] |
重点理解 field_rules:它为每个 Schema 路径指定比对方式(exact、case_insensitive、number、date 等)、可接受的证据读数({page, bbox, quote, value},任一被接受即算正确)、以及是否要求原文出处。这是评分确定性的来源。
第3步:运行抽取评测并看懂3个分数
把评测框架的 eval.yaml 可以看到,官方按 mean、short、medium、long 四个维度分别出分。运行你的抽取流水线只需一条命令:
uv run extract-bench run <pipeline> # 推理 -> 评测 -> 报告
报告会给出 3 类核心指标,看分前先明确各自含义:
- Unified value F1(取值准确率)——抽取的值是否与期望输出一致,对标量字段和记录数组用统一定义计分,覆盖全部文档
- Word-level grounding F1(词级定位)——字段值正确、且预测框与该字段被接受框的 IoU ≥ 0.5 才算「有据可查」,仅在有框级真值验证的文档上计分(v1.1 已覆盖 339/370 份文档)
- Page-level grounding F1(页级定位)——不要求精确坐标,但必须定位到正确的来源页
拿到分数后,如果某个切分偏低,用 tags 交叉分析即可定位病因:是扫描/手写感知问题(perception)、跨页表格(structure)、还是长列表截断(challenge:T1)。数据集里还内置了 38 份「clean vs corrupted」配对文档(如 real_ftx_full.pdf 与 real_ftx_full_corrupted.pdf),适合直接做系统鲁棒性对比实验。
新手常见坑位清单
- 字段是字符串不是对象:
data_schema、expected_output、field_rules、repeated_structure都需用json.loads解码 - 不要只跑 long 切分:long 仅 20 个用例但单文档超 50 页,迭代慢;先在 short 上调通再扩展
- 空值也要判对:文档中不存在的字段必须输出
null,凭空补值会直接拉低 T3 得分 - 重复记录要全:T1 任务的典型失败是截断、重复、合并行,以及值挂错记录
下一步建议
- 完整文档与数据集格式说明见 README.md(含标签分类学、数据展示与引用格式)
- 想对比「解析」环节而非「抽取」环节,可关注同系列的 ParseBench 配套基准
至此,你已经跑通了 ExtractBench 文档抽取评测的完整闭环:数据加载 → 用例解析 → 流水线评测 → 三维 F1 归因。祝评测顺利,跑分愉快 📊