pdf-inspector：智能判断 PDF 是否需要 OCR

过去七天里，一个名字平平无奇的 Rust 库 star 数从约 7700 跃升至 16300。这不是某个 demo 动图引发的推特病毒式传播——pdf-inspector 是一个文档处理库，这是基础设施领域最不起眼的类别。它不生成图片、不写代码、也不回答问题。它只是查看一个 PDF，在大约 10 毫秒内判断这个文件是否根本不需要 OCR。

这就是它的全部卖点，而且它比听起来更有价值。每个正在构建 RAG 流水线、文档搜索产品，或能读取上传文件的 AI 智能体的团队，都遇到过同样的困境：PDF 不是一种文件格式，它至少是四种（纯文本、扫描图像、嵌入图片，以及三者混合的混乱产物），但大多数提取工具把它们当作同一个问题来处理。Firecrawl——那个做 Web 爬取 for LLM 的公司——开发了 pdf-inspector，目的就是不再为根本不需要 OCR 的 PDF 支付 OCR 费用。

过去几年，PDF 摄取一直是 AI 工具链中悄无声息却价格不菲的角落。每篇 RAG 框架教程最终都会遇到一个让简单文本提取器失效的 PDF——双栏布局被从左到右直接跨两栏读取、没有任何嵌入文本的扫描发票、一份前半部分是原生页后半部分是传真实拍附件装订在一起的合同。业界的默认做法是动用最重的工具——OCR 所有内容，或者把一切交给视觉语言模型——因为这是唯一能保证至少尝试处理每个文档的方案。但这个方案同时也把大批量上传的 PDF 变成了一张不必要的高额 API 账单和缓慢的处理队列，其中大部分时间都花在 OCR 那些压根就不是扫描件的文档上。

它实际做了什么

pdf-inspector 是一个 Rust 库——拥有 Python、Node.js/Bun 和 WebAssembly 的官方绑定——它按顺序完成三件事：

1. 分类：通过对内容流进行采样，检测文本操作符（Tj/TJ）与图片操作符（Do），将 PDF 判定为 TextBased、Scanned、ImageBased 或 Mixed，无需渲染任何一页。

2. 提取：带有位置感知地提取文本——字体元数据、X/Y 坐标、多栏阅读顺序、连字符还原、CID 字体和 ToUnicode CMap 解码、RTL 文本支持。

3. 转换：输出干净的 Markdown：通过字体大小比例推断标题级别，项目符号/编号/字母列表，monospace 触发的代码块，通过矩形几何和启发式对齐双重检测表格，通过字体名识别粗体/斜体，以及将 URL 转为链接。

这一切都不需要模型。核心的 Rust 和 WASM 版本只有一个依赖项 lopdf，用于低级 PDF 解析——没有捆绑的 ML 权重、不需要 GPU、不需要网络请求。这正是其增长曲线合理的细节所在：这是一款可以集成到离线流水线或浏览器标签页中的基础设施，每次运行结果都一致可信。

分类器本身成本很低，因为它从不光栅化任何东西。将页面渲染为图片——几乎是每个 OCR 或 VLM 流水线的第一步——才是文档处理中昂贵的部分；pdf-inspector 的检测阶段完全跳过了这一步，它直接读取 PDF 本身的内容流操作符。由 Tj/TJ 文本绘制操作符组成的页面就是文本页面。几乎只有一个指向嵌入图片的 Do 操作符的页面就是扫描件。两者都有且大致平衡的就是混合类型。每个页面几百微秒的内容流解析，而不是一次光栅化再分类的流程，这就是为什么整个 200 文档语料库能在半秒内处理完成的原因。

表格检测会进行两次独立检测而非一次：一种是基于矩形的方法，查找 PDF 生成器显式绘制的几何网格线；另一种是启发式对齐方法，即使没有任何可见边框，也能从对齐的文本列中推断表格结构。同时运行两种方法并对结果进行调和，是 TEDS（表格结构）得分达到 0.814 的主要原因——这个语料库估计同时包含带边框和不带边框的表格——在后者这个类别中，简单的文本位置提取通常会完全失效。

工作原理：路由而非替换 OCR

真正有趣的结构决策不是 Markdown 转换器——每款 PDF 转 Markdown 工具都有这样一个——而是这个库称为选择性 OCR 的部分，而且它只在 Python 和 Node 版本中提供（纯 Rust/WASM 核心在设计上保持无 OCR）。

流程如下：

