feat: parser pages range and parse type validation for dataset/document (#17293)

## Summary

Adds page-range parsing support to the Go-native pipeline path and
introduces strict `parse_type` validation for both dataset and document
update endpoints.

## What changed

### Pages range parsing
- **`internal/utility/pdf_pages.go`** — `NormalizePDFPages`: normalizes
raw page ranges (list of `[from,to]` 1-indexed inclusive ranges) into
sorted, merged, deduplicated `[][]int`. Invalid ranges are dropped.
- **`internal/ingestion/pipeline/pdf_pages.go`** —
`NormalizeParserConfigPages`: walks any parser_config map and normalizes
`"pages"` values under every component → filetype setup, so the
persisted config always carries clean, merged ranges.
- **`internal/deepdoc/parser/pdf/parser.go`** — integrates
`resolvePagesToProcess` to filter parsed PDF pages by the configured
ranges.
- Pipeline integration (parser pages):
`internal/parser/parser/pdf_parser_common.go`, `chunk_process.go`, plus
associated e2e and unit tests.

### Parse type validation (shared logic)
- **`internal/service/parser_mode.go`** (new) — `ValidateParseTypeMode`:
shared function that validates `parse_type` (1=BuiltIn/parser_id,
2=Pipeline/pipeline_id) and ensures the corresponding field is present.
Used by both dataset and document update endpoints.
- **`internal/service/dataset/crud.go`** / `update.go` — replaces inline
`isPipelineMode`/`isBuiltinMode` computation with the shared
`service.ValidateParseTypeMode`.
- **`internal/service/document/document_dataset_update.go`** — adds
strict `parse_type` validation in `validateDatasetDocumentUpdate`,
simplifies the reparse logic to a two-way switch (isBuiltin/isPipeline)
now that parse_type is always valid.
- **`internal/service/document/document.go`** — adds `ParseType` field
to `UpdateDatasetDocumentRequest`.
- **`internal/service/document/document_dataset_update.go`** —
`updateDocumentParserConfig` fallback path when DSL loading fails.
- **`internal/service/parser_mode_test.go`** (new) — test coverage for
nil, invalid, and missing-field scenarios.

### Frontend
- **`web/src/interfaces/request/document.ts`** — adds `parseType` to
`IChangeParserRequestBody`.
- **`web/src/hooks/use-document-request.ts`** —
`useSetDocumentPipelineParser` sends `parse_type` in the PATCH payload.
- **`web/src/pages/dataset/dataset/use-change-document-parser.ts`** —
Go/Python branching for the document parser config dialog.
-
**`web/src/components/document-pipeline-dialog/use-document-pipeline-form.ts`**
— `buildSubmitData` returns `parseType` (bugfix: was dropped from the
return value).

### Test changes
- **Removed**: 2 tests that verified the old "mutually exclusive" error
(replaced by `ValidateParseTypeMode` coverage).
- **Modified**: 6 tests across document and dataset packages to include
`ParseType` in request structs.
- **Added**: new e2e tests for pages parsing (`pages_e2e_test.go`,
`pdf_parser_pages_e2e_test.go`) and unit tests for `NormalizePDFPages`,
`NormalizeParserConfigPages`, `resolvePagesToProcess`.

## Backward compatibility
- The `parse_type` field is **required** when `parser_id` or
`pipeline_id` is sent. This changes the contract for both dataset and
document PATCH endpoints, but aligns the Go backend with the existing
frontend behavior (the frontend already sends `parse_type`). Callers
that omit `parse_type` when updating parser/pipeline selections will
receive a clear error message.
- Existing callers that only update fields like `name`, `enabled`, or
`meta_fields` are unaffected.
- Test updates ensure all known call sites are compliant.
This commit is contained in:
Jack
2026-07-23 19:57:27 +08:00
committed by GitHub
parent fce2a94fe0
commit d12fd3b79d
45 changed files with 1819 additions and 496 deletions

View File

@@ -6,6 +6,7 @@ import (
"context"
"image/png"
"os"
"ragflow/internal/common"
inf "ragflow/internal/deepdoc/parser/pdf/inference"
pdftype "ragflow/internal/deepdoc/parser/pdf/type"
util "ragflow/internal/deepdoc/parser/pdf/util"

View File

@@ -0,0 +1,119 @@
package pdf
import (
"context"
"fmt"
"reflect"
"strings"
"testing"
pdf "ragflow/internal/deepdoc/parser/pdf/type"
"ragflow/internal/utility"
)
// TestPagesEndToEnd_NormalizeThenParse verifies the full pages path: a
// frontend-submitted (JSON-decoded, possibly dirty) pages value is normalized
// by utility.NormalizePDFPages, fed into ParserConfig.Pages, and the deepdoc
// parser only processes the resulting page ranges.
//
// This ties together step 3 (API-layer normalization) and step 1 (deepdoc
// page filtering) end-to-end at the parser level.
func TestPagesEndToEnd_NormalizeThenParse(t *testing.T) {
// jsonPages builds a JSON-decoded-style []any of []any of float64, mimicking
// what arrives over the wire from the frontend.
jsonPages := func(ranges ...[2]float64) any {
out := make([]any, 0, len(ranges))
for _, r := range ranges {
out = append(out, []any{r[0], r[1]})
}
return out
}
t.Run("overlapping and unsorted ranges normalized then filtered", func(t *testing.T) {
// Frontend submitted [1,3],[2,5],[8,10] (overlap 1-3 & 2-5, unsorted).
raw := jsonPages([2]float64{1, 3}, [2]float64{2, 5}, [2]float64{8, 10})
normalized, err := utility.NormalizePDFPages(raw) // -> [[1,5],[8,10]]
if err != nil {
t.Fatalf("NormalizePDFPages: %v", err)
}
wantNorm := [][]int{{1, 5}, {8, 10}}
if !reflect.DeepEqual(normalized, wantNorm) {
t.Fatalf("NormalizePDFPages = %v, want %v", normalized, wantNorm)
}
cfg := pdf.DefaultParserConfig()
cfg.Pages = normalized
p := NewParser(cfg)
eng := makePageTaggedEngine(10)
result, err := p.ParseRaw(context.Background(), eng, &MockDocAnalyzer{Healthy: true})
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
// [1,5] -> 0-based 0..4 ; [8,10] -> 7..9
wantPages := map[int]struct{}{0: {}, 1: {}, 2: {}, 3: {}, 4: {}, 7: {}, 8: {}, 9: {}}
if got := pageHeightKeys(result.PageHeight); !reflect.DeepEqual(got, wantPages) {
t.Errorf("PageHeight keys = %v, want %v", got, wantPages)
}
// Sections must not carry text from skipped pages (5, 6).
combined := combineSectionText(result.Sections)
for _, pg := range []int{5, 6} {
if strings.Contains(combined, fmt.Sprintf("p%d", pg)) {
t.Errorf("expected p%d to be skipped; combined=%q", pg, combined)
}
}
})
t.Run("invalid range rejected during normalization (fail-fast)", func(t *testing.T) {
// [1,3],[3,1](from>to),[8,10] -> fail-fast rejects the whole input.
raw := jsonPages([2]float64{1, 3}, [2]float64{3, 1}, [2]float64{8, 10})
normalized, err := utility.NormalizePDFPages(raw)
if err == nil {
t.Fatalf("NormalizePDFPages(%v) expected error, got %v", raw, normalized)
}
if normalized != nil {
t.Fatalf("NormalizePDFPages(%v) = %v, want nil on error", raw, normalized)
}
})
t.Run("all invalid -> error (fail-fast, no parse-all fallback)", func(t *testing.T) {
// [3,1],[0,2] both invalid -> error. The request layer rejects this
// before it ever reaches the parser; normalize surfaces the error
// rather than silently degrading to "parse all pages".
raw := jsonPages([2]float64{3, 1}, [2]float64{0, 2})
normalized, err := utility.NormalizePDFPages(raw)
if err == nil {
t.Fatalf("NormalizePDFPages(%v) expected error, got %v", raw, normalized)
}
if normalized != nil {
t.Fatalf("NormalizePDFPages(%v) = %v, want nil on error", raw, normalized)
}
})
t.Run("range clamped to document page count", func(t *testing.T) {
// [1,1000000] on a 5-page doc -> clamped to all 5 pages.
raw := jsonPages([2]float64{1, 1000000})
normalized, err := utility.NormalizePDFPages(raw)
if err != nil {
t.Fatalf("NormalizePDFPages: %v", err)
}
cfg := pdf.DefaultParserConfig()
cfg.Pages = normalized
p := NewParser(cfg)
eng := makePageTaggedEngine(5)
result, err := p.ParseRaw(context.Background(), eng, &MockDocAnalyzer{Healthy: true})
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
wantPages := map[int]struct{}{0: {}, 1: {}, 2: {}, 3: {}, 4: {}}
if got := pageHeightKeys(result.PageHeight); !reflect.DeepEqual(got, wantPages) {
t.Errorf("PageHeight keys = %v, want all 5 pages", got)
}
})
}

View File

@@ -0,0 +1,132 @@
//go:build cgo && manual
// Package pagespdfiumtest exercises Config.Pages against a real PDF via the
// pdfium CGO engine. It lives in a separate subpackage so that it does not
// share the build of the parent package's manual-tag test files (some of
// which do not currently compile on main).
package pagespdfiumtest
import (
"context"
"image"
"os"
"path/filepath"
"reflect"
"testing"
deepdocpdf "ragflow/internal/deepdoc/parser/pdf"
deepdoctype "ragflow/internal/deepdoc/parser/pdf/type"
)
// noopDocAnalyzer reports unhealthy and returns empty results, forcing the
// parser onto the charsToBoxes path so no DeepDoc model service is required.
type noopDocAnalyzer struct{}
func (noopDocAnalyzer) DLA(context.Context, image.Image) ([]deepdoctype.DLARegion, error) {
return nil, nil
}
func (noopDocAnalyzer) TSR(context.Context, image.Image) ([]deepdoctype.TSRCell, error) {
return nil, nil
}
func (noopDocAnalyzer) OCRDetect(context.Context, image.Image) ([]deepdoctype.OCRBox, error) {
return nil, nil
}
func (noopDocAnalyzer) OCRRecognize(context.Context, image.Image) ([]deepdoctype.OCRText, error) {
return nil, nil
}
func (noopDocAnalyzer) Health() bool { return false }
// pageKeys extracts the set of processed page numbers from PageHeight.
func pageKeys(m map[int]float64) map[int]struct{} {
out := make(map[int]struct{}, len(m))
for k := range m {
out[k] = struct{}{}
}
return out
}
// TestPagesRealPdf_PdfiumFilter verifies Config.Pages end-to-end against a
// real multi-page PDF through the pdfium CGO engine (NewEngine ->
// PageCount/ExtractChars/RenderPage call the pdfium C library). DeepDoc
// DLA/TSR/OCR are stubbed by noopDocAnalyzer.
//
// Run with:
//
// ./build.sh --test -tags manual -v -run TestPagesRealPdf_PdfiumFilter ./internal/deepdoc/parser/pdf/pagespdfiumtest/
func TestPagesRealPdf_PdfiumFilter(t *testing.T) {
t.Setenv("BATCH_SKIP_DEEPDOC", "1")
pdfPath := filepath.Join("..", "testdata", "pdfs", "03_multipage.pdf")
data, err := os.ReadFile(pdfPath)
if err != nil {
t.Fatalf("read %s: %v", pdfPath, err)
}
// NewEngine calls into pdfium (CGO). Failure here means the real C path
// was reached but pdfium could not open the document.
eng, err := deepdocpdf.NewEngine(data)
if err != nil {
t.Fatalf("NewEngine (pdfium CGO): %v", err)
}
defer eng.Close()
total, err := eng.PageCount()
if err != nil {
t.Fatalf("eng.PageCount: %v", err)
}
t.Logf("03_multipage.pdf: pdfium PageCount() = %d (real CGO call)", total)
if total < 2 {
t.Skipf("need >=2 pages to verify filtering, got %d", total)
}
mock := noopDocAnalyzer{}
// Group 1: restrict to page 1 (1-indexed) -> only 0-based page 0.
t.Run("filter to page 1 only", func(t *testing.T) {
cfg := deepdoctype.DefaultParserConfig()
cfg.Pages = [][]int{{1, 1}}
p := deepdocpdf.NewParser(cfg)
result, err := p.ParseRaw(context.Background(), eng, mock)
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
if len(result.PageHeight) != 1 {
t.Errorf("expected 1 page parsed, got %d (keys=%v)",
len(result.PageHeight), pageKeys(result.PageHeight))
}
if _, ok := result.PageHeight[0]; !ok {
t.Errorf("expected page 0 in PageHeight, got keys %v",
pageKeys(result.PageHeight))
}
})
// Group 2: control — no Pages restriction -> all pages.
t.Run("no pages -> all pages (control)", func(t *testing.T) {
p := deepdocpdf.NewParser(deepdoctype.DefaultParserConfig())
result, err := p.ParseRaw(context.Background(), eng, mock)
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
if len(result.PageHeight) != total {
t.Errorf("expected %d pages (all), got %d (keys=%v)",
total, len(result.PageHeight), pageKeys(result.PageHeight))
}
})
// Group 3: multi-range — first and last page only.
if total >= 3 {
t.Run("multi-range first and last page", func(t *testing.T) {
cfg := deepdoctype.DefaultParserConfig()
cfg.Pages = [][]int{{1, 1}, {total, total}}
p := deepdocpdf.NewParser(cfg)
result, err := p.ParseRaw(context.Background(), eng, mock)
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
want := map[int]struct{}{0: {}, total - 1: {}}
if got := pageKeys(result.PageHeight); !reflect.DeepEqual(got, want) {
t.Errorf("PageHeight keys = %v, want %v", got, want)
}
})
}
}

View File

@@ -6,6 +6,7 @@ import (
"image"
"log/slog"
"math"
"sort"
"sync"
lyt "ragflow/internal/deepdoc/parser/pdf/layout"
@@ -108,6 +109,46 @@ func documentPages(pageCount int) []int {
return pages
}
// resolvePagesToProcess converts the 1-indexed inclusive Config.Pages ranges
// into a sorted, de-duplicated slice of 0-indexed page numbers clamped to
// [0, pageCount-1]. Empty/nil ranges fall back to all pages (the historical
// behavior), so callers that leave Pages unset are unaffected.
func resolvePagesToProcess(ranges [][]int, pageCount int) []int {
if len(ranges) == 0 {
return documentPages(pageCount)
}
seen := make(map[int]struct{}, pageCount)
out := make([]int, 0, pageCount)
for _, r := range ranges {
if len(r) != 2 {
continue
}
from0 := r[0] - 1
to0 := r[1] - 1
if from0 < 0 {
from0 = 0
}
if from0 > pageCount-1 {
continue
}
if to0 > pageCount-1 {
to0 = pageCount - 1
}
if to0 < from0 {
continue
}
for pg := from0; pg <= to0; pg++ {
if _, dup := seen[pg]; dup {
continue
}
seen[pg] = struct{}{}
out = append(out, pg)
}
}
sort.Ints(out)
return out
}
// extractOutlines extracts the PDF outlines, returning nil on error.
func (p *Parser) extractOutlines(engine pdf.PDFEngine) []pdf.Outline {
outlines, outlineErr := engine.Outlines()
@@ -497,7 +538,15 @@ func (p *Parser) processPages(ctx context.Context, engine pdf.PDFEngine, docAnal
}
tb := NewTableBuilderFor(docAnalyzer)
pages := documentPages(pageCount)
pages := resolvePagesToProcess(p.Config.Pages, pageCount)
if len(p.Config.Pages) > 0 {
slog.Info("deepdoc pdf parse: page ranges applied",
"configured_ranges", p.Config.Pages,
"page_count", pageCount,
"pages_to_parse", pages)
} else {
slog.Debug("deepdoc pdf parse: parsing all pages", "page_count", pageCount)
}
pageResults, pageErr := p.runPageWorkers(ctx, engine, pages, docAnalyzer, tb)
if pageErr != nil {

View File

@@ -0,0 +1,153 @@
package pdf
import (
"context"
"fmt"
"reflect"
"slices"
"strings"
"testing"
pdf "ragflow/internal/deepdoc/parser/pdf/type"
)
// TestResolvePagesToProcess verifies the 1-indexed inclusive ranges are
// converted to a sorted, de-duplicated, clamped 0-indexed page list.
func TestResolvePagesToProcess(t *testing.T) {
// allPages returns [0..n-1] for assertion convenience.
allPages := func(n int) []int {
out := make([]int, n)
for i := range out {
out[i] = i
}
return out
}
cases := []struct {
name string
ranges [][]int
pageCount int
want []int
}{
{"nil ranges -> all pages", nil, 10, allPages(10)},
{"empty ranges -> all pages", [][]int{}, 10, allPages(10)},
{"single range", [][]int{{1, 3}}, 10, []int{0, 1, 2}},
{"two disjoint ranges", [][]int{{1, 3}, {8, 10}}, 10, []int{0, 1, 2, 7, 8, 9}},
{"unbounded upper clamped to page count", [][]int{{1, 1000000}}, 5, allPages(5)},
{"range entirely beyond doc -> empty", [][]int{{8, 10}}, 5, []int{}},
{"overlapping ranges de-duplicated", [][]int{{1, 3}, {2, 4}}, 10, []int{0, 1, 2, 3}},
{"from > to skipped", [][]int{{3, 1}}, 10, []int{}},
{"wrong arity skipped", [][]int{{1}}, 10, []int{}},
{"unsorted input sorted", [][]int{{8, 10}, {1, 3}}, 10, []int{0, 1, 2, 7, 8, 9}},
{"single page range", [][]int{{5, 5}}, 10, []int{4}},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
got := resolvePagesToProcess(c.ranges, c.pageCount)
if !slices.Equal(got, c.want) {
t.Errorf("resolvePagesToProcess(%v, %d) = %v, want %v", c.ranges, c.pageCount, got, c.want)
}
})
}
}
// makePageTaggedEngine builds a MockEngine with `numPages` pages, each carrying
// a single char whose text is "pN" (N = 0-based page number), so parsed pages
// can be identified in the resulting sections.
func makePageTaggedEngine(numPages int) *MockEngine {
chars := make(map[int][]pdf.TextChar, numPages)
for i := 0; i < numPages; i++ {
chars[i] = []pdf.TextChar{
{Text: fmt.Sprintf("p%d", i), X0: 10, X1: 50, Top: 10, Bottom: 30, PageNumber: i},
}
}
return &MockEngine{NumPages: numPages, Chars: chars, RenderW: 100, RenderH: 100}
}
// pageHeightKeys returns the set of page numbers that were actually processed,
// extracted from result.PageHeight (keyed by 0-based page number).
func pageHeightKeys(m map[int]float64) map[int]struct{} {
out := make(map[int]struct{}, len(m))
for k := range m {
out[k] = struct{}{}
}
return out
}
// TestParseRaw_PageRanges_Applied verifies that Config.Pages restricts parsing
// to the specified pages (1-indexed inclusive) and that pages outside the
// ranges are not processed.
func TestParseRaw_PageRanges_Applied(t *testing.T) {
eng := makePageTaggedEngine(10)
p := NewParser(pdf.ParserConfig{Pages: [][]int{{1, 3}, {8, 10}}})
result, err := p.ParseRaw(context.Background(), eng, &MockDocAnalyzer{Healthy: true})
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
wantPages := map[int]struct{}{0: {}, 1: {}, 2: {}, 7: {}, 8: {}, 9: {}}
if got := pageHeightKeys(result.PageHeight); !reflect.DeepEqual(got, wantPages) {
t.Errorf("PageHeight keys = %v, want %v", got, wantPages)
}
// Sections must reference only parsed pages and must not contain text from
// skipped pages (p3..p6).
combined := combineSectionText(result.Sections)
for _, pg := range []int{0, 1, 2, 7, 8, 9} {
if !strings.Contains(combined, fmt.Sprintf("p%d", pg)) {
t.Errorf("expected section text to contain p%d; combined=%q", pg, combined)
}
}
for _, pg := range []int{3, 4, 5, 6} {
if strings.Contains(combined, fmt.Sprintf("p%d", pg)) {
t.Errorf("expected section text NOT to contain p%d (page skipped); combined=%q", pg, combined)
}
}
}
// TestParseRaw_NoPages_AllPagesParsed is the regression guard: with Pages nil
// (the default), every page is parsed exactly as before this feature.
func TestParseRaw_NoPages_AllPagesParsed(t *testing.T) {
eng := makePageTaggedEngine(10)
p := NewParser(pdf.DefaultParserConfig())
result, err := p.ParseRaw(context.Background(), eng, &MockDocAnalyzer{Healthy: true})
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
wantPages := map[int]struct{}{}
for i := 0; i < 10; i++ {
wantPages[i] = struct{}{}
}
if got := pageHeightKeys(result.PageHeight); !reflect.DeepEqual(got, wantPages) {
t.Errorf("PageHeight keys = %v, want all 10 pages %v", got, wantPages)
}
}
// TestParseRaw_PageRanges_BeyondDoc verifies that a range fully beyond the
// document page count yields an empty parse (no pages processed).
func TestParseRaw_PageRanges_BeyondDoc(t *testing.T) {
eng := makePageTaggedEngine(5)
p := NewParser(pdf.ParserConfig{Pages: [][]int{{8, 10}}})
result, err := p.ParseRaw(context.Background(), eng, &MockDocAnalyzer{Healthy: true})
if err != nil {
t.Fatalf("ParseRaw: %v", err)
}
if len(result.PageHeight) != 0 {
t.Errorf("expected 0 pages parsed for fully out-of-range pages, got %d (%v)",
len(result.PageHeight), pageHeightKeys(result.PageHeight))
}
}
// combineSectionText concatenates all section text for content assertions.
func combineSectionText(sections []pdf.Section) string {
var b strings.Builder
for _, s := range sections {
b.WriteString(s.Text)
}
return b.String()
}

View File

@@ -721,10 +721,3 @@ func TestE2E_ParseAndPostProcess(t *testing.T) {
figs := result.Figures()
t.Logf("figures: %d", len(figs))
}
func truncate(s string, n int) string {
if len(s) <= n {
return s
}
return s[:n] + "..."
}

View File

@@ -10,6 +10,7 @@ import (
"strings"
"testing"
"ragflow/internal/common"
lyt "ragflow/internal/deepdoc/parser/pdf/layout"
"ragflow/internal/deepdoc/parser/pdf/tool"
pdf "ragflow/internal/deepdoc/parser/pdf/type"

View File

@@ -6,6 +6,7 @@ import (
"context"
"os"
"path/filepath"
"ragflow/internal/common"
inf "ragflow/internal/deepdoc/parser/pdf/inference"
tbl "ragflow/internal/deepdoc/parser/pdf/table"
pdf "ragflow/internal/deepdoc/parser/pdf/type"

View File

@@ -6,6 +6,7 @@ import (
"context"
"os"
"path/filepath"
"ragflow/internal/common"
pdf "ragflow/internal/deepdoc/parser/pdf/type"
"strings"
"testing"

View File

@@ -213,6 +213,10 @@ type ParserConfig struct {
SeparateTablesFigs bool
SortByTop bool
SkipOCR bool
// Pages restricts parsing to these 1-indexed inclusive page ranges.
// nil/empty means parse all pages. Ranges beyond the document are clamped
// at parse time; fully out-of-range ranges are skipped.
Pages [][]int
}
// DefaultParserConfig returns a ParserConfig with sensible defaults.