mineru-pdf-parser

MinerU PDF Parser

Convert complex PDF documents into machine-readable Markdown/JSON format, suitable for LLM and RAG applications.

Installation

# 推荐使用uv安装
pip install uv
uv pip install -U "mineru[all]"

# 下载模型（首次使用）
mineru-models-download

Quick Start

Command Line

# 解析单个PDF
mineru -p input.pdf -o output_dir

# 批量解析
mineru -p pdf_folder/ -o output_dir

# 指定解析模式
mineru -p input.pdf -o output_dir --backend vlm      # VLM模式（高精度）
mineru -p input.pdf -o output_dir --backend pipeline # Pipeline模式（快速）
mineru -p input.pdf -o output_dir --backend hybrid   # 混合模式（平衡）

Python API

from mineru import MinerU

mineru = MinerU()
result = mineru.parse("document.pdf")

# 获取输出
markdown = result.to_markdown()
json_data = result.to_json()

For detailed API, see references/api_reference.md

Parsing Mode Selection

Mode	Features	Applicable Scenarios
pipeline	Fast, low resource usage	Simple documents, plain text PDFs
vlm	High precision, complex layouts	Academic papers, documents with formulas and tables
hybrid	Balanced speed and precision	General scenarios

Output Files

• {filename}.md - Markdown body
• {filename}_content_list.json - Structured JSON
• images/ - Extracted images
• {filename}_middle.json - Intermediate results (debugging)

For format details, see references/output_formats.md

Best Practices

Academic Papers

mineru -p paper.pdf -o output --backend vlm

Batch Processing

from mineru import MinerU
import os

mineru = MinerU(backend="hybrid")
for pdf in os.listdir("pdfs/"):
    if pdf.endswith(".pdf"):
        result = mineru.parse(f"pdfs/{pdf}")
        result.save(f"output/{pdf[:-4]}/")

RAG Data Preparation

sections = result.get_sections()
for section in sections:
    vector_db.add(section.title, section.content)

Enable GPU Acceleration

Modify ~/.mineru.json in device-mode to cuda。

For more, see references/best_practices.md

Acceptance Criteria (self-check before completing a parsing task)

• In the output directory, .md and _content_list.json both exist; report the actual paths to the user
• Spot-check 1-2 pages against the original PDF: tables/formulas are not obviously missing or garbled; proactively inform of issues rather than delivering silently
• The backend choice is justified (simple text→pipeline; dense formulas and tables→vlm; uncertain→hybrid)
• For batch tasks, report the success/failure list, and give reasons for failures

Known Pitfalls

Pitfall	Specific Manifestation	Countermeasure
Missing model on first run	Parsing directly without running mineru-models-download reports an error	Run the model download after installation; the download is large, so inform the user in advance that it takes time
Running vlm without a GPU	vlm mode is extremely slow on CPU, appearing to hang	Use pipeline/hybrid when there is no GPU; with a GPU, change the ~/.mineru.json device-mode to cuda
Overly high expectations for scanned documents	Poor parsing quality for low-clarity scanned PDFs	Inform in advance that the effect on scanned documents depends on clarity; when results are poor, switch the backend and retry once, and if still poor, report truthfully
Memory pressure with large files	Memory spikes when parsing a PDF of hundreds of pages in a single run	Parse large files in batches or split them by chapter

Script

Use scripts/mineru_parse.py for parsing, with support for error handling and logging.