# 选文档解析器，30 页客户文档胜过任何排行榜

> 一个下午就能搭好的按字段打分脚本，让 FDE 凭实测准确率选解析器，而不是看榜单或凭直觉。

原文: https://fdetimes.net/zh/guides/field-level-parser-evaluation-30-pages/

一项关于发票信息抽取的研究中，一条用 Docling 读取发票的流水线整体准确率只有 63%，错误大多出在数字上。Docling 并不是糟糕的工具。这个数字只是提醒人们：排行榜上的分数和客户真实文档上的分数，可能相差很远。

对前线部署工程师（FDE）来说，“该用哪个解析器？”这个问题通常在驻场第一周就会出现。拿一篇博客或一张排行榜来回答，是最快的失信方式：三周后，客户的 Agent 读错一个总金额，信誉就没了。更有说服力的答案，是 30 页真实文档、一份字段清单，外加一个一个下午就能跑完的打分脚本。

本文就一步步搭起这套工具。需要准备：Python 3、一批样本文档（客户的文档，练习时也可以用公开发票），以及至少两个待比较的解析器。下面的示例使用 Docling、Unstructured 和 Amazon Textract AnalyzeExpense。

## 为什么不能信排行榜？

ParseBench 是一个与 LlamaIndex 相关的基准，发布于 2026 年 4 月，使用经人工核验的企业文档页面，涵盖保险、金融和政府领域。它最值得记住的发现是：在测试的 14 种方法中，没有一种在全部五个评测维度上都稳定领先。擅长表格的解析器可能不擅长扫描页，反之亦然。

作者还指出了另一个陷阱：文本相似度指标主要检查文字是否对得上，因此会漏掉那些在下游造成损害的错误，比如表格错乱。

设想一张列被合并的表格：每个词、每个数字都还在，文本相似度分数依然很高，但金额已经落到了错误的行上。按 ParseBench 的说法，真正需要衡量的是数据的含义是否仍然正确：输出必须保留足够的结构和语义，让系统能够自主做出决策。

所以，打分的单位必须是客户实际使用的数据字段，而不是整页文本。

## 第 1 步：选 30 页，写好答案

不要直接拿文件夹里的前 30 页。按最容易让解析器出错的类型来分：大约 10 页原生数字 PDF、10 页扫描件、10 页表格密集的页面。再问问客户，哪些页面最耗员工的时间，挑几页放进去。

为每一页写一个 JSON 答案文件，字段严格按照客户流程所需的清单：

```json
{
  "page_id": "inv_017",
  "fields": {
    "invoice_id": "HD-2024-0193",
    "vendor_name": "Minh An Co., Ltd.",
    "invoice_date": "2024-03-14",
    "total_amount": "12450000"
  },
  "line_items": [
    {"description": "A4 paper", "qty": "50", "amount": "4500000"},
    {"description": "Printer ink", "qty": "10", "amount": "7950000"}
  ]
}
```

这一步的检查：请客户方的人任选五个文件复核。标准答案错了，后面所有分数都是错的。

## 第 2 步：固定每个解析器的配置

比较解析器时最常见的错误，是沿用默认配置。Unstructured 有基于规则的策略（`fast`），也有基于模型的策略（`hi_res`、`ocr_only`），而默认的 `auto` 会根据文档特征自动选择。停在 `auto` 上，就不知道自己在比什么，所以要把 `fast` 和 `hi_res` 当作两个独立的候选来跑。

Docling 使用版面分析模型、用于表格结构的 TableFormer，以及针对扫描 PDF 的 OCR。导出为 Markdown 会丢失元数据，JSON 则是无损的。要按字段打分，就导出 JSON。

Textract AnalyzeExpense 返回一套标准字段分类，例如 `INVOICE_RECEIPT_ID`，每个值都带有 `Confidence` 分数。两者都要保留。评测工具的配置文件（简化版，结构自行设计）可以写成这样：

```yaml
candidates:
  docling:           {export: json}
  unstructured_fast: {strategy: fast}
  unstructured_hi_res: {strategy: hi_res}
  textract_expense:  {api: AnalyzeExpense, keep: [Confidence]}
```

## 第 3 步：写适配器，把所有输出映射到同一份字段清单

每个解析器返回的结构都不一样，所以要为每个解析器写一个小函数，把输出转换成与答案文件结构相同的 dict。Textract 最简单，因为它本身就有标准字段分类：

```python
TEXTRACT_MAP = {
    "INVOICE_RECEIPT_ID": "invoice_id",
    # 补上客户清单中的其他字段
}
```

对 Docling 和 Unstructured，需要在 JSON 或元素列表里定位取值，例如按标签（"Invoice no.:"）或按表格中的位置。每条查找规则都要记录下来。解析器之间的差距，有相当一部分可能来自适配器而不是解析器本身，向客户汇报时要明确说出来。

## 第 4 步：逐字段打分，区分严格匹配与宽松匹配

前面提到的发票研究，打分时用了字段级精确率、一致性校验违规次数和精确匹配，并且把精确匹配与宽松匹配分开。这种区分非常实用：总金额错一位数就是完全错误，而公司名少一个句点仍然可用。

