本地 PDF 解析不只是省一次 OCR：pdf-inspector 正在变成文档流水线的前置基础设施

文档流水线里最容易被默认化的一步，往往也是最昂贵的一步：OCR。很多系统看见 PDF 就直接渲染成图片，再交给 OCR、视觉模型或外部识别服务处理，理由听起来很充分——接口统一、下游简单、逻辑省事。问题也同样明显：只要源文件本来就带有可靠文字层，这条路就等于把一份可以直接解析的文档，强行改造成了图像识别问题。延迟变高，成本变高，阅读顺序和表格结构变差，隐私边界也更难守住。

Firecrawl 的 pdf-inspector 正好站在这个分叉口上。它不是一个“万能 PDF 平台”，而是一个边界很清楚的 Rust 核心：先分类，再抽取，再决定哪些页需要 OCR。README 把它定义成 fast Rust library for PDF classification and text extraction，支持 TextBased、Scanned、ImageBased、Mixed 四种类型识别，返回 confidence 和 pages_needing_ocr，同时把文本抽取、位置感知、Markdown 转换都留在本地完成。它不做 OCR，不带 ML 模型，也不调用外部服务。这种克制反而让它更像文档系统里的基础设施，而不是一个只适合演示的单点工具。

为什么“先本地解析”比“先 OCR”更适合流水线

如果你的系统面对的是合同、论文、研报、财务报表、技术手册、发票、扫描归档件这些真实文档，最重要的不是把每一页都变成可搜索文本，而是把不同页面分到合适的处理路径。pdf-inspector 的分类结果里，TextBased 表示可以直接抽取的文字层；Scanned 和 ImageBased 则提醒调用方准备后续 OCR；Mixed 则承认现实世界最常见的情况：一本 PDF 里可能同时存在可抽取页、扫描页、图片页和编码异常页。

这件事在架构上很重要，因为它把 OCR 从“默认前置步骤”降级成“精确兜底步骤”。更具体一点：先运行 pdf-inspector，得到 pdf_type、confidence、pages_needing_ocr，再按页或按区域路由。高置信 TextBased 直接进入 Markdown、切块、索引和引用定位；Mixed 文档则先把可抽取页吃干净，扫描页再交给 OCR；低置信或 has_encoding_issues 的页单独进入更保守的分支。这样做的好处不是只省钱，而是把错误面缩小了。对 RAG 来说，错误的上下文比少一点上下文更危险，因为它会稳定地污染向量索引、标题层级、chunk 边界和引用定位。

pdf-inspector 的默认思路非常适合这种“先路由、后重工”的链路。它不试图在第一步就解决所有问题，而是先把哪些页能本地解决、哪些页必须升级到 OCR 说清楚。对企业文档系统来说，这种判定能力往往比单纯的识别准确率更值钱。

位置感知不是细节，而是文档结构的根

很多 PDF 抽取工具看起来也能把文字读出来，但顺序一乱，结果就没法直接进 RAG。左栏、右栏、页眉、脚注、题注、表格编号一混，语义就散了。pdf-inspector 的价值就在于它不是只抓字符串，而是保留文本项的位置信息、字体信息和 X/Y 坐标，再基于这些信息整理阅读顺序。README 里明确提到它支持 multi-column reading order、RTL 文本、CID/Type0 字体通过 ToUnicode CMaps 解码，并且能自动识别损坏的编码，提示调用方回退 OCR。

这说明它的定位不是“把 PDF 变成纯文本”，而是“尽可能保留结构后再输出 Markdown”。这个差别非常关键。对 RAG 系统来说，Markdown 不是终点，而是一个结构化中间表示：标题可以映射成层级，列表可以保留语义，分页可以作为 chunk 边界信号，表格可以单独处理。越接近结构，后续分块、检索、摘要和引用越稳定。相反，如果前面把结构抹平，后面再聪明的嵌入模型也只是拿一锅乱序文本做近似匹配。

pdf-inspector 在这一点上做得很务实：它不是依赖昂贵的视觉模型去“猜结构”，而是从 PDF 内部对象、文本流和绘图操作里读结构。对于本地优先、合规优先、可重复性优先的文档系统，这是一条更稳的路线。

表格、多栏和 RTL：真正影响检索质量的地方

最容易让文档系统翻车的，不是正文，而是表格和版式。pdf-inspector 的 Markdown 转换里，表格识别用了两类信号：一类来自 PDF 绘图操作中的矩形线框，另一类来自文本对齐的启发式判断。这个设计的好处很直接：有些表格真的画了线，有些表格没有线，但文本排列仍然表现得像表格。只靠一种规则，很容易漏掉其中一半。

