MinerU离线部署全流程指南

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

收集部署资源

用户应获取MinerU部署所需的全部资源，确保离线环境中具备完整的运行条件。这包括源代码、模型文件、依赖包和Docker配置。建议采用版本化管理方式，为后续维护和回溯提供依据。

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

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

# 下载模型文件（使用国内源加速）
python -m mineru.cli.models_download -s modelscope -m all \
  --output-path ./mineru_models_v1.4  # 指定模型存储路径，便于管理

💡 技巧：建议将所有资源打包为一个压缩文件，包含版本信息，如mineru_offline_v1.4.2.tar.gz，便于传输和管理。

验证目标环境

在开始部署前，必须验证目标离线环境是否满足基本要求。这一步可以避免因环境不兼容导致的部署失败。

# 环境检查脚本
cat > check_environment.sh << 'EOF'
#!/bin/bash
echo "=== 系统环境检查 ==="
python3 --version | grep "3.10." || { echo "❌ Python版本需3.10.x"; exit 1; }
docker --version && docker compose version || { echo "❌ Docker环境未安装"; exit 1; }
df -h | awk '/\// {print $4 " available on " $NF}' | grep -vE '1[0-9]G|2[0-9]G|3[0-9]G|4[0-9]G' && { echo "❌ 磁盘空间不足40GB"; exit 1; }
free -h | awk '/Mem:/ {print $2 " total memory"}' | grep -vE '8G|1[0-9]G|2[0-9]G' && { echo "❌ 内存不足8GB"; exit 1; }
echo "✅ 环境检查通过"
EOF

# 添加执行权限并运行
chmod +x check_environment.sh && ./check_environment.sh

⚠️ 警告：如果检查失败，应先解决环境问题再继续部署。特别是内存和磁盘空间不足会直接影响MinerU的运行稳定性。

准备离线依赖

提前在联网环境中下载所有依赖包，以便在离线环境中安装。这一步确保在没有网络连接的情况下也能完成依赖安装。

# 在联网环境中下载依赖包
mkdir -p offline_deps
pip download -r requirements.txt -d offline_deps/ \
  --no-cache-dir  # 不使用缓存，确保获取最新版本

📌 重点：依赖包应与目标环境的操作系统和Python版本匹配。建议在与目标环境相同的系统中下载依赖。

实施阶段：执行离线部署流程

传输部署文件

将准备好的所有文件传输到离线环境。这包括源代码、模型文件、依赖包和Docker配置文件。建议使用加密的移动存储设备进行传输，确保数据安全。

# 示例：使用rsync传输文件（如果网络可用）
rsync -avz MinerU/ /media/usb_drive/MinerU/
rsync -avz mineru_models_v1.4/ /media/usb_drive/mineru_models_v1.4/
rsync -avz offline_deps/ /media/usb_drive/offline_deps/

💡 技巧：传输完成后，建议使用md5sum验证文件完整性，确保传输过程中没有数据损坏。

安装依赖包

在离线环境中安装预下载的依赖包，确保MinerU运行所需的所有库都已正确安装。

# 创建依赖包安装目录
mkdir -p /opt/mineru/offline_deps

