MinerU：把 PDF 与 Office 文件转成 LLM 可用的 Markdown／JSON

在 RAG、企业知识库与 Agent 工作流中，文件解析经常是最容易被低估的一层。把 PDF 直接转成纯文字，虽然能快速完成 demo，却很容易遗失标题阶层、表格栏列、数学公式、图片与跨页关系；后面的切 chunk、embedding 和检索，也会一起放大这些错误。

OpenDataLab/MinerU 提供一个开源的文件解析引擎，将 PDF、图片、DOCX、PPTX 与 XLSX 转换成适合机器处理的 Markdown、JSON 等格式。它的定位不是聊天机器人，而是放在「原始文件 → 可检索资料」之间，负责把复杂版面整理成下游模型能消化的结构化输入。

截至本文查证时，专案在 GitHub 拥有超过 7.7 万颗星，且近期仍持续发布版本。这让 MinerU 值得被当成一个可以实际整合进资料管线的工程工具，而不只是展示型的文件 OCR demo。

先理解：为什么纯文字抽取不够

一般 PDF 文字抽取器通常擅长「把字拿出来」，却未必知道文字在页面上的角色。例如：

两栏论文可能被交错读取，段落顺序因此失真。
表格被摊平成连续文字后，栏名与数值的对应关系消失。
公式、上下标与特殊符号在 OCR 后变成不可用的字串。
图片、图说与正文之间的关联被切断。
扫描文件需要 OCR，但 OCR 结果还必须和版面分析结合，才能恢复阅读顺序。

对人类读者而言，这些资讯可以靠视觉补回来；对 embedding 模型和 LLM 而言，输入文字就是它们能看到的世界。文件解析品质会直接影响检索召回、引用正确性与回答可信度。

MinerU 的价值在于，它把文件理解当成一个完整流程处理，而不是只提供单一 OCR 函式。官方 README 列出的能力涵盖版面分析、文字与表格辨识、公式处理、图片描述，以及输出为 Markdown、JSON 和中间结果等用途。实际效果仍取决于文件类型与模型后端，因此官方也建议先用线上 demo 评估自己的样本。

MinerU 的工作方式

可以把 MinerU 放进以下管线：

PDF／DOCX／PPTX／XLSX／图片
              │
              ▼
     版面分析与 OCR／VLM
              │
              ▼
   标题、段落、表格、公式、图片
              │
              ▼
       Markdown／JSON／中间结果
              │
              ▼
        清理、切分、Embedding
              │
              ▼
          RAG 或 Agent 应用

这个分层很重要。MinerU 不会替你决定 chunk size、向量资料库 schema 或 prompt；它先把「文件长什么样」整理好，让下游元件可以基于更稳定的结构工作。对工程团队来说，这比把所有责任塞进一个端到端问答服务更容易测试与替换。

官方目前提供多种使用介面：本机 CLI、FastAPI、Gradio WebUI、Docker 部署，以及用于多服务与多 GPU 路由的 mineru-router。因此你可以先用 CLI 验证单份文件，再逐步演进成 API 服务，而不必一开始就建置完整平台。

最小可行用法

官方 README 提供以 uv 安装完整功能的方式：

uv pip install -U "mineru[all]"

如果想从原始码安装：

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

最基本的 CLI 用法是指定输入与输出路径：

mineru -p ./documents/report.pdf -o ./outputs

也可以明确指定 pipeline backend：

mineru -p ./documents/report.pdf -o ./outputs -b pipeline

这些指令适合先建立一个可重现的基准。建议不要直接拿整个历史文件库开始跑，而是先准备一组代表性样本，包含双栏论文、扫描 PDF、表格密集文件、含公式文件和简报，再比较输出品质与处理时间。

对 RAG 管线最有用的三个设计点

1. 先保留结构，再决定怎么切分

如果先把文件压成一个没有阶层的纯文字，再交给 splitter，后面很难知道一段文字属于哪个章节或表格。较稳健的做法是保留 Markdown heading、表格和图片描述，并在切分时把章节路径当成 metadata：

