PDF 和文档提取
Harness-agent tools
本技能从 Octop 移植。使用以下 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
对于 DOCX:使用 python-docx(解析实际文档结构,远优于 OCR)。
对于 PPTX:参见 powerpoint 技能(使用带完整幻灯片/注释支持的 python-pptx)。
本技能涵盖 PDF 和扫描文档。
步骤 1:远程 URL 可用?
如果文档有 URL,先尝试 web_fetch 用于 HTML 页面和基于文本的内容:
web_fetch(url="https://arxiv.org/abs/2402.03300")
web_fetch 将 HTML 转换为 markdown。对于二进制 PDF,它返回纯文本或可能失败——回退到下面的本地提取。
仅当文件是本地文件、web_fetch 失败或返回不可用输出,或者你需要批量处理/OCR 时才使用本地提取。
步骤 2:选择本地提取器
| 功能 | pymupdf (~25MB) | marker-pdf (~3-5GB) |
|---|---|---|
| 基于文本的 PDF | ✅ | ✅ |
| 扫描的 PDF(OCR) | ❌ | ✅(90+ 种语言) |
| 表格 | ✅(基础) | ✅(高精度) |
| 公式 / LaTeX | ❌ | ✅ |
| 代码块 | ❌ | ✅ |
| 表单 | ❌ | ✅ |
| 页眉/页脚移除 | ❌ | ✅ |
| 阅读顺序检测 | ❌ | ✅ |
| 图像提取 | ✅(嵌入) | ✅(带上下文) |
| 图像 → 文本(OCR) | ❌ | ✅ |
| EPUB | ✅ | ✅ |
| Markdown 输出 | ✅(通过 pymupdf4llm) | ✅(原生,更高质量) |
| 安装大小 | ~25MB | ~3-5GB(PyTorch + 模型) |
| 速度 | 即时 |
决策:除非你需要 OCR、公式、表单或复杂布局分析,否则使用 pymupdf。
如果用户的系统缺少 ~5GB 可用空间,但需要 marker 功能:
"此文档需要 OCR/高级提取(marker-pdf),这需要 ~5GB 用于 PyTorch 和模型。你的系统有 [X]GB 可用空间。选项:释放空间、提供 URL 以便我可以使用 web_fetch,或者我可以尝试 pymupdf,它适用于基于文本的 PDF,但不适用于扫描文档或公式。"
pymupdf(轻量级)
pip install pymupdf pymupdf4llm
通过助手脚本(在 init_workspace 后的工作区根目录):
python _builtin_skills/ocr-and-documents/scripts/extract_pymupdf.py document.pdf
python _builtin_skills/ocr-and-documents/scripts/extract_pymupdf.py document.pdf --markdown
python _builtin_skills/ocr-and-documents/scripts/extract_pymupdf.py document.pdf --tables
python _builtin_skills/ocr-and-documents/scripts/extract_pymupdf.py document.pdf --images out/
python _builtin_skills/ocr-and-documents/scripts/extract_pymupdf.py document.pdf --metadata
python _builtin_skills/ocr-and-documents/scripts/extract_pymupdf.py document.pdf --pages 0-4
内联:
import pymupdf
doc = pymupdf.open("document.pdf")
for page in doc:
print(page.get_text())
marker-pdf(高质量 OCR)
# 先检查磁盘空间
python _builtin_skills/ocr-and-documents/scripts/extract_marker.py --check
pip install marker-pdf
通过助手脚本:
python _builtin_skills/ocr-and-documents/scripts/extract_marker.py document.pdf
python _builtin_skills/ocr-and-documents/scripts/extract_marker.py document.pdf --json
python _builtin_skills/ocr-and-documents/scripts/extract_marker.py document.pdf --output_dir out/
python _builtin_skills/ocr-and-documents/scripts/extract_marker.py scanned.pdf
python _builtin_skills/ocr-and-documents/scripts/extract_marker.py document.pdf --use_llm
CLI(随 marker-pdf 安装):
marker_single document.pdf --output_dir ./output
marker /path/to/folder --workers 4 # 批量
Arxiv 论文
# 摘要(HTML → markdown 通过 web_fetch)
web_fetch(url="https://arxiv.org/abs/2402.03300")
# 完整论文 PDF——下载然后本地提取(见上面的 pymupdf / marker)
execute(command="curl -L -o paper.pdf https://arxiv.org/pdf/2402.03300")
对于论文搜索,使用已配置的搜索工具(tavily_search、searchfree_search 等),或对已知 URL 使用 web_fetch。
拆分、合并和搜索
pymupdf 原生处理这些——使用 execute 或内联 Python:
# 拆分:提取前 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
result = pymupdf.open()
for path in ["a.pdf", "b.pdf", "c.pdf"]:
result.insert_pdf(pymupdf.open(path))
result.save("merged.pdf")
# 跨所有页面搜索文本
doc = pymupdf.open("report.pdf")
for i, page in enumerate(doc):
results = page.search_for("venue")
if results:
print(f"Page {i + 1}: {len(results)} match(es)")
print(page.get_text("text"))
无需额外依赖——pymupdf 在一个包中涵盖拆分、合并、搜索和文本提取。
注意事项
web_fetch始终是 URL 的首选- pymupdf 是安全的默认选择——即时、无模型、随处可用
- marker-pdf 用于 OCR、扫描文档、公式、复杂布局——仅在需要时安装
- 两个助手脚本都接受
--help以获取完整用法 - marker-pdf 在首次使用时将
2.5GB 模型下载到 `/.cache/huggingface/` - 对于 Word 文档:
pip install python-docx(优于 OCR——解析实际结构) - 对于 PowerPoint:
pip install python-pptx(参见powerpoint技能)