MinerU 系列教程 第十六篇
本篇教程作为 模块四:进阶篇 - API 服务与部署 的最后一课,将详细讲解 MinerU 的 Docker 容器化部署方案。你将了解完整的镜像体系(全球版、国内版、国产 AI 芯片版),掌握 Docker Compose 四种服务 Profile 的使用方式,以及生产环境部署的**实践。
完成本课学习后,你将能够:
- 理解 MinerU 的 Docker 镜像体系:全球版、国内版和 10 种国产 AI 芯片专用镜像
- 掌握 Dockerfile 的构建流程:基础镜像选择、依赖安装、模型下载
- 使用 Docker Compose 部署四种服务 Profile:openai-server、api、router、gradio
- 理解容器资源配置:GPU 设备映射、共享内存、IPC 模式
- 配置模型挂载策略实现 Volume 持久化
- 实施生产环境**实践:多 GPU 路由部署、混合架构、健康检查与自动重启
1.1 镜像分类概览
MinerU 提供了一套完整的 Docker 镜像体系,覆盖不同地区和硬件平台的需求:
docker/ ├── global/ │ └── Dockerfile # 全球版(基于 vllm/vllm-openai 官方镜像) ├── china/ │ ├── Dockerfile # 国内版(DaoCloud 代理 + 阿里云 PyPI) │ ├── npu.Dockerfile # 昇腾 Ascend NPU │ ├── mlu.Dockerfile # 寒武纪 Cambricon MLU │ ├── maca.Dockerfile # 沐曦 MetaX GPU │ ├── musa.Dockerfile # 摩尔线程 MooreThreads GPU │ ├── corex.Dockerfile # 天数智芯 IluvatarCorex GPU │ ├── gcu.Dockerfile # 燧原 Enflame GCU │ ├── dcu.Dockerfile # 海光 Hygon DCU │ ├── kxpu.Dockerfile # 昆仑芯 Kunlun XPU │ └── ppu.Dockerfile # 平头哥 T-Head PPU └── compose.yaml # Docker Compose 服务编排
1.2 全球版镜像
全球版 Dockerfile 基于 vLLM 官方镜像构建:
# docker/global/Dockerfile FROM vllm/vllm-openai:v0.11.2 # 安装 OpenCV 依赖和中文字体 RUN apt-get update && apt-get install -y fonts-noto-core fonts-noto-cjk fontconfig libgl1 && fc-cache -fv && apt-get clean && rm -rf /var/lib/apt/lists/* # 安装 MinerU RUN python3 -m pip install -U 'mineru[core]>=3.0.0' --break-system-packages && python3 -m pip cache purge # 下载所有模型 RUN /bin/bash -c "mineru-models-download -s huggingface -m all" # 入口点:设置模型源为本地并执行命令 ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec "$@"", "--"]
构建步骤解析:
vllm/vllm-openai:v0.11.2 自带 CUDA、PyTorch、vLLM 2 安装系统依赖
libgl1 供 OpenCV 使用,Noto 字体用于中文 PDF 渲染 3 安装 MinerU
mineru[core] 包含完整功能(不含推理加速框架,因基础镜像已有 vLLM) 4 下载模型
mineru-models-download 预下载所有版面分析和 OCR 模型 5 设置入口 运行时设置
MINERU_MODEL_SOURCE=local 使用本地模型
GPU 架构支持:基础镜像 vllm/vllm-openai:v0.11.2 支持 Compute Capability 7.0 ~ 12.0 的 NVIDIA GPU,覆盖 Volta、Turing、Ampere、Ada Lovelace、Hopper、Blackwell 架构。同时支持 x86_64 和 ARM (AArch64) 两种 CPU 架构。
构建命令:
# 在 docker/ 目录下执行 docker build -f global/Dockerfile -t mineru:latest .
1.3 国内版镜像
国内版使用 DaoCloud 代理拉取基础镜像,并使用阿里云 PyPI 镜像加速 Python 包安装:
# docker/china/Dockerfile FROM docker.m.daocloud.io/vllm/vllm-openai:v0.11.2
… 系统依赖安装相同 …
使用阿里云镜像源
RUN python3 -m pip install -U ‘mineru[core]>=3.0.0’
-i https://mirrors.aliyun.com/pypi/simple --break-system-packages && python3 -m pip cache purge
使用 ModelScope 下载模型(国内可达)
RUN /bin/bash -c “mineru-models-download -s modelscope -m all”
ENTRYPOINT [“/bin/bash”, “-c”, “export MINERU_MODEL_SOURCE=local && exec ”$@“”, “–”]
与全球版的差异:
1.4 国产 AI 芯片专用镜像
MinerU 为 10 种国产 AI 芯片提供了专用 Dockerfile,它们的共同构建模式为:
厂商专用基础镜像 → 系统依赖 → MinerU + 适配依赖 → 模型下载 → 统一入口
以下是各芯片的 Dockerfile 概要:
npu.Dockerfile 昇腾 Ascend NPU
ascend/vllm-ascend:v0.11.0 ARM (AArch64) vLLM / LMDeploy
mlu.Dockerfile 寒武纪 Cambricon MLU LMDeploy / vLLM 专用镜像 x86_64 LMDeploy / vLLM
maca.Dockerfile 沐曦 MetaX GPU
cr.metax-tech.com/…/vllm:maca.ai3.1.0.7… x86_64 vLLM / LMDeploy
musa.Dockerfile 摩尔线程 MooreThreads
registry.mthreads.com/…/vllm-musa-qy2… x86_64 vLLM
corex.Dockerfile 天数智芯 IluvatarCorex OpenDataLab 定制镜像 x86_64 vLLM
gcu.Dockerfile 燧原 Enflame GCU OpenDataLab 定制镜像 x86_64 vLLM
dcu.Dockerfile 海光 Hygon DCU SourceFind Harbor 镜像 x86_64 vLLM
kxpu.Dockerfile 昆仑芯 Kunlun XPU 社区定制镜像 x86_64 vLLM
ppu.Dockerfile 平头哥 T-Head PPU OpenDataLab 定制镜像 x86_64 vLLM / LMDeploy
适配差异示例:
昇腾 NPU 版需要额外固定 numpy 和 opencv 版本,并在模型下载时禁用 Torch 设备后端自动加载:
# docker/china/npu.Dockerfile RUN python3 -m pip install ‘mineru[core]>=3.0.0’
numpy==1.26.4 opencv-python==4.11.0.86 -i https://mirrors.aliyun.com/pypi/simple
禁用 torch 设备后端自动加载以避免 NPU 初始化干扰模型下载
RUN TORCH_DEVICE_BACKEND_AUTOLOAD=0 /bin/bash -c “mineru-models-download -s modelscope -m all”
摩尔线程版需要从源码编译 torchvision:
# docker/china/musa.Dockerfile RUN git clone https://gitcode.com/gh_mirrors/vi/vision.git -b v0.20.0 –depth 1 &&
cd vision && python3 setup.py install
2.1 四种部署 Profile
MinerU 使用 Docker Compose 的 Profile 机制将四种服务分组管理。这意味着你可以按需启动特定的服务组合,而不是一次性启动所有容器。
# docker/compose.yaml services: mineru-openai-server: # Profile: openai-server mineru-api: # Profile: api mineru-router: # Profile: router mineru-gradio: # Profile: gradio
启动方式:
# 启动单个 Profile docker compose --profile api up -d # 启动多个 Profile docker compose --profile openai-server --profile api up -d # 启动所有服务 docker compose --profile openai-server --profile api --profile router --profile gradio up -d
2.2 openai-server Profile
VLM 推理服务,对外暴露 OpenAI 兼容接口,供 http-client 模式使用:
mineru-openai-server: image: mineru:latest container_name: mineru-openai-server restart: always profiles: ["openai-server"] ports: - 30000:30000 environment: MINERU_MODEL_SOURCE: local entrypoint: mineru-openai-server command: --host 0.0.0.0 --port 30000 # --gpu-memory-utilization 0.5 ulimits: memlock: -1 stack: ipc: host healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:30000/health || exit 1"] deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
使用场景:当你需要将 VLM 推理服务独立部署在高显存 GPU 上,供多个 mineru-api 实例通过 vlm-http-client 或 hybrid-http-client 模式远程调用。
2.3 api Profile
FastAPI 文档解析服务,集成完整的解析能力:
mineru-api: image: mineru:latest container_name: mineru-api restart: always profiles: ["api"] ports: - 8000:8000 environment: MINERU_MODEL_SOURCE: local entrypoint: mineru-api command: --host 0.0.0.0 --port 8000 # --gpu-memory-utilization 0.5 ulimits: memlock: -1 stack: ipc: host healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"] deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
使用场景:单 GPU 独立部署,直接对外提供文档解析 API。适用于中小规模使用或开发测试环境。
2.4 router Profile
路由服务,负载均衡多个 API 实例:
mineru-router: image: mineru:latest container_name: mineru-router restart: always profiles: ["router"] ports: - 8002:8002 environment: MINERU_MODEL_SOURCE: local entrypoint: mineru-router command: --host 0.0.0.0 --port 8002 --local-gpus auto # 聚合远程 API 服务而非启动本地 worker: # --local-gpus none # --upstream-url http://mineru-api:8000 # --upstream-url http://mineru-api-2:8000 ulimits: memlock: -1 stack: ipc: host healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8002/health || exit 1"] deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
使用场景:多 GPU 环境的统一入口,自动管理本地 GPU 工作进程或聚合远程 API 实例。
2.5 gradio Profile
Web UI 服务,提供可视化交互界面:
mineru-gradio: image: mineru:latest container_name: mineru-gradio restart: always profiles: ["gradio"] ports: - 7860:7860 environment: MINERU_MODEL_SOURCE: local entrypoint: mineru-gradio command: --server-name 0.0.0.0 --server-port 7860 # --enable-api false # --max-convert-pages 20 ulimits: memlock: -1 stack: ipc: host deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
使用场景:为最终用户提供浏览器可访问的文档解析界面。
3.1 GPU 设备映射
每个服务通过 deploy.resources.reservations.devices 指定使用的 GPU:
deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] # 使用第 0 号 GPU capabilities: [gpu]
多 GPU 配置:
# 单个服务使用多张 GPU device_ids: ["0", "1"] # 使用所有可用 GPU # 将 device_ids 替换为 count: devices: - driver: nvidia count: all capabilities: [gpu]
3.2 IPC 模式
ipc: host
ipc: host 让容器共享主机的 IPC 命名空间(Inter-Process Communication)。这对于 PyTorch 的多进程数据加载和 GPU 内存共享至关重要。
如果不设置 ipc: host,PyTorch DataLoader 的 num_workers > 0 可能因共享内存不足而失败。
3.3 共享内存与进程限制
ulimits: memlock: -1 # 取消内存锁定限制 stack: # 栈大小限制:64MB
memlock: -1 无限制 允许 GPU 驱动锁定内存页面(CUDA pinned memory)
stack: 64MB 增大线程栈空间,防止深层递归或大模型推理时栈溢出
提示:如果你的 GPU 显存有限,可以通过
--gpu-memory-utilization 0.5参数减少 vLLM 的 KV Cache 大小。若仍然 OOM,可以进一步降低到0.4或更低。
3.4 自动重启策略
restart: always
restart: always 确保服务在以下情况自动重启:
- 进程崩溃(非零退出码)
- OOM Kill
- Docker 守护进程重启
- 主机重启
4.1 默认行为
在默认的 Dockerfile 中,模型文件在构建时通过 mineru-models-download 预下载并内嵌到镜像中。这使得镜像体积较大(通常 20GB+),但部署时无需额外步骤。
4.2 Volume 持久化模型目录
在生产环境中,建议使用 Docker Volume 或 Bind Mount 将模型目录外置:
services: mineru-api: image: mineru:latest volumes: # 方式 1:Bind Mount(主机路径映射) - /data/mineru-models:/root/.cache/mineru # 方式 2:Named Volume # - mineru-models:/root/.cache/mineru # ... # 使用 Named Volume 时需要声明 volumes: mineru-models:
优势:
- 镜像瘦身:构建镜像时跳过模型下载步骤,镜像体积可减少 15GB+
- 多容器共享:多个服务实例可挂载同一个模型目录,避免重复存储
- 独立更新:模型更新不需要重新构建镜像
4.3 轻量镜像构建
如果使用 Volume 挂载模型,可以构建不含模型的轻量镜像:
# Dockerfile.lightweight FROM vllm/vllm-openai:v0.11.2 RUN apt-get update && apt-get install -y fonts-noto-core fonts-noto-cjk fontconfig libgl1 && fc-cache -fv && apt-get clean && rm -rf /var/lib/apt/lists/* RUN python3 -m pip install -U 'mineru[core]>=3.0.0' --break-system-packages && python3 -m pip cache purge # 跳过模型下载步骤 ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec "$@"", "--"]
然后首次部署时在主机上执行模型下载:
# 在主机上下载模型到指定目录 docker run --rm -v /data/mineru-models:/root/.cache/mineru mineru:lightweight mineru-models-download -s huggingface -m all
4.4 模型下载源选择
-s huggingface 从 HuggingFace Hub 下载 全球可达环境
-s modelscope 从 ModelScope 下载 中国大陆环境
-m all 下载所有模型 完整功能(推荐)
5.1 单 GPU 快速部署
最简单的生产部署 —— 一台单 GPU 服务器对外提供 API:
# 构建镜像 cd docker && docker build -f global/Dockerfile -t mineru:latest . # 启动 API 服务 docker compose --profile api up -d # 验证服务状态 curl http://localhost:8000/health
5.2 多 GPU 路由部署
一台多 GPU 服务器使用 Router 自动分配任务:
# 自定义 compose.override.yaml services: mineru-router: command: --host 0.0.0.0 --port 8002 --local-gpus auto # 自动检测所有 GPU deploy: resources: reservations: devices: - driver: nvidia count: all # 分配所有 GPU capabilities: [gpu]
docker compose --profile router up -d
Router 将自动为每张 GPU 启动一个 mineru-api Worker 进程,并通过负载均衡分配请求。
5.3 远程 VLM + 本地 Pipeline 的混合架构
将 VLM 推理服务部署在高显存 GPU 服务器上,API 服务以 hybrid-http-client 模式连接:
┌───────────────────────────────────────┐ │ GPU Server A (A100 80GB) │ │ │ │ ┌─────────────────────────────────┐ │ │ │ mineru-openai-server │ │ │ │ (端口 30000) │ │ │ │ 模型: Qwen2.5-VL-7B │ │ │ └─────────────────────────────────┘ │ └───────────────────────┬───────────────┘ │ HTTP ┌───────────────────────▼───────────────┐ │ API Server B (RTX 4090 24GB) │ │ │ │ ┌─────────────────────────────────┐ │ │ │ mineru-api │ │ │ │ (端口 8000) │ │ │ │ --backend hybrid-http-client │ │ │ │ --server-url http://A:30000 │ │ │ └─────────────────────────────────┘ │ └───────────────────────────────────────┘
Server A 的 compose.yaml:
services: mineru-openai-server: image: mineru:latest restart: always ports: - 30000:30000 environment: MINERU_MODEL_SOURCE: local entrypoint: mineru-openai-server command: --host 0.0.0.0 --port 30000 ipc: host deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
Server B 的 compose.yaml:
services: mineru-api: image: mineru:latest restart: always ports: - 8000:8000 environment: MINERU_MODEL_SOURCE: local entrypoint: mineru-api command: --host 0.0.0.0 --port 8000 ipc: host deploy: resources: reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
调用时指定远程 VLM 服务:
curl -X POST http://server-b:8000/tasks -F "files=@document.pdf" -F "backend=hybrid-http-client" -F "server_url=http://server-a:30000"
5.4 多机分布式 Router 部署
多台服务器通过 Router 统一管理:
┌─────────────────────────┐ │ mineru-router │ │ (端口 8002) │ │ --local-gpus none │ │ --upstream-url A:8000 │ │ --upstream-url B:8000 │ └───────┬──────┬──────────┘ │ │ ┌─────────────┘ └─────────────┐ ▼ ▼ ┌─────────────────────────┐ ┌─────────────────────────┐ │ GPU Server A │ │ GPU Server B │ │ mineru-api :8000 │ │ mineru-api :8000 │ │ (2x A100) │ │ (4x A100) │ └─────────────────────────┘ └─────────────────────────┘
Router 的 compose 配置:
services: mineru-router: image: mineru:latest restart: always ports: - 8002:8002 entrypoint: mineru-router command: --host 0.0.0.0 --port 8002 --local-gpus none --upstream-url http://server-a:8000 --upstream-url http://server-b:8000 healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8002/health || exit 1"]
注意:Router 配置
--local-gpus none表示不启动本地 Worker,仅作为纯反向代理和负载均衡器。此模式下 Router 容器本身不需要 GPU。
5.5 健康检查与自动重启
所有服务都配置了 Docker 原生健康检查:
healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
Docker 默认的健康检查行为:
interval 30s 检查间隔
timeout 30s 单次检查超时
retries 3 连续失败次数判定不健康
start_period 0s 启动宽限期
对于需要较长模型加载时间的服务,建议增加 start_period:
healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"] interval: 30s timeout: 10s retries: 3 start_period: 120s # VLM 模型加载可能需要 1-2 分钟
结合 restart: always,当容器被判定为不健康时,Docker 会自动重启容器。
5.6 日志管理
生产环境建议配置日志驱动限制存储:
services: mineru-api: logging: driver: json-file options: max-size: "100m" max-file: "3"
6.1 开发测试环境
# 快速启动 Gradio WebUI(一站式体验) docker compose --profile gradio up -d # 访问 http://localhost:7860
6.2 CI/CD 集成
# 使用 API Profile,通过 API 接口调用 docker compose --profile api up -d # 等待健康检查通过 until curl -sf http://localhost:8000/health; do sleep 5; done # 批量处理文档 curl -X POST http://localhost:8000/tasks -F "files=@document.pdf" -F "backend=hybrid-auto-engine"
6.3 高可用生产环境
# 多 GPU 服务器部署 Router docker compose --profile router up -d # 验证所有 Worker 就绪 curl http://localhost:8002/health | python -m json.tool
7.1 常见问题
nvidia-smi 可用且 CUDA 版本兼容 OOM Killed 显存不足 添加
–gpu-memory-utilization 0.4 降低 KV Cache 健康检查失败 模型加载超时 增加
start_period 或使用 VLM 预加载 多 GPU 未识别 device_ids 配置错误 检查
nvidia-smi 输出的 GPU 编号 中文乱码 字体缺失 确认
fonts-noto-cjk 已安装
7.2 调试命令
# 查看容器日志 docker logs mineru-api –tail 100 -f
# 进入容器调试 docker exec -it mineru-api bash
# 检查 GPU 状态 docker exec mineru-api nvidia-smi
# 检查模型文件是否完整 docker exec mineru-api ls /root/.cache/mineru/
# 查看健康状态 docker inspect –format=‘{{.State.Health.Status}}’ mineru-api
7.3 性能调优
–gpu-memory-utilization 0.8 提高(默认 0.9 左右),可处理更长文档 并发数
MINERU_API_MAX_CONCURRENT_REQUESTS=5 增加并发(需确保显存充足) 共享内存
shm_size: “32g” 或
ipc: host 解决 PyTorch 多进程共享内存不足
8.1 网络隔离
services: mineru-api: networks: - mineru-internal # 内部网络 ports: - "127.0.0.1:8000:8000" # 仅本地访问 networks: mineru-internal: driver: bridge
8.2 只读文件系统
services: mineru-api: read_only: true tmpfs: - /tmp volumes: - mineru-output:/output # 仅输出目录可写
8.3 非 Root 运行
若基础镜像支持,建议添加:
services: mineru-api: user: "1000:1000"
9.1 核心文件
docker/global/Dockerfile 全球版构建文件,基于
vllm/vllm-openai:v0.11.2
docker/china/Dockerfile 国内版构建文件,DaoCloud 代理 + 阿里云 PyPI + ModelScope
docker/compose.yaml Docker Compose 编排,定义四种 Profile
docker/china/*.Dockerfile 10 种国产 AI 芯片专用 Dockerfile
9.2 构建流程对照
所有 Dockerfile 遵循统一的四层结构:
┌─────────────────────────────────────────────────┐ │ Layer 1: 基础镜像 │ │ - 包含 CUDA/加速框架/Python/推理引擎 │ │ - 不同芯片使用各自厂商提供的基础镜像 │ ├─────────────────────────────────────────────────┤ │ Layer 2: 系统依赖 │ │ - libgl1 (OpenCV) │ │ - fonts-noto-cjk (中文字体) │ │ - fontconfig │ ├─────────────────────────────────────────────────┤ │ Layer 3: MinerU 安装 │ │ - pip install mineru[core] │ │ - 芯片特定版本锁定 (numpy, opencv-python) │ ├─────────────────────────────────────────────────┤ │ Layer 4: 模型预下载 │ │ - mineru-models-download -s -m all │ │ - 包含版面分析、OCR、VLM 等所有模型 │ ├─────────────────────────────────────────────────┤ │ ENTRYPOINT: 统一入口 │ │ - export MINERU_MODEL_SOURCE=local │ │ - exec “$@”(执行传入的命令) │ └─────────────────────────────────────────────────┘
9.3 Compose 服务通用配置
四个服务共享以下配置模式:
# 通用模式 image: mineru:latest # 统一使用同一镜像 restart: always # 自动重启 environment: MINERU_MODEL_SOURCE: local # 使用本地模型 ulimits: memlock: -1 # 无内存锁定限制 stack: # 64MB 栈空间 ipc: host # 共享主机 IPC deploy: resources:
reservations: devices: - driver: nvidia device_ids: ["0"] capabilities: [gpu]
区别在于:
entrypoint
mineru-openai-server
mineru-api
mineru-router
mineru-gradio 默认端口 30000 8000 8002 7860 健康检查 有 有 有 无(Gradio 无 /health 端点) 核心参数
–gpu-memory-utilization -
–local-gpus
–enable-api
本课我们系统性地学习了 MinerU 的 Docker 容器化部署方案。核心要点回顾:
- 镜像体系:全球版基于
vllm/vllm-openai:v0.11.2,国内版使用 DaoCloud 代理和阿里云源,另有 10 种国产 AI 芯片专用 Dockerfile - 统一构建模式:所有 Dockerfile 遵循四层结构 —— 基础镜像 → 系统依赖 → MinerU 安装 → 模型预下载
- 四种 Profile:openai-server(VLM 推理)、api(文档解析)、router(负载均衡)、gradio(Web UI)
- 资源配置:GPU 设备映射、
ipc: host、ulimits内存锁定和栈空间配置 - 模型挂载:Volume 持久化避免重复存储,支持多容器共享
- 生产实践:多 GPU 路由部署、远程 VLM + 本地 Pipeline 混合架构、健康检查与自动重启
下一课我们将进入 模块五:原理篇 - 数据流与中间格式,深入分析 MinerU 的 Middle JSON 统一中间格式设计。我们将了解 pdf_info 的分页结构、标准 Block 的数据模型、各后端到 Middle JSON 的转换路径。
版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容,请联系我们,一经查实,本站将立刻删除。
如需转载请保留出处:https://51itzy.com/kjqy/276936.html