mineru

项目地址： https://github.com/opendatalab/MinerU

官方文档： https://opendatalab.github.io/MinerU/

PyPI： mineru（4.0.12，截至 2026-10；4.x 与 3.x 的命令行入口不同，见下文）

许可证： AGPL-3.0

概述

MinerU 把 PDF、扫描件、图片与多种办公文档解析成结构化 Markdown / JSON，输出保留版面顺序、公式、表格与图片资源，可直接喂给 RAG 检索、翻译流水线或人工复核。

• 多档质量：flash/basic/standard/advanced 四档，按"速度 ↔ 精度 ↔ 硬件"取舍，而不是按旧版 backend 名字猜
• 两个入口：mineru（库式、带缓存与续读协议）与 mineru-kit（无状态、一次到底）
• 本地文档库：解析结果落库，用 doc:.../page:N 定位符续读，不必反复整篇重解析
• 可编程：Python DoclibClient 与 V1 HTTP API；另有 WebUI 与服务模式
• 后端自动选择：小模型走 ONNX/Torch，VLM 走 llama.cpp / vLLM / LMDeploy，按本机依赖与设备自动挑
• 容器化：官方 Dockerfile 面向 Linux + NVIDIA（Windows 走 WSL2）

---

环境准备

前置条件

项	要求
Python	>=3.10,<3.15（推荐 3.12）
操作系统	Linux / macOS / Windows；Docker 路径只覆盖 Linux + NVIDIA GPU
硬件	CPU 可跑（ONNX 小模型 + llama.cpp Vulkan）；NVIDIA GPU 装 mineru[full] 吞吐最好
磁盘	模型权重与文档库需要额外空间，默认在 ~/.mineru/models

方式一：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"

方式二：普通 pip（已有环境时）

python -m pip install -U "mineru>=4.0,<5"

需要最好吞吐时装 extras：

# NVIDIA GPU 推荐：自带匹配的 torch 与推理引擎
uv pip install -U "mineru[full]>=4.0,<5"

# 只补 torch 侧
uv pip install -U "mineru[torch]>=4.0,<5"

Windows 上 GPU 版 torch 需要单独装；macOS 默认安装即为最佳吞吐，不需要 [full]。

方式三：Docker（Linux + NVIDIA）

# 在仓库根目录（含 4.0 Dockerfile）执行
docker build -t mineru:4 -f docker/global/Dockerfile .

镜像基于 vLLM 0.21.0、默认 CUDA 13.0；构建期会显式选 Torch 小模型与 vLLM 权重（可在无 GPU 的构建机上准备），运行期固定 MINERU_MODEL_SMALL_BACKEND=torch、MINERU_MODEL_VLM_ENGINE=vllm。国内版 Dockerfile 走 ModelScope，global 版走 Hugging Face。

验证

mineru version --json          # 4.x 的版本查询；老 CLI 用 mineru --version
mineru --help                  # 查看当前安装支持的子命令
mineru-kit parse --help        # 无状态入口

---

命令行入口