myagents/.claude/skills/rag-files/references/pdf_reading.md

PDF 读取与分析

⚠️ 使用本文档前请注意：本文档应在实际处理 PDF 文件之前完整阅读，以选择最合适的工具和方法。不要在未阅读本文档的情况下盲目尝试处理 PDF。

用于从 PDF 文件中提取文本、表格和元数据的方法。

快速决策表

场景	推荐工具	原因	命令/代码示例
纯文本提取（最常见）	pdftotext 命令	最快最简单	pdftotext input.pdf output.txt
需要保留布局	pdftotext -layout	保持原始排版	pdftotext -layout input.pdf output.txt
需要提取表格	pdfplumber	表格识别能力强	page.extract_tables()
需要元数据	pypdf	轻量级	reader.metadata
扫描PDF（图片）	OCR (pytesseract)	无其他选择	先转图片再OCR

文本提取优先级

推荐优先级（从高到低）：

1. pdftotext 命令行工具（最快，适合大多数 PDF）
2. pdfplumber（适合需要保留布局或提取表格）
3. pypdf（轻量级，适合简单提取）
4. OCR（仅用于扫描PDF或无法直接提取文本的情况）

快速开始：使用 pdftotext（推荐）

⚠️ 重要：必须将输出保存到文件，不要直接输出到终端（stdout），否则会占用大量 token！

# ✅ 正确：提取文本到文件（最快最简单）
pdftotext input.pdf output.txt

# ✅ 正确：保留布局并输出到文件
pdftotext -layout input.pdf output.txt

# ✅ 正确：提取特定页面到文件
pdftotext -f 1 -l 5 input.pdf output.txt  # 第1-5页

# ❌ 错误：不要使用 stdout（会占用大量 token）
# pdftotext input.pdf -

使用流程：

1. 使用 pdftotext 提取文本到临时文件
2. 使用 grep 或 Read 工具对生成的文本文件进行检索
3. 只读取匹配部分的上下文，而非全文

如果需要在 Python 中处理：

from pypdf import PdfReader

# 读取 PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# 提取文本
text = ""
for page in reader.pages:
    text += page.extract_text()

Python 库

pypdf - 基本文本提取

from pypdf import PdfReader

reader = PdfReader("document.pdf")

# 提取全部文本
for page in reader.pages:
    text = page.extract_text()
    print(text)

# 提取元数据
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")

pdfplumber - 带布局的文本和表格提取

提取文本（保留布局）

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)

提取表格

with pdfplumber.open("document.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"Table {j+1} on page {i+1}:")
            for row in table:
                print(row)

高级表格提取（转为 DataFrame）

import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            if table:  # 检查表格非空
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

# 合并所有表格
if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)

带坐标的精确文本提取

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    page = pdf.pages[0]
    
    # 提取所有字符及其坐标
    chars = page.chars
    for char in chars[:10]:  # 前10个字符
        print(f"Char: '{char['text']}' at x:{char['x0']:.1f} y:{char['y0']:.1f}")
    
    # 按边界框提取文本 (left, top, right, bottom)
    bbox_text = page.within_bbox((100, 100, 400, 200)).extract_text()

复杂表格的高级设置

import pdfplumber

with pdfplumber.open("complex_table.pdf") as pdf:
    page = pdf.pages[0]
    
    # 自定义表格提取设置
    table_settings = {
        "vertical_strategy": "lines",
        "horizontal_strategy": "lines",
        "snap_tolerance": 3,
        "intersection_tolerance": 15
    }
    tables = page.extract_tables(table_settings)
    
    # 可视化调试
    img = page.to_image(resolution=150)
    img.save("debug_layout.png")

pypdfium2 - 快速渲染和文本提取

import pypdfium2 as pdfium

# 加载 PDF
pdf = pdfium.PdfDocument("document.pdf")

# 提取文本
for i, page in enumerate(pdf):
    text = page.get_text()
    print(f"Page {i+1} text length: {len(text)} chars")

将 PDF 页面渲染为图片

import pypdfium2 as pdfium
from PIL import Image

pdf = pdfium.PdfDocument("document.pdf")

