3 步跑通 pdf-inspector：PDF 检测与转 Markdown

3 步跑通 pdf-inspector：PDF 检测与转 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-inspector 是一个用 Rust 写的本地 PDF 处理库，它先判断一份 PDF 是文本型还是扫描型，再决定走本地提取还是 OCR，把文本型文档直接转成干净的 Markdown。如果你不想把每一页都丢给昂贵的 OCR 服务，这个库就是为这条路由逻辑做的。

🎯 它是什么：本地 PDF 路由与提取

一句话定位：一个纯本地、无外部服务的 PDF 分类 + 文本提取 + Markdown 转换引擎。下面这些数字来自它的 README 基准：

指标	数值
分类耗时	约 10–50ms
文本型 PDF 处理	本地 < 200ms
200 份文档综合分	0.875（基准最高）
阅读顺序 NID / 表格 TEDS	0.915 / 0.814
绑定	Rust / Python / Node.js / WASM

它只做三件事：分类（TextBased / Scanned / ImageBased / Mixed）、提取带坐标的文本、转 Markdown，默认不碰 OCR。

📦 从 0 到第一次运行：装好并看到第一个结果

预编译 wheel 覆盖 CPython ≥3.8 的 Linux、macOS、Windows。装完直接跑，两条命令就能出结果：

pip install pdf-inspector

import pdf_inspector r = pdf_inspector.process_pdf("document.pdf") print(r.pdf_type) # text_based / scanned / image_based / mixed print(r.markdown) # Markdown 字符串，扫描页可能为 None

process_pdf一次调用就完成"分类 + 提取 + 转 Markdown"，markdown就是最终产出。

⚡ 高频用法：三种典型场景

只分类不提取：毫秒级路由

管线里大多数 PDF 其实不用 OCR。detect_pdf只做分类，不解析全文，毫秒级返回：

info = pdf_inspector.detect_pdf("document.pdf") print(info.pdf_type) # 四类之一 print(info.confidence) # 0.0 - 1.0 print(info.pages_needing_ocr) # 缺文本层的页码（注意：1 索引） if info.pdf_type == "text_based" and info.confidence > 0.8: # 本地提取即可，省掉 OCR 调用 ...

只转指定页：拿坐标和字体

做布局分析或二次排版时，pages只处理你需要的页，每个文本项带 X/Y 坐标、字体和字号：

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

扫描件按需 OCR

真要走 OCR 时，process_pdf_with_ocr只对被判为需要 OCR 的页做处理，干净文本页不会加载 OCR 运行时：

ocr = pdf_inspector.process_pdf_with_ocr("scan.pdf") print(ocr.pages_routed_to_ocr) # 实际走了 OCR 的页 print(ocr.markdown)

🚧 边界与避坑：这些坑别踩

• 两套页码索引不一致：process_pdf(pages=...)和extract_text_with_positions(pages=...)用 0 索引；而detect_pdf返回的pages_needing_ocr是 1 索引。混用会差一页，这是最常见的报错来源。
• markdown可能为 None：纯扫描、无文本层的页提取不出内容，别假设它一定有字符串，先判is None。
• OCR 有额外依赖：Python / Node 包内不打包模型，路由到 OCR 时才需要单独装 PDFium 和 ONNX Runtime 并配好库路径；不接 OCR 就完全不用管。
• 字体编码损坏：result.has_encoding_issues为 True 时说明字体编码有问题，直接提取会乱码，应回退 OCR。
• 表格与多列是启发式：依赖矩形绘图操作和文字对齐，复杂版式看is_complex_layout，别指望 100% 还原。
• 非主流平台要 Rust 工具链：wheel 之外（如某些 ARM 服务器）需从源码编译，先装好 Rust 工具链。

📚 接下来看哪里

• 完整 Python API
• Node.js 绑定
• WebAssembly 浏览器用法
• OCR 运行时配置
• 性能基准与复现

下一步：拿一份你手头的报告或发票 PDF，先跑detect_pdf看类型和置信度，再用process_pdf检查markdown输出是否够用，不够再决定要不要接 OCR。

【免费下载链接】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