如何快速上手ExtractBench:3步跑通第一次文档抽取评测的完整新手教程

原创2026-10-20 10:06:481,384 阅读

如何快速上手ExtractBench:3步跑通第一次文档抽取评测的完整新手教程

ExtractBench 是一个面向真实企业文档的文档抽取评测基准(benchmark):给定一份 PDF 和一份 JSON Schema,评测你的抽取系统能否返回既准确、又带来源页码与坐标证据(evidence)的结构化 JSON。本文带你用 3 个步骤完成第一次文档抽取评测:下载数据、读懂测试用例、运行评测并看懂 F1 分数,全程无需从零搭建环境。

ExtractBench文档抽取评测基准概览:输入PDF与Schema,输出带页码和坐标证据的结构化JSON

为什么选择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", ...]

ExtractBench标签体系:任务挑战、感知挑战、表格结构、长度与业务领域五维独立标注

重点理解 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 类核心指标,看分前先明确各自含义:

  1. Unified value F1(取值准确率)——抽取的值是否与期望输出一致,对标量字段和记录数组用统一定义计分,覆盖全部文档
  2. Word-level grounding F1(词级定位)——字段值正确、且预测框与该字段被接受框的 IoU ≥ 0.5 才算「有据可查」,仅在有框级真值验证的文档上计分(v1.1 已覆盖 339/370 份文档)
  3. 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 归因。祝评测顺利,跑分愉快 📊

登录后查看全文
ExtractBench