注意：模型文件总共约 3-5GB，下载时间取决于网速，请耐心等待。下载完成后，模型文件会存放在以下位置：

• Windows：C:Users用户名.cachemodelscopehubmodelsopendatalabPDF-Extract-Kit-1.0
• Linux：/home/用户名/.cache/modelscope/hub/models/opendatalab/PDF-Extract-Kit-1.0

模型下载完成后，系统会自动在你用户目录生成 magic-pdf.json 配置文件。

找到配置文件：

查看配置文件内容：

在 Windows 上可以直接用记事本打开：

notepad C:Users%USERNAME%magic-pdf.json 

在 Linux/macOS 上：

cat ~/magic-pdf.json 

一个典型的配置文件内容如下（已去除注释）：

{ "bucket_info": { "bucket-name-1": [ "ak", "sk", "endpoint" ] }, "models-dir": "C:\Users\Administrator\.cache\modelscope\hub\models\opendatalab\PDF-Extract-Kit-1.0/models", "layoutreader-model-dir": "C:\Users\Administrator\.cache\modelscope\hub\models\ppaanngggg\layoutreader", "device-mode": "cpu", "layout-config": { "model": "doclayout_yolo" }, "formula-config": { "mfd_model": "yolo_v8_mfd", "mfr_model": "unimernet_small", "enable": true }, "table-config": { "model": "rapid_table", "sub_model": "slanet_plus", "enable": true, "max_time": 400 } } 

关键字段说明：

CPU 模式下，确保 device-mode 的值为 cpu：

{ "device-mode": "cpu" } 

如果当前值是 cuda，请用文本编辑器手动修改为 cpu。

下载一个官方样例 PDF 并测试解析效果：

# 下载样例 PDF（一个包含 OCR 内容的扫描版 PDF） curl -L https://github.com/opendatalab/MinerU/raw/master/demo/pdfs/small_ocr.pdf -o small_ocr.pdf # 解析 PDF magic-pdf -p small_ocr.pdf -o ./output 

命令逐字解释：

• magic-pdf — MinerU 的命令行工具
• -p small_ocr.pdf — 指定要解析的 PDF 文件路径（-p 是 --path 的简写）
• -o ./output — 指定输出目录（-o 是 --output 的简写），解析结果会保存在 ./output 目录下

运行过程中你会看到类似输出：

2026-04-18 17:57:14.502 | INFO | magic_pdf.data.dataset - lang: None 2026-04-18 17:57:18.912 | INFO | magic_pdf.libs.pdf_detect - detect result: ... 2026-04-18 17:57:19.123 | INFO | magic_pdf.model.doc_analyze - processing page 1... ... 

解析完成后，输出目录结构如下：

output/ └── small_ocr/ ├── small_ocr.md # Markdown 格式的解析结果 ├── small_ocr.json # JSON 格式的解析结果（包含更多结构化信息） ├── images/ # 提取出的图片 │ ├── 0_0.png │ └── ... └── layout_vis/ # 版面分析可视化（可选） └── ... 

打开 small_ocr.md 文件即可查看 Markdown 格式的解析结果。

以 RTX 3050 + i5 配置为例：

提示：CPU 模式下速度较慢，如果需要批量处理大量 PDF，强烈建议使用 GPU 模式。

本章节适合以下用户：

• 有 NVIDIA 显卡（显存 >= 6GB）
• 需要高性能解析
• 需要批量处理 PDF 文件

预计耗时：30-60 分钟（主要取决于 PyTorch 和模型下载速度）

5.1.1 检查 NVIDIA 显卡驱动

nvidia-smi 

如果看到类似输出，说明显卡驱动已正确安装：

+-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 572.70 Driver Version: 572.70 CUDA Version: 12.8 | |-----------------------------------------+------------------------+----------------------+ | GPU Name Driver-Model | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | |=========================================+========================+======================| | 0 NVIDIA GeForce RTX 3050 WDDM | 00000000:01:00.0 On | N/A | | 41% 47C P0 22W / 70W | 1368MiB / 6144MiB | 6% Default | +-----------------------------------------+------------------------+----------------------+ 

如果没有输出或报错：

1. Windows 用户：前往 NVIDIA 驱动下载页面 下载并安装最新驱动
2. Linux 用户：执行 sudo apt install nvidia-driver-550（或最新版本）

