MinerU 企业级离线部署指南

环境规划

部署环境评估

在实施MinerU离线部署前，需对目标环境进行全面评估，确保满足系统运行的基础条件。部署环境分为联网准备环境和离线目标环境两个阶段，前者用于资源准备，后者为最终运行环境。

硬件适配建议

硬件配置	最低要求	推荐配置	适用场景
CPU	4核64位处理器	8核或更高	文档处理任务量较小
内存	8GB RAM	16GB RAM	单用户日常使用
存储	40GB可用空间	100GB SSD	包含模型文件和处理缓存
图形加速	可选	NVIDIA GPU (8GB VRAM)	大规模文档处理或包含复杂公式的PDF

[!TIP] 对于仅处理纯文本文档的场景，可采用最低配置；涉及表格识别、公式提取等复杂任务时，建议使用推荐配置。GPU加速可将处理速度提升3-5倍。

软件环境要求

软件	版本要求	作用
Python	3.10.x	运行MinerU核心功能
Docker	20.10.0+	容器化部署支持
Docker Compose	2.0.0+	多容器协调管理
操作系统	Linux (Ubuntu 20.04+/CentOS 8+)	提供稳定运行环境

部署模式决策指引

根据企业实际需求，可选择以下部署模式：

1. 单机部署：适用于小型团队或个人使用，部署简单，资源占用较少
2. 容器化部署：推荐企业环境使用，隔离性好，便于维护和版本控制
3. 分布式部署：适用于超大规模文档处理需求，可横向扩展处理能力

[!TIP] 首次部署建议采用容器化部署模式，平衡部署复杂度和系统稳定性。

资源筹备

资源矩阵表

资源类别	具体内容	获取方式	存储要求	版本控制
源代码	MinerU核心代码	git clone https://gitcode.com/GitHub_Trending/mi/MinerU	~200MB	建议使用v1.4.2稳定版
模型文件	pipeline模型集	模型下载工具	~15GB	记录模型版本号
	VLM模型	模型下载工具	~25GB	记录模型版本号
依赖包	Python依赖	pip下载缓存	~5GB	requirements.txt锁定版本
	系统依赖	系统包管理器	~2GB	记录系统版本
配置文件	基础配置模板	项目内置	<1MB	配置版本与代码版本匹配
文档资料	部署指南	项目docs目录	~50MB	与代码版本同步

前置检查项

• 联网环境具备至少50GB存储空间
• Git工具已安装并配置
• Python环境已准备就绪
• 网络连接稳定，可访问模型下载源

资源获取操作指南

源代码获取

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

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

模型文件下载

# 创建模型存储目录
mkdir -p ./mineru_models_v1.4

# 使用国内源下载所有模型
python -m mineru.cli.models_download \
  -s modelscope \
  -m all \
  --output-path ./mineru_models_v1.4

依赖包缓存

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

# 下载依赖包到本地缓存
pip download -r requirements.txt -d ./offline_deps

