minerU-api 本地化部署调用几次后总是 out of memory

[verigle]

🔎 Search before asking | 提交之前请先搜索

• I have searched the MinerU Readme and found no similar bug report.
• I have searched the MinerU Issues and found no similar bug report.
• I have searched the MinerU Discussions and found no similar bug report.

🤖 Consult the online AI assistant for assistance | 在线 AI 助手咨询

• I have consulted the online AI assistant but was unable to obtain a solution to the issue.

Description of the bug | 错误描述

多调用几次 mineru-api 的接口， 显存会一直增加

How to reproduce the bug | 如何复现

使用 docker/compose.yml 启动
在 2卡 16GB 显存GPU上
使用 docker compose -f docker/compose.yml up -d

Operating System Mode | 操作系统类型

Linux

Operating System Version| 操作系统版本

Ubuntu22.04

Python version | Python 版本

3.10

Software version | 软件版本 (mineru --version)

>=2.5

Backend name | 解析后端

vlm

Device mode | 设备模式

cuda

[dosubot]

你遇到的 mineru-api 显存持续增长、最终 OOM 的问题，是 MinerU 在 vlm（尤其是 vllm-engine）后端的已知设计限制。根本原因是模型实例采用了单例缓存（ModelSingleton），模型（如 vllm.LLM）会常驻进程，clean_memory 只能清理 PyTorch 缓存，无法释放单例中的模型引用，导致每次处理 PDF 后显存不会完全释放，只有重启进程或手动清空单例缓存才会彻底释放显存 [分析1][分析2]。

有效缓解方案：

1. 定期重启 mineru-api 服务，彻底释放显存。
2. 推荐使用“两进程模式”：mineru-vllm-server + vlm-http-client，推理进程挂掉或重启不会影响主服务，显存释放更彻底 [方案]。
3. 设置环境变量 MINERU_VIRTUAL_VRAM_SIZE（如 8 或 12），并在启动参数中加 --gpu-memory-utilization 0.4（或更低），限制单进程显存占用 [方案][compose配置]。
4. 大 PDF 建议分批处理（如用 start_page_id、end_page_id 或 CLI 的 --start、--end、--max-convert-pages），避免一次性加载过多页面 [方案]。
5. 用 nvidia-smi、top 等工具监控显存，必要时手动清理或重启服务。

配置举例（docker/compose.yml）：

environment:
  MINERU_VIRTUAL_VRAM_SIZE: "8"
command:
  --engine vllm
  --gpu-memory-utilization 0.4
  # --data-parallel-size 2  # 多卡并行

注意事项：

• 2.5.x 及以上版本 VLM 后端采用两阶段推理，显存需求比老版本高，目前没有参数能彻底优化 VLM 的两阶段推理显存，只能通过分批处理和进程管理规避 [说明]。
• 近期版本（如 2.6.6）增加了并发控制、显存检测和日志优化，但未改变单例模型常驻的机制 [PR#4105]。
• 如果需要更细粒度的显存释放，需关注后续 MinerU 版本或自行扩展代码，增加显式清空单例缓存的能力 [说明]。

如需进一步排查，建议结合日志、nvidia-smi 监控具体显存变化，确认是否为上述单例缓存问题导致。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[lc345]

我们也遇到了，希望下个版本可以修复这个问题，我们目前只能减少worker数量，减少gpu占用百分比，多预留显存

[JevonXing]

相比于显存，内存泄露的不是更快么

[lc345]

相比于显存，内存泄露的不是更快么

看了下确实内存也逐渐上涨，不做处理的话就是自己oom。大家有什么好的办法吗？

[JevonXing]

相比于显存，内存泄露的不是更快么

看了下确实内存也逐渐上涨，不做处理的话就是自己oom。大家有什么好的办法吗？

我们暂时也没解决，用的很难受

[lc345]

相比于显存，内存泄露的不是更快么

看了下确实内存也逐渐上涨，不做处理的话就是自己oom。大家有什么好的办法吗？

我们暂时也没解决，用的很难受

如果oom了失败就重新请求，应该会重新拉起，就是重启的第一次会慢一点。我们准备这么处理，然后等着修复了。

[lc345]

相比于显存，内存泄露的不是更快么

看了下确实内存也逐渐上涨，不做处理的话就是自己oom。大家有什么好的办法吗？

我们暂时也没解决，用的很难受

如果oom了失败就重新请求，应该会重新拉起，就是重启的第一次会慢一点。我们准备这么处理，然后等着修复了。
这个方案还是不行，等官方吧还是