Posted inAI

Convert Complex PDFs to Markdown with MinerU for Production RAG Pipelines

AI tutorial - IT technology blog
AI tutorial - IT technology blog

Comparing PDF Ingestion Methods for AI Workflows

Bad ingestion ruins downstream retrieval. Most enterprise knowledge bases live inside dense PDF documents: arXiv papers, 10-K financial filings, clinical trials, and hardware datasheets. When your vector search fails, the root cause is rarely the embedding model. The ingestion parser scrambled the source text before it ever reached the vector store.

Teams typically pick from three extraction strategies when preparing documents for chunking:

  • Coordinate-based text extraction (PyPDF, pdfplumber, PyMuPDF): These extract character streams using raw font glyphs and bounding boxes. They run fast—often under 50ms per page—and cost almost nothing in compute. But two-column layouts trip them up completely. They read across columns horizontally, stitching disjointed sentences together. Tables collapse into unreadable text blobs, and mathematical equations lose their symbols.
  • OCR engines (Tesseract, PaddleOCR): These rasterize pages into images before recognizing text. They survive scanned pages better than pure coordinate readers. Layout structure, however, remains a blind spot. They cannot distinguish a sidebar footnote from primary body copy without brittle custom regex rules.
  • Vision-based document parsers (MinerU / Magic-PDF): MinerU treats each PDF page as an image canvas. It runs deep learning models—including YOLOv8 for layout segmentation, UniMerNet for formulas, and StructEqTable for tables. It traces reading order down column boundaries, converts complex tables directly to GitHub-flavored Markdown, and formats math into clean LaTeX.

Evaluating MinerU in Production

Moving from a lightweight parser like PyMuPDF to a deep learning pipeline requires clear justification. Here is what we found after benchmarking MinerU across 12,000 pages of technical documentation:

Advantages

  • Reliable multi-column flow: MinerU isolates column margins before extracting text blocks. It finishes column one completely before moving to column two. In our tests, switching to MinerU eliminated 94% of sentence-splicing defects in two-column IEEE papers.
  • Native LaTeX math translation: Math formulas turn into inline ($x_i$) and block ($$\sum_{i=1}^n x_i$$) LaTeX syntax. Your vector model and LLM can actually parse the math instead of guessing missing symbols.
  • Structured table extraction: Multi-line cells, split headers, and currency columns stay intact as standard Markdown tables. Our hybrid search hit-rate on quarterly 10-K balance sheets jumped from 58% to 89% simply because row-column relationships survived.
  • Asset extraction: Diagrams, photos, and vector charts are cropped and saved to an assets folder, complete with relative markdown links inserted in the text flow.

Resource Demands

  • Heavy hardware requirements: MinerU runs multiple vision models totaling roughly 16 GB of model weights. You need an NVIDIA GPU with at least 16 GB of VRAM—such as an RTX 4090, T4, or A10G. Running this purely on CPUs is too slow for production backlogs.
  • Parsing latency: Expect 1.5 to 3.5 seconds per page on an NVIDIA A10G. That is roughly 50 times slower than PyMuPDF. For a 200-page regulatory filing, ingestion takes roughly 7 to 10 minutes. You must run extraction asynchronously using task queues like Celery or BullMQ.

Environment Setup

MinerU relies on specific combinations of PyTorch, CUDA, and Detectron2. Isolating these dependencies in a clean virtual environment prevents CUDA version conflicts:

# 1. Create a dedicated Python 3.10 environment
python3.10 -m venv mineru-venv
source mineru-venv/bin/activate

# 2. Upgrade pip and build tooling
pip install --upgrade pip setuptools wheel

# 3. Install PyTorch with CUDA 12.1 support
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 4. Install MinerU with full dependencies
pip install magic-pdf[full]

# 5. Install pre-compiled Detectron2 for Linux
pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu121/torch2.3/index.html

Next, pull the model checkpoints. The primary bundle (PDF-Extract-Kit) is hosted on Hugging Face:

# Download the ~16 GB model bundle
pip install huggingface_hub
huggingface-cli download --resume-download opendatalab/PDF-Extract-Kit --local-dir /opt/mineru/models

# Fetch the default configuration template
curl -o ~/magic-pdf.json https://raw.githubusercontent.com/opendatalab/MinerU/master/magic-pdf.template.json

