MinerU: Structure-Aware Document Parsing for RAG and Agent Workflows

Introduction

When building RAG knowledge bases, developers often hit a ceiling: better embedding models, chunk tuning, and reranking fail to fix retrieval errors caused by garbled tables, broken formulas, and scrambled reading order in parsed documents. The root cause lies not in the retrieval layer but in document parsing — traditional tools merely extract text characters by coordinate order without understanding layout.

MinerU addresses this by parsing document structure first, then reassembling content in human reading order. With over 80,000 GitHub stars, it positions itself as AI-ready data infrastructure. This article covers its core advantages, internal pipeline, version 4.0 upgrades (locator and four parsing tiers), code usage, tier selection guide, Agent-centric locator value, pros and cons, and applicable scenarios.

Why Traditional PDF Parsing Fails

Tools like PyMuPDF perform character-level extraction ("picking characters") without semantic awareness. They cannot distinguish headings, tables, or formulas. Three fatal problems arise:

Multi-column layouts: Dual-column papers are read left-column top-to-bottom then right-column top-to-bottom. Coordinate-based sorting often concatenates the bottom of the left column with the top of the right column, breaking context.

Tables: Table cells exist as independent text blocks; extraction yields scattered numbers and labels with lost row/column relationships. RAG retrieval on such fragments leaves the LLM unable to map values to metrics.

Formulas: Formulas appear as images or special-font symbols. Character extractors either miss them or output garbled code. For technical papers, losing formulas loses half the content.

MinerU's approach is "understand structure then reorganize": it detects page elements (headings, paragraphs, tables, formulas, images) via layout analysis, processes each element type with specialized models (LaTeX for formulas, HTML/OTSL for tables), and reassembles everything in reading order into structured Markdown or JSON.

MinerU's Processing Pipeline

The pipeline operates in four scenario-aware steps:

Document type detection: Native PDFs with extractable text/vectors (e.g., arXiv papers) are parsed directly via PyMuPDF, avoiding unnecessary image conversion. Scanned or image-only pages trigger OCR.

Layout analysis: A vision model locates text blocks, tables, figures, and formulas, determining segmentation and reading order.

Element-specific processing: Formulas → LaTeX via proprietary model; tables → HTML or OTSL structure; images extracted with position metadata.

Structured reassembly: Content reordered by human reading logic, stripping headers/footers/page numbers, preserving heading hierarchy and paragraph structure.

MinerU 4.0: Locator and Four Parsing Tiers

Released September 2026, version 4.0 targets Agent-era workflows.

Stable Locator

Previous parsers output plain text; Agents could not trace a passage back to its exact page and block. MinerU 4.0 emits a stable locator for every block: doc:{id}/tier:{tier}/page:{page}/block:{block} This enables Agents to first read the document structure, identify relevant sections, then precisely jump to the original location for verification, citation, or continued reading — without re-parsing the whole document or stuffing hundreds of pages into context.

Four Parsing Tiers

Replacing the old pipeline/vlm/hybrid selection, four tiers balance cost and quality:

flash — Fast preview/indexing; no inference models, parses native text only.

basic — Lightweight processing; small models for OCR/formulas/tables, runnable on CPU.

standard — Daily high-quality parsing (default); small models + VLM, balances quality and speed.

advanced — Complex/difficult documents; allocates more inference compute for highest quality.

Developers choose per document: flash for contracts, standard for academic papers, advanced for tough scans.

Code Examples

Installation

Base package (ONNX CPU small models + llama.cpp VLM):

pip install uv
uv pip install -U "mineru"

Full version with GPU-accelerated VLM:

uv pip install -U "mineru[full]"

Command-Line Parsing

# Parse single PDF, default reads first 10 pages, returns continuation command
mineru parse input.pdf --json

# Read all pages, output Markdown
mineru parse input.pdf --pages all -o output.md

Note: 4.0 defaults to reading only the first 10 pages and returns a next_request command for progressive reading — designed for Agents to skim first, then deepen.

Java Integration via HTTP Service

MinerU is a Python tool; Java projects integrate through its HTTP service (V1 API): mineru server start Java client logic (upload → create job → poll):

