Windows 本地部署MinerU详细教程

📖 项目概述

MinerU是一款由OpenDataLab开发的开源PDF转Markdown工具，可以高质量地提取PDF文档内容，生成结构化的Markdown格式文本。本指南将帮助您在本地部署并使用MinerU。

⭐ 功能特性

MinerU具有以下核心功能：

✨ 文档处理

删除页眉、页脚、脚注、页码等元素，确保语义连贯
保留原文档的结构，包括标题、段落、列表等
提取图像、图片描述、表格、表格标题及脚注
🔄 格式转换
自动识别并转换文档中的公式为LaTeX格式
自动识别并转换文档中的表格为HTML格式
💻 运行环境
支持纯CPU环境运行
支持GPU加速，提升处理效率

💻 Windows10/11

📌 注意：一定要仔细看好每个软件及环境的版本

1. 安装cuda和cuDNN

需要安装的版本 CUDA 11.8 + cuDNN 8.7.0

CUDA 11.8 https://developer.nvidia.com/cuda-11-8-0-download-archive
cuDNN v8.7.0 (November 28th, 2022), for CUDA 11.x https://developer.nvidia.com/rdp/cudnn-archive
安装教程参考：https://zhuanlan.zhihu.com/p/32400431090

2. 安装anaconda

如果已安装conda，可以跳过本步骤

下载链接：
https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/Anaconda3-2024.06-1-Windows-x86_64.exe

安装教程：https://blog.csdn.net/m0_66047447/article/details/141110995

3. 使用conda 创建环境

需指定python版本为3.10
📌 方案一：创建默认环境

bash 复制代码

conda create -n MinerU python=3.10
conda activate MinerU

📌 方案二：指定自定义路径创建环境

bash 复制代码

conda create --prefix=D:\Computer\Anaconda\envs\mineru python=3.10 
conda activate mineru

4. 安装应用

bash 复制代码

pip install -U magic-pdf[full] --extra-index-url https://wheels.myhloli.com -i https://pypi.tuna.tsinghua.edu.cn/simple

❗️下载完成后，验证版本信息：
bash 复制代码
magic-pdf --version   
# 当前版本：1.3.11

5. 下载模型

首次使用需下载模型文件，提供两种下载方式：

📥 方法一：从Hugging Face下载模型（国际用户推荐）

bash 复制代码

pip install huggingface_hub
curl -o download_models_hf.py https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models_hf.py
python download_models_hf.py

📥 方法二：从ModelScope下载模型（国内用户推荐）

bash 复制代码

pip install modelscope 
curl -o download_models.py https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py
python download_models.py

📁 模型默认存储路径示例：

bash 复制代码

model_dir: C:\Users\用户名\.cache\modelscope\hub\models\opendatalab\PDF-Extract-Kit-1___0/models
layoutreader_model_dir: C:\Users\用户名\.cache\modelscope\hub\models\ppaanngggg\layoutreader

💡 提示 ：下载完成后，系统会自动在用户目录下生成magic-pdf.json配置文件

用户目录位置：

🪟 Windows：C:\Users\用户名
🐧 Linux：/home/用户名
🍎 macOS：/Users/用户名
⚡下载后请将models目录移动到空间较大的ssd磁盘目录

❗️模型下载后请务必检查模型文件是否下载完整

请检查目录下的模型文件大小与网页上描述是否一致，如果可以的话，最好通过sha256校验模型是否下载完整
❗️务必确保配置文件在【用户目录】下，否则程序将无法运行

windows用户目录为 "C:\Users\用户名"

在用户目录中找到magic-pdf.json文件并配置"models-dir"为下载的模型权重文件所在目录

❗️务必正确配置模型权重文件所在目录的【绝对路径】，否则会因为找不到模型文件而导致程序无法运行

windows系统中此路径应包含盘符，且需把路径中所有的"\"替换为"/",否则会因为转义原因导致json文件语法错误。

例如：模型放在D盘根目录的models目录，则model-dir的值应为"D:/models"

json 复制代码

{
  "models-dir": "/tmp/models"
}

6. CUDA加速

