MinerU Docker Compose 使用

一、前置条件

硬件要求

项目	要求
GPU	NVIDIA Volta 架构及以上（V100, RTX 20xx/30xx/40xx, A100, H100 等）
显存	8GB+（hybrid/vlm），4GB+（pipeline）
内存	16GB 最低，32GB 推荐
磁盘	20GB 最低，SSD 推荐

软件要求

软件	版本
Docker	20.10+
Docker Compose	V2（docker compose 命令）
NVIDIA Driver	支持 CUDA 12.9.1+
NVIDIA Container Toolkit	已安装

注意：Docker 部署仅支持 Linux 和 Windows WSL2，不支持 macOS。

---

二、构建镜像

Docker Compose 需要 MinerU 的 Docker 镜像，需先构建。

2.1 国内环境（推荐）

cd docker/china
docker build --network=host -t mineru:latest -f Dockerfile .

2.2 国际环境

cd docker/global
docker build --network=host -t mineru:latest -f Dockerfile .

2.3 昇腾 NPU 环境

cd docker/china
docker build --network=host -t mineru:latest -f npu.Dockerfile .

---

三、Compose 文件结构

Compose 文件位于 docker/compose.yaml，定义了 4 个服务：

services:
  mineru-openai-server:    # OpenAI 兼容 API 服务
    profiles: ["openai-server"]
    ports: ["30000:30000"]

  mineru-api:              # FastAPI 解析服务
    profiles: ["api"]
    ports: ["8000:8000"]

  mineru-router:           # 负载均衡路由服务
    profiles: ["router"]
    ports: ["8002:8002"]

  mineru-gradio:           # Gradio Web 界面
    profiles: ["gradio"]
    ports: ["7860:7860"]

关键设计：所有服务都使用 profiles 分组，不会同时启动，需要通过 --profile 指定启动哪个。

---

四、四种服务模式

4.1 服务对比总览

服务	端口	用途	适用场景
openai-server	30000	OpenAI 兼容 API	与 OpenAI SDK 集成、LLM 应用
api	8000	FastAPI 解析服务	程序调用、批量处理
router	8002	多 GPU / 多机负载均衡	多 GPU 服务器、集群部署
gradio	7860	Web 图形界面	可视化操作、演示

4.2 OpenAI 兼容服务（端口 30000）

提供与 OpenAI API 兼容的接口，可用 OpenAI SDK 直接调用：

# 启动
cd docker
docker compose --profile openai-server up -d

# 查看日志
docker compose logs -f mineru-openai-server

# 健康检查
curl http://localhost:30000/health

Python 调用示例：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:30000/v1",
    api_key="none"  # 不需要真实 key
)

# 发送文档解析请求
response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "解析这个文档"}],
    extra_body={"file_url": "http://your-server/doc.pdf"},
)

print(response.choices[0].message.content)

显存不足时调整：

# 修改 compose.yaml 中的 command
command:
  --host 0.0.0.0
  --port 30000
  --gpu-memory-utilization 0.4  # 降低 KV cache 大小

4.3 FastAPI 解析服务（端口 8000）

提供同步和异步两种解析接口：

# 启动
cd docker
docker compose --profile api up -d

# 健康检查
curl http://localhost:8000/health

# 查看 Swagger 文档
# 浏览器访问 http://localhost:8000/docs

调用示例：

# 同步解析（等待完成）
curl -X POST http://localhost:8000/file_parse \
  -F "file=@input.pdf" \
  -F "backend=hybrid-auto-engine" \
  -o result.zip

# 异步解析（提交任务）
curl -X POST http://localhost:8000/tasks \
  -F "file=@input.pdf" \
  -F "backend=hybrid-auto-engine"

# 查询任务状态
curl http://localhost:8000/tasks/{task_id}

# 下载结果
curl http://localhost:8000/tasks/{task_id}/result -o result.zip

并发调优：

# compose.yaml 中添加环境变量
environment:
  MINERU_MODEL_SOURCE: local
  MINERU_API_MAX_CONCURRENT_REQUESTS: 6  # 默认 3，增大可提高并发
  MINERU_API_TASK_RETENTION_SECONDS: 86400  # 任务保留 24 小时

4.4 Router 负载均衡服务（端口 8002）

在多 GPU 或多机环境下自动分发请求：

