MinerU：把复杂文档转为MD格式的高精度解析引擎

PDF 里的公式、表格、多栏排版，直接复制粘贴到大模型里往往变成一团乱码。MinerU 要解决的正是这个问题：把 PDF、DOCX、PPTX、XLSX、图片、网页等复杂文档，高精度地转换成结构清晰、LLM 可直接使用的 Markdown / JSON。

一、项目简介

1.1 MinerU 是什么

MinerU 是由 OpenDataLab（上海人工智能实验室旗下数据开放平台）开源的一款高精度文档解析引擎，诞生于 InternLM（书生·浦语大模型）的预训练过程，最初专注于解决科学文献中的数学符号转换问题，如今已发展为面向 LLM / RAG / Agent 工作流的通用文档理解基础设施。

它的核心能力可以概括为一句话：将复杂排版的文档，无损地还原为机器可理解的结构化文本。公式转成 LaTeX、表格转成 HTML、布局按人类阅读顺序重建，输出的 Markdown 可以直接送入大模型进行问答、摘要或知识库构建。

项目地址：https://github.com/opendatalab/MinerU
官方文档：https://opendatalab.github.io/MinerU
在线体验：https://mineru.net
开源协议：MinerU Open Source License（基于 Apache 2.0，3.1.0 版本起从 AGPLv3 迁移，大幅降低了商业部署门槛）
Python 要求：3.10 ~ 3.13（Windows 平台因依赖限制仅支持 3.10 ~ 3.12）

1.2 核心功能特性

能力	说明
全格式输入	原生支持 PDF、图片、DOCX、PPTX、XLSX，同时支持网页提取
公式识别	自动识别行内/行间数学公式并转换为 LaTeX
表格识别	自动识别表格并转换为 HTML，支持跨页表格合并
布局重建	保留标题、段落、列表等原始结构，单栏/多栏/复杂排版均按人类阅读顺序输出
智能清洗	自动去除页眉、页脚、脚注、页码等干扰元素，保证语义连贯
OCR 能力	VLM + OCR 双引擎，支持 109 种语言；可自动检测扫描版 PDF 和乱码 PDF 并启用 OCR
多种输出	多模态 Markdown、NLP Markdown、按阅读顺序排序的 JSON、丰富的中间格式
可视化	支持布局可视化、span 可视化，方便调试与校验解析质量
多种调用方式	内置命令行（CLI）、FastAPI 服务、Gradio WebUI、MCP Server

1.3 适用场景

RAG 知识库构建：把论文、财报、合同、技术手册批量转成干净文本，接入 LangChain、LlamaIndex、RAGFlow、Dify、FastGPT 等框架；
学术文献处理：精确还原公式、表格、参考文献结构，是科研人员做文献精读与综述的得力工具；
AI 编程辅助：通过 MCP Server 接入 Cursor、Claude Desktop、Windsurf，让 AI 助手直接"读懂"本地 PDF；
数据要素加工：为大模型训练/微调准备高质量语料。

1.4 版本演进（近期重点）

3.4（2026/06）：OCR 模型升级为 PP-OCRv6，OCR 精度提升约 11%、处理速度提升约 100%；新增模型源自动选择，下载前优先检查本地缓存；
3.3（2026/06）：新增 effort 解析强度参数（medium 相比 high 仅降 0.13 分，速度提升 35%~220%）；VLM 模型升级为 MinerU2.5-Pro-2605-1.2B；
3.1.0（2026/04）：许可证从 AGPLv3 迁移到基于 Apache 2.0 的自定义许可证；新增原生 PPTX、XLSX 解析；
3.0.0（2026/03）：原生 DOCX 解析（端到端速度提升数十倍）；滑动窗口机制大幅降低长文档峰值内存；全面支持多线程并发推理。

二、Windows 详细使用教程

MinerU 在 Windows 上有三种使用方式，按上手难度从低到高排列：

