MinerU Docker 部署指南：PDF 结构化解析服务实践

关注

原创最新推荐文章于 2026-10-16 12:15:55 发布 1.7k 阅读 AI 写同款· GEO 优化 ›

【MinerU技术原理深度解析】大模型时代的文档解析革命在AI技术快速发展的今天，大量非结构化数据的处理成为亟待解决的问题。尤其是PDF文档，作为最常见的文件格式之一，如何高效准确地提取其中的信息，成为了许多企业和研究机构的痛点。上海人工智能实验室（上海AI实验室）大模型数据基座OpenDataLab团队开源了全新的智能数据提取工具——MinerU，旨在解决这一问题。MinerU能够将混合了图片、公式、表格、脚注等复杂元素的PDF文档转化为Markdown和JSON格式，大幅提升了AI语料的准备效率。阅读详情

概述

MinerU 是一款面向开发者与科研用户的 PDF 结构化解析工具，专注于将 PDF 文档高质量地转换为机器可读格式（如 Markdown、JSON 等），以便于后续的检索、分析与二次加工。MinerU 起源于「书生·浦语」大模型预训练过程，核心目标是解决科技文献中复杂版式、符号与公式的高质量解析问题，在大模型时代为科研与工程应用提供可靠的数据基础。

随着 2.7.0 版本的发布，MinerU 在解析架构和易用性方面进行了重要升级，引入了全新的 hybrid 后端，融合了 pipeline 与 VLM 两类后端的优势，在保证解析精度的同时显著提升了扩展性与稳定性。该后端在文本型 PDF 场景下可直接抽取原生文本，天然支持多语言并有效降低解析幻觉；在扫描版 PDF 场景下，则支持多达 109 种语言的 OCR 识别，并提供独立的行内公式识别开关，以适配不同视觉与结构需求。

在推理加速与部署层面，MinerU 提供了多种后端与引擎组合（pipeline / VLM / hybrid），并支持通过 *-auto-engine 模式自动选择适合当前运行环境的推理引擎，显著降低了使用与部署门槛。默认解析后端已切换为 hybrid-auto-engine，为新用户提供更加一致、开箱即用的解析体验。

本指南将以 Docker 容器化部署 为核心，详细介绍 MinerU 在 vLLM 等加速后端场景下的部署方式，包括环境准备、镜像拉取、服务启动、功能验证以及生产环境配置建议，帮助用户快速构建稳定、可复现的 MinerU 文档解析服务。

环境准备

系统要求

部署 MinerU 容器化应用前，请确保您的系统满足以下基本要求：

操作系统：Linux (Ubuntu 20.04+/CentOS 7+)、macOS 10.15+ 或 Windows 10+（建议使用 WSL2）
硬件配置：至少 2 CPU 核心、4GB 内存；如使用 GPU 加速功能，需配备 NVIDIA GPU 及相应驱动
网络环境：能够访问互联网以拉取 Docker 镜像和相关依赖
权限要求：具有 sudo 或 root 权限以安装 Docker 和管理容器

Docker 环境安装

推荐使用以下一键脚本安装 Docker 环境，该脚本会自动安装 Docker Engine、Docker CLI、Docker Compose 等必要组件：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

安装完成后，建议将当前用户添加到 docker 用户组以避免每次使用 Docker 命令都需要 sudo 权限：

sudo usermod -aG docker $USER

⚠️ 注意：添加用户组后需要注销并重新登录才能生效

验证 Docker 是否安装成功：

docker --version
docker compose version

若命令输出 Docker 版本信息，则说明安装成功。

GPU 运行环境（可选）

如需启用 GPU 加速，请确保系统已正确安装：

NVIDIA GPU 驱动
NVIDIA Container Toolkit（nvidia-docker）

验证 GPU 是否可被 Docker 识别：

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

如能正常输出 GPU 信息，则说明 GPU 容器环境配置成功。

镜像准备

拉取 MinerU 镜像

使用以下命令通过轩辕镜像访问支持域名拉取最新版本的 MinerU 镜像：

docker pull xxx.xuanyuan.run/alexsuntop/mineru:latest

验证镜像是否拉取成功：

docker images | grep mineru

若输出包含 xxx.xuanyuan.run/alexsuntop/mineru:latest 则说明镜像拉取成功。

查看可用镜像标签

