Skip to content
PDF Oxide

从 pypdf 迁移到 PDF Oxide

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

为什么要从 pypdf 迁移？

四个值得迁移的理由：

  1. 快 15 倍 — PDF Oxide 每页平均 0.8ms，pypdf 为 12.1ms。500 页文档的处理时间从 6 秒降到 0.4 秒。
  2. 100% 可靠性 — PDF Oxide 通过 100% 的 PDF 测试套件。pypdf 在 1.6% 的文件上失败（98.4% 通过率），大约每 60 个文档就有 1 个输出异常。
  3. 内置 Markdown 和 HTML — pypdf 只能提取纯文本。PDF Oxide 可以将页面转换为保留表格和结构的 Markdown 和 HTML，这对 LLM 和 RAG 管线至关重要。
  4. 内置 OCR 和渲染 — pypdf 没有 OCR 和页面渲染功能。PDF Oxide 内置 PaddleOCR 处理扫描文档，还能将页面渲染为图片，无需外部依赖。

第 1 步：安装

pip install pdf_oxide
pip uninstall pypdf  # 可选

第 2 步：替换导入

# 之前
from pypdf import PdfReader, PdfWriter, PdfMerger

# 之后
from pdf_oxide import PdfDocument, Pdf

第 3 步：API 映射表

任务 pypdf PDF Oxide
打开 PDF PdfReader("file.pdf") PdfDocument("file.pdf")
页数 len(reader.pages) doc.page_count()
提取文本 reader.pages[0].extract_text() doc.extract_text(0)
提取图片 reader.pages[0].images doc.extract_image_bytes(0)
表单字段 reader.get_fields() doc.get_form_fields()
元数据 reader.metadata doc.metadata()
加密 PDF reader.decrypt("pw") PdfDocument("file.pdf", password="pw")
合并 PDF PdfMerger() + .append() doc.merge_from("doc2.pdf")
拆分页面 PdfWriter() + .add_page() doc.extract_pages([0,1,2,3,4], "out.pdf")
转为 Markdown 不支持 doc.to_markdown(0)
渲染 不支持 doc.render_page(0)
OCR 不支持 doc.extract_text_ocr(0)

第 4 步：常见模式变更

文本提取

# pypdf
from pypdf import PdfReader
reader = PdfReader("report.pdf")
for page in reader.pages:
    print(page.extract_text())

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    print(doc.extract_text(i))

合并 PDF

pypdf 需要创建合并器对象并逐个添加文件。PDF Oxide 一步完成：

# pypdf
from pypdf import PdfMerger
merger = PdfMerger()
merger.append("doc1.pdf")
merger.append("doc2.pdf")
merger.write("merged.pdf")

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("doc1.pdf")
doc.merge_from("doc2.pdf")
doc.save("merged.pdf")

拆分/提取页面

# pypdf — 手动逐页复制
from pypdf import PdfReader, PdfWriter
reader = PdfReader("report.pdf")
writer = PdfWriter()
for page in reader.pages[0:5]:
    writer.add_page(page)
writer.write("first_5_pages.pdf")

# PDF Oxide — 一次调用
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
doc.extract_pages([0, 1, 2, 3, 4], "first_5_pages.pdf")

加密 PDF

# pypdf — 先打开再解密
from pypdf import PdfReader
reader = PdfReader("encrypted.pdf")
reader.decrypt("password")
text = reader.pages[0].extract_text()

# PDF Oxide — 构造函数中指定密码
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)

Markdown 转换（新功能）

pypdf 不支持 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)

图片提取

# pypdf
from pypdf import PdfReader
reader = PdfReader("report.pdf")
for image in reader.pages[0].images:
    with open(image.name, "wb") as f:
        f.write(image.data)

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
images = doc.extract_image_bytes(0)
for i, img in enumerate(images):
    with open(f"image_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

第 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}")

其他迁移指南

相关页面