PDF Inspector:毫秒级PDF解析与智能分类实战指南

PDF字节    │    ├──► 分类器（detector）：采样→返回PDF类型    │    └──► 提取器（extractor）          ├── 字体 → 字体宽度、编码信息          ├── 内容流 → 遍历PDF操作符 → TextItems + PdfRects          ├── XObjects → Form XObject文本、图片占位符          ├── 链接 → 超链接、AcroForm表单字段          ├── 布局分析 → 栏检测→行分组→阅读顺序          ├── 表格检测          │     ├── 矩形检测（union-find合并重叠矩形）          │     ├── 启发式检测（对齐检测）          │     └── 网格化 → 列/行分配 → 单元格 → Markdown表格          └── Markdown生成                ├── 分析 → 字体统计、标题层级                ├── 预处理 → 标题合并、首字下沉处理                ├── 转换 → 行循环 + 表格/图片插入                ├── 分类 → 图表标题、列表、代码块识别                └── 后处理 → 清理 → 最终Markdown

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shsource ~/.cargo/envrustc --version

cargo --version

# 安装maturin（PyO3构建工具）pip install maturin# 克隆仓库git clone https://github.com/firecrawl/pdf-inspectorcd pdf-inspector# 构建Python绑定maturin develop --release# 验证导入python -c "import pdf_inspector; print('安装成功')"

npm install @firecrawl/pdf-inspector# 或bun add @firecrawl/pdf-inspector

[dependencies]pdf-inspector = { git = "https://github.com/firecrawl/pdf-inspector" }

git clone https://github.com/firecrawl/pdf-inspectorcd pdf-inspector# 将PDF转换为Markdowncargo run --bin pdf2md -- document.pdf# 仅检测（不提取）cargo run --bin detect-pdf -- document.pdf

import pdf_inspectorfrom pathlib import Pathimport sysdef smart_pdf_processor(pdf_path: str):    """    智能PDF处理器：自动判断PDF类型并选择最优处理路径    """    # 第一步：快速检测（不加载完整文档）    print("[1/3] 正在检测PDF类型...")    detection = pdf_inspector.detect_pdf(pdf_path)    print(f"  PDF类型: {detection.pdf_type}")    print(f"  置信度: {detection.confidence:.2f}")    print(f"  总页数: {detection.page_count}")    needs_ocr_pages = detection.pages_needing_ocr    if needs_ocr_pages:        print(f"  需要OCR的页面: {needs_ocr_pages}")    # 第二步：根据分类结果选择处理路径    if detection.pdf_type == "text_based":        print("[2/3] 文本型PDF → 使用本地提取")        return _extract_text_pdf(pdf_path)    elif detection.pdf_type == "mixed":        print("[2/3] 混合型PDF → 分页处理")        return _process_mixed_pdf(pdf_path, detection.pages_needing_ocr)    else:        print("[2/3] 扫描/图片型PDF → 应调用OCR服务")        return {"status": "ocr_required", "pages": detection.pages_needing_ocr}def _extract_text_pdf(pdf_path: str):    """全量提取文本型PDF"""    result = pdf_inspector.process_pdf(pdf_path)    print(f"  处理耗时: {result.processing_time_ms:.1f}ms")    print(f"  包含表格的页面: {result.pages_with_tables}")    print(f"  多栏布局: {result.is_complex_layout}")    # 保存Markdown    if result.markdown:        output_path = Path(pdf_path).with_suffix('.md')        output_path.write_text(result.markdown, encoding='utf-8')        print(f"[3/3] ✅ Markdown已保存至: {output_path}")    return {"status": "success", "markdown": result.markdown}def _process_mixed_pdf(pdf_path: str, needs_ocr_pages: list):    """处理混合型PDF：分页判断"""    # 按页提取Markdown    result = pdf_inspector.extract_pages_markdown(pdf_path)    for page_result in result.pages:        if page_result.needs_ocr:            print(f"  第{page_result.page+1}页 → 需要OCR")        else:            print(f"  第{page_result.page+1}页 → 文本提取 ({len(page_result.markdown)}字符)")    return {"status": "mixed", "needs_ocr_pages": needs_ocr_pages}# 执行示例if __name__ == "__main__":    if len(sys.argv) > 1:        result = smart_pdf_processor(sys.argv[1])        print(f"\n最终结果: {result}")    else:        print("用法: python processor.py <PDF文件路径>")

def extract_with_coordinates(pdf_path: str):    """提取文本及其位置坐标，可用于构建PDF预览高亮"""    items = pdf_inspector.extract_text_with_positions(pdf_path)    for item in items[:10]:  # 打印前10项        print(f"'{item.text}' 位于 ({item.x:.0f}, {item.y:.0f}) "              f"字体={item.font} 大小={item.font_size} "              f"加粗={item.is_bold} 斜体={item.is_italic}")    return items

