32.MinerU-pdf转md文件

内容参考于：图灵AI大模型全栈

文档中存在表格、图片这种数据处理起来比较麻烦，也就是说非结构化数据处理起来麻烦，当前没有好的处理标准，都需要自己根据实际场景手写，处理起来麻烦的愿意是要保证文档里内容的相关性，比如说现在有一个pdf，然后有3页，在第一个的最后有一个表格，然后由于表格太长扩展到了第二页中，这就导致第二页的开头是第一页中的内容（表格），我们现在读取PDF的库会把PDF每一页都分开（一页一个对象），但实际上第一页的末尾和第二页的开头是一起的才对

现在没有比较好的处理方式，比较好用的是，先使用工具把PDF转成MD文档，md文档比PDF文档处理起来方便，转成md文档之后进行切分，通过md里的标签进行分割，md文档中可以写很多标签（都可以写什么标签去网上搜）

如下图红框它的表格就分页了，我们正常人可以看出这俩个表格是一起的都属于利润表，做向量时就要放到一起才对 ，使用PDF就不好做

如下图转成md文档后就不会分页了

然后如下图红框和蓝框通过md文档中的标签，也就是井号（#）来当一段文档的切分，从红框开始是利润信息的开头，蓝框结束，这样就可以很好的把表格放到一个切分里做向量了

通过上方的思路就把文档切分好了，切分好之后把标签中的文本拿出来，标签做成向量也没有用，所以要把文本拿出来，然后表格的内容也很多也不要做向量，在处理文本的时候检测到表格后，把表格的内容拿出来，然后在原本的文档分片里删掉，然后写一个占位符，当通过问题检索到当前文档分片后再把拿出来的表格通过占位符替换回去，这样不会影响语意，还把文本和表格分开了

PDF转md文档的工具MinerU

它是一个开源的

项目开源地址：https://github.com/opendatalab/MinerU

在线体验（限速/限量）：https://mineru.net/

桌面版地址：https://mineru.net/

它有三种pdf转md文档的方式

第一种在线网页版：https://mineru.net/，点击下图红框

然后点击下图红框里的上传文件或直接把PDF文件鼠标左键按住不放拖到下图红框位置

然后点击下图红框就可以下载pdf转换后的md文档了，注意它里面的图片可能是一个http地址，这个需要处理一下（访问链接把图片下载下来）

第二种桌面版，下载地址MinerU

下载后打开如下图，跟网页版用法一样

通过点击下图红框位置，可以打开文件保存的目录，它的图片会在你电脑中，通过下图点击下图红框可以看到

点击之后如下图，images文件夹中是所有的图片

第三种命令行写代码

首先下载库文件

pip install -U "mineru[all]"
pip install hf_xet

还需下载一个模型，这个模型是用来PDF提取的模型MinerU使用

from modelscope import snapshot_download

snapshot_download('OpenDataLab/PDF-Extract-Kit-1.0', local_dir=r'D:\\huanjing\\ai模型\\LLM\\Local_model\\PDF-Extract-Kit-1.0')

也就是下载下图红框的模型

下载完需要一个环境变量指向上方下载PDF提取模型

MINERU_MODEL_DIR = D:\\huanjing\\ai模型\\LLM\\Local_model\\PDF-Extract-Kit-1.0

代码，第一次运行，如下图红框，它会下载很多东西（PDF-Extract-Kit模型使用的权重），运行时最好连接VPN

这些权重下载的目录，在C盘用户目录中的cache中，如下图

代码

# ========== 导入所需工具包 ==========
# os：Python内置的系统操作库，用来创建文件夹、拼接路径、读取环境变量等和系统相关的操作
import os
# 从MinerU工具中导入核心解析函数 do_parse，这是实现PDF内容提取、格式解析的核心功能函数
from mineru.cli.common import do_parse
# 从MinerU中导入文件型数据写入器，专门负责把PDF里提取出的图片保存到本地文件夹
from mineru.data.data_reader_writer import FileBasedDataWriter
# load_dotenv：用来加载.env配置文件的工具，可以把模型路径、密钥这类配置放在.env里，不用写死在代码中，更安全灵活
from dotenv import load_dotenv