5.1.2 检查 CUDA 版本

在 nvidia-smi 的输出右上角，找到 CUDA Version: 12.8 这样的信息。这表示你的显卡驱动支持的最高 CUDA 版本。

关键理解：这里的 CUDA 版本只是驱动支持的版本号，实际使用时需要安装对应版本的 PyTorch CUDA 运行时库。MinerU 支持的 CUDA 版本为 11.8、12.4、12.6。通常选择 12.4 版本兼容性最好。

# 如果之前创建过 mineru 环境，先删除重建 conda env remove -n mineru -y # 创建新环境 conda create -n mineru python=3.10 -y # 激活环境 conda activate mineru # 验证 python --version # 应输出：Python 3.10.x 

pip install --upgrade pip pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple 

安装完成后验证：

magic-pdf --version # 应输出：magic-pdf, version 1.x.x 

这是 GPU 部署最容易踩坑的一步！

安装 magic-pdf[full] 时，pip 会自动安装 PyTorch。但默认安装的是 CPU 版本，即使你有显卡也无法使用 GPU 加速。因此必须强制安装 CUDA 版本。

5.4.1 检查当前 PyTorch 版本

python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')" 

如果输出类似：

PyTorch: 2.11.0+cpu CUDA: False 

说明当前是 CPU 版本，需要替换。

5.4.2 强制安装 CUDA 版本

根据你的 CUDA 版本选择对应的安装命令：

CUDA 12.4（推荐，兼容性最好）：

pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu124 

CUDA 11.8：

pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu118 

命令逐字解释：

• --force-reinstall — 强制重新安装，即使已经安装了也会覆盖
• torch torchvision — PyTorch 核心包和视觉处理库
• "numpy<=2.1.1" — 锁定 numpy 版本到 2.1.1 或更低，避免兼容性问题
• --index-url https://download.pytorch.org/whl/cu124 — 从 PyTorch 官方的 CUDA 12.4 仓库下载

注意：CUDA 版 PyTorch 体积很大（约 2.5GB），下载需要一定时间。请耐心等待，不要中断安装。

5.4.3 验证 CUDA 版 PyTorch 安装成功

python -c " import torch print(f'PyTorch version: {torch.__version__}') print(f'CUDA available: {torch.cuda.is_available()}') print(f'CUDA version (compiled): {torch.version.cuda}') print(f'cuDNN version: {torch.backends.cudnn.version()}') print(f'Device count: {torch.cuda.device_count()}') print(f'Device name: ') print(f'Device memory: GB') " 

正常输出应该类似：

PyTorch version: 2.6.0+cu124 CUDA available: True CUDA version (compiled): 12.4 cuDNN version: 90100 Device count: 1 Device name: NVIDIA GeForce RTX 3050 Device memory: 6.0 GB 

关键检查点：

• CUDA available: True — 必须为 True，否则 GPU 不可用
• PyTorch version: 2.6.0+cu124 — 版本号中必须包含 +cu124 或 +cu118，如果是 +cpu 则说明没装对

与 CPU 模式完全相同：

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

如果之前 CPU 模式已经下载过模型，可以跳过此步。模型文件是通用的，CPU 和 GPU 共用同一套模型文件。

打开用户目录下的 magic-pdf.json 文件，确保 device-mode 设置为 cuda：

{ "device-mode": "cuda" } 

模型下载脚本默认会将 device-mode 设置为 cuda，所以你一般不需要手动修改。但如果之前被改成了 cpu，请记得改回来。

不同显存大小的显卡，能开启的功能不同。请根据自己的情况调整 magic-pdf.json：

6GB 显存（如 RTX 3050）

仅开启基础加速（layout + OCR），关闭公式和表格识别：

{ "device-mode": "cuda", "formula-config": { "enable": false }, "table-config": { "enable": false } } 

8GB 显存（如 RTX 3060）

可以开启公式识别：

{ "device-mode": "cuda", "formula-config": { "enable": true }, "table-config": { "enable": false } } 

10GB+ 显存（如 RTX 3080 / 4070）

可以开启全部功能：

{ "device-mode": "cuda", "formula-config": { "enable": true }, "table-config": { "enable": true } } 

16GB+ 显存（如 RTX 4080 / A10）

**性能，可以启用批处理加速：

{ "device-mode": "cuda", "formula-config": { "enable": true }, "table-config": { "enable": true } } 

