Xberg 实测:PDF 表格、OCR 与失败处理

实测 Kreuzberg 后继项目 Xberg 1.3.9,核对原生 PDF 表格、混合扫描页、OCR 数字错误及批量部分失败,说明文档入库的验收边界。

AgentIndex · 发布于 2026-11-07 · 更新于 2026-11-07

Xberg 是 Kreuzberg 的后继项目。这次实测中,它正确提取了原生 PDF 表格,配置 Tesseract 后也能读出所测英文扫描内容;但复杂扫描表格出现了漏行与数字错误。提取结果可以作为文档流水线的输入,表格对象的存在却不足以证明可以直接入库。

我们使用发布版 Xberg 1.3.9 原生 wheel,实际执行了 15 次 Python 提取调用。这篇长评解决一个具体选型问题:原生文本、扫描页与失败文档混在一起时,调用方还需要检查什么?

先区分 Xberg 1.x 与 Kreuzberg 4.x

固定发布版本的 README 将 Xberg 描述为 Kreuzberg 的下一代实现,重新构建并使用新的 v1 版本线。当前仓库为 xberg-io/xberg,Kreuzberg v4 LTS 仓库 单独保留。评测时 Python 包分别为 xberg==1.3.9 与旧线 kreuzberg==4.10.4,实际运行的是前者。

所测公开 Python API 提供 extract、extract_batch 和 ExtractInput,没有 extract_file_sync。已有 Kreuzberg 示例需要按所选版本重新核对;本次没有验证无修改迁移。本站保留原有工具网址,让搜索新旧项目名的读者都能到达同一条已评测记录。

测试对象与可复现范围

测试日期为 2026 年 11 月 7 日,环境是 Apple M1 Pro、macOS 26.6.2、x86_64 Python 3.13.1。仅安装预编译包,依赖锁包含 Xberg 1.3.9、pypdf 7.0.0、Pillow 13.0.0。使用的文件为 xberg-1.3.9-cp310-abi3-macosx_11_0_x86_64.whl,SHA-256 为 8e1ea84e5cfbeeec3c13957584754c45ae1b29bfd5e4ea5ebca222fe84ae3552。四个 Python 包装文件与发布提交 fdb16150ed0bf8578d68e20ec32301bc2caa8fd1 一致,安装后的原生二进制也与核验过的 wheel 一致。

五份 PDF 均来自该提交的合成测试样本,文件保持原样:空白页、原生表格、简单扫描件、两页原生/扫描混合文档、带底纹的密集扫描表格。它们不代表客户文档分布,表格也不是真实财报。我们用独立的 Poppler 渲染全部六页并逐页目视检查,再用 pypdf 检查文本层;另编写了一份小型中文 HTML 对照。

复现脚本、来源哈希与原始输出 保留了固定下载地址、返回正文、表格单元格、分页内容及预期失败。英文 tessdata_fast 文件也固定了版本与哈希。系统 Tesseract CLI 报告 5.5.0;这是环境记录,不代表另外核实了 Xberg 内嵌后端的版本。

条件实际结果
原生表格,禁用 OCR返回一张表,20 个单元格均与目视参考一致
同一 PDF 改用字节输入正文与表格和文件输入一致
纯图片简单扫描件,禁用 OCR成功返回,但正文为空
同一扫描件,明确配置英文 Tesseract三个选定文本标记均出现
原生页与扫描页混合原生内容保留,配置 OCR 后第二页按顺序出现
带底纹的密集扫描表格五个选定行中,两行的六个数值全部匹配
单次调用损坏 PDF抛出含解析错误的 RuntimeError
有效与损坏 PDF 同批提取返回一条有效结果及一条带输入索引的错误

调用明确使用原生 PDF 后端、表格与分页提取、关闭缓存,以及 30 秒提取期限。OCR 用例指定 Tesseract、eng 语言数据,关闭 VLM 回退;没有据此推断未指定配置时的默认 OCR 行为。未调用模型服务或远程文档接口。Python TCP 审计没有记录连接尝试,但它不能观测原生库中的所有可能网络路径。

原生表格:文件与字节两条路径一致

原生样本包含四列、一行表头与四行年度数据。禁用 OCR 后,Xberg 恰好返回一张表,20 个单元格全部匹配,包含带逗号的数字和多词表头。将同一文件改成 ExtractInput(kind="bytes", ...),正文和表格数据也完全一致。

