智能分类
采样内容流,10–50ms 内判定 TextBased / Scanned / ImageBased / Mixed,返回置信度(0.0–1.0)与逐页 OCR 路由。
文本提取
位置感知提取:含字体信息、X/Y 坐标,自动多栏阅读顺序。
Markdown 转换
识别 H1–H4 标题、列表、代码块、表格、粗斜体、URL 与分页符。
表格检测
双模式:基于矩形的检测 + 基于文本对齐的启发式。兼顾财务表格、脚注与跨页续表。
CID 字体支持
对 Type0 / Identity‑H 字体执行 ToUnicode CMap 解码,覆盖 UTF‑16BE、UTF‑8 与 Latin‑1。
多栏布局
自动探测报纸式栏位、顺序阅读,并支持 RTL(从右到左)文本。
编码诊断
自动标记损坏的字体编码,让调用方准确回退到 OCR。
单次加载
文档仅解析一次,检测与提取共享,杜绝冗余 I/O。
浏览器 WebAssembly
在浏览器与 Web Worker 中本地运行同一 Rust 解析器,内置 CMap,无需服务器往返。
轻量级
纯 Rust,无 ML 模型、无外部服务,仅依赖 lopdf。
§ 02 · 基准测试
P.02
与五个本地引擎的对照。
| 引擎 | 总体 | 阅读顺序 NID | 表格 TEDS | 标题 MHS | 速度 / 200 文档 |
|---|---|---|---|---|---|
| pdf‑inspector 本品 | 0.875 | 0.915 | 0.814 | 0.788 | 0.470 s |
| liteparse | 0.873 | 0.913 | 0.693 | 0.811 | 0.750 s |
| opendataloader | 0.831 | 0.902 | 0.489 | 0.739 | 2.569 s |
| pymupdf4llm | 0.735 | 0.886 | 0.401 | 0.424 | 17.117 s |
| markitdown | 0.589 | 0.844 | 0.273 | 0.000 | 16.165 s |
评测于 2026‑07‑31 · Apple M4 Pro · 版本 pdf‑inspector 0.2.6 / LiteParse 2.10.1 / OpenDataLoader 2.2.1 / PyMuPDF4LLM 0.2.0 / MarkItDown 0.1.5。分数 0–1,越高越好;速度为五次交替运行中位数(排除预热)。完整可复现结果 ↗
在需要速度、阅读顺序与表格结构的原生文本 PDF 上,本品总体、阅读顺序与表格三项均居首,且整体运行最快。适合将报告、研究论文、财务文档、发票与法律文件作为无需 OCR 延迟与额外基建的默认选择。可配合配对基准工具 ↗自测。
§ 03 · 快速上手
P.03
五种语言,三十秒上路。
# 安装
pip install maturin
maturin develop --release
import pdf_inspector
result = process_pdf("document.pdf")
print(result.pdf_type) # text_based / scanned / image_based / mixed
print(result.markdown) # Markdown 字符串或 None
// npm install @firecrawl/pdf-inspector
import { readFileSync } from 'fs';
import { processPdf, classifyPdf } from '@firecrawl/pdf-inspector';
const result = processPdf(readFileSync('document.pdf'));
console.log(result.pdfType); // TextBased · Scanned · ImageBased · Mixed
console.log(result.markdown); // Markdown 字符串或 null
// npm install @firecrawl/pdf-inspector-wasm
import init, { processPdf } from '@firecrawl/pdf-inspector-wasm';
await init();
const response = await fetch('/document.pdf');
const pdf = new Uint8Array(await response.arrayBuffer());
const result = processPdf(pdf);
console.log(result.pdfType);
console.log(result.markdown);
// [dependencies] pdf-inspector = "0.1"
use pdf_inspector::process_pdf;
let result = process_pdf("document.pdf")?;
println!("Type: {:?}", result.pdf_type);
if let Some(markdown) = &result.markdown {
println!("{}", markdown);
}
# 安装 CLI
cargo install pdf-inspector
# 转换为 Markdown
pdf2md document.pdf
# JSON 输出(用于管道)
pdf2md document.pdf --json
# 带位置 TextItem JSON(含 is_underline 元数据)
pdf2md document.pdf --items-json
# 纯 markdown(无头部)
pdf2md document.pdf --raw
# 插入分页标记 <!-- Page N -->
pdf2md document.pdf --pages
# 仅处理指定页面
pdf2md document.pdf --select-pages 1,3,5-10
# 仅检测(不提取)
detect-pdf document.pdf
detect-pdf document.pdf --json
# 检测 + 布局分析(表格、栏位)
detect-pdf document.pdf --analyze --json
从源码运行时:cargo run --bin pdf2md -- document.pdf 或 cargo run --bin detect-pdf -- document.pdf。
§ 04 · 架构
P.04
一次加载,两次使用。
同一份解析共享于检测与提取阶段,杜绝冗余 I/O。
PDF 字节
│
├─► detector → PdfType(TextBased / Scanned / ImageBased / Mixed)
│
└─► extractor
├─ fonts → 字体宽度 · 编码
├─ content_stream → PDF 操作符 → TextItems + PdfRects
├─ xobjects → Form XObject 文本 · 图像占位符
├─ links → 超链接 · AcroForm 字段
└─ layout → 栏位 → 行分组 → 阅读顺序
│
├─► tables
│ ├─ detect_rects → 基于矩形(并查集)
│ ├─ detect_heuristic → 基于对齐
│ ├─ grid → 列/行 → 单元格
│ └─ format → 单元格 → Markdown 表格
│
└─► markdown
├─ analysis → 字体统计 · 标题层级
├─ preprocess → 合并标题 · 首字下沉
├─ convert → 行循环 · 表格/图像插入
├─ classify → 图注 · 列表 · 代码
└─ postprocess → 清理 → 最终 Markdown§ 05 · 分类原理
- 01解析 xref 表与页面树(无需完整对象加载)
- 02依
ScanStrategy选择页面(默认:全扫 + 提前退出) - 03在内容流定位
Tj/TJ(文本)与Do(图像)操作符 - 04按采样页中文本操作符的存在进行分类
扫描策略
| 策略 | 行为 | 最佳适用 |
|---|---|---|
| EarlyExit默认 | 全扫,遇首个非文本页即停 | 把 TextBased 路由到快速提取 |
| Full | 全扫,不提前退出 | 精确 Mixed / Scanned 判定 |
| Sample(n) | 均匀采样 n 页(首/末/中) | 速度优先的超大 PDF |
| Pages(vec) | 仅扫指定页(1 起) | 调用方已知检查范围 |
§ 06 · 输出规格
| 标题 H1–H4 | 相对正文字号层级 · 0.5pt 聚类 |
| 粗体 / 斜体 | 字体名模式 Bold / Italic / Oblique |
| 列表 | • - * ○ ● ◦ · 1. 1) (1) · a. a) (a) |
| 代码块 | 等宽字体(Courier 等)· 关键字检测 |
| 表格 | 矩形检测 + 对齐启发式 |
| 图注 | "Figure / Table / Source:" 前缀 |
| 上下标 | 基线字体大小与 Y 偏移 |
| URL | 转为 Markdown 链接 |
| 连字符 | 重连跨行断词 |
| 页码 / 点串 | 过滤页码 · 折叠为 " ... " |
| 首字下沉 | 大首字母与正文合并 |
§ 附录 · 版权页
P.06
文档 · 目录与资料
出版信息
本页排版,正如同 PDF 中的每一页:先分类,再提取,后呈现。