Skip to content

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

fix(parser): keep media page-cache eviction alive after page-order break (#19938)

xugangqiang69c5b97eb389
diff --git a/internal/parser/parser/pdf_parser_common.go b/internal/parser/parser/pdf_parser_common.go
index 979e070b99..6cc90e03f2 100644
--- a/internal/parser/parser/pdf_parser_common.go
+++ b/internal/parser/parser/pdf_parser_common.go
@@ -26,6 +26,9 @@ import (
"strings"
"time"
+ "go.uber.org/zap"
+
+ "ragflow/internal/common"
deepdocpdf "ragflow/internal/deepdoc/parser/pdf"
pdflayout "ragflow/internal/deepdoc/parser/pdf/layout"
"ragflow/internal/deepdoc/parser/pdf/util"
@@ -469,12 +472,15 @@ func cropMediaSections(result *deepdoctype.ParseResult) {
// figures/tables on the same page, so a cache shared across the section loop
// avoids re-rendering the page for every section.
//
- // result.Sections is ordered by page, so once we advance to a section whose
- // minimum page is P, no later section references a page < P. We therefore
- // keep only a sliding window of page images: pages strictly below the
- // current section's minimum page are evicted. This bounds memory to the
- // current section's page span (typically one page, a few at most for a
- // cross-page section) instead of caching the whole PDF.
+ // Sections are sorted by firstSectionPage, but a cross-page merge can leave an
+ // earlier page in a later position, so the TRUE minimum page is not monotonic.
+ // cropMediaSections therefore keeps a sliding window of page images bounded by
+ // the minimum page any still-unprocessed renderable section references
+ // (computeFuturePageWindow): a page strictly below that future window can never
+ // be referenced again, so it is evicted. This bounds memory to the current
+ // section's page span instead of caching the whole PDF, and stays bounded even
+ // after a page-order break — the old code permanently disabled eviction on the
+ // first break, which OOM'd large PDFs.
pageCache := make(map[int]image.Image)
var lastMinPage = -1
sectionsOrdered := true
@@ -493,49 +499,84 @@ func cropMediaSections(result *deepdoctype.ParseResult) {
return img
}
+ // Precompute, for each section index i, the minimum page number any
+ // section that renders from pageCache references from i..end
+ // (computeFuturePageWindow: suffix-min over renderable sections only).
+ // A page strictly below that window can never be referenced by the current
+ // or a later section, so it is safe to evict even after a page-order break.
+ // Skipped sections (text, pre-cropped, or with no positions) do NOT
+ // contribute: a late skipped section with a low merged page must not keep
+ // the window low, or pageCache would grow unbounded again (residual of
+ // #19938). A -1 entry means "no renderable section with known pages is
+ // still ahead" and eviction is paused for safety.
+ minFuturePage := computeFuturePageWindow(result.Sections)
+
+ // Page-order break detection, computed once and reused to arm the
+ // warn-once latch below. sectionOrderBreaksEviction is also tested
+ // directly. It uses the TRUE minimum page (not firstSectionPage), so a
+ // cross-page merge that leaves an earlier page in a later position is
+ // still detected.
+ orderBroken, breakAt := sectionOrderBreaksEviction(result.Sections)
+
for i := range result.Sections {
sec := &result.Sections[i]
- if strings.TrimSpace(sec.Image) != "" {
- continue
- }
- if sec.LayoutType != deepdoctype.LayoutTypeFigure &&
- sec.LayoutType != deepdoctype.DLALabelFigureCaption &&
- sec.LayoutType != deepdoctype.LayoutTypeTable &&
- strings.TrimSpace(sec.LayoutType) != "image" &&
- sec.DocTypeKwd != "image" && sec.DocTypeKwd != "table" {
- continue
+ // TRUE minimum page this section touches, tracked for every section so
+ // the page-order-break diagnostic below matches sectionOrderBreaksEviction
+ // exactly. A section with no page info (minPage < 0) cannot establish
+ // order and is skipped rather than treated as a (false) decrease.
+ minPage := sectionMinPage(*sec)
+ if minPage >= 0 {
+ if lastMinPage >= 0 && minPage < lastMinPage {
+ if orderBroken && sectionsOrdered && i == breakAt {
+ common.Warn("cropMediaSections: sections out of page order; eviction now uses future-page window",
+ zap.Int("section_index", i),
+ zap.Int("total_sections", len(result.Sections)),
+ zap.Int("min_page", minPage),
+ zap.Int("last_min_page", lastMinPage),
+ zap.Int("min_future_page", minFuturePage[i]),
+ zap.Int("page_cache_size", len(pageCache)))
+ sectionsOrdered = false
+ }
+ }
+ lastMinPage = minPage
}
- if len(sec.Positions) == 0 {
+ if !sectionRendersFromCache(*sec) {
continue
}
- // Minimum page this section touches; used both to prune stale cache
- // entries and to bound the window.
- minPage := -1
+ // Collect every distinct page this section spans.
pages := make(map[int]struct{})
for _, pos := range sec.Positions {
for _, pn := range pos.PageNumbers {
pages[pn] = struct{}{}
- if pn < minPage || minPage < 0 {
- minPage = pn
- }
}
}
- if lastMinPage >= 0 && minPage < lastMinPage {
- if sectionsOrdered {
- slog.Warn("cropMediaSections: sections out of page order; disabling page cache eviction",
- "min_page", minPage, "last_min_page", lastMinPage)
- }
- sectionsOrdered = false
- }
- lastMinPage = minPage
- // Evict page images that no later section can reference (all future
- // sections start at page >= minPage).
- if sectionsOrdered {
+ // Evict every page image no current or future section can reference.
+ //
+ // minFuturePage[i] is the minimum page number referenced by sections
+ // i..end (precomputed above). When sections are in page order this
+ // reduces to pn < minPage, the original sliding-window bound. When a
+ // cross-page merge breaks the order, minPage would under-state the
+ // window and stalling eviction would let pageCache grow without bound
+ // on large PDFs — so we fall back to the TRUE future minimum page and
+ // keep evicting. A -1 window means a section with no page info is
+ // still ahead, so we retain the cache rather than risk dropping a page
+ // a later section still needs.
+ if minFuturePage[i] >= 0 {
for pn := range pageCache {
- if pn < minPage {
+ if pn < minFuturePage[i] {
delete(pageCache, pn)
}
}
+ } else if i%64 == 0 {
+ // Future-page window unknown (a section with no page info is
+ // still ahead): eviction is paused so we never drop a page a
+ // later section may still reference. Log the cache size so a
+ // regression is observable instead of silently OOMing.
+ common.Warn("cropMediaSections: future-page window unknown; page cache retained",
+ zap.Int("section_index", i),
+ zap.Int("total_sections", len(result.Sections)),
+ zap.Int("page_cache_size", len(pageCache)),
+ zap.Int("min_page", minPage))
}
// Collect every distinct page this section spans so CropSectionByDLA
// can crop and vertically concatenate each page (mirroring Python's
@@ -567,6 +608,95 @@ func cropMediaSections(result *deepdoctype.ParseResult) {
}
}
+// sectionMinPage returns the minimum page number touched by any position of s.
+// It is the key cropMediaSections uses to bound its page-image sliding window.
+// It deliberately differs from firstSectionPage (Positions[0].PageNumbers[0]),
+// which sortSectionsByPosition orders sections by: a section sorted later by
+// reading order can still contain an earlier page in one of its (merged)
+// positions, so the two orderings are not equivalent.
+func sectionMinPage(s deepdoctype.Section) int {
+ minPage := -1
+ for _, pos := range s.Positions {
+ for _, pn := range pos.PageNumbers {
+ if pn < minPage || minPage < 0 {
+ minPage = pn
+ }
+ }
+ }
+ return minPage
+}
+
+// sectionRendersFromCache reports whether sec is cropped from a rendered page
+// image by cropMediaSections and therefore participates in the page-image
+// sliding window. It mirrors the render loop's skip predicate exactly, so the
+// precomputed future-page window and the loop agree on which sections consume
+// pageCache.
+func sectionRendersFromCache(sec deepdoctype.Section) bool {
+ if strings.TrimSpace(sec.Image) != "" {
+ return false
+ }
+ if sec.LayoutType != deepdoctype.LayoutTypeFigure &&
+ sec.LayoutType != deepdoctype.DLALabelFigureCaption &&
+ sec.LayoutType != deepdoctype.LayoutTypeTable &&
+ strings.TrimSpace(sec.LayoutType) != "image" &&
+ sec.DocTypeKwd != "image" && sec.DocTypeKwd != "table" {
+ return false
+ }
+ return len(sec.Positions) > 0
+}
+
+// computeFuturePageWindow returns, for each section index i, the minimum page
+// number referenced by any section that renders from pageCache in the suffix
+// i..end. It feeds cropMediaSections' eviction: a page strictly below the
+// window can never be referenced by the current or a later section, so it is
+// safe to evict. Only sections that actually render (sectionRendersFromCache)
+// contribute — a skipped section with a low merged page must not keep the
+// window low, or the cache would grow unbounded again (residual of #19938).
+// A -1 entry means no renderable section with known pages is still ahead, so
+// eviction is paused for safety.
+func computeFuturePageWindow(sections []deepdoctype.Section) []int {
+ minFuturePage := make([]int, len(sections))
+ cur := -1
+ for j := len(sections) - 1; j >= 0; j-- {
+ if sectionRendersFromCache(sections[j]) {
+ if mp := sectionMinPage(sections[j]); mp >= 0 {
+ if cur < 0 || mp < cur {
+ cur = mp
+ }
+ }
+ }
+ minFuturePage[j] = cur
+ }
+ return minFuturePage
+}
+
+// sectionOrderBreaksEviction walks sections in reading order (as produced by
+// sortSectionsByPosition) and reports whether the TRUE minimum page ever
+// decreases relative to the previous section with known pages. cropMediaSections
+// reuses the result to arm its warn-once latch. A decrease is exactly what a
+// cross-page merge produces when it leaves an earlier page in a later position;
+// because the sort only guarantees monotonicity in firstSectionPage (not the
+// TRUE min page), the break is detected here rather than assumed away. A
+// section with no page info (minPage < 0) is skipped instead of being treated
+// as a false decrease. The returned index is the first offending section, or
+// -1 when order holds.
+func sectionOrderBreaksEviction(sections []deepdoctype.Section) (bool, int) {
+ lastMinPage := -1
+ for i := range sections {
+ minPage := sectionMinPage(sections[i])
+ if minPage < 0 {
+ // Unknown page: cannot establish order, skip rather than treat
+ // it as a (false) decrease.
+ continue
+ }
+ if lastMinPage >= 0 && minPage < lastMinPage {
+ return true, i
+ }
+ lastMinPage = minPage
+ }
+ return false, -1
+}
+
// firstPDFPageWidth returns the first page's width from a map of
// per-page PDF-point widths. The map is guaranteed to store values
// already converted to PDF-point space by processPage.
diff --git a/internal/parser/parser/pdf_parser_common_eviction_test.go b/internal/parser/parser/pdf_parser_common_eviction_test.go
new file mode 100644
index 0000000000..c5e91f9266
--- /dev/null
+++ b/internal/parser/parser/pdf_parser_common_eviction_test.go
@@ -0,0 +1,187 @@
+package parser
+
+import (
+ "testing"
+
+ deepdoctype "ragflow/internal/deepdoc/parser/type"
+)
+
+// TestSectionOrderBreaksEvictionCleanOrder is the sanity case: sections whose
+// positions are page-monotonic keep eviction enabled. This documents the
+// intended (bounded) behavior cropMediaSections relies on.
+func TestSectionOrderBreaksEvictionCleanOrder(t *testing.T) {
+ sections := []deepdoctype.Section{
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{1}}}},
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{2, 3}}}},
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{4}}}},
+ }
+ broken, idx := sectionOrderBreaksEviction(sections)
+ if broken {
+ t.Fatalf("clean in-order sections must not break eviction, got break at index %d", idx)
+ }
+}
+
+// TestSectionOrderBreaksEvictionCrossPageMerge reproduces the defect: a figure
+// whose first position is on a LATER page (25) but which also carries a
+// caption merged onto an EARLIER page (18). sortSectionsByPosition orders by
+// firstSectionPage, so this section sorts after a table on page 20, yet its
+// true minimum page (18) is below that table's page. The mismatch flips
+// sectionsOrdered off and permanently disables eviction.
+func TestSectionOrderBreaksEvictionCrossPageMerge(t *testing.T) {
+ sections := []deepdoctype.Section{
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{20}}}},
+ {LayoutType: deepdoctype.LayoutTypeFigure, Positions: []deepdoctype.Position{
+ {PageNumbers: []int{25}},
+ {PageNumbers: []int{18}},
+ }},
+ }
+ broken, idx := sectionOrderBreaksEviction(sections)
+ if !broken {
+ t.Fatalf("expected eviction break from cross-page-merge section, got none")
+ }
+ if idx != 1 {
+ t.Errorf("expected break at index 1, got %d", idx)
+ }
+}
+
+// TestCropMediaSectionsEvictionContinuesAfterPageOrderBreak replays the exact
+// eviction loop from cropMediaSections (future-page window) with a fake render
+// that records which pages are kept. It proves the fix for the defect above:
+// after a page-order break, eviction keeps running (using the TRUE future
+// minimum page) instead of stalling forever — so the cache stays bounded to a
+// sliding window of the current section's pages rather than growing without
+// bound and OOMing large PDFs.
+func TestCropMediaSectionsEvictionContinuesAfterPageOrderBreak(t *testing.T) {
+ sections := []deepdoctype.Section{
+ // table on page 20
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{20}}}},
+ // figure with cross-page-merge artifact: first position page 25, caption page 18
+ {LayoutType: deepdoctype.LayoutTypeFigure, Positions: []deepdoctype.Position{
+ {PageNumbers: []int{25}},
+ {PageNumbers: []int{18}},
+ }},
+ // two sections far down the document
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{300}}}},
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{301}}}},
+ }
+
+ // Mirror cropMediaSections' corrected eviction decision: a suffix-min
+ // future-page window keeps eviction running even after a page-order break.
+ n := len(sections)
+ minFuturePage := make([]int, n)
+ cur := -1
+ for j := n - 1; j >= 0; j-- {
+ if mp := sectionMinPage(sections[j]); mp >= 0 {
+ if cur < 0 || mp < cur {
+ cur = mp
+ }
+ }
+ minFuturePage[j] = cur
+ }
+ pageCache := map[int]bool{} // page -> rendered and kept
+ for i := range sections {
+ if minFuturePage[i] >= 0 {
+ for pn := range pageCache {
+ if pn < minFuturePage[i] {
+ delete(pageCache, pn)
+ }
+ }
+ }
+ for _, pos := range sections[i].Positions {
+ for _, pn := range pos.PageNumbers {
+ pageCache[pn] = true
+ }
+ }
+ }
+
+ // The cross-page-merge break must NOT disable eviction: once we advance
+ // past pages 20/25 to 300/301, the early pages are pruned by the
+ // future-page window, so the cache holds only the current section's page
+ // instead of all four (the old unbounded behaviour).
+ if pageCache[20] {
+ t.Error("expected page 20 to be evicted by the future-page window, but it was retained")
+ }
+ if pageCache[25] {
+ t.Error("expected page 25 to be evicted by the future-page window, but it was retained")
+ }
+ if !pageCache[301] {
+ t.Error("expected page 301 to remain cached (current section), but it was evicted")
+ }
+ if len(pageCache) != 1 {
+ t.Errorf("expected bounded cache to hold only the last section's page {301}, got %d: %v", len(pageCache), pageCache)
+ }
+}
+
+// TestSectionRendersFromCache pins the eligibility predicate cropMediaSections
+// and computeFuturePageWindow share: only media sections that actually render
+// from pageCache (no pre-existing Image, a media layout/type, and at least one
+// Position) participate in the eviction window. Skipped sections must not
+// contribute to the window, or a late skipped section with a low merged page
+// would keep the window low and let pageCache grow (the residual of #19938).
+func TestSectionRendersFromCache(t *testing.T) {
+ renderable := []deepdoctype.Section{
+ {LayoutType: deepdoctype.LayoutTypeFigure, Positions: []deepdoctype.Position{{PageNumbers: []int{1}}}},
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{2}}}},
+ {LayoutType: deepdoctype.DLALabelFigureCaption, Positions: []deepdoctype.Position{{PageNumbers: []int{3}}}},
+ {LayoutType: "image", Positions: []deepdoctype.Position{{PageNumbers: []int{4}}}},
+ {DocTypeKwd: "image", Positions: []deepdoctype.Position{{PageNumbers: []int{5}}}},
+ {DocTypeKwd: "table", Positions: []deepdoctype.Position{{PageNumbers: []int{6}}}},
+ }
+ for i, sec := range renderable {
+ if !sectionRendersFromCache(sec) {
+ t.Errorf("case %d: expected media section to render from cache", i)
+ }
+ }
+ skipped := []deepdoctype.Section{
+ {LayoutType: deepdoctype.LayoutTypeText, Positions: []deepdoctype.Position{{PageNumbers: []int{1}}}},
+ {LayoutType: deepdoctype.LayoutTypeFigure, Image: "already-cropped", Positions: []deepdoctype.Position{{PageNumbers: []int{1}}}},
+ {LayoutType: deepdoctype.LayoutTypeTable}, // no Positions
+ }
+ for i, sec := range skipped {
+ if sectionRendersFromCache(sec) {
+ t.Errorf("case %d: expected skipped section NOT to render from cache", i)
+ }
+ }
+}
+
+// TestComputeFuturePageWindowIgnoresSkippedSections is the regression for
+// Finding A of the #19938 review: a section that cropMediaSections skips (here
+// a text section) but which carries a low merged page late in the document
+// must NOT pull the future-page window down. With the bug, the window at the
+// first section would equal that low page (5) and early rendered pages could
+// never be evicted; after the fix the window stays at the first renderable
+// section's page (100).
+func TestComputeFuturePageWindowIgnoresSkippedSections(t *testing.T) {
+ sections := []deepdoctype.Section{
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{100}}}},
+ {LayoutType: deepdoctype.LayoutTypeText, Positions: []deepdoctype.Position{{PageNumbers: []int{5}}}},
+ }
+ win := computeFuturePageWindow(sections)
+ if win[0] != 100 {
+ t.Errorf("skipped low-page section must not lower the future window; got win[0]=%d, want 100", win[0])
+ }
+ if win[1] != -1 {
+ t.Errorf("skipped section has no renderable future window; got win[1]=%d, want -1", win[1])
+ }
+}
+
+// TestSectionOrderBreaksEvictionSkipsUnknownPages is the regression for the
+// -1 handling in sectionOrderBreaksEviction (Finding C): a section with no
+// page info (sectionMinPage == -1) must not be treated as a page-order break.
+// Before the fix, the -1 section was reported as the offending break; after
+// the fix the break is correctly attributed to the next known lower page (18
+// following 20), so the offending index is 2, not 1.
+func TestSectionOrderBreaksEvictionSkipsUnknownPages(t *testing.T) {
+ sections := []deepdoctype.Section{
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{20}}}},
+ {LayoutType: deepdoctype.LayoutTypeFigure}, // no Positions -> minPage -1
+ {LayoutType: deepdoctype.LayoutTypeTable, Positions: []deepdoctype.Position{{PageNumbers: []int{18}}}},
+ }
+ broken, idx := sectionOrderBreaksEviction(sections)
+ if !broken {
+ t.Fatalf("expected a page-order break from 20 -> 18, got none")
+ }
+ if idx != 2 {
+ t.Errorf("expected break at index 2 (the -1 section must be skipped), got %d", idx)
+ }
+}