MinerU 离线部署全流程指南：从环境评估到优化落地

引言

MinerU 作为一站式开源高质量数据提取工具，能够将 PDF 转换成 Markdown 和 JSON 格式，在离线环境下的部署需要系统性的规划与执行。本文将按照"环境评估→资源筹备→部署实施→验证优化"的四阶段递进结构，为您提供专业、易懂且实操性强的技术部署指南，帮助您顺利完成 MinerU 的离线部署工作。

一、环境评估：奠定部署基础

环境评估是离线部署的首要环节，旨在全面了解目标环境的硬件条件、软件配置及网络状况，为后续部署工作提供决策依据。此阶段预计耗时 30 分钟。

1.1 硬件资源检查

硬件是 MinerU 运行的基础，需确保目标环境满足基本要求。

内存检查：MinerU 至少需要 8GB RAM，推荐 16GB 以保证流畅运行。可通过以下命令检查内存大小：

free -h | awk '/Mem:/ {print $2 " total memory"}'

若内存不足，需考虑升级硬件或调整后续部署策略以降低资源占用。

磁盘空间检查：至少需要 40GB 可用磁盘空间用于存储源代码、模型文件及依赖包等。执行以下命令检查磁盘空间：

df -h | awk '/\// {print $4 " available on " $NF}'

确保目标分区有足够的可用空间，避免因空间不足导致部署失败。

CPU/GPU 环境检查：MinerU 支持在 CPU 或 GPU 环境下运行，若使用 Docker 部署，需确保环境支持 Docker。检查 Docker 环境命令如下：

docker --version && docker compose version

若输出 Docker 及 Docker Compose 版本信息，则说明环境支持；否则需先安装 Docker。

1.2 软件环境验证

软件环境的兼容性直接影响 MinerU 的正常运行，需重点验证 Python 版本。

Python 版本验证：MinerU 对 Python 版本有特定要求，推荐使用 Python 3.10.x。通过以下命令检查 Python 版本：

python3 --version | grep "3.10." || echo "Python版本不兼容"

若输出 Python 3.10.x 版本信息，则版本兼容；否则需安装或升级 Python 至指定版本。

1.3 网络环境确认

离线部署意味着无法直接连接互联网获取资源，需提前确认目标环境的网络隔离情况，确保后续资源传输方案的可行性。同时，记录联网环境的配置信息，以便在联网环境中完成资源筹备工作。

1.4 环境适配建议

针对不同硬件配置，提供差异化部署策略：

• 低配环境（8GB RAM，无GPU）：降低批处理大小，减少并行任务数量，关闭部分非核心功能，优先保证基本转换功能的实现。
• 标准环境（16GB RAM，可选GPU）：采用默认配置，可适当开启部分优化功能，平衡性能与资源占用。
• 高配环境（32GB+ RAM，高性能GPU）：可增加批处理大小，启用更多高级功能，如复杂表格识别、公式提取等，以提高处理效率。

二、资源筹备：确保部署物资齐全

资源筹备是离线部署的关键步骤，需在联网环境中完成所有必要资源的获取与整理，为后续部署实施提供充足的"弹药"。此阶段预计耗时 1-2 小时，具体取决于网络速度。

2.1 源代码获取

获取 MinerU 源代码是部署的第一步。在联网环境中，通过 Git 克隆项目仓库：

git clone https://gitcode.com/GitHub_Trending/mi/MinerU.git
cd MinerU

为保证版本稳定性，建议切换到稳定版本，而非直接使用 main 分支：

git checkout v1.4.2  # 请根据实际稳定版本号调整

2.2 模型文件下载

MinerU 依赖 pipeline 和 VLM 模型进行数据提取，需下载完整的模型文件集合。使用国内源加速下载可提高效率：

python -m mineru.cli.models_download -s modelscope -m all \
  --output-path ./mineru_models_v1.4  # 指定模型存储路径，便于管理和后续传输

下载完成后，妥善保存模型文件，确保文件完整无损坏。

2.3 依赖包缓存

提前缓存 Python 和系统依赖包，以便在离线环境中安装。可通过以下方式获取依赖包：

# 在联网环境中创建依赖包缓存目录
mkdir -p ./offline_deps
pip download -r requirements.txt -d ./offline_deps

此命令会将项目所需的依赖包下载到 ./offline_deps 目录中，方便后续传输到离线环境。

