一、MinerU
MinerU 是一个面向 Agent 的文档解析工具,核心作用是把各种格式的文档(PDF、图片、Office 文档等)解析成可读、可引用、可继续阅读的结构化内容。
它的定位很明确:
不是RAG 框架
不是向量数据库
不是“聊天式文档问答”应用
是一个命令行文档阅读器,供 Agent 调用
它特别适合处理扫描件、表格、公式、复杂版面的文档。
二、支持的输入格式
| 类型 | 扩展名 |
|---|---|
.pdf(含扫描件、学术论文) | |
| 图片 | .png、.jpg、.jpeg、.webp、.gif、.bmp、.tiff、.jp2 |
| Word | .doc、.docx |
| PowerPoint | .ppt、.pptx |
| Excel | .xls、.xlsx |
| 富文本 | .rtf |
| OpenDocument | .odt、.ods、.odp |
| EPUB | .epub |
| OFD | .ofd |
| HTML | .html、.htm、.shtml |
| MHTML | .mhtml、.mht |
| CSV / TSV | .csv、.tsv |
注意:纯文本文件(.txt、.md、.markdown、.rst、.tex)不解析,直接读取。
三、四档解析质量(Quality Tiers)
MinerU 提供四档解析质量,控制质量、速度和计算资源的权衡:
| 档位 | 中文名 | 质量与速度 | 适用场景 |
|---|---|---|---|
| flash | 极速解析 | 质量最低,速度最快 | 预览、索引,不作为最终阅读质量 |
| basic | 基础解析 | 基础质量,速度中等 | 隐私本地阅读、低资源设备 |
| standard | 标准解析 | 标准高质量,速度与 basic 相近 | 默认档位,普通阅读和复杂文档 |
| advanced | 高级解析 | 困难文档质量更好,速度最慢 | 极难文档、追求最高质量 |
默认行为:
不指定
--tier时,默认用standardflash不会作为默认的最终阅读质量advanced不会自动选择,需要显式指定
四、安装方式
要求
Python >= 3.10, < 3.15
建议在虚拟环境中安装
方式一:使用 uv(推荐)
pip install uv uv venv .mineru --python 3.12 # Linux/macOS source .mineru/bin/activate # Windows (PowerShell) .\.mineru\Scripts\Activate.ps1 uv pip install -U "mineru>=4.0,<5"方式二:使用 uv tool
uv tool install --python 3.12 "mineru>=4.0,<5"方式三:使用全局 pip
pip install "mineru>=4.0,<5"默认安装即可开箱即用:小模型用 ONNX CPU 推理,VLM 用 llama.cpp Vulkan 模式,在绝大多数设备上兼容性良好。
如果设备有NVIDIA GPU,可以安装mineru[full]获得最佳吞吐:
mineru server stop mineru server status --json uv tool install --force "mineru[full]>=4.0,<5" mineru server start mineru server status --json五、模型引擎与硬件要求
| Extra | 模型引擎 | 安装方式 |
|---|---|---|
| base | ONNX + llama.cpp | 默认包含 |
| torch | ONNX + PyTorch + llama.cpp | mineru[torch] |
| full | ONNX + PyTorch + llama.cpp + vLLM/lmdeploy/mlx | mineru[full] |
| 档位 | 模型引擎 | 模型下载 | 最低内存 | 加速器 |
|---|---|---|---|---|
| basic | ONNX | ~0.8 GB | 2GB | 无(CPU 可用) |
| basic | PyTorch | ~0.8 GB | 8GB | 推荐 GPU/MPS |
| standard/advanced | ONNX + llama.cpp | ~2 GB | 8GB | CPU 可用,推荐 Vulkan |
| standard/advanced | PyTorch + llama.cpp | ~2 GB | 16GB | 需要 GPU/MPS,8GB+ 显存 |
| standard/advanced | PyTorch + vLLM/lmdeploy/mlx | ~3 GB | 16GB | 需要 GPU/MPS,8GB+ 显存 |
硬件推荐:
| 硬件 | 推荐启动档位 | 模型引擎 | Extra |
|---|---|---|---|
| MacOS Apple Silicon | standard | PyTorch + llama.cpp | torch(已内置) |
| MacOS Intel CPU | basic | ONNX | base |
| Linux/Windows NVIDIA GPU 8GB+ | standard | PyTorch + vLLM/lmdeploy | full |
| Linux/Windows NVIDIA GPU 4GB+ | basic | PyTorch | torch |
| Linux/Windows 现代 iGPU | standard | ONNX + llama.cpp | base |
| Linux/Windows 无现代加速器 | basic | ONNX | base |