MinerU离线部署：完全断网环境解决方案

痛点场景：为什么需要离线部署？

在企业级应用和政府项目中，数据安全是首要考虑因素。许多组织要求系统在完全断网的环境中运行，以防止敏感数据泄露。MinerU作为高质量的PDF解析工具，在处理机密文档、科研论文、财务报告等场景时，离线部署需求尤为突出。

典型痛点场景：

• 🚫 内网环境无法访问外部模型仓库
• 🔒 数据安全要求禁止外网连接
• ⚡ 网络不稳定导致模型下载失败
• 📦 需要一次性部署到多台离线机器

离线部署架构设计

flowchart TD
    A[离线环境准备] --> B[模型文件下载]
    B --> C[依赖包缓存]
    C --> D[Docker镜像构建]
    D --> E[部署验证]
    E --> F[生产环境运行]
    
    subgraph B [模型下载阶段]
        B1[联网机器下载]
        B2[模型文件打包]
        B3[传输到离线环境]
    end
    
    subgraph C [依赖准备]
        C1[Python包缓存]
        C2[系统依赖包]
        C3[字体文件准备]
    end

完整离线部署流程

阶段一：准备工作（在联网环境中）

1. 下载MinerU源码和模型文件

# 克隆项目源码
git clone https://gitcode.com/gh_mirrors/mi/MinerU.git
cd MinerU

# 下载所有模型文件（pipeline + VLM）
python -m mineru.cli.models_download -s modelscope -m all

2. 缓存Python依赖包

# 创建依赖包缓存目录
mkdir -p offline_deps

# 下载所有依赖包
uv pip download -r requirements.txt -d offline_deps --no-deps
uv pip download mineru[core] -d offline_deps --no-deps

# 如果有sglang需求，额外下载
uv pip download mineru[sglang] -d offline_deps --no-deps

3. 准备Docker构建文件

# 复制Dockerfile和相关配置
cp docker/china/Dockerfile .
cp docker/compose.yaml .

阶段二：离线环境部署

1. 传输文件到离线环境

将以下文件传输到离线环境：

• MinerU项目目录（包含已下载的模型）
• offline_deps依赖包目录
• Dockerfile和compose.yaml文件

2. 离线安装Python依赖

# 在离线环境中安装依赖
uv pip install --no-index --find-links=offline_deps mineru[core]

# 或者从源码安装
uv pip install --no-index --find-links=offline_deps -e .[core]

3. 配置本地模型路径

创建或修改 ~/.mineru.json 配置文件：

{
  "config_version": "1.3.0",
  "models-dir": {
    "pipeline": "/path/to/your/models/pipeline",
    "vlm": "/path/to/your/models/vlm"
  },
  "model-source": "local"
}

4. 验证离线安装

# 测试基本功能
mineru --version

# 测试模型加载
mineru -p test.pdf -o output.md --dry-run

阶段三：Docker离线部署方案

1. 构建离线Docker镜像

修改Dockerfile，使用本地文件：

# 使用基础系统镜像
FROM ubuntu:22.04

# 安装系统依赖
RUN apt-get update && \
    apt-get install -y \
        python3.10 \
        python3-pip \
        fonts-noto-core \
        fonts-noto-cjk \
        libgl1 \
        && apt-get clean

# 复制本地依赖包
COPY offline_deps /tmp/offline_deps

# 离线安装Python包
RUN pip3 install --no-index --find-links=/tmp/offline_deps mineru[core]

# 复制模型文件
COPY models /root/.cache/mineru/models

# 设置环境变量
ENV MINERU_MODEL_SOURCE=local

# 设置入口点
ENTRYPOINT ["mineru"]

2. 构建和运行容器

# 构建镜像
docker build -t mineru-offline:latest .

# 运行容器
docker run -v $(pwd)/input:/input -v $(pwd)/output:/output \
    mineru-offline:latest -p /input/document.pdf -o /output/result.md

模型文件管理策略

模型文件结构

models/
├── pipeline/
│   ├── doclayout_yolo/          # 布局分析模型
│   ├── yolo_v8_mfd/            # 文档检测模型
│   ├── unimernet_small/        # 公式识别模型
│   ├── pytorch_paddle/         # OCR模型
│   ├── layout_reader/          # 阅读顺序模型
│   └── slanet_plus/            # 表格识别模型
└── vlm/
    └── mineru2/                # VLM多模态模型

模型版本控制

建议使用以下目录结构进行版本管理：

models/
├── v1.3.0/
│   ├── pipeline/
│   └── vlm/
├── v2.0.0/
│   ├── pipeline/
│   └── vlm/
└── current -> v2.0.0/          # 符号链接指向当前版本

高级配置选项

1. 内存优化配置

对于资源受限的环境，可以调整配置：

{
  "memory-optimization": {
    "max-workers": 2,
    "batch-size": 1,
    "gpu-memory-limit": "4G"
  }
}

2. 后端选择配置

{
  "backend-preference": {
    "primary": "pipeline",      # 主用后端
    "fallback": "vlm",          # 备用后端
    "auto-switch": true         # 自动切换
  }
}

故障排除指南

常见问题及解决方案

问题现象	可能原因	解决方案
模型加载失败	模型路径配置错误	检查MINERU_MODEL_SOURCE环境变量
内存不足	模型文件过大	调整batch-size或使用CPU模式
字体显示异常	缺少中文字体	安装fonts-noto-cjk包
Docker权限问题	显卡驱动问题	添加--gpus all和--privileged参数

性能优化建议

1. CPU模式优化：

   export CUDA_VISIBLE_DEVICES=""  # 强制使用CPU
   mineru -p input.pdf -o output.md --device cpu
   

2. 内存限制：

   # 限制GPU内存使用
   export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128
   

3. 批处理优化：

   # 小文件批处理
   mineru -p "*.pdf" -o output_dir --batch-size 4
   

安全加固措施

1. 容器安全配置

# docker-compose安全配置
version: '3.8'
services:
  mineru:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

2. 网络隔离

# 完全禁用网络
docker run --network none \
  -v /path/to/models:/models \
  mineru-offline:latest

3. 用户权限控制

# 使用非root用户运行
RUN useradd -m mineru-user
USER mineru-user

部署验证清单

✅ 基础环境验证

• [ ] Python 3.10+ 已安装
• [ ] 依赖包完整缓存
• [ ] 模型文件完整性校验

✅ 功能验证

• [ ] 命令行工具可执行
• [ ] 模型加载正常
• [ ] 基本PDF解析功能

✅ 性能验证

• [ ] 单文件解析时间
• [ ] 内存使用情况
• [ ] 多文件批处理能力

✅ 安全验证

• [ ] 网络连接已禁用
• [ ] 文件权限正确
• [ ] 日志输出正常

总结与展望

MinerU的离线部署方案为企业级用户提供了完整的安全保障。通过本文的详细指导，您可以在完全断网的环境中部署和使用这一强大的PDF解析工具。

关键优势：

• 🔒 完全数据隔离：所有处理在本地完成，无数据外传风险
• ⚡ 稳定可靠：不受网络波动影响，保证服务连续性
• 📦 一次部署，多处使用：支持批量部署到多台离线机器
• 🔧 灵活配置：支持多种后端和优化配置

随着MinerU项目的持续发展，离线部署方案也将不断完善，为更多有严格安全要求的场景提供支持。

---

下一步行动建议：

1. 立即开始准备模型文件和依赖包缓存
2. 按照本文指南进行测试环境部署
3. 验证通过后推广到生产环境
4. 建立定期的模型更新机制

通过系统化的离线部署，让MinerU在您的安全环境中发挥最大价值！