MinerU：把复杂文档压成 LLM 可读的结构化文本

MinerU 解决的是一个看似平淡、实则棘手的问题：把 PDF、Office 这类为人类眼睛排版的文档，转成 LLM 真正能消化的 markdown 或 JSON。很多团队在搭 RAG 或 Agentic workflow 时，第一步就卡在解析上。普通 PDF 提取工具拿到的是一堆按坐标散落的字符，表格变成空格对齐的文本，公式变成乱码，双栏论文读成一锅粥。MinerU 的定位就是把这个环节做成一个可编程的 Python 工具，让下游模型拿到的是保留版面语义的结构化输入。

它瞄准的不是“能读 PDF”，而是“读完之后能直接喂给模型”。这个差别决定了它的输出格式、内部流程和取舍。如果只是给人看，保留视觉顺序就够了；但给 LLM 看，必须把视觉结构翻译成语义结构——哪些字符属于同一个标题、哪些数字属于同一列、哪些符号构成一个公式。这种翻译本身是有损的，MinerU 的价值在于把损失控制在模型可容忍的范围。

从版面坐标到语义结构：它必须做的第一步

PDF 文档本质上没有段落、表格、公式这些概念，它只有“某个字形在某个坐标出现”。MinerU 要做的第一件事，是把这些散落的字形重新聚合成有意义的块。这个过程的难点不在于找到文字，而在于判断哪些文字应该连在一起，哪些应该切开。

双栏论文是典型的陷阱。如果只按 y 坐标从上到下、x 坐标从左到右扫描，左右两栏会被交叉拼成一句不通顺的话。MinerU 必须识别栏的边界，先分栏再串行。类似的问题出现在页眉页脚、脚注、边注上——这些元素在视觉上离正文很近，但在语义上应该被剥离或单独标记。

代价是：任何版面分析模型都不可能 100% 正确。一旦栏位判断出错，整页的阅读顺序就乱了，下游模型拿到的是错位的上下文。MinerU 把这个问题暴露给调用者，而不是悄悄吞掉。输出的 markdown 保留了标题层级和段落边界，让下游至少有机会发现结构异常。

表格还原：为什么不能用纯文本切割

表格是文档解析里最容易被低估的难点。一个简单的三列表格，在 PDF 里可能只是一堆用横线竖线画出来的字符，也可能根本没有线，只靠空白对齐。如果解析器只是按行提取文本，表头和内容之间的对应关系就丢了。

MinerU 的目标输出是 markdown 表格或 JSON 结构，这意味着它必须在字符级别重建行列关系。对于有线表格，检测横线和竖线的交叉点可以重建网格；对于无线表格，则要依赖列间距和内容对齐来推断。后者更难，因为数字列可能右对齐，文本列左对齐，中间还可能混入合并单元格。

这个环节的机制设计有一个隐含判断：解析器不能只输出“看起来像表格”的文本，而要输出结构明确的表格。因为下游 LLM 对 markdown 表格的理解远好于对空格对齐文本的理解。代价是解析时间增加，而且复杂表格的重建可能引入错误行合并或列错位。文档没有说明它对嵌套表格或跨页表格的具体处理策略，但这两类通常是表格解析的深水区。

公式：从渲染符号到可计算表示

论文和财报里的公式是另一个硬骨头。PDF 里的公式往往由特殊字体和大量定位信息构成，直接提取出来是一串无法阅读的符号。MinerU 需要识别公式区域，把它和正文分开，再转成某种结构化表示，比如 LaTeX 或 MathML。

这个选择背后有一个关键判断：markdown 本身不擅长表达数学公式，但很多 LLM 的预训练语料里包含大量 LaTeX。把公式转成 LaTeX 嵌入 markdown，可以让模型利用它已有的数学语言理解能力。如果只转成图片或者纯文本，模型对公式的语义理解会大打折扣。

代价是公式识别的准确性。行内公式和独立公式的区分、上下标的归属、多行公式的对齐，都是容易出错的地方。一个被错误转换的公式，对模型来说比没有公式更危险，因为它提供了错误的结构信息。文档没有披露公式识别模块的具体实现，但从输出格式可以推断，它在公式和正文之间做了显式分隔，而不是混在一起。

为什么要输出 markdown 和 JSON 两种格式

MinerU 同时支持 markdown 和 JSON 输出，这不是简单的格式转换，而是服务两类不同的下游。markdown 适合直接拼进 prompt，因为多数 LLM 的指令微调语料里 markdown 占比很高，模型对标题、列表、表格、代码块的语义边界有很好的先验。JSON 则适合需要程序化处理的场景，比如要精确提取某个字段、做结构化存储或者和其他工具链对接。

这种双输出设计意味着内部需要维护一套中间表示。解析结果先变成结构化的文档对象，再分别渲染成 markdown 和 JSON。这个架构的优点是一致性，两种输出来自同一个解析结果，不会出现 markdown 里有表格、JSON 里表格变成纯文本的情况。代价是维护成本增加，而且中间表示的粒度直接决定了两种输出的上限。

另一个隐含的取舍是：markdown 本身表达复杂版面的能力有限。比如跨页表格、多级嵌套列表、带注释的公式，在 markdown 里没有标准表达方式。MinerU 只能选一个折中方案，把复杂结构降级成 markdown 能表达的形式。这个降级过程损失了什么，文档没有详细说明，但这是所有 markdown 输出工具共同面对的问题。

接入 Agentic workflow：解析只是起点

MinerU 的典型用法不是单独跑一个解析任务，而是嵌在 Agentic workflow 或 RAG 流程的前置环节。这个定位对工具提出了额外要求：它必须能被 Python 代码稳定调用，输出格式要确定，解析失败要有可预期的行为。

在 RAG 场景里，MinerU 的输出会被切块、嵌入、检索。如果解析阶段把表格拆散了，检索到的块就缺少上下文，模型无法正确回答“这个季度的营收增长率是多少”这类问题。如果公式被转成乱码，涉及数学推导的查询就全部失效。所以 MinerU 的结构保真度直接影响下游检索质量。

在 Agentic 场景里，解析结果可能被多个 Agent 反复读取和处理。JSON 输出的价值在这里更明显，因为 Agent 可以按字段访问内容，而不是重新解析 markdown 文本。但这也要求 JSON 结构足够稳定，字段命名和嵌套层级不能随意变化，否则 Agent 的解析逻辑会频繁失效。

边界与判断

MinerU 的价值集中在“把版面还原成结构”这一步。它不负责理解文档内容，不负责回答问题，也不负责存储和检索。它是一个前置工具，解决的是文档进入 LLM 之前的格式障碍。这个定位清晰，但也意味着它的上限受版面分析能力约束。遇到扫描件、手写体、极端复杂的排版，解析质量会下降，这是所有规则加模型混合方案的共同短板。

License 标记为 NOASSERTION，说明仓库没有明确声明一个标准开源许可证。对于想集成到商业产品的团队，这是一个必须先行评估的法律风险。Star 数高说明需求真实且广泛，但不能替代许可证审查。

判断：如果你的工作流里大量依赖 PDF 论文、财报或 Office 文档，MinerU 值得作为解析层候选。但不要期待它解决所有文档问题，扫描件和极度复杂版面仍需要额外的 OCR 或人工兜底。建议先用自己业务里最有代表性的几十份文档做小批量测试，重点检查双栏阅读顺序、无线表格和公式转换这三类最容易出错的场景，再决定是否纳入生产链路。