# 定义主函数，所有核心业务逻辑都封装在这个函数里
# 好处：代码结构清晰，只有主动调用main()时才会执行里面的逻辑，避免导入文件时误执行
def main():
# 加载.env配置文件里的环境变量
# 作用：MinerU的模型路径、运行参数等配置可以写在.env文件中，执行这行后就能通过os.getenv读取到配置
load_dotenv()

# ===== 1️⃣ 输入PDF文件配置 =====
# 变量作用：保存待解析的PDF文件的路径
# 修改说明：把引号里的内容改成你自己的PDF文件路径即可，支持相对路径（和代码同目录）和绝对路径
pdf_path = "xxxx.pdf"

# 以二进制只读模式打开PDF文件，读取文件的原始二进制内容
# 语法&逻辑说明：
# – with open(…) as f：Python的上下文管理器语法，打开文件后自动管理生命周期，用完自动关闭文件，不用手动写f.close()，避免文件资源泄露
# – "rb"：read binary 的缩写，也就是二进制只读模式
# 为什么必须用二进制读取：PDF不是纯文本文件，里面包含图片、排版格式等二进制数据，用普通文本模式读取会损坏文件内容，导致解析失败
with open(pdf_path, "rb") as f:
# 读取整个PDF文件的二进制内容，保存到pdf_bytes变量中，后续传给解析函数使用
pdf_bytes = f.read()

# ===== 2️⃣ 输出目录配置 =====
# 变量作用：保存解析结果的输出文件夹名称/路径，所有解析后的文本、图片等结果都会存在这个文件夹里
output_dir = "output"
# 创建输出文件夹
# 参数 exist_ok=True：如果目标文件夹已经存在，不会报错，直接跳过创建步骤
# 为什么要加这个参数：重复运行代码时，如果文件夹已经存在，不加这个参数会直接报错中断程序，加了之后可以重复运行不出错
os.makedirs(output_dir, exist_ok=True)

# ===== 3️⃣ 组装MinerU要求的入参格式 =====
# 注意：MinerU的do_parse函数原生支持批量解析多个PDF文件，因此所有和文件相关的参数都要求是「列表格式」
# 哪怕只解析1个PDF，也要把参数包成列表，保证格式和函数要求一致，多个文件时列表里的元素按顺序一一对应

# pdf_file_names：存放每个PDF文件文件名的列表
# os.path.basename(pdf_path)：从完整的文件路径里提取出纯文件名（比如路径是"files/test.pdf"，提取后就是"test.pdf"）
# 作用：MinerU保存解析结果文件时，会用这个文件名来命名输出的Markdown、JSON等文件
pdf_file_names = [os.path.basename(pdf_path)]
# pdf_bytes_list：存放每个PDF二进制内容的列表，和上面的文件名列表按顺序一一对应
pdf_bytes_list = [pdf_bytes]
# p_lang_list：每个PDF对应的语言设置列表
# 可选入参说明：
# – 传空字符串""：表示自动识别文档语言，适合不确定文档语言的通用场景
# – 传"zh"：指定文档为中文，可优化中文文档的解析效果
# – 传"en"：指定文档为英文，可优化英文文档的解析效果
# 列表里的每个值，对应前面一个PDF文件的语言设置
p_lang_list = [""] # 自动语言识别

# ===== 4️⃣ 初始化图片写入工具 =====
# img_writer：图片写入器对象，专门负责把PDF里提取出来的图片保存到本地指定文件夹
# os.path.join(output_dir, "images")：拼接路径，最终生成的路径是 output/images
# 为什么用os.path.join拼接路径：Windows系统路径用\\分隔，Mac/Linux用/分隔，这个函数会自动适配当前操作系统，不会出现路径格式错误
img_writer = FileBasedDataWriter(
os.path.join(output_dir, "images")
)