```python
import re
from difflib import SequenceMatcher

EXACT_FIELDS = {"invoice_id", "invoice_date", "total_amount"}

def norm_amount(s, dec=","):
    s = re.sub(rf"[^\d{re.escape(dec)}-]", "", s or "")
    return s.replace(dec, ".")

def exact_match(field, pred, truth):
    if field == "total_amount":
        return norm_amount(pred) == norm_amount(truth)
    return (pred or "").strip() == (truth or "").strip()

def relaxed_match(pred, truth, threshold=0.9):
    # 宽松阈值：自行确定，并在报告中写明
    a, b = (pred or "").lower(), (truth or "").lower()
    return SequenceMatcher(None, a, b).ratio() >= threshold

def match(field, pred, truth):
    if field in EXACT_FIELDS:
        return exact_match(field, pred, truth)
    return relaxed_match(pred, truth)
```

上面的归一化函数做了简化。客户的数字和日期格式可能更复杂，打分前要先和客户商定归一化规则。

## 第 5 步：为表格打分，不因顺序变化扣分

ParseBench 的 TableRecordMatch 指标不考虑行和列的顺序：只要表格保留了值之间的对应关系，就不扣分。同一思路的简化版（并非原始实现）把每一行看作一组（列，值）对：

```python
def table_score(pred_rows, truth_rows):
    as_set = lambda rows: {frozenset(r.items()) for r in rows}
    p, t = as_set(pred_rows), as_set(truth_rows)
    return len(p & t) / len(t) if t else 1.0
```

只有一行中的每个单元格都正确，这一行才算对。标准很严，但这正是客户的 Agent 所需要的。

## 第 6 步：加上业务规则

只逐字段比对还不够。那项发票研究单独统计了抽取数据违反预设业务规则的情况，因为有些错误能躲过逐字段比对。最容易写的规则是：总金额必须等于各明细金额之和：

```python
def consistent(doc):
    total = float(norm_amount(doc["fields"]["total_amount"]))
    lines = sum(float(norm_amount(r["amount"])) for r in doc["line_items"])
    return abs(total - lines) < 0.01
```

这条规则在没有答案文件的文档上也能跑。所以系统上线到生产环境后，可以把它保留下来作为告警。

## 第 7 步：按最关键的字段解读结果

设想 30 页、每页 8 个字段，共 240 个值。解析器 A 答对 228 个，即 95%。听起来不错，直到发现 12 个错误中有 6 个落在 `total_amount` 上：客户用来审批付款的字段，30 页中只有 24 页正确，即 80%。

因此，要把结果输出为“字段 × 解析器”矩阵，并按页面分组拆开。下表中的数字是假设的，仅用于说明版式：

| 字段 | Docling | Unstructured hi_res | Textract |
|---|---|---|---|
| invoice_id（精确） | 29/30 | 27/30 | 30/30 |
| total_amount（精确） | 24/30 | 25/30 | 28/30 |
| line_items（正确行数） | 81% | 74% | 77% |
| 总金额规则违规次数 | 5 | 4 | 2 |

对 Textract 再多做一步：画出准确率随 `Confidence` 阈值变化的曲线。如果低 Confidence 的值几乎全错，就直接得到了一条规则：把这些页面转给人工复核。

**要点:** 平均分好看，可能恰好掩盖了客户最需要的那个字段在出错。

## 常见错误

第一，在 Markdown 上打分，然后怪罪解析器，而实际上是导出步骤本身破坏了结构。第二，所有字段用同一个宽松阈值，结果错误的金额也被算作“足够接近”。第三，挑了 30 页干净的文档，到生产环境遇上歪斜的扫描件才大吃一惊。

最难察觉的是，针对自己恰好偏爱的那个解析器调优适配器。只保留一套成文的适配器规则，对每个候选一视同仁。

## 在客户现场，评测工具本身就是产品

汇报时，不要以“解析器 X 最好”开场，而要以矩阵开场：哪些字段足够可靠、可以自动化，哪些需要人工复核，哪些业务规则能兜住其余问题。客户往往早就忘了你选的是哪个解析器，却还记得你是怎么衡量的。

这套评测工具也是一个很像样的作品集项目：一个代码仓库，包含基于公开文档的标准答案、两三个解析器的适配器和一张结果矩阵。写在简历上，“搭建字段级解析器评测工具，包含业务规则和置信度阈值”这样一句话，比罗列一串工具更有分量。

解析器会被一次次替换。30 页答案加一个打分脚本，每出现一个新候选都能拿来复用。

**本周动手试试:**

- 从客户那里取 30 页真实文档（或同类公开文档），分成原生数字文档、扫描件和表格密集三组，为 5-8 个字段写好 JSON 标准答案。
- 用固定配置运行至少两个解析器，编写适配器把输出映射到同一份字段清单，然后输出“字段 × 解析器”矩阵。
- 加一条业务规则（总金额等于各明细之和），统计每个解析器在多少页上违反了这条规则。

## 信源

- [ParseBench: A Document Parsing Benchmark for AI Agents](https://arxiv.org/abs/2604.08538)

- [ParseBench: A Document Parsing Benchmark for AI Agents](https://arxiv.org/html/2604.08538v3)

- [Invoice Information Extraction: Methods and Performance Evaluation](https://arxiv.org/abs/2510.15727)

- [Invoice Information Extraction: Methods and Performance Evaluation](https://arxiv.org/html/2510.15727v2)

- [Docling: An Efficient Open-Source Toolkit for AI-driven Document Conversion](https://arxiv.org/html/2501.17887v1)

- [Partitioning strategies - Unstructured](https://docs.unstructured.io/open-source/concepts/partitioning-strategies)

- [Analyzing Invoices and Receipts - Amazon Textract](https://docs.aws.amazon.com/textract/latest/dg/invoices-receipts.html)
