引言 MinerU是一款开源的智能文档解析工具，专注于将PDF等文档高效转换为Markdown和JSON等结构化格式。在当前大语言模型(LLM)蓬勃发展的时代，高质量的结构化数据对于训练和微调LLM至关重要。MinerU通过其强大的智能文档解析能力，不仅可以为LLM提供清晰的训练语料，还能作为AI应用的重要数据预处理工具。与传统PDF处理工具不同，MinerU的智能解析能力涵盖了文本、图片、表格和公式等多模态内容，尤其适用于多语言文档和复杂布局的PDF文件批量处理。本文将重点介绍MinerU的核心特点、环境配置，以及详细的使用教程。
MinerU的特点 MinerU MinerU在文档解析方面具有以下关键特点：
语义一致性 ：支持移除页眉、页脚、脚注、页码等内容，确保语义连贯。 人类可读性 ：输出文本按照人类阅读顺序排列，支持单列、多列及复杂布局。 结构保留 ：保留原始文档的结构，包括标题、段落、列表等。 多样化内容提取 ：支持提取图像、图像描述、表格、表格标题和脚注。 公式转换 ：自动识别文档中的公式并转换为LaTeX格式。 表格转换 ：自动识别文档中的表格并转换为HTML格式。 OCR功能 ：自动检测扫描版PDF和乱码PDF，并启用OCR功能。 多语言支持 ：OCR功能支持84种语言的检测和识别。 多种输出格式 ：支持多模态和NLP Markdown、按阅读顺序排序的JSON以及丰富的中间格式。 可视化结果
：支持布局可视化和跨度可视化，便于高效确认输出质量。 多种运行环境 ：支持纯CPU环境运行，并支持GPU(CUDA)/NPU(CANN)/MPS加速。 跨平台兼容性 ：兼容Windows、Linux和Mac平台。 安装与环境准备 系统与硬件要求 为了确保MinerU的稳定运行，官网建议在以下环境中部署：
操作系统 ：Linux（2019年后版本）、Windows 10/11、macOS 11+ Python版本 ：3.10（请使用conda创建Python虚拟环境） 硬件加速支持 CPU模式 ：支持所有现代x86_64或ARM64架构的CPU。 GPU模式 ：支持NVIDIA显卡（8GB显存及以上），需要安装CUDA 11.8及cuDNN v8.7.0。 NPU模式 ：支持华为Ascend NPU（Ascend 910b），需要安装CANN 8.0+。 安装步骤 这里所列的安装步骤，以我自己的使用环境为例，仅供参考。
1. 创建Python虚拟环境 使用conda创建一个独立的Python 3.10虚拟环境：
conda create -n MinerU python=3.10 conda activate MinerU 2. 安装MinerU 使用pip安装MinerU及其依赖：
pip install -U "magic-pdf[full]" --extra-index-url https://wheels.myhloli.com 3. 下载模型文件 MinerU需要预训练的模型文件来解析PDF内容。以下是下载模型文件的步骤：
a. 安装所需工具：
pip install huggingface_hub b. 下载模型文件的Python脚本：
wget https://github.com/opendatalab/MinerU/raw/master/scripts/download_models_hf.py -O download_models_hf.py c. 执行下载脚本：
python download_models_hf.py 该脚本会自动从Hugging Face下载模型文件，并将其配置到用户目录下的配置文件中。
下载完成后，模型文件的路径会自动更新到用户目录下的 magic-pdf.json 配置文件中。您可以手动检查配置文件以确认模型路径是否正确。
注意，如果只想使用CPU模式，安装到这里就可以了，如果想使用GPU加速，请继续往下看。
4. 使用GPU加速（Colab环境） 因为本人的笔记本GPU较为孱弱，所以这里使用Google Colab来演示GPU加速。
在完成前述步骤后，请执行以下步骤：
a. 修改配置文件，将设备从 cpu 切换为 cuda ：
!sed -i 's|cpu|cuda|g' ~/magic-pdf.json b. 安装PaddlePaddle的GPU版本（适配CUDA 11.8）：
!pip install https://paddle-whl.bj.bcebos.com/stable/cu118/paddlepaddle-gpu/paddlepaddle_gpu-3.0.0b1-cp310-cp310-linux_x86_64.whl 5. 验证安装 安装完成后，运行以下命令检查安装是否成功：
magic-pdf -v PDF解析功能详解 MinerU在PDF解析方面的功能强大且灵活，支持文本模式（Text Mode）和OCR模式（OCR Mode），能够根据PDF的内容类型自动选择最佳解析方法。一般有两种方式调用MinerU，一种是基于API的PDF解析，另一种是基于命令行的PDF解析。
基于API的PDF解析 MinerU提供了强大的Python API，用户可以通过代码调用其功能。以下是一个解析本地PDF文件的示例：
示例：解析本地PDF文件 import os from magic_pdf.data.data_reader_writer import FileBasedDataWriter, FileBasedDataReader from magic_pdf.data.dataset import PymuDocDataset from magic_pdf.model.doc_analyze_by_custom_model
import doc_analyze from magic_pdf.config.enums import SupportedPdfParseMethod # 输入PDF文件路径 pdf_file_name = "example.pdf" local_image_dir, local_md_dir = "output/images" , "output" # 创建输出目录 os.makedirs(local_image_dir, exist_ok= True ) image_writer, md_writer = FileBasedDataWriter(local_image_dir), FileBasedDataWriter(local_md_dir) # 读取PDF内容 reader = FileBasedDataReader( "" ) pdf_bytes = reader.read(pdf_file_name) # 创建数据集实例并进行分类 ds = PymuDocDataset(pdf_bytes) if ds.classify() == SupportedPdfParseMethod.OCR: infer_result = ds.apply(doc_analyze, ocr= True ) pipe_result = infer_result.pipe_ocr_mode(image_writer) else : infer_result = ds.apply(doc_analyze, ocr= False ) pipe_result = infer_result.pipe_txt_mode(image_writer) # 输出Markdown文件 pipe_result.dump_md(md_writer, f" {os.path.splitext(pdf_file_name)[ 0 ]} .md" , local_image_dir) 结果说明 运行上述代码后，MinerU会生成以下文件：
Markdown文件 ：包含PDF内容的结构化文本。 基于命令行的PDF解析 MinerU的命令行工具（CLI）提供了一种快速解析PDF的方法，适合非开发者用户。以下是常用命令参数及示例：
命令参数 magic-pdf -- help Usage: magic-pdf [OPTIONS] Options: -p, --path PATH 输入文件路径或目录，支持PDF、PPT、DOC等格式 [必需] -o, --output-dir PATH 输出目录 [必需] -m, --method [ocr|txt|auto] 选择解析方法，默认为auto -l, --lang TEXT 指定OCR语言，支持多语言 -s, --start INTEGER 起始页码 -e, --end INTEGER 结束页码 示例：解析PDF文件 magic-pdf -p example.pdf -o output_dir -m auto 执行上述命令后，MinerU会自动选择最佳解析方法并将结果保存到指定的输出目录中。
OCR模式解析 对于扫描版PDF或图片形式的PDF，MinerU会自动启用OCR模式。通过指定语言参数（如 --lang zh ），可以进一步提高OCR的准确性。
文档内容输出 MinerU支持多种输出格式，包括：
Markdown ：适合人类阅读的文本格式，保留文档的结构化信息。 JSON ：包含丰富的中间处理结果，便于进一步处理和分析。 其他高级功能 MinerU在解析PDF时，还提供以下高级功能：
公式解析 ：自动将PDF中的公式转换为LaTeX格式，便于科学计算和排版。 表格解析 ：将表格内容转换为HTML格式，支持复杂表格结构。 可视化结果 ：生成布局和跨度可视化结果，帮助用户快速验证解析效果。 
