MinerU Docker 部署指南（RAG 场景）

本文面向 RAG 系统开发者，介绍为何 MinerU 是理想的文档解析引擎，并重点讲解 Docker 部署中的关键配置改动（特别是 CUDA 版本适配问题）。本文仅涵盖安装部署，不涉及 RAG 使用细节。

一、为什么 RAG 需要 MinerU？

在 RAG（检索增强生成）系统中，文档解析的质量直接决定了整个系统的性能天花板。如果解析环节出错，后续的文本分块、向量检索和模型生成都难以补救。

RAG 文档解析的三大痛点

MinerU 的核心优势

MinerU 专为 RAG 场景设计，扮演 "结构化抽取层" 的角色：

• 高精度：MinerU 2.5 仅以 12 亿参数，在权威测试中超越 GPT-4o、Qwen2.5-VL-72B，PDF 转 Markdown 准确率提升至 92%，RAG Top-1 召回率提升 25%。

• 深度结构化：精准识别并还原文档的层级结构、表格、公式、列表，输出 Markdown 或元素级 JSON，为分块提供天然语义边界。

• 高效率：解析速度可达 200 页/分钟，在消费级显卡（RTX 4090）上达 1.7 页/秒。

• 多格式支持：支持 PDF、DOCX、PPTX、XLSX、图片等，可无缝集成 LangChain、LlamaIndex、Dify、RAGFlow 等框架。

二、环境准备

硬件要求

软件要求

• Docker Desktop 20.10+（Windows 需启用 WSL2）
• NVIDIA 驱动：支持 CUDA 12.9+（推荐 560.x 或更高版本）
• NVIDIA Container Toolkit：让容器能访问 GPU

三、获取源码与构建镜像（含关键改动）

3.1 克隆项目

git clone https://github.com/opendatalab/MinerU.git
cd MinerU/docker

3.2 选择 Dockerfile（国内环境推荐）

进入国内优化目录：

cd china

🔥 关键改动 1：修改基础镜像的 CUDA 版本

docker/china/Dockerfile 默认使用 vllm/vllm-openai:v0.21.0（基于 CUDA 13.0）。如果你的驱动不支持 CUDA 13.0（或遇到 cuda>=13.0 报错），必须切换到 v0.21.0-cu129 版本（CUDA 12.9）：

# 注释掉默认的 CUDA 13.0 版本
# FROM docker.m.daocloud.io/vllm/vllm-openai:v0.21.0

# 启用 CUDA 12.9 兼容版本
FROM docker.m.daocloud.io/vllm/vllm-openai:v0.21.0-cu129

如何确认需要哪个版本：运行 nvidia-smi，查看右上角的 CUDA Version。如果显示为 12.x，建议使用 cu129；如果显示为 13.0，可使用默认版本。

🔥 关键改动 2：优化 APT 源（加速构建）

在 Dockerfile 的 apt-get update 前插入换源命令，避免因海外源缓慢导致构建卡顿：

RUN sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list && \
    sed -i 's/security.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list && \
    apt-get update && \
    apt-get install -y \
        fonts-noto-core \
        fontconfig \
        libgl1 && \
    fc-cache -fv && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

3.3 构建镜像

docker build --network=host -t mineru:cu129 -f Dockerfile .

注意：建议使用自定义标签（如 mineru:cu129）而非 latest，便于区分不同 CUDA 版本。

构建过程约需 20-40 分钟，主要耗时在下载基础镜像和 AI 模型。

四、启动服务（含 GPU 配置改动）

MinerU 的 compose.yaml 定义了 4 种服务模式，通过 --profile 参数按需启动：

4.1 启动 Gradio WebUI（推荐新手）

docker compose -f compose.yaml --profile gradio up -d

访问 http://localhost:7860。

4.2 启动 API 服务（推荐开发者）

docker compose -f compose.yaml --profile api up -d

API 文档：http://localhost:8000/docs

4.3 启动 OpenAI 兼容服务

docker compose -f compose.yaml --profile openai-server up -d

🔥 关键改动 3：为服务添加 GPU 运行时和跳过版本检查

此步至关重要，否则会遇到 cuda>=12.9 或 No CUDA GPUs 等报错。

在 compose.yaml 中，为需要 GPU 的服务（如 mineru-gradio、mineru-api）添加以下配置：

mineru-gradio:
    image: mineru:cu129                     # 使用你构建的镜像标签
    container_name: mineru-gradio
    restart: always
    profiles: ["gradio"]
    ports:
      - 7860:7860
    runtime: nvidia                         # 【必须】启用 NVIDIA 运行时
    environment:
      MINERU_MODEL_SOURCE: local
      NVIDIA_DISABLE_REQUIRE: "true"        # 【必须】跳过 CUDA 版本硬性检查
    entrypoint: mineru-gradio

同理，mineru-api 也需做相同改动：

mineru-api:
    image: mineru:cu129
    container_name: mineru-api
    runtime: nvidia
    environment:
      MINERU_MODEL_SOURCE: local
      NVIDIA_DISABLE_REQUIRE: "true"
    # ... 其他配置

为什么需要 NVIDIA_DISABLE_REQUIRE：即使驱动满足 CUDA 12.9 要求，在某些环境（如 WSL2）中，nvidia-container-toolkit 可能误判版本，导致容器无法启动。设置该变量可绕过检查，让容器正常启动。

4.4 常用管理命令

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f mineru-gradio

# 停止服务
docker compose down

# 进入容器调试
docker exec -it mineru-gradio /bin/bash

五、验证部署

5.1 检查容器状态

docker ps | grep mineru

5.2 验证 GPU 可用性

docker exec -it mineru-gradio nvidia-smi

5.3 验证解析功能（API 模式）

curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@你的文档.pdf" \
  -F "backend=hybrid-engine"

六、常见问题

Q1: 构建镜像时提示 cuda>=13.0 不满足？

解决方案：按 关键改动 1 将基础镜像切换为 v0.21.0-cu129，并重新构建。

Q2: 启动容器时提示 cuda>=12.9 不满足？

解决方案：按 关键改动 3 在 compose.yaml 中添加 runtime: nvidia 和 NVIDIA_DISABLE_REQUIRE: "true"。

Q3: 容器内提示 No CUDA GPUs are available？

检查是否已配置 runtime: nvidia，并确认 Docker Desktop 中已启用 GPU 支持（WSL2 后端需安装 NVIDIA CUDA on WSL 驱动）。

Q4: Docker Desktop 频繁崩溃？

执行 WSL2 重置：

wsl --shutdown
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data

然后重启 Docker Desktop。

Q5: 解析速度慢？

• 确认使用 GPU 模式（CPU 模式慢约 5 倍）
• 使用 hybrid-engine 后端，在 GPU 上比纯 CPU 模式快 8-12 倍

七、参考资源

• GitHub 项目地址：https://github.com/opendatalab/MinerU
• 官方 Docker 部署文档：https://deepwiki.com/opendatalab/MinerU/5.1-docker-deployment
• MinerU 官网：https://mineru.net