如需指定特定版本的 MinerU 镜像，可访问 MinerU 镜像标签列表（轩辕）查看所有可用标签。拉取特定版本镜像的命令格式为：

docker pull xxx.xuanyuan.run/alexsuntop/mineru:{TAG}

将 {TAG} 替换为实际标签名称，例如拉取 1.0.0 版本：

docker pull xxx.xuanyuan.run/alexsuntop/mineru:1.0.0

🚀 5 分钟快速启动（推荐）

如果您希望最快体验 MinerU 的 vLLM 后端服务，可使用以下最小化启动命令（GPU 环境推荐）：

docker run -d \
  --name mineru-vllm \
  --restart unless-stopped \
  --gpus all \
  --ipc host \
  -p 30000:30000 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  --host 0.0.0.0 \
  --port 30000

启动完成后，使用以下命令验证服务是否正常：

curl http://localhost:30000/health

返回 HTTP 200 即表示服务正常运行。

⚠️ 提示

如未安装 NVIDIA Container Toolkit，请先完成 GPU 运行环境配置
若仅使用 CPU，可移除 --gpus all 参数

容器部署

MinerU 提供三种主要服务模式，可根据实际需求选择部署：vLLM 后端服务、API 服务和 Gradio WebUI。以下分别介绍这三种服务的部署方法。

1. vLLM 后端服务部署

vLLM 后端服务是 MinerU 的核心组件，提供高性能的文档解析与处理能力。使用以下命令部署 vLLM 后端服务：

docker run -d \
  --name mineru-vllm-server \
  --restart unless-stopped \
  --ipc host \
  -p 30000:30000 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  --host 0.0.0.0 \
  --port 30000

命令参数说明：

-d: 后台运行容器
--name mineru-vllm-server: 指定容器名称为 mineru-vllm-server
--restart unless-stopped: 除非手动停止，否则容器总是自动重启
--ipc host: 使用主机的 IPC 命名空间，提高共享内存性能
-p 30000:30000: 将容器的 30000 端口映射到主机的 30000 端口
-e MINERU_MODEL_SOURCE=local: 设置模型来源为本地
--ulimit memlock=-1: 禁用内存锁定限制
--ulimit stack=67108864: 设置栈大小限制为 64MB

⚠️ GPU 说明
若需启用 GPU，请在 docker run 命令中添加 --gpus all 参数；
若未启用 GPU，相关显存与并行参数将不会生效。

对于多 GPU 环境，可添加 --data-parallel-size 参数以提高吞吐量：

docker run -d \
  --name mineru-vllm-server \
  --restart unless-stopped \
  --ipc host \
  -p 30000:30000 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  --host 0.0.0.0 \
  --port 30000 \
  --data-parallel-size 2

若在单 GPU 环境中遇到显存不足问题，可通过 --gpu-memory-utilization 参数调整显存利用率（取值范围 0-1）：

docker run -d \
  --name mineru-vllm-server \
  --restart unless-stopped \
  --ipc host \
  -p 30000:30000 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  --host 0.0.0.0 \
  --port 30000 \
  --gpu-memory-utilization 0.5

2. API 服务部署

API 服务提供 RESTful 接口，方便其他应用程序集成 MinerU 的文档处理能力。使用以下命令部署 API 服务：

docker run -d \
  --name mineru-api \
  --restart unless-stopped \
  --ipc host \
  -p 8000:8000 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-api \
  --host 0.0.0.0 \
  --port 8000

同样，可根据 GPU 配置添加相应参数：

docker run -d \
  --name mineru-api \
  --restart unless-stopped \
  --ipc host \
  -p 8000:8000 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-api \
  --host 0.0.0.0 \
  --port 8000 \
  --data-parallel-size 2 \
  --gpu-memory-utilization 0.5

3. Gradio WebUI 部署

Gradio WebUI 提供直观的图形界面，适合非技术用户使用 MinerU 的功能。使用以下命令部署 Gradio WebUI：

docker run -d \
  --name mineru-gradio \
  --restart unless-stopped \
  --ipc host \
  -p 7860:7860 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-gradio \
  --server-name 0.0.0.0 \
  --server-port 7860 \
  --enable-vllm-engine true

可根据需要添加其他参数，如限制转换页数：

