OpenDataLab/MinerU 的安装与部署

本文详细介绍了OpenDataLab/MinerU的系统环境要求、Docker部署指南、本地安装步骤以及常见问题解决方案。内容涵盖硬件配置、操作系统支持、软件依赖、网络配置等部署前准备，并提供了基于Docker的快速部署方案和本地pip/源码安装方式。最后总结了部署和使用过程中可能遇到的典型问题及其解决方法。

系统环境要求

在部署和使用 OpenDataLab/MinerU 之前，确保您的系统满足以下环境要求。这些要求涵盖了硬件、操作系统、软件依赖以及网络配置等方面，以确保 MinerU 能够高效运行。

1. 硬件要求

组件	最低配置	推荐配置
CPU	4 核	8 核或更高
内存	8 GB	16 GB 或更高
GPU	支持 CUDA 的 NVIDIA 显卡（8GB 显存）	NVIDIA Turing/Ampere/Ada Lovelace 架构（16GB+ 显存）
存储	50 GB 可用空间	100 GB 或更高（用于模型缓存）

[!NOTE] 如果使用 sglang 加速 VLM 模型推理，必须满足以下额外条件：

• 显卡架构需为 Turing 或更高版本。
• 显存至少为 8GB。
• 物理机显卡驱动需支持 CUDA 12.6 或更高版本（Blackwell 平台需支持 CUDA 12.8）。

---

2. 操作系统要求

MinerU 支持以下操作系统：

操作系统	版本	备注
Linux	Ubuntu 20.04/22.04	推荐使用 Ubuntu 22.04 LTS
Windows	Windows 10/11	需安装 WSL2（推荐 Ubuntu 子系统）
macOS	macOS 12+	仅支持 CPU 推理

[!TIP] 在 Linux 系统上部署时，建议使用 Docker 容器以避免环境冲突。

---

3. 软件依赖

以下是 MinerU 运行所需的核心软件依赖：

依赖项	版本要求	安装方式
Python	3.10 - 3.12	通过 pyenv 或系统包管理器安装
CUDA	12.6（Linux/Windows）	从 NVIDIA 官网下载安装
Docker	24.0+	通过官方脚本安装
NVIDIA 驱动	支持 CUDA 12.6+	通过系统包管理器或 NVIDIA 官网安装

3.1 Python 依赖

MinerU 的 Python 依赖项可通过 pip 安装：

pip install torch>=2.2.0 transformers>=4.54.0 sglang>=0.4.9

3.2 Docker 依赖

如果使用 Docker 部署，需确保 Docker 已正确配置 NVIDIA 运行时：

docker run --rm --gpus all nvidia/cuda:12.6-base nvidia-smi

---

4. 网络配置

配置项	要求
带宽	10 Mbps 或更高（用于模型下载）
代理	如需访问外部资源，需配置代理
端口	确保以下端口可用： - 30000（sglang-server） - 7860（Gradio WebUI） - 8000（FastAPI）

---

5. 环境验证

在部署前，可通过以下命令验证环境是否满足要求：

5.1 验证 GPU 驱动

nvidia-smi

输出应显示 GPU 信息和 CUDA 版本。

5.2 验证 Python 环境

python -c "import torch; print(torch.cuda.is_available())"

输出应为 True。

5.3 验证 Docker 环境

docker run --rm --gpus all nvidia/cuda:12.6-base nvidia-smi

输出应与本地 nvidia-smi 结果一致。

---

6. 常见问题

6.1 显存不足

如果显存不足，可尝试以下方法：

• 降低 max_new_tokens 参数。
• 使用 vlm-sglang-client 模式连接远程服务器。

6.2 依赖冲突

建议使用虚拟环境或 Docker 容器隔离依赖：

python -m venv mineru-env
source mineru-env/bin/activate

6.3 模型下载失败

可通过配置镜像源加速下载：

export HF_ENDPOINT=https://hf-mirror.com

通过以上步骤，您可以确保系统环境满足 MinerU 的部署和运行需求。

Docker 部署指南

MinerU 提供了基于 Docker 的快速部署方案，支持通过 docker-compose 快速启动 sglang-server、mineru-api 和 mineru-gradio 服务。以下内容将详细介绍如何通过 Docker 部署 MinerU。

1. 准备工作

在开始部署之前，请确保满足以下条件：

• 已安装 Docker 和 Docker Compose。
• 确保 GPU 驱动已正确安装，并支持 CUDA（推荐版本为 12.6 或更高）。
• 至少 8GB 显存（推荐 16GB 及以上）。

2. 配置文件解析