# 下载测试 PDF curl -L https://github.com/opendatalab/MinerU/raw/master/demo/pdfs/small_ocr.pdf -o small_ocr.pdf # 解析（GPU 自动加速） magic-pdf -p small_ocr.pdf -o ./output 

运行过程中，你可以打开另一个终端窗口运行 nvidia-smi 来观察 GPU 使用情况：

nvidia-smi -l 1 

你应该能看到 GPU 利用率（GPU-Util）和显存占用明显上升。

以同一份 20 页扫描版 PDF 为例：

Docker 部署适合以下场景：

• 服务器 / 云端部署
• 团队多人共用
• CI/CD 集成
• 环境隔离

6.1.1 安装 Docker

Windows 用户：

1. 下载并安装 Docker Desktop：https://www.docker.com/products/docker-desktop/
2. 安装完成后启动 Docker Desktop
3. 在设置中确保 WSL2 后端已启用

Linux（Ubuntu）用户：

# 卸载旧版本（如有） sudo apt remove -y docker docker-engine docker.io containerd runc # 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG key sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加 Docker 仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 将当前用户加入 docker 组（避免每次 sudo） sudo usermod -aG docker $USER # 重新登录使变更生效 # 验证 docker --version 

6.1.2 安装 NVIDIA Container Toolkit（GPU 模式需要）

如果你需要在 Docker 容器内使用 GPU 加速，必须安装 NVIDIA Container Toolkit。

Linux 用户：

# 添加 NVIDIA 软件源 curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list # 安装 sudo apt update sudo apt install -y nvidia-container-toolkit # 配置 Docker sudo nvidia-ctk runtime configure --runtime=docker # 重启 Docker sudo systemctl restart docker 

Windows 用户（Docker Desktop + WSL2）：

Docker Desktop for Windows 默认已包含 NVIDIA GPU 支持，只要确保 WSL2 中的 NVIDIA 驱动已安装即可（通常 Windows 显卡驱动会自动安装到 WSL2 中）。

6.1.3 验证 Docker GPU 支持

docker run --rm --gpus=all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi 

如果能看到类似 GPU 信息，说明配置正确：

+-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 572.70 Driver Version: 572.70 CUDA Version: 12.8 | | ... | | 0 NVIDIA GeForce RTX 3050 WDDM | ... | +-----------------------------------------+ 

如果报错 could not select device driver，请检查 NVIDIA Container Toolkit 是否正确安装。

MinerU 官方提供了 Dockerfile，已经配置好了所有依赖和模型下载步骤。

# 下载适用于国内网络的 Dockerfile（使用国内镜像源） curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfile -o Dockerfile 

Dockerfile 内容详解：

这个 Dockerfile 做了以下事情：

1. 基础镜像：使用 Ubuntu 22.04
2. 安装 Python 3.10：通过 PPA 仓库安装
3. 创建虚拟环境：在 /opt/mineru_venv 创建 Python 虚拟环境
4. 安装 magic-pdf[full]：使用阿里云镜像源安装
5. 下载模型文件：使用 ModelScope 下载所有模型
6. 设置设备模式：将 device-mode 从 cpu 改为 cuda
7. 安装中文和日文字体：确保 PDF 渲染时中文不会乱
8. 安装 LibreOffice：支持 Word/PPT 文档处理
9. 安装 poppler-utils：PDF 处理工具

docker build -t mineru:latest . 

构建过程说明：

Docker 会按顺序执行 Dockerfile 中的每一条指令：

1. Step 1/10: FROM ubuntu:22.04 — 拉取 Ubuntu 22.04 基础镜像
2. Step 2/10: ENV DEBIAN_FRONTEND=noninteractive — 设置非交互模式
3. Step 3/10: RUN apt-get update && apt-get install -y ... — 安装系统依赖（约 500MB）
4. Step 4/10: RUN update-alternatives ... — 设置 Python 3.10 为默认
5. Step 5/10: RUN python3 -m venv /opt/mineru_venv — 创建虚拟环境
6. Step 6/10: RUN pip3 install magic-pdf[full] — 安装 MinerU（约 2GB，最耗时）
7. Step 7/10: RUN pip3 install modelscope && python3 download_models.py — 下载模型（约 3-5GB）
8. ...

预计构建时间：30-60 分钟，取决于网速。主要耗时在步骤 6（安装包下载）和步骤 7（模型下载）。

