站点图标 高效码农

MinerU震撼登场！开源文档解析工具让PDF处理效率飙升300%

高效码农

MinerU：让文档解析高效又智能

在当今数字化时代，文档处理已成为我们工作和学习中不可或缺的一部分。无论是科研人员处理学术论文，还是办公人员整理报告，亦或是学生整理学习资料，都离不开对文档内容的提取与转换。但传统文档解析方式往往存在诸多局限，比如格式混乱、内容提取不准确、无法识别复杂元素等。好消息是，一款名为 MinerU 的工具横空出世，为文档解析带来全新的解决方案，让文档处理变得高效且智能。

一、MinerU 是什么？

MinerU 是一款专注于文档内容提取的工具，它能够将 PDF 等格式的文档转化为机器可读的格式，例如 markdown 或 JSON。它最初诞生于 InternLM 的预训练过程中，主要目的是解决科学文献中符号转换的问题，但如今已发展成为一款功能强大的通用文档解析工具。MinerU 的优势在于，它不仅能高效地提取文本内容，还能精准识别文档中的各种复杂元素，如公式、表格、图片等，并将其转化为便于后续处理的格式。

二、MinerU 的关键特性

（一）去除冗余内容，保持语义连贯

在处理文档时，MinerU 能够智能地去除文档中的页眉、页脚、脚注、页码等冗余信息，只保留核心内容，确保提取后的文档语义清晰连贯。这对于科研人员和学生来说尤其重要，因为学术文献中往往包含大量的此类冗余信息，若手动去除，既费时又容易出错。

（二）按阅读顺序输出文本

MinerU 能够自动识别文档的布局，无论是单栏、多栏还是复杂布局，都能将文本内容按照人类自然阅读的顺序输出。这使得提取后的文档内容更易于阅读和理解，方便用户直接使用或进一步编辑。

（三）保留文档结构

MinerU 在提取文本的同时，还能保留原文档的结构，包括标题、段落、列表等。这对于需要对文档内容进行后续分析或处理的用户来说非常有用，因为文档的结构信息往往蕴含着重要的逻辑关系。

（四）精准识别多种元素

MinerU 能够自动识别并提取文档中的图片、图片描述、表格、表题及脚注等内容。此外，它还具备强大的公式识别能力，可将文档中的公式自动转换为 LaTeX 格式，方便在学术写作或技术文档中使用。

（五）支持多种语言和加速选项

MinerU 的 OCR 功能支持 84 种语言的检测与识别，无论是中文、英文还是其他小语种文档，都能轻松应对。而且，它还支持在纯 CPU 环境下运行，并兼容 GPU（CUDA）、NPU（CANN）和 MPS 加速，用户可根据自己的硬件条件选择合适的加速方式，提高文档解析效率。

（六）多种输出格式与可视化结果

MinerU 支持多种输出格式，如多模态和 NLP Markdown、按阅读顺序排序的 JSON 以及丰富的中间格式。同时，它还提供布局可视化和区域可视化等多种可视化结果，方便用户快速确认输出质量，确保提取的文档内容准确无误。

三、MinerU 的快速上手

（一）在线演示体验

MinerU 提供了便捷的在线演示服务，用户无需安装任何软件，只需通过浏览器访问其在线演示平台，如 OpenDataLab、HuggingFace 或 ModelScope 等，即可快速体验文档解析功能。这种方式非常适合初次接触 MinerU 的用户，能够快速了解其功能和效果。

（二）本地部署安装

1. 通过 pip 或 uv 安装

首先，确保系统已安装 Python 3.10 – 3.13 版本。然后，打开终端或命令提示符，输入以下命令：

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[core]"

2. 从源代码安装

如果需要对 MinerU 进行二次开发或定制化修改，可以从 GitHub 上克隆源代码进行安装：

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[core]

在 Linux 和 macOS 系统上，安装完成后会自动支持 CUDA/MPS 加速。对于 Windows 系统用户，若要使用 CUDA 加速，需前往 PyTorch 官方网站安装适配相应 CUDA 版本的 PyTorch。

