processing-pdf

PDF 处理

使用命令行工具和 Python 库处理 PDF 文件。对于扫描版 PDF，将页面转换为图像，并让大模型使用内置的图像理解功能读取图像。

先决条件

运行任何 Python 脚本前，请激活 opencode 虚拟环境：

source ~/.local/opencode-venv/bin/activate

然后照常使用 python3 scripts/...。

可用工具

工具	命令	用途
pdf-extractor Agent	全局 Agent（通过 task 分派）	完整提取 PDF（所有页面、所有数据、结构化文件夹树）
pdftotext	系统（Poppler）	快速提取文本
pdfinfo	系统（Poppler）	元数据、页数
pypdf	Python（虚拟环境）	合并、拆分、旋转
pdfplumber	Python（虚拟环境）	提取表格、详细文本
to_images.py	Python 脚本（虚拟环境）	将页面转换为 PNG 图像

决策指南

Need to process a PDF?
│
├─ Extract everything from a PDF?
│  └─ Dispatch the `pdf-extractor` agent.
│     It converts all pages to images, reads each one, and stores
│     per-page results in extracted_data/<pdf_name>/page_NNN/content.md
│     along with images and a summary.
│
├─ Quick text from a normal PDF?
│  ├─ Simple: pdftotext input.pdf output.txt
│  └─ With page numbers: python3 scripts/extract_text.py input.pdf
│
├─ Extract tables?
│  └─ python3 scripts/extract_tables.py input.pdf -o ./tables/
│
├─ Fill a form?
│  ├─ Check fields: python3 scripts/check_forms.py input.pdf
│  └─ Fill: python3 scripts/fill_form.py input.pdf fields.json output.pdf
│
├─ Read a scanned PDF (quick)?
│  ├─ Convert: python3 scripts/to_images.py scanned.pdf -o ./pages/ --dpi 200
│  └─ Read the images and extract what you need
│
├─ Merge/Split/Rotate?
│  └─ See pypdf examples below
│
└─ Large file (>50MB)?
   ├─ Quick text: pdftotext (fastest)
   └─ Page ranges: pdftotext -f N -l M input.pdf

完整提取 PDF

要从 PDF 中完整提取所有数据（文本、表格、表单、结构），请分派 pdf-extractor Agent。它会：

1. 将所有页面转换为 PNG 图像
2. 使用大模型视觉功能读取每张图像
3. 提取文本、表格、关键信息、表单字段和备注
4. 按页输出到 extracted_data/<pdf_name>/page_NNN/：
   • page_NNN.png — 页面图像
   • content.md — 所有文本和提取出的信息，以 Markdown 格式呈现
   • 根据需要提供其他大模型可读取的文件
5. 创建 summary.md，概述文档内容

何时使用提取器 Agent

• 需要获取所有数据的多页文档
• 扫描版 PDF 或扫描版与数字版混合的 PDF
• 布局复杂的文档（表格、分栏、表单）
• 需要结构化、可浏览的结果文件夹树时

快速提取（不使用 Agent）

对于单页文档或只需快速查看的情况，请使用以下手动步骤。

读取扫描版 PDF（快速，无需 Agent）

如果 PDF 是扫描版（没有可选中文本），请将页面转换为图像，然后让大模型读取。

步骤 1：检测 PDF 是否为扫描版

pdftotext document.pdf - | head -20

如果输出为空或只有空白字符，则该 PDF 是扫描版。

步骤 2：将页面转换为图像

# All pages at 200 DPI (sufficient for most documents)
python3 scripts/to_images.py document.pdf -o ./pdf-pages/ --dpi 200

# Higher quality for handwritten or low-quality scans
python3 scripts/to_images.py document.pdf -o ./pdf-pages/ --dpi 300

步骤 3：读取图像

直接引用生成的 PNG 文件即可——大模型可以直接读取。请让它提取文本、表格、字段，或回答有关文档内容的问题。

