MinerU 离线部署指南：从环境准备到生产优化

1. 准备阶段：构建离线部署基础

1.1 规划资源需求

📋 资源准备清单

资源类型	最低要求	推荐配置	性能影响评估
内存	8GB RAM	16GB RAM	低于8GB将导致模型加载失败，推荐配置可提升30%处理速度
存储	40GB可用空间	100GB SSD	SSD可将模型加载时间减少50%，额外空间用于缓存和日志
处理器	4核CPU	8核CPU+GPU	GPU加速可提升复杂文档处理效率3-5倍
网络	无（离线环境）	临时联网准备环境	-

⚠️ 注意：所有硬件需支持Docker虚拟化技术，确保BIOS中已启用虚拟化功能。

1.2 收集部署资产

在联网环境中完成以下资产准备：

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

# 切换至稳定版本
git checkout v1.4.2

# 下载模型文件（国内源加速）
python -m mineru.cli.models_download -s modelscope -m all \
  --output-path ./mineru_models_v1.4

# 缓存Python依赖
pip wheel --wheel-dir=./offline_wheels -r requirements.txt

💡 提示：建议使用16GB以上USB3.0移动存储设备传输这些资产，总大小约25-35GB。

2. 实施阶段：构建离线运行环境

2.1 验证环境兼容性

在目标离线服务器上执行以下检查：

# 验证Python版本（需3.10.x）
python3 --version | grep "3.10." || echo "❌ Python版本不兼容"

# 验证Docker环境
docker --version && docker compose version || echo "❌ Docker未安装"

# 检查系统资源
echo "📊 磁盘空间：$(df -h / | awk 'NR==2 {print $4}') 可用"
echo "📊 内存大小：$(free -h | awk '/Mem:/ {print $2}') 总内存"

⚠️ 注意：若磁盘空间不足，可通过du -sh *命令查找并清理大文件释放空间。

2.2 配置离线环境

2.2.1 安装依赖包

# 创建本地依赖库
mkdir -p /opt/mineru/offline_deps
cp -r /media/usb/offline_wheels/* /opt/mineru/offline_deps/

# 安装依赖
pip install --no-index --find-links=/opt/mineru/offline_deps \
  -r requirements.txt \
  --ignore-installed

2.2.2 配置模型路径

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

{
  "config_version": "1.4.0",
  "models-dir": {
    "pipeline": "/opt/mineru/models/pipeline",
    "vlm": "/opt/mineru/models/vlm"
  },
  "model-source": "local",
  "logging-level": "INFO",
  "performance": {
    "batch-size": 2,
    "max-workers": 4
  }
}

2.3 构建Docker镜像

# 复制模型文件
mkdir -p /opt/mineru/models
cp -r /media/usb/mineru_models_v1.4/* /opt/mineru/models/

# 构建镜像
docker build -f docker/china/Dockerfile \
  --build-arg MODEL_PATH=/opt/mineru/models \
  --build-arg DEPS_PATH=/opt/mineru/offline_deps \
  -t mineru:v1.4.2 .

# 启动服务
docker compose up -d

💡 提示：构建过程可能需要30分钟以上，请耐心等待。如遇错误，可添加--progress=plain参数查看详细构建日志。

3. 验证阶段：确保部署正确性

3.1 基础功能测试

# 验证服务状态
docker compose ps | grep "Up" || echo "❌ 服务未正常启动"

# 检查版本信息
docker compose exec mineru mineru --version | grep "1.4.2" || echo "❌ 版本不匹配"

# 处理测试文档
docker compose exec mineru \
  mineru -p ./tests/unittest/pdfs/test.pdf \
  -o /tmp/test_output.md \
  --device cpu

# 验证输出结果
grep "成功" /tmp/test_output.md && echo "✅ 基础功能测试通过"

3.2 处理流程验证

下图展示了MinerU的典型文档处理流程，可用于验证部署后的功能完整性：

💡 提示：建议测试不同类型文档（纯文本、表格、公式、图片混合）以全面验证系统能力。

4. 优化阶段：提升离线环境表现

4.1 性能参数调优

📊 批处理配置对比

参数	低资源环境	平衡配置	高性能配置
batch-size	1	2-4	8-16
max-workers	2	4	8
gpu-memory-limit	4G	8G	16G
处理速度	较慢	平衡	最快
资源占用	低	中	高

修改配置文件调整性能参数：

{
  "performance": {
    "batch-size": 2,
    "max-workers": 4,
    "gpu-memory-limit": "8G",
    "ocr-threads": 4
  }
}

4.2 维护策略制定

4.2.1 版本管理

创建版本信息记录文件：

cat > /opt/mineru/version_info.txt << EOF
MinerU版本: v1.4.2
部署日期: $(date +%Y-%m-%d)
模型版本: model_v202311
依赖包版本: deps_v1.4
配置版本: config_v2
EOF

4.2.2 日志配置优化

{
  "logging": {
    "level": "INFO",
    "file-path": "/var/log/mineru",
    "max-size": "100MB",
    "max-backup": 5,
    "format": "json"
  }
}

4.3 常见问题速查

问题	可能原因	解决方案
模型加载失败	模型文件损坏或路径错误	1. 检查模型文件MD5校验和 2. 验证配置文件中的models-dir路径 3. 确保磁盘有足够空间
处理速度慢	资源配置不足	1. 降低batch-size至1 2. 关闭不必要的功能模块 3. 清理系统内存，关闭其他应用
内存溢出	文档过大或批处理设置不当	1. 增加系统内存 2. 启用内存优化模式 3. 将大文档拆分为小文件处理
输出格式异常	字体缺失或配置问题	1. 安装文泉驿等中文字体 2. 检查格式转换配置 3. 更新到最新版本

4.4 自动化处理配置

创建批量处理脚本：

cat > /opt/mineru/scripts/batch_process.sh << 'EOF'
#!/bin/bash
INPUT_DIR="/opt/documents/input"
OUTPUT_DIR="/opt/documents/output"
LOG_FILE="/var/log/mineru/batch_process.log"

# 创建必要目录
mkdir -p $INPUT_DIR $OUTPUT_DIR $INPUT_DIR/processed

# 处理所有未处理的PDF
find $INPUT_DIR -name "*.pdf" -not -name ".*" | while read -r file; do
  filename=$(basename "$file" .pdf)
  if [ ! -f "$OUTPUT_DIR/$filename.md" ]; then
    echo "[$(date)] Processing $file" >> $LOG_FILE
    mineru -p "$file" -o "$OUTPUT_DIR/$filename.md" >> $LOG_FILE 2>&1
    if [ $? -eq 0 ]; then
      mv "$file" "$INPUT_DIR/processed/"
      echo "[$(date)] Successfully processed $file" >> $LOG_FILE
    else
      echo "[$(date)] Failed to process $file" >> $LOG_FILE
    fi
  fi
done
EOF

chmod +x /opt/mineru/scripts/batch_process.sh

💡 提示：可通过crontab设置定时任务，实现无人值守的批量文档处理。