3. 安装完整版（支持 sglang 加速）

如果设备具备 Ampere 或更新架构，并且拥有至少 24GB 的 GPU 显存，可安装支持 sglang 加速的完整版：

uv pip install -U "mineru[all]"

或者从源代码安装：

uv pip install -e .[all]

也可以通过 Dockerfile 构建镜像：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfile
docker build -t mineru-sglang:latest -f Dockerfile .

启动 Docker 容器：

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 \
  --ipc=host \
  mineru-sglang:latest \
  mineru-sglang-server --host 0.0.0.0 --port 30000

或者使用 Docker Compose 启动：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml
docker compose -f compose.yaml up -d

4. 安装客户端（仅需 CPU 和网络连接的边缘设备）

对于只需要 CPU 和网络连接的边缘设备，可安装客户端：

uv pip install -U mineru
mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://<host_ip>:<port>

（三）使用 MinerU

1. 命令行使用

基本用法

最简单的命令行调用方式为：

mineru -p <input_path> -o <output_path>

其中，<input_path> 是本地 PDF 文件或目录（支持 pdf/png/jpg/jpeg 格式），<output_path> 是输出目录。

查看帮助信息

用户可通过以下命令获取所有可用参数的详细描述：

mineru --help
参数详解
Usage: mineru [OPTIONS]

Options:
  -v, --version                   Show version and exit
  -p, --path PATH                 Input file path or directory (required)
  -o, --output PATH              Output directory (required)
  -m, --method [auto|txt|ocr]     Parsing method: auto (default), txt, ocr (pipeline backend only)
  -b, --backend [pipeline|vlm-transformers|vlm-sglang-engine|vlm-sglang-client]
                                  Parsing backend (default: pipeline)
  -l, --lang [ch|ch_server|... ]  Specify document language (improves OCR accuracy, pipeline backend only)
  -u, --url TEXT                  Service address when using sglang-client
  -s, --start INTEGER             Starting page number (0-based)
  -e, --end INTEGER               Ending page number (0-based)
  -f, --formula BOOLEAN           Enable formula parsing (default: on, pipeline backend only)
  -t, --table BOOLEAN             Enable table parsing (default: on, pipeline backend only)
  -d, --device TEXT               Inference device (e.g., cpu/cuda/cuda:0/npu/mps, pipeline backend only)
  --vram INTEGER                  Maximum GPU VRAM usage per process (pipeline backend only)
  --source [huggingface|modelscope|local]
                                  Model source, default: huggingface
  --help                          Show help information

2. 模型源配置

MinerU 在首次运行时会自动从 HuggingFace 下载所需的模型。如果无法访问 HuggingFace，用户可以切换模型源：

切换到 ModelScope 源

命令如下：

mineru -p <input_path> -o <output_path> --source modelscope

或者设置环境变量：

export MINERU_MODEL_SOURCE=modelscope
mineru -p <input_path> -o <output_path>
使用本地模型
1. 下载本地模型

用户可通过以下命令下载模型：

mineru-models-download --help

或者使用交互式命令行工具选择模型：

mineru-models-download

下载完成后，终端会显示模型路径，并自动将其写入用户目录下的 mineru.json 文件。

2. 使用本地模型进行解析

命令如下：

mineru -p <input_path> -o <output_path> --source local

或者通过环境变量设置：

export MINERU_MODEL_SOURCE=local
mineru -p <input_path> -o <output_path>

3. 使用 sglang 加速 VLM 模型推理

通过 sglang-engine 模式

命令为：

mineru -p <input_path> -o <output_path> -b vlm-sglang-engine
通过 sglang-server/client 模式

首先启动服务器：

mineru-sglang-server --port 30000

