pdf-inspector如何分类提取PDF

ENGINEERING NOTES

技术专栏目录

01 firecrawl/pdf-inspector 如何把 PDF 先分类再提取：Rust 本地库的最小使用流程

NO.01

firecrawl/pdf-inspector 如何把 PDF 先分类再提取：Rust 本地库的最小使用流程

2026/08/04 00:00:00

TECH NOTE

先给结论：它解决的是 PDF 进入下游流程前的分流问题

pdf-inspector 是 firecrawl 开源的 Rust PDF 检查、分类和文本提取库，主要入口包括 Python 的 pdf_inspector.process_pdf、Node.js 的 processPdf/classifyPdf，以及浏览器侧的 @firecrawl/pdf-inspector-wasm。

这个项目最值得看的不是“又一个 PDF 转文本工具”，而是先判断文件属于 text_based、scanned、image_based 还是 mixed，再决定继续本地解析、转入 OCR，还是进入人工复核队列。

README 给出的 Python 构建路径是 pip install maturin 与 maturin develop --release；Node.js 侧使用 npm install @firecrawl/pdf-inspector；WASM 侧使用 npm install @firecrawl/pdf-inspector-wasm。

官方基准使用 opendataloader-bench 的 200 份 PDF，在禁用 OCR、只比较本地非模型解析器的条件下，pdf-inspector overall 为 0.875，reading order 为 0.915，tables 为 0.814，200 份文档速度为 0.470s。

短期更适合做原生文本 PDF 的快速入口分流和 Markdown 提取；如果主要输入是扫描件、照片 PDF 或需要 OCR 识别，它不能替代 OCR 引擎。

TECH NOTE

这个项目为什么会火：PDF 解析的第一步经常被做错

文档处理链路里最常见的失败，不是“没有 PDF 解析库”，而是把所有 PDF 都当成同一种文件处理。一个可复制文本的研究论文、一个由扫描图片组成的合同、一个前几页是文本后几页是图片的混合文件，在文件扩展名上都叫 PDF，但对程序来说完全不同。把扫描件直接交给文本提取器，结果往往是空字符串、错乱对象、缺页，或者只有图片引用；把原生文本 PDF 全部送去 OCR，又会引入额外延迟、计算成本和隐私边界。

pdf-inspector 的定位正好在这个入口处。它不是把自己包装成完整文档理解平台，而是做三件更窄但更实用的事：检查 PDF、判断类型、提取文本并输出 Markdown。README 对它的描述是 Fast Rust library for PDF inspection, classification, and text extraction，并强调能 intelligently detects scanned vs text-based PDFs to enable smart routing decisions。这里真正有价值的词是 routing decisions，也就是在下游任务开始前先做路径选择。

这类分流在 RAG、知识库导入、财报解析、发票处理、合同归档里很重要。一个小团队如果没有这个入口，通常会遇到两种极端：要么为了省事全部 OCR，吞下速度和成本；要么全部走文本解析，等到用户问答结果错了才发现原始文件根本没有可提取文本。pdf-inspector 的价值不是让所有 PDF 都“看懂”，而是让系统尽早知道哪类 PDF 可以低成本处理，哪类 PDF 不该继续走当前管线。

从项目热度看，它也确实踩中了开发者痛点。素材显示 firecrawl/pdf-inspector 在 GitHub Trending 当日第 3 名，总 Stars 8,203，Forks 542，当日新增 1,699 stars。热度不能替代验证，但说明“本地、快速、无需模型的 PDF 分类和提取”有明确需求。真正要不要采用，还是要看你自己的样本文档上能不能稳定得到 pdf_type、markdown、阅读顺序和表格结构。

TECH NOTE

前置条件：先把它当作本地库，而不是云端文档服务

评估 pdf-inspector 前，要先把预期摆正。它是一个纯 Rust 本地库，README 里写到它不使用 ML models，不依赖 external services，PDF 解析依赖 lopdf。这个设计带来的直接好处是边界清楚：文件不需要上传到外部服务，也不需要 API key；坏处也同样明确：它不会替你做 OCR，不会管理任务队列，不会维护文档状态，也不会把解析失败样本自动送进人工后台。

Python 用户需要关注 maturin。pyproject.toml 里的 build-system requires 是 maturin>=1.0,<2.0，build-backend 是 maturin；tool.maturin 下的 features 包含 python。也就是说，Python 入口不是一个纯 Python 脚本，而是通过 PyO3 暴露 Rust 能力。你需要准备 Python 3.8 以上环境，以及能构建 Rust 扩展的本地开发环境。第一次试用时，建议在干净虚拟环境里安装，避免把构建错误和现有项目依赖混在一起。

