如何快速上手Omni Parse Bench:10分钟跑通你的第一次文档解析基准评测(安装与opb命令教程)

原创2026-10-17 22:52:031,646 阅读
文章标签:数据集AI 评测OCR数据标注

如何快速上手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]'    # + 数据集访问,可跑完整基准

三档说明:

  1. 基础版:只装评分器,本地算分,零网络依赖——先跑通它最稳妥;
  2. harness 档:增加各厂商适配器,opb predict 可用;
  3. 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 等标签切片,就能得到专属于"你的文档"的解析器选型报告。祝评测顺利!

登录后查看全文
omni_parse_bench