如果您的NVIDIA显卡显存≥8GB，可配置CUDA加速：

1.覆盖安装支持cuda的torch和torchvision

bash 复制代码

pip install --force-reinstall torch==2.3.1 torchvision==0.18.1 --index-url https://download.pytorch.org/whl/cu118

❗️务必在命令中指定以下版本，当前 magic-pdf 版本为 1.3.11（如果不是这个版本请查阅最新的官方安装文档） MinerU
bash 复制代码
torch==2.3.1 torchvision==0.18.1 
这是我们支持的最高版本，如果不指定版本会自动安装更高版本导致程序无法运行

2.修改【用户目录】中配置文件magic-pdf.json中"device-mode"的值

json 复制代码

{
  "device-mode":"cuda"
}

3.运行以下命令测试cuda加速效果

bash 复制代码

magic-pdf -p demo1.pdf -o ./output

-p 为本地pdf文件路径或目录

-o 输出本地目录

提示：CUDA加速是否生效可以根据log中输出的各个阶段cost耗时来简单判断，通常情况下，layout detection cost 和 mfr time 应提速10倍以上。

bash 复制代码

magic-pdf --help
Usage: magic-pdf [OPTIONS]

Options:
  -v, --version                display the version and exit
  -p, --path PATH              local pdf filepath or directory  [required]
  -o, --output-dir TEXT        output local directory
  -m, --method [ocr|txt|auto]  the method for parsing pdf.
                               ocr: using ocr technique to extract information from pdf,
                               txt: suitable for the text-based pdf only and outperform ocr,
                               auto: automatically choose the best method for parsing pdf
                                  from ocr and txt.
                               without method specified, auto will be used by default.
  --help                       Show this message and exit.


## show version
magic-pdf -v

## command line example
magic-pdf -p {some_pdf} -o {some_output_dir} -m auto

4.执行命令可能遇到NumPy 版本不兼容问题问题

🚨 报错关键信息如下：

bash 复制代码

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.1.2 as it may crash.

...


Traceback (most recent call last):
...
magic_pdf.tools.cli:parse_doc:134 - Numpy is not available

🔍 问题分析
✅ 当前环境：

已安装 numpy==2.1.2（最新版本）
使用了依赖于旧版 NumPy（1.x）的模块或库（如 ultralytics, magic-pdf 等）

❌ 问题原因：

某些 Python 包（例如 ultralytics 或其依赖项）是在 NumPy 1.x 上编译的。而你现在使用的是 NumPy 2.x，它们之间存在ABI 兼容性问题，导致这些包无法正常加载或运行。

✅ 解决方案：降级 NumPy 到 1.x 版本

✅ 推荐操作步骤：

bash 复制代码

pip uninstall numpy -y
pip install numpy==1.26.4

✅ NumPy 1.26.4 是目前最稳定且与大多数包兼容的最后一代 1.x 版本。

💡 额外建议（防止意外升级）

你可以冻结当前环境中的 numpy 版本，防止后续 pip 安装其他包时自动升级：

bash 复制代码

numpy==1.26.4

或者创建一个 constraints.txt 文件，内容如下：

bash 复制代码

pip install -r requirements.txt --constraint constraints.txt

🧪 验证是否修复成功

执行以下命令验证 numpy 是否已正确降级：

bash 复制代码

python -c "import numpy; print(numpy.__version__)"

输出应为：

bash 复制代码

1.26.4

然后再重新运行你的 magic-pdf 命令：

bash 复制代码

magic-pdf -p {some_pdf} -o {some_output_dir}

7. 为ocr开启cuda加速

❗️以下操作需显卡显存大于等于16G才可进行，否则会因为显存不足导致程序崩溃或运行速度下降

1.下载paddlepaddle-gpu, 安装完成后会自动开启ocr加速

bash 复制代码

pip install paddlepaddle-gpu==2.6.1

2.运行以下命令测试ocr加速效果

bash 复制代码

magic-pdf -p small_ocr.pdf -o ./output

提示：CUDA加速是否生效可以根据log中输出的各个阶段cost耗时来简单判断，通常情况下，ocr cost应提速10倍以上。