多栏文档也是同样的道理。论文、金融报告、政策文件和新闻扫描件经常把同一页拆成两栏甚至多栏，如果阅读顺序错了，摘要会把不同栏的内容混成一团，检索命中后也会把相邻但无关的句子串在一起。pdf-inspector 提供自动的多栏阅读顺序识别和 RTL 支持，这意味着它不是只面向英文报告，而是更接近通用文档基础设施。对跨语言知识库来说，这种支持比“能打开 PDF”重要得多。

它还把页码、页面级 Markdown、页级 OCR 路由、表格页标记等信息暴露给调用方。换句话说，下游不是只能拿到一坨字符串，而是能拿到一个更适合做工程决策的数据对象。你可以把某些页直接存为索引文本，把某些页单独进入图像 OCR，把表格页交给专门的结构化抽取器，再把最终结果统一成知识库格式。这样的设计更像流水线编排，而不是单一函数调用。

Python、Node/Bun、WASM、Rust：同一套核心，四种部署面

另一个值得重视的点，是 pdf-inspector 并没有把自己局限在 Rust 用户里。官方文档提供了 Python 绑定、Node.js/Bun 绑定和浏览器 WebAssembly 绑定，核心仍然是同一套 Rust 解析器。Python 文档在 docs/python.md，Rust API 在 docs/rust-api.md，Node 侧的 N-API 方案在 napi/，浏览器侧 WebAssembly 在 wasm/，基准测试说明则在 docs/benchmarking.md。

这套跨语言布局的意义，不只是“生态丰富”。它代表 pdf-inspector 可以嵌进不同层级的系统：Python 适合数据处理、批任务和实验脚本；Rust 适合服务端核心库和高吞吐后端；Node/Bun 适合产品层工具和流水线脚本；WASM 则把同一套能力推到浏览器和 Web Worker 里。对文档系统来说，这很实用，因为很多场景并不想把 PDF 先上传到远端服务才处理，尤其是合同审阅、内部知识库和离线批处理。能本地跑，就能少一次传输，少一次合规风险，少一次平台绑定。

benchmark 的意义：不是“比谁最全”，而是“谁更适合作为默认层”

README 的 benchmark 很值得读，但要读对。它不是在说 pdf-inspector 是所有 PDF 任务的终极答案，而是在说它在一个特定约束下表现非常强：opendataloader-bench 的 200 个 PDF，OCR 关闭，只比较本地引擎。结果是 pdf-inspector overall 0.875，reading order 0.915，tables 0.814，speed 2.8s，基准于 2026-07-16 在 Apple M4 Pro 上刷新。这个结果的含义不是“它能打败一切”，而是“在需要本地、快速、结构感强的文本抽取时，它非常适合做默认入口”。

这里的 tradeoff 也很清楚：pdf-inspector 强在本地解析、布局保真和速度，弱在它并不试图替代 OCR 或模型式文档理解。Image-only 文档、手写稿、严重损坏的扫描件、图文混排异常复杂的页，仍然要交给后续 OCR 或专门的视觉管线。换句话说，它不是终点，而是让后续重活更精准的分流器。对成熟文档平台来说，这不是缺点，而是分层设计的优点。

适合放进什么样的系统

如果你在搭建 RAG、知识库、研报解析、合同归档、票据处理或技术文档搜索系统，pdf-inspector 最适合放在“接入层”或“预处理层”。它先判断文档是不是应该直接抽取，再决定是否需要 OCR，再输出尽量结构化的 Markdown 和页级元数据。这样做能让后续的 chunk、embedding、召回、重排和人工复核都站在更干净的输入上。

如果你的目标是一个完全离线、隐私优先、可重复、可解释的文档管道，那么它比“先图像化再识别”的思路更像一块可复用的基础组件。如果你的目标是处理大量扫描件和手写件，那它也仍然有价值，只是它的角色应该是前置分类和部分抽取，而不是替代 OCR。把它放对位置，它就能明显降低系统复杂度；把它放错位置，你只会觉得它“不够全能”。

真正成熟的文档管线，通常不是一条神奇的通道，而是分层路由。pdf-inspector 的价值就在于，它把“哪些页值得本地解析”这件事先算清楚了。对 RAG 来说，这一步往往比后面多加一个向量库参数更重要。