# 启动（自动检测所有 GPU）
cd docker
docker compose --profile router up -d

# 健康检查（包含所有 worker 状态）
curl http://localhost:8002/health

多 GPU 配置：

# compose.yaml 中修改 deploy 部分
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ["0", "1", "2", "3"]  # 使用 4 块 GPU
          capabilities: [gpu]

连接远程 API 代替本地 Worker：

# compose.yaml 中修改 command
command:
  --host 0.0.0.0
  --port 8002
  --local-gpus none
  --upstream-url http://192.168.1.101:8000
  --upstream-url http://192.168.1.102:8000

Router 客户端调用（与 API 接口完全一致）：

# 通过 Router 调用（Router 自动分发到最空闲的后端）
curl -X POST http://localhost:8002/file_parse \
  -F "file=@input.pdf" \
  -o result.zip

4.5 Gradio Web 界面（端口 7860）

提供可视化 Web 操作界面：

# 启动
cd docker
docker compose --profile gradio up -d

浏览器访问 http://localhost:7860 即可使用。

可选配置：

# compose.yaml 中修改 command
command:
  --server-name 0.0.0.0
  --server-port 7860
  --enable-api false           # 禁用 API 接口
  --max-convert-pages 20       # 限制最大转换页数

---

五、完整配置参数参考

5.1 通用配置

# 所有服务共享的配置
environment:
  MINERU_MODEL_SOURCE: local          # 模型源：local / huggingface / modelscope

# GPU 分配
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ["0"]            # 单 GPU
          # device_ids: ["0", "1"]     # 多 GPU
          capabilities: [gpu]

# 资源限制
ulimits:
  memlock: -1                         # 不限内存锁定
  stack: 67108864                     # 64MB 栈
ipc: host                             # 主机 IPC 命名空间

5.2 API 服务环境变量

environment:
  MINERU_MODEL_SOURCE: local
  # 并发与性能
  MINERU_API_MAX_CONCURRENT_REQUESTS: 3       # 最大并发请求
  MINERU_PROCESSING_WINDOW_SIZE: 64           # Pipeline 每批页数
  MINERU_API_OUTPUT_ROOT: ./output            # 输出目录

  # 任务管理
  MINERU_API_TASK_RETENTION_SECONDS: 86400    # 任务保留（秒）
  MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS: 300  # 清理间隔（秒）

  # 文档与功能
  MINERU_API_ENABLE_FASTAPI_DOCS: 1           # 启用 Swagger UI
  MINERU_FORMULA_ENABLE: true                 # 启用公式识别
  MINERU_TABLE_ENABLE: true                   # 启用表格识别

  # 安全
  MINERU_API_PUBLIC_BIND_EXPOSED: 0           # 公网绑定安全
  MINERU_API_ALLOW_PUBLIC_HTTP_CLIENT: 0      # 允许公网 http-client
  MINERU_API_DISABLE_ACCESS_LOG: 0            # 禁用访问日志

5.3 Router 服务环境变量

environment:
  MINERU_MODEL_SOURCE: local
  MINERU_ROUTER_LOCAL_GPUS: auto              # GPU: auto / none / "0,1,2"
  MINERU_ROUTER_WORKER_HOST: 127.0.0.1        # Worker 监听地址
  MINERU_ROUTER_ENABLE_VLM_PRELOAD: 0         # 预加载 VLM
  MINERU_ROUTER_WORKER_REFRESH_INTERVAL_SECONDS: 2  # 健康检查间隔

5.4 显存调优参数

所有使用 VLM 的服务都可配置：

command:
  --host 0.0.0.0
  --port 8000
  --gpu-memory-utilization 0.5    # vLLM KV cache 占用显存比例
                                   # 0.5 = 50%，显存不足可降至 0.4

---

六、常用操作命令

6.1 服务管理

# 进入 docker 目录
cd docker

# 启动指定服务
docker compose --profile api up -d              # API 服务
docker compose --profile openai-server up -d     # OpenAI 服务
docker compose --profile router up -d            # Router 服务
docker compose --profile gradio up -d            # Gradio 服务

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f mineru-api               # 跟踪日志
docker compose logs --tail 100 mineru-api       # 最近 100 行

