pdf-inspector 快速上手指南：10ms 识别 PDF 类型，文本型 PDF 200ms 转 Markdown-平芜编程栈

pdf-inspector 快速上手指南：10ms 识别 PDF 类型，文本型 PDF 200ms 转 Markdown

【免费下载链接】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 后的第一问是：哪些能直接抽文本，哪些是必须走 OCR 的扫描件？文本型本地处理 200ms 以内就够，扫描件却要 2–10s 的 OCR 服务。pdf-inspector 是一个用 Rust 写的 PDF 检查库：约 10–50ms 判定 text_based / scanned / image_based / mixed 四种类型，返回置信度和按页的 OCR 路由清单，从而跳过约 54% 根本不需要 OCR 的文档。

验证安装是否成功的第一条命令

pip install pdf-inspector

预编译 wheel 覆盖 Linux / macOS / Windows（CPython ≥3.8），其他平台需从源码构建。装完后拿手头任意一份 PDF 跑下面这行，输出类型和处理耗时毫秒数：

python -c "import pdf_inspector as p; r=p.process_pdf('document.pdf'); print(r.pdf_type, r.processing_time_ms)"

看到text_based 148这类输出就说明通了——一个文本型 PDF 通常 200ms 内跑完。

一行代码把文本型 PDF 转成带结构的 Markdown

import pdf_inspector # 一次调用完成 检测 + 抽取 + Markdown 转换 result = pdf_inspector.process_pdf("document.pdf") print(result.pdf_type) # "text_based" / "scanned" / "image_based" / "mixed" print(result.markdown) # Markdown 字符串或 None

输出不是原始文本堆砌：按字号比例推断 H1–H4 标题，识别项目符号和编号列表，等宽字体自动成代码块，表格用「绘图矩形 + 文本对齐」双模式检测，URL 转成链接，页码被过滤，多栏版面按阅读顺序重排。质量上有 opendataloader-bench 对比数据（200 份 PDF，Apple M4 Pro，2026-07-31 更新）：pdf-inspector 综合 0.875、阅读顺序 0.915、表格 0.814、跑完整个语料 0.470s，均为参评的 5 个本地引擎中最高。只处理部分页面时传pages=[0, 1, 2]，页码从 0 开始。

判断文件是不是扫描件：走快速检测模式

只想知道类型而不做抽取时用detect_pdf，它 10–50ms 出结果，300 多页的 PDF 也能毫秒级判定：

# 只做检测、不抽文本：10–50ms info = pdf_inspector.detect_pdf("document.pdf") print(info.pdf_type, info.confidence) # 类型与置信度（0.0–1.0） print(info.pages_needing_ocr) # 缺文本的页，用于按页路由 OCR

这就是它最典型的路由用法：先分类（约 20ms），是 text_based 就本地抽取（约 150ms），否则才送去 OCR（2–10s）。

markdown 返回 None 时：用选择性 OCR 处理扫描页

文件是扫描件时result.markdown会是 None——这不是失败，而是库在告诉你「这份 PDF 没有可抽的文本」。Python 包内置选择性 OCR 管线：

# 只对原生抽取被拒的页做 OCR；干净文本 PDF 不会加载 OCR 运行时 ocr = pdf_inspector.process_pdf_with_ocr("document.pdf") print(ocr.pages_routed_to_ocr) # 实际走了 OCR 的页

注意 wheel 不带 PDFium、ONNX Runtime 和模型，只有页面被路由到 OCR 时才会加载它们，PP-OCRv6 Small 模型在首个 OCR 页时下载并校验。离线环境传offline=True加model_directory指向本地模型即可，细节见 OCR 运行时指南。

拿到文本的 X/Y 坐标和字体信息

# 每个文本项带坐标、字体、字号，适合做定位或高亮 items = pdf_inspector.extract_text_with_positions("document.pdf") for item in items[:5]: print(f"'{item.text}' at ({item.x:.0f}, {item.y:.0f}) {item.font} {item.font_size}")

带标签结构的 PDF 还可以用extract_structure_elements恢复真实标题层级。

Node.js 与浏览器绑定：各一行安装命令

npm install @firecrawl/pdf-inspector # Node.js npm install @firecrawl/pdf-inspector-wasm # 浏览器 WebAssembly

Rust 侧用cargo install pdf-inspector装 CLI，pdf2md document.pdf --json、detect-pdf document.pdf --analyze --json的输出都适合进管道。

易踩的四个坑：None、两套页码索引、编码告警与 OCR 默认关闭

markdown 可能为 None：detect_pdf和无法抽取的 PDF 都返回 None，用if result.markdown:先判断。
页码有两套索引：process_pdf的 PdfResult 里pages_needing_ocr是 1 基，classify_pdf的 PdfClassification 里是 0 基，extract_pages_markdown的 pages 参数也是 0 基，混用会偏移一页。
has_encoding_issues：字体编码损坏（部分中文 PDF 常见）时该字段为 True，抽出的文本可能乱码，建议回退 OCR。
默认流程不含 OCR：process_pdf是纯抽取，OCR 只有显式调用process_pdf_with_ocr才会加载运行时。