docker run -d \
  --name mineru-gradio \
  --restart unless-stopped \
  --ipc host \
  -p 7860:7860 \
  -e MINERU_MODEL_SOURCE=local \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-gradio \
  --server-name 0.0.0.0 \
  --server-port 7860 \
  --enable-vllm-engine true \
  --max-convert-pages 20 \
  --gpu-memory-utilization 0.5

Docker Compose 部署（生产推荐）

对于生产环境，推荐使用 Docker Compose 管理多个服务。创建 docker-compose.yml 文件：

⚠️ Docker Compose 资源限制说明
deploy.resources 仅在 Docker Swarm 或 Kubernetes 环境中生效。
普通 Docker Compose（docker compose up）请使用以下方式限制资源。

version: '3.8'

x-default: &default
  restart: unless-stopped
  volumes:
    - /etc/localtime:/etc/localtime:ro
    - /etc/timezone:/etc/timezone:ro
  logging:
    driver: json-file
    options:
      max-size: 100m

x-mineru-vllm: &mineru-vllm
  <<: *default
  image: xxx.xuanyuan.run/alexsuntop/mineru:latest
  environment:
    MINERU_MODEL_SOURCE: local
  ulimits:
    memlock: -1
    stack: 67108864
  ipc: host
  # 普通 Docker Compose 资源限制（非 Swarm 模式）
  cpus: 4
  mem_limit: 16g

services:
  mineru-vllm-server:
    <<: *mineru-vllm
    container_name: mineru-vllm-server
    profiles: ["vllm-server"]
    ports:
      - 30000:30000
    entrypoint: mineru-vllm-server
    command:
      --host 0.0.0.0
      --port 30000
      # --data-parallel-size 2  # 多GPU环境下可启用
      # --gpu-memory-utilization 0.5  # 显存不足时可调整

  mineru-api:
    <<: *mineru-vllm
    container_name: mineru-api
    profiles: ["api"]
    ports:
      - 8000:8000
    entrypoint: mineru-api
    command:
      --host 0.0.0.0
      --port 8000
      # --data-parallel-size 2  # 多GPU环境下可启用
      # --gpu-memory-utilization 0.5  # 显存不足时可调整

  mineru-gradio:
    <<: *mineru-vllm
    container_name: mineru-gradio
    profiles: ["gradio"]
    ports:
      - 7860:7860
    entrypoint: mineru-gradio
    command:
      --server-name 0.0.0.0
      --server-port 7860
      --enable-vllm-engine true
      # --max-convert-pages 20  # 限制转换页数
      # --gpu-memory-utilization 0.5  # 显存不足时可调整

根据需要部署不同服务：

# 部署 vLLM 后端服务
docker compose --profile vllm-server up -d

# 部署 API 服务
docker compose --profile api up -d

# 部署 Gradio WebUI
docker compose --profile gradio up -d

# 部署所有服务
docker compose --profile vllm-server --profile api --profile gradio up -d

功能测试

验证容器状态

部署完成后，首先检查容器是否正常运行：

# 查看单个容器状态
docker ps --filter "name=mineru-vllm-server"
docker ps --filter "name=mineru-api"
docker ps --filter "name=mineru-gradio"

# 或使用 docker compose 查看
docker compose ps

正常运行的容器状态应为 "Up"。若状态异常，可通过日志排查问题：

docker logs mineru-vllm-server
docker logs mineru-api
docker logs mineru-gradio

测试 vLLM 后端服务

vLLM 后端服务提供健康检查接口，可通过以下命令测试：

curl -f http://localhost:30000/health || echo "服务未正常运行"

若返回状态码 200，则说明服务正常运行。

官方提供了专门的测试工具，可通过以下步骤进行更全面的测试：

安装 mineru 客户端：

pip install mineru

准备测试文档（如 demo.pdf），执行测试命令：

mineru -p demo.pdf -o ./output -b vlm-http-client -u http://localhost:30000

查看输出目录 ./output，若生成解析结果文件，则说明 vLLM 后端服务工作正常。

测试 API 服务

API 服务部署后，可通过 curl 或浏览器访问以下地址测试：

curl http://localhost:8000/health

若返回健康状态信息，则说明 API 服务正常运行。

测试 Gradio WebUI

Gradio WebUI 部署后，可通过浏览器访问以下地址：

http://localhost:7860

若能正常打开 MinerU 的 Web 界面，则说明 Gradio 服务部署成功。您可以上传测试文档并尝试解析功能，验证系统是否正常工作。