构建完成后，验证镜像是否创建成功：

docker images | grep mineru 

应输出类似：

mineru latest abc123def456 2 minutes ago 10GB 

6.4.1 CPU 模式运行

docker run -it --name mineru mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" 

命令逐字解释：

• docker run — 运行一个容器
• -it — 交互式终端（-i 保持标准输入，-t 分配伪终端）
• --name mineru — 给容器起名为 mineru
• mineru:latest — 使用的镜像名称和标签
• /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" — 启动后自动激活虚拟环境，然后进入 bash 交互模式

进入容器后：

# 验证安装 magic-pdf --version # 解析 PDF magic-pdf -p /path/to/file.pdf -o /path/to/output 

6.4.2 GPU 模式运行

docker run -it --name mineru --gpus=all mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" 

与 CPU 模式唯一的区别是多了 --gpus=all 参数，这会让容器能够访问宿主机的所有 GPU。

6.4.3 挂载宿主机目录

如果你需要让容器访问宿主机上的 PDF 文件，需要使用 -v 参数挂载目录：

# Windows（使用 Git Bash / WSL） docker run -it --gpus=all -v /d/pdfs:/data/pdfs -v /d/output:/data/output mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" # Linux docker run -it --gpus=all -v /home/user/pdfs:/data/pdfs -v /home/user/output:/data/output mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" 

挂载后，在容器内访问 /data/pdfs 就相当于访问宿主机的 /d/pdfs（Windows）或 /home/user/pdfs（Linux）。

然后在容器内执行：

magic-pdf -p /data/pdfs/sample.pdf -o /data/output 

你也可以不进入容器交互，直接用一行命令解析 PDF：

docker run --rm --gpus=all -v /d/pdfs:/data mineru:latest magic-pdf -p /data/sample.pdf -o /data/output 

说明：

• --rm — 容器运行结束后自动删除
• 这条命令会启动容器、运行 magic-pdf 命令、输出结果到挂载目录、然后清理容器

如果你希望以配置文件的方式管理 MinerU 容器，可以使用 Docker Compose。

创建 docker-compose.yml 文件：

version: '3.8' services: mineru: image: mineru:latest container_name: mineru deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] volumes: - ./pdfs:/data/pdfs - ./output:/data/output stdin_open: true tty: true restart: unless-stopped 

启动：

# 启动容器并进入交互模式 docker compose up -d docker compose exec mineru /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" # 在容器内执行解析 magic-pdf -p /data/pdfs/sample.pdf -o /data/output 

停止：

docker compose down 

MinerU 提供了基于 Gradio 的 Web 图形界面，适合不喜欢命令行的用户使用。

确保你已经完成了 本机 CPU 部署 或 本机 GPU 部署。

conda activate mineru pip install gradio gradio-pdf 

依赖说明：

• gradio — Web 界面框架
• gradio-pdf — PDF 预览组件

MinerU 项目中包含了 Gradio 应用的示例代码，位于 projects/gradio_app/ 目录下。

如果你是通过 git clone 获取的项目：

cd projects/gradio_app 

如果你没有 clone 整个项目，可以手动创建一个 app.py 文件：

import gradio as gr from gradio_pdf import PDF from magic_pdf.tools.cli import do_parse import os import tempfile def parse_pdf(pdf_file): """解析 PDF 文件并返回 Markdown 内容""" output_dir = tempfile.mkdtemp() result = do_parse(pdf_file, output_dir) return result # 创建 Gradio 界面 with gr.Blocks(title="MinerU PDF Parser") as demo: gr.Markdown("# MinerU PDF 解析器") with gr.Row(): with gr.Column(): pdf_input = gr.File(label="上传 PDF 文件", file_types=[".pdf"]) parse_btn = gr.Button("开始解析") with gr.Column(): pdf_preview = PDF(label="PDF 预览") md_output = gr.Markdown(label="解析结果") parse_btn.click( fn=parse_pdf, inputs=[pdf_input], outputs=[md_output] ) if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860) 

注意：以上代码是一个简化示例。完整的 Gradio 应用请参考 MinerU 项目中的 projects/gradio_app/app.py。

python app.py 

启动后，终端会输出类似以下信息：

Running on local URL: http://127.0.0.1:7860 

打开浏览器，访问：

http://127.0.0.1:7860 

