Skip to content

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

perf(chunker): coalesce PDF renders and share crop workers (#21850)

jay777210c7fb3d7d7ac
diff --git a/internal/ingestion/component/chunker/pdfcrop_cgo.go b/internal/ingestion/component/chunker/pdfcrop_cgo.go
index db091477d5..adb840babc 100644
--- a/internal/ingestion/component/chunker/pdfcrop_cgo.go
+++ b/internal/ingestion/component/chunker/pdfcrop_cgo.go
@@ -15,9 +15,6 @@ import (
"encoding/base64"
"encoding/json"
"image"
- "os"
- "runtime"
- "strconv"
"sync"
"sync/atomic"
@@ -31,6 +28,7 @@ import (
"ragflow/internal/ingestion/component"
"ragflow/internal/ingestion/component/schema"
"ragflow/internal/parser/parser"
+ "ragflow/internal/utility"
"gorm.io/gorm"
)
@@ -65,26 +63,46 @@ 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.
+// cropJob is one chunk's crop + PNG-encode work.
+type cropJob func(context.Context)
+
+const cropPoolQueueFactor = 4
+
+var (
+ cropPoolOnce sync.Once
+ cropPool *utility.WorkerPool[cropJob, struct{}]
+)
+
+// cropWorkerPool returns the process-wide crop worker pool. Concurrent
+// documents share this pool, so crop concurrency is capped globally instead of
+// per cropImageChunks call. It is created lazily so its default size sees the
+// page concurrency registered at server start (pdf.SetPageConcurrency); package
+// initialization would freeze the pre-config default.
+func cropWorkerPool() *utility.WorkerPool[cropJob, struct{}] {
+ cropPoolOnce.Do(func() {
+ n := cropConcurrency()
+ cropPool = utility.NewWorkerPool[cropJob, struct{}](
+ n, n*cropPoolQueueFactor,
+ func(ctx context.Context, job cropJob) (struct{}, error) {
+ job(ctx)
+ return struct{}{}, nil
+ },
+ )
+ })
+ return cropPool
+}
+
+// cropConcurrency returns the process-wide crop worker count. 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. Crop reuses the
+// existing process-wide PDF page budget (pdf.SetPageConcurrency, resolved from
+// CLI > env > config), so there is one source of truth for PDF concurrency.
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
+ if n := deepdocpdf.PageConcurrency(); n > 0 {
+ return n
}
- return n
+ return 1
}
// cropImageChunks crops image/table chunks and renders text previews (for
@@ -94,8 +112,8 @@ func cropConcurrency() int {
// 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
+// CropSectionImage -> image/png) is dispatched to the process-wide crop 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 {
@@ -155,24 +173,21 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
total := int64(len(candidateIndices))
var settled atomic.Int64
- sem := make(chan struct{}, cropConcurrency())
- var wg sync.WaitGroup
+ pool := cropWorkerPool()
+ futs := make([]utility.WorkerPoolFuture[cropJob, struct{}], 0, len(candidateIndices))
for _, idx := range candidateIndices {
if ctx.Err() != nil {
break
}
- wg.Add(1)
- sem <- struct{}{}
- go func(chunkIdx int) {
- defer wg.Done()
- defer func() { <-sem }()
- if ctx.Err() != nil {
+ chunkIdx := idx
+ fut, err := pool.Submit(ctx, func(jobCtx context.Context) {
+ if jobCtx.Err() != nil {
return
}
defer func() {
- if ctx.Err() == nil {
+ if jobCtx.Err() == nil {
done := settled.Add(1)
- agentruntime.ReportComponentFraction(ctx, float64(done)/float64(total))
+ agentruntime.ReportComponentFraction(jobCtx, float64(done)/float64(total))
}
}()
@@ -233,7 +248,7 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
// here simply falls through to that retry path. kb_id is empty
// only in canvas debug (dry-run) mode, where no persist stage
// runs and the decorator's debug branch drops the raw bytes.
- if kbID, docID := resolveImageUploadContext(ctx, nil); kbID != "" {
+ if kbID, docID := resolveImageUploadContext(jobCtx, nil); kbID != "" {
if rawBytes, derr := base64.StdEncoding.DecodeString(img); derr == nil {
// Key the streamed upload under the chunk's canonical id,
// so the MinIO object is stored under exactly the key the
@@ -243,7 +258,7 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
// derive it from canonical text (folded media context and
// stripped position tags), matching the decorator's text.
chunkID := canonicalChunkID(docID, out[chunkIdx])
- if imgID, uerr := uploadOneImage(ctx, ChunkImageUploader, kbID, chunkID, rawBytes); uerr == nil {
+ if imgID, uerr := uploadOneImage(jobCtx, ChunkImageUploader, kbID, chunkID, rawBytes); uerr == nil {
out[chunkIdx].ImgID = imgID
out[chunkIdx].Image = ""
out[chunkIdx].ID = chunkID
@@ -256,9 +271,20 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
}
}
}
- }(idx)
+ })
+ if err != nil {
+ break
+ }
+ futs = append(futs, fut)
+ }
+ for _, fut := range futs {
+ // Wait with a non-canceled context: a canceled job is skipped by the
+ // pool, but an already-running job must finish before out is returned.
+ res, _ := fut.Wait(context.Background())
+ if res.Err != nil && ctx.Err() == nil {
+ common.Warn("cropImageChunks: crop worker failed", zap.Error(res.Err))
+ }
}
- wg.Wait()
if ctx.Err() == nil {
agentruntime.ReportComponentFraction(ctx, 1.0)
}
diff --git a/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go b/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
index f29afda359..b7924bd781 100644
--- a/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
+++ b/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
@@ -4,17 +4,59 @@ package chunker
import (
"context"
+ "image"
"strings"
+ "sync"
"testing"
+ "time"
+ deepdocpdf "ragflow/internal/deepdoc/parser/pdf"
"ragflow/internal/ingestion/component/schema"
)
+// TestCropConcurrency_UsesPageBudget pins the sizing policy: the crop pool
+// reuses the process-wide PDF page budget instead of deriving its own core
+// fraction or reading a second override.
+func TestCropConcurrency_UsesPageBudget(t *testing.T) {
+ orig := deepdocpdf.PageConcurrency()
+ t.Cleanup(func() { deepdocpdf.SetPageConcurrency(orig) })
+
+ deepdocpdf.SetPageConcurrency(7)
+ if got := cropConcurrency(); got != 7 {
+ t.Fatalf("cropConcurrency() = %d, want page concurrency 7", got)
+ }
+}
+
+// resetCropWorkerPoolForTest replaces the process-wide crop pool with a fresh
+// one sized from the PDF page budget. Resizing the existing pool is not enough
+// for a concurrency test: shrinking only retires workers after they finish a
+// job, so idle workers from an earlier test can still pick up new jobs. Tests
+// in this package run without t.Parallel, so replacing the global pool is safe.
+func resetCropWorkerPoolForTest(t *testing.T, n int) {
+ t.Helper()
+ orig := deepdocpdf.PageConcurrency()
+ if cropPool != nil {
+ cropPool.StopWait()
+ }
+ cropPoolOnce = sync.Once{}
+ cropPool = nil
+ deepdocpdf.SetPageConcurrency(n)
+ cropWorkerPool()
+ t.Cleanup(func() {
+ if cropPool != nil {
+ cropPool.StopWait()
+ }
+ cropPoolOnce = sync.Once{}
+ cropPool = nil
+ deepdocpdf.SetPageConcurrency(orig)
+ })
+}
+
// 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")
+ resetCropWorkerPoolForTest(t, 16)
ctx := context.Background()
eng := mockCropEngine{}
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
@@ -40,7 +82,7 @@ func TestCropImageChunks_ConcurrentCropsAll(t *testing.T) {
// (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")
+ resetCropWorkerPoolForTest(t, 16)
ctx := context.Background()
eng := mockCropEngine{}
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
@@ -57,3 +99,96 @@ func TestCropImageChunks_ConcurrentPageCacheReuse(t *testing.T) {
}
}
}
+
+// blockingCropEngine holds every render until gate is closed so a test can
+// observe how many crop jobs enter the shared pool at once.
+type blockingCropEngine struct {
+ mockCropEngine
+ started chan struct{}
+ gate chan struct{}
+
+ mu sync.Mutex
+ active int
+ maxSeen int
+}
+
+func (e *blockingCropEngine) RenderPageImage(_ int, _ float64) (image.Image, error) {
+ e.mu.Lock()
+ e.active++
+ if e.active > e.maxSeen {
+ e.maxSeen = e.active
+ }
+ e.mu.Unlock()
+
+ select {
+ case e.started <- struct{}{}:
+ default:
+ }
+ <-e.gate
+
+ e.mu.Lock()
+ e.active--
+ e.mu.Unlock()
+ return image.NewRGBA(image.Rect(0, 0, 64, 64)), nil
+}
+
+func (e *blockingCropEngine) maxConcurrent() int {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ return e.maxSeen
+}
+
+// TestCropImageChunks_ProcessWidePoolLimitsConcurrency proves two independent
+// cropImageChunks calls share the process-wide pool: with one worker, the
+// second call cannot render while the first is blocked.
+func TestCropImageChunks_ProcessWidePoolLimitsConcurrency(t *testing.T) {
+ resetCropWorkerPoolForTest(t, 1)
+ eng := &blockingCropEngine{
+ started: make(chan struct{}, 2),
+ gate: make(chan struct{}),
+ }
+ var gateOnce sync.Once
+ release := func() { gateOnce.Do(func() { close(eng.gate) }) }
+ t.Cleanup(release)
+
+ pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
+ chunks := []schema.ChunkDoc{{DocType: "image", Text: "cap", PDFPositions: pos}}
+
+ var wg sync.WaitGroup
+ run := func() {
+ defer wg.Done()
+ _ = cropImageChunks(context.Background(), eng, chunks)
+ }
+ wg.Add(2)
+ go run()
+
+ select {
+ case <-eng.started:
+ case <-time.After(5 * time.Second):
+ t.Fatal("timed out waiting for the first crop render")
+ }
+
+ go run()
+
+ // Wait until both calls have submitted their job. The first is blocked in
+ // RenderPageImage; the second must remain queued behind the single worker.
+ deadline := time.Now().Add(5 * time.Second)
+ for cropWorkerPool().Stats().PendingTotal < 2 {
+ if time.Now().After(deadline) {
+ t.Fatalf("timed out waiting for both crop jobs to be submitted: %+v", cropWorkerPool().Stats())
+ }
+ time.Sleep(5 * time.Millisecond)
+ }
+
+ select {
+ case <-eng.started:
+ t.Fatal("second crop render started while the first was blocked; the crop pool is not process-wide")
+ case <-time.After(100 * time.Millisecond):
+ }
+ if got := eng.maxConcurrent(); got != 1 {
+ t.Fatalf("max concurrent crop renders = %d, want 1 (pool size 1)", got)
+ }
+
+ release()
+ wg.Wait()
+}
diff --git a/internal/ingestion/component/chunker/pdfcrop_pagecache.go b/internal/ingestion/component/chunker/pdfcrop_pagecache.go
index d958098a09..ea78ade30f 100644
--- a/internal/ingestion/component/chunker/pdfcrop_pagecache.go
+++ b/internal/ingestion/component/chunker/pdfcrop_pagecache.go
@@ -34,14 +34,14 @@ type pageCacheEntry struct {
// 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.
+// can never lose a page it still holds a reference to. Concurrent loads of the
+// same page are serialized so workers share the loaded bitmap.
type lruPageCache struct {
- mu sync.Mutex
- ll *list.List // front = most-recently-used; element value = pageCacheEntry
- items map[int]*list.Element
- cap int
+ loading [64]sync.Mutex
+ 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
@@ -60,17 +60,27 @@ func newLRUPageCache(capacity int) *lruPageCache {
// 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.
+// never serialized by the cache mutex. Concurrent misses of the same page
+// share one load. A hit is served without taking the page's load stripe, so it
+// never waits for an unrelated page that hashes to the same stripe.
func (c *lruPageCache) Acquire(render func(int) (image.Image, bool), pn int) (image.Image, bool) {
+ // Fast path: a cached page only needs the cache mutex. Taking the load
+ // stripe here would make a hit wait behind an unrelated page's render.
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
+ if img, ok := c.lookupLocked(pn); ok {
+ c.mu.Unlock()
+ return img, true
+ }
+ c.mu.Unlock()
+
+ load := &c.loading[uint(pn)%uint(len(c.loading))]
+ load.Lock()
+ defer load.Unlock()
+
+ // Another worker may have loaded the page while this one waited for the
+ // stripe; recheck before paying for a render.
+ c.mu.Lock()
+ if img, ok := c.lookupLocked(pn); ok {
c.mu.Unlock()
return img, true
}
@@ -82,16 +92,6 @@ func (c *lruPageCache) Acquire(render func(int) (image.Image, bool), pn int) (im
}
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()
@@ -99,6 +99,20 @@ func (c *lruPageCache) Acquire(render func(int) (image.Image, bool), pn int) (im
return img, true
}
+// lookupLocked returns pn's bitmap and marks it referenced. Caller must hold
+// c.mu.
+func (c *lruPageCache) lookupLocked(pn int) (image.Image, bool) {
+ el, ok := c.items[pn]
+ if !ok {
+ return nil, false
+ }
+ e := el.Value.(pageCacheEntry)
+ e.ref++
+ el.Value = e
+ c.ll.MoveToFront(el)
+ return e.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.
diff --git a/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go b/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go
index 3ce402958c..ef4602f5cf 100644
--- a/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go
+++ b/internal/ingestion/component/chunker/pdfcrop_pagecache_test.go
@@ -4,6 +4,7 @@ import (
"image"
"sync"
"testing"
+ "time"
)
// taggedImg wraps an image with an id so tests can assert which page bitmap a
@@ -199,6 +200,167 @@ func TestLRUPageCache_ConcurrentSafe(t *testing.T) {
}
}
+// TestLRUPageCache_ConcurrentSamePageRendersOnce proves that concurrent misses
+// of the same page are coalesced: only the first worker renders, and every
+// worker receives the shared bitmap.
+func TestLRUPageCache_ConcurrentSamePageRendersOnce(t *testing.T) {
+ const (
+ workers = 8
+ pn = 7
+ )
+ c := newLRUPageCache(4)
+
+ var (
+ mu sync.Mutex
+ renders int
+ )
+ started := make(chan struct{})
+ release := make(chan struct{})
+
+ render := func(page int) (image.Image, bool) {
+ mu.Lock()
+ renders++
+ n := renders
+ mu.Unlock()
+ if n == 1 {
+ close(started) // the single in-flight render has started
+ }
+ <-release // hold the page stripe until the test observes the state
+ return fakeImg(page), true
+ }
+
+ imgs := make([]image.Image, workers)
+ oks := make([]bool, workers)
+ var wg sync.WaitGroup
+ wg.Add(workers)
+ for i := 0; i < workers; i++ {
+ go func(i int) {
+ defer wg.Done()
+ imgs[i], oks[i] = c.Acquire(render, pn)
+ }(i)
+ }
+
+ // Let the blocked workers finish and drop their cache refs even when an
+ // assertion below fails before release is closed.
+ defer func() {
+ select {
+ case <-release:
+ default:
+ close(release)
+ }
+ wg.Wait()
+ for _, ok := range oks {
+ if ok {
+ c.Release(pn)
+ }
+ }
+ }()
+
+ select {
+ case <-started:
+ case <-time.After(10 * time.Second):
+ t.Fatal("timed out waiting for the first render to start")
+ }
+
+ // While the first render is still blocked, every other worker must be
+ // waiting on the page stripe rather than rendering the page again.
+ mu.Lock()
+ got := renders
+ mu.Unlock()
+ if got != 1 {
+ t.Fatalf("render called %d times while the first render is in flight, want 1: same-page misses must wait on the page stripe", got)
+ }
+
+ close(release)
+ wg.Wait()
+
+ for i := 0; i < workers; i++ {
+ if !oks[i] {
+ t.Fatalf("worker %d failed to acquire page %d", i, pn)
+ }
+ if imgs[i] == nil {
+ t.Fatalf("worker %d received a nil image", i)
+ }
+ }
+
+ mu.Lock()
+ got = renders
+ mu.Unlock()
+ if got != 1 {
+ t.Fatalf("render called %d times for one page, want 1 (concurrent misses must be coalesced)", got)
+ }
+}
+
+// TestLRUPageCache_HitDoesNotWaitForSameStripeRender proves a cache hit does
+// not take the page-load stripe. Pages 7 and 71 share a stripe (71%64 == 7);
+// rendering page 71 must not delay a hit on page 7.
+func TestLRUPageCache_HitDoesNotWaitForSameStripeRender(t *testing.T) {
+ c := newLRUPageCache(4)
+ if _, ok := c.Acquire(func(int) (image.Image, bool) { return fakeImg(7), true }, 7); !ok {
+ t.Fatal("prime page 7")
+ }
+ c.Release(7)
+
+ started := make(chan struct{})
+ release := make(chan struct{})
+ var releaseOnce sync.Once
+ releaseRender := func() { releaseOnce.Do(func() { close(release) }) }
+
+ var renderWG sync.WaitGroup
+ renderWG.Add(1)
+ var ok71 bool
+ go func() {
+ defer renderWG.Done()
+ _, ok71 = c.Acquire(func(pn int) (image.Image, bool) {
+ close(started)
+ <-release
+ return fakeImg(pn), true
+ }, 71)
+ }()
+
+ defer func() {
+ releaseRender()
+ renderWG.Wait()
+ if ok71 {
+ c.Release(71)
+ }
+ c.Release(7)
+ }()
+
+ select {
+ case <-started:
+ case <-time.After(10 * time.Second):
+ t.Fatal("timed out waiting for page 71 render to start")
+ }
+
+ hitDone := make(chan struct{})
+ var hitOK bool
+ go func() {
+ defer close(hitDone)
+ img, ok := c.Acquire(func(int) (image.Image, bool) {
+ t.Error("cache hit on page 7 must not render")
+ return nil, false
+ }, 7)
+ hitOK = ok
+ if img == nil {
+ t.Error("cache hit on page 7 returned a nil image")
+ }
+ }()
+
+ select {
+ case <-hitDone:
+ case <-time.After(time.Second):
+ releaseRender()
+ <-hitDone
+ t.Fatal("cache hit on page 7 waited for the page 71 render sharing its stripe")
+ }
+
+ if !hitOK {
+ t.Fatal("cache hit on page 7 reported a miss")
+ }
+ c.Release(7)
+}
+
func TestPageCacheLimit_DefaultAndOverride(t *testing.T) {
t.Setenv("RAGFLOW_PAGE_CACHE_LIMIT", "")
if got := pageCacheLimit(); got != 64 {