【MinerU】多类型文件解析与模型管理

MinerU 多类型文件解析与模型管理

一、支持的文件格式

MinerU 目前支持以下文件格式：

类型	支持的格式	不支持
PDF	`.pdf`	---
图片	`.png`, `.jpg`, `.jpeg`, `.jp2`, `.webp`, `.gif`, `.bmp`, `.tiff`	---
Word	`.docx`	`.doc`（旧格式）
PowerPoint	`.pptx`	`.ppt`（旧格式）
Excel	`.xlsx`	`.xls`（旧格式）

注意：只支持 Office Open XML 格式（.docx/.pptx/.xlsx），不支持旧版二进制格式（.doc/.ppt/.xls）。

MinerU 会通过文件头字节自动检测文件类型，不仅依赖扩展名。

二、PPTX 解析

2.1 基本使用

PPTX 解析是 MinerU 3.1.0 新增的原生支持功能，无需额外配置：

bash 复制代码

# 直接解析 PPTX 文件
mineru -p input.pptx -o output_dir

# 指定后端
mineru -p input.pptx -o output_dir -b pipeline

# 批量解析（传入目录）
mineru -p /path/to/pptx_files/ -o output_dir

2.2 PPTX 解析原理

MinerU 使用 pypptx-with-oxml 库原生解析 PPTX 文件，不依赖 PDF 转换中转：

复制代码

PPTX 文件 → pypptx 库解析 → 提取幻灯片内容（文本/图片/表格/形状） → 结构化输出

核心处理流程：

读取 PPTX 文件中的每张幻灯片
遍历幻灯片中的形状（Shape），按类型处理：
- 文本框：提取文本内容，保留格式
- 图片：提取图片数据
- 表格：提取表格结构
- 其他形状：尝试提取文本内容
组装为结构化的页面数据，输出与 PDF 解析相同的格式

2.3 其他 Office 文件

bash 复制代码

# DOCX
mineru -p document.docx -o output_dir

# XLSX
mineru -p spreadsheet.xlsx -o output_dir

# 图片
mineru -p image.png -o output_dir

2.4 PPTX 解析的局限

仅支持 .pptx，不支持旧版 .ppt
PPTX 解析走的是 Office 文档处理管线，不涉及 OCR/VLM
复杂动画、嵌入对象（如视频、OLE 对象）可能无法完整提取
如果 PPTX 内包含扫描图片形式的文字，不会进行 OCR（除非先将图片导出为单独文件再解析）

三、模型切换

3.1 后端选择（-b 参数）

后端决定了使用什么技术栈来解析文档：

bash 复制代码

# 传统多模型流水线（CPU 可用，精度 85+）
mineru -p input.pdf -o output_dir -b pipeline

# VLM+OCR 混合引擎（默认，精度 95+，需 GPU）
mineru -p input.pdf -o output_dir -b hybrid-auto-engine

# 纯 VLM 引擎（仅中英文，需 GPU）
mineru -p input.pdf -o output_dir -b vlm-auto-engine

# 远程 OpenAI 兼容服务（VLM）
mineru -p input.pdf -o output_dir -b vlm-http-client -u http://remote-server:8000/v1

# 远程 OpenAI 兼容服务（混合）
mineru -p input.pdf -o output_dir -b hybrid-http-client -u http://remote-server:8000/v1

后端	说明	GPU 要求	精度
`pipeline`	多模型流水线	CPU 或 4GB+ GPU	85+
`hybrid-auto-engine`	VLM+OCR 混合（默认）	8GB+ GPU	95+
`vlm-auto-engine`	纯 VLM	8GB+ GPU	95+
`vlm-http-client`	远程 VLM 服务	无本地 GPU	95+
`hybrid-http-client`	远程混合服务	无本地 GPU	95+

3.2 模型源切换

模型文件可从不同来源下载：

bash 复制代码

# 方式 1：环境变量
# Linux/macOS
export MINERU_MODEL_SOURCE=modelscope    # 国内 ModelScope（推荐国内用户）
export MINERU_MODEL_SOURCE=huggingface   # 国际 HuggingFace
export MINERU_MODEL_SOURCE=local         # 使用本地已下载的模型

