XL-DocBench 是一个面向超长文档理解（Extra-Long Document Understanding）的基准评测数据集，包含 292 份真实专业文档和 1,345 道经 194 位人类专家逐条核验的问答题。它要求系统不仅"读懂"文档，还要找到证据、组合多方支撑、适用正确规则，并知道何时该拒答。本教程带你用一条命令、约 5 分钟的时间，完成从获取数据到跑通首次基准评测的完整流程。

为什么选择 XL-DocBench？📊

与常见的短文档问答基准不同，XL-DocBench 考察的是"数百甚至数千页"文档下的证据推理能力，非常适合用来检验你的长上下文模型或 RAG 系统。本次保守发布版（strict release）的关键数据：

题目覆盖金融、法律、医疗、理工、学术、文学六大专业领域。当前公开榜单上，最强系统 GPT-5.4 的 Accuracy 也只有38.36（满分 100），可见难度之高。

仓库结构速览 🗂️

在开始之前，先了解你即将打交道的几个文件：

一条命令跑通首次评测：分步指南 🚀

第 1 步：获取数据（约 1 分钟）

在终端中执行以下命令克隆仓库：

git clone https://gitcode.com/hf_mirrors/microsoft/XL-DocBench cd XL-DocBench

💡 所有脚本仅依赖 Python 标准库，无需安装任何第三方包。推荐使用uv来运行，省去环境配置。

第 2 步：运行冒烟测试（核心一条命令）

uv run --no-project python code/quickstart.py

这一条命令会一口气完成四件事：校验三份数据表与 ID 唯一性、核对证据页元数据、检查逐题得分覆盖是否完整、并运行一个 5 题的评测示例。看到如下输出，就说明环境完全就绪：

XL-DocBench smoke test: PASS data: 292 documents, 1,345 QA (1,191 single + 154 cross) evidence items: 3,044 per-question scores: 13 systems sample metrics: Accuracy=100.0, F1=100.0, ANLS=100.0

✅ 看到PASS即代表数据完整、评测器工作正常。示例中满分是因为内置了 5 条完美预测。

第 3 步：快速浏览数据（可选）

uv run --no-project python code/examples/load_data.py

该脚本会加载全部三张 JSONL 表，并打印文档数、题目数以及第一道问题，帮助你直观感受数据长什么样。示例记录格式可参考 schema/release_format_sample.json。

第 4 步：用内置示例跑一次真实评测

官方内置了一组 5 题示例（gold 标注 + 预测结果），直接运行：

uv run --no-project python code/evaluate.py \ --gold-files code/examples/gold_sample.jsonl \ --predictions code/examples/predictions_sample.jsonl

示例文件见 code/examples/gold_sample.jsonl 与 code/examples/predictions_sample.jsonl。这一步走通了，离跑完整 1,345 题就只差"把真实预测接进来"。

评测指标解读：三个数字分别代表什么？🧮

evaluate.py 报告三个确定性指标，均为规则式打分，不调用任何模型：

• Accuracy（宽松准确率）：预测与标准答案经过归一化后精确匹配才算对，衡量"答对"的硬指标；
• Token F1：按 token 粒度计算 F1，答对一部分也能拿到部分分，更平滑；
• ANLS：容错版准确率，允许答案存在轻微字符差异。

⚠️ 注意：缺失、失败或无法解析的预测一律计为错误，除非显式启用--ignore-missing参数。

如何评测自己的模型？🔧

让模型回答 1,345 道题后，把结果整理成 JSONL，每题一行，格式如下（预测字段也接受model_answer、answer、response、output等别名）：

{"question_id": "adubench_single_000001", "prediction": "the biggest single risk to human health worldwide"} {"question_id": "adubench_cross_000001", "prediction": "macroprudential measures"}

然后执行：

uv run --no-project python code/evaluate.py \ --predictions predictions.jsonl \ --output eval_report.json \ --per-question-csv per_question.csv

产出整体报告eval_report.json和逐题明细per_question.csv。你可以直接将自己的成绩与 results/summary.json 中 13 个已发布系统对比——榜单第一名 GPT-5.4（OCR 输入）的 Accuracy 为 38.36，这是一个值得瞄准的起点。

常见问题 FAQ 💬

Q1：没有安装uv怎么办？所有脚本只用 Python 标准库，可直接用系统 Python 替代：

python3 code/quickstart.py

Q2：冒烟测试报 FAIL 了？错误信息会明确指出失败原因（如Missing release file、Duplicate document_id）。最常见原因是数据文件不完整，重新克隆仓库即可。

Q3：仓库里为什么没有 PDF？出于版权考虑，本次发布仅包含文档的公开 URL 与元数据（见 data/documents.jsonl），不重分发第三方 PDF。

Q4：evidence_pages的页码是什么含义？使用从 1 开始的 PDF 页索引；而证据项（evidence item）中的页码保留标注员原始引用，印刷页码可能与 PDF 页索引不同，manifest.json 中有完整说明。

写在最后

从克隆仓库到跑通首次评测，整个流程只需要一条核心命令：

uv run --no-project python code/quickstart.py

接下来你可以：① 用 code/examples/load_data.py 深入浏览题目；② 接入自己的长上下文模型或 RAG 系统；③ 用 code/evaluate.py 完成全部 1,345 题的评测，看看你的系统能否超越当前榜首。祝评测顺利！