Pipeline Backend Processing Window#

Overview#

The processing window is the unit of batched model inference in MinerU's pipeline backend. Rather than processing one page at a time or loading an entire document into memory, the pipeline slices all input pages (across one or more documents) into fixed-size windows and runs each window through all model stages before advancing to the next. This is the primary mechanism by which memory consumption is bounded during large-document processing.

The entry point is doc_analyze_streaming() in pipeline_analyze.py, which drives the window loop.

Window Sizing and Loop Mechanics#

Window size is read from configuration via get_processing_window_size(default=64), making 64 pages the default per window. The env var MINERU_PROCESSING_WINDOW_SIZE overrides this.

The loop in doc_analyze_streaming():

1. Fills the window by consuming pages sequentially from each document context until window_size pages are collected or all documents are exhausted 1.
2. Logs the batch with doc-slice details: batch number, pages in window, and which page ranges belong to which documents 2.
3. Dispatches inference to batch_image_analyze(), which runs the full BatchAnalyze pipeline on the window.
4. Distributes results back to each document's middle_json via append_batch_results_to_middle_json().
5. Finalizes completed documents: if a document's last page was in this window, _finalize_processing_window_context() is called immediately — it runs post-processing and fires the on_doc_ready callback 3.

A window can span multiple documents: pages are drawn from each doc_context in order until batch_capacity reaches zero 1. This allows concurrent multi-doc ingestion with a single batch.

What Happens Inside a Window: BatchAnalyze#

batch_image_analyze() instantiates BatchAnalyze and calls it with the window's images. The BatchAnalyze.__call__() method 4 runs four sequential model stages on all pages in the window:

The batch_ratio multiplier is auto-detected from VRAM in batch_image_analyze(): ≥32 GB → 16, ≥16 GB → 8, ≥8 GB → 4, ≥6 GB → 2, else 1. It can be overridden with MINERU_HYBRID_BATCH_RATIO.

Memory Management Between Stages#

After layout inference and after MFR inference, clean_vram(device, vram_threshold=8) is called to free cached GPU/NPU memory 5. A third clean_vram call follows OCR-det batch processing 6. clean_memory() is called after the entire window completes.

Important caveat: clean_vram only fires when total VRAM ≤ 8 GB. On high-VRAM devices (≥32 GB), this cleanup is skipped entirely unless MINERU_VIRTUAL_VRAM_SIZE=8 is set to spoof the threshold. See Large Document Memory Management for detail.

Peak memory per window scales with MINERU_API_MAX_CONCURRENT_REQUESTS × MINERU_PROCESSING_WINDOW_SIZE. The default (3 concurrent × 64-page window) targets ~32 GB RAM.

Error Handling#

The window loop uses a two-level try/finally pattern:

• Inner finally 7: Always closes and clears images_list for all documents in the current window, regardless of whether batch_image_analyze() succeeded or raised. This prevents PIL image objects from accumulating in memory across failures.
• Outer finally 8: Ensures all pdf_doc pdfium document handles are closed if the loop exits for any reason (exception or normal completion).

If batch_image_analyze() raises, the window's images are still freed (inner finally), but the results are never written to middle_json and on_doc_ready is never called for affected documents. The exception propagates to the caller.

Within BatchAnalyze, individual model stages use try/except only for table orientation classification and table classification, logging warnings and continuing with a fallback rather than aborting 9 10. Layout, MFR, and OCR stages do not have stage-level exception handling — failures propagate immediately and abort the entire window.

Key Configuration#

Source Files#

• mineru/backend/pipeline/pipeline_analyze.py — window loop (doc_analyze_streaming), batch_image_analyze, ModelSingleton
• mineru/backend/pipeline/batch_analyze.py — BatchAnalyze.__call__, per-stage inference and clean_vram call sites
• mineru/utils/model_utils.py — clean_vram, clean_memory, get_vram