输出格式设计与应用：Markdown、JSON 与可视化

输出格式设计与应用：Markdown、JSON 与可视化

学习目标

读完本章后，你将能够：

• 理解 MinerU 四种输出格式的设计意图与适用场景
• 根据下游需求选择合适的输出格式
• 利用可视化输出进行质量检查
• 处理中间表示（middle_json）进行自定义转换

前置知识

• 文档内容转 Markdown
• 文档解析在 RAG 管线中的定位

---

1. MinerU 的输出格式全景

MinerU 每次解析都会生成一组输出文件：

2. 四种核心输出格式详解

2.1 多模态 Markdown（mm_markdown）

设计意图：保留所有视觉元素的引用，作为多模态 LLM 的输入。

# 论文标题

作者：张三, 李四

## 1. 引言

近年来，深度学习在自然语言处理领域取得了显著进展$^{[1]}$。

![Figure 1: 模型架构图](images/figure_1.png)

如上图所示，模型由三个主要部分组成...

## 2. 方法

损失函数定义为：

$$
\mathcal{L} = -\sum_{i=1}^{n} y_i \log(\hat{y}_i)
$$

| 方法 | 准确率 | F1 |
|------|--------|-----|
| Baseline | 85.2% | 0.83 |
| Ours | 92.1% | 0.91 |

> 表1：对比实验结果

适用场景：

• 多模态 LLM 的文档理解（需要图片信息）
• 人类阅读与审查
• 需要保留文档原始视觉信息的场景

2.2 NLP Markdown（nlp_markdown）

设计意图：纯文本模式，移除视觉元素引用，适合纯文本 LLM。

# 论文标题

作者：张三, 李四

## 1. 引言

近年来，深度学习在自然语言处理领域取得了显著进展。

[图片: Figure 1 模型架构图]

如上图所示，模型由三个主要部分组成...

## 2. 方法

损失函数定义为：$\mathcal{L} = -\sum_{i=1}^{n} y_i \log(\hat{y}_i)$

[表格: 方法 Baseline 准确率 85.2% F1 0.83 | 方法 Ours 准确率 92.1% F1 0.91]
> 表1：对比实验结果

适用场景：

• 纯文本 LLM 的 RAG 管线
• 向量数据库索引
• 文本相似度计算

2.3 内容列表（content_list / content_list_v2）

设计意图：完全结构化的 JSON 输出，保留每个元素的类型信息。

[
  {
    "type": "title",
    "text": "论文标题",
    "level": 1
  },
  {
    "type": "text",
    "text": "作者：张三, 李四"
  },
  {
    "type": "title",
    "text": "1. 引言",
    "level": 2
  },
  {
    "type": "text",
    "text": "近年来，深度学习..."
  },
  {
    "type": "image",
    "image_path": "images/figure_1.png",
    "caption": "Figure 1: 模型架构图"
  },
  {
    "type": "equation_interline",
    "text": "\\mathcal{L} = -\\sum_{i=1}^{n} y_i \\log(\\hat{y}_i)"
  },
  {
    "type": "simple_table",
    "html": "<table>...</table>"
  }
]

适用场景：

• 需要精细控制每个元素的处理方式
• 构建自定义的文档浏览界面
• 需要对不同类型内容应用不同策略（如图片送多模态模型、文本送向量模型）

2.4 中间表示（middle_json）

设计意图：解析引擎与输出格式之间的中间层，保留最完整的解析信息。

{
  "page_info": [{"w": 612, "h": 792}],
  "blocks": [
    {
      "type": "doc_title",
      "bbox": [100, 50, 500, 80],
      "lines": [{"text": "论文标题", "bbox": [100, 50, 500, 80]}]
    }
  ]
}

适用场景：

• 自定义输出格式转换
• 解析结果调试与验证
• 二次开发的基础数据结构

3. 可视化质检

3.1 布局可视化（_layout.pdf）

在原始 PDF 上叠加布局检测的边界框和类型标签：

• 用途：验证布局检测是否正确识别了页面元素
• 颜色编码：不同类型的块用不同颜色标注
• 适用场景：解析效果不佳时，定位是布局检测还是后续处理的问题

3.2 Span 可视化（_span.pdf）

在原始 PDF 上叠加 OCR 文本 span 的边界框：

• 用途：验证 OCR 文本的位置是否准确
• 适用场景：文本位置偏移、阅读顺序错误时诊断

4. 输出格式选择策略

5. 陷阱与对策

陷阱	对策
NLP Markdown 中表格信息丢失	改用 content_list，保留 HTML 表格结构
图片引用路径在迁移后失效	整体移动输出目录，保持相对路径
内容列表 v2 与 v1 字段不同	确认解析器版本，使用对应的 schema
中间 JSON 结构过于复杂	使用 MinerU 提供的转换工具简化
可视化 PDF 生成失败	检查 PDFium 兼容性，关闭可视化选项

6. 设计权衡

为什么保留多种输出格式

考量	单一格式	多格式
灵活性	低（用户需自行转换）	高（按需选择）
存储	少	多（但可按需生成）
维护	简单	复杂（多个转换模块）

取舍：MinerU 选择多格式方案，因为文档解析的下游场景差异太大，单一格式无法兼顾所有需求。中间表示（middle_json）作为统一基础，降低了多格式的维护成本。

Markdown vs 内容列表

维度	Markdown	内容列表
可读性	人类友好	需要工具
结构化	半结构化	完全结构化
类型信息	隐含在语法中	显式标注
下游处理	文本处理管线	结构化处理管线
转换灵活性	固定格式	可自定义渲染

取舍：MinerU 同时提供两种格式，Markdown 用于直接阅读和文本模型，内容列表用于需要精细控制的场景。

---

参考来源

• MinerU 源码：mineru/backend/*/pipeline_middle_json_mkcontent.py、vlm_middle_json_mkcontent.py
• MinerU 官方文档：https://opendatalab.github.io/MinerU/