Node.js 路线适合后端服务、批处理脚本或队列消费者。README 示例使用 readFileSync 读取 document.pdf，再调用 processPdf 或 classifyPdf。WASM 路线则适合浏览器或边缘环境，示例里需要 import init, { processPdf } from @firecrawl/pdf-inspector-wasm，先 await init()，再把 fetch 得到的 arrayBuffer 转成 Uint8Array 交给 processPdf。这个路径的优势是文件可以留在当前运行环境内，限制是浏览器内存、大文件体验和初始化成本需要单独测。

最小样本不要只准备一份“看起来正常”的 PDF。建议准备三类：一份可复制文本的报告或论文，一份扫描件或图片 PDF，一份混合型 PDF。pdf-inspector 的核心价值在分类边界，如果只用原生文本 PDF 测试，最多证明它能跑通，不能证明它能帮你的流程做分流。

TECH NOTE

最小使用路径：从源码构建到一次分类和 Markdown 输出

下面这条路径按 Python 本地验证来设计，适合想先看清 pdf_type 和 markdown 输出的读者。真正可复制的命令放在紧邻步骤的代码块里；步骤文字说明输入、对象和检查点。document.pdf 需要你自己准备，并放在当前项目目录下。README 里的示例文件名就是 document.pdf，但仓库不一定自带这个样本。

获取 firecrawl/pdf-inspector 仓库并进入项目目录，检查 README.md、pyproject.toml 和 src 目录是否存在；这一步的对象是源码，输入是本地 Git 工作区，检查点是后续 maturin 能在当前目录找到 Python 构建配置。

安装 maturin 并执行 maturin develop --release，目标是把 Rust 核心构建成本地 Python 扩展；检查点是 Python 解释器能够 import pdf_inspector，而不是只看到安装命令成功结束。

把待测样本命名为 document.pdf 放在仓库根目录，至少先用一份原生文本 PDF 试跑；检查点是 process_pdf 能返回 result.pdf_type，并且输出值落在 text_based、scanned、image_based、mixed 这类分类结果里。

用 Python 调用 pdf_inspector.process_pdf("document.pdf")，打印 pdf_type 与 markdown；检查点是原生文本 PDF 应该能得到 Markdown 字符串，扫描件或图片型 PDF 则可能返回空内容或不适合继续本地文本提取。

如果你的服务栈在 Node.js，安装 @firecrawl/pdf-inspector，并把同一份 document.pdf 交给 processPdf(readFileSync('document.pdf'))；检查点是 pdfType 与 markdown 能在服务端脚本中被读取，便于后续接队列、数据库或 RAG 管线。

如果要在浏览器或 WASM 环境处理文件，再安装 @firecrawl/pdf-inspector-wasm；检查点是调用前必须 await init()，输入必须是 Uint8Array，而不是直接把文件路径交给 WASM 入口。

记录每份样本的 pdf_type、markdown 是否为空、Markdown 长度和处理耗时；检查点不是“跑通一次”，而是能否把 scanned、image_based 和 mixed 样本从 text_based 样本里稳定分出来。

BASH

git clone https://github.com/firecrawl/pdf-inspector.git cd pdf-inspector pip install maturin maturin develop --release python - <<'PY' import pdf_inspector result = pdf_inspector.process_pdf("document.pdf") print(result.pdf_type) print(result.markdown) PY npm install @firecrawl/pdf-inspector npm install @firecrawl/pdf-inspector-wasm

这段命令闭环覆盖了三个动作：获取源码、构建 Python 绑定、调用 process_pdf 并打印验收结果。后两行 npm install 不会自动运行 Node.js 示例，它们用于确认 README 给出的 Node 和 WASM 包入口可安装。真正接入 Node.js 时，需要在自己的脚本里按照 README 示例引入 readFileSync、processPdf 和 classifyPdf；浏览器侧则按 README 先 init，再处理 Uint8Array。

如果 Python 调用阶段失败，先区分是构建失败还是样本失败。构建失败通常发生在 maturin develop --release 阶段，应该检查 Python 版本和 Rust 扩展构建环境；样本失败则发生在 process_pdf 之后，应该换成另一份已知可复制文本的 PDF 重试。不要在第一份扫描件上得不到 markdown 就判断项目不可用，因为它本来就把 scanned 和 image_based 当成需要分流的对象。

