Geek-skills-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	Use Cases
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, both .md and _content_list.json 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 the user of any issues rather than delivering silently
• The backend choice is justified (simple text → pipeline; formula/table-intensive → vlm; uncertain → hybrid)
• For batch tasks, report the success/failure list, and give reasons for failures

Known Pitfalls

Pitfall	Symptom	Mitigation
Missing models on first run	Parsing directly without running mineru-models-download causes an error	Run the model download after installation; the download is large, so inform the user in advance about the time required
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 ~/.mineru.json 's device-mode to cuda
Overly high expectations for scanned documents	Poor parsing quality for low-clarity scanned PDFs	Inform the user in advance that the result for scanned documents depends on clarity; if the result is poor, retry once with a different backend, and if it is still poor, report it truthfully
Memory pressure with large files	Parsing a PDF with hundreds of pages in a single run causes memory to spike	Parse large files in batches or split them by chapter

Script

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