# Windows
set MINERU_MODEL_SOURCE=modelscope
set MINERU_MODEL_SOURCE=huggingface
set MINERU_MODEL_SOURCE=local

3.3 模型下载与管理

bash 复制代码

# 交互式选择下载
mineru-models-download

# 下载全部模型
mineru-models-download -m all

# 只下载 pipeline 模型（OCR、版面检测、表格识别等）
mineru-models-download -m pipeline

# 只下载 VLM 模型（视觉语言模型）
mineru-models-download -m vlm

# 指定模型源下载
mineru-models-download -s modelscope -m all      # ModelScope
mineru-models-download -s huggingface -m all     # HuggingFace

3.4 本地模型路径配置

模型下载后会在用户目录生成 mineru.json 配置文件，可通过模板 mineru.template.json 自定义路径：

json 复制代码

{
    "models-dir": {
        "pipeline": "/path/to/pipeline/models",
        "vlm": "/path/to/vlm/models"
    }
}

使用步骤：

下载模型：mineru-models-download -m all
修改 ~/mineru.json 中的模型路径
设置 MINERU_MODEL_SOURCE=local
运行 MinerU

3.5 默认模型

MinerU 3.1.0 默认使用的 VLM 模型为 MinerU2.5-Pro-2604-1.2B。

当前不支持通过 CLI 参数直接切换为其他 VLM 模型，但可以通过以下方式使用自定义模型：

使用 http-client 后端连接已部署自定义模型的远程服务
通过环境变量 MINERU_VL_MODEL_NAME 指定远程模型名称

3.6 远程模型配置

使用 http-client 后端时，需要配置远程服务信息：

bash 复制代码

# 设置远程服务地址
mineru -p input.pdf -o output_dir -b vlm-http-client -u http://192.168.1.100:8000/v1

# 或通过环境变量
export MINERU_VL_MODEL_NAME="your-model-name"
export MINERU_VL_API_KEY="your-api-key"
mineru -p input.pdf -o output_dir -b vlm-http-client

四、CLI 完整参数参考

bash 复制代码

mineru -p <输入路径> -o <输出目录> [选项]

参数	说明	默认值
`-p, --path`	输入文件路径或目录	（必填）
`-o, --output`	输出目录	（必填）
`-b, --backend`	解析后端	`hybrid-auto-engine`
`-m, --method`	解析方法：auto/txt/ocr	`auto`
`-l, --lang`	文档语言（ch/en/korean/japan 等）	自动检测
`-s, --start`	起始页码（从 0 开始）	0
`-e, --end`	结束页码	最后一页
`-f, --formula`	启用公式解析	true
`-t, --table`	启用表格解析	true
`-u, --url`	远程 OpenAI 兼容服务地址	---
`--api-url`	MinerU FastAPI 服务地址	---

常用环境变量

bash 复制代码

# 模型与功能
MINERU_MODEL_SOURCE              # 模型源：huggingface / modelscope / local
MINERU_FORMULA_ENABLE            # 启用公式识别（默认 true）
MINERU_TABLE_ENABLE              # 启用表格识别（默认 true）

# 性能调优
MINERU_PDF_RENDER_THREADS        # 渲染并发线程数（默认 4）
MINERU_PROCESSING_WINDOW_SIZE    # 处理窗口大小（默认 64）
MINERU_API_MAX_CONCURRENT_REQUESTS  # 最大并发请求数（默认 3）

# Hybrid 后端
MINERU_HYBRID_BATCH_RATIO        # 小模型批处理比例（显存不足时可调小）

# 远程服务
MINERU_VL_MODEL_NAME             # 远程模型名称
MINERU_VL_API_KEY                # 远程 API 密钥

# NPU 相关
MINERU_LMDEPLOY_DEVICE           # 设备类型：cuda / ascend
VLLM_WORKER_MULTIPROC_METHOD     # 多进程方式（Ascend 需设为 spawn）

五、常用示例

bash 复制代码

# 示例 1：使用默认后端解析 PPTX
mineru -p presentation.pptx -o ./output