TECH NOTE

命令与配置：能确认的配置很少，但边界反而清楚

pdf-inspector 的配置证据主要来自 pyproject.toml，而不是 .env。素材里没有给出 API endpoint、Token、数据库地址或云服务密钥，这与项目定位一致：它是本地库，不是托管 API。写入配置时不要凭空添加 PDF_INSPECTOR_API_KEY、OCR_ENDPOINT 之类的环境变量；如果你的系统需要 OCR 或对象存储，那是你自己的下游集成，不属于 pdf-inspector README 已经证明的能力。

ENV

[build-system] requires = ["maturin>=1.0,=3.8"  [tool.maturin] features = ["python"]

这个配置块值得读两点。第一，requires-python >=3.8 给了 Python 接入的最低版本边界；如果你的线上环境仍在更低版本，应该先升级运行时，而不是把 pdf-inspector 硬塞进去。第二，features = ["python"] 说明 Python 绑定是 maturin 构建过程的一部分，CI、容器镜像或本地开发机都要能完成这个构建流程。对只用 Node.js 包的项目来说，可以不经过 Python 绑定，但仍要在部署环境里验证 npm 包是否能安装并运行。

目录结构也给出了能力边界。README 摘录列出 src/lib.rs 是 Public API、PdfOptions builder 和 convenience functions；python.rs 是 PyO3 Python bindings；types.rs 放 TextItem、TextLine、PdfRect、ItemType 等共享类型；text_utils.rs 处理 CJK、RTL、ligatures、bold/italic 等字符和文本辅助；process_mode.rs 定义 DetectOnly、Analyze、Full；detector.rs 做不完整加载文档的快速 PDF 类型检测；glyph_names.rs 负责 Adobe Glyph List 到 Unicode 的映射；tounicode.rs 解析 CID 编码文本的 ToUnicode CMap。

这些文件名说明它并不是简单地把页面文本拼接出来。ToUnicode、glyph names、CJK、RTL、连字、粗斜体识别，都是 PDF 文本抽取里容易踩坑的位置；process mode 和 detector 则说明项目关注“先检测、再分析、再完整处理”的成本分层。对开发者来说，合理用法不是一上来把它当万能解析器，而是在入口处先调用轻量分类，再决定是否进入 Full 级别处理或交给其他工具。

TECH NOTE

工作流拆解：把 pdf_type 当作路由信号，而不是展示字段

图 1｜pdf-inspector 的组件关系与运行架构

在真实流程里，pdf_type 不应该只打印在日志里。它更适合作为下一步动作的条件。text_based 可以进入 Markdown 清洗、分块、索引或数据库写入；scanned 和 image_based 应该进入 OCR 或人工复核；mixed 则需要更谨慎，可能部分页面能提取文本，部分页面仍需要 OCR。这样做的好处是把失败提前，而不是等到问答系统返回空答案、摘要系统漏页、字段抽取结果异常时再回头排查。

最小数据流可以很朴素：输入是 document.pdf 或一批 PDF 文件；第一步调用 process_pdf 或 processPdf；第二步读取 pdf_type；第三步只对 markdown 非空且类型合适的文件进入下游；第四步把 scanned、image_based、mixed 的文件名、分类结果和失败原因记录下来。这个流程里 pdf-inspector 不负责数据库、不负责消息队列、不负责 OCR，但它给了一个稳定的分岔点。

如果你已经在做文档 RAG，这个分岔点尤其有用。很多 RAG 失败样本不是 embedding 模型的问题，而是源文本一开始就抽错了。pdf-inspector 官方基准里 reading order 为 0.915，tables 为 0.814，说明它在原生文本 PDF 的阅读顺序和表格结构上有一定优势；但这个成绩来自 opendataloader-bench 的 200 份 PDF、本地非模型解析、禁用 OCR 条件。它不能外推成“任何 PDF 都能高质量解析”，也不能替代你自己的样本验收。

对 Node.js 项目，最实际的接法是把 @firecrawl/pdf-inspector 放在上传后的第一道处理任务中。读取文件 buffer，调用 processPdf，拿到 pdfType 和 markdown；如果 pdfType 是 TextBased 且 markdown 有内容，再继续分块；如果是 Scanned 或 ImageBased，直接标记为需要 OCR。对浏览器侧工具，WASM 包可以让用户本地预检查 PDF 类型，减少不必要的上传，但要先测试大文件在浏览器内存里的表现。

TECH NOTE

验收清单：不要只看能否打印 Markdown

图 2｜pdf-inspector 的通过信号、权限边界与停止条件

pdf-inspector 的验收要分成“能运行”和“值得接入”两层。能运行只需要 import 成功、process_pdf 返回结果、pdf_type 能打印；值得接入则要看分类稳定性、结构输出和失败样本比例。尤其是在团队准备把它放进批处理前，不能只用 README 示例跑一份 document.pdf 就结束。

验收指标要至少记录四项：每份 PDF 的 pdf_type、markdown 是否为空、Markdown 字符长度或行数、处理耗时；如果目标是表格或报告，还要人工抽查阅读顺序和表格结构是否足够进入下游。

权限和隐私边界比较清楚：pdf-inspector 是本地 Rust 库，README 没有要求 API key 或外部服务；但你自己的接入层如果把 PDF 上传到对象存储、OCR 服务或日志系统，隐私边界就已经不再由 pdf-inspector 单独决定。

不适合扩大使用的失败条件很明确：扫描件占比高、mixed 文件经常漏页、Markdown 表格结构不能满足抽取需求、maturin 构建在目标部署环境不稳定，或者浏览器 WASM 处理大文件时内存不可控，都应该暂缓全量替换。

分类结果要和人工抽样对照。至少挑出 text_based、scanned、image_based、mixed 各若干份样本复核；如果分类经常与人工判断不一致，后面的 OCR 路由和 RAG 入库都会被污染。

性能验收不能直接照搬官方 0.470s。官方数字是在 Apple M4 Pro、200 份 opendataloader-bench 文档、五次轮换完整运行并排除预热的条件下得到的；你的服务器、文件大小、并发方式和 I/O 路径都会改变结果。

失败回退也要提前写好。对 text_based 但 markdown 为空的文件，不要直接丢弃，应该保留原文件路径和分类结果，进入复核队列；对 scanned 和 image_based 文件，不要反复重试本地文本提取，应该改走 OCR；对 mixed 文件，不要假设 Markdown 已覆盖所有页面，最好把它标记成需要额外检查的中间状态。这个策略比“解析失败就重跑三次”更省时间。

TECH NOTE

取舍判断：今天该不该把它放进你的 PDF 流程

pdf-inspector 短期最值得试的点，是把 PDF 类型判断前置化。它适合那些已经有一批 PDF、需要本地处理、不想把所有文件都送去 OCR、又需要比较干净 Markdown 的开发者。尤其是报告、研究论文、财务文件、发票、法律 PDF 这类原生文本占比较高的材料，可以先拿 20 到 50 份真实样本跑一轮，看分类和 Markdown 质量是否足够进入下游。

不适合的人群也很明确。如果你的主要材料来自扫描仪、手机拍照、图片归档，或者业务目标是识别印章、手写字、复杂版面视觉关系，pdf-inspector 只能做入口判断，不能替你完成 OCR 和视觉理解。如果你的团队没有 Rust 扩展构建经验，也要先验证 maturin develop --release 在本地、CI 和部署镜像里是否稳定，不要等接入主流程后才发现构建链路卡住。

和 PyMuPDF4LLM、MarkItDown、LiteParse、OpenDataLoader 这类工具相比，pdf-inspector 在 README 给出的基准里强调的是本地、非模型、禁用 OCR 条件下的速度、阅读顺序和表格表现。这个比较有参考价值，但不是最终选型结论。选型时最应该问的不是“榜单上谁最高”，而是“我的 PDF 样本里扫描件占多少、表格是否关键、解析失败如何回退、隐私是否允许外部服务”。

DECISION

今天可以试的人：正在做文档导入、RAG、报告解析、合同或发票文本抽取，并且手里有较多原生文本 PDF 的开发者，可以先 clone firecrawl/pdf-inspector，按 README 的 maturin 和 process_pdf 路线跑 20 份真实样本。应该先观望的人：主要处理扫描件、照片 PDF、手写内容或强依赖 OCR 的团队，不要把它当完整文档理解方案。试用时看三个指标：pdf_type 与人工判断的一致率、markdown 对阅读顺序和表格结构的保留程度、在你自己的机器和部署环境里的单文件耗时与构建稳定性。

下一步动作很具体：先用 Python 路线跑通 document.pdf，再换成你自己的三类样本；如果结果稳定，再把 pdf_type 接到下游路由，而不是只把 markdown 存起来。能做到这一点，pdf-inspector 就不只是一个 Trending 项目，而是 PDF 流程里一个低成本的前置闸门。