RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
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.pyindex 462dad63ce..683ab2d244 100644--- a/api/db/services/task_service.py+++ b/api/db/services/task_service.py@@ -25,6 +25,7 @@ from peewee import JOINfrom api.db.db_models import DB, File2Document, Filefrom api.db import FileTypefrom api.db.db_models import Task, Document, Knowledgebase, Tenant+from api.db.joint_services.tenant_model_service import get_composite_model_name_by_idfrom api.db.services.common_service import CommonServicefrom api.db.services.document_service import DocumentServicefrom 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 12if 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_NUMBERpage_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.pyindex 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_NUMBERself.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_fromself.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 = Noneself.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.")@staticmethoddef _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_bodycase 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):continueposition_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.pyindex 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 += 1return "@@{}\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.pyindex 91fc4ff079..dd9ad04cbf 100644--- a/rag/app/naive.py+++ b/rag/app/naive.py@@ -245,10 +245,9 @@ def by_mineru(return sections, tables, pdf_parserexcept 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__.pyindex 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 PdfParserif table_context_size <= 0:@@ -862,6 +862,7 @@ def append_context2table_image4pdf(sections: list, tabls: list, table_context_sifor page, left, right, top, bottom in poss:if isinstance(page, list):page = page[0] if page else 0+ page += section_page_offsetpage_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_sipage, 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 = 0blks = page_bucket.get(page, [])@@ -956,6 +960,8 @@ def append_context2table_image4pdf(sections: list, tabls: list, table_context_sicontexts.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 resdiff --git a/test/unit_test/deepdoc/parser/test_mineru_parser.py b/test/unit_test/deepdoc/parser/test_mineru_parser.pyindex 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 sysfrom io import BytesIOfrom pathlib import Pathfrom types import ModuleType-from unittest.mock import Mock+from unittest.mock import Mock, callimport jsonimport pytest@@ -109,6 +109,91 @@ def test_parse_pdf_forwards_normalized_dataset_language_to_image_enhancement(monenhance.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 = "<table><tr><td>Alpha</td><td>Beta</td></tr></table>"@@ -161,6 +246,37 @@ def test_transfer_to_sections_only_sanitizes_tables(monkeypatch, output, expecteassert 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 = 12image_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.pyindex 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 refrom pathlib import Pathfrom unittest.mock import Mock@@ -152,3 +153,100 @@ def test_mineru_forwards_dataset_language_to_parser(monkeypatch):assert tables == []assert returned_parser is parserassert 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