Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: stop RAG PDF parsing from starving the server on scanned pages (#13137)

Daniel Hanfdaa9dc41bd7
diff --git a/studio/backend/core/rag/parsers.py b/studio/backend/core/rag/parsers.py
index d541263d9ee..5c0e4b92a02 100644
--- a/studio/backend/core/rag/parsers.py
+++ b/studio/backend/core/rag/parsers.py
@@ -159,6 +159,37 @@ def _markdown_incomplete(markdown: str, plain: str) -> bool:
return markdown_letters < _PDF_INCOMPLETE_RATIO * plain_letters
+# JPEG2000 decodes at ~45 ms per megapixel; a logo stays far below this, a 300 dpi scan far above.
+_SCAN_IMAGE_MIN_PIXELS = 1_000_000
+
+
+def _image_covers_a_corner(doc, number: int) -> bool:
+ """True when a scan-sized raster image overlaps one of the 10pt page corners pymupdf4llm
+ renders to guess the background colour. That render decodes the whole image in one C call
+ holding the GIL (~2 s per JPEG2000 scan page), starving the server's event loop until the
+ desktop watchdog kills it (#13094)."""
+ try:
+ import fitz
+
+ page = doc[number]
+ r = page.rect
+ # 1pt slack: the render clip rounds outward to whole pixels.
+ corners = [
+ fitz.Rect(x - 1, y - 1, x + 11, y + 11)
+ for x in (r.x0, r.x1 - 10)
+ for y in (r.y0, r.y1 - 10)
+ ]
+ # Image boxes are unrotated; the probe clips page.rect, which is rotated.
+ boxes = [
+ fitz.Rect(info["bbox"]) * page.rotation_matrix
+ for info in page.get_image_info()
+ if info["width"] * info["height"] >= _SCAN_IMAGE_MIN_PIXELS
+ ]
+ except Exception:
+ return False
+ return any(box.intersects(corner) for box in boxes for corner in corners)
+
+
def _pdf_markdown(doc, pages: range | None = None) -> list[str] | None:
"""Per-page layout-aware Markdown (tables, headings, lists) via pymupdf4llm; index
i maps to page i+1. Returns None when the lib is missing, extraction fails, or the
@@ -169,9 +200,27 @@ def _pdf_markdown(doc, pages: range | None = None) -> list[str] | None:
return None
try:
kwargs = {"page_chunks": True, "show_progress": False, "ignore_images": True}
- if pages is not None:
- kwargs["pages"] = list(pages)
- chunks = pymupdf4llm.to_markdown(doc, **kwargs)
+ indices = list(range(doc.page_count) if pages is None else pages)
+ scans = {i for i in indices if _image_covers_a_corner(doc, i)}
+ if not scans:
+ if pages is not None:
+ kwargs["pages"] = indices
+ chunks = pymupdf4llm.to_markdown(doc, **kwargs)
+ else:
+ # Background detection only where it is cheap. Each call still builds its header
+ # table from the whole (baked) document, so both halves agree on heading levels.
+ by_page = {}
+ for group, detect in (
+ ([i for i in indices if i not in scans], True),
+ ([i for i in indices if i in scans], False),
+ ):
+ if not group:
+ continue
+ part = pymupdf4llm.to_markdown(doc, pages = group, detect_bg_color = detect, **kwargs)
+ if not isinstance(part, list) or len(part) != len(group):
+ return None
+ by_page.update(zip(group, part))
+ chunks = [by_page[i] for i in indices]
except Exception: # noqa: BLE001 - never let Markdown extraction break ingestion
logger.warning("pymupdf4llm extraction failed; using plain text", exc_info = True)
return None
diff --git a/studio/backend/tests/test_rag_parsing.py b/studio/backend/tests/test_rag_parsing.py
index 7bb8f46663b..b4b579ef6ae 100644
--- a/studio/backend/tests/test_rag_parsing.py
+++ b/studio/backend/tests/test_rag_parsing.py
@@ -82,6 +82,80 @@ def test_pdf_markdown_keeps_text_drawn_over_a_picture(tmp_path, monkeypatch):
assert sidebar in text
+def test_pdf_markdown_does_not_render_scanned_pages(tmp_path, monkeypatch):
+ # pymupdf4llm's background-colour probe renders page corners; under a full-page scan that
+ # decodes the whole image while holding the GIL, which starved the event loop until the
+ # desktop watchdog killed the backend (#13094). Text pages keep the probe.
+ pytest.importorskip("pymupdf4llm")
+ import pymupdf
+
+ from core.rag import config, parsers
+
+ monkeypatch.setattr(config, "PDF_MARKDOWN", True)
+ doc = pymupdf.open()
+ scan = doc.new_page()
+ pix = pymupdf.Pixmap(pymupdf.csRGB, pymupdf.IRect(0, 0, 1000, 1300), False)
+ pix.set_rect(pix.irect, (250, 250, 240))
+ scan.insert_image(scan.rect, pixmap = pix, keep_proportion = False)
+ scan.insert_text((60, 120), "Chapter one covers shelter.", fontsize = 10)
+ text_page = doc.new_page()
+ text_page.insert_text((60, 80), "Survival Training", fontsize = 16)
+ text_page.insert_text((60, 120), "Chapter two covers water.", fontsize = 10)
+ pdf = tmp_path / "scan.pdf"
+ doc.save(str(pdf))
+ doc.close()
+
+ rendered = []
+ real_get_pixmap = pymupdf.Page.get_pixmap
+
+ def recording_get_pixmap(self, *args, **kwargs):
+ rendered.append(self.number)
+ return real_get_pixmap(self, *args, **kwargs)
+
+ monkeypatch.setattr(pymupdf.Page, "get_pixmap", recording_get_pixmap)
+ pages = parsers.parse(str(pdf))
+ assert [p.page_number for p in pages] == [1, 2]
+ assert "Chapter one covers shelter." in pages[0].text
+ assert "Chapter two covers water." in pages[1].text
+ assert "# Survival Training" in pages[1].text
+ assert 0 not in rendered
+ assert 1 in rendered
+
+
[email protected]("rotation", [0, 90, 180, 270])
+def test_scan_corner_check_follows_page_rotation(rotation):
+ import pymupdf
+
+ from core.rag import parsers
+
+ doc = pymupdf.open()
+ page = doc.new_page()
+ pix = pymupdf.Pixmap(pymupdf.csRGB, pymupdf.IRect(0, 0, 2000, 500), False)
+ pix.set_rect(pix.irect, (250, 250, 240))
+ # A strip along the unrotated bottom edge covers two corners at every rotation.
+ page.insert_image(pymupdf.Rect(0, 700, 595, 842), pixmap = pix, keep_proportion = False)
+ inset = doc.new_page()
+ inset.insert_image(pymupdf.Rect(100, 100, 400, 600), pixmap = pix, keep_proportion = False)
+ for number in range(2):
+ doc[number].set_rotation(rotation)
+ assert parsers._image_covers_a_corner(doc, 0)
+ assert not parsers._image_covers_a_corner(doc, 1)
+
+
+def test_scan_corner_check_ignores_small_corner_logos():
+ # A logo is cheap to decode, so its page keeps pymupdf4llm's background probe.
+ import pymupdf
+
+ from core.rag import parsers
+
+ doc = pymupdf.open()
+ page = doc.new_page()
+ logo = pymupdf.Pixmap(pymupdf.csRGB, pymupdf.IRect(0, 0, 200, 200), False)
+ logo.set_rect(logo.irect, (200, 30, 30))
+ page.insert_image(pymupdf.Rect(0, 0, 60, 60), pixmap = logo)
+ assert not parsers._image_covers_a_corner(doc, 0)
+
+
def test_pdf_markdown_off_uses_plain_text(tmp_path, monkeypatch):
# The toggle (RAG_PDF_MARKDOWN=0) falls back to flat PyMuPDF text: content is still
# there, but with no Markdown markup.