方式	适合人群	特点
桌面客户端	所有用户（推荐）	开箱即用、无需登录、无需编程，拖拽即解析
在线版	临时使用、不想装软件	打开网页即用，有每日免费额度
本地开源部署	开发者、批量/私有化需求	免费无限制、数据不出本机、可 GPU 加速

2.1 方式一：桌面客户端（推荐）

官方桌面客户端是普通用户的首选：无需登录、无需编程、无需配置 Python 环境，下载安装后拖拽文件即可开始解析。

下载与安装：

打开官方下载页 https://mineru.net/client ，选择 Windows 版本下载安装包（约 430 MB）；
双击下载的 .exe 安装包，同意许可协议；
选择安装范围（选"仅为我安装"即可）与安装路径，点击安装，等待完成；
启动 MinerU 客户端，无需注册登录即可直接使用。

客户端同时提供 macOS 版本（下载页区分 Apple silicon 与 Intel 芯片两个版本），本文以 Windows 版为例。

使用方法：

导入文件：把 PDF、Word、PPT、Excel 或图片直接拖拽进客户端窗口，也可以粘贴网页 URL 解析网页内容；
批量处理：支持一次拖入多个文件排队解析，可自定义处理优先级，处理过程有实时进度条，卡在哪个文件一目了然；
选择输出：按需选择输出格式（Markdown / JSON / CSV / HTML / LaTeX 等）与识别语言；
开始解析：点击转换，完成后即可在线预览并导出结果——公式自动转为 LaTeX，跨页、合并单元格的复杂表格自动还原；
内置翻译：客户端集成了翻译功能，可在解析的同时将外文文献译为中文，适合快速精读英文论文。

客户端与本地部署怎么选： 客户端走官方云端解析通道，省心省力，适合日常论文阅读、资料提取；如果文档涉密、要求完全离线，或需要每天处理海量文件，再考虑下面的本地开源部署。

2.2 方式二：在线版（免安装）

打开 https://mineru.net 注册登录后，直接在网页中上传文件解析。据官方说明，单个文件限制约 200 MB / 600 页，免费额度约每天 2000 页（以官网实际政策为准），解析结果可在线预览导出，也可一键导出至 Dify / Notion。适合临时处理少量文件，或在安装客户端前先试试效果。

2.3 方式三：本地开源部署（进阶）

以下面向有开发能力的用户，适用于免费无限制、数据不出本机的场景。

环境要求：

Python 3.10 ~ 3.12（关键依赖 ray 在 Windows 上不支持 3.13，务必注意；安装 Python 时勾选 “Add python.exe to PATH”）；
内存 16 GB 以上（推荐 32 GB+），磁盘预留 20 GB+（推荐 SSD）；
可选：Volta 架构及以后的 NVIDIA 显卡（显存 ≥ 4 GB）用于 GPU 加速。

安装（约 5 分钟）：

:: 创建工作目录并创建虚拟环境
mkdir D:\mineru-work && cd /d D:\mineru-work
python -m venv .venv
.venv\Scripts\activate

:: 安装 MinerU 完整版
pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

首次运行与模型下载： 直接执行解析命令即会自动下载模型（3.4+ 会根据网络环境自动选择更优模型源，且优先复用本地缓存）：

mineru -p D:\test\demo.pdf -o D:\test\output

常用命令：

:: 基本用法（有 N 卡时自动 GPU 加速）
mineru -p <输入路径> -o <输出路径>

:: 纯 CPU 环境显式指定 pipeline 后端
mineru -p <输入路径> -o <输出路径> -b pipeline

:: 批量处理整个文件夹
mineru -p D:\papers -o D:\papers_output

输出目录中每个文档会生成独立文件夹，包含 Markdown、按阅读顺序排列的 JSON、提取的图片，以及布局/span 可视化文件。

以后每次使用前，需先进入 D:\mineru-work 执行 .venv\Scripts\activate 激活环境。模型源手动配置见官方「模型源文档」：https://opendatalab.github.io/MinerU/usage/model_source/