{
  "text": "本节讨论混合检索……",
  "metadata": {
    "source": "annual-report.pdf",
    "section": "第三章／检索架构",
    "page": 18,
    "content_type": "paragraph"
  }
}

这样做不代表所有文件都能自动得到完美 metadata，而是让解析结果保留足够讯息，方便你在自己的资料清理层补上来源、页码与章节。

2. 表格不要急着转成一般段落

表格常常包含最有价值的比较资料，但也最容易在纯文字化时失去语意。对表格内容，可以考虑同时保存两份表示：一份是适合人类阅读的 Markdown table，另一份是供程式处理的 JSON 结构。问答时再依问题类型决定要用文字检索、栏位过滤，或交给模型做表格推理。

3. 把解析品质纳入可观测性

文件解析不是一次性脚本。建议在管线中记录：输入档案 hash、页数、解析 backend、处理耗时、输出字数、表格数量、OCR 页面数和失败原因。当使用者回报「答案引用错误」时，你才能判断问题出在解析、切分、检索或生成，而不是只能重新跑整条流程。

Pipeline、VLM 与服务化的取舍

MinerU 的 README 将 pipeline 与 VLM 类型的后端放在同一个产品脉络中。可以用一个务实的方式理解它们：

pipeline 适合先建立稳定、可批次处理的本机流程，并针对常见文件格式做效能与输出评估。
VLM 类型的解析更适合需要视觉理解的复杂页面，但要把模型大小、GPU 记忆体、延迟与成本纳入部署设计。
当单机 CLI 已经验证品质，再考虑以 API、Docker 或 router 服务化，让多个上游系统共用解析能力。

专案近期的更新也聚焦于批次处理、模型快取、长文件、非同步任务、多执行绪与多 GPU 路由。这些能力对真正的文件平台比单次 demo 更重要，因为生产环境通常面对的是长时间任务、重试、并行量和资源隔离。

不要忽略授权与资料治理

MinerU README 目前标示专案使用 MinerU Open Source License，该授权以 Apache 2.0 为基础并附加条件。若要用于商业产品、代客处理机密文件，或把模型与服务重新包装，应在导入前阅读仓库中的 LICENSE.md，并让法务确认适用范围。

另外，文件解析常涉及合约、财务报表、医疗或内部规范。即使工具可以在本机执行，也仍应设计暂存档清理、权限隔离、输出脱敏和稽核纪录。把文件送到第三方 API 前，也要先确认资料是否允许离开自己的环境。

适合谁使用？

MinerU 特别适合以下情境：

需要把大量 PDF 或 Office 文件导入 RAG 知识库。
需要保留表格、公式、章节和图片语意，而不满足于纯 OCR。
想先用 CLI 或 WebUI 验证，再逐步部署成 API 服务。
需要在本机或自有 GPU 环境处理文件，降低外部服务依赖。
想把文件解析和切分、Embedding、向量搜寻、LLM 生成分离，建立可替换的资料管线。

它不一定适合所有文件。版面极度特殊、手写内容比例很高、低品质扫描或需要高度领域校正的文件，仍然要用自己的资料集做评估。官方也明确提醒，复杂版面、扫描页面和手写内容可能出现不符合预期的结果。

结语：把文件解析当成 AI 系统的基础设施

RAG 专案最常见的错误之一，是太早讨论向量资料库和 prompt，却没有先确认「进入系统的文件是否仍然保有正确结构」。MinerU 的定位很清楚：它是文件到机器可读资料之间的解析层，让团队可以用 Markdown、JSON、CLI、API 或服务路由，把这个步骤纳入可测试、可观测、可扩展的工程流程。

如果你的文件工作流目前仍是「PDF 转纯文字，再直接切 chunk」，MinerU 值得作为下一个基准工具。先挑一小组真实文件比较输出，再根据表格、公式、图片和长文件的结果决定是否导入；这比只看 demo 或星数，更能判断它是否适合你的 AI Chain。