你大概率默认了一件事：把 PDF 变成干净的 Markdown，就得上 OCR 或者视觉大模型。pdf-inspector 干的第一件事，是把这个前提推翻。它先问一句：这份 PDF 里到底有没有现成文字？哪些页能直接读，哪些页才真需要 OCR？
它的做法很克制。读 PDF 的内部结构，看字体编码、文本操作符、图像覆盖度，几十毫秒就判断出它属于 TextBased、Scanned、ImageBased 还是 Mixed，顺手给出置信度和哪些页需要 OCR。判断清楚了，文本页本地提取直出 Markdown，扫描页才交给 OCR。
为什么这件事值得专门做个库？Firecrawl 每天的文档摄入量不是小数，他们公开说实际处理的 PDF 里大约 54% 根本不需要 OCR。报告、论文、发票、合同、法律文件大多由软件生成，里面就躺着完整的文字层。过去我们图省事，收到 PDF 就丢给 OCR，又慢又贵还常常不如原生文字准。pdf-inspector 就是这道分诊台。
我一开始也把它当成又一个 PDF 转 Markdown 轮子。翻完 README 和几篇独立评测之后，判断收窄了：轮子不少，但把“要不要 OCR”做成每页级路由层的，它是头一个。这篇文章就想讲清楚，这个路由层到底值不值得你接进管线，以及它在哪些地方会悄悄让你踩坑。
核心亮点
最让我惊讶的不是提取质量，是它对 OCR 的态度。绝大多数 PDF 工具把 OCR 当默认路径，pdf-inspector 反过来，默认完全不碰 OCR。这个设计选择决定了它的速度、成本和失败模式，也决定了它和 marker、MinerU 那类“重型 OCR 优先”方案根本不是一种东西。
分类器的工作方式解释了为什么快。它不加载整篇文档，只解析 xref 表和页面树，然后采样内容流里的 Tj/TJ（文本操作符）和 Do（图像操作符）。有文本操作符就判文本页，有图像操作符就判扫描页。300 多页的 PDF 毫秒级分完类，没有光栅化、没有布局模型、没有推理。
架构上它是一颗 Rust 内核，外面套了四层壳。核心 detector 和 extractor 共享一次文档加载，避免重复 I/O；extractor 往下拆成字体、内容流、XObject、链接、布局五大块，布局再分出表格检测和 Markdown 转换两条支路。Python 走 PyO3、Node 走 napi-rs、浏览器走 wasm-bindgen，三套绑定共用同一份解析逻辑。
真正拉开差距的是 per-page 路由，而不是简单的“整篇是不是扫描件”。它给你一份 pages_needing_ocr 列表，精确到页码。你的管线可以只把这几页送进视觉模型或 OCR，其余页本地直出。这个粒度，是它敢说自己让 Firecrawl 托管的 Fire-PDF 引擎比旧管线快 3.5 到 5 倍的原因。
文本提取本身也不含糊。位置感知，带字体信息和 X/Y 坐标，自动排好多栏阅读顺序；Markdown 转换覆盖 H1-H4、列表、代码块、表格、粗斜体、链接和分页符。表格检测是双模的，既看 PDF 绘制指令的矩形边界，也看文本对齐的启发式，能处理金融表格、脚注和跨页续表。
我把官方基准摆出来，因为它和同类拉开了可视差距。下面这份 opendataloader-bench 200 份语料的对比里，pdf-inspector 综合 0.875 排第一，整库跑完 0.47 秒，而 PyMuPDF4LLM 要 17.1 秒。
| 引擎 | 综合得分 | 阅读顺序 | 表格 | 标题 | 200 份耗时 |
|---|---|---|---|---|---|
| pdf-inspector | 0.875 | 0.915 | 0.814 | 0.788 | 0.470s |
| liteparse | 0.873 | 0.913 | 0.693 | 0.811 | 0.750s |
| opendataloader | 0.831 | 0.902 | 0.489 | 0.739 | 2.569s |
| pymupdf4llm | 0.735 | 0.886 | 0.401 | 0.424 | 17.117s |
| markitdown | 0.589 | 0.844 | 0.273 | 0.000 | 16.165s |
数据好看，但我得泼盆冷水：这份基准是 Firecrawl 自己跑的，OCR 全程关闭，只比本地无模型解析引擎。它证明的是“文本型 PDF 场景里 pdf-inspector 又快又准”，不是“它能替代 OCR 方案”。结论的边界要划清楚。
快速体验
装起来几乎没有门槛。Rust 生态直接 cargo add，Python 和 Node 都有官方包，浏览器里还能跑 WebAssembly 版。我先在命令行试了最轻的路径，一条命令就能把 PDF 变成 Markdown。
# 安装 CLI 工具
cargo install pdf-inspector
# 把 PDF 转成 Markdown
pdf2md document.pdf
# 只做检测，不提取
detect-pdf document.pdf --json
最小可运行示例更接近“调一个函数”。Python 这边 API 面小得离谱，process_pdf 一把梭，返回类型、Markdown 和可选的 OCR 路由信息都在结果对象里。
import pdf_inspector
result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type) # "text_based", "scanned", "image_based", "mixed"
print(result.markdown) # Markdown 字符串或 None
# 选择性 OCR，纯文本页不会加载外部 OCR 运行时
ocr = pdf_inspector.process_pdf_with_ocr("document.pdf")
print(ocr.pages_routed_to_ocr)
真正上手后我发现一个坑得提前说。默认构建完全不含 OCR，Rust 和 CLI 要 OCR 得 cargo install pdf-inspector --features ocr --bin pdf2md，还得自己装 PDFium 和 ONNX Runtime 两个外部库。浏览器 WASM 版干脆就是纯提取，永远没有 OCR。
另外两个常见卡点来自社区实测。一是 CJK 字体在某些文档上仍有 open bug，中文 PDF 遇到冷门编码要留神；二是密集双栏排版偶尔翻车，跨页表格和旋转页也还没到稳的状态。用在生产前，先拿你自己的真实文档测一轮。但工具好不好用是一回事，你手上的 PDF 到底适不适合它，是另一回事。
适用场景与局限
不是所有 PDF 都该交给它。pdf-inspector 的强项是文本型文件，弱点恰好在它的反面。下面这张表帮你快速对号入座，看清它到底压不压得住你的场景。
| 场景 | 典型用户 | 优势 | 局限 |
|---|---|---|---|
| 文本型报告/论文/发票 | RAG、合同分析团队 | 本地 150ms 直出，零 GPU 成本 | 扫描页无能为力 |
| 大规模文档摄取管线 | 搜索、知识库服务 | 路由层省下绝大多数 OCR 账单 | 需自建 OCR 兜底 |
| 浏览器内解析 | 前端文档预览 | WASM 零服务端往返 | 不支持 OCR |
| 纯扫描件/图片 PDF | 档案数字化 | 会精准标记需 OCR 的页 | 自己不提取内容 |
如果你的 PDF 绝大多数是软件生成的文本型文件，它是最优解。54% 的省 OCR 比例放到真实业务里，省下的 GPU 账单相当可观。
光说不适合不够，不适用的情况我得逐条讲明白，而且每一条都给你配了明确的替代方案：
-
你是做扫描件批量数字化的：它只负责“告诉哪页要 OCR”，提取还得接 marker 或 MinerU 这类带 OCR 的方案。 -
你的文档以中文老旧编码、密集双栏为主：先拿样本测，别直接进生产，CJK 和双栏目前确有 open bug。 -
你要的是连图表都抠出来的端到端方案：开源版目前不提取图形，得另找 marker 或 MinerU。
聊完它能干嘛、不能干嘛，背后那支团队的成色才是决定它能不能长期跟的关键。
社区健康度
先看硬指标。这个项目 2026 年 2 月才开库，半年左右冲到约 15k Stars，Fork 约 1k，8 月初还以单日 +2,500 的速度登顶过 GitHub Trending。
| 指标 | 数据 | 说明 |
|---|---|---|
| Stars | 约 15k | 2026 年 8 月多源汇总 14.9k–15.8k，增速异常 |
| 核心维护者 | Firecrawl 团队 | 公司背书，Bus Factor 看公司优先级 |
| 协议 | MIT | 商业友好，可闭源集成 |
| 版本 | 1.17.0（2026-08-21） | 迭代极快，版本号跳跃明显 |
维护质量有亮点也有隐忧。亮点是有公司团队持续投入，CI 频繁，CMap 处理、NAPI/Python API 统一都在推进；隐忧是 commit 历史里大量由 Claude、Cursor Agent 代笔，人类 review 密度值得长期观察。
社区声音里最尖锐的一条来自评测区：“ms per page 是误导性的营销话术。决定用户留不留下的，是到底有多少乱七八糟的真实文档，扫描件、旋转页、2004 年打印机驱动导出的 PDF，能被正确解析出结构。”这句话戳中了基准没覆盖的盲区。
独立评测 andrew.ooo 也给了诚实的差评维度：开源版不做 OCR、不提取图形、基准是厂商自跑，而且 CJK 字体和密集双栏确有 open bug。这些不是黑料，是接进生产前必须评估的真实边界。但维护数据再漂亮，也架不住一个问题：它到底值不值得你长期跟？
洞察与判断
我的核心判断：把它当“路由层”用，它是 2026 年最值得接的 PDF 组件之一；把它当“OCR 替代品”用，你会失望。这两个定位一字之差，决定项目成败。
表面看它和 PyMuPDF4LLM、pdfplumber 是同类，都是提取文字。真正关键的差别在路由粒度。PyMuPDF4LLM 提取强但默认全量跑，pdf-inspector 多了一道每页级分诊，把 54% 不需要 OCR 的文档拦在 GPU 门外。对按量计费的管线，这笔账省的是真金白银。
趋势上我判断它在上升通道。不是因为 Stars 好看，是因为它背后是 Firecrawl 一套 deliberate 的文档解析战略：pdf-inspector 管 PDF，AnyDoc 管另外 14 种格式（docx、xlsx、pptx、epub 等），两者都已经在 /parse 和 /scrape 端点跑着。一个公司把核心基建开源，通常不会轻易砍。
但你得接受它的“半成品感”。版本号从 7 月底基准的 0.2.6 跳到 8 月的 1.17.0，这种跳跃要么是营销式版本对齐，要么意味着 API 还在剧烈变动。中文用户尤其要记住 CJK 和双栏那两个 open bug，别被英文基准的漂亮数字带偏。
还有个容易忽略的信号：commit 历史里大量提交由 Claude、Cursor Agent 代笔。这说明 Firecrawl 在用量产化的 AI 辅助开发，迭代速度快得吓人，但也意味着人类 review 的密度需要你长期盯。开源项目里，谁在合代码比谁在写代码更重要。
放到 PDF 解析这个赛道看，它填补的是“路由层”这块长期空白。marker、MinerU 在 OCR 端卷精度，PyMuPDF4LLM 在提取端卷速度，没人专门把“先判断要不要 OCR”做成独立、可嵌入的组件。这个空位被 Firecrawl 占了，而且占得很早。
顺带说一句，54% 这个“不需要 OCR”的比例也是 Firecrawl 自己公布的，不是独立审计。但它和基准里 pdf-inspector 在文本型语料上的压倒性表现能对上，所以我愿意先信一半，等社区拿更多真实文档验证。
说它好用和说它不够好用的，其实都没说到点子上。它把对的事做了，把难的事（扫描件、图表、怪异编码）留给了你和 OCR。这个取舍很务实，也很诚实。
如果哪天你要处理的不只是 PDF，记住 AnyDoc 这层。它把 pdf-inspector 当内核，一份调用覆盖 14 种格式，PDF 只是其中之一。
我会给它一个明确建议：文本型 PDF 为主的管线，现在就可以接；混合或扫描为主的，等 OCR 集成和 CJK 修复再动。
资源地址
上面的链接就摆在这了，最后落到你手上其实只有一件事要想清楚：接下来你怎么把它接进自己的管线。
先接路由层，别当 OCR 用
如果你已经在做 RAG 或文档摄取，且 PDF 以文本型为主，先把 pdf-inspector 当分诊台接在 OCR 前面。从一条 pdf2md document.pdf 命令开始，拿你自己的真实文档测一轮再决定。
如果你还在观望，盯两个指标：CJK 字体 bug 的修复进度，以及 OCR 集成的稳定性。这两点决定它是停留在好用的个人工具，还是能变成靠谱的生产依赖。
PDF 解析最贵的从来不是解析，是替那些本来就带文字的文档白付的 OCR 账单。先分诊，再花钱，这个顺序很多团队到现在还没理顺。