@Service
public class MinerUClient {
    public String parseDocument(MultipartFile file, String tier) throws Exception {
        // 1. Upload file, get file_id
        String uploadResp = upload(file);
        String fileId = JsonPath.read(uploadResp, "$.id");

        // 2. Create parsing job
        String jobResp = createJob(fileId, tier); // tier: flash/basic/standard/advanced
        String jobId = JsonPath.read(jobResp, "$.job_id");

        // 3. Poll status until completion
        while (true) {
            String status = getJobStatus(jobId);
            if ("completed".equals(status)) {
                return getJobResult(jobId); // returns Markdown or JSON
            }
            if ("failed".equals(status)) {
                throw new RuntimeException("Parsing failed");
            }
            Thread.sleep(2000);
        }
    }
}

Key point: parsing is asynchronous; long documents may take minutes. Java side must poll or use callbacks, not block synchronously.

Choosing the Right Tier

The four-tier design ensures you don't run the heaviest model for simple tasks. Quick reference:

Contracts/preview → flash

Academic papers/daily high-quality → standard

Difficult scans/complex layouts → advanced

Why Agents Need Locators

Locators turn document parsing from a one-time conversion into a queryable knowledge base. Agents can:

Read structure first to locate relevant passages.

Precisely return to the original text for verification.

Avoid feeding entire documents into context or re-parsing.

This progressive read-verify loop is the essence of true Agent workflows.

Pros and Cons

Pros

Structured output, RAG-friendly: Markdown/JSON with heading hierarchy, table HTML, formula LaTeX — chunk quality and retrieval accuracy far exceed character-level extraction.

Native multi-format support: PDF, images, DOCX, PPTX, XLSX, EPUB, OFD, HTML — no pre-conversion needed.

Four tiers, cost-on-demand: Match compute to document complexity.

Agent locator: Enables precise citation and progressive reading.

Fully local, privacy-controlled: Runs locally by default; only --remote uploads documents. Anonymous telemetry can be disabled.

80k+ stars, community-validated: Since open-sourcing in 2024, widely adopted in RAG pipelines and enterprise document processing.

Cons

Less optimized for non-academic documents: Core gene is solving scientific literature symbol conversion; contracts/invoices work but lack targeted optimization.

No support for handwritten Chinese or vertical ancient texts: Explicit limitation; alternative solutions required.

Python tool, Java integration via HTTP: Adds network layer and async polling complexity.

Some dependencies carry separate licenses: e.g., PyMuPDF (AGPL); enterprises must verify compliance.

Applicable Scenarios

RAG knowledge base preprocessing: Strongly recommended — structured output feeds directly into vector stores.

Academic paper parsing: Strongly recommended — restores LaTeX formulas, HTML tables, dual-column order.

Enterprise document digitization: Strongly recommended — multi-format support, locator enables traceability.

Agent workflow document reading: Strongly recommended — 4.0 locator + progressive reading.

Scanned document OCR: Recommended — built-in multilingual OCR; weak on handwriting.

Contracts/invoices: Evaluate — usable but not optimized like academic scenes.

Handwritten Chinese / vertical ancient texts: Not recommended — explicitly unsupported.

Conclusion

MinerU upgrades document parsing from "readable" to "directly usable." RAG's ceiling is the parsing layer: feeding LLMs scrambled text, broken tables, and garbled formulas yields garbage answers. MinerU understands document structure and reassembles content per human reading logic, outputting structured, traceable, Agent-ready Markdown/JSON. Version 4.0's locator transforms parsing into a reusable knowledge base where Agents read structure, dive into details, and verify against source — the core of Agent workflows.

Limitations remain: non-academic document optimization is ongoing, handwritten/vertical ancient texts unsupported, Java integration requires HTTP. Yet for RAG, academic parsing, and enterprise digitization, MinerU is a battle-tested, continuously iterated, open-source choice validated by 80,000+ developers.

References:

GitHub: https://github.com/opendatalab/MinerU

Official Docs: https://opendatalab.github.io/MinerU/