# 示例 2：使用 pipeline 后端解析（无需 GPU）
mineru -p presentation.pptx -o ./output -b pipeline

# 示例 3：解析 DOCX 文件
mineru -p document.docx -o ./output

# 示例 4：解析图片
mineru -p photo.png -o ./output

# 示例 5：使用 ModelScope 下载模型后本地运行
export MINERU_MODEL_SOURCE=local
mineru -p input.pdf -o ./output

# 示例 6：使用远程 VLM 服务
mineru -p input.pdf -o ./output -b vlm-http-client -u http://192.168.1.100:8000/v1

# 示例 7：只解析 PDF 的第 3-10 页
mineru -p input.pdf -o ./output -s 2 -e 9

# 示例 8：指定文档语言为中文，提高 OCR 精度
mineru -p scanned.pdf -o ./output -l ch

六、复杂文件解析原理详解

6.1 整体处理流程

不同文件类型走完全不同的处理路径：

复制代码

输入文件
    ↓
文件类型自动检测（Magika 字节头检测）
    ↓
    ├─ PDF  → pipeline / hybrid / vlm 后端处理
    ├─ 图片 → EXIF 旋转 → 转 PDF → 同 PDF 路径
    ├─ PPTX → PptxConverter 原生解析
    ├─ DOCX → DocxConverter 原生解析
    └─ XLSX → XlsxConverter 原生解析
    ↓
统一输出 Middle JSON → Markdown / JSON / HTML

关键区别：

PDF 和图片走模型推理（OCR/VLM），适合扫描件和复杂版面
Office 文件走原生解析（pypptx/python-docx/openpyxl），直接提取内嵌内容，不经过 OCR/VLM

6.2 文件类型自动检测

MinerU 使用 Magika 库进行基于字节头的文件类型检测，不仅依赖文件扩展名：

python 复制代码

# mineru/utils/guess_suffix_or_lang.py
def guess_suffix_by_bytes(file_bytes, file_path=None):
    # Magika AI 检测文件内容类型
    # 特殊处理：PDF 签名 %PDF 覆盖 AI 误判
    # 返回小写扩展名："pdf", "png", "docx", "pptx", "xlsx" 等

支持的文件分类：

类别	扩展名	处理方式
PDF	`.pdf`	模型推理
图片	`.png`, `.jpg`, `.jpeg`, `.jp2`, `.webp`, `.gif`, `.bmp`, `.tiff`	转 PDF → 模型推理
Word	`.docx`	原生解析
PowerPoint	`.pptx`	原生解析
Excel	`.xlsx`	原生解析

6.3 图片处理流程

图片会先转换为 PDF，然后走标准的 PDF 处理路径：

复制代码

图片文件（bytes）
    ↓
PIL 加载图片
    ↓
EXIF 自动旋转（ImageOps.exif_transpose）
    │ 处理手机拍摄照片的 Orientation 元数据
    ↓
转换为 RGB 模式
    ↓
保存为 PDF（DPI=200, Quality=95）
    ↓
走 PDF 处理路径（pipeline / hybrid / vlm）
    ↓
OCR 识别文字 + 版面检测 + 公式/表格识别

这意味着：图片中的文字会通过 OCR 或 VLM 进行识别，与扫描 PDF 的处理方式一致。

6.4 PPTX 解析原理

整体流程

复制代码

PPTX 文件
    ↓
python-pptx 库加载 Presentation 对象
    ↓
遍历每张幻灯片（Slide）
    ↓
对每张幻灯片：
    1. 展开所有形状（包括嵌套分组形状）
    2. 计算变换矩阵（缩放、平移、旋转）
    3. XYCut 算法排序阅读顺序
    4. 按类型提取内容：
       ├─ 文本 → 富文本（粗体/斜体/字号/超链接）
       ├─ 公式 → OMML → LaTeX
       ├─ 表格 → HTML 表格（支持合并单元格）
       ├─ 图表 → XML 解析 → HTML
       ├─ 图片 → 提取嵌入图片（过滤小图/背景图）
       ├─ 列表 → 多级列表检测
       └─ 备注 → notes_slide 提取
    ↓
输出结构化 Block 列表

