Skip to content

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

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.go
index 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, 0
for _, cell := range row {
@@ -487,7 +549,7 @@ func HeaderSetWithBlockType(rows [][]pdf.TSRCell, boxes []pdf.TextBox) map[int]b
continue
}
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.go
new file mode 100644
index 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.go
index 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 header
diff --git a/internal/deepdoc/parser/pdf/table/table_layout.go b/internal/deepdoc/parser/pdf/table/table_layout.go
index 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 table
import (
"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.TSRCell
var 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)