文档首先经过分类器。TextBased 页面原生提取后永远不会进入 OCR 路径——文档称这一步在本地可以轻松在 200ms 内完成。

被标记为 Scanned 或 ImageBased 的页面被路由到 OCR，但只处理这些页面，而非整个文档。分类器支持四种扫描策略，选择哪一个实际上是在决定你希望把错误预算花在哪里：EarlyExit（默认策略）在遇到非文本页时立即停止，速度快但可能误分类一个中间夹杂一张扫描附件页的mostly-text 文档；Full 会扫描每一页以获得确定性的答案，代价是预先扫描整个文档；Sample(n) 检查均匀分布的页面，是长文档的折中方案，愿意以小幅漏检率换取速度；Pages(vec) 允许直接指定特定页面，当你已经知道比如附件总是出现在申报文档末尾时可以使用。

每个页面的结果都带有一个 provenance 字段——native、ocr 或 fused——外加一个置信度分数，因此下游代码（或人工审核者）可以准确知道某段文本是如何产生的，而不必把提取当作一个黑箱。

OCR 本身通过 PDFium 和 ONNX Runtime 可插拔式接入，延迟加载，且只在页面真正需要时才加载——如果一个默认的自动请求从未遇到扫描页，那些依赖项根本不会被加载到内存中。

这是竞争对手大多跳过的地方。基于视觉语言模型的工具默认将每个 PDF 都当作扫描文档处理，因为这是构建起来最简单且在所有文档上都能勉强工作的方式。pdf-inspector 赌的是，当一个有意义的 PDF 子集（银行对账单、合同、生成的报告、导出的发票）已经是完全可解析的文本时，"在所有文档上勉强工作"是错误的目标——而对这些文档仍然运行 OCR/VLM 处理纯粹是在浪费延迟和 API 支出。

如果你关注过 AI 基础设施栈其他部分的成熟过程，这也一种熟悉的形态。LLM 网关增加了路由，这样便宜的请求不会打到最贵的模型上。向量数据库增加了混合搜索，这样语义查询不会在关键字匹配就能立即回答的查询上运行。pdf-inspector 做了同样的事，只是应用在更早一层：在确认文档真正需要之前，不要让它走流水线中最贵的路径。分类作为门控，而非分类作为事后补救，这种模式在文档摄取领域尤其未被充分应用，因为"把所有文档都 OCR"长期以来一直是默认做法，团队已经停止质疑他们的大部分文档是否真的需要它。

基准测试数字

Firecrawl 发布了针对 opendataloader-bench 语料库的结果——200 份 PDF，在阅读顺序准确性、表格结构（TEDS）和标题检测上打分，汇总为一个综合得分：

处理完整的 200 文档语料库耗时 0.470 秒（五次运行的中位数）——作为对比，仅调用一次托管 OCR/VLM API 处理一份中等复杂度的 PDF 本身就通常需要更长时间。与 LiteParse 的差距很小，更像是"与最好的规则解析器持平"而非"全面超越"，但与 PyMuPDF4LLM 和 MarkItDown 的差距——这两者都是 RAG 教程中的广泛默认选项——大到足以在生产环境中产生影响。

值得精确说明这个基准测试展示和不展示什么：这是一个基于文本的 PDF 语料库，测试的是提取质量，而非扫描文档的 OCR 准确性。pdf-inspector 并未声称自己在 OCR 方面超越了谁——它声称的是很多目前正在被 OCR 处理的文档其实根本不需要 OCR，而且它能证明在那些不需要 OCR 的文档上自己是赢家。

为什么这个意义超越了 star 数

成本。OCR 和基于 VLM 的提取在大多数托管提供商那里是按页或按文档计费的。先分类、只为真正需要 OCR 的文档子集支付 OCR 费用的流水线，把线性成本曲线变成了平缓得多的曲线——节省的幅度取决于你的文档组合中已有文本的占比。

延迟。在同步上传预览流程中，低于 200ms 的本地提取对比调用 OCR 服务的网络往返，绝非边际差异。它决定了是让用户瞬间看到文档，还是让他们苦等。

锁定风险。由于核心库零捆绑模型、仅依赖一个 PDF 解析包，它不会将你绑定到特定的 OCR 供应商。OcrPageProvenance 和置信度评分设计意味着，你可以在 force/auto/off 路由模式下切换 OCR 后端，而无需触动流水线的其余部分——文档中尚未明确列出哪些外部 OCR 提供商能干净地接入，这对于正在评估而非只是阅读源码的你来说是个现实差距。

