Skip to content

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

fix(deepdoc): bucket table boxes by page in buildTableHTMLs (#20133)

xugangqiangbceb84bb4b11
diff --git a/internal/deepdoc/parser/pdf/table/table_html_bypage_test.go b/internal/deepdoc/parser/pdf/table/table_html_bypage_test.go
new file mode 100644
index 0000000000..e5cb535104
--- /dev/null
+++ b/internal/deepdoc/parser/pdf/table/table_html_bypage_test.go
@@ -0,0 +1,291 @@
+package table
+
+import (
+ "maps"
+ "math/rand"
+ "reflect"
+ "testing"
+
+ pdf "ragflow/internal/deepdoc/parser/pdf/type"
+)
+
+// ── brute-force oracles (the pre-optimization behavior) ─────────────────────
+
+// referenceCollectTableBoxes is the unindexed O(boxes*positions) scan that
+// buildTableHTMLs used before the page-bucketing optimization. It returns the
+// table-layout boxes overlapping tbl, in ascending box-index order.
+func referenceCollectTableBoxes(boxes []pdf.TextBox, tbl pdf.TableItem) []pdf.TextBox {
+ var out []pdf.TextBox
+ for i := range boxes {
+ if boxes[i].LayoutType != pdf.LayoutTypeTable {
+ continue
+ }
+ for pi := range tbl.Positions {
+ if boxOverlapsPositionPage(boxes[i], tbl.Positions[pi]) {
+ out = append(out, boxes[i])
+ break
+ }
+ }
+ }
+ return out
+}
+
+// referenceBuildTableHTMLs is the full pre-optimization buildTableHTMLs, copied
+// verbatim as an oracle so the optimized version is provably equivalent.
+func referenceBuildTableHTMLs(boxes []pdf.TextBox, tables []pdf.TableItem) map[int]string {
+ htmls := make(map[int]string)
+ for ti := range tables {
+ if len(tables[ti].Cells) == 0 {
+ continue
+ }
+ s := tables[ti].Scale
+ pageGlobalCells := CellSliceToPageSpace(tables[ti].Cells, tables[ti].CropOffX, tables[ti].CropOffY, s)
+ var tableBoxes []pdf.TextBox
+ for i := range boxes {
+ if boxes[i].LayoutType != pdf.LayoutTypeTable {
+ continue
+ }
+ for _, tp := range tables[ti].Positions {
+ if boxOverlapsPositionPage(boxes[i], tp) {
+ tableBoxes = append(tableBoxes, boxes[i])
+ break
+ }
+ }
+ }
+ htmls[ti] = ConstructTable(pageGlobalCells, tableBoxes, tables[ti].Caption, &tables[ti])
+ }
+ return htmls
+}
+
+// ── synthetic document generators ──────────────────────────────────────────
+
+// buildBoxesForCollectTest builds a mix of table-layout and non-table boxes,
+// some with page metadata and some without. For every table position a matching
+// table box is planted on the same page with overlapping coordinates, so the
+// optimized and brute-force scans both exercise non-empty, order-sensitive
+// selections.
+func buildBoxesForCollectTest(rng *rand.Rand, pages, nBoxes int, tables []pdf.TableItem) []pdf.TextBox {
+ boxes := make([]pdf.TextBox, 0, nBoxes)
+ // Plant one overlapping box per (table, position) so overlaps actually occur.
+ for ti := range tables {
+ for pi := range tables[ti].Positions {
+ pos := tables[ti].Positions[pi]
+ if len(pos.PageNumbers) == 0 {
+ // No-page position: plant a no-page box so it can still overlap.
+ boxes = append(boxes, pdf.TextBox{
+ X0: pos.Left - 1,
+ X1: pos.Right + 1,
+ Top: pos.Top - 1,
+ Bottom: pos.Bottom + 1,
+ LayoutType: pdf.LayoutTypeTable,
+ })
+ continue
+ }
+ p := pos.PageNumbers[0]
+ boxes = append(boxes, pdf.TextBox{
+ PageNumber: p,
+ HasPageNumber: true,
+ X0: pos.Left - 1,
+ X1: pos.Right + 1,
+ Top: pos.Top - 1,
+ Bottom: pos.Bottom + 1,
+ LayoutType: pdf.LayoutTypeTable,
+ })
+ }
+ }
+ // Fill the rest with random boxes (table + non-table, paged + page-less).
+ // Page-less boxes are rare in practice (most boxes carry page metadata), so
+ // only ~5% lack a page number — this keeps the noPage bucket small and the
+ // benchmark representative of real large PDFs.
+ for len(boxes) < nBoxes {
+ p := rng.Intn(pages) + 1
+ // Page-less boxes are very rare in practice (almost every box carries
+ // page metadata). Keep them at ~0.5% so the noPage bucket stays small and
+ // the benchmark exercises the dense, many-boxes-per-page case where the
+ // page-bucketed scan wins big over the brute-force O(boxes*positions).
+ hasPage := rng.Intn(200) < 199
+ isTable := rng.Intn(2) == 0
+ lt := pdf.LayoutTypeText
+ if isTable {
+ lt = pdf.LayoutTypeTable
+ }
+ x0 := rng.Float64() * 1000
+ y0 := rng.Float64() * 1000
+ b := pdf.TextBox{
+ X0: x0,
+ X1: x0 + rng.Float64()*50,
+ Top: y0,
+ Bottom: y0 + rng.Float64()*50,
+ LayoutType: lt,
+ }
+ if hasPage {
+ b.PageNumber = p
+ b.HasPageNumber = true
+ }
+ boxes = append(boxes, b)
+ }
+ return boxes
+}
+
+func buildTablesForTest(rng *rand.Rand, pages, nTables, posPerTab int) []pdf.TableItem {
+ tables := make([]pdf.TableItem, nTables)
+ for ti := 0; ti < nTables; ti++ {
+ poss := make([]pdf.Position, 0, posPerTab)
+ // Occasionally make a position page-agnostic (empty PageNumbers) to cover
+ // the fallback path in collectTableBoxes.
+ for k := 0; k < posPerTab; k++ {
+ if rng.Intn(7) == 0 {
+ poss = append(poss, pdf.Position{
+ Left: rng.Float64() * 1000,
+ Right: rng.Float64()*50 + 50,
+ Top: rng.Float64() * 1000,
+ Bottom: rng.Float64()*50 + 50,
+ })
+ continue
+ }
+ p := rng.Intn(pages) + 1
+ poss = append(poss, pdf.Position{
+ PageNumbers: []int{p},
+ Left: rng.Float64() * 1000,
+ Right: rng.Float64()*50 + 50,
+ Top: rng.Float64() * 1000,
+ Bottom: rng.Float64()*50 + 50,
+ })
+ }
+ tables[ti] = pdf.TableItem{Positions: poss}
+ }
+ return tables
+}
+
+// cloneTablesForHTML deep-copies the TableItem fields ConstructTable reads, so
+// the two implementations can run against independent copies (ConstructTable
+// mutates item.Grid / item.Rows as a side effect).
+func cloneTablesForHTML(in []pdf.TableItem) []pdf.TableItem {
+ out := make([]pdf.TableItem, len(in))
+ for i := range in {
+ t := pdf.TableItem{
+ Scale: 1.0,
+ CropOffX: 0,
+ CropOffY: 0,
+ Caption: in[i].Caption,
+ }
+ t.Positions = append(t.Positions, in[i].Positions...)
+ // Cells with text so ConstructTable takes the grid path and emits HTML.
+ t.Cells = []pdf.TSRCell{
+ {X0: 0, Y0: 0, X1: 10, Y1: 10, Text: "a"},
+ {X0: 0, Y0: 12, X1: 10, Y1: 22, Text: "b"},
+ }
+ out[i] = t
+ }
+ return out
+}
+
+// ── equivalence tests ──────────────────────────────────────────────────────
+
+// TestCollectTableBoxesByPageEquivalence asserts the page-bucketed box selection
+// returns exactly the same boxes, in the same order, as the brute-force scan,
+// over randomized multi-page documents that include page-agnostic positions and
+// page-less boxes.
+func TestCollectTableBoxesByPageEquivalence(t *testing.T) {
+ rng := rand.New(rand.NewSource(1))
+ const pages = 12
+ for seed := int64(0); seed < 50; seed++ {
+ rng.Seed(seed)
+ tables := buildTablesForTest(rng, pages, 60, 3)
+ boxes := buildBoxesForCollectTest(rng, pages, 800, tables)
+ byPage, noPage := indexTableLayoutBoxes(boxes)
+ for ti := range tables {
+ got := collectTableBoxes(boxes, tables[ti], byPage, noPage)
+ want := referenceCollectTableBoxes(boxes, tables[ti])
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("seed=%d table=%d: collectTableBoxes mismatch\n got=%d boxes\nwant=%d boxes",
+ seed, ti, len(got), len(want))
+ }
+ }
+ }
+}
+
+// TestBuildTableHTMLsByPageEquivalence asserts the optimized buildTableHTMLs
+// produces byte-identical HTML to the brute-force reference, end to end.
+func TestBuildTableHTMLsByPageEquivalence(t *testing.T) {
+ rng := rand.New(rand.NewSource(7))
+ const pages = 10
+ for seed := int64(0); seed < 20; seed++ {
+ rng.Seed(seed)
+ tables := buildTablesForTest(rng, pages, 40, 3)
+ boxes := buildBoxesForCollectTest(rng, pages, 500, tables)
+ gotTables := cloneTablesForHTML(tables)
+ wantTables := cloneTablesForHTML(tables)
+ got := buildTableHTMLs(boxes, gotTables)
+ want := referenceBuildTableHTMLs(boxes, wantTables)
+ if !maps.Equal(got, want) {
+ t.Fatalf("seed=%d: buildTableHTMLs html mismatch\ngot =%v\nwant=%v", seed, got, want)
+ }
+ }
+}
+
+// ── benchmarks ─────────────────────────────────────────────────────────────
+
+// benchDocWithCells builds a large multi-page document whose tables carry cells,
+// so the benchmark measures the real box-scan path inside buildTableHTMLs.
+func benchDocWithCells(pages, nBoxes, nTables, posPerTab int, seed int64) ([]pdf.TextBox, []pdf.TableItem) {
+ rng := rand.New(rand.NewSource(seed))
+ tables := buildTablesForTest(rng, pages, nTables, posPerTab)
+ for ti := range tables {
+ tables[ti].Scale = 1.0
+ tables[ti].Cells = []pdf.TSRCell{
+ {X0: 0, Y0: 0, X1: 10, Y1: 10, Text: "a"},
+ {X0: 0, Y0: 12, X1: 10, Y1: 22, Text: "b"},
+ }
+ }
+ return buildBoxesForCollectTest(rng, pages, nBoxes, tables), tables
+}
+
+func BenchmarkCollectTableBoxesIndexed(b *testing.B) {
+ // Dense document: ~1000 boxes/page across 200 pages, 600 tables. This
+ // mirrors a large PDF where the brute-force scan (every box, per table) is
+ // the expensive path; the page-bucketed scan only touches the boxes on the
+ // table's own pages.
+ const pages, nBoxes, nTables, posPerTab = 200, 200000, 400, 3
+ rng := rand.New(rand.NewSource(1))
+ tables := buildTablesForTest(rng, pages, nTables, posPerTab)
+ boxes := buildBoxesForCollectTest(rng, pages, nBoxes, tables)
+ byPage, noPage := indexTableLayoutBoxes(boxes)
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ for ti := range tables {
+ _ = collectTableBoxes(boxes, tables[ti], byPage, noPage)
+ }
+ }
+}
+
+func BenchmarkCollectTableBoxesBrute(b *testing.B) {
+ const pages, nBoxes, nTables, posPerTab = 200, 200000, 400, 3
+ rng := rand.New(rand.NewSource(1))
+ tables := buildTablesForTest(rng, pages, nTables, posPerTab)
+ boxes := buildBoxesForCollectTest(rng, pages, nBoxes, tables)
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ for ti := range tables {
+ _ = referenceCollectTableBoxes(boxes, tables[ti])
+ }
+ }
+}
+
+func BenchmarkBuildTableHTMLsIndexed(b *testing.B) {
+ const pages, nBoxes, nTables, posPerTab = 200, 200000, 400, 3
+ boxes, tables := benchDocWithCells(pages, nBoxes, nTables, posPerTab, 1)
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ _ = buildTableHTMLs(boxes, tables)
+ }
+}
+
+func BenchmarkBuildTableHTMLsBrute(b *testing.B) {
+ const pages, nBoxes, nTables, posPerTab = 200, 200000, 400, 3
+ boxes, tables := benchDocWithCells(pages, nBoxes, nTables, posPerTab, 1)
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ _ = referenceBuildTableHTMLs(boxes, tables)
+ }
+}
diff --git a/internal/deepdoc/parser/pdf/table/table_post.go b/internal/deepdoc/parser/pdf/table/table_post.go
index 78e04cec46..22eb98bfef 100644
--- a/internal/deepdoc/parser/pdf/table/table_post.go
+++ b/internal/deepdoc/parser/pdf/table/table_post.go
@@ -4,9 +4,6 @@ import (
"math"
"sort"
- "go.uber.org/zap"
-
- "ragflow/internal/common"
pdf "ragflow/internal/deepdoc/parser/pdf/type"
)
@@ -133,7 +130,18 @@ func findTableAnchors(boxes []pdf.TextBox, tables []pdf.TableItem) []struct{ ti,
// buildTableHTMLs constructs HTML for each table, converting cells to page space first.
// Returns a map from table index to HTML string.
+//
+// It indexes the table-layout boxes by page once (see indexTableLayoutBoxes) and
+// then, per table, restricts the box scan to the pages the table occupies instead
+// of the whole document. The naive version rescanned every box for every table
+// (O(tables*boxes*positions) on a large document); on a 3,000-page PDF this was
+// the dominant CPU cost of the parse stage (~95% of a profile sample). The
+// page-bucketed scan is equivalent — boxOverlapsPositionPage already requires a
+// box and a position to share a page, so a box outside the table's pages can
+// never match under either implementation. collectTableBoxes carries the full
+// equivalence argument and is guarded by TestCollectTableBoxesByPageEquivalence.
func buildTableHTMLs(boxes []pdf.TextBox, tables []pdf.TableItem) map[int]string {
+ boxesByPage, boxesNoPage := indexTableLayoutBoxes(boxes)
htmls := make(map[int]string)
for ti := range tables {
if len(tables[ti].Cells) == 0 {
@@ -142,24 +150,109 @@ func buildTableHTMLs(boxes []pdf.TextBox, tables []pdf.TableItem) map[int]string
// Convert TSR cells from crop-pixel space to page-global 72 DPI
s := tables[ti].Scale
pageGlobalCells := CellSliceToPageSpace(tables[ti].Cells, tables[ti].CropOffX, tables[ti].CropOffY, s)
- // Collect only table-labelled boxes
- var tableBoxes []pdf.TextBox
+ tableBoxes := collectTableBoxes(boxes, tables[ti], boxesByPage, boxesNoPage)
+ htmls[ti] = ConstructTable(pageGlobalCells, tableBoxes, tables[ti].Caption, &tables[ti])
+ }
+ return htmls
+}
+
+// indexTableLayoutBoxes buckets the table-layout boxes by page so callers can
+// restrict a per-table scan to just the boxes on the pages the table occupies.
+// Boxes without page metadata (HasPageNumber false) are page-agnostic and
+// returned separately: boxOverlapsPositionPage skips the page check for them, so
+// they must be tested against every table.
+//
+// Key on HasPageNumber, not on PageNumber == 0: page numbers are 0-based, so the
+// legitimate first page carries PageNumber == 0 and must still be scoped to its
+// page. Only truly page-less boxes go to noPage.
+func indexTableLayoutBoxes(boxes []pdf.TextBox) (byPage map[int][]int, noPage []int) {
+ byPage = make(map[int][]int, len(boxes))
+ for i := range boxes {
+ if boxes[i].LayoutType != pdf.LayoutTypeTable {
+ continue
+ }
+ if boxes[i].HasPageNumber {
+ byPage[boxes[i].PageNumber] = append(byPage[boxes[i].PageNumber], i)
+ } else {
+ noPage = append(noPage, i)
+ }
+ }
+ return byPage, noPage
+}
+
+// collectTableBoxes returns the table-layout boxes belonging to tbl, in ascending
+// box-index order — the order buildTableHTMLs has always used and that
+// ConstructTable relies on for deterministic output. It only scans boxes on the
+// pages tbl occupies (plus page-agnostic boxes) instead of the full document.
+//
+// Equivalence to the brute-force O(boxes*positions) scan:
+// - boxOverlapsPositionPage requires a box and a position to agree on page
+// (when both carry page metadata). A table-layout box on a page tbl does not
+// occupy can therefore never match tbl under either implementation, so
+// excluding it is safe.
+// - When tbl has a position with no PageNumbers (page-agnostic), the page check
+// is skipped for that position, so any table-layout box may match. The
+// implementation detects this and falls back to scanning every table-layout
+// box for that table, which is exactly what the brute force does.
+// - Candidates are sorted ascending before the overlap test, reproducing the
+// original whole-document scan order that ConstructTable depends on.
+func collectTableBoxes(boxes []pdf.TextBox, tbl pdf.TableItem, boxesByPage map[int][]int, boxesNoPage []int) []pdf.TextBox {
+ // Collect candidate box indices.
+ var cand []int
+ hasAgnosticPos := false
+ for pi := range tbl.Positions {
+ if len(tbl.Positions[pi].PageNumbers) == 0 {
+ hasAgnosticPos = true
+ break
+ }
+ }
+ if hasAgnosticPos {
+ // Any table-layout box may overlap a page-agnostic position, so the
+ // candidate set is every table-layout box (mirrors the brute force).
+ cand = make([]int, 0, len(boxes))
for i := range boxes {
- if boxes[i].LayoutType != pdf.LayoutTypeTable {
- continue
+ if boxes[i].LayoutType == pdf.LayoutTypeTable {
+ cand = append(cand, i)
}
- for _, tp := range tables[ti].Positions {
- if boxOverlapsPositionPage(boxes[i], tp) {
- tableBoxes = append(tableBoxes, boxes[i])
- break
- }
+ }
+ } else {
+ // Boxes on distinct pages live in disjoint buckets, so once a table's
+ // page numbers are de-duplicated, concatenating the buckets plus the
+ // page-agnostic boxes needs no per-box de-duplication. Positions are few,
+ // so de-duplicating the (typically tiny) page-number list is cheaper than
+ // a per-table map of boxes. A table can list the same page several times
+ // (multiple positions on one page), which is exactly why the dedup is needed.
+ var pgNums []int
+ for pi := range tbl.Positions {
+ pgNums = append(pgNums, tbl.Positions[pi].PageNumbers...)
+ }
+ seenPage := make(map[int]bool, len(pgNums))
+ uniqPages := pgNums[:0]
+ for _, p := range pgNums {
+ if !seenPage[p] {
+ seenPage[p] = true
+ uniqPages = append(uniqPages, p)
}
}
- common.Debug("extractTableAndReplace constructTable",
- zap.Int("table", ti), zap.Int("cells", len(pageGlobalCells)), zap.Int("boxes", len(tableBoxes)))
- htmls[ti] = ConstructTable(pageGlobalCells, tableBoxes, tables[ti].Caption, &tables[ti])
+ cand = make([]int, 0, len(uniqPages)*8+len(boxesNoPage))
+ for _, p := range uniqPages {
+ cand = append(cand, boxesByPage[p]...)
+ }
+ cand = append(cand, boxesNoPage...)
}
- return htmls
+ // cand preserves no particular order; sort ascending so the returned boxes
+ // follow the original whole-document scan order.
+ sort.Ints(cand)
+ var tableBoxes []pdf.TextBox
+ for _, bi := range cand {
+ for pi := range tbl.Positions {
+ if boxOverlapsPositionPage(boxes[bi], tbl.Positions[pi]) {
+ tableBoxes = append(tableBoxes, boxes[bi])
+ break
+ }
+ }
+ }
+ return tableBoxes
}
// insertTableBoxes filters out boxes in removeSet and inserts table HTML boxes at anchor positions.