2.4 Docker 相关文件准备

收集 Docker 构建文件和配置，包括项目中的 docker 目录下的相关文件，如 Dockerfile、compose.yaml 等，确保在离线环境中能够顺利构建 Docker 镜像。

三、部署实施：精细操作确保成功

部署实施阶段是将筹备好的资源在离线环境中进行配置、安装和启动的过程，需要严格按照步骤操作，确保每个环节准确无误。此阶段预计耗时 1-1.5 小时。

3.1 文件传输与准备

将在联网环境中准备好的以下文件传输到离线环境：

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

可使用可移动存储介质（如 USB drive）进行传输，传输完成后，将文件放置在合适的位置，如 /opt/mineru 目录下。

3.2 依赖包安装

在离线环境中安装依赖包，确保 MinerU 运行所需的库文件正确安装。

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

# 复制依赖包到目标位置（假设通过 USB 传输）
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  # 忽略已安装的包，确保版本一致性

3.3 配置模型路径

创建 MinerU 配置文件，指定本地模型路径，使 MinerU 能够找到离线模型。

// ~/.mineru.json - MinerU 配置文件
{
  "config_version": "1.4.0",          // 配置文件版本号，需与 MinerU 版本匹配
  "models-dir": {
    "pipeline": "/opt/mineru/models/pipeline",  // 本地 pipeline 模型路径
    "vlm": "/opt/mineru/models/vlm"             // 本地 VLM 模型路径
  },
  "model-source": "local",            // 指定使用本地模型，而非从网络获取
  "logging-level": "INFO",            // 日志级别，生产环境建议使用 INFO
  "performance": {
    "batch-size": 2,                  // 批处理大小，根据内存调整，低配环境可设为 1
    "max-workers": 4                  // 工作进程数，不超过 CPU 核心数
  }
}

3.4 Docker 部署

使用 Docker 部署可简化环境配置，提高部署一致性。

# 构建 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

四、验证优化：保障系统稳定高效运行

部署完成后，需进行全面验证以确保系统功能正常，并根据实际运行情况进行优化，提升系统性能与可靠性。此阶段预计耗时 30 分钟。

4.1 基本功能验证

验证 MinerU 是否成功部署，基本功能是否正常。

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

# 运行测试文档处理
docker compose exec mineru \
  mineru -p ./tests/unittest/pdfs/test.pdf \  # 测试 PDF 文件路径
  -o /tmp/test_output.md \  # 输出文件路径
  --device cpu  # 如果没有 GPU，强制使用 CPU

检查输出结果是否符合预期：

cat /tmp/test_output.md | grep "成功" && echo "测试通过"

若输出"测试通过"，则说明基本功能正常。

4.2 性能优化

根据硬件配置和实际需求，调整 MinerU 的性能参数，以达到最佳运行效果。

{
  "performance": {
    "batch-size": 1,          // 降低批处理大小减少内存占用，适用于低配环境
    "max-workers": 2,         // 根据 CPU 核心数调整工作进程
    "gpu-memory-limit": "6G", // 限制 GPU 内存使用（如有 GPU）
    "ocr-threads": 4,         // OCR 处理线程数
    "table-recognition": {
      "accuracy-mode": "balanced", // 表格识别模式：speed/balanced/accuracy
      "merge-threshold": 0.3       // 表格单元格合并阈值
    }
  }
}

4.3 日志管理与故障排除

配置详细的日志记录，便于问题诊断和系统监控。

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

常见问题及解决方案：

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

4.4 部署经验总结

• 版本管理：建立清晰的版本管理机制，记录部署的所有组件版本，如 MinerU 版本、模型版本、依赖包版本等，便于后续维护和追溯。
• 备份策略：定期备份配置文件、模型文件及重要数据，以防数据丢失或系统故障。
• 更新流程：设计合理的离线更新流程，在隔离的联网环境中准备更新包，测试通过后再传输到离线环境进行更新。
• 文档完善：记录部署过程中的问题及解决方案，形成内部知识库，为后续部署和维护提供参考。

上图展示了 MinerU 的数据处理流程界面，您可以参考此流程来验证部署效果，重点关注文件上传、处理状态和结果展示等核心功能。通过以上四个阶段的操作，您已成功完成 MinerU 的离线部署，并具备了对系统进行优化和维护的能力。