安全与可维护性。一个仅有一个依赖项且无 ML 权重的解析器，相比捆绑模型文件或每次上传文档都要信任第三方推理 API 的方案，攻击面和审计负担要小得多——对于处理含个人身份信息或财务数据的 PDF 的任何人，这一点都不可小觑。

开发者体验。一种 Rust 核心对应四种语言绑定，意味着分类逻辑——这部分才是真正来之不易的——不会在 Python 服务、Node API 和浏览器端预览之间被重新实现并产生分歧。这种单一真相来源的绑定策略在 2026 年已是基础设施库的标配，但仍未普及，值得在此肯定。

许可证。整体以 MIT 许可证发布。这对于一家由风险投资支持的公司来说，比看起来更重要——其付费产品（Firecrawl 的托管 API）与经过良好调参的自托管流水线可能实现的功能直接竞争。没有任何源码可用条款、没有使用场景限制、没有未来重新授权的计时器——你可以 fork 它、 vendoring 它，永远不用碰 Firecrawl 的付费端点，而且这种承诺是可执行的，而非一厢情愿。这与其他基础设施相关公司（Unstructured、LangChain）在自家核心库上采用的建立信任做法如出一辙：送出会成为锁定楔子的那个组件，然后在托管便利层上竞争。

适用场景：

需要根据每个文档、每个页面来决定是访问昂贵的 OCR/VLM 端点还是本地免费提取的 RAG 摄取流水线。

文档上传预览场景，本地提取低于 200ms 击败网络调用来渲染首轮视图，随后更慢、更高保真的一轮完成前用户无需等待。

合规与审计工具，其中 provenance 字段的 native/OCR/fused 标签为每个提取文本块提供了"这段文本是如何产生的"的可辩护答案——适用于任何提取准确度需要可追溯而不仅仅是看似合理的场景。

浏览器端工具——WASM 构建版本内置 CMaps，意味着 PDF 分类和基于文本的提取可以完全在客户端运行，除非文档确实需要 OCR，否则永远不会离开用户的机器。

大型文档存档的批量重处理，其中 Sample(n) 和 EarlyExit 扫描策略让你在语料库规模上调整成本/彻底性权衡，而非逐文件处理。

文档未明确说明的几个问题

在生产环境采用前，有几个差距值得指出：

OCR 提供商集成文档不足。Python 文档详细描述了路由契约（auto/force/off、provenance、置信度），但没有指名开箱即用支持哪些外部 OCR 服务——需要你自己对照 PDFium/ONNX Runtime 来接线。

置信度评分不透明。PdfResult 和 OCR 页面结果都暴露了一个 0.0–1.0 的置信度值，但公开文档没有解释它是如何计算的——如果你计划用它做自动路由决策的阈值（而不仅仅是记录日志），这一点很重要。

基准测试对这个设计来说是最佳情况。opendataloader-bench 是一个通用提取语料库，而非病态 PDF 的压力测试——重度嵌套表格、扫描件与可编辑文本混合、带重叠层的表单。在真正模糊的"混合"文档（库确实将其定义为一个类别）上的分类准确率没有在已发布内容中单独列出。

标题检测是四个评分维度中最弱的（0.788），这与字体大小启发式在面对不符合常规标题样式的 PDF 时天然脆弱是一致的——对于法律或学术文本等结构化文档用例来说是真实风险。

"自动标记损坏字体编码"做了大量悄无声息的工作。库文档说明它检测格式错误的 CID 字体映射和编码不匹配，而不是默默发出乱码文本，这是正确的做法——但这也意味着现实世界中相当一部分 PDF（旧版来自异常生成器的文档、部分在其他地方扫描后 OCR 的混合体）会被标记回来，而非干净提取，假设每个 TextBased 分类都产生干净输出的流水线需要将该标记作为一个真实分支来处理，而不是忽略的边缘情况。

一个值得与 star 数量一起考量的采用信号：约 1,100 个 fork 对比 16,300 个 star，对于这么新的库来说是相对较高的 fork 比率，这往往表明人们真的在拉取代码来构建绑定、打补丁 OCR 集成或为自家语料库改编分类器——而非仅仅收藏一个 GitHub 趋势条目。

