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
fix(deepdoc): align table header detection with Python (follow-up to #18404) (#18454)
Jack746fe4f0b3bc
diff --git a/internal/deepdoc/parser/pdf/table/table_cells.go b/internal/deepdoc/parser/pdf/table/table_cells.goindex 944302bede..c087cd7769 100644--- a/internal/deepdoc/parser/pdf/table/table_cells.go+++ b/internal/deepdoc/parser/pdf/table/table_cells.go@@ -406,79 +406,141 @@ func containsCJK(s string) bool {return false}-// HeaderSetWithBlockType returns the set of rows that are header rows, combining-// THREE additive signals to match Python's construct_table header detection-// (table_structure_recognizer.py:336-348):+// HeaderSetWithBlockType returns the set of rows that are header rows, matching+// Python's construct_table header detection (table_structure_recognizer.py:336-348).+// Python scores every row independently (no early stop) and, per column, counts+// the cell toward the header when it has a geometric H OR (for numeric-dominant+// tables) the cell is non-numeric; a numeric cell in a numeric-dominant table is+// skipped entirely (it neither helps nor hurts).//-// 1. Geometric: a box overlapping the header region by ≥0.3 has box.H>0-// (AnnotateTableBoxes sets it against grid[0], the first grid row). A row is-// a header when more than half of its columns have such a box — the same-// column-majority Python applies (per-column any(a.get("H") for a in arr),-// then per-row h/cnt > 0.5). Go hardcodes the header region to grid[0], so-// this matches Python for the common header-on-row-0 case but is an-// approximation, not a 1:1 port.-// 2. blockType (Python: max_type == "Nu" and btype != "Nu"): only contributes-// for numeric-dominant tables, then per-row majority.-// 3. TSR label (Go-only model-agnostic fallback; Python has no exact-// equivalent): a cell whose Label contains "header" counts, then per-row-// majority.+// Go folds Python's geometric (box.H>0) and blockType signals into ONE per-cell+// pass with that exact predicate, so a row is a header when more than half of its+// columns (including skipped numeric ones, matching Python's h/cnt) satisfy it.+// box.H is set by AnnotateTableBoxes against the header-labeled cells (Python+// t_recognizer.py: gather(r".*header$")), not grid[0].//-// A row is a header if ANY signal flags it (no mutually-exclusive gate).-//-// Python divergence: Python stops at the first row that fails the majority (a-// contiguous header prefix); Go scores each row independently and adds signals,-// so a later row that independently clears the majority is still flagged.+// A THIRD, additive signal is Go-only: a TSR cell whose Label contains "header"+// (Python has no exact equivalent) also promotes a row via the same >0.5+// row-majority. A row is a header if ANY signal flags it.//// boxes may be nil (e.g. the test-only cell-grouping path); the geometric signal// is then skipped and only blockType + label are consulted.func HeaderSetWithBlockType(rows [][]pdf.TSRCell, boxes []pdf.TextBox) map[int]bool {- // Compute dominant block type across all cells.+ // Compute dominant block type across all cells (Python: max_type, derived+ // from box btype with first-seen tie-breaking). Track first-seen order so+ // the tie rule matches Python's Counter+max (first max wins on ties).typeCounts := make(map[string]int)+ order := []string{}+ seen := make(map[string]bool)for _, row := range rows {for _, cell := range row {- t := strings.TrimSpace(cell.Text)- if t != "" {- typeCounts[BlockType(t)]+++ if t := strings.TrimSpace(cell.Text); t != "" {+ bt := BlockType(t)+ if !seen[bt] {+ seen[bt] = true+ order = append(order, bt)+ }+ typeCounts[bt]++}}}maxType := ""- maxCount := 0- for t, c := range typeCounts {- if c > maxCount {- maxType = t- maxCount = c+ maxCount := -1+ for _, t := range order {+ if typeCounts[t] > maxCount {+ maxType, maxCount = t, typeCounts[t]+ }+ }++ // Geometric H per cell, from boxes overlapping the header region (box.H > 0).+ // colHit[row][col] = true when that column's cell has such a box.+ //+ // The boxes' R/C may have been assigned against the PRE-cleanup grid while+ // `rows` here is POST-cleanup (CleanupOrphanColumns/Rows in ConstructTable+ // removes empty rows/columns). So we re-derive (row, column) from geometry+ // instead of trusting the stale R/C — matching Python, which keys the+ // geometric H off the box itself and never re-indexes by a stale coordinate.+ colHit := make(map[int]map[int]bool)+ for i := range boxes {+ b := boxes[i]+ if b.H <= 0 {+ continue+ }+ bestRi, bestCi, bestOv := -1, -1, 0.0+ for ri, row := range rows {+ for ci, cell := range row {+ if tsrBoxOverlap(b, cell) {+ continue // no overlap with this cell+ }+ if ov := util.OverlapInter(&b, &cell); ov > bestOv {+ bestOv, bestRi, bestCi = ov, ri, ci+ }+ }+ }+ if bestRi >= 0 {+ // Geometry resolved the cell against the (post-cleanup) rows.+ if colHit[bestRi] == nil {+ colHit[bestRi] = make(map[int]bool)+ }+ colHit[bestRi][bestCi] = true+ } else if b.R >= 0 && b.R < len(rows) && b.C >= 0 && b.C < len(rows[b.R]) {+ // No geometric overlap (e.g. boxes supplied without coordinates):+ // fall back to the box's own R/C when it is in range, so callers+ // that pre-assigned a correct R/C still work.+ if colHit[b.R] == nil {+ colHit[b.R] = make(map[int]bool)+ }+ colHit[b.R][b.C] = true}}hdrs := make(map[int]bool)- // Signal 2: blockType (numeric-dominant tables only).- for ri, row := range rows {- cnt, h := 0, 0- for _, cell := range row {- t := strings.TrimSpace(cell.Text)- if t == "" {- continue- }- cnt++- bt := BlockType(t)- // Python: max_type == "Nu" and cell btype == "Nu" → skip- if maxType == "Nu" && bt == "Nu" {- continue+ // Signals 1+2 folded (Python: construct_table, 336-348). Numeric-dominant+ // table: a numeric cell is skipped (continue); otherwise the cell counts when+ // it has H OR is non-numeric. Non-numeric table: the predicate reduces to+ // any(H) — the geometric signal alone.+ if maxType == "Nu" {+ for ri, row := range rows {+ cnt, h := 0, 0+ for ci, cell := range row {+ t := strings.TrimSpace(cell.Text)+ if t == "" {+ continue+ }+ cnt+++ bt := BlockType(t)+ if bt == "Nu" {+ continue // numeric cell in a numeric table: ignored+ }+ if colHit[ri][ci] || bt != "Nu" {+ h+++ }}- // Python: max_type == "Nu" and cell btype != "Nu" → header- if maxType == "Nu" && bt != "Nu" {- h+++ if cnt > 0 && float64(h)/float64(cnt) > 0.5 {+ hdrs[ri] = true}}- if cnt > 0 && float64(h)/float64(cnt) > 0.5 {- hdrs[ri] = true+ } else {+ for ri, row := range rows {+ cnt, h := 0, 0+ for ci, cell := range row {+ if strings.TrimSpace(cell.Text) == "" {+ continue+ }+ cnt+++ if colHit[ri][ci] {+ h+++ }+ }+ if cnt > 0 && float64(h)/float64(cnt) > 0.5 {+ hdrs[ri] = true+ }}}- // Signal 3: TSR label "header" (additive, with 0.5 majority — fixes- // over-detection where a single mislabeled cell promoted a whole data row).+ // Signal 3: TSR label "header" (additive Go-only fallback; Python has no+ // exact equivalent), with the same >0.5 row-majority.for ri, row := range rows {cnt, h := 0, 0for _, cell := range row {@@ -487,7 +549,7 @@ func HeaderSetWithBlockType(rows [][]pdf.TSRCell, boxes []pdf.TextBox) map[int]bcontinue}cnt++- if strings.Contains(cell.Label, "header") || strings.Contains(cell.Label, "Header") {+ if isHeaderLabel(cell.Label) {h++}}@@ -496,39 +558,5 @@ func HeaderSetWithBlockType(rows [][]pdf.TSRCell, boxes []pdf.TextBox) map[int]b}}- // Signal 1: geometric H from boxes (additive, with the same column-majority- // Python uses). For each row, count how many of its columns have at least one- // box overlapping the header region (box.H > 0); mark the row when that- // fraction exceeds 0.5. This mirrors Python's per-column- // any(a.get("H") for a in arr) followed by its per-row h/cnt > 0.5 — distinct- // from the old BoxHeaderSet any-box rule, which flagged a whole row whenever a- // single stray box overlapped the header region (over-promotion).- if len(boxes) > 0 {- // colHit[row] = set of columns whose cell has an H>0 box.- colHit := make(map[int]map[int]bool)- for i := range boxes {- b := boxes[i]- if b.H <= 0 || b.R < 0 || b.R >= len(rows) {- continue- }- if b.C < 0 || b.C >= len(rows[b.R]) {- continue- }- if colHit[b.R] == nil {- colHit[b.R] = make(map[int]bool)- }- colHit[b.R][b.C] = true- }- for ri, row := range rows {- n := len(row)- if n == 0 {- continue- }- if float64(len(colHit[ri]))/float64(n) > 0.5 {- hdrs[ri] = true- }- }- }-return hdrs}diff --git a/internal/deepdoc/parser/pdf/table/table_header_divergence_test.go b/internal/deepdoc/parser/pdf/table/table_header_divergence_test.gonew file mode 100644index 0000000000..50791ed566--- /dev/null+++ b/internal/deepdoc/parser/pdf/table/table_header_divergence_test.go@@ -0,0 +1,150 @@+package table++import (+ pdf "ragflow/internal/deepdoc/parser/pdf/type"+ "testing"+)++// These tests verify Go's header detection against Python's construct_table+// (deepdoc/vision/table_structure_recognizer.py:336-348) and t_recognizer.py.+// They assert the Python behavior. The grid[0] and numeric-skip cases are+// already aligned (GREEN); the box-R/C-after-cleanup case is a known divergence+// currently exposed as RED (TestHeaderSetWithBlockType_BoxRCStaleAfterCleanup).+//+// Python reference:+// - Header region = cells whose label ends in "header"+// (t_recognizer.py:64 `headers = gather(r".*header$")`), NOT the first grid+// row (grid[0] approximation).+// - Per-column predicate `any(a.get("H")) or (max_type=="Nu" and btype!="Nu")`,+// with a numeric cell in a numeric-dominant table SKIPPED entirely+// (table_structure_recognizer.py:343 `continue`). Every row is scored+// independently — there is NO early stop / prefix break.+// - HeaderSetWithBlockType receives boxes whose R/C were assigned against the+// PRE-cleanup grid, but the rows passed in are POST-cleanup (orphan+// rows/columns removed). Python keys the geometric H off the box itself, so+// the Go side must re-derive the box→cell column after cleanup rather than+// trust the stale R/C.++// TestAnnotateTableBoxes_HeaderNotOnFirstRow exposes the grid[0] approximation.+// Python's header region is the set of cells the layout model labeled as header+// (t_recognizer.py:64 `gather(r".*header$")`), NOT the first grid row. So a+// header that sits on a row other than row 0 is still detected via H.+// Go used to hardcode `headers = grid[0]` in AnnotateTableBoxes, so a header not+// on row 0 got no H.+//+// Here row 1 (not row 0) is the header. The box on row 1 must receive H>0.+func TestAnnotateTableBoxes_HeaderNotOnFirstRow(t *testing.T) {+ cells := []pdf.TSRCell{+ {X0: 0, Y0: 10, X1: 100, Y1: 30, Label: "table row"}, // row 0: data+ {X0: 0, Y0: 30, X1: 100, Y1: 50, Label: "table column header"}, // row 1: header+ }+ boxes := []pdf.TextBox{+ {X0: 0, X1: 100, Top: 10, Bottom: 30, LayoutType: pdf.LayoutTypeTable, Text: "Data"}, // overlaps row 0+ {X0: 0, X1: 100, Top: 30, Bottom: 50, LayoutType: pdf.LayoutTypeTable, Text: "Header"}, // overlaps row 1+ }++ AnnotateTableBoxes(boxes, GroupTSRCellsToRows(cells))++ hdrIdx, dataIdx := -1, -1+ for i := range boxes {+ if boxes[i].R == 1 {+ hdrIdx = i+ }+ if boxes[i].R == 0 {+ dataIdx = i+ }+ }+ if hdrIdx < 0 || dataIdx < 0 {+ t.Fatal("boxes were not annotated with a row index")+ }++ // Python: header region = header-labeled cells (row 1) -> the row-1 box overlaps it -> H>0.+ if boxes[hdrIdx].H <= 0 {+ t.Errorf("GRID[0] DIVERGENCE: the box on the real header row (row 1) must get H>0 (Python matches header-labeled boxes, not grid[0]). Got H=%d", boxes[hdrIdx].H)+ }+ // Python: the row-0 data box does NOT overlap the header region -> H stays 0.+ if boxes[dataIdx].H > 0 {+ t.Errorf("GRID[0] DIVERGENCE: Go's grid[0] approximation wrongly sets H on the non-header row-0 box. Got H=%d", boxes[dataIdx].H)+ }+}++// TestHeaderSetWithBlockType_NumericCellsSkipped exposes the per-cell predicate+// divergence. In a numeric-dominant table Python SKIPS numeric cells+// (table_structure_recognizer.py:343 `continue`): a numeric column with H+// contributes NOTHING — only non-numeric columns can push a row past the >0.5+// majority. Go's OLD code evaluated the geometric H signal in a separate pass+// that counted numeric-with-H columns, so it over-detected.+//+// Here 3/4 columns are numeric and carry H, only 1 is non-numeric. Python:+// 1/4 non-numeric < 0.5 -> NOT a header. The faithful fold must agree.+func TestHeaderSetWithBlockType_NumericCellsSkipped(t *testing.T) {+ rows := [][]pdf.TSRCell{+ {+ {Text: "100", Label: "table row"}, // numeric, gets H below+ {Text: "200", Label: "table row"}, // numeric, gets H+ {Text: "300", Label: "table row"}, // numeric, gets H+ {Text: "Name", Label: "table row"}, // non-numeric, no H+ },+ }++ // col0/1/2 boxes carry H (they overlap the header region); col3 does not.+ boxes := []pdf.TextBox{+ {Text: "100", R: 0, C: 0, H: 1},+ {Text: "200", R: 0, C: 1, H: 1},+ {Text: "300", R: 0, C: 2, H: 1},+ {Text: "Name", R: 0, C: 3, H: -1},+ }++ hdrs := HeaderSetWithBlockType(rows, boxes)++ // Python skips the 3 numeric columns; only 1/4 is non-numeric -> not a header.+ if hdrs[0] {+ t.Errorf("NUMERIC-SKIP DIVERGENCE: Python skips numeric cells, so 3/4 numeric-with-H columns cannot form a header; only 1/4 non-numeric -> not a header. Go's old per-pass geometric counted them and over-detected: %v", hdrs)+ }+}++// TestHeaderSetWithBlockType_BoxRCStaleAfterCleanup exposes the R/C-stale+// divergence (CodeRabbit review of PR #18454). In production (table_construct.go)+// CleanupOrphanColumns/Rows removes empty rows/columns from `rows` AFTER+// AnnotateTableBoxes assigned each box its R/C against the PRE-cleanup grid.+// HeaderSetWithBlockType then indexes `rows` with those stale R/C. A box whose+// column was shifted left by a removed column now points past the end of the+// cleaned row and is dropped, so a fully header-overlapped row can be missed.+//+// Python keys the geometric H off the box itself (box["H"] > 0) and never+// re-indexes by a stale grid coordinate, so it is unaffected.+//+// Here `rows` is the POST-cleanup grid (2 cols); the boxes carry PRE-cleanup+// column indices (C=1 and C=2) because column 0 was an orphan that got removed.+// Both boxes overlap the header row and carry H>0, so the row must be a header.+// Go (trusting stale C) drops the C=2 box and only counts 1/2 -> misses it.+func TestHeaderSetWithBlockType_BoxRCStaleAfterCleanup(t *testing.T) {+ // POST-cleanup grid: 2 columns with real coordinates. Row 0 is the header,+ // but its cells carry NO "header" label, so only the geometric signal+ // (box.H>0) can detect it — this isolates the R/C-stale bug from the label+ // fallback.+ rows := [][]pdf.TSRCell{+ {+ {X0: 0, X1: 50, Y0: 10, Y1: 30, Text: "H0", Label: "table row"},+ {X0: 50, X1: 100, Y0: 10, Y1: 30, Text: "H1", Label: "table row"},+ },+ {+ {X0: 0, X1: 50, Y0: 30, Y1: 50, Text: "D0", Label: "table row"},+ {X0: 50, X1: 100, Y0: 30, Y1: 50, Text: "D1", Label: "table row"},+ },+ }+ // PRE-cleanup boxes: column 0 was an orphan and removed, so the original+ // columns 1 and 2 are now cleaned columns 0 and 1. The boxes still carry the+ // old C (1 and 2) and H>0 (they overlapped the header region), but their+ // geometry correctly overlaps the cleaned columns.+ boxes := []pdf.TextBox{+ {X0: 5, X1: 45, Top: 12, Bottom: 28, Text: "H0", R: 0, C: 1, H: 1},+ {X0: 55, X1: 95, Top: 12, Bottom: 28, Text: "H1", R: 0, C: 2, H: 1},+ }++ hdrs := HeaderSetWithBlockType(rows, boxes)++ if !hdrs[0] {+ t.Errorf("R/C-STALE DIVERGENCE: both boxes overlap the header row with H>0 (2/2 columns), so row 0 must be a header. Go trusts the stale PRE-cleanup C and drops the C=2 box (past the cleaned row), counting only 1/2 -> misses it: %v", hdrs)+ }+}diff --git a/internal/deepdoc/parser/pdf/table/table_header_parity_test.go b/internal/deepdoc/parser/pdf/table/table_header_parity_test.goindex 5e2c24375d..b16ad034c6 100644--- a/internal/deepdoc/parser/pdf/table/table_header_parity_test.go+++ b/internal/deepdoc/parser/pdf/table/table_header_parity_test.go@@ -20,11 +20,11 @@ import (// header if ANY signal flags it.// =============================================================================-// TestHeaderDetection_GeometricPathVsProductionPathDiverge verifies the+// TestHeaderDetection_GeometricPathAndProductionPathAgree verifies the// production TSR-grid path (HeaderSetWithBlockType) and the box-geometric path// (BoxHeaderSet) agree on the same table: a non-numeric, unlabeled header row// whose boxes overlap the header region must be detected by both.-func TestHeaderDetection_GeometricPathVsProductionPathDiverge(t *testing.T) {+func TestHeaderDetection_GeometricPathAndProductionPathAgree(t *testing.T) {// Same 2-row, 2-col table, two views:// - TSR grid: row 0 cells have NO "header" label (TSR missed them).// - boxes: row 0 boxes carry H>0 (they geometrically overlap the headerdiff --git a/internal/deepdoc/parser/pdf/table/table_layout.go b/internal/deepdoc/parser/pdf/table/table_layout.goindex ca3d47120a..895a98df62 100644--- a/internal/deepdoc/parser/pdf/table/table_layout.go+++ b/internal/deepdoc/parser/pdf/table/table_layout.go@@ -2,6 +2,8 @@ package tableimport ("math"+ "strings"+pdf "ragflow/internal/deepdoc/parser/pdf/type""ragflow/internal/deepdoc/parser/pdf/util""sort"@@ -87,6 +89,12 @@ func notOverlapped(a, b pdf.TSRCell) bool {return a.X1 < b.X0 || a.X0 > b.X1 || a.Y1 < b.Y0 || a.Y0 > b.Y1}+// isHeaderLabel reports whether a TSR cell label denotes a header region,+// matching Python's gather(r".*header$") in t_recognizer.py.+func isHeaderLabel(label string) bool {+ return strings.HasSuffix(strings.ToLower(label), "header")+}+// tsrBoxOverlap returns true if a pdf.TextBox and a pdf.TSRCell do NOT overlap.func tsrBoxOverlap(b pdf.TextBox, c pdf.TSRCell) bool {return b.X1 < c.X0 || b.X0 > c.X1 || b.Bottom < c.Y0 || b.Top > c.Y1@@ -153,8 +161,18 @@ func AnnotateTableBoxes(boxes []pdf.TextBox, grid [][]pdf.TSRCell) {// grid[0] is the header row. Spans are computed by calSpans later.var headers, spans []pdf.TSRCellvar clmns []pdf.TSRCell+ // Python t_recognizer.py: headers = gather(r".*header$") — the set of layout+ // cells whose label ends in "header", NOT the first grid row. Collect them+ // from every grid row so a header that sits on a row other than 0 is still+ // matched and tagged with H>0 (fixes the grid[0] approximation).+ for _, row := range grid {+ for _, cell := range row {+ if isHeaderLabel(cell.Label) {+ headers = append(headers, cell)+ }+ }+ }if len(grid) > 0 {- headers = grid[0]clmns = append(clmns, grid[0]...)}SortYFirstly(headers, 10)