这证明了一个小型、清晰文本层表格的实际处理结果,不能推广到合并单元格、旋转表格、跨页布局或任意报告。我们还运行了强制 OCR 配置,表格矩阵同样匹配;由于流水线仍能访问原生 PDF 结构,不能将其归因于纯 OCR 建表。

额外的分块调用设置 max_characters=180、overlap=30,返回五个非空块。这里只检查是否得到分块,没有验证检索质量、语义边界或通用长度保证。

混合页:需要明确 OCR 配置并检查分页

pypdf 在简单扫描件中没有找到文本层。Xberg 禁用 OCR 时返回一条结果、零条错误,正文为空;明确配置英文 Tesseract 后,选定标题、第二行文字和发票编号标记均出现,元数据报告使用了 OCR。

两页混合文档更能说明处理路径:第一页带有可选取的文本,第二页只有图片。禁用 OCR 时,只出现原生页内容,没有扫描页标记;配置 OCR 后,两页内容按顺序出现,第二页选定总额也被读出,分页结果包含两条记录。设置 force_ocr_pages=[2] 后,第一页原生标记仍保留,第二页扫描标记也出现。

单独的空白 PDF 同样成功返回空正文。因此在这些条件下,空正文可能是合法空白页,也可能是未处理的扫描内容,不能与解析异常混为一谈。入库时应结合文档预期、分页输出和 OCR 元数据,再决定接收、重试或人工复核。

扫描表格:结构化输出仍可能数字出错

提取前,我们目视抄录了底纹扫描件的五行,每行六个数值。行名经过规范化匹配;数字比较只去掉逗号和空白,保留正负号、括号与小数点。这个验收条件比“返回了表格对象”更严格。

选定行六个数值是否全部匹配观察
APPLES是六个值一致
SUBTOTAL FRUIT否返回表格行中没有找到该行名
TOTAL PRODUCE是六个值一致
SPOILAGE否返回表格行中没有找到该行名
CLOSING STOCK BALANCE否两个数字不同

最后一行中,预期 30,640 变成 30,604,预期 29,408 变成 29,749。即使响应已包含结构化单元格,这类变化仍会影响数字入库。原始提取保留下来,读者可以检查选定行之外的内容。

这个输入也有局限:Poppler 成功渲染,但先报告 JP2 流格式异常,再尝试按 J2K 处理。我们保留警告与目视检查记录。它限制了该样本对一般 OCR 行为的代表性,但不会消除已经观察到的错值。五个选定行中两行全匹配,只是本次抽查结果,不是整篇文档的 OCR 准确率,更不能作为其他文档的预测值。

涉及数字入库时,应检查预期行名、列数,在适用时核对合计,并把不一致送入视觉复核。至少对这个扫描样本而言,成功标记和非空表格不能单独充当验收标准。

单次失败与批量失败需要两种处理

故意损坏的 PDF 字节通过 extract 调用时,抛出 RuntimeError,信息指向无效交叉引用表。不存在的本地路径另行抛出带 I/O 错误的 RuntimeError。

将有效表格 PDF 与同一损坏输入交给 extract_batch,调用正常返回,汇总为 inputs=2、results=1、errors=1。错误指向输入索引 1,有效表格仍然精确匹配。这保留了批次中的可用工作,但只捕获异常的调用方会漏掉失败输入。

需要同时处理抛出的异常与批次内返回的错误,并保留它们到源输入的映射;成功但空正文则作为另一种结果处理。这里验证的是这些实际用例的契约,没有遍历全部错误代码。

适合怎样采用

如果你需要本地库来处理原生 PDF 文本、表格、可选 OCR 与逐输入批量错误,并愿意增加文档自身的验收规则,Xberg 值得进入小规模试点。所测 Python 包声明要求 Python 3.10 或更新版本;本次环境下预编译包安装与 pip check 均通过,没有运行其他平台。

人工中文 HTML 中的标记被保留,脚本标记没有进入正文;这只验证静态 HTML,没有验证中文 OCR。本次只使用英文 OCR 数据。未测 Office、完整格式列表、多语种扫描、嵌入、VLM、其他语言绑定、CLI/MCP 服务、大文件内存、生产吞吐或相对速度优势。

Xberg 工具详情 汇总安装与选型条件。若要把提取功能开放为 Python MCP 服务,可继续看 FastMCP 校验与超时评测,了解业务契约仍需哪些检查;后续涉及上下文压缩时,Headroom 评测 区分了压缩输出与保留原文的实际边界。