sglang-server 提供了一些常用参数供配置：

  • 如果拥有两块 12GB 或 16GB 显存的 GPU，可采用 Tensor Parallel（TP）模式：--tp 2
  • 若两块 GPU 显存为 11GB，除了启用 TP 模式，还需减少 KV 缓存大小：--tp 2 --mem-fraction-static 0.7
  • 若拥有两块或更多 24GB 及以上显存的 GPU，可启用 sglang 的多 GPU 并行模式以提升吞吐量：--dp 2
  • 可启用 torch.compile 来加速推理速度，大约提升 15%：--enable-torch-compile
  • 关于 sglang 参数的更多使用方法，可参考其官方文档

然后在另一个终端中使用客户端：

mineru -p <input_path> -o <output_path> -b vlm-sglang-client -u http://127.0.0.1:30000

关于输出文件的详细信息，可参考输出文件文档。

4. API 使用

用户还可以通过 Python 代码调用 MinerU，示例代码位于：

👉Python 使用示例

5. 部署衍生项目

社区开发者基于 MinerU 创建了多种扩展项目，包括基于 Gradio 的图形界面、基于 FastAPI 的 Web API、具有多 GPU 负载均衡功能的客户端 / 服务器架构以及基于官方 API 的 MCP Server 等。这些项目通常提供更出色的用户体验和额外功能，详细部署说明可参考：

👉衍生项目文档

四、MinerU 的更新历程

MinerU 自开源以来，不断迭代更新，功能日益完善。以下是其部分重要更新节点：

（一）2025 年 6 月 20 日，2.0.6 版本发布

修复了在 vlm 模式下因无效块内容导致的解析偶尔中断问题，以及因表格结构不完整引起的解析中断问题。

（二）2025 年 6 月 17 日，2.0.5 版本发布

解决了在 sglang-client 模式下仍需下载模型的问题，以及在该模式下运行时对 torch 等包的不必要依赖问题。同时，修复了在同一个进程中通过多个 URL 启动多个 sglang-client 实例时，只有第一个实例生效的问题。

（三）2025 年 6 月 13 日，2.0.0 版本发布

这是 MinerU 的一次重大重构和升级。在架构方面，代码组织和交互方式得到深度重构，系统易用性、可维护性和可扩展性显著提升。移除了对 pymupdf 的依赖，向更开放、合规的开源方向迈进。同时，实现了参数设置的简化，大部分参数可通过命令行或 API 直接设置，无需手动编辑 JSON 配置文件。新增了模型自动下载和更新机制，支持完全离线环境的部署。代码结构得到精简，提升了可读性和开发效率，并统一了中间格式输出，采用标准化的 middle_json 格式，与基于此格式的二次开发场景高度兼容。

在模型方面，MinerU 2.0 集成了最新研发的小参数、高性能多模态文档解析模型。该模型参数量不足 1B，却在解析精度上超越了传统的 72B 级别视觉 – 语言模型（VLM）。它集成了多语言识别、手写识别、版面分析、表格解析、公式识别和阅读顺序排序等核心任务于一身。借助 sglang 加速，单块 NVIDIA 4090 显卡上的推理速度峰值可超过 10000 tokens/s，能够轻松应对大规模文档处理需求。

需要注意的是，MinerU 2.0 存在一些不兼容的变更。为了提升整体架构的合理性和长期可维护性，Python 包名从 magic-pdf 更改为 mineru，命令行工具也从 magic-pdf 更改为 mineru。此外，出于模块化系统设计和生态系统一致性考虑，MinerU 2.0 不再包含 LibreOffice 文档转换模块。如果需要处理 Office 文档，建议通过独立部署的 LibreOffice 服务将文档转换为 PDF 格式后再进行后续解析操作。

（四）其他版本更新

从 2024 年 7 月首次开源至今，MinerU 经历了多个版本的迭代。每一次更新都带来了性能的优化、功能的增强以及对新需求的满足。例如，2024 年 11 月 22 日发布的 0.10.0 版本引入了混合 OCR 文本提取能力，显著提升了在复杂文本分布场景下的解析性能；2025 年 1 月 10 日发布的 1.0.1 版本带来了全新的 API 接口、增强的兼容性以及自动语言识别功能等。

五、MinerU 的应用场景

（一）学术研究

