如何快速上手Omni Parse Bench:10分钟跑通你的第一次文档解析基准评测(安装与opb命令教程)
如何快速上手Omni Parse Bench:10分钟跑通你的第一次文档解析基准评测(安装与opb命令教程)
Omni Parse Bench 是 Datalab 推出的文档解析基准评测数据集:22 个测试套件、2,937 个页面、16,288 道测试题,覆盖 92 种语言,用来回答你真正关心的问题——"哪款解析器最适合我的文档?" 本文带你 10 分钟内完成安装,并用 opb 命令行跑通第一次评测 🚀
为什么需要 Omni Parse Bench?
选文档解析器时,大家通常只看排行榜上的一个平均分数。但平均分的赢家,未必能在你的文档上胜出。Omni Parse Bench 把评测拆成可审计的是/否小题,每题只检查一页上的一个事实:
| 测试类型 | 检查内容 | 所属家族 | 题数 |
|---|---|---|---|
present |
这段文字/数字/公式是否存在 | text | 7,275 |
order |
文本 A 是否出现在文本 B 之前 | text | 1,189 |
repeat |
这行是否恰好出现 N 次 | text | 35 |
table_cell |
单元格是否位于指定表头下 | tables | 5,386 |
layout_kind |
所在块是标题、正文还是表格 | layout | 2,403 |
总分(headline)= text、tables、layout 三个家族得分的均值。
更重要的是,每道题都带标签,你可以按任意切片单独计分:
- 结构:
table、math、form、multi_column - 渲染:
handwriting、tiny、rotated、degraded - 角色:
heading、caption、footnote、list、code、figure、header_footer - 文字系统 / 语言:ISO 15924 与 ISO 639-3 代码(如
Latn、eng、tha)
想看"某解析器在手写体上的表现"?一个按 handwriting 标签过滤的查询就够了。
仓库结构速览:数据都在哪里
整个数据集组织得非常直白,5 个部分各司其职:
| 路径 | 内容 |
|---|---|
| manifest.parquet | 元数据,一页一行:page_id、document、suite、doc_path、gt_path、outputs |
| pages/ | 实际送测的页面:单页 PDF 或图片 .png |
| gold/ | 每页的测试题,如 gold/handwriting_samples-htru_moonshines_p1.json |
| results.parquet | 各解析器对每道题的判定:pass / fail / unsupported,附失败原因 |
| licenses/ | 每个数据来源的许可证与署名要求 |
gold 文件里每道题长这样(节选自 gold/handwriting_samples-htru_moonshines_p1.json):
{
"id": "htru_moonshines_p1_00",
"test_type": "present",
"output_type": "html",
"tags": ["Latn", "fra", "handwriting"],
"args": {"content": {"text": "Bergère ô tour Eiffel...", "max_diffs": 0}}
}
一键安装步骤:三条命令搞定
安装用 uv(用 pip 同理)。按你的需求装到对应深度即可:
uv pip install omni-parse-bench # 评分器:score(),无需联网、无需 API key
uv pip install 'omni-parse-bench[harness]' # + 厂商适配器,可调用解析器做预测
uv pip install 'omni-parse-bench[benchmark]' # + 数据集访问,可跑完整基准
三档说明:
- 基础版:只装评分器,本地算分,零网络依赖——先跑通它最稳妥;
- harness 档:增加各厂商适配器,
opb predict可用; - benchmark 档:增加数据集访问,
opb benchmark可用。
⚠️ 注意版本:当前数据集版本需要 omni-parse-bench ≥ 0.1.2。若你用 0.1.1,需指定适配该版本的旧修订:--dataset hf://datasets/datalab-to/omni_parse_bench@1c35a52。
如果你希望从仓库获取数据集副本(只读):
git clone https://gitcode.com/hf_mirrors/datalab-to/omni_parse_bench
最快配置方法:opb 命令全解
opb 是本项目提供的命令行入口,四个子命令覆盖完整工作流。
1️⃣ opb providers:先看看有哪些解析器
opb providers
列出所有可用 provider 及其可选项。调用闭源 API 前记得先把对应厂商的 API key 写进环境变量。
2️⃣ opb benchmark:跑基准评测(本文主角)
opb benchmark --out runs/ --limit 5 --providers datalab openai/gpt-5.6-sol
这条命令对数据集中 5 个页面分别用两个 provider 跑测。它先打印执行计划,确认后才真正调用收费 API;运行可随时中断,之后执行相同命令即可断点续跑。
同一个 provider 的每种配置都是一个独立 run,用 --options 指定多档模式:
opb benchmark --out runs/ --limit 5 --providers datalab \
--options '{"datalab": [{"mode": "balanced"}, {"mode": "accurate"}]}'
--dataset 可指定本地文件夹,或锁定某个修订以保证结果可复现(不指定则默认用 main 上的最新数据)。
每次运行生成 scores.jsonl:一行一题,判定旁边就写着题目内容,方便你按标签、套件或测试类型横向对比。
3️⃣ opb predict:单页预测
opb predict --provider openai/gpt-5.6-sol --page pages/<page_id>.pdf --wants html
指定页面文件、输出类型,即可单独获取某一页的解析结果,适合调试。
4️⃣ opb score:本地算分
opb score --pred outputs.json --gold gold/<page_id>.json
把你的预测输出(JSON 文件)与 gold 测试题对拍,得到每题 pass / fail / unsupported / error 及失败原因 why。评分是纯规则代码,没有任何模型裁判,因此结果可复现、可审计。
在 Python 里调用:score 与 harness
如果你的工作流是脚本化的,可以直接用 API(示意,完整示例见 README.md):
from omni_parse_bench import gold, score, summarize
tests = gold.read("gold/<page_id>.json")
verdicts = score(outputs, tests) # outputs: {"html": "..."}
s = summarize(verdicts, tests)["html"] # 总分、按题型分、按标签分
调用厂商解析器则用 harness:
from omni_parse_bench import harness
record = harness.predict("datalab", "pages/<page_id>.pdf", {"html", "blocks"}, mode="balanced")
record["outputs"] # {"html": "...", "blocks": [...]}
record["errors"] # 各输出类型的失败原因
record["calls"] # 发送内容、费用、耗时
跑完之后:如何读懂结果
- 单个 run:看
runs/下每次运行的scores.jsonl,按标签切片对比,例如找出某解析器的手写体失分点; - 历史榜单:results.parquet 每行记录"某解析器 × 某题"的判定、页面、套件、题型与标签。官方榜单上 Datalab accurate 与 Gemini 3.8 Flash 以 92.9 分并列榜首,开源模型中 chandra-ocr-2(90.1)领先;Tesseract 仅 17.6 的 text 分,直观体现了基准的区分度;
- 许可证合规:商用前务必查阅 licenses/README.md,每个来源的授权范围与署名要求一目了然。
常见问题 FAQ
Q:跑 benchmark 会扣费吗?
opb benchmark 会先展示计划并等待确认,调用厂商 API 才会产生费用;opb score、opb providers 与 Python 评分器完全离线,不花一分钱。
Q:中断了怎么办? 运行是可续跑的:执行同一条命令即可从断点继续,不会重复已完成的页面。
Q:unsupported 和 error 算分吗?
都不算。unsupported(解析器无法产出该输出)与 error(评分器自身异常)会被排除在一切分数之外。
Q:为什么有的解析器没有 headline? headline 需要 text、tables、layout 三个家族齐全。Tesseract、olmOCR-2、Nanonets-OCR2-3B 不返回布局信息,因此只有分项分。
小结
10 分钟回顾一下你刚做完的事:✅ 安装 omni-parse-bench → ✅ opb providers 查看解析器 → ✅ opb benchmark --limit 5 跑通小规模评测 → ✅ opb score 本地对拍验证。接下来把 --limit 调大、锁定数据集修订、按 handwriting、rotated、tiny 等标签切片,就能得到专属于"你的文档"的解析器选型报告。祝评测顺利!