[!TIP] 建议对下载的资源进行校验，确保文件完整性。模型文件可通过MD5校验和验证，命令示例：md5sum ./mineru_models_v1.4/*

成功验证标准

• 源代码目录结构完整，无缺失文件
• 模型文件大小与官方说明一致
• 依赖包缓存目录包含所有必需的.whl和.tar.gz文件

部署实施

部署流程图解

图1：MinerU数据处理流程界面 - 展示了文档上传、处理和结果查看的完整流程

环境验证

在离线环境中执行以下命令，验证系统兼容性：

# 验证Python版本
python3 --version | grep "3.10." || { echo "Python版本不兼容"; exit 1; }

# 验证Docker环境
docker --version && docker compose version

# 检查磁盘空间（确保至少有40GB可用空间）
df -h | awk '/\// {print $4 " available on " $NF}'

# 检查内存大小（至少8GB）
free -h | awk '/Mem:/ {print $2 " total memory"}'

成功验证标准

• Python版本输出包含"3.10."
• Docker和Docker Compose命令正常返回版本信息
• 根分区可用空间≥40GB
• 总内存≥8GB

文件传输与准备

将以下资源传输至离线环境目标服务器：

1. 源代码目录（MinerU）
2. 模型文件（mineru_models_v1.4）
3. 依赖包缓存（offline_deps）

# 在离线环境创建工作目录
mkdir -p /opt/mineru/{src,models,deps,config}

# 复制源代码
cp -r ./MinerU /opt/mineru/src/

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

# 复制依赖包
cp -r ./offline_deps /opt/mineru/deps/

依赖安装

# 进入项目目录
cd /opt/mineru/src/MinerU

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

[!TIP] 使用--ignore-installed参数确保依赖版本严格匹配，避免系统已安装包造成版本冲突。

配置文件设置

基础配置

创建基础配置文件/opt/mineru/config/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
  }
}

配置项	说明	推荐值
config_version	配置文件版本号	与软件版本匹配
models-dir.pipeline	pipeline模型存储路径	/opt/mineru/models/pipeline
models-dir.vlm	VLM模型存储路径	/opt/mineru/models/vlm
model-source	模型来源	"local"（离线环境）
logging-level	日志级别	"INFO"（生产环境）
performance.batch-size	批处理大小	2（根据内存调整）
performance.max-workers	工作进程数	4（不超过CPU核心数）

高级调优

对于具备GPU的环境，可添加以下高级配置：

{
  "performance": {
    "gpu-memory-limit": "6G",
    "ocr-threads": 4,
    "table-recognition": {
      "accuracy-mode": "balanced",
      "merge-threshold": 0.3
    }
  },
  "logging": {
    "file-path": "/var/log/mineru",
    "max-size": "100MB",
    "max-backup": 5,
    "format": "json"
  }
}

Docker部署

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

# 启动服务
docker compose up -d

[!TIP] 构建过程可能需要30分钟以上，具体时间取决于硬件配置。首次启动时会初始化模型，可能需要额外时间。

质量验证

功能验证

验证维度	方法	预期结果
版本验证	docker compose exec mineru mineru --version	输出v1.4.2版本信息
基础功能	docker compose exec mineru mineru -h	显示命令帮助信息
文档处理	docker compose exec mineru mineru -p ./tests/unittest/pdfs/test.pdf -o /tmp/test_output.md --device cpu	生成test_output.md文件
输出验证	`cat /tmp/test_output.md	grep "成功"`

性能测试

在不同硬件配置下处理标准测试文档集的性能对比：

配置	纯文本PDF (秒/页)	含表格PDF (秒/页)	含公式PDF (秒/页)
CPU (4核8GB)	1.5	4.2	5.5
CPU (8核16GB)	0.8	2.7	3.9
GPU (8GB VRAM)	0.3	1.2	1.8

[!TIP] 建议创建包含不同类型PDF的测试套件，包括文本密集型、表格丰富型和包含公式的复杂文档，以全面验证系统功能。

部署风险评估

风险类型	可能性	影响	缓解措施
模型文件损坏	中	高	传输后验证MD5校验和
依赖版本冲突	中	高	使用--ignore-installed参数
资源配置不足	高	中	提前进行环境验证
配置文件错误	中	高	使用配置模板并检查关键路径

回滚策略

1. 版本备份：在部署前备份当前版本配置和数据

   # 创建配置备份
   cp /opt/mineru/config/mineru.json /opt/mineru/config/mineru.json.bak
   

2. 镜像保留：保留之前版本的Docker镜像

   # 标记当前镜像
   docker tag mineru:latest mineru:prev_version
   

3. 回滚步骤：

   # 停止当前服务
   docker compose down
   
   # 恢复配置文件
   cp /opt/mineru/config/mineru.json.bak /opt/mineru/config/mineru.json
   
   # 使用之前版本镜像启动
   docker tag mineru:prev_version mineru:latest
   docker compose up -d
   

运维优化

性能优化策略

根据硬件条件和文档类型，调整配置参数以获得最佳性能：

低资源环境优化

{
  "performance": {
    "batch-size": 1,          // 降低批处理大小减少内存占用
    "max-workers": 2,         // 根据CPU核心数调整
    "ocr-threads": 2,         // 减少OCR线程数
    "table-recognition": {
      "accuracy-mode": "speed" // 优先速度模式
    }
  }
}

高资源环境优化

{
  "performance": {
    "batch-size": 4,          // 增加批处理大小
    "max-workers": 8,         // 充分利用CPU核心
    "gpu-memory-limit": "10G", // 分配更多GPU内存
    "table-recognition": {
      "accuracy-mode": "accuracy" // 优先 accuracy模式
    }
  }
}

常见场景解决方案

问题	可能原因	解决方案
模型加载失败	模型文件损坏或路径错误	1. 验证模型文件MD5校验和 2. 检查配置文件中的模型路径 3. 确保模型文件权限正确
处理速度慢	资源配置不足或模式选择不当	1. 调整batch-size和max-workers参数 2. 如使用CPU，切换至"speed"模式 3. 关闭不必要的功能模块
内存溢出	文档过大或批处理设置不当	1. 降低batch-size值 2. 启用内存优化模式 3. 增加系统内存或使用swap
输出格式异常	字体缺失或配置问题	1. 安装必要的字体文件 2. 调整格式转换配置 3. 更新到最新版本

日常维护建议

1. 日志管理：

   # 设置日志轮转
   echo "*/6 * * * * root logrotate /etc/logrotate.d/mineru" >> /etc/crontab
   