MinerU 的 Docker 部署配置文件位于 docker/compose.yaml 中，包含以下服务：

• mineru-sglang-server：提供 sglang-server 服务，用于模型推理。
• mineru-api：提供 FastAPI 接口服务。
• mineru-gradio：提供 Gradio WebUI 服务。

关键配置说明

services:
  mineru-sglang-server:
    image: mineru-sglang:latest
    ports:
      - 30000:30000
    environment:
      MINERU_MODEL_SOURCE: local
    command:
      --host 0.0.0.0
      --port 30000
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]
              capabilities: [gpu]

3. 构建镜像

MinerU 提供了两种 Dockerfile，分别适用于全球和中国地区：

• 全球版：基于官方 sglang 镜像构建。
• 中国版：使用 DaoCloud 镜像加速构建。

全球版 Dockerfile

FROM lmsysorg/sglang:v0.4.9.post6-cu126
RUN apt-get update && apt-get install -y fonts-noto-cjk libgl1
RUN pip install -U 'mineru[core]' && mineru-models-download -s huggingface -m all
ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec \"$@\"", "--"]

中国版 Dockerfile

FROM docker.m.daocloud.io/lmsysorg/sglang:v0.4.9.post6-cu126
RUN apt-get update && apt-get install -y fonts-noto-cjk libgl1
RUN pip install -U 'mineru[core]' -i https://mirrors.aliyun.com/pypi/simple && mineru-models-download -s modelscope -m all
ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec \"$@\"", "--"]

4. 启动服务

运行以下命令启动服务：

docker-compose -f docker/compose.yaml up -d

5. 验证服务

• sglang-server：访问 http://localhost:30000/health，返回 200 表示服务正常。
• mineru-api：访问 http://localhost:8000/docs 查看 API 文档。
• mineru-gradio：访问 http://localhost:7860 使用 WebUI。

6. 性能优化

• 多 GPU 支持：通过 --dp-size 和 --tp-size 参数启用多 GPU 并行。
• 显存优化：通过 --mem-fraction-static 调整显存占用比例。

7. 常见问题

• 显存不足：降低 --mem-fraction-static 值（如 0.4）。
• 模型下载失败：检查网络或手动下载模型后挂载到容器中。

通过以上步骤，您可以快速完成 MinerU 的 Docker 部署并开始使用。

本地安装步骤

MinerU 提供了多种本地安装方式，包括通过 pip 安装 Python 包、从源码构建以及使用 Docker 容器化部署。以下将详细介绍每种安装方式的具体步骤。

1. 通过 pip 安装

MinerU 的 Python 包已发布到 PyPI，您可以通过以下命令直接安装：

pip install mineru

安装完成后，您可以通过以下命令验证安装是否成功：

mineru --version

如果输出版本号，则表示安装成功。

依赖说明

• Python 版本要求：3.10 及以上。
• 推荐使用虚拟环境（如 venv 或 conda）以避免依赖冲突。

2. 从源码安装

如果您希望从源码构建 MinerU，可以按照以下步骤操作：

1. 克隆仓库：

git clone https://gitcode.com/OpenDataLab/MinerU.git
cd MinerU

2. 安装依赖：

pip install -r docs/requirements.txt

3. 安装 MinerU：

pip install -e .

源码安装注意事项

• 确保您的系统已安装 git 和 pip。
• 如果需要 GPU 支持，请确保已安装对应版本的 CUDA 和 cuDNN。

3. 模型下载

MinerU 依赖多个预训练模型，安装完成后需要下载这些模型。您可以通过以下命令下载默认模型：

mineru --download-models

模型下载选项

• --model-source：指定模型下载源（默认为 huggingface）。
• --model-type：指定下载的模型类型（如 pipeline 或 vlm）。

4. 验证安装

安装完成后，您可以通过运行以下命令验证 MinerU 是否正常工作：

mineru -p demo/pdfs/demo1.pdf -o output

如果命令执行成功，您将在 output 目录下看到解析结果。

5. 常见问题

依赖冲突

如果安装过程中出现依赖冲突，可以尝试以下方法：

• 使用虚拟环境隔离依赖。
• 手动安装兼容版本的依赖包。

模型下载失败

如果模型下载失败，可以尝试：

• 检查网络连接。
• 使用 --model-source 参数切换下载源。

GPU 支持

如果您的设备支持 GPU，可以通过以下命令启用 GPU 加速：

mineru --device cuda

确保已安装对应版本的 CUDA 和 cuDNN。

6. 总结