如果你希望从其他设备访问，在启动时指定 server_name：

python app.py --server-name 0.0.0.0 --server-port 7860 

然后通过 http://你的IP地址:7860 访问。

本章节详细介绍 MinerU 的两种推理模式的使用方法。

切换模式只需要修改 magic-pdf.json 中的 device-mode 字段：

切换到 CPU：

{ "device-mode": "cpu" } 

切换到 GPU：

{ "device-mode": "cuda" } 

切换到 MPS（Apple Silicon Mac）：

{ "device-mode": "mps" } 

注意：切换到 GPU 模式前，请确保已经安装了 CUDA 版本的 PyTorch（参见 5.4 节）。

命令行用法在 CPU 和 GPU 模式下完全相同：

# 解析单个文件 magic-pdf -p sample.pdf -o ./output # 指定 OCR 语言（默认为 auto，自动检测） magic-pdf -p sample.pdf -o ./output --lang ch # 指定解析方法（默认 auto，自动检测文档类型） magic-pdf -p sample.pdf -o ./output --method auto 

所有可用参数：

magic-pdf --help 

输出类似：

Usage: magic-pdf [OPTIONS] Options: -p, --path PATH PDF 文件路径（必填） -o, --output PATH 输出目录（必填） --lang TEXT OCR 语言，默认为 auto --method TEXT 解析方法，默认为 auto -h, --help 显示帮助信息 

方法一：Shell 脚本批量处理

#!/bin/bash # 设置输入输出目录 INPUT_DIR="/path/to/pdfs" OUTPUT_DIR="./output" # 创建输出目录 mkdir -p "$OUTPUT_DIR" # 遍历目录下所有 PDF 文件 for pdf_file in "$INPUT_DIR"/*.pdf; do # 获取文件名（不含扩展名） filename=$(basename "$pdf_file" .pdf) echo "正在解析: $filename" # 解析 PDF magic-pdf -p "$pdf_file" -o "$OUTPUT_DIR" echo "完成: $filename" echo "---" done echo "全部解析完成！" 

保存为 batch_parse.sh，然后执行：

# Linux / macOS chmod +x batch_parse.sh ./batch_parse.sh # Windows（Git Bash） bash batch_parse.sh 

方法二：Python 脚本批量处理

创建 batch_parse.py：

import os import glob from magic_pdf.tools.cli import do_parse # 设置输入输出目录 INPUT_DIR = "/path/to/pdfs" OUTPUT_DIR = "./output" # 创建输出目录 os.makedirs(OUTPUT_DIR, exist_ok=True) # 获取所有 PDF 文件 pdf_files = glob.glob(os.path.join(INPUT_DIR, "*.pdf")) print(f"找到 {len(pdf_files)} 个 PDF 文件") for i, pdf_path in enumerate(pdf_files, 1): filename = os.path.basename(pdf_path) print(f"[{i}/{len(pdf_files)}] 正在解析: {filename}") try: do_parse(pdf_path, OUTPUT_DIR) print(f" 完成: {filename}") except Exception as e: print(f" 失败: {filename} - {e}") print("全部解析完成！") 

执行：

conda activate mineru python batch_parse.py 

如果你希望在 Python 代码中调用 MinerU，可以使用以下方式：

方法一：使用 API 接口

from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze from magic_pdf.data.dataset import PymuPDFDataset from magic_pdf.tools.common import do_parse # 加载 PDF 文件 pdf_path = "sample.pdf" dataset = PymuPDFDataset(pdf_path) # 执行版面分析（自动使用配置文件中的 device-mode） result = doc_analyze(dataset, model_name="doclayout_yolo") # 解析并导出 do_parse( pdf_path, dataset, result, output_dir="./output", # 可选参数 # lang="ch", # 指定 OCR 语言 # method="auto", # 指定解析方法 ) 

方法二：使用 CLI 模块

from magic_pdf.tools.cli import do_parse # 一行代码搞定 result = do_parse("sample.pdf", "./output") print(result) 

在 GPU 模式下运行时，可以在另一个终端窗口监控 GPU 使用情况。

Linux / Windows：

# 每秒刷新一次 nvidia-smi -l 1 

输出示例：