# 渲染单页
page = pdf[0]  # 第一页
bitmap = page.render(
    scale=2.0,  # 高分辨率
    rotation=0  # 不旋转
)

# 转换为 PIL Image
img = bitmap.to_pil()
img.save("page_1.png", "PNG")

# 处理多页
for i, page in enumerate(pdf):
    bitmap = page.render(scale=1.5)
    img = bitmap.to_pil()
    img.save(f"page_{i+1}.jpg", "JPEG", quality=90)

命令行工具

pdftotext (poppler-utils)

⚠️ 性能优化：始终输出到文件，避免占用 token

# ✅ 提取文本到文件
pdftotext input.pdf output.txt

# ✅ 保留布局提取到文件
pdftotext -layout input.pdf output.txt

# ✅ 提取特定页面到文件
pdftotext -f 1 -l 5 input.pdf output.txt  # 第1-5页

# ✅ 提取带坐标的文本到 XML 文件（用于结构化数据）
pdftotext -bbox-layout document.pdf output.xml

# ❌ 避免：不要省略输出文件名（会输出到 stdout）
# pdftotext input.pdf

高级图片转换 (pdftoppm)

# 转换为 PNG，指定分辨率
pdftoppm -png -r 300 document.pdf output_prefix

# 转换特定页面范围，高分辨率
pdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages

# 转换为 JPEG，指定质量
pdftoppm -jpeg -jpegopt quality=85 -r 200 document.pdf jpeg_output

提取嵌入图片 (pdfimages)

# 提取所有图片
pdfimages -j input.pdf output_prefix

# 列出图片信息（不提取）
pdfimages -list document.pdf

# 以原始格式提取
pdfimages -all document.pdf images/img

OCR 提取（扫描PDF）

# 需要: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# PDF 转图片
images = convert_from_path('scanned.pdf')

# OCR 每一页
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

print(text)

处理加密 PDF

from pypdf import PdfReader

try:
    reader = PdfReader("encrypted.pdf")
    if reader.is_encrypted:
        reader.decrypt("password")
    
    # 解密后可正常提取文本
    for page in reader.pages:
        text = page.extract_text()
        print(text)
except Exception as e:
    print(f"Failed to decrypt: {e}")

# 使用 qpdf 解密（需要知道密码）
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

# 检查加密状态
qpdf --show-encryption encrypted.pdf

批量处理

import os
import glob
from pypdf import PdfReader
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def batch_extract_text(input_dir):
    """批量提取文本"""
    pdf_files = glob.glob(os.path.join(input_dir, "*.pdf"))
    
    for pdf_file in pdf_files:
        try:
            reader = PdfReader(pdf_file)
            text = ""
            for page in reader.pages:
                text += page.extract_text()
            
            output_file = pdf_file.replace('.pdf', '.txt')
            with open(output_file, 'w', encoding='utf-8') as f:
                f.write(text)
            logger.info(f"Extracted text from: {pdf_file}")
            
        except Exception as e:
            logger.error(f"Failed to extract text from {pdf_file}: {e}")
            continue

性能优化

1. 文件输出优先：始终将 pdftotext 输出保存到文件，然后用 grep/Read 检索，避免直接输出到终端占用大量 token
2. 大型PDF：使用流式方式逐页处理，避免一次性加载整个文件
3. 文本提取：pdftotext 最快；pdfplumber 适合结构化数据和表格
4. 图片提取：pdfimages 比渲染页面快得多
5. 内存管理：逐页或分块处理大文件

快速参考

任务	最佳工具	命令/代码
提取文本	pdfplumber	page.extract_text()
提取表格	pdfplumber	page.extract_tables()
命令行提取	pdftotext	pdftotext -layout input.pdf
OCR 扫描PDF	pytesseract	先转图片再OCR
提取元数据	pypdf	reader.metadata
PDF转图片	pypdfium2	page.render()

可用包

• pypdf - 基本操作（BSD 许可）
• pdfplumber - 文本和表格提取（MIT 许可）
• pypdfium2 - 快速渲染和提取（Apache/BSD 许可）
• pytesseract - OCR（Apache 许可）
• pdf2image - PDF转图片
• poppler-utils - 命令行工具（GPL-2 许可）