MinerU 开源：把 PDF 和 Office 文档一键变成 LLM 能吃的 Markdown，已 83K Star

做 RAG、知识库、Agent 的人几乎都踩过同一个坑：手里的资料是 PDF、Word、PPT、Excel，而大模型只认干净的 Markdown 或 JSON。扫描件里的表格、公式、图表，转出来不是乱码就是丢结构。MinerU 就是为解决这件事而生的开源工具——它把"复杂文档转成 LLM 友好格式"做成了一条干净、可编排、面向 Agent 的流水线，目前在 GitHub 上已经攒到 8.3 万 Star。

一、它到底做什么

MinerU 是一个命令行文档读取工具，核心定位很聚焦：把 PDF、Office 等复杂文档转换为 LLM 友好的 Markdown / JSON，专门服务于 Agentic 工作流。它不是 RAG 框架、不是向量数据库、也不是"和文档聊天"的应用，而是更底层、更纯粹的"文档→结构化文本"转换器。

最新版本已迭代到 4.1.7。它有几个特别贴合 Agent 的设计：解析本地文档后，支持按页（page）或按块（block）续读，并返回稳定的定位符（locator），后续读取和引用都靠这个定位符锚定，避免大模型一次性把整本文档塞进上下文。

二、四级解析层级：质量与速度自己选

MinerU 4.0 起引入了四级解析质量，按需取舍：

  • flash（极速）：最快，适合发现、预览、索引，不作为最终阅读的默认质量；
  • basic（基础）：本地私有阅读；
  • standard（标准）：默认普通阅读；
  • advanced（高级）：针对困难文档的最高质量，最慢。

PDF 和图片支持全部四个层级；Office、OpenDocument、EPUB、OFD、HTML/MHTML、CSV/TSV 等则走本地 flash 原生解析。纯文本（.txt/.md/.rst/.tex）不解析，直接读取。

三、支持的格式有多全

输入几乎覆盖了日常能遇到的所有文档类型：PDF（含扫描件、学术论文）、图片（png/jpg/jpeg/webp/gif/bmp/tiff/jp2）、Word、PowerPoint、Excel、RTF、OpenDocument、EPUB、OFD、HTML/MHTML、CSV/TSV。

输出以 Markdown 为主，也可通过 --json 拿到结构化状态、内容与续读数据；一个文档模型还支持 9 种渲染目标（Markdown、HTML、LaTeX、DOCX、EPUB、PDF、结构化内容、Content List V1/V2 等）。

四、工作原理：布局检测 + OCR + 公式表格识别

MinerU 背后是一套工程化很扎实的管线：

  • 布局检测（Layout Detection）：用神经网络模型识别版面区域，区分正文、标题、表格、图注；
  • OCR：扫描版 PDF 和图片的文字识别，底层依赖 PaddleOCR 等成熟方案；
  • 公式 / 表格识别：对含表格、公式、图形、复杂排版的文档特别有效，借助 TableStructureRec、PaddleOCR 等组件还原结构；
  • 原生文档解析：由 DocVortex 提供支持；
  • 模型引擎：基础包用 ONNX + llama.cpp，可装 mineru[torch] 扩展 PyTorch，或 mineru[full]（含 vLLM / lmdeploy / mlx，需 NVIDIA GPU）。

4.1 起还做了跨平台 GPU 自动加速（Windows/Linux 自动 ONNX 加速，macOS 支持 MPS/Metal），核心推理负载约为 CPU 速度的 2–3 倍。

五、怎么装、怎么用

安装门槛很低，几条命令就能跑起来：

# 推荐：uv 安装
uv tool install --python 3.12 "mineru>=4.0,<5"

# 或者 pip
pip install "mineru>=4.0,<5"

# 作为 Agent 技能安装
npx skills add opendatalab/MinerU --skill mineru --global --yes

Python 要求 >=3.11,<3.15（推荐 3.12）。4.1 还统一了异步 Tasks API（/v1/tasks），支持文件清单、URL 输入、缓存复用、取消等，并提供了可恢复的同步文件解析接口 /v1/file_parse。

六、隐私优先，天然适配 Agent

MinerU 默认本地解析，只有显式加 --remote 才会上传远程；它还会在出现可恢复错误（如 quality_tier_unavailable）时给出恢复路径并等待用户选择，而不是偷偷降级。定位符格式形如 doc:{id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}，让 Agent 可以精准引用"第 7 页第 3 块"的内容，而不是凭记忆复述。

项目采用 MinerU Open Source License（基于 Apache 2.0 并附加条件），明确商业使用条款与署名义务，企业落地前有合规预期。

适合谁用

  • 做 RAG / 知识库的团队：需要把海量 PDF、合同、论文稳定转成干净 Markdown 喂给检索与生成；
  • Agent / 工作流开发者：希望让智能体"读文档、按页续读、精准引用"，而不是一次性灌满上下文；
  • 科研与办公自动化：处理扫描件、公式、表格混排的专业资料；
  • 个人效率玩家：想把本地资料库变成可被 AI 检索和问答的结构化文本。

一句话总结：MinerU 把"文档解析"这件脏活累活做成了一个高 Star、高完成度、且真正为 Agent 时代设计的开源组件。如果你的 AI 项目还在为"文档进不来、结构保不住"发愁，它值得成为你流水线里的第一道关卡。