通过以上步骤，您可以顺利完成 MinerU 的本地安装。无论是通过 pip 安装还是从源码构建，MinerU 都提供了灵活的部署方式。安装完成后，您可以通过命令行工具或 API 快速开始文档解析任务。

常见问题与解决方案

在部署和使用 OpenDataLab/MinerU 时，可能会遇到一些常见问题。以下是这些问题及其解决方案的详细说明，帮助您快速解决问题并顺利使用 MinerU。

---

1. 安装依赖冲突问题

问题描述：
在安装 MinerU 时，可能会因为 Python 版本或第三方依赖项的冲突导致安装失败。

解决方案：

• 确保您的 Python 版本在 3.10~3.12 范围内。
• 使用虚拟环境隔离依赖项：

  python -m venv mineru_env
  source mineru_env/bin/activate
  pip install mineru
  

• 如果仍然遇到冲突，可以尝试手动安装依赖项：

  pip install --upgrade pip
  pip install torch==2.6.0 transformers==4.54.1 sglang==0.4.9.post6
  

---

2. Docker 容器启动失败

问题描述：
在使用 Docker 启动 MinerU 时，可能会因为 GPU 驱动或 CUDA 版本不兼容导致容器启动失败。

解决方案：

• 检查 GPU 驱动是否支持 CUDA 12.6 或更高版本：

  nvidia-smi
  

• 如果使用的是 Blackwell 平台，请确保 CUDA 版本为 12.8 或更高。
• 修改 Dockerfile 中的基础镜像为适配的版本：

  FROM lmsysorg/sglang:v0.4.9.post6-cu128-b200
  

---

3. 显存不足问题

问题描述：
在使用 vlm-sglang-engine 后端时，可能会因为显存不足导致推理失败。

解决方案：

• 确保显卡显存至少为 8GB。
• 关闭其他占用显存的服务或程序。
• 降低推理时的批处理大小：

  mineru -p input.pdf -o output.json -b vlm-sglang-engine --batch_size 1
  

---

4. 模型下载失败

问题描述：
在首次运行时，MinerU 会自动下载模型文件，但可能会因为网络问题导致下载失败。

解决方案：

• 检查网络连接，确保能够访问模型存储服务器。
• 手动下载模型文件并放置到指定目录：

  wget https://models.opendatalab.com/mineru/vlm-model.tar.gz
  tar -xzvf vlm-model.tar.gz -C ~/.mineru/models
  

---

5. 解析结果不准确

问题描述：
在某些文档中，解析结果可能出现文本块丢失或表格识别不准确的情况。

解决方案：

• 确保文档的分辨率适中（推荐长边为 2000 像素左右）。
• 尝试切换 OCR 模型：

  mineru -p input.pdf -o output.json --lang ch_server
  

• 如果问题仍然存在，可以提交 Issue 并提供相关 PDF 文件以便开发者复现问题。

---

6. 服务端口冲突

问题描述：
在启动 sglang-server 或 gradio 服务时，可能会因为端口被占用导致服务启动失败。

解决方案：

• 检查端口占用情况：

  netstat -tulnp | grep 30000
  

• 修改 compose.yaml 文件中的端口映射：

  ports:
    - "30001:30000"
    - "7861:7860"
    - "8001:8000"
  

---

7. 中文文档解析异常

问题描述：
在解析中文文档时，可能会出现乱码或文本块顺序错误。

解决方案：

• 确保系统已安装中文字体：

  sudo apt-get install fonts-wqy-zenhei
  

• 检查文档编码是否为 UTF-8。
• 如果问题仍然存在，可以尝试使用 PP-OCRv5 模型：

  mineru -p input.pdf -o output.json --lang ch_server
  

---

8. 离线部署问题

问题描述：
在无网络环境中部署 MinerU 时，可能会因为无法下载模型或依赖项导致失败。

解决方案：

• 提前在有网络的环境中下载所有模型文件：

  mineru --download-models all
  

• 将模型文件打包并复制到离线环境中：

  tar -czvf mineru-models.tar.gz ~/.mineru/models
  

---

通过以上解决方案，您可以快速解决 MinerU 在部署和使用过程中遇到的常见问题。如果问题仍未解决，可以参考官方文档或加入社区寻求帮助。

本文全面梳理了OpenDataLab/MinerU的部署流程和技术要点，从系统环境验证到具体安装实施，再到问题排查，形成了完整的部署知识体系。通过遵循文档中的硬件要求、配置建议和优化方案，用户可以高效完成MinerU的部署并充分发挥其文档解析能力。对于特殊场景需求，文中提供的多GPU支持、离线部署等方案也展现了工具的灵活性和扩展性。