MinerU如何定制输出格式？模板修改实战指南
MinerU 2.5-1.2B 深度学习 PDF 提取镜像专为解决科研、出版、教育等场景中 PDF 文档结构化提取难题而生。它不只把文字“抠出来”，而是真正理解文档的视觉逻辑——多栏排版自动识别、复杂表格保留行列关系、数学公式转为可编辑 LaTeX、图片与图表精准定位并命名。但很多人用了一段时间后才发现：默认生成的 Markdown 虽然准确，却未必符合自己团队的文档规范、知识库要求或发布平台格式。比如你可能需要在每张图前加一句“图X：说明文字”，或让所有表格自动带编号和标题，又或者把公式块统一包裹在$$...$$中而非$...$。这些都不是模型能力问题，而是输出模板的控制权——而这恰恰是 MinerU 最被低估的实用能力。
本镜像已深度预装 GLM-4V-9B 模型权重及全套依赖环境，真正实现“开箱即用”。您无需繁琐配置，只需通过简单的三步指令即可在本地快速启动视觉多模态推理，极大地降低了模型部署与体验的门槛。更重要的是，它把模板定制的入口设计得足够直接：没有复杂的 API 封装，不依赖二次开发，所有格式控制都落在一个清晰、可读、可改的 Jinja2 模板文件里。本文将带你从零开始，亲手修改模板，让 MinerU 输出的每一份 Markdown 都长成你想要的样子。
1. 理解 MinerU 的输出生成机制
MinerU 并非直接“硬编码”输出 Markdown 字符串，而是采用典型的“数据+模板”分离架构。它的核心流程是：
第一步：解析与结构化
PDF 经过 MinerU2.5 模型解析后，被拆解为一个结构化的 Python 对象（DocLayout），其中包含页面、文本块、图片、表格、公式等元素，并附带位置、类型、置信度等元信息。第二步：数据序列化
这些结构化数据被转换为标准 JSON 格式，保存在中间临时目录（如./output/test.json），你可以随时打开查看原始结构。第三步：模板渲染
MinerU 使用 Jinja2 模板引擎，将上述 JSON 数据“填充”进预设的.jinja模板文件，最终生成.md文件。
这个设计意味着：你改模板，就等于改了最终输出的所有样式、顺序、标签甚至逻辑判断。不需要碰模型代码，也不需要重写解析器。
1.1 默认模板在哪？长什么样？
在本镜像中，MinerU 的默认 Markdown 模板位于：
/root/MinerU2.5/magic_pdf/templates/md.jinja它是一个纯文本文件，内容精炼，约 200 行。我们来快速看一段关键片段：
{%- for block in blocks -%} {%- if block.type == "text" -%} {{ block.text | trim }} {%- elif block.type == "image" -%}  {%- elif block.type == "table" -%} {{ block.markdown_table | safe }} {%- elif block.type == "formula" -%} {{ block.latex | trim | replace("\\", "\\\\") | replace("$", "\\$") | safe }} {%- endif -%} {%- endfor -%}这段代码的意思很直白：遍历每个解析块（block），如果是文字就原样输出；是图片就按格式输出；是表格就直接插入 Markdown 表格字符串；是公式就做简单转义后输出。它就是你看到的默认效果的全部来源。
1.2 为什么不能直接改源码？模板才是正道
有人会问：“我直接改mineru包里的 Python 文件不行吗？”
技术上可行，但强烈不建议。原因有三：
- 不可维护：每次
pip install --upgrade magic-pdf，你的修改会被覆盖； - 不安全：修改底层逻辑容易引入解析错误，导致整个文档提取失败；
- 不灵活：一个项目要一种格式，另一个项目要另一种，硬编码无法切换。
而模板方案完美规避了这些问题：你可以在/root/workspace/my_templates/下创建多个.jinja文件（如blog.jinja、notion.jinja、thesis.jinja），运行时用-t参数指定即可，互不干扰，版本可控。
2. 实战：三类高频定制需求逐个击破
下面我们将以三个真实、高频、小白也能立刻上手的定制需求为例，手把手演示如何修改模板。所有操作均在本镜像内完成，无需额外安装工具。
2.1 需求一：给每张图自动添加带编号的标题（如“图1：XXX”）
默认模板对图片的处理是，但很多学术写作或知识库要求图片必须有编号和固定格式标题，例如：
#### 图1：Transformer 架构示意图 操作步骤：
进入模板目录并复制一份新模板：
cd /root/MinerU2.5/magic_pdf/templates cp md.jinja my_doc.jinja用
nano编辑my_doc.jinja，找到处理image类型的代码段（约第 80 行附近）：{%- elif block.type == "image" -%} 替换为以下增强逻辑（支持自动编号 + 标题分级）：
{%- elif block.type == "image" -%} {%- set img_count = loop.index -%} #### 图{{ img_count }}：{{ block.caption or "无标题图片" }} 保存退出（
Ctrl+O → Enter → Ctrl+X）。运行时指定新模板：
mineru -p test.pdf -o ./output --task doc -t /root/MinerU2.5/magic_pdf/templates/my_doc.jinja
效果：所有图片上方都会自动生成#### 图X：描述标题，且编号严格按出现顺序递增。
2.2 需求二：让所有表格自动带“表X”编号和居中标题
默认表格输出是裸 Markdown 表格，没有编号，也没有标题容器。我们希望它变成这样：
##### 表1：实验参数设置 | 参数 | 值 | |------|----| | 学习率 | 3e-5 | | Batch Size | 16 |操作步骤：
在
my_doc.jinja中，找到处理table的代码段（约第 90 行）：{%- elif block.type == "table" -%} {{ block.markdown_table | safe }}替换为带编号与标题的完整结构：
{%- elif block.type == "table" -%} {%- set table_count = loop.index -%} ##### 表{{ table_count }}：{{ block.caption or "无标题表格" }} {{ block.markdown_table | safe }}注意：
block.caption字段并非所有 PDF 都能提取到。为防空值，我们再加一层兜底逻辑——如果没识别出标题，就用“表X”作为默认：{%- elif block.type == "table" -%} {%- set table_count = loop.index -%} {%- set table_title = block.caption or "表" ~ table_count ~ "：未识别标题" -%} ##### {{ table_title }} {{ block.markdown_table | safe }}重新运行命令，即可看到所有表格都拥有了标准化标题。
效果：表格不再“裸奔”，而是拥有语义清晰、格式统一的标题容器，方便后续导入 Notion、Obsidian 或 Word。
2.3 需求三：公式块统一使用双美元符（$$...$$），并添加“公式X”标题
默认公式输出是行内$...$或块级$$...$$混用，且无编号。学术文档通常要求所有独立公式用$$...$$，并配上编号，如：
##### 公式1：交叉熵损失函数 $$ \mathcal{L} = -\sum_{i=1}^{C} y_i \log(\hat{y}_i) $$操作步骤：
找到处理
formula的代码段（约第 100 行）：{%- elif block.type == "formula" -%} {{ block.latex | trim | replace("\\", "\\\\") | replace("$", "\\$") | safe }}替换为带编号与双美元符的版本：
{%- elif block.type == "formula" -%} {%- set formula_count = loop.index -%} ##### 公式{{ formula_count }}：{{ block.caption or "未命名公式" }} $$ {{ block.latex | trim | safe }} $$关键细节：
block.latex字符串本身已包含$$或$，我们需先清理。更稳妥的做法是强制包裹：
{%- elif block.type == "formula" -%} {%- set formula_count = loop.index -%} ##### 公式{{ formula_count }}：{{ block.caption or "未命名公式" }} $$ {{ block.latex | trim | replace("$", "") | replace("$$", "") | safe }} $$- 保存后再次运行，所有公式都将被标准化为居中显示、带编号的块级公式。
效果：公式输出完全符合 LaTeX 学术排版习惯，可直接粘贴进 Typora、Obsidian 或 Jupyter Notebook 渲染。
3. 进阶技巧：让模板更智能、更健壮
上面的修改已经能满足大部分场景，但如果你希望模板更具适应性，还可以加入这些实用技巧。
3.1 条件判断：根据内容类型动态调整格式
不是所有图片都需要标题。比如页眉、水印、装饰性图标，可以跳过编号。MinerU 的block对象包含score（置信度）和bbox（坐标）字段，我们可以利用它们做过滤：
{%- elif block.type == "image" and block.score > 0.7 and block.bbox[3] - block.bbox[1] > 50 -%} {%- set img_count = loop.index -%} #### 图{{ img_count }}：{{ block.caption or "示意图" }}  {%- endif -%}这段代码表示：只对置信度高于 0.7、且高度大于 50 像素的图片才生成标题，小图标、页脚 logo 将被忽略。
3.2 自定义过滤器：添加日期、作者等元信息
Jinja2 支持自定义 Python 过滤器。你可以在模板顶部注册一个简单函数，比如添加当前日期：
{%- macro now() -%}{{ "now"|strftime("%Y-%m-%d") }}{%- endmacro -%}然后在模板开头插入：
> 本文由 MinerU 于 {{ now() }} 自动提取整理3.3 复用与模块化：抽离公共片段
如果多个模板都需要相同的图片处理逻辑，可以把通用代码存为partials/image.jinja，然后在主模板中引用：
{%- include "partials/image.jinja" -%}这能让模板结构更清晰，也便于团队协作维护。
4. 模板调试与验证最佳实践
改完模板不是终点，验证才是关键。以下是高效调试的四步法：
4.1 第一步：先看中间 JSON，确认数据存在
运行带--debug参数的命令，生成中间结构化数据：
mineru -p test.pdf -o ./output --task doc --debug查看./output/test.json，确认blocks数组中每个image、table、formula是否都有caption、score、bbox等字段。这是模板能正确工作的前提。
4.2 第二步：用jinja2-cli独立测试模板
安装轻量 CLI 工具，脱离 MinerU 环境单独渲染：
pip install jinja2-cli jinja2 my_doc.jinja ./output/test.json > test_output.md这样能快速验证模板语法是否正确，避免反复跑 MinerU 浪费时间。
4.3 第三步：对比差异，用diff定位问题
将新旧输出用diff对比：
diff -u output_old/test.md output_new/test.md一眼看出哪一行被修改、哪一块逻辑生效，极大提升调试效率。
4.4 第四步：建立最小测试集
准备 3~5 个典型 PDF：单栏论文、双栏期刊、含复杂表格的报告、带大量公式的教材、图文混排的说明书。每次改模板后都跑一遍，确保改动不破坏其他场景。
5. 总结：掌握模板，你就掌握了 MinerU 的真正自由度
MinerU 的强大，从来不止于“识别准不准”，更在于“输出听不听话”。本文带你走完了从理解机制、动手修改、到进阶调试的完整闭环：
- 你明白了 MinerU 的输出本质是Jinja2 模板渲染，而非黑盒硬编码；
- 你亲手实现了三类最常用定制：图片编号标题、表格标准化、公式块统一；
- 你掌握了条件判断、数据过滤、模块复用等进阶技巧，让模板更智能；
- 你建立了完整的调试工作流，从此改模板不再靠猜，而是靠验证。
记住，模板不是一次性的配置文件，而是你和 MinerU 之间的“契约”——你定义规则，它负责执行。当别人还在为格式不一致手动调整 Markdown 时，你已经用一个.jinja文件，让整个团队的 PDF 提取结果自动对齐知识库规范。
下一步，你可以尝试：
- 为公司内部 Wiki 定制专属模板（自动加版权页、链接跳转）；
- 为博客系统生成带 Front Matter 的 Hugo/Jekyll 兼容格式；
- 为 Obsidian 笔记库生成带
#pdf标签和[[关联笔记]]的智能链接。
真正的自动化，始于你愿意花 10 分钟读懂那个.jinja文件。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