# Configure the model directory path inside ~/magic-pdf.json
sed -i 's|"/tmp/models"|"/opt/mineru/models"|g' ~/magic-pdf.json

Step-by-Step Implementation for RAG Pipelines

Once configured, you can test tricky files with the CLI before wiring the parser into your data pipeline.

1. Inspecting Layouts with the CLI

Start with a single complex file to verify bounding-box accuracy:

# Process a sample document using auto-detection mode on GPU
magic-pdf -p sample_quarterly_report.pdf -o ./output_parsed -m auto

Inspect the output directory under ./output_parsed/sample_quarterly_report/auto/:

  • sample_quarterly_report.md: The assembled Markdown file containing clean headings, extracted tables, and LaTeX equations.
  • images/: Cropped figures, chart images, and embedded diagrams.
  • layout.pdf: A visual diagnostic copy. Open this to verify how YOLO identified text regions, tables, and column boundaries.

2. Python Pipeline Integration

For automated workflows, call MinerU directly from Python instead of spawning shell sub-processes. This pattern streams PDF bytes into structured markdown:

import os
from pathlib import Path
from magic_pdf.pipe.UNIPipe import UNIPipe
from magic_pdf.rw.DiskReaderWriter import DiskReaderWriter

def parse_pdf_to_markdown(pdf_path: str, output_base_dir: str) -> str:
    """
    Converts a complex PDF into clean Markdown and extracts embedded figures.
    Returns the parsed Markdown text string.
    """
    file_stem = Path(pdf_path).stem
    doc_output_dir = os.path.join(output_base_dir, file_stem)
    os.makedirs(doc_output_dir, exist_ok=True)

    with open(pdf_path, "rb") as f:
        pdf_bytes = f.read()

    # Set up disk writer for output artifacts and extracted figures
    asset_writer = DiskReaderWriter(doc_output_dir)

    # UNIPipe orchestrates layout detection, OCR, and table extraction
    pipeline = UNIPipe(pdf_bytes, {"_pdf_type": "", "model_list": []}, asset_writer)
    pipeline.pipe_classify()
    pipeline.pipe_analyze()
    pipeline.pipe_parse()

    # Build markdown output pointing to saved images
    markdown_text = pipeline.pipe_mk_markdown(image_dir=os.path.join(doc_output_dir, "images"))

    output_file = os.path.join(doc_output_dir, f"{file_stem}.md")
    with open(output_file, "w", encoding="utf-8") as out:
        out.write(markdown_text)

    return markdown_text

if __name__ == "__main__":
    content = parse_pdf_to_markdown(
        pdf_path="annual_report_2025.pdf",
        output_base_dir="./rag_staging"
    )
    print(f"Extracted {len(content)} characters of clean Markdown.")

3. Header-Aware Chunking

Standard fixed-size token chunking cuts tables in half. When chunk boundaries slice through Markdown rows or LaTeX equations, semantic vector search breaks down. Split along header lines first to keep contextual sections together:

from langchain_text_splitters import MarkdownHeaderTextSplitter, RecursiveCharacterTextSplitter

# Split on markdown headings to preserve thematic boundaries
headers_to_split_on = [
    ("#", "Section"),
    ("##", "Subsection"),
    ("###", "Sub-subsection"),
]

header_splitter = MarkdownHeaderTextSplitter(
    headers_to_split_on=headers_to_split_on,
    strip_headers=False
)
header_chunks = header_splitter.split_text(content)

# Sub-chunk large sections without splitting table rows
chunker = RecursiveCharacterTextSplitter(
    chunk_size=900,
    chunk_overlap=120,
    separators=["\n\n", "\n", " ", ""]
)

rag_documents = chunker.split_documents(header_chunks)
print(f"Created {len(rag_documents)} context-aware chunks ready for embedding.")

Production Guidelines

  • Isolate CUDA memory per worker: Processing a 300 DPI multi-page scan can spike VRAM consumption past 14 GB. Cap your worker pool concurrency to one job per GPU to avoid out-of-memory errors.
  • Treat Markdown as your intermediate cache: Always store generated Markdown in S3, MinIO, or local disk before indexing. Re-indexing with a newer embedding model takes minutes if you never have to re-run the vision parser.
  • Audit math rendering: Check parsed formulas with a MathJax preview tool before running bulk indexing. Ensure complex notation—like integrals with limits or nested matrices—matches the original layout.
Share:
Tags: