ocr-and-documents

PDF 和文档提取

对于 DOCX：请参阅 docx 技能（创建/编辑），或使用 python-docx 读取结构化内容。 对于 PPTX：请参阅 powerpoint 技能（全面支持创建/读取/编辑）。 对于 PDF 操作（合并、拆分、表单、水印、创建）：请参阅 pdf 技能。 本技能介绍从 PDF 和扫描文档中提取文本。

遇到 read_file 的 EXTRACTION COVERAGE WARNING？ read_file 会自动转换本地 PDF，但只读取文本层；警告页脚会列出未提取到文本的页面（扫描图像）。如果只有少数几页，渲染后使用视觉分析最快：先运行 pdftoppm -jpeg -r 150 -f N -l N file.pdf /tmp/page，再对每张图像运行 vision_analyze。若要批量 OCR 多页文档，请使用下文的 marker-pdf（步骤 2）。

步骤 1：是否有远程 URL？

如果文档有 URL，请始终先尝试 web_extract：

web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
web_extract(urls=["https://example.com/report.pdf"])

它通过 Firecrawl 将 PDF 转换为 Markdown，无需本地依赖。

仅在以下情况下使用本地提取：文件在本地、web_extract 失败，或需要批量处理。

步骤 2：选择本地提取器

特性	pymupdf（约 25MB）	marker-pdf（约 3-5GB）
基于文本的 PDF	✅	✅
扫描版 PDF（OCR）	❌	✅（90 多种语言）
表格	✅（基础）	✅（高准确度）
公式 / LaTeX	❌	✅
代码块	❌	✅
表单	❌	✅
移除页眉/页脚	❌	✅
阅读顺序检测	❌	✅
图像提取	✅（嵌入式）	✅（含上下文）
图像 → 文本（OCR）	❌	✅
EPUB	✅	✅
Markdown 输出	✅（通过 pymupdf4llm）	✅（原生，质量更高）
安装大小	约 25MB	约 3-5GB（PyTorch + 模型）
速度	即时	约 1-14 秒/页（CPU），约 0.2 秒/页（GPU）

选择建议：除非需要 OCR、公式、表单或复杂布局分析，否则使用 pymupdf。

如果用户需要 marker 的功能，但系统没有约 5GB 的可用磁盘空间：

“此文档需要 OCR/高级提取（marker-pdf），需要约 5GB 空间来安装 PyTorch 和模型。你的系统有 [X]GB 可用空间。你可以选择：腾出空间、提供 URL 以便我使用 web_extract，或者我可以尝试使用 pymupdf；它适用于基于文本的 PDF，但不支持扫描文档或公式。”

---

pymupdf（轻量）

pip install pymupdf pymupdf4llm

通过辅助脚本：

python scripts/extract_pymupdf.py document.pdf              # Plain text
python scripts/extract_pymupdf.py document.pdf --markdown    # Markdown
python scripts/extract_pymupdf.py document.pdf --tables      # Tables
python scripts/extract_pymupdf.py document.pdf --images out/ # Extract images
python scripts/extract_pymupdf.py document.pdf --metadata    # Title, author, pages
python scripts/extract_pymupdf.py document.pdf --pages 0-4   # Specific pages

内联：

python -c "
import pymupdf
doc = pymupdf.open('document.pdf')
for page in doc:
    print(page.get_text())
"

---

marker-pdf（高质量 OCR）

# Check disk space first
python scripts/extract_marker.py --check

pip install marker-pdf

通过辅助脚本：

python scripts/extract_marker.py document.pdf                # Markdown
python scripts/extract_marker.py document.pdf --json         # JSON with metadata
python scripts/extract_marker.py document.pdf --output_dir out/  # Save images
python scripts/extract_marker.py scanned.pdf                 # Scanned PDF (OCR)
python scripts/extract_marker.py document.pdf --use_llm      # LLM-boosted accuracy

CLI（随 marker-pdf 安装）：

marker_single document.pdf --output_dir ./output
marker /path/to/folder --workers 4    # Batch

---

Arxiv 论文

# Abstract only (fast)
web_extract(urls=["https://arxiv.org/abs/2402.03300"])

# Full paper
web_extract(urls=["https://arxiv.org/pdf/2402.03300"])

# Search
web_search(query="arxiv GRPO reinforcement learning 2026")

拆分、合并和搜索

pymupdf 原生支持这些操作——使用 execute_code 或内联 Python：

# Split: extract pages 1-5 to a new PDF
import pymupdf
doc = pymupdf.open("report.pdf")
new = pymupdf.open()
for i in range(5):
    new.insert_pdf(doc, from_page=i, to_page=i)
new.save("pages_1-5.pdf")

# Merge multiple PDFs
import pymupdf
result = pymupdf.open()
for path in ["a.pdf", "b.pdf", "c.pdf"]:
    result.insert_pdf(pymupdf.open(path))
result.save("merged.pdf")

# Search for text across all pages
import pymupdf
doc = pymupdf.open("report.pdf")
for i, page in enumerate(doc):
    results = page.search_for("revenue")
    if results:
        print(f"Page {i+1}: {len(results)} match(es)")
        print(page.get_text("text"))

无需额外依赖——pymupdf 在一个软件包中即可完成拆分、合并、搜索和文本提取。

---

注意事项

• 对 URL 始终优先使用 web_extract
• pymupdf 是稳妥的默认选择——速度快、无需模型、适用范围广
• marker-pdf 用于 OCR、扫描文档、公式和复杂布局——仅在需要时安装
• 两个辅助脚本均支持 --help，可查看完整用法
• marker-pdf 首次使用时会将约 2.5GB 的模型下载到 ~/.cache/huggingface/
• 对于 Word 文档：pip install python-docx（优于 OCR——它会解析实际结构）
• 对于 PowerPoint：请参阅 powerpoint 技能（使用 python-pptx）