ocr-and-documents

用途

本技能专注于从 PDF 和扫描文档中提取文本。它不负责 DOCX 的创建/编辑（应使用 docx 技能或 python-docx 进行结构化读取），不负责 PPTX 的完整创建/读取/编辑（应使用 powerpoint 技能），也不负责 PDF 的合并、拆分、表单、水印、创建等操作（应使用 pdf 技能）。本技能覆盖的是 PDF 与扫描件的文本提取。

主要能力

技能提供两种本地提取器，能力对比如下：

pymupdf（约 25MB）：支持文本型 PDF、基础表格、嵌入图像提取、EPUB、通过 pymupdf4llm 输出 Markdown；不支持扫描 PDF 的 OCR、公式/LaTeX、代码块、表单、页眉页脚移除、阅读顺序检测、图像转文本。速度即时。
marker-pdf（约 3-5GB）：支持文本型 PDF、扫描 PDF 的 OCR（90+ 语言）、高精度表格、公式/LaTeX、代码块、表单、页眉页脚移除、阅读顺序检测、带上下文的图像提取、图像转文本、EPUB、原生高质量 Markdown 输出。速度约 1-14 秒/页（CPU），约 0.2 秒/页（GPU）。

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

使用方式

第一步：是否有远程 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 失败或需要批量处理时，才使用本地提取。

第二步：选择本地提取器

pymupdf（轻量）

安装：

pip install pymupdf pymupdf4llm

通过辅助脚本使用：

python scripts/extract_pymupdf.py document.pdf              # 纯文本
python scripts/extract_pymupdf.py document.pdf --markdown    # Markdown
python scripts/extract_pymupdf.py document.pdf --tables      # 表格
python scripts/extract_pymupdf.py document.pdf --images out/ # 提取图像
python scripts/extract_pymupdf.py document.pdf --metadata    # 标题、作者、页数
python scripts/extract_pymupdf.py document.pdf --pages 0-4   # 指定页面

内联使用：

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

marker-pdf（高质量 OCR）

先检查磁盘空间：

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
python scripts/extract_marker.py document.pdf --output_dir out/  # 保存图像
python scripts/extract_marker.py scanned.pdf                 # 扫描 PDF（OCR）
python scripts/extract_marker.py document.pdf --use_llm      # LLM 增强准确率

CLI（随 marker-pdf 安装）：

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

拆分、合并与搜索

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

拆分（提取第 1-5 页到新 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")

合并多个 PDF：

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

跨页搜索文本：

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 一个包即可覆盖拆分、合并、搜索与文本提取。

处理 read_file 提取覆盖警告

如果来自 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（第二步）。

Arxiv 论文

# 仅摘要（快速）
web_extract(urls=["https://arxiv.org/abs/2402.03300"])

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

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

适用场景

从文本型 PDF 快速提取纯文本、Markdown、表格、图像或元数据。
对扫描 PDF 进行多语言 OCR，并保留公式、代码块、表单与阅读顺序。
处理远程 PDF 链接（优先 web_extract，无需本地依赖）。
对 PDF 进行拆分、合并与全文搜索。
处理 EPUB 文件。

限制

若用户需要 marker 能力但系统缺少约 5GB 可用磁盘，应提示：该文档需要 OCR/高级提取（marker-pdf），需要约 5GB 用于 PyTorch 和模型；当前系统有 [X]GB 可用。选项包括：释放空间、提供 URL 以便使用 web_extract，或尝试 pymupdf（适用于文本型 PDF，但不支持扫描文档或公式）。
marker-pdf 首次使用会下载约 2.5GB 模型到 ~/.cache/huggingface/。
两个辅助脚本均接受 --help 查看完整用法。
对于 Word 文档：pip install python-docx（优于 OCR——解析实际结构）。
对于 PowerPoint：参见 powerpoint 技能（使用 python-pptx）。
web_extract 始终是 URL 的首选。
pymupdf 是安全默认——即时、无需模型、随处可用。
marker-pdf 用于 OCR、扫描文档、公式、复杂版面——仅在需要时安装。