三步跑通：pdf-inspector PDF 文本提取与智能类型检测快速指南-开发者社区

三步跑通：pdf-inspector PDF 文本提取与智能类型检测快速指南

【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspector

手里一批 PDF，想抽文字转成 Markdown，第一步就卡住：哪些是原生文本可以直接抽，哪些是扫描件得先过 OCR？全部丢给 OCR 服务，一半时间和钱白花；直接硬抽，扫描件又拿不到任何文字。pdf-inspector就是为这个决策环节做的——一个纯 Rust 的 PDF 提取与类型判定库，10–50 毫秒采样内容流，告诉你哪些文件本地就能抽、哪些页面需要 OCR。下面是 pdf-inspector 的 PDF 提取上手教程，从安装到跑出第一份 Markdown，只需要三步。

项目速览：先分流，再处理

pdf-inspector 的核心思路是"先分流，再处理"。文档只加载解析一次，detector 采样内容流（找Tj/TJ文本操作符和Do图像操作符），把 PDF 归入 TextBased / Scanned / ImageBased / Mixed 四类，并给出 0.0–1.0 的置信度和逐页的 OCR 路由清单。原生文本 PDF 直接进提取管线：带坐标和字体信息、支持多栏阅读顺序、能识别表格，最终产出干净的 Markdown，整个过程 200 毫秒量级。官方在 200 份 PDF 的基准语料上，综合质量分 0.875，阅读顺序、表格得分和速度在参测的本地引擎中全部排第一。

项目名片：

实现语言：纯 Rust，本地处理，无外部服务依赖
安装方式：pip（Python）、npm（Node.js / 浏览器 WASM）、cargo（Rust / CLI）
绑定：Python、Node.js（napi-rs）、浏览器 WebAssembly
许可：MIT
默认不含 OCR 模型，只有页面被路由到 OCR 时才加载外部运行时

三步跑起来

第 1 步：装

pip install pdf-inspector

预编译 wheel 覆盖 CPython 3.8+ 的 Linux / macOS / Windows，不需要 Rust 工具链。Node.js 用户用npm install @firecrawl/pdf-inspector，浏览器端用对应的-wasm包；想从源码开发的话，clone 仓库后用 maturin 构建：

git clone https://gitcode.com/GitHub_Trending/pdf/pdf-inspector pip install maturin && maturin develop --release

第 2 步：写最小示例

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

第 3 步：运行看输出

text_based # 第 1 章 概述 ...（带标题、列表、表格的 Markdown 全文）

一次调用同时返回类型、Markdown、页数、耗时、是否有表格/多栏页等字段，完整打印版见仓库里的 examples/basic_usage.py。

先看这两个核心功能

快速类型检测：决定要不要走 OCR

场景：流水线收到每个文件都要回答"本地抽还是转 OCR 服务"。

info = pdf_inspector.detect_pdf("document.pdf") print(info.pdf_type) # 类型 print(info.confidence) # 0.0 – 1.0 print(info.pages_needing_ocr) # 缺原生文本的页码，1 起始

结果：300 页以上的 PDF 也是毫秒级出结果，且pages_needing_ocr让你按页路由，而不是整份文档一刀切。Rust 侧还可以把扫描策略从默认的 EarlyExit 换成Sample(n)采样，超大文件进一步省时间。

带位置信息的提取：知道文字在哪、多大、什么字体

场景：要还原版面、定位某个区域、或者做字体级校验。

items = pdf_inspector.extract_text_with_positions("document.pdf", pages=[0]) for item in items[:5]: print(f"'{item.text}' at ({item.x:.0f}, {item.y:.0f}) size={item.font_size}")

每个文本项都带 X/Y 坐标、宽高、字号、粗体/斜体/下划线标记和页码。表格检测和多栏阅读顺序识别都是基于这些位置信息做的，想理解"它怎么认出表格"可以从这里入手。

新手最容易踩的 4 个坑

Markdown 返回 None。现象：process_pdf跑完markdown是空。原因：这份 PDF 是扫描件或图像型，没有原生文字层，本地抽不出来。处理：看pages_needing_ocr确认缺失范围；配好 PDFium 和 ONNX Runtime 环境后可改用process_pdf_with_ocr只把需要的页走本地 OCR，否则把这份文档转给外部 OCR 服务即可。
页码下标两套标准。现象：pages=[0, 1, 2]传进去没问题，结果里pages_needing_ocr却是[1, 2, 3]。原因：调用方入参用 0 起始，PDF 页码类字段用 1 起始，两套约定并存。处理：传参前对照 docs/python.md 的类型注释确认每个字段的起始位，别凭感觉换算。
把置信度当成抽取成功率。现象：text_based但 confidence 只有 0.87，不敢用。原因：confidence 表示"分类有多确定"，不是"抽出来的文字有多准"。处理：类型和置信度组合判断；是 scanned/mixed 时直接看pages_needing_ocr做逐页路由，比纠结数值更可靠。
以为 OCR 开箱即用。现象：pip 包只有几 MB，一调 OCR 相关接口就报缺库。原因：wheel 不内置 PDFium、ONNX Runtime 和模型文件，只有页面真正被路由到 OCR 时才需要它们。处理：不做 OCR 可以完全忽略；要用就先按 docs/ocr-runtime.md 配好环境变量和模型缓存。