Skip to content
PDF Oxide

Python RAG 流水线 PDF 提取

为 RAG 流水线把 PDF 抽取成结构化 Markdown：

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("paper.pdf")
md = doc.to_markdown_all(detect_headings=True, include_images=False)
# 切块、生成向量嵌入,再写入你的向量数据库

WASM

import { WasmPdfDocument } from "pdf-oxide-wasm";

const doc = new WasmPdfDocument(bytes);
const md = doc.toMarkdownAll();
// 切块、生成向量嵌入,再写入你的向量数据库
doc.free();

Rust

use pdf_oxide::PdfDocument;

let mut doc = PdfDocument::open("paper.pdf")?;
let md = doc.to_markdown_all(true)?;
// 切块、生成向量嵌入,再写入你的向量数据库

Go

package main

import (
    "log"
    pdfoxide "github.com/yfedoseev/pdf_oxide/go"
)

func main() {
    doc, err := pdfoxide.Open("paper.pdf")
    if err != nil { log.Fatal(err) }
    defer doc.Close()

    md, _ := doc.ToMarkdownAll()
    _ = md // 切块、生成向量嵌入,再写入你的向量数据库
}

C#

using PdfOxide;

using var doc = PdfDocument.Open("paper.pdf");
var md = doc.ToMarkdownAll();
// 切块、生成向量嵌入,再写入你的向量数据库

PDF Oxide 在 3.1 秒内处理 3830 份 PDF —— 每页 0.8 ms,通过率 100%。索引里不会缺失任何一份文档。

为什么提取质量对 RAG 如此重要

检索系统的上限由前端的提取质量决定：

  • 文本缺失 = 答案缺失。通过率 98.4% 的库（pypdf）会在 3823 份文件的语料里悄悄丢掉 61 份。PDF Oxide 则是 100% 通过。
  • 结构丢失 = 分块变差。纯文本把标题、表格和格式都扔掉了,而这些恰恰是语义分块的依据。Markdown 会把它们保留下来。
  • 提取缓慢 = 流水线瓶颈。每页 12.1 ms（pypdf）或 23.2 ms（pdfplumber）时,处理 10 万页要花几分钟。0.8 ms 时只要 80 秒。

安装

pip install pdf_oxide

快速开始：从 PDF 到向量数据库

from pdf_oxide import PdfDocument, PdfError
from pathlib import Path

def extract_documents(pdf_dir: str) -> list[dict]:
    """把目录里全部 PDF 抽取为结构化分块。"""
    documents = []
    for pdf_path in Path(pdf_dir).glob("*.pdf"):
        try:
            doc = PdfDocument(str(pdf_path))
            for i in range(doc.page_count()):
                md = doc.to_markdown(i,
                    detect_headings=True,
                    include_images=False
                )
                if md.strip():
                    documents.append({
                        "content": md,
                        "source": pdf_path.name,
                        "page": i,
                    })
        except PdfError as e:
            print(f"跳过 {pdf_path.name}: {e}")
    return documents

docs = extract_documents("research-papers/")
print(f"共从 PDF 中抽取 {len(docs)} 个分块")
# 把 docs 交给嵌入模型与向量存储

分块策略

按标题（语义分块）

按标题切分 Markdown 输出,得到语义上有意义的分块：

Python

import re
from pdf_oxide import PdfDocument

doc = PdfDocument("paper.pdf")
md = doc.to_markdown_all(detect_headings=True, include_images=False)

# 在 ## 标题处切分
chunks = re.split(r'\n(?=## )', md)
chunks = [c.strip() for c in chunks if c.strip()]

WASM

const doc = new WasmPdfDocument(bytes);
const md = doc.toMarkdownAll();

