Skip to content

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

fix(document): route image and presentation uploads to their dedicated parsers (#20061)

jay77721a4c0fc8e76a9
diff --git a/internal/service/document/document_parser_selection.go b/internal/service/document/document_parser_selection.go
new file mode 100644
index 0000000000..fd10f48750
--- /dev/null
+++ b/internal/service/document/document_parser_selection.go
@@ -0,0 +1,88 @@
+package document
+
+import (
+ "context"
+ "strings"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+ pipelinepkg "ragflow/internal/ingestion/pipeline"
+ "ragflow/internal/service"
+ "ragflow/internal/utility"
+
+ "go.uber.org/zap"
+)
+
+// defaultDocumentParserID returns the parser that owns a document of the given
+// file type, mirroring Python's FileService.get_parser
+// (api/db/services/file_service.py:734-743): images and video are parsed by the
+// picture pipeline, audio by audio, presentations by presentation and mail by
+// email. Every other file type keeps the dataset's parser.
+func defaultDocumentParserID(filetype utility.FileType, filename, fallback string) string {
+ switch filetype {
+ case utility.FileTypeVISUAL:
+ return "picture"
+ case utility.FileTypeAURAL:
+ return "audio"
+ }
+
+ // The presentation and email extensions all classify as FileTypeDOC, so the
+ // name decides (same name-based rule as Python's get_parser and the
+ // document parser_id guard in document_dataset_update.go).
+ name := strings.ToLower(filename)
+ switch {
+ case strings.HasSuffix(name, ".ppt"),
+ strings.HasSuffix(name, ".pptx"),
+ strings.HasSuffix(name, ".pages"):
+ return "presentation"
+ case strings.HasSuffix(name, ".msg"),
+ strings.HasSuffix(name, ".eml"):
+ return "email"
+ }
+ return fallback
+}
+
+// resolveDocumentParser returns the parser_id and parser_config a newly created
+// document should carry.
+//
+// A file type owned by a dedicated pipeline overrides the dataset's parser and
+// the document is seeded with that pipeline's component params, so the row
+// matches the parser it actually runs with: document parser_config drives both
+// the parser-gap validation and the runtime override params. Without the config
+// swap the document would keep another template's component ids and be reported
+// as unsupported by its own file type.
+//
+// Canvas pipeline mode keeps the dataset parser untouched (parser_id is blanked
+// by the caller). On a DSL failure the dataset parser and config are kept: a
+// registry lookup must not fail an upload, and a half-switched row (new parser,
+// old config) is exactly the inconsistent state this function exists to avoid.
+func resolveDocumentParser(ctx context.Context, kb *entity.Knowledgebase, filename string, filetype utility.FileType, base entity.JSONMap) (string, entity.JSONMap) {
+ if kb.PipelineID != nil {
+ return kb.ParserID, base
+ }
+ parserID := defaultDocumentParserID(filetype, filename, kb.ParserID)
+ if parserID == kb.ParserID || parserID == "" {
+ return kb.ParserID, base
+ }
+
+ dslJSON, err := service.LoadPipelineDSL(ctx, false, parserID, nil)
+ if err != nil {
+ common.Warn("document: file-type parser DSL unavailable, keeping dataset parser",
+ zap.String("parser_id", parserID), zap.String("filename", filename), zap.Error(err))
+ return kb.ParserID, base
+ }
+ raw := map[string]interface{}(base)
+ cleaned := pipelinepkg.BuildParserConfig(dslJSON, raw)
+ // The dataset-level metadata group is parser-independent; keep it so the
+ // target pipeline's Extractor node inherits the dataset setting instead of
+ // falling back to disabled.
+ if meta, ok := raw["metadata"]; ok {
+ cleaned["metadata"] = meta
+ }
+ pipelinepkg.ApplyParentChildChunkerConfig(cleaned, raw)
+ if tenant, tenantErr := dao.NewTenantDAO().GetByID(ctx, dao.DB, kb.TenantID); tenantErr == nil && tenant != nil {
+ cleaned = service.ApplyComponentScopedParserConfig(cleaned, tenant.LLMID)
+ }
+ return parserID, cleaned
+}
diff --git a/internal/service/document/document_parser_selection_test.go b/internal/service/document/document_parser_selection_test.go
new file mode 100644
index 0000000000..041aa0dacc
--- /dev/null
+++ b/internal/service/document/document_parser_selection_test.go
@@ -0,0 +1,163 @@
+package document
+
+import (
+ "mime/multipart"
+ "strings"
+ "testing"
+
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+ "ragflow/internal/storage"
+ "ragflow/internal/utility"
+)
+
+func TestDefaultDocumentParserID(t *testing.T) {
+ cases := []struct {
+ name string
+ filetype utility.FileType
+ filename string
+ fallback string
+ want string
+ }{
+ {"image routes to picture", utility.FileTypeVISUAL, "photo.jpg", "naive", "picture"},
+ {"video routes to picture", utility.FileTypeVISUAL, "clip.mp4", "naive", "picture"},
+ {"audio routes to audio", utility.FileTypeAURAL, "talk.mp3", "naive", "audio"},
+ {"pptx routes to presentation", utility.FileTypeDOC, "deck.pptx", "naive", "presentation"},
+ {"legacy ppt routes to presentation", utility.FileTypeDOC, "deck.ppt", "naive", "presentation"},
+ {"pages routes to presentation", utility.FileTypeDOC, "deck.pages", "naive", "presentation"},
+ {"presentation extension is case-insensitive", utility.FileTypeDOC, "DECK.PPTX", "naive", "presentation"},
+ {"eml routes to email", utility.FileTypeDOC, "mail.eml", "naive", "email"},
+ {"msg routes to email", utility.FileTypeDOC, "mail.msg", "naive", "email"},
+ {"pdf keeps the dataset parser", utility.FileTypePDF, "report.pdf", "naive", "naive"},
+ {"text keeps the dataset parser", utility.FileTypeDOC, "notes.txt", "manual", "manual"},
+ {"no substring false positive", utility.FileTypeDOC, "deck.pptx.md", "naive", "naive"},
+ {"dedicated dataset parser is kept", utility.FileTypeVISUAL, "photo.jpg", "picture", "picture"},
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ got := defaultDocumentParserID(tc.filetype, tc.filename, tc.fallback)
+ if got != tc.want {
+ t.Fatalf("defaultDocumentParserID(%q, %q, %q) = %q, want %q",
+ tc.filetype, tc.filename, tc.fallback, got, tc.want)
+ }
+ })
+ }
+}
+
+// TestUploadLocalDocuments_RoutesFileTypesToDedicatedParsers pins the Python
+// FileService.get_parser parity: an uploaded image or presentation is re-pointed
+// at the pipeline that owns its file type and carries that pipeline's document
+// config (the config the parser-gap validation and the runtime read), while a
+// plain text upload keeps the dataset parser and config untouched.
+func TestUploadLocalDocuments_RoutesFileTypesToDedicatedParsers(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ mockStorage := newFakeUploadStorage()
+ factory := storage.GetStorageFactory()
+ origStorage := factory.GetStorage()
+ factory.SetStorage(mockStorage)
+ t.Cleanup(func() { factory.SetStorage(origStorage) })
+
+ if err := dao.DB.Create(&entity.Tenant{
+ ID: "tenant-1", LLMID: "llm-default", EmbdID: "embd-default", ASRID: "asr-default",
+ }).Error; err != nil {
+ t.Fatalf("insert tenant: %v", err)
+ }
+
+ kbConfig := entity.JSONMap{
+ "GeneralChunker:SixApplesFall": map[string]any{"chunk_token_size": 512},
+ "metadata": map[string]any{
+ "enabled": true,
+ "metadata": []any{},
+ "built_in_metadata": []any{},
+ },
+ }
+ kb := &entity.Knowledgebase{
+ ID: "kb-route",
+ TenantID: "tenant-1",
+ Name: "kb-route",
+ CreatedBy: "user-1",
+ ParserID: "naive",
+ ParserConfig: kbConfig,
+ }
+ if err := dao.DB.Create(kb).Error; err != nil {
+ t.Fatalf("insert kb: %v", err)
+ }
+
+ ctx := t.Context()
+ svc := testDocumentService(t)
+ files := []*multipart.FileHeader{
+ makeTestFileHeader(t, "file", "photo.jpg", []byte("jpeg-bytes")),
+ makeTestFileHeader(t, "file", "deck.pptx", []byte("pptx-bytes")),
+ makeTestFileHeader(t, "file", "notes.txt", []byte("plain text")),
+ }
+ got, errs := svc.UploadLocalDocuments(ctx, kb, "user-1", files, "", nil)
+ if len(errs) != 0 {
+ t.Fatalf("unexpected errs: %v", errs)
+ }
+ if len(got) != len(files) {
+ t.Fatalf("uploaded docs = %d, want %d", len(got), len(files))
+ }
+
+ if parserID, _ := got[0]["parser_id"].(string); parserID != "picture" {
+ t.Fatalf("jpg parser_id = %q, want picture", parserID)
+ }
+ imageSetup := parserFamilySetup(t, got[0], "image")
+ if imageSetup["parse_method"] != "ocr" {
+ t.Fatalf("jpg image setup = %#v, want the picture pipeline defaults", imageSetup)
+ }
+
+ if parserID, _ := got[1]["parser_id"].(string); parserID != "presentation" {
+ t.Fatalf("pptx parser_id = %q, want presentation", parserID)
+ }
+ slidesSetup := parserFamilySetup(t, got[1], "slides")
+ if _, ok := slidesSetup["suffix"]; !ok {
+ t.Fatalf("pptx slides setup = %#v, want the presentation pipeline defaults", slidesSetup)
+ }
+
+ // The rebuilt config goes through the same assembly as a parser switch, so
+ // the tenant LLM id and the dataset metadata group reach the target
+ // pipeline's Extractor node.
+ for _, doc := range got[:2] {
+ cfg := doc["parser_config"].(map[string]interface{})
+ extractor, _ := cfg["Extractor:AutoExtractDefault"].(map[string]interface{})
+ if extractor["llm_id"] != "llm-default" {
+ t.Fatalf("%v parser_config extractor = %#v, want tenant llm id", doc["name"], extractor)
+ }
+ nodeMeta, _ := extractor["metadata"].(map[string]interface{})
+ if nodeMeta["enabled"] != true {
+ t.Fatalf("%v extractor metadata = %#v, want the dataset metadata group", doc["name"], extractor["metadata"])
+ }
+ }
+
+ if parserID, _ := got[2]["parser_id"].(string); parserID != "naive" {
+ t.Fatalf("txt parser_id = %q, want the dataset parser naive", parserID)
+ }
+ txtCfg, _ := got[2]["parser_config"].(map[string]interface{})
+ if _, ok := txtCfg["GeneralChunker:SixApplesFall"]; !ok {
+ t.Fatalf("txt parser_config = %#v, want the dataset config untouched", txtCfg)
+ }
+}
+
+// parserFamilySetup returns the family setup of the document's Parser node, the
+// shape the web parser-gap validation keys on.
+func parserFamilySetup(t *testing.T, doc map[string]interface{}, family string) map[string]interface{} {
+ t.Helper()
+ cfg, ok := doc["parser_config"].(map[string]interface{})
+ if !ok {
+ t.Fatalf("%v parser_config = %T, want map", doc["name"], doc["parser_config"])
+ }
+ for cpnID, raw := range cfg {
+ if !strings.HasPrefix(cpnID, "Parser:") {
+ continue
+ }
+ params, _ := raw.(map[string]interface{})
+ if setup, ok := params[family].(map[string]interface{}); ok {
+ return setup
+ }
+ }
+ t.Fatalf("%v parser_config has no %q setup on a Parser node: %#v", doc["name"], family, cfg)
+ return nil
+}
diff --git a/internal/service/document/document_upload.go b/internal/service/document/document_upload.go
index 4d5a1495a4..829774f93c 100644
--- a/internal/service/document/document_upload.go
+++ b/internal/service/document/document_upload.go
@@ -93,7 +93,8 @@ func (s *DocumentService) UploadLocalDocuments(ctx context.Context, kb *entity.K
continue
}
- doc := s.newDatasetDocument(kb, tenantID, filename, location, string(filetype), merged, "local", int64(len(blob)), blob)
+ parserID, parserConfig := resolveDocumentParser(ctx, kb, filename, filetype, merged)
+ doc := s.newDatasetDocument(kb, tenantID, filename, location, string(filetype), parserID, parserConfig, "local", int64(len(blob)), blob)
if err = s.InsertDocument(doc); err != nil {
// Roll back the orphaned blob so a failed insert doesn't leak storage.
rmErr := removeObjectBestEffort(ctx, storageImpl, kb.ID, location)
@@ -141,7 +142,9 @@ func (s *DocumentService) UploadEmptyDocument(ctx context.Context, kb *entity.Kn
return nil, common.CodeServerError, err
}
- doc := s.newDatasetDocument(kb, tenantID, name, "", "virtual", kb.ParserConfig, "local", 0, nil)
+ // Virtual documents have no file type to route on, so they keep the
+ // dataset parser (mirrors Python's _upload_empty_document).
+ doc := s.newDatasetDocument(kb, tenantID, name, "", "virtual", kb.ParserID, kb.ParserConfig, "local", 0, nil)
if err = s.InsertDocument(doc); err != nil {
return nil, common.CodeServerError, err
}
@@ -283,7 +286,8 @@ func (s *DocumentService) UploadWebDocument(ctx context.Context, kb *entity.Know
return nil, common.CodeServerError, err
}
- doc := s.newDatasetDocument(kb, tenantID, filename, location, string(filetype), kb.ParserConfig, "web", int64(len(blob)), blob)
+ parserID, parserConfig := resolveDocumentParser(ctx, kb, filename, filetype, kb.ParserConfig)
+ doc := s.newDatasetDocument(kb, tenantID, filename, location, string(filetype), parserID, parserConfig, "web", int64(len(blob)), blob)
if err = s.InsertDocument(doc); err != nil {
rmErr := removeObjectBestEffort(ctx, storageImpl, kb.ID, location)
if rmErr != nil {
@@ -318,16 +322,16 @@ func normalizeWebDocumentName(name, contentType string, blob []byte) string {
}
}
-// newDatasetDocument builds a Document row for an upload, deriving parser_id,
-// suffix and content hash. blob may be nil for the empty/virtual document.
-func (s *DocumentService) newDatasetDocument(kb *entity.Knowledgebase, tenantID, filename, location, filetype string, parserConfig entity.JSONMap, src string, size int64, blob []byte) *entity.Document {
+// newDatasetDocument builds a Document row for an upload, deriving suffix and
+// content hash. parserID/parserConfig are resolved by the caller (see
+// resolveDocumentParser); blob may be nil for the empty/virtual document.
+func (s *DocumentService) newDatasetDocument(kb *entity.Knowledgebase, tenantID, filename, location, filetype, parserID string, parserConfig entity.JSONMap, src string, size int64, blob []byte) *entity.Document {
docID := utility.GenerateToken()
status := "1"
suffix := ""
if i := strings.LastIndex(filename, "."); i >= 0 {
suffix = filename[i+1:]
}
- parserID := kb.ParserID
if kb.PipelineID != nil {
parserID = "" // canvas pipeline mode — parser_id not applicable
}
diff --git a/internal/service/document/file2document.go b/internal/service/document/file2document.go
index dc50877153..664e1ae942 100644
--- a/internal/service/document/file2document.go
+++ b/internal/service/document/file2document.go
@@ -224,13 +224,13 @@ func (s *File2DocumentService) convertFiles(ctx context.Context, fileIDs, kbIDs
continue
}
- parserID := kb.ParserID
+ parserID, parserConfig := resolveDocumentParser(ctx, kb, docName, utility.FileType(file.Type), kb.ParserConfig)
suffix := strings.TrimPrefix(filepath.Ext(docName), ".")
doc := &entity.Document{
ID: utility.GenerateUUID(),
KbID: kb.ID,
ParserID: parserID,
- ParserConfig: kb.ParserConfig,
+ ParserConfig: parserConfig,
CreatedBy: userID,
Type: file.Type,
Name: &docName,
diff --git a/internal/service/document/sync_document.go b/internal/service/document/sync_document.go
index 56ab4a5963..678cc4e186 100644
--- a/internal/service/document/sync_document.go
+++ b/internal/service/document/sync_document.go
@@ -114,7 +114,8 @@ func (s *DocumentService) insertSyncDocument(ctx context.Context, input service.
}
// create the 'doc'
- doc := s.newDatasetDocument(kb, tenantID, filename, "", filetype, copyJSONMap(kb.ParserConfig), input.SourceType, int64(len(input.SourceDocument.Blob)), input.SourceDocument.Blob)
+ parserID, parserConfig := resolveDocumentParser(ctx, kb, filename, utility.FileType(filetype), copyJSONMap(kb.ParserConfig))
+ doc := s.newDatasetDocument(kb, tenantID, filename, "", filetype, parserID, parserConfig, input.SourceType, int64(len(input.SourceDocument.Blob)), input.SourceDocument.Blob)
doc.ID = input.DocumentID
// put 'file' in mysql `document`