MinerU部署后如何监控？GPU利用率跟踪脚本分享
1. 引言
1.1 业务场景描述
在本地部署 MinerU 2.5-1.2B 深度学习 PDF 提取镜像后，用户能够快速实现复杂排版文档的结构化提取。然而，在实际使用过程中，尤其是批量处理大量 PDF 文件时，模型推理对 GPU 资源的占用情况成为影响效率和稳定性的重要因素。
为了确保系统运行平稳、资源利用合理，并及时发现潜在性能瓶颈，对 GPU 利用率进行持续监控显得尤为关键。特别是在多任务并发或长时间运行服务的场景下，缺乏监控可能导致显存溢出（OOM）、推理延迟上升甚至进程崩溃。
1.2 痛点分析
当前 MinerU 镜像虽已预装 GLM-4V-9B 和 MinerU2.5 模型并支持 CUDA 加速，但默认并未提供资源监控功能。用户在执行mineru -p test.pdf类似命令时：
- 无法直观查看 GPU 使用率、显存占用、温度等关键指标；
- 难以判断是否达到硬件瓶颈；
- 批量处理任务中难以定位某次高负载的具体时间点；
- 缺乏自动化日志记录，不利于后续优化与复盘。
1.3 方案预告
本文将介绍一套轻量级、可落地的GPU 资源监控方案，包含：
- 实时监控脚本编写（基于
nvidia-smi） - 数据采集与日志存储
- 多维度可视化建议
- 与 MinerU 推理流程集成的最佳实践
通过该方案，您可以在不改变原有部署结构的前提下，轻松实现对 MinerU 运行期间 GPU 资源的全面掌控。
2. 技术方案选型
2.1 可选工具对比
| 工具/方法 | 易用性 | 实时性 | 是否需额外安装 | 日志能力 | 适用场景 |
|---|---|---|---|---|---|
nvidia-smiCLI 命令 | ⭐⭐⭐⭐☆ | ⭐⭐⭐⭐ | 否（已预装） | 中等（需脚本配合） | 快速部署、轻量监控 |
| Prometheus + Node Exporter + GPU Plugin | ⭐⭐ | ⭐⭐⭐⭐⭐ | 是 | ⭐⭐⭐⭐⭐ | 生产环境长期监控 |
| Grafana + 插件组合 | ⭐⭐ | ⭐⭐⭐⭐⭐ | 是 | ⭐⭐⭐⭐⭐ | 可视化大屏展示 |
Python 库gpustat | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 是（pip install） | 中等 | Jupyter 或脚本内嵌 |
结论：对于 MinerU 开箱即用镜像环境，推荐采用
nvidia-smi+ Shell 脚本的组合方式。无需额外依赖，兼容性强，适合大多数本地部署用户。
3. 核心实现：GPU 监控脚本详解
3.1 环境准备
MinerU 镜像已内置 NVIDIA 驱动及nvidia-smi工具，无需额外配置。确认可用性：
nvidia-smi预期输出包含 GPU 型号、驱动版本、显存使用情况等信息。
3.2 完整监控脚本
以下是一个生产就绪的 Shell 脚本，用于周期性采集 GPU 状态并记录到日志文件：
#!/bin/bash # gpu_monitor.sh - MinerU GPU Usage Tracker # 功能：每秒采集一次 GPU 状态，记录时间戳、利用率、显存、温度 LOG_DIR="./logs" LOG_FILE="$LOG_DIR/gpu_usage_$(date +%Y%m%d_%H%M%S).log" INTERVAL=1 # 采样间隔（秒） # 创建日志目录 mkdir -p $LOG_DIR # 写入表头 echo "#timestamp,util_gpu(%),util_mem(%),memory_used(MiB),memory_total(MiB),temp(C)" >> $LOG_FILE echo "Starting GPU monitor... Logging to $LOG_FILE" echo "Press Ctrl+C to stop." trap 'echo "Monitoring stopped."; exit 0' INT while true; do # 获取 nvidia-smi 输出（CSV格式） data=$(nvidia-smi --query-gpu=timestamp,utilization.gpu,utilization.memory,memory.used,memory.total,temperature.gpu --format=csv,noheader,nounits) if [ $? -eq 0 ]; then # 清洗数据：去除多余空格，替换分隔符为逗号 cleaned_data=$(echo "$data" | sed 's/ *, */,/g' | sed 's/ *$//') # 添加时间戳前缀并写入日志 echo "$(date '+%Y-%m-%d %H:%M:%S'),$cleaned_data" >> $LOG_FILE else echo "$(date '+%Y-%m-%d %H:%M:%S'),ERROR,FAILED_TO_READ_GPU" >> $LOG_FILE fi sleep $INTERVAL done3.3 脚本说明与解析
（1）字段含义
| 字段 | 说明 |
|---|---|
timestamp | 采集时间（精确到秒） |
util_gpu(%) | GPU 核心利用率百分比 |
util_mem(%) | 显存带宽利用率 |
memory_used(MiB) | 已用显存（MiB） |
memory_total(MiB) | 总显存容量 |
temp(C) | GPU 温度（摄氏度） |
（2）关键命令解释
nvidia-smi --query-gpu=...：指定查询字段--format=csv,noheader,nounits：输出为简洁 CSV 格式sed 's/ *, */,/g'：清理多余空格，保证 CSV 正确分隔trap：捕获中断信号，优雅退出
（3）日志命名策略
日志文件名包含启动时间戳，便于区分不同批次任务：
./logs/gpu_usage_20250405_142310.log4. 实践应用：与 MinerU 推理流程整合
4.1 并行监控模式（推荐）
在运行 MinerU 提取任务的同时，后台启动监控脚本：
# Step 1: 启动 GPU 监控（后台运行） bash gpu_monitor.sh & # 记录 PID，便于后续停止 MONITOR_PID=$! echo "Monitor started with PID: $MONITOR_PID" # Step 2: 执行 MinerU 任务 mineru -p test.pdf -o ./output --task doc # Step 3: 任务完成后终止监控 kill $MONITOR_PID✅优势：完全非侵入式，不影响原流程；适用于单次任务或测试验证。
4.2 批量处理中的监控封装
当需要处理多个 PDF 文件时，可将监控封装为函数：
run_with_monitoring() { local input_pdf=$1 local output_dir=$2 # 启动监控 bash gpu_monitor.sh & MONITOR_PID=$! echo "Processing $input_pdf ..." mineru -p "$input_pdf" -o "$output_dir" --task doc # 结束监控 kill $MONITOR_PID sleep 2 # 等待日志写入完成 } # 批量调用 for pdf in ./batch/*.pdf; do run_with_monitoring "$pdf" "./output/$(basename $pdf .pdf)" done5. 数据分析与可视化建议
5.1 日志示例
#timestamp,util_gpu(%),util_mem(%),memory_used(MiB),memory_total(MiB),temp(C) 2025-04-05 14:23:10,67,82,6845,10240,68 2025-04-05 14:23:11,71,85,6845,10240,68 2025-04-05 14:23:12,75,88,6845,10240,69 ...5.2 使用 Python 进行简单绘图
保存以下代码为plot_gpu.py，可生成利用率趋势图：
import pandas as pd import matplotlib.pyplot as plt # 读取日志（跳过注释行） df = pd.read_csv('logs/gpu_usage_20250405_142310.log', comment='#') # 时间列作为索引 df['timestamp'] = pd.to_datetime(df['timestamp']) df.set_index('timestamp', inplace=True) # 绘图 fig, ax1 = plt.subplots(figsize=(12, 6)) ax1.plot(df.index, df['util_gpu(%)'], label='GPU Util (%)', color='tab:blue') ax1.plot(df.index, df['util_mem(%)'], label='Memory Util (%)', color='tab:cyan') ax1.set_ylabel('Utilization (%)') ax1.tick_params(axis='y') ax1.legend(loc='upper left') ax2 = ax1.twinx() ax2.plot(df.index, df['memory_used(MiB)'], label='Memory Used (MiB)', color='tab:orange') ax2.set_ylabel('Memory Usage (MiB)') ax2.legend(loc='upper right') plt.title('MinerU GPU Resource Usage During PDF Extraction') plt.tight_layout() plt.savefig('gpu_usage_trend.png', dpi=150) plt.show()5.3 可视化洞察示例
通过图表可以清晰识别：
- 峰值利用率时段：对应公式识别或表格重建阶段；
- 显存稳定区间：判断是否接近上限；
- 异常波动：如突然降为 0，可能表示进程崩溃。
6. 常见问题与优化建议
6.1 常见问题解答
Q1：为什么nvidia-smi报错“NVIDIA-SMI has failed”?
A：请确认容器是否以--gpus all启动，并检查宿主机驱动状态。
Q2：日志中出现大量 ERROR 条目？
A：可能是采样频率过高导致nvidia-smi调用冲突，建议将INTERVAL改为 2 秒以上。
Q3：显存未释放？
A：MinerU 使用 PyTorch 模型，若程序异常退出可能导致缓存未清。可手动执行：
pkill python # 或重启容器6.2 性能优化建议
- 调整采样频率：普通监控设为 2~5 秒即可，避免 I/O 压力。
- 限制日志大小：添加日志轮转机制，防止磁盘占满：
# 示例：保留最近 10 个日志文件 find $LOG_DIR -name "gpu_usage_*.log" | head -n -10 | xargs rm -f - 结合
tmux或screen使用：长时间任务可在会话中保持监控运行。
7. 总结
7.1 实践经验总结
本文围绕 MinerU 2.5-1.2B 深度学习 PDF 提取镜像的实际使用需求，提出了一套轻量、高效、无需外部依赖的 GPU 资源监控方案。通过一个简单的 Shell 脚本，即可实现对 GPU 利用率、显存占用、温度等关键指标的持续跟踪。
核心价值在于：
- 零成本接入：仅依赖系统自带
nvidia-smi； - 高实用性：适用于单次测试、批量处理、服务化部署等多种场景；
- 可扩展性强：日志格式标准化，易于对接后续分析与告警系统。
7.2 最佳实践建议
- 每次重要任务都应伴随监控，尤其在首次处理新类型文档时；
- 定期检查日志趋势，建立典型任务的资源消耗基线；
- 结合硬件条件合理调度任务，避免因显存不足导致失败。
掌握资源使用规律，是提升 MinerU 使用效率和稳定性的关键一步。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