// 在 ## 标题处切分
const chunks = md.split(/\n(?=## )/).filter(c => c.trim());
doc.free();

Rust

let mut doc = PdfDocument::open("paper.pdf")?;
let md = doc.to_markdown_all(true)?;

let chunks: Vec<&str> = md.split("\n## ")
    .map(|c| c.trim())
    .filter(|c| !c.is_empty())
    .collect();

Go

doc, _ := pdfoxide.Open("paper.pdf")
defer doc.Close()

md, _ := doc.ToMarkdownAll()

var chunks []string
for _, c := range strings.Split(md, "\n## ") {
    c = strings.TrimSpace(c)
    if c != "" { chunks = append(chunks, c) }
}

C#

using var doc = PdfDocument.Open("paper.pdf");
var md = doc.ToMarkdownAll();

var chunks = md.Split("\n## ")
    .Select(c => c.Trim())
    .Where(c => c.Length > 0)
    .ToList();

按页

一页一个分块 —— 简单,并且保留页面级上下文：

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("manual.pdf")
chunks = []
for i in range(doc.page_count()):
    md = doc.to_markdown(i, detect_headings=True, include_images=False)
    if md.strip():
        chunks.append({"content": md, "page": i})

WASM

const doc = new WasmPdfDocument(bytes);
const chunks = [];
for (let i = 0; i < doc.pageCount(); i++) {
    const md = doc.toMarkdown(i);
    if (md.trim()) {
        chunks.push({ content: md, page: i });
    }
}
doc.free();

Rust

let mut doc = PdfDocument::open("manual.pdf")?;
let mut chunks = Vec::new();
for i in 0..doc.page_count()? {
    let md = doc.to_markdown(i, true)?;
    if !md.trim().is_empty() {
        chunks.push((i, md));
    }
}

Go

doc, _ := pdfoxide.Open("manual.pdf")
defer doc.Close()

type Chunk struct{ Page int; Content string }
var chunks []Chunk

n, _ := doc.PageCount()
for i := 0; i < n; i++ {
    md, _ := doc.ToMarkdown(i)
    if strings.TrimSpace(md) != "" {
        chunks = append(chunks, Chunk{Page: i, Content: md})
    }
}

C#

using var doc = PdfDocument.Open("manual.pdf");
var chunks = Enumerable.Range(0, doc.PageCount)
    .Select(i => new { Page = i, Content = doc.ToMarkdown(i) })
    .Where(c => !string.IsNullOrWhiteSpace(c.Content))
    .ToList();

定长 + 重叠

把长文本切成定长带重叠的分块：

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("book.pdf")
full_text = doc.to_markdown_all(detect_headings=True, include_images=False)

chunk_size = 1000  # 字符数
overlap = 200
chunks = []

for start in range(0, len(full_text), chunk_size - overlap):
    chunk = full_text[start:start + chunk_size]
    if chunk.strip():
        chunks.append(chunk)

WASM

const doc = new WasmPdfDocument(bytes);
const fullText = doc.toMarkdownAll();

const chunkSize = 1000;
const overlap = 200;
const chunks = [];

for (let start = 0; start < fullText.length; start += chunkSize - overlap) {
    const chunk = fullText.slice(start, start + chunkSize);
    if (chunk.trim()) chunks.push(chunk);
}
doc.free();

Rust

let mut doc = PdfDocument::open("book.pdf")?;
let full_text = doc.to_markdown_all(true)?;

let chunk_size = 1000;
let overlap = 200;
let mut chunks = Vec::new();
let mut start = 0;

while start < full_text.len() {
    let end = (start + chunk_size).min(full_text.len());
    let chunk = &full_text[start..end];
    if !chunk.trim().is_empty() {
        chunks.push(chunk.to_string());
    }
    start += chunk_size - overlap;
}

Go

doc, _ := pdfoxide.Open("book.pdf")
defer doc.Close()

full, _ := doc.ToMarkdownAll()

const chunkSize, overlap = 1000, 200
var chunks []string
for start := 0; start < len(full); start += chunkSize - overlap {
    end := start + chunkSize
    if end > len(full) { end = len(full) }
    chunk := full[start:end]
    if strings.TrimSpace(chunk) != "" {
        chunks = append(chunks, chunk)
    }
}

C#

using var doc = PdfDocument.Open("book.pdf");
var full = doc.ToMarkdownAll();

const int chunkSize = 1000, overlap = 200;
var chunks = new List<string>();
for (int start = 0; start < full.Length; start += chunkSize - overlap)
{
    var end = Math.Min(start + chunkSize, full.Length);
    var chunk = full[start..end];
    if (!string.IsNullOrWhiteSpace(chunk))
        chunks.Add(chunk);
}

批量处理数千份 PDF

以 0.8 ms/页的速度,PDF Oxide 能飞快地扫完海量语料：

from pdf_oxide import PdfDocument, PdfError
from pathlib import Path

pdf_files = list(Path("corpus/").glob("**/*.pdf"))
print(f"正在处理 {len(pdf_files)} 份 PDF...")

all_chunks = []
errors = 0

for pdf_path in pdf_files:
    try:
        doc = PdfDocument(str(pdf_path))
        md = doc.to_markdown_all(
            detect_headings=True,
            include_images=False
        )
        if md.strip():
            all_chunks.append({
                "content": md,
                "source": str(pdf_path),
                "pages": doc.page_count(),
            })
    except PdfError:
        errors += 1

print(f"已抽取 {len(all_chunks)} 份文档,错误 {errors} 个")

在流水线里处理扫描版 PDF

任何语料中都可能混入扫描图像的 PDF。这时把 OCR 作为兜底：

from pdf_oxide import PdfDocument

doc = PdfDocument("mixed-corpus-file.pdf")
text = doc.extract_text(0)

if len(text.strip()) < 50:
    # 很可能是扫描页 —— 转用 OCR
    text = doc.extract_text_ocr(0)

具体配置见 OCR 指南。

为什么选 Markdown 而不是纯文本

特性 纯文本 Markdown
标题层级 丢失 保留（#、##、###）
表格 被摊平 GFM 表格语法
粗体/斜体 丢失 **粗体**、*斜体*
语义分块 困难 按标题切分
LLM 理解度 较低 更高（结构化输入）

Markdown 能给 LLM 提供更多文档结构方面的上下文,从而提升检索和生成质量。

大规模性能

语料规模 PDF Oxide pypdf pdfplumber
1,000 页 0.8 秒 12.1 秒 23.2 秒
10,000 页 8 秒 121 秒 232 秒
100,000 页 80 秒 1,210 秒 2,320 秒
通过率 100% 98.4% 98.8%

100% 通过率意味着你永远不用手动去查为什么索引里会缺文档。

相关页面