形状展开与变换

PPTX 中的形状可能嵌套在分组（GroupShape）中，需要递归展开：

python 复制代码

# 递归展开分组形状
def flatten_shapes(shapes):
    for shape in shapes:
        if shape.shape_type == GROUP:
            # 计算组合变换矩阵：父级变换 × 子级变换
            # 处理缩放、平移、旋转
            yield from flatten_shapes(shape.shapes, parent_transform)
        else:
            yield shape_with_transform

展开后使用 XYCut 算法 按空间位置排序，确保阅读顺序正确（类似报纸分栏的阅读顺序）。

文本提取（富文本）

文本提取保留完整的格式信息：

格式属性	处理方式
粗体	追踪 `<b>` 标签
斜体	追踪 `<i>` 标签
下划线	追踪 `<u>` 标签
删除线	追踪 `<s>` 标签
字号	多级回退：run 属性 → 段落默认 → 文本框样式 → 版式占位符 → 母版样式
超链接	解析 relationship 获取 URL
数学公式	OMML → `<eq>LaTeX</eq>`

字号的多级回退机制：

复制代码

Run 属性中的字号
    ↓ 没有
段落默认字号
    ↓ 没有
文本框样式中的字号
    ↓ 没有
版式占位符（Layout Placeholder）中的字号
    ↓ 没有
幻灯片母版（Slide Master）中的字号
    ↓ 都没有
使用默认值

标题自动提升

如果文本的字号足够大且为粗体，会自动被提升为 TITLE 类型，级别根据字号大小决定。这确保了没有显式设置标题样式的 PPTX 也能正确识别文档结构。

表格提取

复制代码

PPTX 表格
    ↓
遍历行和列
    ↓
处理合并单元格（rowSpan / colSpan）
    ↓
提取每个单元格的富文本内容
    ↓
转义 HTML 特殊字符（<, >, &）
    ↓
输出 HTML 表格（首行 <th>，其余 <td>）

图表提取

复制代码

PPTX 图表
    ↓
提取 chart_part.blob（OOXML 格式）
    ↓
解析图表 XML 获取系列数据
    ↓
提取嵌入的工作簿数据
    ↓
extract_chart_html_from_ooxml() 转换为 HTML
    ↓
输出 CHART 类型 Block

图片提取与过滤

图片提取有多层策略：

复制代码

1. 优先从 shape.image 获取
2. 从 blip 元素获取（DrawingML 关系）
3. 从关系文件获取嵌入图片

图片格式处理：
- RGB 图像 → JPEG
- RGBA/LA/P（带透明度）→ PNG
- 矢量图 → 特殊占位符格式
- SVG → serialize_vector_image_with_placeholder()

智能过滤：

过滤规则	说明
小图片过滤	尺寸 < 10% 或面积 < 1% 的图片被跳过
背景图片过滤	如果文字覆盖率 > 10%，判定为背景图，跳过

列表检测

支持三种列表标记：

类型	标记	示例
`buChar`	自定义字符	•、-、*
`buAutoNum`	自动编号	1.、2.、3.
`buBlip`	图片标记	自定义图标

支持多级嵌套列表，通过 ilevel 字段表示层级。

备注提取

从 notes_slide 提取演讲者备注，但会过滤掉占位符（幻灯片编号、日期、页脚）。

6.5 DOCX 解析原理

整体流程

复制代码

DOCX 文件
    ↓
python-docx 加载 + mammoth 预解析
    ↓
mammoth 全文档转换（提供完整上下文：编号、图片、样式）
    ↓
遍历文档元素：
    ├─ 段落 → 富文本（格式/超链接/隐藏文字/公式）
    ├─ 表格 → HTML（含无网格表格修复）
    ├─ 图片 → 嵌入图片提取
    ├─ 目录（SDT/TOC）→ INDEX 结构块
    ├─ 文本框 → w:txbxContent / VML / DrawingML
    └─ 分节符 → 页面分割
    ↓
mammoth 遗失的公式重新注入
    ↓
输出结构化 Block 列表

mammoth 预解析的作用

DOCX 解析使用 mammoth 库做全文档预解析，而非逐元素独立解析。原因是：

