模型管理与部署：自动下载、缓存、切换源与多平台适配

模型管理与部署：自动下载、缓存、切换源与多平台适配

学习目标

读完本章后，你将能够：

• 理解 MinerU 的模型下载与缓存机制
• 掌握 HuggingFace 与 ModelScope 源切换方法
• 配置 VLM 推理后端（vLLM/LMDeploy/MLX）
• 了解国产算力平台的适配方案

前置知识

• 三引擎后端的源码实现与调度

---

1. 模型清单

MinerU 涉及的模型包括：

1.1 Pipeline 模型

模型	功能	HuggingFace 路径	ModelScope 路径
PDF-Extract-Kit-1.0	打包模型根路径	opendatalab/PDF-Extract-Kit-1.0	OpenDataLab/PDF-Extract-Kit-1.0
PP-DocLayoutV2	布局检测	models/Layout/PP-DocLayoutV2	同左
UniMERNet	公式识别	models/MFR/unimernet_hf_small_2503	同左
pp_formulanet_plus_m	公式识别（增强）	models/MFR/pp_formulanet_plus_m	同左
PaddleOCR	OCR	models/OCR/paddleocr_torch	同左
SlanetPlus	表格结构	models/TabRec/SlanetPlus/slanet-plus.onnx	同左
UnetStructure	表格结构（备用）	models/TabRec/UnetStructure/unet.onnx	同左

1.2 VLM 模型

模型	功能	HuggingFace 路径	ModelScope 路径
MinerU2.5-Pro-2605-1.2B	VLM 主模型	opendatalab/MinerU2.5-Pro-2605-1.2B	OpenDataLab/MinerU2.5-Pro-2605-1.2B

2. 自动下载机制

2.1 触发时机

首次使用时，MinerU 自动检测并下载所需模型：

mineru/utils/models_download_utils.py

def auto_download_and_get_model_root_path():
    """自动下载模型并返回本地缓存路径"""
    # 1. 确定模型源（HuggingFace 或 ModelScope）
    model_source = os.getenv("MINERU_MODEL_SOURCE", "huggingface")

    # 2. 检查本地缓存
    cache_dir = get_model_cache_dir()
    if model_exists_locally(cache_dir):
        return cache_dir

    # 3. 下载模型
    if model_source == "modelscope":
        download_from_modelscope()
    else:
        download_from_huggingface()

    return cache_dir

2.2 模型源切换

通过环境变量切换模型源：

# 使用 HuggingFace（默认）
export MINERU_MODEL_SOURCE=huggingface

# 使用 ModelScope（国内推荐）
export MINERU_MODEL_SOURCE=modelscope

2.3 预下载工具

使用命令行预下载所有模型：

mineru-models-download

优势：

• 在生产部署时提前下载，避免首次解析时等待
• 可在有网络的环境下载后迁移到无网络环境

3. 缓存机制

3.1 缓存位置

来源	默认缓存路径
HuggingFace	~/.cache/huggingface/hub/
ModelScope	~/.cache/modelscope/hub/

3.2 自定义缓存路径

# 设置 HuggingFace 缓存路径
export HF_HOME=/data/models/huggingface

# 设置 ModelScope 缓存路径
export MODELSCOPE_CACHE=/data/models/modelscope

4. VLM 推理后端配置

4.1 后端选择

MinerU 根据平台自动选择推荐的 VLM 推理后端：

平台	推荐后端	说明
Linux	vllm	性能最佳，支持 PagedAttention
Windows	lmdeploy	Turbomind 推理引擎
macOS	mlx	Apple Silicon 原生推理
全平台	transformers	兼容性最好，但性能一般
全平台	http-client	调用远程 API

4.2 后端配置

通过后端名称指定：

# vLLM 后端（Linux）
mineru -p doc.pdf -o output/ -b vlm-vllm-auto-engine

# LMDeploy 后端（Windows）
mineru -p doc.pdf -o output/ -b vlm-lmdeploy-auto-engine