诚实的框架：pdf-inspector 并非在真正需要重型布局理解的文档上与 Docling、Unstructured 或 LlamaParse 竞争——扫描表单、旋转页面、含图表的密集多栏学术 PDF、视觉模型看页面能力真正发挥作用的文档。它竞争的是"你需要这些工具的开销"这个假设——针对现实中占比很大的、仅仅只是……文本、编码正确、标准布局、视觉理解对 VLM 没有增加价值的 PDF。路由模型意味着它可以放在那些更重型的工具前面而非取代它们——先分类，只把困难案例发往下游，让昂贵的模型在真正需要它的文档上赚回成本。

这种框架也解释了为什么"击败 PyMuPDF4LLM 和 MarkItDown"比"击败 LlamaParse"更有意义。PyMuPDF4LLM 和 MarkItDown 与 pdf-inspector 占据相同的市场定位——免费、本地、基于规则、默认不 OCR——而且大多数 RAG 教程首先选用它们恰恰因为它们阻力最小，而非经过基准测试。Docling 和 Unstructured 在能力和成本上高一个档次；用纯文本文档语料库对比 pdf-inspector 和它们，相当于把路由器与完整解析引擎比较，两个方向都不公平。

增长数字是真实的，基准测试是可信的，但这也是针对一个非 Firecrawl 设计的语料库、在单一维度上（基于文本的提取质量）与竞品对比的第一方基准。它没有说明 pdf-inspector 的分类器在大规模对抗性或边缘情况文档上如何表现，而且 OCR 集成故事仍然足够薄弱，以至于"选择性 OCR"目前更多是一个设计良好的接口而非成品——路由契约在那里，但你需要带入哪些 OCR 提供商仍然留给集成商作为练习。

还有一个值得直接点名的幸存者偏差风险：一周的爆炸式 star 增长衡量的是多少开发者觉得这个说法足够吸引人去点击按钮，而非多少开发者将其放入生产流水线并保留在那里。GitHub Trending 之前在这类工具上烧过很多人——它们在第一周看起来具有变革性，但一旦边缘情况出现就悄然停滞——在将 star 数量视为成熟度信号而非兴趣信号之前，值得记住这一点。

独立于炒作周期来看，真正做得好的部分是架构：解析文档一次并在分类和提取之间共享，而不是每阶段重新读取文件；按页暴露 provenance 和置信度，而不是返回隐藏每个文本块如何产生的扁平字符串；保持核心无依赖，这样它可以运行在浏览器标签页中而完全不需服务器往返。这些设计决策往往无论这个特定 crate 一年后是否仍是默认选择都会良好演进——它们对于问题是正确的形状，竞争对手要想赶超也得做出类似选择。

谁应该尝试，谁应该等待

如果你正在构建或维护一个文档摄取管道，并且能够测算当前有多少比例的 PDF 在不必要地运行 OCR——这个数字你完全可以先查一下再动手写代码，它直接决定你能节省多少成本。同样值得关注的是，如果你想把快速、零依赖的 PDF 分类作为你已有 heavier 提取工具的上游预处理步骤：即使团队已经在 Docling 或 Unstructured 上处理复杂场景，也完全可以把 pdf-inspector 作为路由门控接入，让下游所有流程保持不变。WASM 构建版本也是一个真正独特的选择——在客户端完成分类，文档从不接触服务器，这种能力在其他地方很难实现。

如果你的文档以扫描件、旋转件或版式复杂件为主（医疗记录、历史档案、传真合同、带手写与印刷叠加层的表单）——那这不是这个库的目标用户，Docling 或托管的 VLM 解析器目前可能更适合你。同样，如果你需要开箱即用、有文档和支持的 OCR 集成，而不是自己去接线 PDFium 和 ONNX Runtime；那这一步目前还需要自己构建，而非一个配置开关。

如果你对现有管道的准确率和成本已经满意，或者文档量太小以至于 OCR 成本从来就不是瓶颈，那就无需关注。一个星期内 star 增长 16.3k 说明它值得关注，而不是必须迁移——而且为一个仍在补充 OCR 提供商文档的库迁移一个正常运行的提取管道，是在赌它的路线图，而不只是现有的代码。

讨论：如果你目前正在运行一个文档摄取管道，你真的知道你的 PDF 中有多少是纯文本的、多少是扫描件吗——还是说因为没人先做分类这一步，你默认就在为所有文档支付 OCR/VLM 的费用？

firecrawl/pdf-inspector on GitHub

pdf-inspector Python API docs

GitHub Trending (weekly)

opendataloader-bench corpus