2. 定期备份：

   # 创建备份脚本
   cat > /opt/mineru/scripts/backup.sh << 'EOF'
   #!/bin/bash
   BACKUP_DIR="/opt/mineru/backups/$(date +%Y%m%d)"
   mkdir -p $BACKUP_DIR
   cp -r /opt/mineru/config $BACKUP_DIR/
   cp -r /opt/mineru/models $BACKUP_DIR/  # 可选，如模型无更新可省略
   tar -zcvf $BACKUP_DIR.tar.gz $BACKUP_DIR
   rm -rf $BACKUP_DIR
   EOF
   
   # 添加执行权限
   chmod +x /opt/mineru/scripts/backup.sh
   

3. 监控设置：

   # 创建简单监控脚本
   cat > /opt/mineru/scripts/monitor.sh << 'EOF'
   #!/bin/bash
   LOG_FILE="/var/log/mineru/monitor.log"
   TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
   CPU_USAGE=$(top -bn1 | grep "Cpu(s)" | awk '{print $2 + $4}')
   MEM_USAGE=$(free -m | awk '/Mem:/ {print $3/$2 * 100}')
   echo "[$TIMESTAMP] CPU: $CPU_USAGE% MEM: $MEM_USAGE%" >> $LOG_FILE
   EOF
   

批量处理优化

对于需要处理大量文档的场景，建议配置自动化批处理：

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

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

# 处理所有未处理的PDF文件
find $INPUT_DIR -name "*.pdf" -not -name ".*" | while read -r file; do
  filename=$(basename "$file" .pdf)
  log_file="$LOG_DIR/${filename}_$(date +%Y%m%d).log"
  
  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

# 添加到定时任务
echo "0 * * * * root /opt/mineru/scripts/batch_process.sh" >> /etc/crontab

[!TIP] 批处理任务建议在系统负载较低的时间段执行，如夜间或周末，以避免影响日常使用。

API服务配置

启用API服务以支持其他系统集成：

# 配置API服务
docker compose exec mineru \
  mineru api start --host 0.0.0.0 --port 8000 --workers 2

# 验证API服务
curl http://localhost:8000/health | grep "OK" && echo "API服务正常"

API服务配置参数：

参数	说明	推荐值
--host	绑定地址	0.0.0.0（允许外部访问）
--port	服务端口	8000
--workers	工作进程数	2（根据CPU核心数调整）
--timeout	请求超时时间	300秒（处理大型文档时增加）

通过以上部署和优化策略，MinerU可以在离线环境中稳定高效地运行，满足企业级文档处理需求。定期维护和监控将确保系统长期稳定运行，而性能优化策略则可根据实际使用场景进行灵活调整。