# MLX 后端（macOS）
mineru -p doc.pdf -o output/ -b vlm-mlx-auto-engine

# HTTP 客户端（远程 API）
mineru -p doc.pdf -o output/ -b vlm-http-client \
  --api-url https://your-server/v1

4.3 vLLM 部署

独立启动 vLLM 推理服务：

# 启动 vLLM 服务
mineru-vllm-server --model opendatalab/MinerU2.5-Pro-2605-1.2B --port 8000

# CLI 连接远程 vLLM 服务
mineru -p doc.pdf -o output/ -b vlm-http-client --api-url http://localhost:8000/v1

4.4 LMDeploy 部署

# 启动 LMDeploy 服务
mineru-lmdeploy-server --model-path /path/to/model --port 8000

4.5 OpenAI 兼容服务

# 通用 OpenAI 兼容服务（支持任何 OpenAI 兼容 API）
mineru-openai-server --server-url http://your-server/v1

5. 国产算力适配

MinerU 支持十余款国产算力平台：

算力平台	架构	支持情况
昇腾（Ascend）	NPU	通过 PyTorch Adapter
寒武纪（Cambricon）	MLU	通过 PyTorch Adapter
燧原（Enflame）	GCU	社区适配
沐曦（MetaX）	GPU	社区适配
摩尔线程（Moore Threads）	GPU	社区适配
昆仑芯（Kunlunxin）	XPU	社区适配
天数智芯（Iluvatar）	GPU	社区适配
瀚博（Hanbox）	GPU	社区适配
太初元碁（MetaX）	GPU	社区适配
海光（Hygon）	DCU	社区适配
平头哥（T-Head）	NPU	社区适配

适配方式：

• 通过 PyTorch 的设备抽象（torch.device）支持
• 大部分国产算力通过 ROCm 或自定义后端接入 PyTorch

6. Docker 部署

MinerU 提供 Docker 部署方案：

# Pipeline 引擎 Docker
docker run --gpus all -v /data:/data mineru:mineru-pipeline \
  mineru -p /data/doc.pdf -o /data/output/ -b pipeline

# VLM 引擎 Docker
docker run --gpus all -v /data:/data mineru:mineru-vlm \
  mineru -p /data/doc.pdf -o /data/output/ -b vlm-auto-engine

Docker 优势：

• 环境隔离，不污染宿主机
• 一键部署，简化依赖安装
• 适合 CI/CD 和容器化编排

7. 陷阱与对策

陷阱	对策
首次运行下载模型耗时过长	使用 mineru-models-download 预下载
无法访问 HuggingFace	设置 MINERU_MODEL_SOURCE=modelscope
vLLM 在 macOS 不可用	macOS 使用 mlx 后端
国产算力推理报错	确认 PyTorch 适配器已正确安装
模型版本不匹配	使用 mineru 最新版本的配套模型
磁盘空间不足	清理 HuggingFace 缓存或设置 HF_HOME

8. 设计权衡

HuggingFace vs ModelScope

维度	HuggingFace	ModelScope
全球访问	是	有限
国内访问	可能受限	快速稳定
模型完整性	完整	完整（镜像）
推荐场景	海外环境	国内环境

取舍：默认 HuggingFace（全球通用），但通过环境变量轻松切换到 ModelScope（国内优化）。

本地推理 vs 远程 API

维度	本地推理	远程 API
部署成本	高（GPU 硬件）	低（按需付费）
数据隐私	高（本地处理）	中（需信任服务端）
延迟	低（无网络）	高（网络传输）
维护	重（模型管理）	轻（无需管理）

---

参考来源

• MinerU 源码：mineru/utils/models_download_utils.py、mineru/model/vlm/
• MinerU 官方文档：https://opendatalab.github.io/MinerU/
• vLLM 文档：https://docs.vllm.ai/
• LMDeploy 文档：https://lmdeploy.readthedocs.io/
• MLX 文档：https://ml-explore.github.io/mlx/