生产环境建议

硬件资源配置

MinerU 的性能很大程度上取决于硬件配置，特别是在处理大型文档或启用 AI 增强功能时。生产环境建议配置：

CPU：至少 4 核心，推荐 8 核心或更高
内存：至少 8GB，推荐 16GB 或更高
存储：至少 20GB 可用空间，推荐使用 SSD 以提高性能
GPU：如使用 AI 相关功能，推荐配备 NVIDIA GPU（至少 8GB 显存）

可根据实际负载情况调整资源配置。对于 Docker Swarm 或 Kubernetes 环境，可使用以下配置：

deploy:
  resources:
    limits:
      cpus: '8.0'
      memory: 16G
    reservations:
      cpus: '4.0'
      memory: 8G

对于普通 Docker Compose 环境，请使用以下方式：

services:
  mineru-vllm-server:
    image: xxx.xuanyuan.run/alexsuntop/mineru:latest
    cpus: 4
    mem_limit: 16g

数据持久化

为确保数据安全，建议将关键数据目录挂载到主机：

# 为 vLLM 服务添加数据持久化
docker run -d \
  --name mineru-vllm-server \
  # 其他参数...
  -v /path/on/host/models:/app/models \
  -v /path/on/host/cache:/app/cache \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  # 其他参数...
  --model-path /app/models

对于 Docker Compose 部署，可在 docker-compose.yml 中添加卷挂载配置：

services:
  mineru-vllm-server:
    <<: *mineru-vllm
    # 其他配置...
    volumes:
      - /path/on/host/models:/app/models
      - /path/on/host/cache:/app/cache
    # 其他配置...

安全配置

生产环境中，建议采取以下安全措施：

使用非 root 用户运行容器：在 Dockerfile 或运行时指定用户
限制容器权限：使用 --cap-drop=ALL 移除不必要的内核能力
设置资源限制：防止容器过度消耗资源
使用环境变量管理敏感信息：避免在命令行或配置文件中硬编码密码等敏感信息
启用 TLS/SSL：为 API 和 WebUI 服务配置 HTTPS

示例安全增强的运行命令：

docker run -d \
  --name mineru-vllm-server \
  --restart unless-stopped \
  --ipc host \
  -p 30000:30000 \
  -e MINERU_MODEL_SOURCE=local \
  -e MINERU_API_KEY=your_secure_api_key \
  --user 1000:1000 \
  --cap-drop=ALL \
  --cap-add=IPC_LOCK \
  --security-opt no-new-privileges \
  --memory=16g \
  --cpus=4 \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  -v /path/on/host/models:/app/models \
  -v /path/on/host/cache:/app/cache \
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  --host 0.0.0.0 \
  --port 30000

说明：
vLLM / PyTorch 在部分场景下需要 IPC_LOCK 能力以支持高性能共享内存。

监控与日志

为确保服务稳定运行，建议配置监控和日志收集：

容器健康检查：

docker run -d \
  --name mineru-vllm-server \
  # 其他参数...
  --health-cmd "curl -f http://localhost:30000/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  --health-start-period 60s \
  # 其他参数...

集中式日志管理：可考虑使用 ELK Stack、Graylog 或 Loki 等工具收集和分析日志
性能监控：可使用 Prometheus + Grafana 监控容器资源使用情况和应用性能指标

高可用部署

对于关键业务场景，建议部署多实例并配置负载均衡，以提高系统可用性：

多实例部署：部署多个 MinerU 实例，避免单点故障
负载均衡：使用 Nginx 或云服务提供商的负载均衡服务分发流量
自动扩缩容：在 Kubernetes 环境中，可配置 HPA (Horizontal Pod Autoscaler) 实现自动扩缩容

故障排查

常见问题及解决方法

容器无法启动

若容器无法启动，首先查看容器日志：

docker logs mineru-vllm-server

常见原因及解决方法：

端口冲突：
- 错误信息：Bind for 0.0.0.0:30000 failed: port is already allocated
- 解决方法：更换主机端口或停止占用端口的其他服务

# 更换主机端口
docker run -d \
  --name mineru-vllm-server \
  -p 30001:30000 \  # 将主机端口改为 30001
  # 其他参数不变...

资源不足：
- 错误信息：no resources available to schedule container 或内存溢出相关错误
- 解决方法：增加系统资源或调整容器资源限制
权限问题：
- 错误信息：permission denied
- 解决方法：检查挂载目录权限或调整运行用户