对于科研人员而言，MinerU 是处理学术文献的得力助手。它能够快速、准确地提取文献中的文本、公式、表格等内容，将其转化为适合进一步分析和引用的格式。例如，在撰写学术论文时，科研人员可以利用 MinerU 快速提取相关文献中的关键信息，整合到自己的研究中，提高科研效率。

（二）办公自动化

在办公场景中，MinerU 可用于处理各种报告、合同等文档。它能够去除文档中的冗余信息，提取核心内容，并保持文档结构完整，方便办公人员进行信息整理和汇报。此外，其支持的多种输出格式也便于与其他办公软件进行集成，实现办公自动化。

（三）教育教学

教师可以借助 MinerU 提取教学资料中的内容，制作电子教案或在线课程资源。学生则可以利用它整理学习资料，提取重点知识，辅助学习。特别是对于理工科学生，MinerU 的公式识别功能能够帮助他们更好地整理和理解复杂的数学、物理公式等。

（四）数据分析

数据分析师在处理包含大量文本和数据的文档时，MinerU 可以快速提取表格、图片描述等数据相关元素，将其转化为便于分析的格式，如 JSON 等。这大大节省了数据预处理的时间，提高了数据分析的效率。

六、MinerU 的优势与局限

（一）优势

  1. 高效精准 ：MinerU 能够快速解析文档，准确识别各种元素，节省人工处理时间，提高工作效率。
  2. 功能丰富 ：支持多种文档格式、多种语言，具备强大的公式、表格识别能力，满足不同用户在不同场景下的需求。
  3. 灵活易用 ：提供多种安装和部署方式，用户可根据自身硬件条件和需求选择合适的方案。同时，命令行和 API 的使用方式也方便用户集成到自己的工作流程中。
  4. 开源免费 ：作为开源项目，MinerU 免费提供给用户使用，降低了文档处理的成本，也促进了技术的交流和共享。

（二）局限

  1. 对复杂布局支持有限 ：在面对极其复杂的文档布局时，MinerU 的阅读顺序确定可能会出现偏差，导致部分区域的内容提取顺序不准确。
  2. 不支持垂直文本 ：对于垂直排版的文本，MinerU 无法正确识别和提取。
  3. 对特殊格式识别能力不足 ：部分不常见的列表格式、代码块以及漫画书、艺术画册、小学教材和练习册等特殊类型的文档，MinerU 的解析效果不佳。
  4. 表格和 OCR 识别存在误差 ：在复杂表格中可能出现行列识别错误，对于一些生僻语言的 PDF，OCR 识别的字符准确性也有待提高。

七、MinerU 的未来发展

尽管 MinerU 已经取得了显著的成果，但仍有很大的发展空间。根据项目规划，未来 MinerU 将继续优化现有功能，提高对复杂文档的解析能力，特别是提升对特殊格式和垂直文本的识别效果。同时，研发团队也将探索新的技术和算法，增加新的功能，如代码块识别、化学公式识别和几何形状识别等，以满足更多用户的需求。

此外，随着 AI 技术的不断发展，MinerU 有望与更多的 AI 模型和工具进行集成，实现更智能的文档处理和分析。例如，结合自然语言处理模型，对提取的文档内容进行语义理解和分析，为用户提供全面的文档智能处理解决方案。

八、总结

MinerU 作为一款开源的文档解析工具，凭借其高效、精准、功能丰富和灵活易用的特点，为科研人员、办公人员、学生等各类用户在文档处理方面带来了极大的便利。虽然它在某些方面仍存在局限，但随着技术的不断进步和更新，MinerU 有望不断完善，成为文档处理领域的佼佼者。如果你经常需要处理各种文档，不妨尝试使用 MinerU，相信它会为你带来意想不到的惊喜和效率提升。

在使用 MinerU 的过程中，如果你遇到任何问题或有好的建议，可以通过其 GitHub 页面提交 issue，与开发团队和其他用户进行交流。同时，也感谢所有为 MinerU 贡献代码和智慧的开发者们，正是因为他们的努力，才让 MinerU 不断发展壮大，为更多人所用。

退出移动版