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 评测 区分了压缩输出与保留原文的实际边界。