Every 1.0s: nvidia-smi +-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 572.70 Driver Version: 572.70 CUDA Version: 12.8 | |-----------------------------------------+------------------------+----------------------+ | GPU Name Driver-Model | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | |=========================================+========================+======================| | 0 NVIDIA GeForce RTX 3050 WDDM | 00000000:01:00.0 On | N/A | | 65% 72C P2 65W / 70W | 4892MiB / 6144MiB | 95% Default | +-----------------------------------------+------------------------+----------------------+ 

关键指标：

• GPU-Util: 95% — GPU 利用率，越高说明 GPU 越充分地被利用
• Memory-Usage: 4892MiB / 6144MiB — 显存使用量，如果接近上限可能会 OOM
• Temp: 72C — GPU 温度，超过 85C 建议增加散热

问题描述： 安装 magic-pdf[full] 时 pip 报错，提示某些包版本冲突。

解决方案：

1. 使用干净的 Conda 环境

# 删除旧环境 conda env remove -n mineru -y # 重新创建 conda create -n mineru python=3.10 -y conda activate mineru # 升级 pip pip install --upgrade pip # 重新安装 pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple 

2. 如果仍然失败，尝试逐个安装依赖

pip install numpy==2.1.1 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124 pip install "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple 

问题描述： 明明有 NVIDIA 显卡，但 GPU 就是无法使用。

排查步骤：

步骤 1：检查 PyTorch 版本

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

如果输出中包含 +cpu（如 2.11.0+cpu），说明安装的是 CPU 版本。

步骤 2：强制安装 CUDA 版本

pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu124 

步骤 3：验证

python -c "import torch; print(torch.cuda.is_available())" # 应输出: True 

步骤 4：如果仍然为 False

检查 NVIDIA 驱动是否正确安装：

nvidia-smi 

如果这个命令报错，说明显卡驱动有问题，需要先修复驱动。

问题描述： 执行 python download_models.py 时报网络连接错误。

解决方案 1：使用 HuggingFace 镜像

pip install huggingface_hub # 下载 HuggingFace 版本的模型下载脚本 curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models_hf.py -o download_models_hf.py python download_models_hf.py 

解决方案 2：手动下载模型

如果脚本也下载不了，可以手动从 ModelScope 网站下载：

1. 访问 https://www.modelscope.cn/models/opendatalab/PDF-Extract-Kit-1.0
2. 下载所有文件到 ~/.cache/modelscope/hub/models/opendatalab/PDF-Extract-Kit-1.0 目录
3. 手动修改 magic-pdf.json 中的 models-dir 路径

问题描述： 运行时报错 CUDA out of memory。

解决方案：

方案 1：关闭部分功能

编辑 magic-pdf.json：

{ "table-config": { "enable": false }, "formula-config": { "enable": false } } 

方案 2：减少批处理大小

如果你有大批量 PDF 需要处理，建议逐个处理而非批量：

# 不要同时解析多个文件 magic-pdf -p file1.pdf -o ./output magic-pdf -p file2.pdf -o ./output 

方案 3：升级显卡或使用 CPU 模式

如果显存实在不够，可以切换到 CPU 模式：

{ "device-mode": "cpu" } 

问题描述： 使用中文路径的文件无法解析，或者输出内容中文乱码。

解决方案：

1. 配置文件路径使用双反斜杠

{ "models-dir": "C:\Users\张三\.cache\modelscope\hub\models\opendatalab\PDF-Extract-Kit-1.0\models" } 

2. PowerShell 中设置 UTF-8 编码

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8 

3. 尽量使用英文路径

为了避免编码问题，建议 PDF 文件路径使用英文。

问题描述： 在 Docker 容器内运行 nvidia-smi 报错。

排查步骤：

1. 确认 NVIDIA Container Toolkit 已安装

# 检查是否安装 dpkg -l | grep nvidia-container-toolkit 

2. 确认 Docker 已配置 NVIDIA 运行时

sudo nvidia-ctk runtime configure –runtime=docker sudo systemctl restart docker 

3. 运行容器时必须加上 –gpus=all 参数

docker run –gpus=all … 

问题描述： 解析出的 Markdown 内容缺失图片、公式或表格。

排查步骤：

1. 确认所有功能已启用

检查 magic-pdf.json 中 formula-config.enable 和 table-config.enable 是否为 true。

2. 查看日志输出

MinerU 运行时会输出详细信息，注意查看是否有 WARNING 或 ERROR 级别的日志。

3. 尝试更新模型

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