🔒 You must be logged in as an Administrator or Editor to listen to this audio.

Python 逐行精讲：MinerU（magic-pdf）解析 PDF 代码

逐行精讲：MinerU(magic-pdf) 解析PDF的Python代码

我会逐行、逐段拆解这段代码，同时讲清楚 MinerU 核心用法、原理、依赖和注意事项，让你完全看懂并能独立使用。

前置知识

MinerU = magic-pdf：阿里开源的PDF深度解析工具，支持公式、表格、图片、OCR，比普通PDF解析强很多
代码功能：输入PDF路径 → 输出完整Markdown文本 + 提取的附件(图片等)
依赖安装：必须先安装库
```
pip install magic-pdf[full] pymupdf
```
必须下载模型权重：MinerU 推理需要离线模型（代码中会提示）

逐行完整解析


def _read_pdf_mineru(self, filepath: str, doc_id: str) -> (str, List[Dict]):

定义一个类内部方法（_开头表示私有）
入参：filepath=PDF文件路径，doc_id=文档ID（标记用途）
返回值：Markdown字符串 + 附件列表（字典格式）
类型注解：Python语法规范，提升可读性


    """使用 MinerU (magic-pdf) 进行深度解析 (适配 v1.3.1)"""

文档字符串：说明方法功能、适配版本


    import os
    from magic_pdf.data.dataset import PymuDocDataset
    from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze
    from magic_pdf.data.data_reader_writer import FileBasedDataWriter
    import magic_pdf.model as model_config

延迟导入：放在方法内，只有调用时才加载，节省内存
核心导入说明：
- os：文件/路径/环境变量操作
- PymuDocDataset：MinerU 加载PDF数据的核心类
- doc_analyze：PDF分析推理函数（识别文字、表格、公式、图片）
- FileBasedDataWriter：把解析出的图片/附件写入本地文件夹
- model_config：MinerU 模型配置


    # 1. 环境配置：优先寻找项目根目录下的 magic-pdf.json
    # 假设 readers.py 在 enterprise_cleaner 目录下，根目录是上一级
    base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

__file__：当前代码文件的路径
两层os.path.dirname：获取项目根目录

示例结构：


项目根目录/
├─ magic-pdf.json  # 配置文件
└─ enterprise_cleaner/
   └─ readers.py   # 当前代码文件


    config_path = os.path.join(base_dir, 'magic-pdf.json')

拼接根目录 + 配置文件名，得到完整配置路径


    if os.path.exists(config_path):
        os.environ['MINERU_TOOLS_CONFIG_JSON'] = config_path

如果配置文件存在，设置环境变量
MinerU 会自动读取这个环境变量加载配置（模型路径、OCR参数等）


    # 2. 启用内部模型模式
    model_config.__use_inside_model__ = True
    model_config.__model_mode__ = 'full'

最关键配置：
- __use_inside_model__ = True：使用内置离线模型（必须下载权重）
- __model_mode__ = 'full'：全功能模式（识别文本+表格+公式+图片+版面）
- 可选精简模式：light


    # 3. 读取并处理
    with open(filepath, "rb") as f:
        pdf_bytes = f.read()

以二进制模式读取PDF文件
得到pdf_bytes：PDF原始字节数据（MinerU 要求用字节输入）


    ds = PymuDocDataset(pdf_bytes)

把PDF字节数据封装成 MinerU 标准数据集
作用：统一数据格式，供后续推理 pipeline 使用


    # 注意：此处推理需要已下载的模型权重
    infer_result = ds.apply(doc_analyze, ocr=True)

核心推理步骤：
- doc_analyze：执行PDF分析（版面、文字、表格、公式检测）
- ocr=True：开启OCR（扫描件PDF、图片里的文字都能识别）
- infer_result：推理原始结果（包含所有PDF元素信息）
⚠️ 报错解决：这里必须提前下载 MinerU 模型权重，否则直接报错


    # 附件目录适配
    if not os.path.exists(self.attachments_dir):
        os.makedirs(self.attachments_dir)

创建附件保存目录（存放PDF里的图片、图表）
self.attachments_dir：类中提前定义的路径（如./attachments）


    # MinerU 图片输出到临时目录，随后可根据需要同步
    image_writer = FileBasedDataWriter(self.attachments_dir)

初始化文件写入器
告诉 MinerU：把解析出的图片保存到 attachments 目录


    # 4. 获取 Pipeline 结果
    pipe_result = infer_result.pipe_ocr_mode(image_writer)

转换为OCR模式流水线结果
自动执行：元素整理 → 图片保存 → 格式结构化


    # 5. 获取 Markdown（图片路径设为相对 attachments 目录）
    md_content = pipe_result.get_markdown("attachments")

最终成果：把PDF转换成标准Markdown文本
参数"attachments"：图片路径统一替换为 attachments/xxx.png


    # 提取 attachments 信息（此处简单处理，MinerU 已将图片存入 self.attachments_dir）
    attachments = [] # 实际可遍历 self.attachments_dir 获取

附件列表：这里只是占位
真实使用：遍历self.attachments_dir，把图片名、路径存入列表


    return md_content, attachments

返回：Markdown全文 + 附件信息
外部调用即可拿到格式化好的PDF内容

完整运行流程（极简总结）

加载配置 → 启用MinerU内置模型
读取PDF为二进制
封装数据集 → 执行PDF推理（OCR+全要素解析）
创建附件目录 → 保存图片
生成标准Markdown
返回结果

必看：常见问题&解决方案

模型找不到报错 必须下载模型，放到配置文件指定的路径
OCR不生效 确保ocr=True，且模型为full模式
图片不输出 检查attachments_dir权限，确保路径正确
扫描版PDF乱码 必须开启ocr=True，MinerU会自动OCR识别

最简可独立运行Demo（直接复制测试）


import os
from magic_pdf.data.dataset import PymuDocDataset
from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze
from magic_pdf.data.data_reader_writer import FileBasedDataWriter
import magic_pdf.model as model_config

def pdf_to_markdown(pdf_path, save_img_dir="./attachments"):
    # 配置模型
    model_config.__use_inside_model__ = True
    model_config.__model_mode__ = "full"
    
    # 读取PDF
    with open(pdf_path, "rb") as f:
        pdf_bytes = f.read()
    
    # 推理
    ds = PymuDocDataset(pdf_bytes)
    infer_result = ds.apply(doc_analyze, ocr=True)
    
    # 保存图片
    os.makedirs(save_img_dir, exist_ok=True)
    writer = FileBasedDataWriter(save_img_dir)
    
    # 生成MD
    pipe_res = infer_result.pipe_ocr_mode(writer)
    md = pipe_res.get_markdown("attachments")
    
    return md

# 测试
if __name__ == "__main__":
    md = pdf_to_markdown("test.pdf")
    with open("output.md", "w", encoding="utf-8") as f:
        f.write(md)
    print("转换完成！")

总结

这段代码是标准MinerU生产级用法，逐行对应官方流程
核心：PymuDocDataset加载数据 + doc_analyze推理 + get_markdown输出
关键开关：ocr=True（识别图片/扫描版）、full模型（全功能）
最终输出：带图片、公式、表格的标准Markdown，可直接用于文档、大模型输入