# 复制依赖包到目标位置
cp -r /media/usb_drive/offline_deps/* /opt/mineru/offline_deps/

# 安装依赖包
pip install --no-index --find-links=/opt/mineru/offline_deps \
  -r requirements.txt \
  --ignore-installed  # 忽略已安装的包，确保版本一致性

为什么这么做：使用--no-index参数确保pip不会尝试从网络下载包，完全使用本地依赖。--ignore-installed确保安装requirements.txt中指定的精确版本。

配置模型路径

创建MinerU配置文件，指定本地模型路径和其他关键参数。正确的配置是MinerU能够找到并使用本地模型的关键。

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

📌 重点配置说明：

• model-source: 设置为"local"表示使用本地模型
• models-dir: 指定pipeline和vlm模型的本地路径
• batch-size: 批处理大小，根据内存调整（推荐值：2-4）
• max-workers: 工作进程数，不超过CPU核心数

构建Docker镜像

使用Docker构建离线环境下的MinerU镜像，将所有依赖和配置打包到容器中，确保环境一致性。

# 构建Docker镜像
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 .

# 使用compose启动服务
docker compose up -d

为什么这么做：Docker容器提供了隔离的运行环境，确保MinerU在不同系统上的行为一致，同时简化部署和回滚流程。

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

基础功能验证

验证MinerU是否正确安装并能正常运行基本命令。这一步确保软件本身没有问题。

# 验证版本信息
docker compose exec mineru mineru --version

# 检查服务状态
docker compose ps | grep "Up" | grep "mineru" || { echo "❌ MinerU服务未运行"; exit 1; }

预估完成时间：5分钟

文档处理测试

运行实际的文档处理任务，验证MinerU的核心功能是否正常工作。建议使用不同类型的PDF文档进行测试。

# 创建测试目录
mkdir -p /tmp/mineru_test

# 复制测试文档
cp ./tests/unittest/pdfs/test.pdf /tmp/mineru_test/

# 运行文档处理
docker compose exec mineru \
  mineru -p /tmp/mineru_test/test.pdf \
  -o /tmp/mineru_test/test_output.md \
  --device cpu  # 如果没有GPU，强制使用CPU

# 检查输出结果
cat /tmp/mineru_test/test_output.md | grep "成功" && echo "✅ 测试通过"

💡 技巧：建议创建包含不同类型内容的测试套件，包括纯文本、表格、公式和图片的PDF，全面验证MinerU的处理能力。

性能指标评估

测试MinerU在不同配置下的性能表现，确定最佳运行参数。这一步对于优化MinerU在特定硬件环境下的表现至关重要。

# 创建性能测试脚本
cat > performance_test.sh << 'EOF'
#!/bin/bash
TEST_FILES=("./demo/pdfs/demo1.pdf" "./demo/pdfs/demo2.pdf" "./demo/pdfs/demo3.pdf")
OUTPUT_DIR="/tmp/performance_test"
mkdir -p $OUTPUT_DIR

for file in "${TEST_FILES[@]}"; do
  echo "测试文件: $file"
  for batch_size in 1 2 4; do
    echo "批处理大小: $batch_size"
    time docker compose exec mineru \
      mineru -p $file -o $OUTPUT_DIR/$(basename $file .pdf)_bs$batch_size.md \
      --batch-size $batch_size
  done
done
EOF

# 添加执行权限并运行
chmod +x performance_test.sh && ./performance_test.sh

📊 性能对比表：不同批处理大小下的文档处理时间（秒/页）

文档类型	批处理大小=1	批处理大小=2	批处理大小=4
纯文本PDF	1.1	0.9	0.8
含表格PDF	3.2	2.5	2.1
含公式PDF	4.5	3.8	3.5

优化阶段：提升系统表现

资源配置优化

根据硬件条件调整MinerU的资源配置，平衡性能和资源占用。适当的配置可以显著提升处理效率。

{
  "performance": {
    "batch-size": 1,          // 低内存环境建议设为1
    "max-workers": 2,         // CPU核心数的50%
    "gpu-memory-limit": "6G", // 如有GPU，限制内存使用
    "ocr-threads": 4,         // OCR处理线程数
    "table-recognition": {
      "accuracy-mode": "balanced", // 平衡模式兼顾速度和 accuracy
      "merge-threshold": 0.3       // 表格单元格合并阈值
    }
  }
}

⚠️ 警告：批处理大小过大会导致内存溢出，特别是处理大型PDF文件时。建议从较小值开始测试，逐步调整到最佳值。

自动化运维配置

设置日志管理和定期维护任务，确保MinerU长期稳定运行。良好的运维配置可以减少人工干预，及时发现并解决问题。

{
  "logging": {
    "level": "INFO",                // 生产环境建议使用INFO级别
    "file-path": "/var/log/mineru", // 日志存储路径
    "max-size": "100MB",            // 单个日志文件大小
    "max-backup": 5,                // 保留日志文件数
    "format": "json"                // 结构化日志便于分析
  }
}

# 创建日志轮转配置
cat > /etc/logrotate.d/mineru << 'EOF'
/var/log/mineru/*.log {
    daily
    missingok
    rotate 7
    compress
    delaycompress
    notifempty
    create 0640 root root
}
EOF

故障排除指南

建立常见问题的排查流程，快速定位并解决部署和运行中可能遇到的问题。

常见问题解决方案

问题	可能原因	解决方案
模型加载失败	模型文件损坏或路径错误	1. 检查模型文件MD5校验和 2. 验证配置中的模型路径 3. 确保模型文件完整
处理速度慢	资源配置不足	1. 调整批处理大小和工作进程数 2. 关闭不必要的功能 3. 考虑使用GPU加速
内存溢出	文档过大或批处理设置不当	1. 增加系统内存 2. 降低批处理大小 3. 启用内存优化模式
输出格式异常	字体缺失或配置问题	1. 安装必要的字体文件 2. 检查格式转换配置 3. 更新MinerU到最新版本

💡 技巧：建立本地知识库，记录遇到的问题及解决方案，形成组织内部的故障排除指南。

批量处理优化

对于大量文档处理需求，配置自动化批量处理流程，提高处理效率。

# 创建批处理脚本
cat > /opt/mineru/scripts/batch_process.sh << 'EOF'
#!/bin/bash
INPUT_DIR="/opt/documents/input"
OUTPUT_DIR="/opt/documents/output"
PROCESSED_DIR="/opt/documents/processed"

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

# 处理所有未处理的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 "Processing $file..."
    mineru -p "$file" -o "$OUTPUT_DIR/$filename.md"
    # 处理完成后移动源文件
    mv "$file" "$PROCESSED_DIR/"
  fi
done
EOF

# 添加执行权限
chmod +x /opt/mineru/scripts/batch_process.sh

# 设置定时任务
echo "0 2 * * * /opt/mineru/scripts/batch_process.sh >> /var/log/mineru/batch_process.log 2>&1" | crontab -

为什么这么做：定时批量处理可以在系统负载较低的时间段（如夜间）自动处理文档，提高资源利用率和工作效率。

环境差异对照表

操作系统	注意事项	推荐配置
Ubuntu 20.04	需要安装python3.10及对应开发包	内存≥16GB，磁盘≥60GB
CentOS 7	需要启用EPEL仓库，安装额外依赖	内存≥16GB，磁盘≥60GB
Debian 11	自带python3.9，需手动安装python3.10	内存≥16GB，磁盘≥60GB
Windows Subsystem for Linux	注意文件权限和路径格式	内存≥16GB，磁盘≥80GB

问题排查决策树

1. 服务无法启动

   • 检查Docker服务状态 → systemctl status docker
   • 检查容器日志 → docker compose logs mineru
   • 检查配置文件格式 → jsonlint ~/.mineru.json

2. 文档处理失败

   • 检查输入文件是否损坏 → pdfinfo test.pdf
   • 检查模型路径是否正确 → grep "models-dir" ~/.mineru.json
   • 检查内存使用情况 → free -h

3. 输出格式异常

   • 检查输出文件编码 → file -i output.md
   • 尝试不同的输出格式 → mineru -p test.pdf -o output.json
   • 更新MinerU到最新版本 → git pull && docker compose build