服务响应缓慢

资源瓶颈：
- 检查容器资源使用情况：docker stats mineru-vllm-server
- 解决方法：增加资源配额或优化应用配置
GPU 相关问题：
- 若使用 GPU 功能，检查 GPU 驱动和 CUDA 版本是否兼容
- 解决方法：更新 GPU 驱动或调整 --gpu-memory-utilization 参数

# 降低 GPU 内存利用率
docker run -d \
  --name mineru-vllm-server \
  # 其他参数...
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-vllm-server \
  --host 0.0.0.0 \
  --port 30000 \
  --gpu-memory-utilization 0.4  # 降低至 0.4 或更低

文档解析失败

文件格式不支持：
- 解决方法：检查文档格式是否在支持列表中，转换为支持的格式重试
文件过大：
- 解决方法：拆分大型文档或调整配置以支持更大文件

# 增加最大转换页数限制
docker run -d \
  --name mineru-gradio \
  # 其他参数...
  xxx.xuanyuan.run/alexsuntop/mineru:latest \
  mineru-gradio \
  # 其他参数...
  --max-convert-pages 50  # 增加最大转换页数

日志查看与分析

MinerU 容器日志包含详细的运行信息，是排查问题的重要依据：

# 查看最新日志
docker logs mineru-vllm-server

# 实时查看日志
docker logs mineru-vllm-server -f

# 查看特定数量的日志
docker logs mineru-vllm-server --tail 100

# 查看指定时间段的日志
docker logs mineru-vllm-server --since 2023-11-01T00:00:00 --until 2023-11-02T00:00:00

对于 Docker Compose 部署：

# 查看所有服务日志
docker compose logs

# 查看特定服务日志
docker compose logs mineru-vllm-server

# 实时查看特定服务日志
docker compose logs -f mineru-vllm-server

镜像文档参考

若遇到其他问题，可参考 MinerU 镜像文档（轩辕）获取更多信息。

参考资源

官方文档

Docker 相关资源

vLLM 相关资源

Gradio 相关资源

Gradio 官方文档

总结

本文详细介绍了 MinerU 的 Docker 容器化部署方案，包括环境准备、镜像拉取、容器部署、功能测试、生产环境配置及故障排查等内容。通过容器化部署，用户可以快速搭建 MinerU 服务，充分利用其提供的 vLLM 后端服务、API 服务和 Gradio WebUI 等功能。

关键要点：

使用一键脚本可快速部署 Docker 环境，简化前期准备工作
轩辕镜像访问支持可改善镜像访问体验，镜像来源于官方公共仓库
MinerU 提供三种服务模式（vLLM 后端、API 和 Gradio WebUI），可根据需求选择部署
生产环境中应注意资源配置、数据持久化、安全加固和监控等关键环节
Docker Compose 是管理多服务部署的推荐方式，可简化复杂部署流程
遇到问题时，容器日志是排查故障的重要依据

后续建议：

深入学习 MinerU 高级特性，如自定义模型配置、批量处理优化等
根据业务需求调整资源配置参数，平衡性能与成本
建立完善的监控告警机制，及时发现并解决潜在问题
定期更新 MinerU 镜像，获取最新功能和安全修复
考虑在 Kubernetes 环境中部署，以获得更强大的编排和管理能力

通过本文提供的指南，相信您已能够顺利部署和使用 MinerU 容器化应用。如遇其他问题，建议参考官方文档或社区资源获取帮助。

收录于

docker

教程

docker镜像源

标签

#docker #pdf #容器 #MinerU #MinerU部署

MinerU教程第二弹丨MinerU 本地部署保姆级“喂饭”教程本文为MinerU的本地部署指南，MinerU是一款由上海人工智能实验室OpenDataLab团队开发的开源PDF转Markdown工具，适用于RAG、LLM语料准备等场景。文章详细介绍了MinerU的功能特性，包括文档处理、格式转换和运行环境支持。接着，提供了系统要求和基础环境配置的说明，并逐步指导用户完成Conda环境的创建、模型文件的下载以及GPU加速的配置。此外，文章还涵盖了功能测试、批量PDF转换、本地API服务的搭建和卸载MinerU的步骤。对于不熟悉代码或硬件条件有限的用户，推荐使用官方提供的阅读详情