# 停止服务
docker compose --profile api down               # 停止并删除容器
docker compose --profile api stop               # 仅停止不删除

# 重启服务
docker compose --profile api restart

6.2 多服务同时启动

# 同时启动 API + Gradio（注意：不能同时启动使用 vLLM 的多个服务）
docker compose --profile api --profile gradio up -d

重要限制：由于 vLLM 会预分配 GPU 显存，同一台机器上不能同时运行多个使用 VLM 的服务（如不能同时运行 api + openai-server）。如果需要多种服务，只能运行其中一个，或使用 Router 聚合远程 API。

6.3 显存不足时的处理

# 方案 1：降低 GPU 显存利用率
command:
  --gpu-memory-utilization 0.4    # 从默认 0.9 降到 0.4

# 方案 2：使用 Pipeline 后端（不需要 VLM）
environment:
  MINERU_MODEL_SOURCE: local
# 在请求参数中指定 backend=pipeline

6.4 多 GPU 指定

# 使用所有 GPU
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ["0", "1", "2", "3"]
          capabilities: [gpu]

# 使用特定 GPU
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ["1"]  # 只用第 2 块 GPU
          capabilities: [gpu]

---

七、典型部署场景

7.1 单机单 GPU（最小部署）

# 构建镜像
cd docker/china && docker build -t mineru:latest -f Dockerfile .

# 启动 API 服务
cd ../ && docker compose --profile api up -d

# 调用
curl -X POST http://localhost:8000/file_parse \
  -F "file=@doc.pdf" -o result.zip

7.2 单机多 GPU（Router 负载均衡）

# compose.yaml 修改 router 的 GPU 配置
mineru-router:
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            device_ids: ["0", "1", "2", "3"]
            capabilities: [gpu]
  command:
    --host 0.0.0.0
    --port 8002
    --local-gpus auto

docker compose --profile router up -d
# Router 自动启动 4 个 worker，总并发 = 4 × 3 = 12

7.3 多机集群（Router + 远程 API）

机器 A（192.168.1.101）：

docker compose --profile api up -d
# API 服务启动在 8000 端口

机器 B（192.168.1.102）：

docker compose --profile api up -d
# API 服务启动在 8000 端口

机器 C（Router 入口）：

mineru-router:
  command:
    --host 0.0.0.0
    --port 8002
    --local-gpus none
    --upstream-url http://192.168.1.101:8000
    --upstream-url http://192.168.1.102:8000

docker compose --profile router up -d

7.4 带可视化界面（API + Gradio）

# 先启动 API
docker compose --profile api up -d

# 再启动 Gradio（Gradio 连接到 API）
docker compose --profile gradio up -d
# 浏览器访问 http://localhost:7860

7.5 数据持久化

默认 compose.yaml 没有定义 volume，容器删除后数据丢失。添加持久化：

mineru-api:
  volumes:
    - ./output:/app/output          # 解析结果持久化
    - ./models:/root/.mineru/models # 模型文件持久化（避免重复下载）
  environment:
    MINERU_MODEL_SOURCE: local
    MINERU_API_OUTPUT_ROOT: /app/output

7.6 昇腾 NPU 部署

使用 NPU Dockerfile 构建镜像后，需要特殊的 docker run 参数（见 docs/npu_ascend_deployment_guide.md）。目前 compose.yaml 不直接支持昇腾 NPU 的设备透传配置，建议使用 docker run 手动启动。

---

八、端口速查表

端口	服务	说明
30000	openai-server	OpenAI 兼容 API
8000	api	FastAPI 解析服务
8002	router	负载均衡路由
7860	gradio	Web 图形界面

---

九、故障排查

容器启动失败

# 查看详细日志
docker compose logs mineru-api

# 常见原因：
# 1. 镜像未构建 → docker build -t mineru:latest ...
# 2. GPU 不可用 → nvidia-smi 检查
# 3. 端口冲突 → netstat -tlnp | grep 8000
# 4. 内存不足 → free -h 检查

OOM（显存不足）

# 降低 GPU 显存利用率
--gpu-memory-utilization 0.4

# 或切换到 Pipeline 模式（不使用 VLM）
# 请求时指定 backend=pipeline

健康检查失败

# 手动检查
curl http://localhost:8000/health

# 查看容器内日志
docker compose exec mineru-api curl http://localhost:8000/health