2.4 进阶用法（简要）

本地部署后还有几种扩展玩法，此处仅作指引，详细参数请查阅官方使用指南（https://opendatalab.github.io/MinerU/usage/ ）：

Gradio WebUI：执行 mineru-gradio --server-name 127.0.0.1 --server-port 7860，浏览器访问 http://127.0.0.1:7860 获得图形界面；
本地 API：执行 mineru-api 启动 FastAPI 服务，提供同步 POST /file_parse 与异步 POST /tasks 端点，便于集成进自有系统；多机多卡可用 mineru-router 做负载均衡；
MCP Server：接入 Cursor、Claude Desktop、Windsurf 等 AI 编程工具，让 AI 直接读取本地文档；
Docker：仅支持 Linux 和 WSL2 环境，Windows 原生用户建议直接用上面的 pip 安装方式；
CUDA 加速未生效：通常是 PyTorch 装成了 CPU 版，参考官方 FAQ（https://opendatalab.github.io/MinerU/faq/ ）安装与显卡匹配的 PyTorch。

2.5 三种推理后端怎么选

MinerU 3.x 提供三类解析后端，适用于不同的硬件条件与精度需求：

解析后端	pipeline	*-engine（vlm/hybrid）	*-http-client
后端特性	兼容性最好，快速稳定、无幻觉	精度最高，硬件要求高	连接 OpenAI 兼容服务器
精度（OmniDocBench v1.6）	86.47	95.39（high）/ 95.26（medium）	95.30
纯 CPU 运行	支持	不支持	支持
GPU 加速	Volta 架构及以后的 N 卡，或 Apple Silicon	需要更高配置	不需要本地 GPU
最低显存	4 GB	8 GB	2 GB
内存	最低 16 GB，推荐 32 GB+	最低 16 GB	—
磁盘空间	最低 20 GB，推荐 SSD	最低 2 GB	—

简单结论：普通 Windows 用户选 pipeline 即可——它可以在纯 CPU 上运行，有一块 4 GB 以上显存的 NVIDIA 显卡时还能自动加速；追求极致精度且有 8 GB+ 显存时，再考虑 vlm-engine / hybrid-engine。

2.6 常见问题速查

问题	排查方向
pip 安装报依赖错误	确认 Python 版本为 3.10~3.12，不要用 3.13
模型下载慢/失败	3.4+ 会自动选源；仍失败则在 `mineru.template.json` 中手动配置模型源
解析时报显存不足	确认显存 ≥ 4 GB，关闭其他占显存程序，或改用纯 CPU 模式
长文档内存爆掉	3.0+ 已引入滑动窗口机制大幅降低峰值内存，请升级到最新版
扫描件识别为乱码	MinerU 会自动检测并启用 OCR，确认未手动关闭 OCR 参数
GPU 不生效	参考 FAQ 安装与 CUDA 版本匹配的 PyTorch
客户端/在线版文件超限	单文件限约 200 MB / 600 页，超出可先拆分再上传，或改用本地部署（无此限制）

三、总结

MinerU 是目前开源社区中综合表现最突出的文档解析项目之一：精度上，VLM 引擎在 OmniDocBench v1.6 基准达到 95+ 分；格式上，覆盖 PDF/DOCX/PPTX/XLSX/图片/网页；工程上，CLI、API、WebUI、MCP、SDK 一应俱全，且许可证已放宽至 Apache 2.0 系，商业使用友好。

对个人用户，首选桌面客户端（2.1 节）：下载安装后拖拽即用、无需登录，是上手成本最低的方式；临时处理少量文件可用在线版（2.2 节）免安装体验；需要在本地构建 RAG 知识库、批量处理海量文档或有私有化要求的用户，按 2.3 节完成开源版部署后，一条 mineru -p 输入 -o 输出 命令即可开始工作。