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): 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.goindex 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.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.+// 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 = imgIDout[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.goindex 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 chunkerimport ("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.goindex 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] = elc.evictLocked()@@ -99,6 +99,20 @@ func (c *lruPageCache) Acquire(render func(int) (image.Image, bool), pn int) (imreturn 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.goindex 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 {