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
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.goindex 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.Chunkereturn 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] = ckif !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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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)+ }+}