MinerU PDF Parsing#

RAGFlow integrates with MinerU as one of several selectable PDF parse backends (alongside deepdoc, docling, opendataloader, and others) 1. MinerU runs as a separate API server; RAGFlow posts PDF files to it via POST /file_parse and receives a ZIP archive containing content_list.json, middle.json, and page images 2.

The core implementation lives in deepdoc/parser/mineru_parser.py (MinerUParser class), which extends RAGFlowPdfParser. The entry point for document processing is parse_pdf(), which:

1. Accepts OCR language, parse method (auto/txt/ocr), formula/table flags from parser_config 3
2. Writes the PDF to a temp file if binary is provided 4
3. Calls _run_mineru_api() to POST to the MinerU API server and stream back the ZIP 5
4. Reads *_content_list.json from the ZIP via _read_output() 6
5. Converts content blocks to RAGFlow sections via _transfer_to_sections()

MinerU output bounding boxes are in 0–1000 normalized coordinates. _line_tag() converts these to pixel coordinates by scaling against rendered page image size, and swaps inverted coordinates (x0 > x1, top > bott) that MinerU sometimes emits for rotated pages 7.

Supported backends are enumerated in MinerUBackend: pipeline (default multimodel), several vlm-* variants (HuggingFace Transformers, vLLM, MLX, LMDeploy), and vlm-http-client for remote VLM servers. The vlm-http-client backend additionally requires MINERU_SERVER_URL 8.

Page Range Forwarding#

Problem#

RAGFlow's task dispatcher (in api/db/services/task_service.py) splits large PDFs into multiple page-range sub-tasks, each with a from_page/to_page window. These values are passed through to by_mineru() in rag/app/naive.py via the PARSERS registry call in the task executor 9. However, in the baseline implementation, by_mineru() accepted from_page/to_page in its signature but did not forward them to parse_pdf() or the MinerU API request 10. The API request payload hardcoded start_page_id: 0 and end_page_id: 99999 11, so every page-range sub-task triggered a full-document parse—inflating chunk counts to N× the real count for an N-task document.

Fixes#

Multiple PRs addressed this across successive iterations:

• PR #16957 threaded page_from/page_to through the call chain: by_mineru() → parse_pdf() → _run_mineru() → _run_mineru_api(), and wired them into the API payload as start_page_id and end_page_id. RAGFlow uses an exclusive to_page (Python slice semantics); MinerU's end_page_id is 0-based inclusive, so the conversion is end_page_id = page_to - 1 (or 99999 when page_to == MAXIMUM_PAGE_NUMBER) 12.

• PR #16857 made the same fix as part of a broader cross-parser patch covering Docling and OpenDataLoader as well. It added an additional correction: because MinerU pre-slices the PDF before analysis, returned page_idx values are relative to the slice start. The fix offsets each output's page_idx by start_page_id to restore absolute document-level page numbers for downstream position tagging and chunk storage 13.

• PR #16600 (earlier iteration) also tackled the same gap, adding start_page_id/end_page_id to MinerUParseOptions and updating by_mineru(). It also handled a MinerU version difference: some versions return page_idx relative to the slice start, others use absolute page numbers—detected by inspecting whether the minimum returned page_idx >= start_page_id 14.

Page Index Semantics#

Deduplication / Redundant Re-parsing#

Before the page range fixes, every page-range task for a given PDF independently called the MinerU API with the full document — O(N) redundant full-document parses for an N-task PDF. There is no output caching in the current architecture: each parse_pdf() invocation creates a fresh tempfile.mkdtemp() directory, and the MinerU API server does not deduplicate requests 15.

The deduplication strategy adopted by the fix PRs is input narrowing rather than output caching: pass the exact from_page/to_page window to the MinerU API, so the server only parses and returns content for the requested page slice. Each sub-task sends a smaller payload and receives a smaller result—avoiding redundant work by construction. Task-level result reuse (matching chunks from prior runs via task digest) is handled separately at the task executor layer and is not specific to MinerU.

Key Files & References#

Related PRs:

• PR #16957 — Page range threading into MinerU API request (focused fix)
• PR #16857 — Cross-parser page range fix (MinerU + Docling + OpenDataLoader)
• PR #16600 — Earlier MinerU page range fix with version-detection logic
• PR #16283 — MinerU middle.json cross-page table reconstruction