jianjungki/mineru

MinerU Docker镜像 技术文档

1. 镜像概述和主要用途

1.1 镜像概述

!MinerU Logo

MinerU是一款专注于将PDF转换为机器可读格式（如markdown、JSON）的工具，诞生于https://github.com/InternLM/InternLM%E7%9A%84%E9%A2%84%E8%AE%AD%E7%BB%83%E8%BF%87%E7%A8%8B%EF%BC%8C%E8%87%B4%E5%8A%9B%E4%BA%8E%E8%A7%A3%E5%86%B3%E7%A7%91%E6%8A%80%E6%96%87%E7%8C%AE%E4%B8%AD%E7%9A%84%E7%AC%A6%E5%8F%B7%E8%BD%AC%E6%8D%A2%E9%97%AE%E9%A2%98%E3%80%82%E6%9C%ACDocker%E9%95%9C%E5%83%8F%E5%B0%81%E8%A3%85%E4%BA%86MinerU%E7%9A%84%E5%AE%8C%E6%95%B4%E8%BF%90%E8%A1%8C%E7%8E%AF%E5%A2%83%EF%BC%8C%E5%8C%85%E5%90%ABwebui%E3%80%81API%E6%9C%8D%E5%8A%A1%E5%8F%8Avllm%E6%8E%A8%E7%90%86%E5%8A%A0%E9%80%9F%E6%A1%86%E6%9E%B6%EF%BC%8C%E5%8F%AF%E5%BF%AB%E9%80%9F%E9%83%A8%E7%BD%B2%E5%B9%B6%E8%A7%A3%E5%86%B3%E7%8E%AF%E5%A2%83%E5%85%BC%E5%AE%B9%E9%97%AE%E9%A2%98%EF%BC%8C%E7%A1%AE%E4%BF%9D%E5%9C%A8%E4%B8%8D%E5%90%8C%E5%B9%B3%E5%8F%B0%E4%B8%8A%E6%8F%90%E4%BE%9B%E4%B8%80%E8%87%B4%E7%9A%84%E8%BF%90%E8%A1%8C%E4%BD%93%E9%AA%8C%E3%80%82

1.2 主要用途

• 将PDF文档（包括扫描版、图片型文档）转换为结构化的机器可读格式（markdown、JSON等）
• 通过WebUI（Gradio）进行可视化操作，方便非技术用户使用
• 提供API接口，支持集成到自动化工作流或第三方系统
• 利用vllm框架加速VLM模型推理，提升PDF转换效率

2. 核心功能和特性

2.1 核心功能

• 文档转换：支持PDF到markdown、JSON等格式的转换，保留文档结构和符号信息
• 多服务支持：集成API服务、Gradio WebUI、vllm推理服务器，满足不同使用场景
• OCR能力：可选启用OCR功能，处理扫描版或图片型文档
• 批量处理：支持同时处理多个文档，提升效率

2.2 关键特性

• 环境一致性：Docker容器化确保在Linux、Windows、macOS等平台上运行环境一致
• 简化部署：无需手动配置依赖，一键启动完整服务
• 加速支持：集成vllm框架，支持Turing及以后架构GPU加速（需显存≥8G）
• 资源隔离：与宿主机其他服务隔离，避免依赖冲突
• 跨平台兼容：支持CPU纯环境运行，也可利用GPU/CUDA/NPU/MPS加速

3. 使用场景和适用范围

3.1 典型使用场景

• 个人用户：通过Gradio WebUI可视化转换PDF文档，快速获取结构化内容
• 开发者集成：调用API接口将PDF转换功能嵌入自有应用或工作流
• 批量处理需求：针对大量学术论文、报告等PDF文件进行批量转换和结构化存储
• 离线环境部署：在无网络或隐私敏感场景中，通过本地部署处理文档

3.2 适用范围

• 用户群体：研究人员、开发者、需要处理PDF文档的个人或企业用户
• 环境要求：支持Docker的设备，若使用GPU加速需满足CUDA 12.8+及显卡架构要求
• 应用场景：学术文献处理、文档结构化存储、自动化办公流程集成

4. 使用方法和配置说明

4.1 基础使用（Docker Run）

4.1.1 直接运行官方镜像

bash
docker run --rm -it -p 3000:3000 -p 7860:7860 --gpus=all jianjungki/mineru:latest

• 参数说明：
  • --rm：容器退出后自动清理
  • -it：启用交互式终端
  • -p 3000:3000 -p 7860:7860：映射服务端口（3000用于vllm-server，7860用于Gradio WebUI）
  • --gpus=all：允许容器访问GPU（如需vllm加速）

4.1.2 手动构建并运行镜像

bash
# 克隆仓库
git clone https://github.com/jianjungki/MinerU
cd MinerU
# 构建镜像
docker build -t mineru:latest .
# 启动容器
docker run -p 8001:8001 --env-file .env mineru:latest

• 参数说明：
  • --env-file .env：通过环境变量文件配置API密钥等参数
  • -p 8001:8001：映射MCP-Server服务端口

4.2 Docker Compose 配置示例

yaml
version: '3'
services:
  mineru:
    image: jianjungki/mineru:latest
    ports:
      - "30000:30000"  # vllm-server端口
      - "7860:7860"    # Gradio WebUI端口
      - "8000:8000"    # API服务端口
    shm_size: "32g"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: /bin/bash

4.2.1 启动特定服务

启动Web API服务：

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

访问http://<server_ip>:8000/docs查看API文档

启动Gradio WebUI：

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

访问http://<server_ip>:7860使用WebUI，http://<server_ip>:7860/?view=api调用Gradio API

启动vllm-server：

bash
docker compose -f compose.yaml --profile vllm-server up -d

通过客户端连接：mineru -p <input_path> -o <output_path> -b vlm-http-client -u http://<server_ip>:30000

4.3 核心配置参数

通过环境变量或命令行参数配置服务，常用参数如下：

4.4 数据持久化

为保留转换结果，建议挂载输出目录：

bash
docker run -p 8001:8001 --env-file .env \
  -v $(pwd)/downloads:/app/downloads \
  jianjungki/mineru:latest

• 挂载$(pwd)/downloads到容器/app/downloads，用于持久化存储转换后的文件

5. 参考链接

• MinerU GitHub仓库：https://github.com/jianjungki/MinerU
• Docker Hub镜像地址：https://hub.docker.com/r/jianjungki/mineru
• 官方文档：[***]
• 快速开始指南：[***]