Skip to content
PDF Oxide

从 pdfminer.six 迁移到 PDF Oxide

从 pdfminer（pdfminer.six）切换到 PDF Oxide 的完整指南，涵盖你目前使用的所有 API 及其替代方案。

为什么要从 pdfminer 迁移？

四个值得迁移的理由：

  1. 快约 30 倍 — pdfminer 是主流 Python PDF 库中最慢的。PDF Oxide 每页平均 0.8ms，pdfminer 需要数十毫秒。原来几分钟的批处理现在几秒就能完成。
  2. 活跃维护 — pdfminer.six 更新频率低，积压了大量未解决的 issue。PDF Oxide 持续活跃开发，定期发布新版本。
  3. 一体化解决方案 — pdfminer 仅支持文本提取。PDF Oxide 还能创建 PDF、编辑、渲染页面、提取图片、处理表单，以及转换为 Markdown/HTML。
  4. 无需配置 — pdfminer 需要手动调整 LAParams（word_margin、line_margin、char_margin）才能获得不错的结果。PDF Oxide 自动处理布局检测。

第 1 步：安装

pip install pdf_oxide
pip uninstall pdfminer.six  # 可选

第 2 步：替换导入

# 之前
from pdfminer.high_level import extract_text, extract_pages
from pdfminer.layout import LAParams

# 之后
from pdf_oxide import PdfDocument

第 3 步：API 映射表

任务 pdfminer PDF Oxide
提取文本 extract_text("file.pdf") PdfDocument("file.pdf").extract_text(0)
提取页面 extract_pages("file.pdf") 使用 doc.extract_text(i) 逐页处理
布局分析 LAParams() 配置 内置布局检测
字符位置 LTChar 对象 doc.extract_chars(0)
加密 PDF 有限支持（AES-256 会失败） 完全支持
转为 Markdown 不支持 doc.to_markdown(0)
表单字段 不支持 doc.get_form_fields()

第 4 步：常见模式变更

基本文本提取

pdfminer 的 extract_text 一次处理整个文档。PDF Oxide 提供逐页控制：

# pdfminer — 一次处理整个文档
from pdfminer.high_level import extract_text
text = extract_text("report.pdf")
print(text)

# PDF Oxide — 逐页控制
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    text = doc.extract_text(i)
    print(text)

布局分析

pdfminer 需要手动配置 LAParams。PDF Oxide 自动处理：

# pdfminer — 手动布局配置
from pdfminer.high_level import extract_text
from pdfminer.layout import LAParams

params = LAParams(
    word_margin=0.1,
    line_margin=0.5,
    char_margin=2.0,
    boxes_flow=0.5,
)
text = extract_text("report.pdf", laparams=params)

# PDF Oxide — 自动布局检测
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
text = doc.extract_text(0)  # 布局自动处理

字符级提取

pdfminer 使用复杂的布局对象树。PDF Oxide 返回扁平列表：

# pdfminer — 遍历布局树
from pdfminer.high_level import extract_pages
from pdfminer.layout import LTChar, LTTextBox

for page_layout in extract_pages("report.pdf"):
    for element in page_layout:
        if isinstance(element, LTTextBox):
            for line in element:
                for char in line:
                    if isinstance(char, LTChar):
                        print(f"{char.get_text()} at ({char.x0}, {char.y0})")

# PDF Oxide — 扁平字符列表
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for c in doc.extract_chars(0):
    print(f"{c.char} at ({c.x}, {c.y})")

加密 PDF

pdfminer 对加密的支持有限，AES-256 加密文件会失败：

# pdfminer — 很多加密 PDF 会失败
from pdfminer.high_level import extract_text
text = extract_text("encrypted.pdf", password="password")
# AES-256 加密文件可能报错

# PDF Oxide — 完全支持加密
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)  # 支持所有加密方式

Markdown 转换（新功能）

pdfminer 不支持 Markdown。PDF Oxide 让 PDF 轻松接入 LLM 管线：

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    md = doc.to_markdown(i)
    print(md)

表单字段提取（新功能）

pdfminer 无法提取表单字段。PDF Oxide 可以：

from pdf_oxide import PdfDocument

doc = PdfDocument("form.pdf")
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

页面渲染（新功能）

pdfminer 没有渲染功能。PDF Oxide 可以将页面渲染为图片：

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
png_bytes = doc.render_page(0, dpi=150)
with open("page.png", "wb") as f:
    f.write(png_bytes)

主要区别

  1. 无需调整 LAParams — PDF Oxide 自动处理布局。不需要配置 word_margin、line_margin 等参数。
  2. 速度 — pdfminer 是最慢的 Python PDF 库。PDF Oxide 快约 30 倍。
  3. 一体化解决方案 — pdfminer 仅支持提取。PDF Oxide 还可以创建、编辑和渲染 PDF。

第 5 步：测试迁移

通过两个库运行现有测试文件并比较输出：

from pdf_oxide import PdfDocument

doc = PdfDocument("your-test-file.pdf")

# 验证文本提取
text = doc.extract_text(0)
print(text[:500])

# 验证页数
print(f"Pages: {doc.page_count()}")

# 验证表单字段（如适用）
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

其他迁移指南

相关页面