Why MinerU Dominates RAG Document Parsing: Tiers, Deployment & Structured Outputs

MinerU is an open-source document parsing tool developed by the OpenDataLab team at Shanghai AI Laboratory. It converts PDFs, scanned documents, images, and Office files into Markdown and structured JSON, preserving layout elements such as titles, tables, formulas, headers, and footers. The project has gained over 82,000 GitHub stars, a rare level of adoption for a document parsing library.

What MinerU Does Differently

Unlike text-only extractors such as pdfplumber, MinerU performs full layout restoration. It renders each PDF page as an image, runs layout detection to separate titles, body text, tables, figures, formulas, headers, and footers, then reorders them in reading order. Tables are output as HTML preserving row/column relationships, formulas as LaTeX, and scanned pages receive an additional OCR pass. All models can run locally without internet access.

Real-World Case Study: 2,000 Complex PDFs

The author processed over 2,000 bid documents containing two-column layouts, cross-page tables, and LaTeX formulas. Using pdfplumber, the reading order was scrambled and tables collapsed into single-column numbers. Switching to MinerU (standard tier) overnight produced structured_content.json with tables as HTML, formulas as LaTeX, and heading hierarchy intact — demonstrating why the tool spreads rapidly.

Core Approach: Layout Restoration via Vision-Language Model

Traditional libraries rely on character coordinates and cannot understand semantics, causing column interleaving, header/footer contamination, and loss of table structure. MinerU renders pages to images, detects layout regions, classifies each region (title, text, table, figure, formula, header/footer), and routes them to specialized models: table structure recognition → HTML, formula recognition → LaTeX, scanned regions → OCR.

Four Quality Tiers (Introduced in v4.0)

flash : Native text parsing + Flash OCR. Use for indexing, preview, Office documents. Runs on CPU / Apple Silicon.

basic : ONNX or Torch small models. Pure CPU, handles scans, formulas, tables.

standard (default): Small model + 1.2B VLM (MinerU2.5-Pro-2605-1.2B). Handles complex layouts; the model is trained specifically for document parsing, not a generic multimodal model, giving better stability and lower VRAM usage.

advanced : Same model with more inference compute. For high-value documents.

Installation (v4.0+; v2.x instructions are obsolete)

# Base package: ONNX + llama.cpp, CPU and Apple Silicon sufficient
uv pip install -U "mineru>=4.0,<5"

# With NVIDIA GPU, high throughput: installs vLLM on Linux
uv pip install -U "mineru[full]>=4.0,<5"

# In China, set model source to ModelScope to avoid slow downloads
export MINERU_MODEL_SOURCE=modelscope

After install, run mineru-kit models show to verify which backend is active (GPU vs CPU).

Command-Line Usage

Two entry points behave differently: mineru-kit parse — stateless, parses entire document by default. mineru parse — document library client, reads only first 10 pages of PDFs by default.

# Single file to Markdown, standard tier
mineru-kit parse paper.pdf -o paper.md --tier standard

# Batch directory to ZIP; explicit --pages all overrides default differences
mineru-kit parse ./docs -o ./out --format zip --pages all

# Indexing only, flash tier (no VLM), ~10x faster
mineru-kit parse manual.pdf -o manual.md --tier flash

Python API

Synchronous Parsing

from pathlib import Path
from mineru.parser import parse

# tier controls cost: flash uses native text, standard adds small model + VLM
result = parse(
    "paper.pdf",
    tier="standard",
    ocr_mode="txt",      # text PDFs skip OCR; scans use "ocr"
    page_range="1-20",   # 1-based, inclusive
)

# markdown() for humans, to_json() for programs — from same parse
Path("paper.md").write_text(result.markdown(), encoding="utf-8")
Path("paper.json").write_text(result.to_json(), encoding="utf-8")

Asynchronous Batch Processing

import asyncio
from pathlib import Path
from mineru.parser import parse_async

async def main():
    for pdf in sorted(Path("./docs").glob("*.pdf")):
        try:
            # Already in event loop, just await
            result = await parse_async(str(pdf), tier="standard")
            Path(f"./out/{pdf.stem}.md").write_text(result.markdown(), encoding="utf-8")
        except Exception as exc:
            print(f"{pdf.name} parse failed: {exc}")

asyncio.run(main())

Deployment Modes

Solo use : Run CLI directly; models download once and stay cached.

Shared model for multiple services : Start a V1 API server (

mineru-kit api-server --host 0.0.0.0 --port 8000 --tier standard

). Model loads once, saving VRAM vs per-process loads. For multi-GPU/multi-node, run a router (

mineru-kit router --host 0.0.0.0 --port 8002 --local-gpus auto

). Old endpoints (/file_parse, /tasks) removed in v4.0.

Gradio WebUI : mineru-kit webui for manual verification by non-technical colleagues. Not for production API traffic.

Client-Side API Usage

from mineru.parser import MinerUApiParser

# api_url is root before /v1; key via MINERU_API_KEY env var
parser = MinerUApiParser(api_url="http://127.0.0.1:8000", tier="standard")
print(parser.parse("contract.pdf").markdown())

Intermediate Outputs: The Key to Downstream Control

Beyond Markdown, MinerU retains middle.json and structured_content.json. Each block includes type, page_idx, bbox, and content. This enables custom chunking logic:

Table blocks → vector store as whole HTML (row/column relations preserved).

Formula blocks → extract LaTeX for dedicated retrieval.

Header/footer blocks → filter by coordinates.

This solves the common RAG headache of tables being split across chunks.

Custom Chunking Example

# structured_content gives page-level blocks; block-level slicing beats character splitting
for page in result.structured_content()["pages"]:
    for block in page["blocks"]:
        if block["type"] == "table":
            store_table(block["content"])   # table HTML, rows and columns intact
        elif block["type"] == "equation":
            store_formula(block["content"])  # LaTeX

When Not to Use MinerU

Pure text PDFs where only text is needed — pypdf finishes in tens of milliseconds; MinerU is overkill.

Latency-sensitive online APIs — standard tier takes seconds to tens of seconds; use async task queues instead.

License Note

Since v3.1 the license changed to a MinerU Open Source License based on Apache 2.0, more permissive than the previous AGPL. Still, read LICENSE.md before commercial use; do not rely on hearsay.

Author's Verdict & Cost-Saving Strategy

MinerU's popularity stems from three capabilities: private deployment, batch processing, and structured intermediate outputs. RAG teams lack control over data ingestion, not another cloud API. The author's practical pattern: run flash tier on the full corpus for indexing , then re-parse only high-recall documents with standard tier , cutting cost by over half compared to full standard parsing. While not necessarily the "best" parser, it is the only tool the author has found that keeps the entire data pipeline under control.