PDF 提取如何避免成功响应下的内容错误
pdf-slice 是本地 CPU 运行的 PDF 转 Markdown 工具,针对错误缓存和正文漏提取设计显式异常提示。文章用同名文件串缓存、复杂文本层漏识别案例,说明完整 URL、内容哈希与缓存复核的作用。
AI 深度解读
PDF 提取最麻烦的失败,是接口返回 200、Markdown 看起来正常,内容却少了大半,甚至拿到了另一份文档。作者做的 pdf-slice,想解决的就是这种「成功假象」:检查文档身份、识别可疑的提取结果,并把来源和警告一起交出来。
它是一个本地、仅用 CPU 的 PDF 转 Markdown 工具。对把 PDF 接进 LLM 或 RAG 的程序员来说,值得借鉴的是它如何定义失败;至于「绝不静默出错」的承诺,现有测试还不足以完全证明。
文件名相同,为什么会读到另一份报告
作者遇到过几份都叫 Nexus.pdf 的文件,却共用了一个缓存键。用户要四月报告,系统返回了三月报告,连元数据都显得正常。
pdf-slice 的处理方式是:缓存键使用完整 URL 加下载内容的 SHA-256,不使用文件名;返回缓存前,再校验内容哈希。只要不匹配,就重新提取。
文档身份应该由内容验证,不能只靠文件名推断。
这一步解决的是「拿到的到底是哪份文件」,还没涉及提取质量。对 RAG 来说,两者必须分开检查:错误文档即使提取得完整,也只会让后续回答更有迷惑性。
原文没有解释缓存命中前如何重新获取、校验远端内容,因此不能据此判断它的网络开销和缓存收益。
有文字层,也可能只提取出页眉
另一个案例更隐蔽:一份 46 页、带完整文字层的 PDF,只提取出约 3,000 个字符,而且几乎都是页眉。同一文件,其他提取器能找到 86,000 多个字符。
正文是白色文字,嵌套在 form XObjects 中,又位于不透明图像下方。这里的 form XObjects 可以理解为 PDF 内嵌、可复用的页面内容对象。分类器认定它属于文字型 PDF,便跳过了 OCR,结果把残缺输出当成答案。
pdf-slice 不把「有文字层」当作充分条件。原生提取的每页字符数低于阈值,就自动运行 OCR;OCR 后仍然过少,则标为低置信度(fallback),并给出警告。原文没有公布阈值,也没有提供 OCR 的耗时或识别准确率对照。
它还把检查依据交给调用方:
- 每页 JSON 元数据记录 native/OCR 来源、字符数、表格和耗时,文档级记录
content_hash与缓存状态。 - Markdown 输出支持多栏阅读顺序和 Markdown 表格。
- RAG 分块输出为 JSONL,每块包含
text、page、element_type、confidence、source(URI 与内容哈希)以及reading_order。 - 加密、损坏、空文件及非 PDF 输入明确报错,不返回空的「成功」结果。
它也提供 stdio MCP server,可供 Claude Code、Cursor 和 Codex 使用。extract_pdf 负责提取,verify_pdf 从两条路径提取同一文档,返回 match_rate,用于发现不同路径实际返回不同内容的情况;仓库还提供现成的 agent skill。
下面三行用于安装依赖并提取本地 PDF:
git clone https://github.com/kamalmosadegh/pdf-slice && cd pdf-slice
python -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python extract.py your-file.pdf
注意最后一行通过虚拟环境中的 Python 执行 extract.py,your-file.pdf 需要替换为实际文件路径。
我的判断
我认可它把「输出是否可信」纳入接口契约。相比只交付 Markdown,来源、警告和缓存状态能让调用方决定是否继续入库,也更容易定位问题。
但「永不静默返回错误内容」目前更像设计目标。作者报告的静默错误数为 0,依据是工具自身测试套件生成的样本,覆盖 26 组测试,每组重复 3 次,包含缓存碰撞、白色文字、扫描件、多语言、表格、分栏、损坏、加密、批处理、MCP 和全新安装。这能说明已知案例受到检查,不能证明真实 PDF 都能被识别。
按字符数触发 OCR 也有边界:字数少可能是正常封面,字数多也可能顺序错乱。与始终 OCR 相比,这种回退策略试图减少处理量,但原文没有性能对照。两条路径结果一致同样不等于内容正确,match_rate 的计算方式和判定阈值也没说清。
它最有价值的做法,是让调用方能看见不确定性。
能拿来做什么
- 给 PDF 导入流程增加内容身份校验,避免不同来源的同名附件共用缓存;至少把完整来源和内容哈希保存下来。
- 在 Node 编排的 RAG 入库流程中读取逐页字符数、提取来源和警告,对低置信度结果暂停自动入库,安排复核。
- 在 Claude Code、Cursor 或 Codex 中试用 MCP 时,拿自己的问题 PDF 验证
extract_pdf和verify_pdf,重点检查缺页、阅读顺序和表格内容,别只看工具是否成功返回。