VRAM Requirements for MinerU's VLM Backend: Complete Hardware Guide

MinerU's Vision-Language Model (VLM) backend requires a minimum of 8 GB VRAM for standard operation, with 10 GB recommended when enabling full table acceleration features.

The opendatalab/MinerU project provides document parsing capabilities through multiple VLM acceleration backends. Understanding the VRAM requirements ensures optimal deployment whether you're running local inference, Docker containers, or full-featured extraction pipelines.

Minimum VRAM Requirements for MinerU VLM

The codebase explicitly defines VRAM thresholds across different deployment scenarios in the documentation and utility modules.

Base VLM Backend (vLLM and LMDeploy)

Both the vLLM and LMDeploy acceleration modules require 8 GB+ VRAM on GPUs with Volta architecture or newer. This requirement is documented in docs/en/quick_start/extension_modules.md and enforced through environment detection in mineru/utils/model_utils.py.

Docker Deployment Requirements

Containerized deployments maintain the same baseline. The Docker quick-start guide in docs/en/quick_start/docker_deployment.md specifies 8 GB VRAM (Volta or newer) as the minimum for running the VLM backend within containers.

Full-Feature Acceleration with Table Support

While basic VLM operations run on 8 GB, enabling all acceleration modules including table recognition requires additional memory:

• Standard features (layout, formula, OCR): 8 GB VRAM
• With table acceleration: 10 GB VRAM

Recent memory optimizations in the codebase reduced the upper requirement from 24 GB to 10 GB, as noted in docs/zh/reference/changelog.md.

SGLang Backend Support

The VLM-sglang backend supports GPUs with Turing architecture or newer, requiring 8 GB VRAM minimum. This is documented in docs/en/reference/changelog.md.

How MinerU Manages VRAM Automatically

The codebase implements automatic VRAM detection and batch size adjustment to prevent out-of-memory errors.

In mineru/utils/model_utils.py, the system reads the MINERU_VIRTUAL_VRAM_SIZE environment variable to determine available memory. If unset, it falls back to hardware detection.

The get_batch_ratio function in mineru/backend/vlm/utils.py calculates appropriate batch sizes based on detected VRAM, automatically scaling processing to fit within available memory constraints.

Configuring VRAM Limits Manually

You can override automatic detection when running on shared GPUs or constrained environments.

Environment Variable Configuration

Set the virtual VRAM size before starting the server:

# Limit MinerU to use 8 GB VRAM calculations

export MINERU_VIRTUAL_VRAM_SIZE=8
mineru vlm_server

Programmatic Batch Ratio Adjustment

For advanced use cases, access the batch ratio calculator directly:

from mineru.backend.vlm.utils import get_batch_ratio

# Get optimized batch ratio for specific device

device = "cuda:0"
batch_ratio = get_batch_ratio(device)
print(f"Batch ratio for {device}: {batch_ratio}")

Summary

• Minimum VRAM: 8 GB required for all VLM backends (vLLM, LMDeploy, SGLang)
• Recommended VRAM: 10 GB when enabling table acceleration features
• Architecture: Volta or newer for most backends; Turing or newer for SGLang
• Configuration: Use MINERU_VIRTUAL_VRAM_SIZE environment variable to override auto-detection in mineru/utils/model_utils.py
• Optimization: The get_batch_ratio function in mineru/backend/vlm/utils.py automatically adjusts batch sizes based on available VRAM

Frequently Asked Questions

Can I run MinerU's VLM backend with less than 8 GB VRAM?

No. The codebase explicitly requires 8 GB minimum VRAM for all VLM acceleration backends. Attempting to run with less memory will result in initialization failures or out-of-memory errors during document processing, as the model weights and inference buffers exceed available capacity.

What GPU architecture is required for MinerU VLM acceleration?

Most VLM backends (vLLM and LMDeploy) require Volta architecture or newer (compute capability 7.0+). The SGLang backend specifically requires Turing or newer (compute capability 7.5+). These requirements are documented in docs/en/quick_start/extension_modules.md and docs/en/reference/changelog.md.

How do I check if MinerU is using my available VRAM efficiently?

Monitor the MINERU_VIRTUAL_VRAM_SIZE environment variable setting and review the automatic batch ratio calculations in mineru/backend/vlm/utils.py. The get_batch_ratio function adjusts processing batches based on detected hardware. If you notice out-of-memory errors despite having sufficient VRAM, verify that MINERU_VIRTUAL_VRAM_SIZE matches your actual GPU memory.

Does enabling table acceleration significantly increase VRAM usage?

Yes. While basic VLM features (layout analysis, formula recognition, and OCR) run on 8 GB VRAM, enabling table acceleration increases the requirement to 10 GB. Previous versions required up to 24 GB for table features, but recent optimizations in the codebase reduced this threshold as documented in docs/zh/reference/changelog.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}