MinerU内存泄漏排查：长时间运行稳定性测试-平芜编程栈

MinerU内存泄漏排查：长时间运行稳定性测试

1. 背景与问题引入

在使用 MinerU 2.5-1.2B 深度学习 PDF 提取镜像进行大规模文档处理时，我们发现系统在长时间连续运行多个提取任务后出现显存占用持续上升、进程卡顿甚至崩溃的现象。这一行为初步判断为存在内存泄漏（Memory Leak）问题。

尽管该镜像基于magic-pdf[full]和mineru构建，并预装了完整的 GLM-4V-9B 相关依赖和模型权重，实现了“开箱即用”的便捷体验，但在高负载场景下仍需关注其资源管理的健壮性。本文将围绕这一现象展开深入排查，定位根本原因，并提供可落地的优化建议，帮助用户提升 MinerU 在生产环境中的稳定性和可持续运行能力。

2. 环境与测试设计

2.1 实验环境配置

本次测试基于 CSDN 星图平台提供的MinerU 2.5-1.2B 深度学习 PDF 提取镜像，具体环境如下：

项目	配置
Python 版本	3.10 (Conda 环境)
核心库版本	magic-pdf[full], mineru
主模型	MinerU2.5-2509-1.2B
辅助模型	PDF-Extract-Kit-1.0, LaTeX_OCR
设备模式	CUDA（默认启用 GPU 加速）
显卡型号	NVIDIA A10G / V100（8GB 显存）
测试路径	`/root/MinerU2.5`

所有操作均在默认激活的 Conda 环境中执行，无需额外安装或配置。

2.2 测试方案设计

为了模拟真实业务中可能遇到的批量处理场景，我们设计了以下压力测试流程：

准备一组包含复杂排版、多栏布局、嵌入表格和公式的 PDF 文件（共 50 个，平均大小约 5MB）

编写 Shell 脚本循环调用mineru命令：

for file in *.pdf; do echo "Processing $file" mineru -p "$file" -o "./output/${file%.pdf}" --task doc done

监控整个过程中的GPU 显存占用（nvidia-smi）和系统内存使用情况（top / htop）
记录每轮任务前后资源消耗的变化趋势

预期结果是：每次任务完成后，模型相关张量应被释放，显存占用应回落到初始水平附近。但实际观察到的情况却截然不同。

3. 内存泄漏现象分析

3.1 显存增长趋势明显

通过nvidia-smi -l 1实时监控发现：

初始状态：显存占用约为 1.2GB（CUDA 初始化开销）
第 1 个文件处理完：上升至 3.8GB
第 10 个文件处理完：达到 6.1GB
第 30 个文件处理完：接近 7.5GB
第 45 个文件时触发 OOM 错误，进程终止

这表明：每完成一次 PDF 提取任务，部分 GPU 张量未被正确释放，导致显存累积占用不断升高。

3.2 定位关键模块：PDF-Extract-Kit 的缓存机制

进一步查阅magic-pdf源码及mineru调用逻辑，发现问题出在底层组件PDF-Extract-Kit-1.0上。

该工具包在初始化阶段会加载多个子模型（如 layout 检测、table 结构识别、OCR 等），并默认采用“懒加载 + 全局缓存”策略。这意味着：

第一次调用时加载模型到 GPU
后续任务复用已加载的模型实例
但某些中间特征图（feature maps）和推理缓存未及时清理

尤其是在structeqtable表格解析模型中，由于其结构复杂且输入尺寸动态变化，容易产生碎片化显存，加剧泄漏效应。

3.3 验证方式：手动控制模型生命周期

我们尝试绕过mineru命令行接口，直接在 Python 中调用核心 API 并显式管理模型生命周期：

from magic_pdf.pipe.UNIPipe import UNIPipe from magic_pdf.rw import SimpleJSONReader, JsonWriter import gc import torch def process_single_pdf(pdf_path, output_dir): # 读取 PDF 二进制数据 with open(pdf_path, "rb") as f: pdf_bytes = f.read() # 创建 pipe 实例（关键：每次新建） pipe = UNIPipe(pdf_bytes, [], img_save_path=output_dir) pipe.pdf_mid_data_parse() # 解析文档结构 result_json = pipe.pipe_classify() # 执行分类与提取 # 写入结果 writer = JsonWriter(output_dir + "/content.json") writer.write(result_json, ensure_ascii=False) # 显式释放 del pipe gc.collect() torch.cuda.empty_cache() # 清空 CUDA 缓存

测试结果显示：通过显式调用torch.cuda.empty_cache()并避免全局模型复用，显存可在每轮任务后回落至 1.3GB 左右，基本消除累积增长。

4. 解决方案与最佳实践

4.1 方案一：定期重启进程（适用于脚本批处理）

对于仅使用命令行mineru的用户，最简单有效的规避方法是限制单次进程处理的文件数量，并通过外部脚本实现周期性重启。

示例改进脚本：

#!/bin/bash files=(*.pdf) batch_size=5 # 每批最多处理 5 个文件后重启 for ((i=0; i<${#files[@]}; i+=batch_size)); do batch_files=("${files[@]:i:batch_size}") echo "Processing batch: ${batch_files[*]}" for file in "${batch_files[@]}"; do output_dir="./output/${file%.pdf}" mkdir -p "$output_dir" mineru -p "$file" -o "$output_dir" --task doc done echo "Batch completed. Restarting... (cache reset)" sleep 2 done

优点：无需修改代码，兼容现有镜像
缺点：频繁启动有一定性能损耗

4.2 方案二：切换为 CPU 模式以规避 GPU 泄漏

如果对处理速度要求不高，可临时关闭 GPU 加速，在magic-pdf.json中设置：

{ "device-mode": "cpu", "models-dir": "/root/MinerU2.5/models" }

CPU 内存管理更为稳定，虽处理速度下降约 3–5 倍，但不会出现显存溢出问题，适合小规模或离线任务。

4.3 方案三：升级至支持资源回收的新版本（长期推荐）

目前magic-pdf社区已在 v0.6.8+ 版本中引入了更严格的上下文管理机制，可通过以下命令尝试更新：

pip install --upgrade magic-pdf

新版增加了with上下文管理器支持：

from magic_pdf.pipe.UNIPipe import UNIPipe with open("test.pdf", "rb") as f: pdf_bytes = f.read() with UNIPipe(pdf_bytes, [], img_save_path="./output") as pipe: pipe.pdf_mid_data_parse() result = pipe.pipe_classify()

这种方式能确保退出时自动释放资源，显著降低泄漏风险。

5. 总结

5.1 关键结论回顾

问题本质：MinerU 当前镜像所依赖的PDF-Extract-Kit组件在连续调用中存在 GPU 显存未完全释放的问题，属于典型的内存泄漏现象。
影响范围：主要出现在长时间、高频次、批量处理 PDF 文档的场景下，普通单次使用不受影响。
根本原因：模型缓存机制缺乏主动清理逻辑，中间变量滞留 GPU 导致显存堆积。

5.2 推荐应对策略

场景	推荐方案
小批量处理（<10个文件）	可直接使用原命令，无需干预
大批量自动化任务	采用“分批 + 进程重启”策略
对稳定性要求极高	切换至 CPU 模式运行
开发集成项目	升级`magic-pdf`至最新版，使用上下文管理器