mammoth 能提供完整的文档上下文（编号定义、图片关系、样式继承）
表格解析需要知道全局编号定义才能正确还原列表编号
但 mammoth 不支持 OMML 公式，需要单独提取并重新注入

富文本提取

格式	追踪方式
粗体/斜体/下划线/删除线	Run 属性解析
上标/下标	script 属性
超链接	relationship 引用解析
隐藏文字	webHidden / vanish 属性检测
字号/字体	Run → 段落默认 → 编号级别 → 主样式回退链

数学公式处理

复制代码

DOCX 中的 OMML 公式
    ↓
mammoth 不支持，会丢失
    ↓
单独从 XML 中提取 <m:oMath> 元素
    ↓
OMML → LaTeX 转换
    ↓
包裹为 <eq>LaTeX</eq>
    ↓
注入到对应位置

公式可以出现在段落中和表格单元格中。

表格处理

DOCX 表格解析有特殊的无网格表格修复逻辑：

复制代码

某些表格没有显式网格线
    ↓
colspan（gridSpan）值可能不一致
    ↓
检测到不一致时进行规范化修复
    ↓
输出标准 HTML 表格

目录（TOC）处理

复制代码

检测到 SDT（结构化文档标签）
    ↓
判断类型：
    ├─ TOC（目录）→ 收集超链接锚点（_Toc 前缀）→ 生成 INDEX 块
    └─ 其他 SDT → 当作普通文本处理

文本框处理

支持多种文本框格式：

类型	标识	处理方式
现代文本框	`w:txbxContent`	直接提取内容
VML 文本框	VML 格式	解析 VML 结构
DrawingML 形状	`a:t` 元素	提取文本

6.6 XLSX 解析原理

整体流程

复制代码

XLSX 文件
    ↓
openpyxl 加载工作簿
    ↓
遍历每个工作表（Sheet）
    ↓
对每个工作表：
    1. 扫描所有单元格，确定数据边界
    2. 洪泛填充（Flood-Fill）检测连续表格区域
    3. 处理合并单元格
    4. 提取单元格内容（富文本/超链接/公式）
    5. 提取图表 → 转为合成表格
    6. 提取图片 → 映射到单元格位置
    7. 提取公式 → OMML → LaTeX
    ↓
输出 HTML 表格

洪泛填充表格检测算法

这是 XLSX 解析最核心的算法------自动从稀疏的工作表中识别出独立的表格区域：

复制代码

Step 1: 确定数据边界
    扫描所有单元格，找到 min_row, max_row, min_col, max_col

Step 2: 洪泛填充（BFS）
    从每个非空单元格开始 BFS 扩展
    相邻的非空单元格归入同一区域
    允许一定的间隙（空行/空列）

Step 3: 间隙容忍（Gap Tolerance）
    tolerance=0：不允许任何空隙（最严格）
    tolerance=1：允许 1 行/列空隙
    tolerance=2：允许 2 行/列空隙
    自动选择最优容忍度（基于惩罚评分）

Step 4: 去重与过滤
    移除被包含的子表格
    移除重叠的冗余区域

Step 5: 输出矩形区域
    每个区域生成一个 HTML 表格

示例：

复制代码

工作表内容：
    A1: 姓名  B1: 年龄  C1: 城市
    A2: 张三  B2: 25    C2: 北京
    A3: 李四  B3: 30    C3: 上海

    （空 2 行）

    A6: 产品  B6: 价格
    A7: 苹果  B7: 5.0
    A8: 香蕉  B8: 3.5

检测结果：
    表格 1: A1:C3（人员信息）
    表格 2: A6:B8（产品价格）

合并单元格处理

复制代码

检测合并单元格定义
    ↓
记录 rowSpan 和 colSpan
    ↓
被合并的隐藏单元格跳过（不重复输出）
    ↓
HTML 表格中使用 rowspan/colspan 属性

图表处理

复制代码

图表（Chart）
    ↓
解析系列公式（numRef, strRef, multiLvlStrRef）
获取数据源单元格范围
    ↓
从对应单元格范围提取数据
    ↓
