Skip to content

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

fix(chunker): retain position-only figures in title chunkers (#21309)

monsterlage34fd2b5ca94
diff --git a/internal/ingestion/component/chunker/common.go b/internal/ingestion/component/chunker/common.go
index 4ef02a6645..52904d86f7 100644
--- a/internal/ingestion/component/chunker/common.go
+++ b/internal/ingestion/component/chunker/common.go
@@ -330,9 +330,8 @@ func canonicalChunkText(ck schema.ChunkDoc) string {
return removeTag(materializeMediaContext(ck).Text)
}
-// mediaChunkIDPrefix marks the identity source of a media chunk whose
-// canonical text is empty. The NUL byte keeps the source from colliding with
-// any real chunk text.
+// mediaChunkIDPrefix marks a media-specific identity source. The NUL byte
+// keeps the source from colliding with ordinary chunk text.
const mediaChunkIDPrefix = "\x00media:"
// canonicalChunkID returns the deterministic chunk id: the single identity
@@ -342,9 +341,16 @@ const mediaChunkIDPrefix = "\x00media:"
// ck["id"] from the same already-finalized text as a fallback for chunks that
// bypassed the streamed crop-upload path; the two routes cannot disagree
// because a chunk is either stamped by crop-upload (and the decorator reuses
-// that id) or computed by the decorator fallback — never both — and both hash
-// the same identity.
+// that id) or computed by the decorator fallback — never both. Position-only
+// title media instead reuses the coordinate-and-text id finalized after headings
+// are applied.
func canonicalChunkID(docID string, ck schema.ChunkDoc) string {
+ // Title-family position-only media is stamped with both coordinates and
+ // finalized heading text. Keep that identity through crop uploads,
+ // including failed-upload retries.
+ if isMediaChunk(ck) && ck.ID != "" {
+ return ck.ID
+ }
return common.ChunkID(docID, chunkIDSource(ck))
}
diff --git a/internal/ingestion/component/chunker/crop_title_test.go b/internal/ingestion/component/chunker/crop_title_test.go
index 6dce870773..5a2bc9d7db 100644
--- a/internal/ingestion/component/chunker/crop_title_test.go
+++ b/internal/ingestion/component/chunker/crop_title_test.go
@@ -17,8 +17,14 @@ package chunker
import (
"context"
+ "fmt"
"strings"
"testing"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+ "ragflow/internal/ingestion/component"
+ "ragflow/internal/tokenizer"
)
// TestCropTitleChunks_CropsPositionedChunk pins residual A: chunks
@@ -66,6 +72,206 @@ func TestCropTitleChunks_CropsImageWithPageList(t *testing.T) {
}
}
+// Position-only figures must keep distinct identities even when the root
+// heading supplies identical text. Streamed uploads, decorator retries and
+// the no-engine fallback must agree on the same per-figure IDs. Changing only
+// the heading text must invalidate those IDs for downstream extraction caches.
+func TestCropTitleChunks_PositionOnlyImagesWithRootHeading(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ new func(map[string]any) (runtime.Component, error)
+ }{
+ {"group", NewGroupTitleChunker},
+ {"hierarchy", NewHierarchyTitleChunker},
+ {"manual", NewManualChunker},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ comp, err := tc.new(map[string]any{
+ "levels": [][]string{{`^# `}},
+ "hierarchy": 1,
+ "root_chunk_as_heading": true,
+ })
+ if err != nil {
+ t.Fatalf("new chunker: %v", err)
+ }
+ var originalIDs, changedIDs, repeatedIDs [2]string
+ t.Run("original-heading", func(t *testing.T) {
+ originalIDs = testPositionOnlyImagesWithRootHeading(t, comp, "# Figure context")
+ })
+ t.Run("changed-heading", func(t *testing.T) {
+ changedIDs = testPositionOnlyImagesWithRootHeading(t, comp, "# Updated figure context")
+ })
+ t.Run("repeated-heading", func(t *testing.T) {
+ repeatedIDs = testPositionOnlyImagesWithRootHeading(t, comp, "# Figure context")
+ })
+ for i := range originalIDs {
+ if originalIDs[i] == changedIDs[i] {
+ t.Errorf("figure %d ID %q unchanged after heading text changed at the same coordinates", i, originalIDs[i])
+ }
+ if originalIDs[i] != repeatedIDs[i] {
+ t.Errorf("figure %d ID = %q, want repeatable ID %q", i, repeatedIDs[i], originalIDs[i])
+ }
+ }
+ })
+ }
+}
+
+func testPositionOnlyImagesWithRootHeading(t *testing.T, comp runtime.Component, heading string) [2]string {
+ t.Helper()
+ ctx := withIngestionGlobals(t, "kb1", "doc1")
+ var wantIDs [2]string
+ for _, mode := range []string{"stream", "retry", "no-engine"} {
+ t.Run(mode, func(t *testing.T) {
+ out, err := comp.Invoke(ctx, nil, map[string]any{
+ "name": "doc.pdf",
+ "output_format": "json",
+ "json": []map[string]any{
+ {"text": heading, "doc_type_kwd": "text"},
+ // _pdf_positions carries only page identity; positions supplies the crop.
+ {"text": "", "doc_type_kwd": "image", "_pdf_positions": [][]float64{{2, 0, 0, 0, 0}}, "positions": [][]float64{{1, 10, 100, 10, 100}}},
+ {"text": "", "doc_type_kwd": "image", "_pdf_positions": [][]float64{{2, 0, 0, 0, 0}}, "positions": [][]float64{{1, 200, 300, 200, 300}}},
+ },
+ })
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ chunks, _ := out["chunks"].([]map[string]any)
+ if len(chunks) != 2 {
+ t.Fatalf("chunks = %#v, want two positioned images", chunks)
+ }
+ for _, ck := range chunks {
+ if ck["doc_type_kwd"] != "image" || !strings.Contains(toString(ck["text"]), heading) {
+ t.Fatalf("root heading not applied to image: %#v", ck)
+ }
+ }
+ if chunks[0]["text"] != chunks[1]["text"] {
+ t.Fatal("fixture must give both figures identical heading-only text")
+ }
+ builtIDs := [2]string{toString(chunks[0]["id"]), toString(chunks[1]["id"])}
+
+ rec := &recordingUploader{}
+ orig := ChunkImageUploader
+ ChunkImageUploader = rec.upload
+ t.Cleanup(func() { ChunkImageUploader = orig })
+ if mode == "retry" {
+ ChunkImageUploader = func(ctx context.Context, kbID, chunkID string, data []byte) (string, error) {
+ rec.upload(ctx, kbID, chunkID, data)
+ return "", fmt.Errorf("stream upload failed")
+ }
+ }
+ if mode != "no-engine" {
+ chunks = cropTitleChunks(ctx, assertZeroPageEngine{}, chunks)
+ if len(rec.calls) != 2 {
+ t.Fatalf("uploads = %d, want 2", len(rec.calls))
+ }
+ if rec.calls[0].chunkID == rec.calls[1].chunkID {
+ t.Errorf("different figures share upload key %q", rec.calls[0].chunkID)
+ }
+ for _, ck := range chunks {
+ if mode == "retry" && (ck["img_id"] != nil || !strings.HasPrefix(toString(ck["image"]), "data:image/png;base64,")) {
+ t.Errorf("failed upload must retain bytes for retry: %#v", ck)
+ }
+ }
+ }
+
+ ChunkImageUploader = rec.upload
+ // Ordinary text IDs must retain their existing text-only formula.
+ text := map[string]any{"text": "ordinary text", "doc_type_kwd": "text"}
+ decorated := &imageUploadDecorator{inner: &stubChunker{chunks: append(chunks, text)}}
+ if _, err := decorated.Invoke(ctx, nil, nil); err != nil {
+ t.Fatalf("decorator Invoke: %v", err)
+ }
+ if text["id"] != common.ChunkID("doc1", "ordinary text") {
+ t.Errorf("ordinary text ID changed: %v", text["id"])
+ }
+ ids := [2]string{toString(chunks[0]["id"]), toString(chunks[1]["id"])}
+ if ids != builtIDs {
+ t.Errorf("IDs changed during crop/upload: built %q, decorated %q", builtIDs, ids)
+ }
+ if ids[0] == "" || ids[1] == "" || ids[0] == ids[1] {
+ t.Fatalf("figure IDs must be nonempty and distinct: %q", ids)
+ }
+ if mode == "stream" {
+ wantIDs = ids
+ } else if wantIDs != ids {
+ t.Errorf("IDs = %q, want stable IDs %q", ids, wantIDs)
+ }
+ wantUploads := map[string]int{"stream": 2, "retry": 4, "no-engine": 0}[mode]
+ if len(rec.calls) != wantUploads {
+ t.Fatalf("uploads = %d, want %d", len(rec.calls), wantUploads)
+ }
+ uploads := make(map[string]int)
+ for _, call := range rec.calls {
+ if call.kbID != "kb1" || call.dataLen == 0 || (call.chunkID != ids[0] && call.chunkID != ids[1]) {
+ t.Errorf("upload key differs from decorator ID: %#v", call)
+ }
+ uploads[call.chunkID]++
+ }
+ for _, id := range ids {
+ if uploads[id] != wantUploads/2 {
+ t.Errorf("uploads at %q = %d, want %d", id, uploads[id], wantUploads/2)
+ }
+ }
+ if mode != "no-engine" {
+ for i, ck := range chunks {
+ if ck["img_id"] != "kb1-"+ids[i] || toString(ck["image"]) != "" {
+ t.Errorf("figure %d must reference its uploaded preview and drop inline bytes", i)
+ }
+ }
+ }
+ })
+ }
+ return wantIDs
+}
+
+// Without a root heading or other text, a position-only figure still separates
+// neighboring text records, but is not cropped/uploaded and the tokenizer drops it.
+func TestCropTitleChunks_PositionOnlyImageWithoutHeading(t *testing.T) {
+ tokenizer.SetEngineType("infinity")
+ t.Cleanup(func() { tokenizer.SetEngineType("") })
+ tok, err := component.NewTokenizerComponent(map[string]any{"search_method": []any{"full_text"}})
+ if err != nil {
+ t.Fatalf("new tokenizer: %v", err)
+ }
+ for _, tc := range titleFamilyComponents(t) {
+ t.Run(tc.name, func(t *testing.T) {
+ ctx := withIngestionGlobals(t, "kb1", "doc1")
+ rec := &recordingUploader{}
+ orig := ChunkImageUploader
+ ChunkImageUploader = rec.upload
+ t.Cleanup(func() { ChunkImageUploader = orig })
+ chunks := titleFamilyChunks(t, tc.comp, []map[string]any{
+ {"text": "before figure", "doc_type_kwd": "text"},
+ {"text": "", "doc_type_kwd": "image", "positions": [][]float64{{1, 10, 100, 10, 100}}},
+ {"text": "after figure", "doc_type_kwd": "text"},
+ })
+ if len(chunks) != 3 || chunks[1]["doc_type_kwd"] != "image" || chunks[1]["text"] != "" {
+ t.Fatalf("chunks = %#v, want text, textless figure, text", chunks)
+ }
+ chunks = cropTitleChunks(ctx, mockCropEngine{}, chunks)
+ decorated := &imageUploadDecorator{inner: &stubChunker{chunks: chunks}}
+ out, err := decorated.Invoke(ctx, nil, nil)
+ if err != nil {
+ t.Fatalf("decorator Invoke: %v", err)
+ }
+ if len(rec.calls) != 0 || toString(chunks[1]["image"]) != "" || toString(chunks[1]["img_id"]) != "" {
+ t.Fatalf("textless figure must not be cropped or uploaded: %#v, uploads=%d", chunks[1], len(rec.calls))
+ }
+ out["name"] = "doc.pdf"
+ out["output_format"] = "chunks"
+ final, err := tok.Invoke(ctx, nil, out)
+ if err != nil {
+ t.Fatalf("tokenizer Invoke: %v", err)
+ }
+ got, _ := final["chunks"].([]map[string]any)
+ if len(got) != 2 || strings.TrimSpace(toString(got[0]["text"])) != "before figure" ||
+ strings.TrimSpace(toString(got[1]["text"])) != "after figure" {
+ t.Fatalf("tokenizer chunks = %#v, want only the two separate text chunks", got)
+ }
+ })
+ }
+}
+
// TestCropTitleChunks_NilEnginePassthrough asserts the helper is a no-op
// when no PDF engine is available (best-effort contract).
func TestCropTitleChunks_NilEnginePassthrough(t *testing.T) {
diff --git a/internal/ingestion/component/chunker/group.go b/internal/ingestion/component/chunker/group.go
index b35498985e..aa3e5cdb37 100644
--- a/internal/ingestion/component/chunker/group.go
+++ b/internal/ingestion/component/chunker/group.go
@@ -177,7 +177,8 @@ func chunkFromRecords(parentCtx context.Context, db *gorm.DB, upstream schema.Ch
zap.String("variant", "group"),
zap.Int("groups", len(groups)),
)
- chunks, _ := buildChunksFromRecordGroups(groups, nil, p, isPlainTextFormat(upstream))
+ docID := globals.GlobalOrInput(parentCtx, nil, "doc_id", upstream.DocID)
+ chunks, _ := buildChunksFromRecordGroups(groups, nil, p, isPlainTextFormat(upstream), docID)
// Enforce the title-family token ceiling (chunk_token_cap) right after
// build_chunks and BEFORE the on-demand crop, mirroring Python's
// invoke() order (build -> cap -> set_chunks). ManualChunker passes
@@ -304,7 +305,7 @@ func isPlainTextFormat(upstream schema.ChunkerFromUpstream) bool {
// stay aligned with the returned chunks after empty groups are dropped and
// root_chunk_as_heading is applied, so the token-cap pass can re-prepend a
// chunk's chain to every piece it splits off.
-func buildChunksFromRecordGroups(groups [][]lineRecord, prefixes []string, p *titleChunkerParam, plain bool) ([]map[string]any, []string) {
+func buildChunksFromRecordGroups(groups [][]lineRecord, prefixes []string, p *titleChunkerParam, plain bool, docID string) ([]map[string]any, []string) {
chunks := make([]map[string]any, 0, len(groups))
var outPrefixes []string
if prefixes != nil {
@@ -367,6 +368,17 @@ func buildChunksFromRecordGroups(groups [][]lineRecord, prefixes []string, p *ti
if m := mergePositionMatrix(posSrc...); m != nil {
chunk["positions"] = m
}
+ first := g[0]
+ if !plain && (first.docType == "image" || first.docType == "table") &&
+ chunkText == "" && first.image == "" && first.imgID == nil {
+ if positions := mergePositionMatrix(first.pdfPositions, first.positions); positions != nil {
+ // Seed position-only media identity with coordinates so figures
+ // sharing a root heading stay distinct. The heading text is folded
+ // in below before cropping. These decoded JSON rows always marshal.
+ identity, _ := json.Marshal(positions)
+ chunk["id"] = common.ChunkID(docID, mediaChunkIDPrefix+first.docType+":"+string(identity))
+ }
+ }
chunks = append(chunks, chunk)
if prefixes != nil {
outPrefixes = append(outPrefixes, prefixes[i])
@@ -376,6 +388,10 @@ func buildChunksFromRecordGroups(groups [][]lineRecord, prefixes []string, p *ti
rootText := toString(chunks[0]["text"])
for i := 1; i < len(chunks); i++ {
chunks[i]["text"] = rootText + "\n" + toString(chunks[i]["text"])
+ if id := toString(chunks[i]["id"]); id != "" {
+ // Extractor caches key on id, so it must also identify the final text.
+ chunks[i]["id"] = common.ChunkID(docID, mediaChunkIDPrefix+id+":"+toString(chunks[i]["text"]))
+ }
if prefixes != nil {
outPrefixes[i] = rootText + "\n" + outPrefixes[i]
}
@@ -599,17 +615,20 @@ func lineRecordsFromPayload(payload *string) []lineRecord {
// recordsFromStructured converts parser-shaped items into records: text items
// keep their text, and media items — tables whose TableData has already been
-// rendered to HTML by materializeTableText, images carrying an image payload
-// or reference — pass through as single records. Only an item with none of
-// text, image and img_id is dropped.
+// rendered to HTML by materializeTableText, images carrying an image payload,
+// reference or positions for on-demand cropping — pass through as single
+// records. Only an item with no text, image, img_id or retained position rows
+// is dropped.
func recordsFromStructured(items []schema.ChunkDoc) []lineRecord {
out := make([]lineRecord, 0, len(items))
for _, it := range items {
text := itemTextOrFallback(it)
// A structured table arrives with Text already rendered from TableData
// (materializeTableText); an image item legitimately carries no text —
- // its payload is the image field. Only a truly empty item is skipped.
- if text == "" && it.Image == "" && it.ImgID == "" {
+ // its payload may be positions for on-demand cropping rather than inline
+ // image bytes. Only a truly empty item is skipped.
+ if text == "" && it.Image == "" && it.ImgID == "" &&
+ mergePositionMatrix(it.PDFPositions, it.Positions) == nil {
continue
}
dt := it.DocType
diff --git a/internal/ingestion/component/chunker/hierarchy.go b/internal/ingestion/component/chunker/hierarchy.go
index 2c4e0f817c..7a3bf92d9d 100644
--- a/internal/ingestion/component/chunker/hierarchy.go
+++ b/internal/ingestion/component/chunker/hierarchy.go
@@ -270,7 +270,8 @@ func invokeHierarchy(parentCtx context.Context, db *gorm.DB, inputs map[string]a
zap.Int("record_groups", len(recordGroups)),
)
- chunks, prefixes := buildChunksFromRecordGroups(recordGroups, groupPrefixes, p, isPlainTextFormat(upstream))
+ docID := globals.GlobalOrInput(parentCtx, nil, "doc_id", upstream.DocID)
+ chunks, prefixes := buildChunksFromRecordGroups(recordGroups, groupPrefixes, p, isPlainTextFormat(upstream), docID)
// Enforce the title-family token ceiling (chunk_token_cap) right after
// build_chunks and BEFORE the on-demand crop, mirroring Python's
// invoke() order (build -> cap -> set_chunks). prefixes re-attaches each
diff --git a/internal/ingestion/component/chunker/pdfcrop_cgo.go b/internal/ingestion/component/chunker/pdfcrop_cgo.go
index 1e4087d8b2..7b8bbda5da 100644
--- a/internal/ingestion/component/chunker/pdfcrop_cgo.go
+++ b/internal/ingestion/component/chunker/pdfcrop_cgo.go
@@ -142,10 +142,7 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
if isMediaChunk(ck) && canonicalChunkText(ck) == "" {
continue
}
- raw := ck.PDFPositions
- if len(raw) == 0 {
- raw = ck.Positions
- }
+ raw := cropPositionMatrix(ck)
if len(raw) == 0 {
continue
}
@@ -179,12 +176,9 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
}()
ck := out[chunkIdx]
- raw := ck.PDFPositions
- if len(raw) == 0 {
- raw = ck.Positions
- }
- var matrix [][]any
- if err := json.Unmarshal(raw, &matrix); err != nil || len(matrix) == 0 {
+ raw := cropPositionMatrix(ck)
+ matrix, ok := decodePositionRows(raw)
+ if !ok || len(matrix) == 0 {
return
}
positions := util.PositionsFromMatrix(matrix)
@@ -241,15 +235,9 @@ func cropImageChunks(ctx context.Context, engine deepdoctype.PDFEngine, chunks [
// so the MinIO object is stored under exactly the key the
// decorator (imageUploadDecorator) later exposes as
// ck["id"] and the persist/retrieval path looks it up by.
- // canonicalChunkText is the single source for that id text:
- // it folds media context and strips position tags, so the
- // value equals the tag-stripped (finalized) text the
- // decorator derives — for every chunk type, including
- // image/table chunks whose text still carries position tags
- // when there is no media context. crop depends only on
- // positions, so reading the canonical text here does not
- // alter the cropped image or the chunker's later output
- // text.
+ // Preserve a pre-stamped position-only media id; otherwise
+ // 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 {
out[chunkIdx].ImgID = imgID
@@ -291,25 +279,25 @@ func needsCrop(ck schema.ChunkDoc) bool {
}
}
+// cropPositionMatrix selects _pdf_positions when it contains a positive-area
+// box, otherwise positions. Inspect every row so a page-only first row does
+// not hide a crop region in a later row. Return nil if neither has a region.
+func cropPositionMatrix(ck schema.ChunkDoc) json.RawMessage {
+ for _, raw := range []json.RawMessage{ck.PDFPositions, ck.Positions} {
+ for _, row := range parser.PDFPositionRowsFromJSON(raw) {
+ if row[2] > row[1] && row[4] > row[3] {
+ return raw
+ }
+ }
+ }
+ return nil
+}
+
// hasCropRegion reports whether the chunk carries a position with a
// positive-area box. A page-only position (page number, no geometry) carries
// page identity for the indexer but no region, so it must not trigger a crop.
-//
-// Every row of the matrix is inspected: mergePositionMatrix sorts page-only
-// rows first, so a page-only first row must not hide a real region in a later
-// row. The matrix is read exactly as the crop path reads it (the canonical
-// _pdf_positions first, the legacy positions key as fallback).
func hasCropRegion(ck schema.ChunkDoc) bool {
- raw := ck.PDFPositions
- if len(raw) == 0 {
- raw = ck.Positions
- }
- for _, row := range parser.PDFPositionRowsFromJSON(raw) {
- if row[2] > row[1] && row[4] > row[3] {
- return true
- }
- }
- return false
+ return len(cropPositionMatrix(ck)) > 0
}
// cropChunkType returns the content type that selects the crop. Callers must
diff --git a/internal/ingestion/component/chunker/pdfcrop_cgo_test.go b/internal/ingestion/component/chunker/pdfcrop_cgo_test.go
index 96af3114df..3ddcab0294 100644
--- a/internal/ingestion/component/chunker/pdfcrop_cgo_test.go
+++ b/internal/ingestion/component/chunker/pdfcrop_cgo_test.go
@@ -110,6 +110,10 @@ func TestNeedsCrop(t *testing.T) {
{"page-only image position", schema.ChunkDoc{DocType: "image", PDFPositions: jsonPositions(t, []float64{3, 0, 0, 0, 0})}, false},
{"page-only text position", schema.ChunkDoc{DocType: "text", Positions: jsonPositions(t, []float64{3, 0, 0, 0, 0})}, false},
{"zero-area box with coordinates", schema.ChunkDoc{DocType: "image", PDFPositions: jsonPositions(t, []float64{3, 10, 10, 5, 5})}, false},
+ {"page-only PDF positions fall back to a region", schema.ChunkDoc{DocType: "image", PDFPositions: jsonPositions(t, []float64{3, 0, 0, 0, 0}), Positions: jsonPositions(t, []float64{1, 10, 100, 10, 100})}, true},
+ {"zero-width PDF positions fall back to a region", schema.ChunkDoc{DocType: "image", PDFPositions: jsonPositions(t, []float64{3, 10, 10, 5, 100}), Positions: jsonPositions(t, []float64{1, 10, 100, 10, 100})}, true},
+ {"zero-height PDF positions fall back to a region", schema.ChunkDoc{DocType: "image", PDFPositions: jsonPositions(t, []float64{3, 10, 100, 5, 5}), Positions: jsonPositions(t, []float64{1, 10, 100, 10, 100})}, true},
+ {"neither matrix has a region", schema.ChunkDoc{DocType: "image", PDFPositions: jsonPositions(t, []float64{3, 0, 0, 0, 0}), Positions: jsonPositions(t, []float64{1, 10, 10, 5, 5})}, false},
// --- A page-only row must not hide a real region in a later row:
// mergePositionMatrix sorts page-only rows first.
@@ -125,6 +129,43 @@ func TestNeedsCrop(t *testing.T) {
}
}
+func TestCropImageChunks_PositionFallback(t *testing.T) {
+ region := jsonPositions(t, []float64{1, 10, 100, 10, 100})
+ flatRegion := jsonFlatPosition(t, []float64{1, 10, 100, 10, 100})
+ otherPage := jsonPositions(t, []float64{2, 20, 200, 20, 200})
+ cases := []struct {
+ name string
+ pdfPositions json.RawMessage
+ positions json.RawMessage
+ }{
+ {"page-only", jsonPositions(t, []float64{2, 0, 0, 0, 0}), region},
+ {"zero-width", jsonPositions(t, []float64{2, 10, 10, 5, 100}), region},
+ {"zero-height", jsonPositions(t, []float64{2, 10, 100, 5, 5}), region},
+ {"empty", json.RawMessage(`[]`), region},
+ {"null", json.RawMessage(`null`), region},
+ {"short-row", json.RawMessage(`[[2,10,100,5]]`), region},
+ {"page-only-with-flat-fallback", jsonPositions(t, []float64{2, 0, 0, 0, 0}), flatRegion},
+ {"flat-positions-only", nil, flatRegion},
+ {"prefer-flat-PDF-region", flatRegion, otherPage},
+ {"prefer-PDF-region", region, otherPage},
+ {"PDF-region-after-page-only-row", jsonPositions(t, []float64{1, 0, 0, 0, 0}, []float64{1, 10, 100, 10, 100}), otherPage},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ chunks := []schema.ChunkDoc{{DocType: "image", Text: "figure caption", PDFPositions: tc.pdfPositions, Positions: tc.positions}}
+ // Only page 1 (engine index 0) can render: falling back when a
+ // PDF region exists, or cropping page-only PDF positions, fails.
+ out := cropImageChunks(context.Background(), assertZeroPageEngine{}, chunks)
+ if len(out) != 1 {
+ t.Fatalf("len(out) = %d, want 1", len(out))
+ }
+ if !strings.HasPrefix(out[0].Image, "data:image/png;base64,") {
+ t.Errorf("image = %q, want cropped preview from page 1", out[0].Image)
+ }
+ })
+ }
+}
+
func TestCropImageChunks_CropsImageTableAndText(t *testing.T) {
ctx := context.Background()
// 1-based JSON position (1) must be rendered as 0-based page 0.
diff --git a/internal/ingestion/component/chunker/register.go b/internal/ingestion/component/chunker/register.go
index 51e076c9f5..0f5489d065 100644
--- a/internal/ingestion/component/chunker/register.go
+++ b/internal/ingestion/component/chunker/register.go
@@ -112,10 +112,10 @@ func (d *imageUploadDecorator) Invoke(ctx context.Context, db *gorm.DB, inputs m
// lives in canonicalChunkID (common.go); this loop only re-derives it as
// a fallback for chunks whose id was not already stamped upstream.
//
- // A chunk id may already be stamped (e.g. by the streamed crop-upload
- // path, which keys MinIO by the canonical id). Reuse it so the id is
- // computed exactly once; both routes derive the identity through the
- // shared helpers, so the crop-time key and this id are identical and
+ // A chunk id may already be stamped (by the streamed crop-upload path,
+ // or from title-family media positions and finalized headings). Reuse it so
+ // the identity is not re-derived after upload; both routes derive it through
+ // the shared helpers, so the crop-time key and this id are identical and
// cannot diverge. For chunks that bypassed crop, fall back to deriving
// it here from the already-finalized text — a captionless image folds
// its payload identity in (mediaChunkIdentity), so distinct images in
diff --git a/internal/ingestion/component/chunker/title_structured_media_test.go b/internal/ingestion/component/chunker/title_structured_media_test.go
index c7aa1323e6..9c0bdf3357 100644
--- a/internal/ingestion/component/chunker/title_structured_media_test.go
+++ b/internal/ingestion/component/chunker/title_structured_media_test.go
@@ -176,6 +176,101 @@ func TestTitleFamilyKeepsEmptyTextImageItem(t *testing.T) {
}
}
+// TestTitleFamilyKeepsPositionOnlyImageItem: PDF figures may carry only
+// coordinates until the on-demand crop runs. Keep them as atomic media chunks
+// even when no caption, inline image or stored reference is available yet.
+func TestTitleFamilyKeepsPositionOnlyImageItem(t *testing.T) {
+ for _, fields := range [][]string{{"positions"}, {"_pdf_positions"}, {"positions", "_pdf_positions"}} {
+ t.Run(strings.Join(fields, "+"), func(t *testing.T) {
+ for _, tc := range titleFamilyComponents(t) {
+ t.Run(tc.name, func(t *testing.T) {
+ item := map[string]any{"text": "", "doc_type_kwd": "image"}
+ for _, field := range fields {
+ item[field] = [][]float64{{1, 10, 100, 10, 100}}
+ }
+ chunks := titleFamilyChunks(t, tc.comp, []map[string]any{
+ {"text": "before figure", "doc_type_kwd": "text"},
+ item,
+ {"text": "after figure", "doc_type_kwd": "text"},
+ })
+ if len(chunks) != 3 || chunks[1]["doc_type_kwd"] != "image" {
+ t.Fatalf("chunks = %#v, want text, image, text", chunks)
+ }
+ ck := chunks[1]
+ if ck["text"] != "" {
+ t.Errorf("image text = %q, want empty caption", ck["text"])
+ }
+ want := [][]any{{float64(1), float64(10), float64(100), float64(10), float64(100)}}
+ for _, field := range fields {
+ if got := ck[field]; !reflect.DeepEqual(got, want) {
+ t.Errorf("%s = %#v, want source coordinates %#v", field, got, want)
+ }
+ }
+ if !strings.Contains(toString(chunks[0]["text"]), "before figure") ||
+ !strings.Contains(toString(chunks[2]["text"]), "after figure") {
+ t.Errorf("neighbor text lost or merged across the image: %#v", chunks)
+ }
+ })
+ }
+ })
+ }
+}
+
+// TestTitleFamilyDropsEmptyPositionImageItem: serialized position fields are
+// not a lazy payload unless the position merge retains at least one row.
+func TestTitleFamilyDropsEmptyPositionImageItem(t *testing.T) {
+ for _, value := range []struct {
+ name string
+ pos any
+ }{
+ {"null", nil},
+ {"empty-array", []any{}},
+ {"empty-row", [][]any{{}}},
+ {"short-row", [][]float64{{1, 10}}},
+ } {
+ t.Run(value.name, func(t *testing.T) {
+ for _, fields := range [][]string{{"positions"}, {"_pdf_positions"}, {"positions", "_pdf_positions"}} {
+ t.Run(strings.Join(fields, "+"), func(t *testing.T) {
+ item := map[string]any{"text": "", "doc_type_kwd": "image"}
+ for _, field := range fields {
+ item[field] = value.pos
+ }
+ for _, tc := range titleFamilyComponents(t) {
+ t.Run(tc.name, func(t *testing.T) {
+ chunks := titleFamilyChunks(t, tc.comp, []map[string]any{
+ {"text": "before figure", "doc_type_kwd": "text"},
+ item,
+ {"text": "after figure", "doc_type_kwd": "text"},
+ })
+ if len(chunks) != 1 || chunks[0]["doc_type_kwd"] != "text" ||
+ chunks[0]["text"] != "before figure\nafter figure\n" {
+ t.Fatalf("chunks = %#v, want one merged text chunk without an empty image", chunks)
+ }
+ })
+ }
+ })
+ }
+ })
+ }
+}
+
+func TestTitleFamilyDropsEmptyPositionsBeforeRootHeading(t *testing.T) {
+ comp, err := NewGroupTitleChunker(map[string]any{
+ "levels": [][]string{{`^# `}},
+ "root_chunk_as_heading": true,
+ })
+ if err != nil {
+ t.Fatalf("NewGroupTitleChunker: %v", err)
+ }
+ chunks := titleFamilyChunks(t, comp, []map[string]any{
+ {"text": "# Figure context", "doc_type_kwd": "text"},
+ {"text": "", "doc_type_kwd": "image", "positions": []any{}, "_pdf_positions": nil},
+ })
+ if len(chunks) != 1 || chunks[0]["doc_type_kwd"] != "text" || chunks[0]["text"] != "# Figure context\n" {
+ t.Fatalf("chunks = %#v, want only the heading text chunk", chunks)
+ }
+}
+
// TestTitleFamilyEmptyTextImageUploadsThroughDecorator: the decorated chunker
// uploads the payload at the chunk id, writes img_id, and drops the raw bytes —
// the empty-text image chunk must flow through the same decorator path as