# ===== 5️⃣ 执行PDF核心解析 =====
# 调用MinerU的核心解析函数do_parse，传入所有配置参数，自动完成PDF的版面分析、内容提取、图片提取、结果保存全流程
# 入参详细说明：
# pdf_file_names：PDF文件名列表，和pdf_bytes_list按顺序一一对应
# pdf_bytes_list：PDF二进制内容列表，是真正要解析的原始文件数据
# p_lang_list：语言设置列表，控制解析时使用的语言模型
# output_dir：主输出目录，解析后的Markdown、JSON等文本结果会保存在这个目录里
# img_writer：图片写入器对象，用来管理提取出的图片的保存路径和逻辑
# parse_method：解析模式，"auto"表示自动选择最优解析方案，MinerU会自动判断文档类型选择最合适的解析策略
# 是最通用的模式，绝大多数场景都用auto即可
do_parse(
pdf_file_names=pdf_file_names,
pdf_bytes_list=pdf_bytes_list,
p_lang_list=p_lang_list,
output_dir=output_dir,
img_writer=img_writer,
parse_method="auto"
)

# Python程序的标准入口判断
# 语法说明：当这个.py文件被直接运行的时候，才会执行下面的main()函数
# 如果这个文件被其他Python文件通过import导入，这行下面的代码不会自动执行，避免导入时误跑程序逻辑
if __name__ == '__main__':
main()

代码运行完，如下图红框，就可以看到PDF转换后的文件了

文件说明（AI生成）

一、核心结果（日常使用重点关注）

• images/ 文件夹

  存放从 PDF 中提取的所有图片、表格截图、公式图片等资源，按页面和顺序编号。上方的 .md 文件里的图片引用，都会指向这个目录下的文件。

• xxxx.pdf.md

  最主要的最终输出文件，Markdown 格式。包含按人类阅读顺序整理的标题层级、正文文本、表格（HTML 格式）、公式（LaTeX 格式），并自动嵌入图片引用，可直接用于阅读、知识库构建、大模型 RAG 素材。

二、结构化数据文件（用于二次开发）

• xxxx.pdf_content_list.json

  按阅读顺序平铺的内容列表，每个块都标注了元素类型（标题 / 正文 / 表格 / 图片 / 公式等）、所属页码、层级关系、位置坐标，适合快速提取文本、做简单的结构化处理。

• xxxx.pdf_content_list_v2.json

  content_list 的增强版本，补充了更丰富的元素类型标签、元数据和结构化信息，字段更完善，是官方更推荐用于二次开发的格式。

• xxxx.pdf_middle.json

  中间处理结果 JSON。是版面分析完成、但还没生成最终 Markdown 时的完整中间数据，包含检测框坐标、OCR 逐行结果、文本跨度信息、版面元数据，适合自定义后处理逻辑、深度调试。

• xxxx.pdf_model.json

  AI 模型的原始推理输出，只包含所有检测框的坐标、类别 ID、置信度分数，是最底层的模型结果，主要用于调试模型识别效果。

三、可视化调试文件（用于质检、排错）

• xxxx.pdf_layout.pdf

  版面分析可视化文件。在原 PDF 页面上用不同颜色的矩形框，标记出所有识别到的内容区块（标题、正文、表格、图片、公式等），并标注类别和序号，用来快速检查版面划分是否准确。

• xxxx.pdf_span.pdf

  细粒度元素可视化文件。比 layout.pdf 颗粒度更细，会标注出所有识别到的文本行、公式片段等最小单元，用来检查 OCR 漏识别、公式识别错误等细节问题。

四、原始存档文件

• xxxx.pdf_origin.pdf

  你输入的原始 PDF 文件的副本，作为解析结果的配套原始存档，方便溯源。