Skip to content

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

perf(chunker): parallelize cropImageChunks across chunks (#20183)

xugangqiang4894936b689e
diff --git a/internal/ingestion/component/chunker/pdfcrop_cgo.go b/internal/ingestion/component/chunker/pdfcrop_cgo.go
index 90e24e45e8..c25775b052 100644
--- a/internal/ingestion/component/chunker/pdfcrop_cgo.go
+++ b/internal/ingestion/component/chunker/pdfcrop_cgo.go
@@ -14,11 +14,16 @@ import (
"context"
"encoding/json"
"image"
+ "os"
+ "runtime"
+ "strconv"
+ "sync"
"go.uber.org/zap"
"ragflow/internal/common"
deepdocpdf "ragflow/internal/deepdoc/parser/pdf"
+ pdfpos "ragflow/internal/deepdoc/parser/pdf/type"
"ragflow/internal/deepdoc/parser/pdf/util"
deepdoctype "ragflow/internal/deepdoc/parser/type"
"ragflow/internal/ingestion/component"
@@ -57,24 +62,65 @@ func newPDFEngineFromUpstream(ctx context.Context, db *gorm.DB, up schema.Chunke
return deepdocpdf.NewEngine(data)
}
+// cropConcurrency bounds how many chunks are cropped concurrently. The CGO
+// pdfium render is serialized by pdfsync.Mu inside the engine, so raising this
+// mostly parallelises the pure-Go crop + PNG-encode path (CropSectionImage →
+// image/png), which was the dominant cost in the serial loop. Overridable via
+// RAGFLOW_CROP_CONCURRENCY; defaults to GOMAXPROCS/3 (the crop path competes
+// with the rest of the ingestor — tokenizer, uploads, extractions — so we use
+// a third of the cores rather than saturating them), never below 1.
+func cropConcurrency() int {
+ if v := os.Getenv("RAGFLOW_CROP_CONCURRENCY"); v != "" {
+ if n, err := strconv.Atoi(v); err == nil && n > 0 {
+ return n
+ }
+ }
+ // Use a third of the available cores so the crop fan-out does not starve
+ // the rest of the ingestor pipeline; never drop below 1.
+ n := runtime.GOMAXPROCS(0) / 3
+ if n < 1 {
+ n = 1
+ }
+ return n
+}
+
// cropImageChunks crops image/table chunks and renders text previews (for
// text chunks that carry PDF positions, mirroring Python
-// restore_pdf_text_previews). Each spanned page is
-// rendered at most once. Chunks arrive in document order, so we keep only a
-// sliding window of page images: once we advance past a chunk whose minimum
-// page is P, no later chunk references a page < P, and we evict those entries
-// from pageCache. This bounds peak memory to the pages spanned by the recent
-// window (typically one page per chunk) instead of holding every rendered
-// page for the whole call. The pdfsync.Mu serializer inside the engine makes
-// concurrent renders safe, but we render sequentially here since the caller
-// fans out across chunks.
+// restore_pdf_text_previews). Each spanned page is rendered at most once and
+// cached; the cache is shared across chunks so two chunks on the same page
+// reuse one render.
+//
+// Concurrency: the per-chunk crop + PNG-encode (the dominant CPU cost,
+// CropSectionImage → image/png) is fanned out across a bounded worker pool.
+// The pdfium CGO render is serialized by pdfsync.Mu inside the engine, so
+// concurrent renders are safe — only the Go-side encode runs in parallel.
func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks []schema.ChunkDoc) []schema.ChunkDoc {
if engine == nil {
return chunks
}
- pageCache := make(map[int]image.Image)
+
+ // cache bounds peak memory (reference counting + LRU, see lruPageCache)
+ // so a thousands-of-pages PDF no longer spills every rendered page into
+ // RAM. This replaces the serial code's sliding-window eviction, which
+ // relied on in-order processing and is unsafe under fan-out. render is
+ // called outside the lock; the warning on failure is logged here so the
+ // cache stays render-agnostic and unit-testable.
+ cache := newLRUPageCache(pageCacheLimit())
+ render := func(pn int) (image.Image, bool) {
+ img, rerr := deepdocpdf.RenderPageToImage(engine, pn)
+ if rerr != nil || img == nil {
+ common.Warn("cropImageChunks: render failed, skipping page",
+ zap.Int("page", pn), zap.Error(rerr))
+ return nil, false
+ }
+ return img, true
+ }
+
out := make([]schema.ChunkDoc, len(chunks))
- for i, ck := range chunks {
+ sem := make(chan struct{}, cropConcurrency())
+ var wg sync.WaitGroup
+ for i := range chunks {
+ ck := chunks[i]
out[i] = ck
if !needsCrop(ck) || ck.Image != "" {
continue
@@ -91,57 +137,46 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
if len(positions) == 0 {
continue
}
- // Minimum page this chunk touches; used to prune stale cache entries.
- minPage := -1
- for _, pos := range positions {
- for _, pn := range pos.PageNumbers {
- if pn < minPage || minPage < 0 {
- minPage = pn
+ wg.Add(1)
+ sem <- struct{}{}
+ go func(i int, ck schema.ChunkDoc, positions []pdfpos.Position) {
+ defer wg.Done()
+ defer func() { <-sem }()
+ if err := ctx.Err(); err != nil {
+ return
+ }
+ single := make(map[int]image.Image, len(positions))
+ acquired := make([]int, 0, len(positions))
+ for _, pos := range positions {
+ for _, pn := range pos.PageNumbers {
+ if _, ok := single[pn]; ok {
+ continue
+ }
+ if img, ok := cache.Acquire(render, pn); ok {
+ single[pn] = img
+ acquired = append(acquired, pn)
+ }
}
}
- }
- // Evict page images that no later chunk can reference (all future
- // chunks start at page >= minPage).
- for pn := range pageCache {
- if pn < minPage {
- delete(pageCache, pn)
+ // Proceed whenever at least one spanned page resolved to an
+ // image — freshly rendered or served from the page cache.
+ if len(single) == 0 {
+ return
}
- }
- single := make(map[int]image.Image, len(positions))
- for _, pos := range positions {
- for _, pn := range pos.PageNumbers {
- if _, ok := single[pn]; ok {
- continue
- }
- if img, ok := pageCache[pn]; ok {
- single[pn] = img
- continue
- }
- img, rerr := deepdocpdf.RenderPageToImage(engine, pn)
- if rerr != nil || img == nil {
- common.Warn("cropImageChunks: render failed, skipping page",
- zap.Int("page", pn), zap.Error(rerr))
- continue
- }
- pageCache[pn] = img
- single[pn] = img
+ img := util.CropSectionPositions(positions, single, deepdoctype.DlaScale)
+ // Release the page bitmaps now that cropping is done. They are no
+ // longer needed and may be evicted under the LRU cap; the image
+ // below is encoded from single and does not depend on the pages.
+ for _, pn := range acquired {
+ cache.Release(pn)
}
- }
- // Proceed whenever at least one spanned page resolved to an
- // image — whether freshly rendered or served from the page cache
- // (the latter happens for the second chunk reusing page 0).
- if len(single) == 0 {
- continue
- }
- if err := ctx.Err(); err != nil {
- return out
- }
- img := util.CropSectionPositions(positions, single, deepdoctype.DlaScale)
- if img == "" {
- continue
- }
- out[i].Image = "data:image/png;base64," + img
+ if img == "" {
+ return
+ }
+ out[i].Image = "data:image/png;base64," + img
+ }(i, ck, positions)
}
+ wg.Wait()
return out
}
diff --git a/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go b/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
new file mode 100644
index 0000000000..a0f252e449
--- /dev/null
+++ b/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
@@ -0,0 +1,59 @@
+//go:build cgo
+
+package chunker
+
+import (
+ "context"
+ "strings"
+ "testing"
+
+ "ragflow/internal/ingestion/component/schema"
+)
+
+// TestCropImageChunks_ConcurrentCropsAll verifies the parallel fan-out still
+// crops every eligible chunk — no lost work, no missing output. Run with
+// `go test -race` to catch data races in the shared pageCache / out slice.
+func TestCropImageChunks_ConcurrentCropsAll(t *testing.T) {
+ t.Setenv("RAGFLOW_CROP_CONCURRENCY", "32")
+ ctx := context.Background()
+ eng := mockCropEngine{}
+ pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
+
+ const n = 64
+ chunks := make([]schema.ChunkDoc, n)
+ for i := 0; i < n; i++ {
+ chunks[i] = schema.ChunkDoc{CKType: "image", PDFPositions: pos}
+ }
+ out := cropImageChunks(ctx, eng, chunks)
+ if len(out) != n {
+ t.Fatalf("len(out) = %d, want %d", len(out), n)
+ }
+ for i, ck := range out {
+ if !strings.HasPrefix(ck.Image, "data:image/png;base64,") {
+ t.Errorf("chunk %d: image = %q, want data:image/png;base64, prefix", i, ck.Image)
+ }
+ }
+}
+
+// TestCropImageChunks_ConcurrentPageCacheReuse hammers renderPage from many
+// goroutines against one shared page to prove the pageCache map is race-free
+// (run with -race). It also confirms every chunk on the same page still gets a
+// cropped preview under heavy contention.
+func TestCropImageChunks_ConcurrentPageCacheReuse(t *testing.T) {
+ t.Setenv("RAGFLOW_CROP_CONCURRENCY", "16")
+ ctx := context.Background()
+ eng := mockCropEngine{}
+ pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
+
+ const n = 200
+ chunks := make([]schema.ChunkDoc, n)
+ for i := 0; i < n; i++ {
+ chunks[i] = schema.ChunkDoc{CKType: "table", Positions: pos}
+ }
+ out := cropImageChunks(ctx, eng, chunks)
+ for i, ck := range out {
+ if !strings.HasPrefix(ck.Image, "data:image/png;base64,") {
+ t.Errorf("chunk %d: image not cropped: %q", i, ck.Image)
+ }
+ }
+}
diff --git a/internal/ingestion/component/chunker/pdfcrop_pagecache.go b/internal/ingestion/component/chunker/pdfcrop_pagecache.go
new file mode 100644
index 0000000000..d958098a09
--- /dev/null
+++ b/internal/ingestion/component/chunker/pdfcrop_pagecache.go
@@ -0,0 +1,150 @@
+// Package chunker — bounded LRU + reference-counted cache for rendered PDF
+// page bitmaps.
+//
+// cropImageChunks renders a PDF page once and reuses the bitmap across every
+// chunk that spans it. The serial version kept the cache unbounded and relied
+// on in-order processing to drop pages it would never touch again. The
+// concurrent version no longer has that "earlier pages are done" invariant, so
+// an unbounded cache retains the whole document: a 3266-page PDF peaked at
+// ~21 GB. lruPageCache bounds that with two mechanisms:
+//
+// - Reference counting: a page is held (ref > 0) only while an in-flight
+// worker is actively cropping from it. When the last user Release-s it
+// (ref → 0) it becomes eligible for eviction — so a page an in-flight
+// worker still needs is never dropped, and never re-rendered.
+// - LRU cap: at most cap pages are kept; when over cap the least-recently
+// used ref==0 pages are evicted, bounding peak memory on long PDFs.
+package chunker
+
+import (
+ "container/list"
+ "image"
+ "os"
+ "strconv"
+ "sync"
+)
+
+// pageCacheEntry pairs a page number with its rendered bitmap and a reference
+// count for storage in the LRU list.
+type pageCacheEntry struct {
+ pn int
+ img image.Image
+ ref int
+}
+
+// lruPageCache is a concurrency-safe bounded LRU of rendered page bitmaps with
+// reference counting. Eviction only drops ref==0 pages, so an in-flight crop
+// can never lose a page it still holds a reference to. A transient double
+// render (two workers both missing the same page) is harmless — the later one
+// discards its render and reuses the cached entry.
+type lruPageCache struct {
+ mu sync.Mutex
+ ll *list.List // front = most-recently-used; element value = pageCacheEntry
+ items map[int]*list.Element
+ cap int
+}
+
+// newLRUPageCache returns a cache that retains at most capacity pages. A
+// capacity below 1 is clamped to 1.
+func newLRUPageCache(capacity int) *lruPageCache {
+ if capacity < 1 {
+ capacity = 1
+ }
+ return &lruPageCache{
+ ll: list.New(),
+ items: make(map[int]*list.Element),
+ cap: capacity,
+ }
+}
+
+// Acquire returns the cached or freshly rendered image for pn and marks it
+// referenced. The caller must call Release(pn) once cropping from pn is done.
+// render is invoked outside the lock on a miss, so the CGO pdfium render is
+// never serialized by the cache mutex. A transient double render (two workers
+// both miss the same page) is harmless: the later one reuses the cached entry
+// and discards its own redundant copy.
+func (c *lruPageCache) Acquire(render func(int) (image.Image, bool), pn int) (image.Image, bool) {
+ c.mu.Lock()
+ if el, ok := c.items[pn]; ok {
+ e := el.Value.(pageCacheEntry)
+ e.ref++
+ el.Value = e
+ c.ll.MoveToFront(el)
+ img := e.img
+ c.mu.Unlock()
+ return img, true
+ }
+ c.mu.Unlock()
+
+ img, ok := render(pn)
+ if !ok {
+ return nil, false
+ }
+
+ c.mu.Lock()
+ if el, ok := c.items[pn]; ok {
+ // Another worker rendered the page concurrently; reuse it and discard
+ // our redundant copy.
+ e := el.Value.(pageCacheEntry)
+ e.ref++
+ el.Value = e
+ c.ll.MoveToFront(el)
+ c.mu.Unlock()
+ return e.img, true
+ }
+ el := c.ll.PushFront(pageCacheEntry{pn: pn, img: img, ref: 1})
+ c.items[pn] = el
+ c.evictLocked()
+ c.mu.Unlock()
+ return img, true
+}
+
+// Release marks pn as no longer needed by the caller. It becomes a candidate
+// for LRU eviction; an in-flight ref never drops to 0 while a worker still
+// holds it.
+func (c *lruPageCache) Release(pn int) {
+ c.mu.Lock()
+ if el, ok := c.items[pn]; ok {
+ e := el.Value.(pageCacheEntry)
+ if e.ref > 0 {
+ e.ref--
+ }
+ el.Value = e
+ c.evictLocked()
+ }
+ c.mu.Unlock()
+}
+
+// evictLocked drops least-recently-used pages whose ref is 0 until the cache
+// is within capacity. Caller must hold c.mu. It never evicts a page still
+// referenced by an in-flight worker, so eviction stops early (never
+// over-shrinks) only when every retained page is in use.
+func (c *lruPageCache) evictLocked() {
+ for c.ll.Len() > c.cap {
+ var victim *list.Element
+ for e := c.ll.Back(); e != nil; e = e.Prev() {
+ if e.Value.(pageCacheEntry).ref == 0 {
+ victim = e
+ break
+ }
+ }
+ if victim == nil {
+ return // all retained pages are in use; cannot shrink further
+ }
+ c.ll.Remove(victim)
+ delete(c.items, victim.Value.(pageCacheEntry).pn)
+ }
+}
+
+// pageCacheLimit bounds the shared rendered-page cache so cropping a very long
+// PDF does not retain every page bitmap for the whole document. 64 pages is
+// enough to cover near-term reuse within a contiguous page window; override
+// with RAGFLOW_PAGE_CACHE_LIMIT.
+func pageCacheLimit() int {
+ if v := os.Getenv("RAGFLOW_PAGE_CACHE_LIMIT"); v != "" {
+ if n, err := strconv.Atoi(v); err == nil && n > 0 {
+ return n
+ }
+ }
+ return 64
+}
diff --git a/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go b/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go
new file mode 100644
index 0000000000..3ce402958c
--- /dev/null
+++ b/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go
@@ -0,0 +1,215 @@
+package chunker
+
+import (
+ "image"
+ "sync"
+ "testing"
+)
+
+// taggedImg wraps an image with an id so tests can assert which page bitmap a
+// cache entry holds (pointer identity is unstable across fakeImg calls).
+type taggedImg struct {
+ image.Image
+ id int
+}
+
+func fakeImg(n int) image.Image {
+ return taggedImg{Image: image.NewRGBA(image.Rect(0, 0, 1, 1)), id: n}
+}
+
+// renderCountingFake returns a render func that records how many times each
+// page was actually rendered, so tests can prove an in-use (ref > 0) page is
+// never re-rendered after eviction would otherwise have dropped it.
+func renderCountingFake(rendered *map[int]int, mu *sync.Mutex) func(int) (image.Image, bool) {
+ return func(pn int) (image.Image, bool) {
+ mu.Lock()
+ (*rendered)[pn]++
+ mu.Unlock()
+ return fakeImg(pn), true
+ }
+}
+
+func TestLRUPageCache_BasicMissThenHit(t *testing.T) {
+ c := newLRUPageCache(2)
+ rendered := make(map[int]int)
+ var mu sync.Mutex
+ r := renderCountingFake(&rendered, &mu)
+ if _, ok := c.Acquire(r, 1); !ok {
+ t.Fatal("acquire should succeed on miss")
+ }
+ c.Release(1)
+ img, ok := c.Acquire(r, 1)
+ if !ok {
+ t.Fatal("expected hit for page 1 after release")
+ }
+ if img.(taggedImg).id != 1 {
+ t.Fatalf("wrong image returned, id=%d", img.(taggedImg).id)
+ }
+ // Page 1 was rendered once (miss), then served from cache on the second
+ // Acquire — render must not have been called a second time.
+ if rendered[1] != 1 {
+ t.Fatalf("page 1 rendered %d times, want 1 (no re-render on cache hit)", rendered[1])
+ }
+ c.Release(1)
+}
+
+func TestLRUPageCache_EvictsLeastRecent(t *testing.T) {
+ c := newLRUPageCache(2)
+ rendered := make(map[int]int)
+ var mu sync.Mutex
+ r := renderCountingFake(&rendered, &mu)
+ c.Acquire(r, 1)
+ c.Release(1)
+ c.Acquire(r, 2)
+ c.Release(2)
+ c.Acquire(r, 1) // touch 1 so 2 becomes LRU
+ c.Release(1)
+ c.Acquire(r, 3) // over capacity → evict 2
+ c.Release(3)
+ if _, ok := c.Acquire(r, 2); !ok {
+ t.Fatal("page 2 should be re-renderable after eviction")
+ }
+ c.Release(2)
+ if _, ok := c.Acquire(r, 1); !ok {
+ t.Fatal("page 1 should remain (recently used)")
+ }
+ c.Release(1)
+ if _, ok := c.Acquire(r, 3); !ok {
+ t.Fatal("page 3 should be present")
+ }
+ c.Release(3)
+ // Page 2 was evicted once, so it must have been rendered a second time.
+ if rendered[2] != 2 {
+ t.Fatalf("page 2 rendered %d times, want 2 (evicted then re-rendered)", rendered[2])
+ }
+}
+
+func TestLRUPageCache_GetRefreshesRecency(t *testing.T) {
+ c := newLRUPageCache(2)
+ rendered := make(map[int]int)
+ var mu sync.Mutex
+ r := renderCountingFake(&rendered, &mu)
+ c.Acquire(r, 1)
+ c.Release(1)
+ c.Acquire(r, 2)
+ c.Release(2)
+ c.Acquire(r, 1) // 1 becomes most-recent, 2 is LRU
+ c.Release(1)
+ c.Acquire(r, 3) // evict 2
+ c.Release(3)
+ if _, ok := c.Acquire(r, 2); !ok {
+ t.Fatal("page 2 should be evicted")
+ }
+ c.Release(2)
+}
+
+func TestLRUPageCache_CapacityClampedTo1(t *testing.T) {
+ c := newLRUPageCache(0)
+ rendered := make(map[int]int)
+ var mu sync.Mutex
+ r := renderCountingFake(&rendered, &mu)
+ c.Acquire(r, 1)
+ c.Release(1)
+ if _, ok := c.Acquire(r, 1); !ok {
+ t.Fatal("capacity clamped to 1, page 1 must survive")
+ }
+ c.Release(1)
+ // Pushing a second page must not panic and should keep the cache bounded.
+ c.Acquire(r, 2)
+ c.Release(2)
+}
+
+// TestLRUPageCache_InFlightPageNotEvicted is the core regression guard for the
+// parallel crop path: a page held by an in-flight worker (ref > 0) must never
+// be evicted under the LRU cap, so the worker never loses the bitmap it is
+// still cropping from and never re-renders it.
+func TestLRUPageCache_InFlightPageNotEvicted(t *testing.T) {
+ c := newLRUPageCache(2)
+ rendered := make(map[int]int)
+ var mu sync.Mutex
+ r := renderCountingFake(&rendered, &mu)
+
+ // Hold page 1 in-flight (ref > 0) while we flood the cache past cap.
+ c.Acquire(r, 1)
+ for pn := 10; pn < 30; pn++ {
+ c.Acquire(r, pn)
+ c.Release(pn)
+ }
+ // Page 1 was never released, so it must still be cached and must not have
+ // been re-rendered.
+ if _, ok := c.Acquire(r, 1); !ok {
+ t.Fatal("in-flight page 1 was evicted under LRU cap")
+ }
+ c.Release(1)
+ if rendered[1] != 1 {
+ t.Fatalf("in-flight page 1 rendered %d times, want 1 (never re-rendered while held)", rendered[1])
+ }
+}
+
+func TestLRUPageCache_ReleasedPageBecomesEvictable(t *testing.T) {
+ c := newLRUPageCache(2)
+ rendered := make(map[int]int)
+ var mu sync.Mutex
+ r := renderCountingFake(&rendered, &mu)
+
+ c.Acquire(r, 1)
+ c.Release(1) // now ref == 0, eligible for eviction
+ for pn := 10; pn < 30; pn++ {
+ c.Acquire(r, pn)
+ c.Release(pn)
+ }
+ // Page 1 is now idle (ref == 0) and should have been evicted as LRU filled.
+ if _, ok := c.Acquire(r, 1); !ok {
+ t.Fatal("released idle page 1 should be re-renderable")
+ }
+ c.Release(1)
+ if rendered[1] != 2 {
+ t.Fatalf("released page 1 rendered %d times, want 2 (evicted while idle, re-rendered on use)", rendered[1])
+ }
+}
+
+func TestLRUPageCache_ConcurrentSafe(t *testing.T) {
+ c := newLRUPageCache(8)
+ var wg sync.WaitGroup
+ for g := 0; g < 32; g++ {
+ wg.Add(1)
+ go func(g int) {
+ defer wg.Done()
+ for i := 0; i < 1000; i++ {
+ pn := (g + i) % 16
+ render := func(int) (image.Image, bool) { return fakeImg(pn), true }
+ img, ok := c.Acquire(render, pn)
+ if !ok {
+ t.Errorf("acquire failed for page %d", pn)
+ return
+ }
+ // Simulate cropping from the bitmap, then release.
+ _ = img
+ c.Release(pn)
+ }
+ }(g)
+ }
+ wg.Wait()
+ // Sanity: every page that was ever added can still be queried without
+ // racing; exact membership is non-deterministic under eviction.
+ for pn := 0; pn < 16; pn++ {
+ render := func(int) (image.Image, bool) { return fakeImg(pn), true }
+ c.Acquire(render, pn)
+ c.Release(pn)
+ }
+}
+
+func TestPageCacheLimit_DefaultAndOverride(t *testing.T) {
+ t.Setenv("RAGFLOW_PAGE_CACHE_LIMIT", "")
+ if got := pageCacheLimit(); got != 64 {
+ t.Fatalf("default = %d, want 64", got)
+ }
+ t.Setenv("RAGFLOW_PAGE_CACHE_LIMIT", "8")
+ if got := pageCacheLimit(); got != 8 {
+ t.Fatalf("override = %d, want 8", got)
+ }
+ t.Setenv("RAGFLOW_PAGE_CACHE_LIMIT", "0") // invalid → fall back to default
+ if got := pageCacheLimit(); got != 64 {
+ t.Fatalf("invalid override should fall back to 64, got %d", got)
+ }
+}