Skip to content

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

fix(chunker): skip crop+upload for non-retrievable empty-text media (#20213)

xugangqiang79bacdf9795b
diff --git a/internal/ingestion/component/chunker/common.go b/internal/ingestion/component/chunker/common.go
index b4eea7c327..2c942169c2 100644
--- a/internal/ingestion/component/chunker/common.go
+++ b/internal/ingestion/component/chunker/common.go
@@ -169,6 +169,18 @@ func itemDocType(it schema.ChunkDoc) string {
return "text"
}
+// isMediaChunk reports whether a chunk is an image or table region. It checks
+// CKType first (general/token paths set it) and falls back to DocType
+// (group/hierarchy forward parser output that carries only doc_type_kwd), so
+// it classifies media regardless of which chunker produced the chunk.
+func isMediaChunk(ck schema.ChunkDoc) bool {
+ typ := strings.ToLower(strings.TrimSpace(ck.CKType))
+ if typ == "" {
+ typ = strings.ToLower(strings.TrimSpace(ck.DocType))
+ }
+ return typ == "image" || typ == "table"
+}
+
// itemTextOrFallback returns the item's preferred text, or "".
func itemTextOrFallback(it schema.ChunkDoc) string {
if t, ok := itemText(it); ok {
diff --git a/internal/ingestion/component/chunker/pdfcrop_cgo.go b/internal/ingestion/component/chunker/pdfcrop_cgo.go
index f6d6c44718..315a047b47 100644
--- a/internal/ingestion/component/chunker/pdfcrop_cgo.go
+++ b/internal/ingestion/component/chunker/pdfcrop_cgo.go
@@ -126,6 +126,21 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
if !needsCrop(ck) || ck.Image != "" {
continue
}
+ // A media chunk whose finalized text is empty — no caption, no vision
+ // description, no media context — is not retrievable: its embedding
+ // would be the empty-string vector, so retrieval can never surface it,
+ // and every captionless image/table in a document would otherwise
+ // collapse onto the same canonical id (ChunkID(docID, "")), each
+ // overwrite the other's MinIO object. Skip the crop and upload
+ // entirely; the finalizer then drops the chunk, so no object is
+ // orphaned and no pdfium render / PNG encode / upload is wasted. This
+ // mirrors Python's token_chunker drop of empty-text media chunks.
+ // Text chunks are excluded: a text body always carries content, and the
+ // Chunker-1.3 preview restore must still run for positioned text
+ // regions.
+ if isMediaChunk(ck) && canonicalChunkText(ck) == "" {
+ continue
+ }
raw := ck.PDFPositions
if len(raw) == 0 {
raw = ck.Positions
diff --git a/internal/ingestion/component/chunker/pdfcrop_cgo_test.go b/internal/ingestion/component/chunker/pdfcrop_cgo_test.go
index e9b4736c11..784ebbe4e4 100644
--- a/internal/ingestion/component/chunker/pdfcrop_cgo_test.go
+++ b/internal/ingestion/component/chunker/pdfcrop_cgo_test.go
@@ -110,8 +110,8 @@ func TestCropImageChunks_CropsImageTableAndText(t *testing.T) {
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
chunks := []schema.ChunkDoc{
- {CKType: "image", PDFPositions: pos},
- {CKType: "table", PDFPositions: pos},
+ {CKType: "image", Text: "img", PDFPositions: pos},
+ {CKType: "table", Text: "tbl", PDFPositions: pos},
{CKType: "text", PDFPositions: pos}, // restored preview (Chunker-1.3)
{CKType: "image", Image: "data:image/png;base64,preexisting"}, // preserved
}
@@ -158,8 +158,8 @@ func TestCropImageChunks_DocTypeFallbackCropsImageTableText(t *testing.T) {
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
chunks := []schema.ChunkDoc{
- {DocType: "image", PDFPositions: pos},
- {DocType: "table", PDFPositions: pos},
+ {DocType: "image", Text: "img", PDFPositions: pos},
+ {DocType: "table", Text: "tbl", PDFPositions: pos},
// A plain text body chunk from group/hierarchy has CKType empty and
// doc_type_kwd "text"; the DocType fallback must crop its preview,
// mirroring Python restore_pdf_text_previews. (Real group/hierarchy
@@ -254,7 +254,7 @@ func TestCropImageChunks_RenderFailureSkipsChunk(t *testing.T) {
// mockCropEngine renders a real image, so a non-empty crop is expected.
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
chunks := []schema.ChunkDoc{
- {CKType: "image", PDFPositions: pos},
+ {CKType: "image", Text: "cap", PDFPositions: pos},
}
out := cropImageChunks(ctx, mockCropEngine{}, chunks)
if len(out) != 1 {
@@ -376,7 +376,7 @@ func TestCropImageChunks_NoUploadWhenKBAbsent(t *testing.T) {
eng := mockCropEngine{}
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
- chunks := []schema.ChunkDoc{{CKType: "image", PDFPositions: pos}}
+ chunks := []schema.ChunkDoc{{CKType: "image", Text: "img", PDFPositions: pos}}
out := cropImageChunks(ctx, eng, chunks)
if len(rec.calls) != 0 {
@@ -463,6 +463,73 @@ func TestCropImageChunks_StreamingUploadUsesFinalizedText(t *testing.T) {
}
}
+// TestCropImageChunks_SkipsEmptyTextMedia verifies that a media chunk whose
+// finalized text is empty — no caption, no vision description, no media
+// context — is NOT cropped or uploaded. Such a chunk is not retrievable
+// (its embedding would be the empty-string vector) and, under the old
+// behavior, collapsed every captionless image/table in a document onto the
+// same canonical id ChunkID(docID, ""), overwriting each other's MinIO
+// object. Skipping the crop+upload here means no object is orphaned and no
+// pdfium render / PNG encode / upload work is wasted; the finalizer then
+// drops the chunk outright (mirroring Python's token_chunker empty-text
+// drop). A captioned (or context-bearing) media chunk must still be cropped
+// and uploaded, so this is guarded by finalized-text emptiness, not by the
+// media type alone.
+func TestCropImageChunks_SkipsEmptyTextMedia(t *testing.T) {
+ ctx := withIngestionGlobals(t, "kb1", "doc1")
+
+ rec := &recordingUploader{}
+ orig := ChunkImageUploader
+ ChunkImageUploader = rec.upload
+ t.Cleanup(func() { ChunkImageUploader = orig })
+
+ eng := mockCropEngine{}
+ pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
+ emptyMedia := []schema.ChunkDoc{
+ {CKType: "image", PDFPositions: pos}, // no text
+ {CKType: "table", PDFPositions: pos}, // no text
+ {CKType: "image", Text: "@@1\t2##", PDFPositions: pos}, // position tag only, no body
+ {CKType: "table", ContextAbove: "", ContextBelow: "", PDFPositions: pos}, // explicit empty
+ {DocType: "image", PDFPositions: pos}, // doc-type fallback, no text
+ }
+ out := cropImageChunks(ctx, eng, emptyMedia)
+ if len(out) != len(emptyMedia) {
+ t.Fatalf("len(out) = %d, want %d", len(out), len(emptyMedia))
+ }
+ if len(rec.calls) != 0 {
+ t.Fatalf("upload calls = %d, want 0 for empty-text media", len(rec.calls))
+ }
+ for i, ck := range out {
+ if ck.Image != "" {
+ t.Errorf("chunk %d: Image = %q, want empty (must not be cropped)", i, ck.Image)
+ }
+ if ck.ImgID != "" {
+ t.Errorf("chunk %d: ImgID = %q, want empty (must not be uploaded)", i, ck.ImgID)
+ }
+ }
+
+ // Sanity: a captioned media chunk is still cropped and uploaded.
+ captioned := []schema.ChunkDoc{
+ {CKType: "image", Text: "a real figure caption", PDFPositions: pos},
+ }
+ out2 := cropImageChunks(ctx, eng, captioned)
+ if len(out2) != 1 {
+ t.Fatalf("len(out2) = %d, want 1", len(out2))
+ }
+ if len(rec.calls) != 1 {
+ t.Fatalf("captioned upload calls = %d, want 1", len(rec.calls))
+ }
+ // With a KB present the preview is streamed then the in-memory base64 is
+ // dropped (the #20165 memory fix), so assert the upload landed (ImgID set)
+ // rather than the transient Image field.
+ if out2[0].ImgID == "" {
+ t.Errorf("captioned chunk ImgID = %q, want uploaded id", out2[0].ImgID)
+ }
+ if out2[0].Image != "" {
+ t.Errorf("captioned chunk Image = %q, want cleared after upload", out2[0].Image)
+ }
+}
+
// TestCropImageChunks_StreamingUploadUsesCanonicalID is the regression test
// for the most common chunk shape: an image/table chunk whose Text still
// carries parser position tags (@@…##) but has NO media context
@@ -485,8 +552,10 @@ func TestCropImageChunks_StreamingUploadUsesCanonicalID(t *testing.T) {
eng := mockCropEngine{}
pos := jsonPositions(t, []float64{1, 10, 100, 10, 100})
- // Text carries a parser position tag (@@x\t y##), no media context.
- in := schema.ChunkDoc{CKType: "image", Text: "abc@@1\t2##", PDFPositions: pos}
+ // Text carries a parser position tag (@@x\t y##) AND a caption, no media
+ // context — materializeMediaContext short-circuits, so the tag-stripped
+ // canonical text is "fig caption".
+ in := schema.ChunkDoc{CKType: "image", Text: "fig caption@@1\t2##", PDFPositions: pos}
out := cropImageChunks(ctx, eng, []schema.ChunkDoc{in})
if len(out) != 1 {
diff --git a/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go b/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
index a0f252e449..b98a735ad5 100644
--- a/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
+++ b/internal/ingestion/component/chunker/pdfcrop_concurrency_test.go
@@ -22,7 +22,7 @@ func TestCropImageChunks_ConcurrentCropsAll(t *testing.T) {
const n = 64
chunks := make([]schema.ChunkDoc, n)
for i := 0; i < n; i++ {
- chunks[i] = schema.ChunkDoc{CKType: "image", PDFPositions: pos}
+ chunks[i] = schema.ChunkDoc{CKType: "image", Text: "cap", PDFPositions: pos}
}
out := cropImageChunks(ctx, eng, chunks)
if len(out) != n {
@@ -48,7 +48,7 @@ func TestCropImageChunks_ConcurrentPageCacheReuse(t *testing.T) {
const n = 200
chunks := make([]schema.ChunkDoc, n)
for i := 0; i < n; i++ {
- chunks[i] = schema.ChunkDoc{CKType: "table", Positions: pos}
+ chunks[i] = schema.ChunkDoc{CKType: "table", Text: "cap", Positions: pos}
}
out := cropImageChunks(ctx, eng, chunks)
for i, ck := range out {