Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(mineru): Fix MinerU Rendering Stability, Error Visibility, and Code Block Parsing Issues (#18617)

Aeovy5b3a66fd8c86
diff --git a/api/db/services/task_service.py b/api/db/services/task_service.py
index 462dad63ce..683ab2d244 100644
--- a/api/db/services/task_service.py
+++ b/api/db/services/task_service.py
@@ -25,6 +25,7 @@ from peewee import JOIN
from api.db.db_models import DB, File2Document, File
from api.db import FileType
from api.db.db_models import Task, Document, Knowledgebase, Tenant
+from api.db.joint_services.tenant_model_service import get_composite_model_name_by_id
from api.db.services.common_service import CommonService
from api.db.services.document_service import DocumentService
from common.misc_utils import get_uuid
@@ -477,7 +478,20 @@ def queue_tasks(doc: dict, bucket: str, name: str, priority: int):
page_size = doc["parser_config"].get("task_page_size") or 12
if doc["parser_id"] == "paper":
page_size = doc["parser_config"].get("task_page_size") or 22
- if doc["parser_id"] in ["one", "knowledge_graph"] or doc["parser_config"].get("toc_extraction", False):
+
+ # Splitting MinerU parsing into page-based tasks would repeatedly upload the entire PDF to the MinerU API server, increasing network bandwidth usage without improving parsing speed. The MinerU API server would also store duplicate copies of these files, wasting disk space.
+ is_mineru = False
+ layout_recognizer = doc["parser_config"].get("layout_recognize", "")
+ if isinstance(layout_recognizer, str) and len(layout_recognizer) == 32:
+ try:
+ layout_recognizer = get_composite_model_name_by_id(layout_recognizer)
+ if layout_recognizer.lower().endswith("@mineru"):
+ is_mineru = True
+ except LookupError:
+ pass
+ if is_mineru:
+ logging.info("Document %s selected MinerU unsplit-task mode with page size %s", doc["id"], MAXIMUM_TASK_PAGE_NUMBER)
+ if doc["parser_id"] in ["one", "knowledge_graph"] or doc["parser_config"].get("toc_extraction", False) or is_mineru:
page_size = MAXIMUM_TASK_PAGE_NUMBER
page_ranges = doc["parser_config"].get("pages") or [(1, MAXIMUM_PAGE_NUMBER)]
for s, e in page_ranges:
diff --git a/deepdoc/parser/mineru_parser.py b/deepdoc/parser/mineru_parser.py
index 71f688f1d0..373d0e2c6d 100644
--- a/deepdoc/parser/mineru_parser.py
+++ b/deepdoc/parser/mineru_parser.py
@@ -146,6 +146,8 @@ class MinerUParser(RAGFlowPdfParser):
self.mineru_api = mineru_api.rstrip("/")
self.mineru_server_url = mineru_server_url.rstrip("/")
self.outlines = []
+ self.page_from = 0
+ self.page_to = MAXIMUM_PAGE_NUMBER
self.logger = logging.getLogger(self.__class__.__name__)
@staticmethod
@@ -354,14 +356,24 @@ class MinerUParser(RAGFlowPdfParser):
def __images__(self, fnm, zoomin: int = 1, page_from=0, page_to=MAXIMUM_PAGE_NUMBER, callback=None):
self.page_from = page_from
self.page_to = page_to
+ if callback:
+ callback(0.16, "[MinerU] Rendering PDF pages...")
try:
- with pdfplumber.open(fnm) if isinstance(fnm, (str, PathLike)) else pdfplumber.open(BytesIO(fnm)) as pdf:
- self.pdf = pdf
- self.page_images = [p.to_image(resolution=72 * zoomin, antialias=True).original for _, p in enumerate(self.pdf.pages[page_from:page_to])]
+ with sys.modules[LOCK_KEY_pdfplumber]:
+ with pdfplumber.open(fnm) if isinstance(fnm, (str, PathLike)) else pdfplumber.open(BytesIO(fnm)) as pdf:
+ self.pdf = pdf
+ self.page_images = [p.to_image(resolution=72 * zoomin, antialias=True).original for _, p in enumerate(self.pdf.pages[page_from:page_to])]
except Exception as e:
self.page_images = None
self.total_page = 0
- self.logger.exception(e)
+ self.logger.exception("[MinerU] PDF page rendering failed for pages %s:%s: %s", page_from, page_to, e)
+ if callback:
+ callback(0.16, f"[MinerU] PDF page rendering failed for pages {page_from}:{page_to}: {e}")
+ else:
+ # Report success only after every selected page rendered successfully.
+ self.logger.info("[MinerU] Rendered %d PDF page images.", len(self.page_images))
+ if callback:
+ callback(0.19, f"[MinerU] Rendered {len(self.page_images)} PDF page images.")
@staticmethod
def _normalize_bbox(bbox):
@@ -858,7 +870,17 @@ class MinerUParser(RAGFlowPdfParser):
case MinerUContentType.EQUATION:
section = output.get("text", "")
case MinerUContentType.CODE:
- section = output.get("code_body", "") + "\n".join(output.get("code_caption", []))
+ code_body = output.get("code_body", "")
+ code_caption = "\n".join(output.get("code_caption", []))
+ if code_caption:
+ # MinerU VLM returns a fenced body while the pipeline backend
+ # may return plain code. Replace only one complete outer fence.
+ outer_fence = re.fullmatch(r"```[^`\r\n]*\r?\n(?P<body>.*)\r?\n```", code_body, flags=re.DOTALL)
+ if outer_fence:
+ code_body = outer_fence.group("body")
+ section = f"```{code_caption}\n{code_body}\n```"
+ else:
+ section = code_body
case MinerUContentType.LIST:
section = "\n".join(output.get("list_items", []))
case MinerUContentType.HEADER | MinerUContentType.FOOTER | MinerUContentType.PAGE_NUMBER | MinerUContentType.DISCARDED:
@@ -899,7 +921,9 @@ class MinerUParser(RAGFlowPdfParser):
continue
position_tag = self._line_tag(output) if "page_idx" in output and "bbox" in output else ""
- positions = [(page, left, right, top, bottom) for pages, left, right, top, bottom in self.extract_positions(position_tag) for page in pages]
+ # MinerU numbers pages from zero within the selected PDF slice.
+ # Media positions leave the parser in the document-global domain.
+ positions = [(page + self.page_from, left, right, top, bottom) for pages, left, right, top, bottom in self.extract_positions(position_tag) for page in pages]
if output_type == MinerUContentType.TABLE:
text = output.get("table_body", "") + "\n".join(output.get("table_caption", [])) + "\n".join(output.get("table_footnote", []))
@@ -1030,7 +1054,7 @@ class MinerUParser(RAGFlowPdfParser):
if callback:
callback(0.15, f"[MinerU] Output directory: {out_dir}")
- self.__images__(pdf, zoomin=1)
+ self.__images__(pdf, zoomin=1, page_from=page_from, page_to=page_to, callback=callback)
try:
options = MinerUParseOptions(
diff --git a/rag/app/manual.py b/rag/app/manual.py
index bcaa3b37d0..65743ecbbd 100644
--- a/rag/app/manual.py
+++ b/rag/app/manual.py
@@ -249,6 +249,10 @@ def chunk(filename, binary=None, from_page=0, to_page=MAXIMUM_PAGE_NUMBER, lang=
def tag(pn, left, right, top, bottom):
if pn + left + right + top + bottom == 0:
return ""
+ if name == "mineru":
+ # MinerU tags stay local and one-based for crop(); crop() adds
+ # the task's page offset when it emits final positions.
+ pn += 1
return "@@{}\t{:.1f}\t{:.1f}\t{:.1f}\t{:.1f}##".format(pn, left, right, top, bottom)
chunks = []
diff --git a/rag/app/naive.py b/rag/app/naive.py
index 91fc4ff079..dd9ad04cbf 100644
--- a/rag/app/naive.py
+++ b/rag/app/naive.py
@@ -245,10 +245,9 @@ def by_mineru(
return sections, tables, pdf_parser
except Exception as e:
logging.error(f"Failed to parse pdf via LLMBundle MinerU ({mineru_llm_name}): {e}")
+ raise
- if callback:
- callback(-1, "MinerU not found.")
- return None, None, None
+ raise RuntimeError("MinerU model not found or not configured.")
def by_docling(filename, binary=None, from_page=0, to_page=MAXIMUM_PAGE_NUMBER, lang="Chinese", callback=None, pdf_cls=None, **kwargs):
@@ -1158,7 +1157,12 @@ def chunk(filename, binary=None, from_page=0, to_page=MAXIMUM_PAGE_NUMBER, lang=
return []
if table_context_size or image_context_size:
- tables = append_context2table_image4pdf(sections, tables, image_context_size)
+ tables = append_context2table_image4pdf(
+ sections,
+ tables,
+ image_context_size,
+ section_page_offset=from_page if name == "mineru" else 0,
+ )
if name in ["tcadp", "docling", "mineru", "paddleocr", "opendataloader", "somark", "mistral ocr"]:
if int(parser_config.get("chunk_token_num", 0)) <= 0:
diff --git a/rag/nlp/__init__.py b/rag/nlp/__init__.py
index dfa41f6e57..fe625b01fa 100644
--- a/rag/nlp/__init__.py
+++ b/rag/nlp/__init__.py
@@ -826,7 +826,7 @@ def attach_media_context(chunks, table_context_size=0, image_context_size=0):
return chunks
-def append_context2table_image4pdf(sections: list, tabls: list, table_context_size=0, return_context=False):
+def append_context2table_image4pdf(sections: list, tabls: list, table_context_size=0, return_context=False, section_page_offset: int = 0):
from deepdoc.parser import PdfParser
if table_context_size <= 0:
@@ -862,6 +862,7 @@ def append_context2table_image4pdf(sections: list, tabls: list, table_context_si
for page, left, right, top, bottom in poss:
if isinstance(page, list):
page = page[0] if page else 0
+ page += section_page_offset
page_bucket[page].append(((left, right, top, bottom), txt))
def upper_context(page, i):
@@ -917,8 +918,11 @@ def append_context2table_image4pdf(sections: list, tabls: list, table_context_si
page, left, right, top, bott = poss[0]
_page, _left, _right, _top, _bott = poss[-1]
- if isinstance(tb, list):
- tb = "\n".join(tb)
+ # Context extraction needs text, but list payloads identify images for
+ # tokenize_table; restore that shape before returning the media block.
+ image_rows = tb if isinstance(tb, list) else None
+ if image_rows is not None:
+ tb = "\n".join(image_rows)
i = 0
blks = page_bucket.get(page, [])
@@ -956,6 +960,8 @@ def append_context2table_image4pdf(sections: list, tabls: list, table_context_si
contexts.append((upper.strip(), lower.strip()))
if len(contexts) < len(res) + 1:
contexts.append(("", ""))
+ if image_rows is not None:
+ tb = image_rows if tb == _tb else [tb]
res.append(((img, tb), poss))
return contexts if return_context else res
diff --git a/test/unit_test/deepdoc/parser/test_mineru_parser.py b/test/unit_test/deepdoc/parser/test_mineru_parser.py
index cbddd45ba8..3a8e206f54 100644
--- a/test/unit_test/deepdoc/parser/test_mineru_parser.py
+++ b/test/unit_test/deepdoc/parser/test_mineru_parser.py
@@ -4,7 +4,7 @@ import sys
from io import BytesIO
from pathlib import Path
from types import ModuleType
-from unittest.mock import Mock
+from unittest.mock import Mock, call
import json
import pytest
@@ -109,6 +109,91 @@ def test_parse_pdf_forwards_normalized_dataset_language_to_image_enhancement(mon
enhance.assert_called_once_with([], vision_model, callback=None, language=expected_language)
+def test_parse_pdf_forwards_page_range_and_callback_to_page_rendering(monkeypatch, tmp_path):
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ pdf_path = tmp_path / "document.pdf"
+ pdf_path.write_bytes(b"%PDF-1.4 fake")
+ output_dir = tmp_path / "output"
+ callback = Mock()
+ render_pages = Mock()
+
+ monkeypatch.setattr(module, "extract_pdf_outlines", Mock(return_value=[]))
+ monkeypatch.setattr(parser, "__images__", render_pages)
+ monkeypatch.setattr(parser, "_run_mineru", Mock(return_value=output_dir))
+ monkeypatch.setattr(parser, "_read_output", Mock(return_value=[]))
+
+ parser.parse_pdf(
+ filepath=str(pdf_path),
+ binary=None,
+ callback=callback,
+ output_dir=str(output_dir),
+ delete_output=False,
+ page_from=12,
+ page_to=15,
+ )
+
+ render_pages.assert_called_once_with(pdf_path, zoomin=1, page_from=12, page_to=15, callback=callback)
+
+
+def test_page_rendering_only_renders_requested_range(monkeypatch):
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+
+ class _Page:
+ def __init__(self, page_number):
+ self.page_number = page_number
+
+ def to_image(self, **_kwargs):
+ rendered_pages.append(self.page_number)
+ return type("RenderedPage", (), {"original": module.Image.new("RGB", (10, 20))})()
+
+ class _Pdf:
+ pages = [_Page(page_number) for page_number in range(15)]
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *_args):
+ return False
+
+ rendered_pages = []
+ monkeypatch.setattr(module.pdfplumber, "open", lambda *_args, **_kwargs: _Pdf())
+
+ parser.__images__(b"pdf", page_from=12, page_to=15)
+
+ assert rendered_pages == [12, 13, 14]
+ assert parser.page_images is not None
+ assert len(parser.page_images) == 3
+ assert parser.page_from == 12
+
+
+def test_crop_converts_local_page_to_document_page(monkeypatch):
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ parser.page_from = 12
+ parser.page_images = [module.Image.new("RGB", (100, 200), "white")]
+
+ image, positions = parser.crop("@@1\t10\t40\t50\t80##", need_position=True)
+
+ assert image is not None
+ assert positions == [(12, 10, 40, 50, 80)]
+
+
+def test_page_rendering_failure_is_reported_to_callback(monkeypatch):
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ callback = Mock()
+ monkeypatch.setattr(module.pdfplumber, "open", Mock(side_effect=ValueError("bad pdf")))
+
+ parser.__images__(b"pdf", page_from=2, page_to=4, callback=callback)
+
+ assert callback.call_args_list == [
+ call(0.16, "[MinerU] Rendering PDF pages..."),
+ call(0.16, "[MinerU] PDF page rendering failed for pages 2:4: bad pdf"),
+ ]
+
+
def test_sanitize_section_text_removes_escaped_html_tags(monkeypatch):
module = _load_mineru_parser(monkeypatch)
text = "&lt;table&gt;&lt;tr&gt;&lt;td&gt;Alpha&lt;/td&gt;&lt;td&gt;Beta&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;"
@@ -161,6 +246,37 @@ def test_transfer_to_sections_only_sanitizes_tables(monkeypatch, output, expecte
assert sections[0][0] == expected
+ ("code_body", "expected_body"),
+ [
+ ("```txt\nList<String> names = new ArrayList<String>();\n```", "List<String> names = new ArrayList<String>();"),
+ ("```\nList<String> names = new ArrayList<String>();\n```", "List<String> names = new ArrayList<String>();"),
+ ("```txt\nList<String> names = new ArrayList<String>();\n``` trailing", "```txt\nList<String> names = new ArrayList<String>();\n``` trailing"),
+ ],
+)
+def test_transfer_to_sections_wraps_caption_and_unwrapped_body_in_fence(
+ monkeypatch: pytest.MonkeyPatch,
+ code_body: str,
+ expected_body: str,
+) -> None:
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ caption = "Java / C# style"
+ output = {
+ "type": module.MinerUContentType.CODE,
+ "code_body": code_body,
+ "code_caption": [caption],
+ "page_idx": 0,
+ "bbox": (97, 195, 579, 252),
+ }
+
+ sections = parser._transfer_to_sections([output], parse_method="raw")
+
+ assert len(sections) == 1
+ assert sections[0][0] == f"```{caption}\n{expected_body}\n```"
+
+
@pytest.mark.p1
@pytest.mark.parametrize("transfer", ["sections", "tables"])
def test_empty_table_fallback_is_logged(monkeypatch, caplog, transfer):
@@ -240,6 +356,7 @@ def test_transfer_to_tables_emits_ordered_typed_media(monkeypatch, tmp_path):
module = _load_mineru_parser(monkeypatch)
parser = module.MinerUParser()
+ parser.page_from = 12
image_path = tmp_path / "figure.png"
module.Image.new("RGB", (2, 2), "red").save(image_path)
outputs = [
@@ -250,6 +367,10 @@ def test_transfer_to_tables_emits_ordered_typed_media(monkeypatch, tmp_path):
"table_footnote": [],
"page_idx": 0,
"bbox": (1, 2, 3, 4),
+ "_mineru_positions": [
+ {"page_idx": 0, "bbox": (1, 2, 3, 4)},
+ {"page_idx": 1, "bbox": (1, 0, 3, 2)},
+ ],
},
{
"type": module.MinerUContentType.IMAGE,
@@ -285,7 +406,10 @@ def test_transfer_to_tables_emits_ordered_typed_media(monkeypatch, tmp_path):
assert isinstance(image, module.Image.Image)
assert image.getpixel((0, 0)) == (255, 0, 0)
assert texts == ["Figure 1", "Source", "A red square"]
- assert [chunk["doc_type_kwd"] for chunk in tokenize_table(media, {}, False)] == ["table", "image", "table"]
+ assert [[position[0] for position in item[1]] for item in media] == [[12, 13], [12], [13]]
+ chunks = tokenize_table(media, {}, False)
+ assert [chunk["doc_type_kwd"] for chunk in chunks] == ["table", "image", "table"]
+ assert [chunk["page_num_int"] for chunk in chunks] == [[13, 14], [13], [14]]
@pytest.mark.p1
@@ -318,6 +442,27 @@ def test_media_context_preserves_media_without_positions(monkeypatch):
assert append_context2table_image4pdf([], media, 1, return_context=True) == [("", ""), ("", "")]
+def test_media_context_preserves_image_payload_type(monkeypatch):
+ import rag.nlp as nlp
+ from PIL import Image
+
+ image = Image.new("RGB", (1, 1))
+ sections = [("Context before.", "@@1\t0\t10\t0\t5##")]
+ media = [((image, ["Figure 1"]), [(12, 0, 1, 10, 20)])]
+
+ monkeypatch.setattr(nlp, "tokenize", lambda d, text, _eng, language="English": d.update({"content_with_weight": text}))
+ contextualized = nlp.append_context2table_image4pdf(sections, media, 1, section_page_offset=12)
+
+ rows = contextualized[0][0][1]
+ assert isinstance(rows, list)
+ assert "Context before." in rows[0]
+ assert "Figure 1" in rows[0]
+ chunks = nlp.tokenize_table(contextualized, {}, False)
+ assert [chunk["doc_type_kwd"] for chunk in chunks] == ["image"]
+ assert chunks[0]["page_num_int"] == [13]
+
+
@pytest.mark.p1
@pytest.mark.parametrize("parse_method", ["naive", "manual", "paper"])
def test_transfer_to_sections_routes_app_media_separately(monkeypatch, parse_method):
diff --git a/test/unit_test/rag/app/test_vision_language_callers.py b/test/unit_test/rag/app/test_vision_language_callers.py
index 87e6a2627d..d6e88a0169 100644
--- a/test/unit_test/rag/app/test_vision_language_callers.py
+++ b/test/unit_test/rag/app/test_vision_language_callers.py
@@ -14,6 +14,7 @@
# limitations under the License.
#
import ast
+import re
from pathlib import Path
from unittest.mock import Mock
@@ -152,3 +153,100 @@ def test_mineru_forwards_dataset_language_to_parser(monkeypatch):
assert tables == []
assert returned_parser is parser
assert parser.parse_pdf.call_args.kwargs["lang"] == "Japanese"
+
+
+ "parser_error",
+ [
+ RuntimeError("[MinerU] server request failed"),
+ FileNotFoundError("[MinerU] PDF not found"),
+ ],
+)
+def test_mineru_propagates_parser_error(monkeypatch, parser_error):
+ parser = Mock()
+ parser.parse_pdf.side_effect = parser_error
+ ocr_model = Mock(mdl=parser)
+ callback = Mock()
+ monkeypatch.setattr(naive, "resolve_model_config", Mock(return_value={"llm_name": "mineru"}))
+ monkeypatch.setattr(naive, "LLMBundle", Mock(return_value=ocr_model))
+
+ with pytest.raises(type(parser_error)) as exc_info:
+ naive.by_mineru(
+ "document.pdf",
+ binary=b"pdf",
+ callback=callback,
+ mineru_llm_name="mineru",
+ tenant_id="tenant-id",
+ vision_model=object(),
+ )
+
+ assert exc_info.value is parser_error
+ callback.assert_not_called()
+
+
+def test_mineru_raises_when_model_is_not_configured(monkeypatch):
+ callback = Mock()
+ monkeypatch.setattr(naive, "get_first_provider_model_name", Mock(return_value=None))
+ monkeypatch.setattr(naive, "ensure_mineru_from_env", Mock(return_value=None))
+
+ with pytest.raises(RuntimeError, match="MinerU model not found or not configured"):
+ naive.by_mineru(
+ "document.pdf",
+ binary=b"pdf",
+ callback=callback,
+ tenant_id="tenant-id",
+ )
+
+ callback.assert_not_called()
+
+
+def test_manual_mineru_preserves_global_page_position(monkeypatch):
+ from rag.app import manual
+
+ class _MinerUParser:
+ outlines = []
+ page_from = 12
+
+ @staticmethod
+ def extract_positions(text):
+ positions = []
+ for tag in re.findall(r"@@[0-9-]+\t[0-9.\t]+##", text):
+ page, left, right, top, bottom = tag.strip("#").strip("@").split("\t")
+ positions.append(([int(page) - 1], float(left), float(right), float(top), float(bottom)))
+ return positions
+
+ @staticmethod
+ def remove_tag(text):
+ return re.sub(r"@@[\t0-9.-]+?##", "", text)
+
+ def crop(self, text, need_position=False):
+ positions = [(pages[0] + self.page_from, left, right, top, bottom) for pages, left, right, top, bottom in self.extract_positions(text) if pages and pages[0] >= 0]
+ return (None, positions) if need_position else None
+
+ parser = _MinerUParser()
+ parse = Mock(return_value=([("Document body", "text", "@@1\t10.0\t190.0\t50.0\t100.0##")], [], parser))
+ monkeypatch.setattr(manual, "PARSERS", {"mineru": parse})
+ monkeypatch.setattr(manual, "normalize_layout_recognizer", lambda _value: ("MinerU", None))
+ monkeypatch.setattr(manual, "extract_pdf_outlines", lambda *_args, **_kwargs: [])
+ monkeypatch.setattr(manual, "bullets_category", lambda _texts: [0])
+ monkeypatch.setattr(manual, "title_frequency", lambda _bullets, _sections: (0, [0]))
+ monkeypatch.setattr(manual.rag_tokenizer, "tokenize", lambda text: text)
+ monkeypatch.setattr(manual.rag_tokenizer, "fine_grained_tokenize", lambda text: text)
+ monkeypatch.setattr(manual, "num_tokens_from_string", lambda text: len(text.split()))
+
+ chunks = manual.chunk(
+ "document.pdf",
+ binary=b"%PDF-1.4 fake",
+ from_page=12,
+ to_page=15,
+ lang="English",
+ callback=lambda *_args, **_kwargs: None,
+ parser_config={"layout_recognize": "MinerU", "chunk_token_num": 128, "delimiter": "\n"},
+ )
+
+ assert len(chunks) == 1
+ assert chunks[0]["page_num_int"] == [13]
+ assert chunks[0]["position_int"][0][0] == 13