import { readFileSync } from 'fs';import { classifyPdf, extractTextInRegions, PageRegions } from '@firecrawl/pdf-inspector';interface ProcessingResult {  success: boolean;  text: string;  ocrFallbackPages: number[];}async function smartPdfProcessor(filePath: string): Promise<ProcessingResult> {  const pdfBuffer = readFileSync(filePath);  // 第一步：全文档分类，确定哪些页面需要OCR  const classification = classifyPdf(pdfBuffer);  console.log(`PDF类型: ${classification.pdfType}`);  console.log(`置信度: ${classification.confidence}`);  console.log(`需要OCR的页面: ${classification.pagesNeedingOcr}`);  // 如果整个文档都是文本型，直接提取  if (classification.pdfType === 'TextBased') {    // 区域提取示例：提取全页（PDF标准尺寸为612x792点）    const pageRegions: PageRegions[] = [];    for (let i = 0; i < classification.pageCount; i++) {      pageRegions.push({        page: i,        regions: [[0, 0, 612, 792]]  // 全页范围      });    }    const results = extractTextInRegions(pdfBuffer, pageRegions);    let fullText = '';    for (const pageResult of results) {      for (const region of pageResult.regions) {        if (!region.needsOcr) {          fullText += region.text + '\n';        }      }    }    return { success: true, text: fullText, ocrFallbackPages: [] };  }  // 混合型：分区域路由  // 实际项目中，需要配合布局检测模型来定位具体区域坐标  // 此处仅演示区域提取API的使用方式  const regionsToCheck: PageRegions[] = classification.pagesNeedingOcr.map(page => ({    page,    regions: [      [100, 100, 300, 200],  // 需要OCR的具体区域坐标（左上x, 左上y, 右下x, 右下y）    ]  }));  const regionResults = extractTextInRegions(pdfBuffer, regionsToCheck);  // region.needsOcr为true表示该区域提取不可靠，应送入OCR服务  const ocrRegions = regionResults.flatMap(page =>    page.regions.filter(r => r.needsOcr)  );  return {    success: true,    text: '需要OCR的区域: ' + ocrRegions.length,    ocrFallbackPages: classification.pagesNeedingOcr  };}// 运行示例smartPdfProcessor('./document.pdf').then(console.log);

use pdf_inspector::process_pdf;use std::path::Path;use std::time::Instant;fnbatch_process_pdfs(pdf_paths: Vec<&str>) {    for path in pdf_paths {        let start = Instant::now();        match process_pdf(path) {            Ok(result) => {                let elapsed = start.as_millis();                println!(                    "{} | 类型={:?} | 置信度={:.2} | 页数={} | 耗时={}ms | MD长度={}",                    Path::new(path).file_name().unwrap().to_string_lossy(),                    result.pdf_type,                    result.confidence,                    result.page_count,                    elapsed,                    result.markdown.as_ref().map(|m| m.len()).unwrap_or(0)                );            }            Err(e) => eprintln!("处理失败 {}: {}", path, e),        }    }}fnmain() {    let docs = vec!["report1.pdf", "report2.pdf", "scanned_doc.pdf"];    batch_process_pdfs(docs);}

# 基础用法：转换为Markdowncargo run --bin pdf2md -- document.pdf# JSON格式输出（便于管道处理）cargo run --bin pdf2md -- document.pdf --json# 仅原始文本，无Markdown格式cargo run --bin pdf2md -- document.pdf --raw# 保留分页标记cargo run --bin pdf2md -- document.pdf --pages# 仅处理指定页码cargo run --bin pdf2md -- document.pdf --select-pages 1,3,5-10# 仅检测（不提取）cargo run --bin detect-pdf -- document.pdfcargo run --bin detect-pdf -- document.pdf --jsoncargo run --bin detect-pdf -- document.pdf --analyze --json  # 包含布局分析

pdf-inspector/├── src/│   ├── lib.rs              # 公共API入口、PdfOptions构建器│   ├── python.rs           # PyO3 Python绑定│   ├── types.rs            # 共享类型定义：TextItem、TextLine、PdfRect、ItemType│   ├── text_utils.rs       # 字符/文本辅助函数（CJK、RTL、连字、加粗/斜体检测）│   ├── process_mode.rs     # ProcessMode枚举（DetectOnly、Analyze、Full）│   ├── detector.rs         # 快速PDF类型检测（不加载完整文档）│   ├── glyph_names.rs      # Adobe字形列表 → Unicode映射│   ├── tounicode.rs        # ToUnicode CMap解析（用于CID编码字体）│   ├── extractor/          # 文本提取管线│   ├── tables/             # 表格检测和格式化│   └── markdown/           # Markdown生成器├── napi/                   # Node.js绑定（napi-rs）├── docs/│   ├── python.md           # Python API完整文档│   ├── rust-api.md         # Rust API完整文档│   └── napi/README.md      # Node.js API文档└── Cargo.toml

PDF输入    │    ▼┌─────────────────┐│ pdf-inspector   │  ◄── 10-50ms│ 分类检测        │└─────────────────┘    │    ├──► TextBased ──► 直接本地提取 (150ms)    │                      │    │                      ▼    │                  Markdown输出    │    └──► Scanned/Mixed ──► 送入OCR服务 (2-10s/页)                               │                               ▼                          OCR结果