步骤 4：清理

rm -rf ./pdf-pages/

扫描版 PDF 提示

• 200 DPI 适用于大多数文档
• 手写内容或模糊扫描件使用 300 DPI
• 对于大型 PDF，请分批转换页面（先使用 pypdf 拆分，再进行转换）
• 读取完毕后，请务必清理生成的图像目录

文本提取

快速提取（pdftotext）

# Simple extraction
pdftotext input.pdf output.txt

# Single page
pdftotext -f 3 -l 3 input.pdf page3.txt

# With layout preservation
pdftotext -layout input.pdf output.txt

# Page range
pdftotext -f 5 -l 10 input.pdf pages_5_10.txt

添加页码（脚本）

python3 scripts/extract_text.py input.pdf

获取 PDF 信息

pdfinfo input.pdf

表格提取

脚本（推荐）

python3 scripts/extract_tables.py input.pdf -o ./tables/

Python（内联）

import pdfplumber
import csv

with pdfplumber.open("input.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            with open(f"page{i+1}_table{j+1}.csv", "w", newline="") as f:
                writer = csv.writer(f)
                for row in table:
                    writer.writerow([cell or "" for cell in row])

表单处理

检查是否存在可填写字段

python3 scripts/check_forms.py input.pdf

填写表单

python3 scripts/fill_form.py input.pdf fields.json output.pdf

其中 fields.json 包含：

{
  "field_name": "John Smith",
  "email": "[email protected]",
  "date": "2026-05-04"
}

PDF 操作（pypdf）

合并 PDF

from pypdf import PdfReader, PdfWriter

writer = PdfWriter()
for pdf_file in ["file1.pdf", "file2.pdf", "file3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as f:
    writer.write(f)

拆分为单独页面

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1:03d}.pdf", "wb") as f:
        writer.write(f)

旋转页面

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()
for page in reader.pages:
    page.rotate(90)  # 90, 180, or 270 degrees
    writer.add_page(page)

with open("rotated.pdf", "wb") as f:
    writer.write(f)

删除页面

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()
pages_to_keep = {0, 1, 4, 5}  # 0-indexed
for i, page in enumerate(reader.pages):
    if i in pages_to_keep:
        writer.add_page(page)

with open("trimmed.pdf", "wb") as f:
    writer.write(f)

元数据

python3 scripts/metadata.py input.pdf

转换为图像

python3 scripts/to_images.py input.pdf --dpi 200

大文件

对于大型 PDF（>50MB）：

• 使用 pdftotext 快速提取（比 Python 更快）
• 使用 pdfplumber 分批处理页面
• 使用 pdftotext 的 -f 和 -l 标志指定页面范围

写入大型输出文件

如果要从非常大的 PDF 中提取文本，请逐步写入输出（每次编辑约 1000 个词元），而不是一次性完成。

常见模式

在 PDF 中搜索文本

pdftotext input.pdf - | grep -n "search term"

比较两个 PDF（文本差异）

pdftotext doc1.pdf - > /tmp/doc1.txt
pdftotext doc2.pdf - > /tmp/doc2.txt
diff /tmp/doc1.txt /tmp/doc2.txt

边缘情况

加密的 PDF

from pypdf import PdfReader

reader = PdfReader("encrypted.pdf")
if reader.is_encrypted:
    reader.decrypt("")  # Try empty password first

已损坏或无效的 PDF

try:
    with pdfplumber.open("file.pdf") as pdf:
        # process...
except Exception as e:
    print(f"Error processing PDF: {e}")

超大型 PDF（>100MB）

• 使用 pdftotext 提高速度
• 使用 pdfplumber 按页批次处理
• 避免将整个文件加载到内存中

混合内容（部分页面已扫描，部分页面未扫描）

1. 首先尝试标准提取（pdftotext）
2. 检查哪些页面返回了空文本
3. 仅将这些页面转换为图像，并让 LLM 读取