构建合成表格（Synthetic Table）
    ↓
根据图表锚点坐标定位在工作表中的位置

图片处理

复制代码

图片来源：
    1. 工作表图片（sheet._images）
    2. 单元格图片（DISPIMG 公式 + cellimages.xml 关系）

图片处理：
    - RGB → JPEG
    - 其他模式 → PNG
    - 矢量图支持

定位：
    根据锚点坐标（anchor）确定图片在表格中的行列位置
    嵌入为 <img> 标签

单元格样式

提取并应用以下样式到 HTML：

样式属性	HTML 对应
粗体	`<b>`
斜体	`<i>`
下划线	`<u>`
删除线	`<s>`
字体颜色	`color: rgb(...)`
上标/下标	`<sup>` / `<sub>`
水平对齐	`text-align: left/center/right`
垂直对齐	`vertical-align: top/middle/bottom`
背景色	`background-color: rgb(...)`

6.7 输出格式

Block 类型定义

所有文件类型的解析结果统一为 Block 列表：

Block 类型	说明	适用文件
`text`	普通文本（含富文本 HTML）	全部
`title`	标题（含级别 level）	全部
`table`	HTML 表格	全部
`chart`	图表（HTML）	PPTX, XLSX
`image`	图片	全部
`list`	列表（有序/无序，含层级）	PPTX, DOCX
`index`	目录结构	DOCX
`page_footnote`	页面备注	PPTX
`interline_equation`	行间公式	PDF

Middle JSON 结构

json 复制代码

{
    "pdf_info": [
        {
            "page_idx": 0,
            "para_blocks": [
                {
                    "type": "title",
                    "level": 1,
                    "lines": [{"spans": [{"content": "第一章", ...}]}]
                },
                {
                    "type": "text",
                    "lines": [{"spans": [{"content": "正文内容...", ...}]}]
                },
                {
                    "type": "table",
                    "lines": [{"spans": [{"content": "<table>...</table>", ...}]}]
                }
            ],
            "discarded_blocks": []
        }
    ],
    "_backend": "office",
    "_version_name": "3.1.0"
}

最终输出文件

文件	说明
`*.md`	Markdown 格式（默认）
`content_list.json`	内容列表 JSON
`middle.json`	中间结果 JSON（含完整结构）
`model_output.json`	模型输出 JSON
`*.pdf`	可视化 BBox PDF（调试用）

6.8 已知限制

PPTX 限制

限制项	说明
旧版 .ppt 不支持	仅支持 Office Open XML 格式（.pptx）
视频/音频	嵌入的媒体文件不会提取
动画效果	动画和过渡效果不保留
SmartArt	部分复杂 SmartArt 可能触发 NotImplementedError
极端分组变换	深层嵌套 + 复杂旋转可能导致定位偏移
密码保护	加密的 PPTX 文件不支持

DOCX 限制

限制项	说明
旧版 .doc 不支持	仅支持 .docx
mammoth 公式丢失	OMML 公式需单独提取注入，极少数情况可能位置偏移
复杂嵌套域	某些域代码不完全支持
修订/批注	追踪的修改和评论不保留
VBA 宏	宏代码不提取
密码保护	加密文件不支持

XLSX 限制

限制项	说明
旧版 .xls 不支持	仅支持 .xlsx
动态命名范围	图表引用动态命名范围时无法提取数据源
数组公式	数组公式不提取
数据透视表	以平面表格呈现，不保留透视结构
极稀疏表格	过于稀疏的工作表可能导致表格碎片化
密码保护	加密文件不支持

图片限制

限制项	说明
文字识别依赖模型	需要走 OCR/VLM，不能原生提取
复杂版面	与 PDF 相同的版面检测限制
无文字的纯图片	不会生成文本内容（除非 VLM 描述）

通用限制

限制项	说明
Office 文件不走模型	PPTX/DOCX/XLSX 不使用 OCR/VLM，无法识别图片中的文字
损坏文件	格式损坏的文件可能在修复重试后仍失败
嵌套对象	嵌套的 OLE 对象不完全支持
宏/VBA	所有 Office 文件的宏代码不提取