Skip to content

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

feat(parser): allow tenant PaddleOCR selection for images (#21113)

Xinliang Zheng41c53d655090
diff --git a/docs/guides/agent/ingestion_pipeline/configure_parser_component.md b/docs/guides/agent/ingestion_pipeline/configure_parser_component.md
index 49bd9706d6..dd9260ba0f 100644
--- a/docs/guides/agent/ingestion_pipeline/configure_parser_component.md
+++ b/docs/guides/agent/ingestion_pipeline/configure_parser_component.md
@@ -28,8 +28,32 @@ For PDF files, select one of the following:
For image files:
-- OCR is used by default.
-- You can also configure a vision language model (VLM) for advanced visual understanding.
+- **OCR** is on by default. **OCR model** starts with **DeepDoc** for local
+ OCR. Select an added **PaddleOCR** or **PaddleOCR.local** model to use
+ that tenant model's instance instead; select **DeepDoc** again to return to
+ local OCR.
+- If the model list cannot be loaded, the field displays an error and preserves
+ the saved selection. A successful empty list is shown separately; **DeepDoc**
+ remains available in either case.
+- Turning **OCR** off skips both local and selected-model OCR without clearing
+ the saved selection. **Enable vision enhancement** independently controls VLM
+ descriptions: selecting an OCR model never enables vision enhancement.
+- SVG files have their document text read directly; they are not submitted to
+ PaddleOCR or a VLM.
+- Image attachments and extracted text continue through the picture pipeline's
+ OneChunker and Tokenizer. An unavailable, disabled, inaccessible, or failing
+ selected model is reported in Parser warnings, without falling back to another
+ OCR instance. An image with no OCR text or vision description has no searchable
+ text and is discarded by the Tokenizer.
+
+For Go Parser configuration, the image family stores `ocr_enabled` and optional
+`ocr_model_id` (an enrolled tenant model ID, not a provider name). An omitted or
+empty `ocr_model_id` keeps local OCR. The selected model must be an active OCR
+model on an active PaddleOCR instance belonging to the pipeline's tenant.
+Self-hosted instances need a configured base URL. A cloud instance without one
+uses the public catalog endpoint and logs a warning with tenant, model and
+instance IDs, not credentials. Server-wide endpoint environment variables do not
+replace an explicitly selected instance.
For email files:
diff --git a/internal/entity/models/paddleocr.go b/internal/entity/models/paddleocr.go
index 5f0c66b008..97747421e2 100644
--- a/internal/entity/models/paddleocr.go
+++ b/internal/entity/models/paddleocr.go
@@ -292,7 +292,7 @@ func (p *PaddleOCRModel) OCRFile(ctx context.Context, modelName *string, content
_ = writer.WriteField("model", *modelName)
_ = writer.WriteField("optionalPayload", string(optBytes))
- part, err := writer.CreateFormFile("file", "document.pdf")
+ part, err := writer.CreateFormFile("file", paddleOCRUploadFilename(content))
if err != nil {
return nil, fmt.Errorf("failed to create form file: %w", err)
}
@@ -531,6 +531,31 @@ func (p *PaddleOCRModel) OCRFile(ctx context.Context, modelName *string, content
return &OCRFileResponse{Text: &extractedText}, nil
}
+// paddleOCRUploadFilename preserves the content-derived format expected by the
+// job API without trusting a user-supplied filename. Unknown data stays PDF.
+func paddleOCRUploadFilename(content []byte) string {
+ // net/http's sniffer does not recognize TIFF, which the image parser accepts.
+ if bytes.HasPrefix(content, []byte("II*\x00")) || bytes.HasPrefix(content, []byte("MM\x00*")) {
+ return "document.tiff"
+ }
+ switch http.DetectContentType(content) {
+ case "image/png":
+ return "document.png"
+ case "image/jpeg":
+ return "document.jpg"
+ case "image/gif":
+ return "document.gif"
+ case "image/webp":
+ return "document.webp"
+ case "image/bmp":
+ return "document.bmp"
+ case "image/tiff":
+ return "document.tiff"
+ default:
+ return "document.pdf"
+ }
+}
+
func (p *PaddleOCRModel) ParseFile(ctx context.Context, modelName *string, content []byte, url *string, apiConfig *APIConfig, parseFileConfig *ParseFileConfig, modelUsage *common.ModelUsage) (*ParseFileResponse, error) {
return nil, fmt.Errorf("%s, no such method", p.Name())
}
diff --git a/internal/entity/models/paddleocr_test.go b/internal/entity/models/paddleocr_test.go
index 3219f7c1d0..c81a8d7f99 100644
--- a/internal/entity/models/paddleocr_test.go
+++ b/internal/entity/models/paddleocr_test.go
@@ -10,6 +10,32 @@ import (
"testing"
)
+// TestPaddleOCRUploadFilename checks content-derived image extensions and the
+// unchanged PDF default, including both TIFF byte orders.
+func TestPaddleOCRUploadFilename(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ data []byte
+ want string
+ }{
+ {"pdf", []byte("%PDF-1.7"), "document.pdf"},
+ {"png", []byte("\x89PNG\r\n\x1a\n"), "document.png"},
+ {"jpeg", []byte("\xff\xd8\xff"), "document.jpg"},
+ {"gif", []byte("GIF89a"), "document.gif"},
+ {"webp", []byte("RIFF\x00\x00\x00\x00WEBPVP8 "), "document.webp"},
+ {"bmp", []byte("BM\x00\x00"), "document.bmp"},
+ {"little endian tiff", []byte("II*\x00"), "document.tiff"},
+ {"big endian tiff", []byte("MM\x00*"), "document.tiff"},
+ {"unrecognized", []byte("unknown"), "document.pdf"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := paddleOCRUploadFilename(tc.data); got != tc.want {
+ t.Fatalf("filename=%q, want %q", got, tc.want)
+ }
+ })
+ }
+}
+
// TestPaddleOCRLocalListModels verifies that the local PaddleOCR driver lists
// the default models shipped in conf/models/paddleocr_local.json, so that the
// "add model by selection" flow can pick them up.
diff --git a/internal/ingestion/component/dispatch_model.go b/internal/ingestion/component/dispatch_model.go
index 52fc024be0..721207bc82 100644
--- a/internal/ingestion/component/dispatch_model.go
+++ b/internal/ingestion/component/dispatch_model.go
@@ -38,6 +38,14 @@ type tenantModelExtra struct {
MaxTokens *int `json:"max_tokens"`
}
+type resolvedModelConfig struct {
+ driver modelModule.ModelDriver
+ model *entity.TenantModel
+ instance *entity.TenantModelInstance
+ apiConfig *modelModule.APIConfig
+ contextLength int
+}
+
var resolveTenantModelByType = defaultResolveTenantModelByType
// resolveModelConfig resolves a specific model reference (tenant-model ID or
@@ -55,6 +63,10 @@ func configuredAudioModelID(setup schema.ParserSetup) string {
return getStringOr(setup, "llm_id", "")
}
+// defaultResolveTenantModelByType resolves the tenant's configured default for
+// modelType, requiring a nonempty default model reference first. It then tries
+// the enrolled tenant-model ID and falls back to the configured reference if
+// that ID is absent or cannot be resolved.
func defaultResolveTenantModelByType(ctx context.Context, db *gorm.DB, tenantID string, modelType entity.ModelType) (modelModule.ModelDriver, string, *modelModule.APIConfig, int, error) {
tenantDAO := dao.NewTenantDAO()
tenant, err := tenantDAO.GetByID(ctx, db, tenantID)
@@ -84,9 +96,9 @@ func defaultResolveTenantModelByType(ctx context.Context, db *gorm.DB, tenantID
return nil, "", nil, 0, fmt.Errorf("no default %s model is set", modelType)
}
if tenantModelID := tenantModelIDByType(tenant, modelType); tenantModelID != "" {
- driver, modelName, apiConfig, maxTokens, err := resolveModelConfigByID(ctx, db, tenantID, modelType, tenantModelID)
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, modelType, tenantModelID)
if err == nil {
- return driver, modelName, apiConfig, maxTokens, nil
+ return resolved.driver, resolved.model.ModelName, resolved.apiConfig, resolved.contextLength, nil
}
}
return resolveModelConfig(ctx, db, tenantID, modelType, modelID)
@@ -99,6 +111,10 @@ func defaultResolveTenantModelByType(ctx context.Context, db *gorm.DB, tenantID
// model_type includes the OCR bit, resolved through resolveModelConfigByID.
var resolveTenantOCRModelByProvider = defaultResolveTenantOCRModelByProvider
+// defaultResolveTenantOCRModelByProvider searches the tenant's named provider,
+// trying its aliases only if the provider lookup fails. The first active OCR
+// model is resolved by ID; its resolution error is returned rather than trying
+// another model.
func defaultResolveTenantOCRModelByProvider(ctx context.Context, db *gorm.DB, tenantID string, providerName string) (modelModule.ModelDriver, string, *modelModule.APIConfig, int, error) {
providerDAO := dao.NewTenantModelProviderDAO()
provider, err := providerDAO.GetByTenantIDAndProviderName(ctx, db, tenantID, providerName)
@@ -134,7 +150,11 @@ func defaultResolveTenantOCRModelByProvider(ctx context.Context, db *gorm.DB, te
if model.Status != "active" || !entity.ModelType(model.ModelType).Has(entity.ModelTypeOCR) {
continue
}
- return resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, model.ID)
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, model.ID)
+ if err != nil {
+ return nil, "", nil, 0, err
+ }
+ return resolved.driver, resolved.model.ModelName, resolved.apiConfig, resolved.contextLength, nil
}
}
return nil, "", nil, 0, fmt.Errorf("tenant %s has no active %s OCR model", tenantID, providerName)
@@ -188,41 +208,61 @@ func stringValue(value *string) string {
return *value
}
+// defaultResolveModelConfig treats a reference without "@" as an exact tenant
+// model ID and a reference containing "@" as a provider-instance composite.
+// Failed ID lookups never fall through to composite or catalog resolution.
func defaultResolveModelConfig(ctx context.Context, db *gorm.DB, tenantID string, modelType entity.ModelType, modelRef string) (modelModule.ModelDriver, string, *modelModule.APIConfig, int, error) {
- modelDAO := dao.NewTenantModelDAO()
- if _, err := modelDAO.GetByID(ctx, db, modelRef); err == nil {
- return resolveModelConfigByID(ctx, db, tenantID, modelType, modelRef)
- } else if !errorsIsRecordNotFound(err) {
- return nil, "", nil, 0, err
+ if !strings.Contains(modelRef, "@") {
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, modelType, modelRef)
+ if err != nil {
+ return nil, "", nil, 0, err
+ }
+ return resolved.driver, resolved.model.ModelName, resolved.apiConfig, resolved.contextLength, nil
}
return resolveModelConfigFromProviderInstance(ctx, db, tenantID, modelType, modelRef)
}
-func resolveModelConfigByID(ctx context.Context, db *gorm.DB, tenantID string, modelType entity.ModelType, modelID string) (modelModule.ModelDriver, string, *modelModule.APIConfig, int, error) {
+// resolveModelConfigByID resolves an enrolled model within tenantID before
+// checking status or type or reading instance credentials. Missing and foreign
+// models share one public error; other database failures remain errors.
+// Query sessions preserve caller scopes without mutating the caller's Statement.
+// Instance/provider consistency and instance status are caller responsibilities.
+func resolveModelConfigByID(ctx context.Context, db *gorm.DB, tenantID string, modelType entity.ModelType, modelID string) (*resolvedModelConfig, error) {
modelDAO := dao.NewTenantModelDAO()
instanceDAO := dao.NewTenantModelInstanceDAO()
providerDAO := dao.NewTenantModelProviderDAO()
- modelObj, err := modelDAO.GetByID(ctx, db, modelID)
+ // Scope the lookup itself so missing and foreign models are indistinguishable
+ // before exposing status, type, instance configuration, or driver details.
+ providers := db.Session(&gorm.Session{}).Model(&entity.TenantModelProvider{}).
+ Select("id").Where("tenant_id = ?", tenantID)
+ scopedDB := db.Session(&gorm.Session{}).Where("provider_id IN (?)", providers)
+ modelObj, err := modelDAO.GetByID(ctx, scopedDB, modelID)
if err != nil {
- return nil, "", nil, 0, err
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return nil, errors.New("model not found or inaccessible")
+ }
+ return nil, err
+ }
+ provider, err := providerDAO.GetByID(ctx, db, modelObj.ProviderID)
+ if err != nil {
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return nil, errors.New("model not found or inaccessible")
+ }
+ return nil, err
+ }
+ if provider.TenantID != tenantID {
+ return nil, errors.New("model not found or inaccessible")
}
if modelObj.Status != "active" {
- return nil, "", nil, 0, fmt.Errorf("model %q is disabled", modelID)
+ return nil, fmt.Errorf("model %q is disabled", modelID)
}
if !entity.ModelType(modelObj.ModelType).Has(modelType) {
- return nil, "", nil, 0, fmt.Errorf("model %q cannot be used as %s model", modelID, modelType.String())
+ return nil, fmt.Errorf("model %q cannot be used as %s model", modelID, modelType.String())
}
instance, err := instanceDAO.GetByID(ctx, db, modelObj.InstanceID)
if err != nil {
- return nil, "", nil, 0, err
- }
- provider, err := providerDAO.GetByID(ctx, db, modelObj.ProviderID)
- if err != nil {
- return nil, "", nil, 0, err
- }
- if provider.TenantID != tenantID {
- return nil, "", nil, 0, fmt.Errorf("tenant %s has no access to provider owned by tenant %s", tenantID, provider.TenantID)
+ return nil, err
}
apiKey := instance.APIKey
@@ -234,11 +274,11 @@ func resolveModelConfigByID(ctx context.Context, db *gorm.DB, tenantID string, m
catalogName := modelModule.CatalogProviderName(provider.ProviderName)
providerInfo := dao.GetModelProviderManager().FindProvider(catalogName)
if providerInfo == nil {
- return nil, "", nil, 0, fmt.Errorf("provider %q driver not found", provider.ProviderName)
+ return nil, fmt.Errorf("provider %q driver not found", provider.ProviderName)
}
driver, err := newModelDriverForBaseURLLocal(providerInfo.ModelDriver, provider.ProviderName, region, baseURL)
if err != nil {
- return nil, "", nil, 0, err
+ return nil, err
}
contextLength := 0
if mi, _ := dao.GetModelProviderManager().GetModelByName(catalogName, modelObj.ModelName); mi != nil {
@@ -251,14 +291,17 @@ func resolveModelConfigByID(ctx context.Context, db *gorm.DB, tenantID string, m
if strings.TrimSpace(modelObj.Extra) != "" {
var tenantExtra tenantModelExtra
if err := json.Unmarshal([]byte(modelObj.Extra), &tenantExtra); err != nil {
- return nil, "", nil, 0, err
+ return nil, err
}
if tenantExtra.MaxTokens != nil && *tenantExtra.MaxTokens > 0 {
contextLength = *tenantExtra.MaxTokens
}
}
apiConfig := &modelModule.APIConfig{ApiKey: &apiKey, Region: &region, BaseURL: &baseURL}
- return driver, modelObj.ModelName, apiConfig, contextLength, nil
+ return &resolvedModelConfig{
+ driver: driver, model: modelObj, instance: instance,
+ apiConfig: apiConfig, contextLength: contextLength,
+ }, nil
}
func resolveModelConfigFromProviderInstance(ctx context.Context, db *gorm.DB, tenantID string, modelType entity.ModelType, modelName string) (modelModule.ModelDriver, string, *modelModule.APIConfig, int, error) {
diff --git a/internal/ingestion/component/dispatch_model_test.go b/internal/ingestion/component/dispatch_model_test.go
index e718b4e3ec..b6eb00bf6e 100644
--- a/internal/ingestion/component/dispatch_model_test.go
+++ b/internal/ingestion/component/dispatch_model_test.go
@@ -16,11 +16,16 @@
package component
import (
+ "errors"
+ "reflect"
+ "strings"
"testing"
"github.com/glebarez/sqlite"
"gorm.io/gorm"
+ "gorm.io/gorm/clause"
+ "ragflow/internal/dao"
"ragflow/internal/entity"
"ragflow/internal/ingestion/component/schema"
)
@@ -105,3 +110,237 @@ func TestResolveModelConfigForStoredMistralOCRProvider(t *testing.T) {
})
}
}
+
+// TestResolveModelConfigInaccessibleIDs checks that missing and foreign model
+// IDs have the same public error and trigger no instance reads before access
+// is established, regardless of the foreign model's state.
+func TestResolveModelConfigInaccessibleIDs(t *testing.T) {
+ for _, tc := range []struct {
+ name, table, id, field string
+ value any
+ }{
+ {name: "active foreign model"},
+ {name: "disabled foreign model", table: "tenant_model", id: "model-b", field: "status", value: "inactive"},
+ {name: "wrong foreign model type", table: "tenant_model", id: "model-b", field: "model_type", value: int(entity.ModelTypeChat)},
+ {name: "missing foreign instance", table: "tenant_model", id: "model-b", field: "instance_id", value: "missing-instance"},
+ {name: "disabled foreign instance", table: "tenant_model_instance", id: "instance-b", field: "status", value: "inactive"},
+ {name: "mismatched foreign instance provider", table: "tenant_model_instance", id: "instance-b", field: "provider_id", value: "other-provider"},
+ {name: "missing foreign provider", table: "tenant_model", id: "model-b", field: "provider_id", value: "missing-provider"},
+ {name: "unknown foreign driver", table: "tenant_model_provider", id: "provider", field: "provider_name", value: "missing-driver"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ db, _ := imageOCRFixture(t, "PaddleOCR.local", false)
+ if tc.table != "" {
+ if err := db.Table(tc.table).Where("id = ?", tc.id).Update(tc.field, tc.value).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ counts := imageOCRModelLookupCounts(t, db)
+ _, _, _, _, missingErr := defaultResolveModelConfig(t.Context(), db, "tenant-2", entity.ModelTypeOCR, "missing-model")
+ driver, name, apiConfig, contextLength, err := defaultResolveModelConfig(t.Context(), db, "tenant-2", entity.ModelTypeOCR, "model-b")
+ if missingErr == nil || err == nil {
+ t.Fatalf("missing and foreign IDs must be rejected: missing=%v foreign=%v", missingErr, err)
+ }
+ if err.Error() != missingErr.Error() || !strings.Contains(strings.ToLower(err.Error()), "not found") {
+ t.Errorf("foreign ID is distinguishable: foreign=%q missing=%q", err, missingErr)
+ }
+ if strings.Contains(err.Error(), "tenant-1") {
+ t.Errorf("owner tenant ID leaked: %v", err)
+ }
+ if driver != nil || name != "" || apiConfig != nil || contextLength != 0 {
+ t.Error("inaccessible resolution returned a partial configuration")
+ }
+ if counts["tenant_model_instance"] != 0 {
+ t.Errorf("instance was queried before authorizing its model provider: counts=%v", counts)
+ }
+ })
+ }
+}
+
+// TestResolveModelConfigAuthorizedModelValidation preserves selected instance
+// credentials, max_tokens overrides, and status/type errors for owned models.
+func TestResolveModelConfigAuthorizedModelValidation(t *testing.T) {
+ for _, tc := range []struct {
+ name, field string
+ value any
+ wantError string
+ }{
+ {name: "active OCR"},
+ {name: "disabled model", field: "status", value: "inactive", wantError: "disabled"},
+ {name: "wrong model type", field: "model_type", value: int(entity.ModelTypeChat), wantError: "cannot be used as ocr"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ db, _ := imageOCRFixture(t, "PaddleOCR.local", false)
+ if err := db.Model(&entity.TenantModel{}).Where("id = ?", "model-b").
+ Update("extra", `{"max_tokens":1234}`).Error; err != nil {
+ t.Fatal(err)
+ }
+ if tc.field != "" {
+ if err := db.Model(&entity.TenantModel{}).Where("id = ?", "model-b").Update(tc.field, tc.value).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ driver, name, apiConfig, contextLength, err := defaultResolveModelConfig(t.Context(), db, "tenant-1", entity.ModelTypeOCR, "model-b")
+ if tc.wantError != "" {
+ if err == nil || !strings.Contains(strings.ToLower(err.Error()), tc.wantError) {
+ t.Fatalf("authorized model validation changed: %v", err)
+ }
+ if driver != nil || name != "" || apiConfig != nil || contextLength != 0 {
+ t.Fatal("invalid model returned a partial configuration")
+ }
+ return
+ }
+ if err != nil {
+ t.Fatal(err)
+ }
+ if driver == nil || driver.Name() != "paddleocr.local" ||
+ name != "PaddleOCR-VL-1.5" || contextLength != 1234 {
+ t.Fatalf("authorized model changed: driver=%v name=%q contextLength=%d", driver, name, contextLength)
+ }
+ if apiConfig == nil || apiConfig.ApiKey == nil || *apiConfig.ApiKey != "fixture-key-b" ||
+ apiConfig.BaseURL == nil || *apiConfig.BaseURL == "" {
+ t.Fatal("selected instance configuration was not preserved")
+ }
+ })
+ }
+}
+
+// TestResolveModelConfigLookupFailureIsNotMissing injects a database failure
+// and checks that it remains distinguishable from a missing model, without a
+// composite fallback masking the failure.
+func TestResolveModelConfigLookupFailureIsNotMissing(t *testing.T) {
+ db, _ := imageOCRFixture(t, "PaddleOCR.local", false)
+ lookupErr := errors.New("fixture database unavailable")
+ if err := db.Callback().Query().Before("gorm:query").Register("test:fail_model_lookup", func(tx *gorm.DB) {
+ if tx.Statement.Table == "tenant_model" {
+ tx.AddError(lookupErr)
+ }
+ }); err != nil {
+ t.Fatal(err)
+ }
+ _, _, _, _, err := defaultResolveModelConfig(t.Context(), db, "tenant-1", entity.ModelTypeOCR, "model-b")
+ if !errors.Is(err, lookupErr) {
+ t.Fatalf("database failure was masked as missing/inaccessible or a composite fallback: %v", err)
+ }
+}
+
+// TestResolveModelConfigByIDScopedQuerySQL captures the real dispatcher's DryRun
+// SQL to verify tenant scoping and separate tenant/model bind parameters.
+// Quote-bearing IDs must remain values, not become SQL conditions.
+func TestResolveModelConfigByIDScopedQuerySQL(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatal(err)
+ }
+ sqlDB, err := db.DB()
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = sqlDB.Close() })
+
+ var queries []struct {
+ sql string
+ vars []any
+ }
+ if err := db.Callback().Query().After("gorm:query").Register("test:capture_model_scope_sql", func(tx *gorm.DB) {
+ if tx.DryRun && tx.Statement.Table == "tenant_model" {
+ queries = append(queries, struct {
+ sql string
+ vars []any
+ }{sql: tx.Statement.SQL.String(), vars: append([]any(nil), tx.Statement.Vars...)})
+ }
+ }); err != nil {
+ t.Fatal(err)
+ }
+ const tenantID = "tenant-' OR 1 = 1 --"
+ const modelID = "model-' OR 1 = 1 --"
+ // Exercise the real ID branch, rather than rebuilding its query here.
+ // DryRun does not hydrate records, so only the generated SQL is inspected.
+ defaultResolveModelConfig(t.Context(), db.Session(&gorm.Session{DryRun: true}), tenantID, entity.ModelTypeOCR, modelID)
+
+ if len(queries) != 1 {
+ t.Fatalf("model queries=%d, want one scoped lookup: %+v", len(queries), queries)
+ }
+ query := queries[0]
+ const wantSQL = "SELECT * FROM `tenant_model` WHERE provider_id IN (SELECT `id` FROM `tenant_model_provider` WHERE tenant_id = ?) AND id = ? LIMIT 1"
+ if query.sql != wantSQL {
+ t.Errorf("scoped SQL=%q, want %q", query.sql, wantSQL)
+ }
+ if len(query.vars) != 2 || query.vars[0] != tenantID || query.vars[1] != modelID {
+ t.Errorf("bound vars=%#v, want tenant ID then model ID", query.vars)
+ }
+ if strings.Contains(query.sql, tenantID) || strings.Contains(query.sql, modelID) {
+ t.Errorf("an ID was interpolated into SQL: %q", query.sql)
+ }
+}
+
+// TestResolveModelConfigChainedDBStatementIsolationFixedOnly checks statement
+// isolation, caller-scope retention, and reuse for provider/instance lookups.
+// It is a fixed-implementation regression, not an old-implementation dynamic repro.
+// Do not run against the shared-Statement subquery version: SQL generation may
+// recurse into the same Statement before an assertion can report the failure.
+func TestResolveModelConfigChainedDBStatementIsolationFixedOnly(t *testing.T) {
+ db, _ := imageOCRFixture(t, "PaddleOCR.local", false)
+ baseURL := imageOCRInstanceBaseURL(t, db)
+ // Where returns a clone0 handle whose Statement must remain caller-owned.
+ chainedDB := db.Where("1 = ?", 1)
+ statement := chainedDB.Statement
+ originalModel := statement.Model
+ originalSelects := append([]string(nil), statement.Selects...)
+ originalWhere := clause.Where{Exprs: []clause.Expression{
+ clause.Expr{SQL: "1 = ?", Vars: []any{1}},
+ }}
+ assertCallerUnchanged := func() {
+ t.Helper()
+ if chainedDB.Statement != statement {
+ t.Fatal("resolver replaced the caller Statement")
+ }
+ if !reflect.DeepEqual(statement.Model, originalModel) {
+ t.Fatalf("caller Model changed: got %T, want %T", statement.Model, originalModel)
+ }
+ if !reflect.DeepEqual(statement.Selects, originalSelects) {
+ t.Fatalf("caller Selects changed: got %v, want %v", statement.Selects, originalSelects)
+ }
+ if got := statement.Clauses["WHERE"].Expression; !reflect.DeepEqual(got, originalWhere) {
+ t.Fatalf("caller WHERE changed: got %#v, want %#v", got, originalWhere)
+ }
+ }
+ assertCallerUnchanged()
+
+ driver, name, apiConfig, _, err := defaultResolveModelConfig(t.Context(), chainedDB, "tenant-1", entity.ModelTypeOCR, "model-b")
+ if err != nil {
+ t.Fatalf("resolve selected model with chained DB: %v", err)
+ }
+ if driver == nil || driver.Name() != "paddleocr.local" || name != "PaddleOCR-VL-1.5" {
+ t.Fatalf("selected model changed: driver=%v name=%q", driver, name)
+ }
+ if apiConfig == nil || apiConfig.ApiKey == nil || *apiConfig.ApiKey != "fixture-key-b" ||
+ apiConfig.BaseURL == nil || *apiConfig.BaseURL != baseURL {
+ t.Fatal("selected instance configuration changed")
+ }
+ assertCallerUnchanged()
+
+ provider, err := dao.NewTenantModelProviderDAO().GetByID(t.Context(), chainedDB, "provider")
+ if err != nil {
+ t.Fatalf("reuse chained DB for provider lookup: %v", err)
+ }
+ if provider.ID != "provider" || provider.TenantID != "tenant-1" || provider.ProviderName != "PaddleOCR.local" {
+ t.Fatalf("provider lookup used a polluted Statement: %+v", provider)
+ }
+ assertCallerUnchanged()
+
+ instance, err := dao.NewTenantModelInstanceDAO().GetByID(t.Context(), chainedDB, "instance-b")
+ if err != nil {
+ t.Fatalf("reuse chained DB for instance lookup: %v", err)
+ }
+ if instance.ID != "instance-b" || instance.ProviderID != "provider" || instance.APIKey != "fixture-key-b" {
+ t.Fatal("instance lookup used a polluted Statement")
+ }
+ assertCallerUnchanged()
+
+ // Isolation must preserve caller scopes, not clear them with NewDB.
+ _, _, _, _, err = defaultResolveModelConfig(t.Context(), db.Where("1 = ?", 0), "tenant-1", entity.ModelTypeOCR, "model-b")
+ if err == nil || !strings.Contains(err.Error(), "not found") {
+ t.Fatalf("resolver dropped the caller's rejecting scope: %v", err)
+ }
+}
diff --git a/internal/ingestion/component/extractor.go b/internal/ingestion/component/extractor.go
index 0db36befe9..bb430661af 100644
--- a/internal/ingestion/component/extractor.go
+++ b/internal/ingestion/component/extractor.go
@@ -1538,14 +1538,12 @@ func resolveExtractorChatConfig(ctx context.Context, db *gorm.DB, compositeLLMID
var modelName string
var apiConfig *models.APIConfig
if isBareTenantModelID(compositeLLMID) {
- // UUID path: resolveModelConfigByID does a single GetByID and
- // returns a clear error if the record doesn't exist. No need
- // for a separate pre-check — resolveModelConfig's redundant
- // GetByID dispatch check is also bypassed.
- driver, modelName, apiConfig, _, err = resolveModelConfigByID(ctx, db, tid, entity.ModelTypeChat, compositeLLMID)
+ // Resolve the exact tenant model without a separate existence check.
+ resolved, err := resolveModelConfigByID(ctx, db, tid, entity.ModelTypeChat, compositeLLMID)
if err != nil {
return extractorChatConfig{}, fmt.Errorf("extractor: tenant model %q not found or not usable: %w", compositeLLMID, err)
}
+ driver, modelName, apiConfig = resolved.driver, resolved.model.ModelName, resolved.apiConfig
} else {
// Composite "model@provider" path: delegate to the shared dispatcher.
driver, modelName, apiConfig, _, err = resolveModelConfig(ctx, db, tid, entity.ModelTypeChat, compositeLLMID)
diff --git a/internal/ingestion/component/image_ocr.go b/internal/ingestion/component/image_ocr.go
new file mode 100644
index 0000000000..71f1569313
--- /dev/null
+++ b/internal/ingestion/component/image_ocr.go
@@ -0,0 +1,84 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package component
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "go.uber.org/zap"
+ "gorm.io/gorm"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+ modelModule "ragflow/internal/entity/models"
+)
+
+// extractSelectedImageOCR accepts an enrolled tenant-model ID, not an engine
+// alias or catalog-only composite. An explicit selection never substitutes the
+// tenant default, another instance, local DeepDoc, or a global server URL.
+func extractSelectedImageOCR(ctx context.Context, db *gorm.DB, tenantID, modelID string, binary []byte) (string, error) {
+ if strings.TrimSpace(tenantID) == "" || db == nil {
+ return "", fmt.Errorf("selected image OCR requires a tenant and database")
+ }
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
+ if err != nil {
+ return "", fmt.Errorf("selected image OCR model: %w", err)
+ }
+ model, instance := resolved.model, resolved.instance
+ if instance.ProviderID != model.ProviderID {
+ return "", fmt.Errorf("selected image OCR instance does not belong to the model provider")
+ }
+ if instance.Status != "active" {
+ return "", fmt.Errorf("selected image OCR instance is disabled")
+ }
+ driver, modelName, apiConfig := resolved.driver, model.ModelName, resolved.apiConfig
+ if !isPaddleOCRDriver(driver) {
+ return "", fmt.Errorf("selected image OCR requires a PaddleOCR model")
+ }
+ baseURL := strings.TrimSpace(stringValue(apiConfig.BaseURL))
+ if baseURL == "" {
+ baseURL = modelModule.ProviderJSONConfigValueFromAPIConfig(apiConfig,
+ "paddleocr_base_url", "PADDLEOCR_BASE_URL", "paddleocr_api_url", "PADDLEOCR_API_URL")
+ }
+ if baseURL == "" && driver.Name() == "paddleocr" {
+ if provider := dao.GetModelProviderManager().FindProvider("PaddleOCR"); provider != nil {
+ baseURL = strings.TrimSpace(provider.URL["default"])
+ if baseURL != "" {
+ // An explicitly selected cloud model may still use its catalog
+ // endpoint. Make that choice observable without logging secrets.
+ common.WarnCtx(ctx, "selected image OCR falls back to cloud provider default endpoint",
+ zap.String("tenant_id", tenantID),
+ zap.String("model_id", model.ID),
+ zap.String("instance_id", instance.ID))
+ }
+ }
+ }
+ if baseURL == "" {
+ return "", fmt.Errorf("selected image OCR instance has no base URL")
+ }
+ apiConfig.BaseURL = &baseURL
+ response, err := driver.OCRFile(ctx, &modelName, binary, nil, apiConfig,
+ &modelModule.OCRConfig{Algorithm: modelName}, nil)
+ if err != nil {
+ return "", fmt.Errorf("selected image OCR: %w", err)
+ }
+ if response == nil || response.Text == nil {
+ return "", fmt.Errorf("selected image OCR returned no text")
+ }
+ return strings.TrimSpace(*response.Text), nil
+}
diff --git a/internal/ingestion/component/image_ocr_resolution_test.go b/internal/ingestion/component/image_ocr_resolution_test.go
new file mode 100644
index 0000000000..01df40c415
--- /dev/null
+++ b/internal/ingestion/component/image_ocr_resolution_test.go
@@ -0,0 +1,349 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package component
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "go.uber.org/zap"
+ "go.uber.org/zap/zaptest/observer"
+ "gorm.io/gorm"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+ "ragflow/internal/parser/parser"
+)
+
+// imageOCRModelLookupCounts observes GORM query executions after fixture setup,
+// excluding DryRun subquery construction. The returned counts are read after
+// the synchronous resolver call, not concurrently with queries.
+func imageOCRModelLookupCounts(t *testing.T, db *gorm.DB) map[string]int {
+ t.Helper()
+ counts := make(map[string]int)
+ if err := db.Callback().Query().Before("gorm:query").Register("test:image_ocr_model_lookups", func(tx *gorm.DB) {
+ if tx.DryRun {
+ return
+ }
+ switch tx.Statement.Table {
+ case "tenant_model", "tenant_model_instance", "tenant_model_provider":
+ counts[tx.Statement.Table]++
+ }
+ }); err != nil {
+ t.Fatal(err)
+ }
+ return counts
+}
+
+// imageOCRInstanceBaseURL returns instance B's fixture endpoint, allowing tests
+// to clear Extra and redirect cloud defaults without contacting a public service.
+func imageOCRInstanceBaseURL(t *testing.T, db *gorm.DB) string {
+ t.Helper()
+ var instance entity.TenantModelInstance
+ if err := db.Where("id = ?", "instance-b").Take(&instance).Error; err != nil {
+ t.Fatal(err)
+ }
+ var extra struct {
+ BaseURL string `json:"base_url"`
+ }
+ if err := json.Unmarshal([]byte(instance.Extra), &extra); err != nil || extra.BaseURL == "" {
+ t.Fatalf("fixture base URL missing: %v", err)
+ }
+ return extra.BaseURL
+}
+
+// setImageOCRCloudDefault keeps fallback requests on a local fixture and
+// restores the shared catalog before the fixture is closed.
+// Callers must not run in parallel because the catalog is process-wide.
+func setImageOCRCloudDefault(t *testing.T, baseURL string) {
+ t.Helper()
+ provider := dao.GetModelProviderManager().FindProvider("PaddleOCR")
+ if provider == nil || provider.URL == nil {
+ t.Fatal("PaddleOCR catalog URL missing")
+ }
+ previous, existed := provider.URL["default"]
+ provider.URL["default"] = baseURL
+ t.Cleanup(func() {
+ if existed {
+ provider.URL["default"] = previous
+ } else {
+ delete(provider.URL, "default")
+ }
+ })
+}
+
+// observeImageOCRWarnings captures Warn-and-higher logs after initializing the
+// shared log level needed by error paths. Cleanup restores the previous logger,
+// sugar logger, and any saved level; callers must not run in parallel.
+func observeImageOCRWarnings(t *testing.T) *observer.ObservedLogs {
+ t.Helper()
+ previousLogger, previousSugar := common.Logger, common.Sugar
+ var previousLevel string
+ if previousLogger != nil {
+ previousLevel = common.GetLogLevel()
+ }
+ t.Cleanup(func() {
+ common.Logger, common.Sugar = previousLogger, previousSugar
+ if previousLevel != "" {
+ if err := common.SetLogLevel(previousLevel); err != nil {
+ t.Errorf("restore log level: %v", err)
+ }
+ }
+ })
+ // Error logging also reads the shared AtomicLevel, which a zap observer
+ // alone does not initialize. Empty FileOutput keeps this fixture file-free.
+ if err := common.InitLogger("warn", common.FileOutput{}, ""); err != nil {
+ t.Fatalf("initialize OCR test logger: %v", err)
+ }
+ core, logs := observer.New(zap.WarnLevel)
+ common.Logger = zap.New(core)
+ common.Sugar = common.Logger.Sugar()
+ return logs
+}
+
+// TestImageOCRSelectedModelLookupOnce checks that cloud and local image OCR
+// each issue one top-level GORM query for the selected model, instance and
+// provider. The model query's provider subquery is not counted separately;
+// neither is the cloud driver's HTTP polling.
+func TestImageOCRSelectedModelLookupOnce(t *testing.T) {
+ for _, provider := range []string{"PaddleOCR.local", "PaddleOCR"} {
+ t.Run(provider, func(t *testing.T) {
+ db, _ := imageOCRFixture(t, provider, false)
+ counts := imageOCRModelLookupCounts(t, db)
+ text, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ if err != nil || text != "Selected instance B." {
+ t.Fatalf("selected OCR failed: text=%q err=%v", text, err)
+ }
+ for _, table := range []string{"tenant_model", "tenant_model_instance", "tenant_model_provider"} {
+ if counts[table] != 1 {
+ t.Errorf("%s lookups=%d, want exactly one; counts=%v", table, counts[table], counts)
+ }
+ }
+ })
+ }
+}
+
+// TestImageOCRInaccessibleSelectionProgressDoesNotRevealModelState compares
+// actual Parser progress warnings for missing and foreign selections. Foreign
+// record states must not alter that message, reveal the owner, or send an OCR
+// request; rejection must still preserve the image attachment.
+func TestImageOCRInaccessibleSelectionProgressDoesNotRevealModelState(t *testing.T) {
+ for _, tc := range []struct {
+ name, table, id, field string
+ value any
+ }{
+ {name: "active foreign model"},
+ {name: "disabled foreign model", table: "tenant_model", id: "model-b", field: "status", value: "inactive"},
+ {name: "wrong foreign model type", table: "tenant_model", id: "model-b", field: "model_type", value: int(entity.ModelTypeChat)},
+ {name: "missing foreign instance", table: "tenant_model", id: "model-b", field: "instance_id", value: "missing-instance"},
+ {name: "disabled foreign instance", table: "tenant_model_instance", id: "instance-b", field: "status", value: "inactive"},
+ {name: "mismatched foreign instance provider", table: "tenant_model_instance", id: "instance-b", field: "provider_id", value: "other-provider"},
+ {name: "missing foreign provider", table: "tenant_model", id: "model-b", field: "provider_id", value: "missing-provider"},
+ {name: "unknown foreign driver", table: "tenant_model_provider", id: "provider", field: "provider_name", value: "missing-driver"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR.local", false)
+ if tc.table != "" {
+ if err := db.Table(tc.table).Where("id = ?", tc.id).Update(tc.field, tc.value).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ data := picturePNG(t)
+ warningFor := func(ref string) string {
+ t.Helper()
+ component, err := NewParserComponent(map[string]any{
+ "image": map[string]any{"ocr_enabled": true, "ocr_model_id": ref},
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ var warnings []string
+ ctx := runtime.WithProgressMessageCallback(t.Context(), func(_ string, message string) {
+ if strings.HasPrefix(message, "WARNING: image OCR unavailable:") {
+ warnings = append(warnings, message)
+ }
+ })
+ out, err := component.Invoke(ctx, db, map[string]any{
+ "name": "invoice.png", "binary": data, "tenant_id": "tenant-2",
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ item := out["json"].([]parser.DocItem)[0].ToMap()
+ if item["text"] != "" || item["image"] == "" || item["image"] == nil {
+ t.Fatalf("rejection lost the image or substituted OCR text: %+v", item)
+ }
+ if len(warnings) != 1 {
+ t.Fatalf("expected one actual Parser warning, got %q", warnings)
+ }
+ return warnings[0]
+ }
+ want := warningFor("missing-model")
+ got := warningFor("model-b")
+ if got != want || !strings.Contains(strings.ToLower(got), "not found") {
+ t.Errorf("foreign model is distinguishable: got %q, missing %q", got, want)
+ }
+ if strings.Contains(got, "tenant-1") {
+ t.Errorf("owner tenant ID leaked in progress: %q", got)
+ }
+ if len(requests.list()) != 0 {
+ t.Fatalf("inaccessible selection sent an OCR request: %v", requests.list())
+ }
+ })
+ }
+}
+
+// TestImageOCRCloudDefaultEndpointWarning checks that choosing a catalog
+// endpoint emits one ID-only warning even if submission fails. The catalog
+// points to a local server, while the real driver supplies the selected key,
+// model, and image bytes.
+func TestImageOCRCloudDefaultEndpointWarning(t *testing.T) {
+ for _, fail := range []bool{false, true} {
+ t.Run(fmt.Sprintf("remote_failure=%v", fail), func(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR", fail)
+ baseURL := imageOCRInstanceBaseURL(t, db)
+ setImageOCRCloudDefault(t, baseURL)
+ if err := db.Model(&entity.TenantModelInstance{}).Where("id = ?", "instance-b").
+ Update("extra", "{}").Error; err != nil {
+ t.Fatal(err)
+ }
+ logs := observeImageOCRWarnings(t)
+ data := picturePNG(t)
+ ctx := common.WithSessionID(t.Context(), "image-ocr-fallback")
+ text, err := extractSelectedImageOCR(ctx, db, "tenant-1", "model-b", data)
+ if fail {
+ if err == nil || !strings.Contains(err.Error(), "fixture OCR unavailable") {
+ t.Fatalf("remote error was lost: %v", err)
+ }
+ } else if err != nil || text != "Selected instance B." {
+ t.Fatalf("cloud fallback failed: text=%q err=%v", text, err)
+ }
+ got := requests.list()
+ if len(got) == 0 {
+ t.Fatal("cloud catalog endpoint was not used")
+ }
+ req := got[0]
+ if req.path != "/v2/ocr/jobs" || req.auth != "Bearer fixture-key-b" ||
+ req.model != "PaddleOCR-VL-1.5" || req.filename != "document.png" || !bytes.Equal(req.content, data) {
+ t.Fatalf("fallback changed the selected instance or image upload: %+v", req)
+ }
+ warnings := logs.FilterLevelExact(zap.WarnLevel).All()
+ if len(warnings) != 1 {
+ t.Fatalf("fallback warnings=%d, want exactly one; logs=%v", len(warnings), logs.All())
+ }
+ entry := warnings[0]
+ wantFields := map[string]string{
+ "tenant_id": "tenant-1", "model_id": "model-b", "instance_id": "instance-b",
+ "session_id": "image-ocr-fallback",
+ }
+ fields := entry.ContextMap()
+ if len(fields) != len(wantFields) {
+ t.Errorf("fallback warning must contain only IDs, got %v", fields)
+ }
+ for key, value := range wantFields {
+ if fields[key] != value {
+ t.Errorf("warning %s=%v, want %q", key, fields[key], value)
+ }
+ }
+ if !strings.Contains(strings.ToLower(entry.Message), "default") ||
+ strings.Contains(entry.Message, baseURL) || strings.Contains(entry.Message, "fixture-key-b") {
+ t.Errorf("fallback warning must describe the default without URL or key: %q", entry.Message)
+ }
+ })
+ }
+}
+
+// TestImageOCRExplicitEndpointDoesNotWarn checks Extra-over-APIKey-JSON endpoint
+// precedence for both drivers. Explicit endpoints must neither contact the
+// catalog fallback server nor emit its warning.
+func TestImageOCRExplicitEndpointDoesNotWarn(t *testing.T) {
+ for _, provider := range []string{"PaddleOCR.local", "PaddleOCR"} {
+ for _, source := range []string{"extra", "api_key_json", "extra_over_api_key_json"} {
+ t.Run(provider+"/"+source, func(t *testing.T) {
+ db, requests := imageOCRFixture(t, provider, false)
+ baseURL := imageOCRInstanceBaseURL(t, db)
+ fallback := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ t.Error("explicit endpoint unexpectedly used the cloud catalog default")
+ http.Error(w, "unexpected catalog fallback", http.StatusBadRequest)
+ }))
+ t.Cleanup(fallback.Close)
+ setImageOCRCloudDefault(t, fallback.URL)
+ if source == "api_key_json" {
+ key := fmt.Sprintf(`{"api_key":{"PADDLEOCR_BASE_URL":%q,"PADDLEOCR_ACCESS_TOKEN":"fixture-key-b"}}`, baseURL)
+ if err := db.Model(&entity.TenantModelInstance{}).Where("id = ?", "instance-b").
+ Updates(map[string]any{"api_key": key, "extra": "{}"}).Error; err != nil {
+ t.Fatal(err)
+ }
+ } else if source == "extra_over_api_key_json" {
+ key := fmt.Sprintf(`{"api_key":{"PADDLEOCR_BASE_URL":%q,"PADDLEOCR_ACCESS_TOKEN":"fixture-key-b"}}`, fallback.URL)
+ if err := db.Model(&entity.TenantModelInstance{}).Where("id = ?", "instance-b").
+ Update("api_key", key).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ logs := observeImageOCRWarnings(t)
+ text, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ if err != nil || text != "Selected instance B." {
+ t.Fatalf("explicit endpoint failed: text=%q err=%v", text, err)
+ }
+ got := requests.list()
+ if len(got) == 0 || got[0].auth != "Bearer fixture-key-b" {
+ t.Fatalf("selected explicit endpoint or key was not used: %v", got)
+ }
+ if warnings := logs.FilterLevelExact(zap.WarnLevel).All(); len(warnings) != 0 {
+ t.Fatalf("explicit endpoint emitted fallback warnings: %v", warnings)
+ }
+ })
+ }
+ }
+}
+
+// TestImageOCRMissingEndpointDoesNotUseGlobalEndpoint rejects incomplete
+// selected instances for both drivers when the cloud catalog URL is also empty.
+// Process-global endpoints must not fill the gap or produce a fallback warning.
+func TestImageOCRMissingEndpointDoesNotUseGlobalEndpoint(t *testing.T) {
+ for _, provider := range []string{"PaddleOCR.local", "PaddleOCR"} {
+ t.Run(provider, func(t *testing.T) {
+ db, requests := imageOCRFixture(t, provider, false)
+ setImageOCRCloudDefault(t, "")
+ if err := db.Model(&entity.TenantModelInstance{}).Where("id = ?", "instance-b").
+ Update("extra", "{}").Error; err != nil {
+ t.Fatal(err)
+ }
+ global := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ t.Error("missing selected endpoint borrowed the process-global OCR server")
+ http.Error(w, "unexpected global endpoint", http.StatusBadRequest)
+ }))
+ t.Cleanup(global.Close)
+ t.Setenv("PADDLEOCR_BASE_URL", global.URL)
+ t.Setenv("PADDLEOCR_API_URL", global.URL)
+ logs := observeImageOCRWarnings(t)
+ _, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ if err == nil || !strings.Contains(err.Error(), "no base URL") || len(requests.list()) != 0 {
+ t.Fatalf("missing selected endpoint must fail without a request: err=%v requests=%v", err, requests.list())
+ }
+ if warnings := logs.FilterLevelExact(zap.WarnLevel).All(); len(warnings) != 0 {
+ t.Fatalf("no endpoint was chosen, but a fallback warning was emitted: %v", warnings)
+ }
+ })
+ }
+}
diff --git a/internal/ingestion/component/image_ocr_test.go b/internal/ingestion/component/image_ocr_test.go
new file mode 100644
index 0000000000..bfee431cb3
--- /dev/null
+++ b/internal/ingestion/component/image_ocr_test.go
@@ -0,0 +1,499 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package component
+
+import (
+ "bytes"
+ "context"
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/glebarez/sqlite"
+ "gorm.io/gorm"
+ "gorm.io/gorm/logger"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+ deepdocpdf "ragflow/internal/deepdoc/parser/pdf"
+ "ragflow/internal/entity"
+ modelModule "ragflow/internal/entity/models"
+ "ragflow/internal/parser/parser"
+ "ragflow/internal/utility"
+)
+
+type imageOCRRequest struct {
+ path, auth, model, filename string
+ fileType int
+ content []byte
+}
+
+type imageOCRRequests struct {
+ mu sync.Mutex
+ items []imageOCRRequest
+}
+
+// append records a fixture request without racing the HTTP handler.
+func (r *imageOCRRequests) append(request imageOCRRequest) {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ r.items = append(r.items, request)
+}
+
+// list copies the recorded request slice under lock. Content byte slices remain
+// shared with the stored requests and must be treated as read-only.
+func (r *imageOCRRequests) list() []imageOCRRequest {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return append([]imageOCRRequest(nil), r.items...)
+}
+
+// imageOCRFixture replaces only the OCR HTTP service. Tenant model resolution,
+// instance configuration, image dispatch and driver calls use production code.
+// It seeds instance B alongside decoy instance A, whose requests fail the test.
+// Its process-wide SSRF bypass is restored at cleanup, so callers must not run
+// in parallel and SSRF-specific tests must explicitly re-enable the guard.
+func imageOCRFixture(t *testing.T, provider string, fail bool) (*gorm.DB, *imageOCRRequests) {
+ t.Helper()
+ withSSRFBypass(t)
+ requests := &imageOCRRequests{}
+ var server *httptest.Server
+ server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ req := imageOCRRequest{path: r.URL.Path, auth: r.Header.Get("Authorization")}
+ w.Header().Set("Content-Type", "application/json")
+ switch r.URL.Path {
+ case "/layout-parsing":
+ var body struct {
+ File string `json:"file"`
+ FileType int `json:"fileType"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+ t.Error(err)
+ }
+ req.fileType = body.FileType
+ req.content, _ = base64.StdEncoding.DecodeString(body.File)
+ requests.append(req)
+ if fail {
+ http.Error(w, "fixture OCR unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ _, _ = io.WriteString(w, `{"errorCode":0,"result":{"layoutParsingResults":[{"markdown":{"text":"Selected instance B."}}]}}`)
+ case "/v2/ocr/jobs":
+ if err := r.ParseMultipartForm(1 << 20); err != nil {
+ t.Error(err)
+ http.Error(w, "invalid fixture upload", http.StatusBadRequest)
+ return
+ }
+ defer r.MultipartForm.RemoveAll()
+ file, header, err := r.FormFile("file")
+ if err != nil {
+ t.Error(err)
+ return
+ }
+ defer file.Close()
+ req.content, _ = io.ReadAll(file)
+ req.filename = header.Filename
+ req.model = r.FormValue("model")
+ requests.append(req)
+ if fail {
+ http.Error(w, "fixture OCR unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ _, _ = io.WriteString(w, `{"data":{"jobId":"image-job"}}`)
+ case "/v2/ocr/jobs/image-job":
+ requests.append(req)
+ _, _ = fmt.Fprintf(w, `{"data":{"state":"done","resultUrl":{"jsonUrl":%q}}}`, server.URL+"/image-result")
+ case "/image-result":
+ requests.append(req)
+ _, _ = io.WriteString(w, `[{"result":{"layoutParsingResults":[{"markdown":{"text":"Selected instance B."}}]}}]`)
+ default:
+ t.Errorf("unexpected OCR path: %s", r.URL.Path)
+ http.NotFound(w, r)
+ }
+ }))
+ t.Cleanup(server.Close)
+ decoy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ t.Errorf("unselected instance was called: %s", r.URL.Path)
+ http.Error(w, "wrong instance", http.StatusBadRequest)
+ }))
+ t.Cleanup(decoy.Close)
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+ if err != nil {
+ t.Fatal(err)
+ }
+ sqlDB, err := db.DB()
+ if err != nil {
+ t.Fatal(err)
+ }
+ sqlDB.SetMaxOpenConns(1)
+ t.Cleanup(func() { _ = sqlDB.Close() })
+ if err := db.AutoMigrate(&entity.TenantModelProvider{}, &entity.TenantModelInstance{}, &entity.TenantModel{}); err != nil {
+ t.Fatal(err)
+ }
+ rows := []any{&entity.TenantModelProvider{ID: "provider", TenantID: "tenant-1", ProviderName: provider}}
+ for _, instance := range []struct{ id, url string }{{"a", decoy.URL}, {"b", server.URL}} {
+ rows = append(rows,
+ &entity.TenantModelInstance{ID: "instance-" + instance.id, ProviderID: "provider", InstanceName: instance.id,
+ APIKey: "fixture-key-" + instance.id, Status: "active", Extra: fmt.Sprintf(`{"base_url":%q}`, instance.url)},
+ &entity.TenantModel{ID: "model-" + instance.id, ProviderID: "provider", InstanceID: "instance-" + instance.id,
+ ModelName: "PaddleOCR-VL-1.5", ModelType: int(entity.ModelTypeOCR), Status: "active"})
+ }
+ for _, row := range rows {
+ if err := db.Create(row).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ return db, requests
+}
+
+// TestImageOCRSelectedTenantModel checks the selected instance, credentials,
+// image bytes and upload protocol for both PaddleOCR providers.
+func TestImageOCRSelectedTenantModel(t *testing.T) {
+ for _, provider := range []string{"PaddleOCR.local", "PaddleOCR"} {
+ t.Run(provider, func(t *testing.T) {
+ db, requests := imageOCRFixture(t, provider, false)
+ data := picturePNG(t)
+ setups := imageSwitchSetups(t, true)
+ setups["image"]["ocr_model_id"] = "model-b"
+ res, handled, err := maybeDispatchImage(t.Context(), db, utility.FileTypeVISUAL,
+ "invoice.png", data, map[string]any{"tenant_id": "tenant-1"}, setups, false, visionSettings{})
+ if err != nil || !handled {
+ t.Fatalf("handled=%v error=%v", handled, err)
+ }
+ if got := res.JSON[0].ToMap()["text"]; strings.TrimSpace(fmt.Sprint(got)) != "Selected instance B." {
+ t.Fatalf("text=%q warnings=%v", got, res.Warnings)
+ }
+ if len(res.Warnings) != 0 {
+ t.Fatalf("warnings=%v", res.Warnings)
+ }
+ image, _ := res.JSON[0].ToMap()["image"].(string)
+ if !strings.HasSuffix(image, base64.StdEncoding.EncodeToString(data)) {
+ t.Fatal("image attachment was lost or changed")
+ }
+ if len(requests.list()) == 0 {
+ t.Fatal("selected OCR driver was never called")
+ }
+ req := requests.list()[0]
+ if req.auth != "Bearer fixture-key-b" || !bytes.Equal(req.content, data) {
+ t.Fatalf("selected instance credentials or image bytes were not used: %+v", req)
+ }
+ if provider == "PaddleOCR.local" && req.fileType != 1 {
+ t.Fatalf("local fileType=%d, want image type 1", req.fileType)
+ }
+ if provider == "PaddleOCR" && (req.filename != "document.png" || req.model != "PaddleOCR-VL-1.5") {
+ t.Fatalf("cloud image upload=%+v", req)
+ }
+ })
+ }
+}
+
+// TestImageOCRReleasesMediaAdmissionBeforeRequest verifies that selected OCR
+// never holds image materialization slots during remote I/O, including failures.
+func TestImageOCRReleasesMediaAdmissionBeforeRequest(t *testing.T) {
+ for _, fail := range []bool{false, true} {
+ t.Run(fmt.Sprint(fail), func(t *testing.T) {
+ db, _ := imageOCRFixture(t, "PaddleOCR.local", false)
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ ctx, cancel := context.WithTimeout(r.Context(), time.Second)
+ defer cancel()
+ for range deepdocpdf.DeepDocConcurrency() {
+ release, err := parser.AcquireImageMedia(ctx)
+ if err != nil {
+ t.Errorf("selected OCR retained an image-media slot during I/O: %v", err)
+ http.Error(w, "image-media admission blocked", http.StatusServiceUnavailable)
+ return
+ }
+ defer release()
+ }
+ if fail {
+ http.Error(w, "fixture OCR unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = io.WriteString(w, `{"errorCode":0,"result":{"layoutParsingResults":[{"markdown":{"text":"Remote OCR text."}}]}}`)
+ }))
+ t.Cleanup(server.Close)
+ if err := db.Model(&entity.TenantModelInstance{}).Where("id = ?", "instance-b").
+ Update("extra", fmt.Sprintf(`{"base_url":%q}`, server.URL)).Error; err != nil {
+ t.Fatal(err)
+ }
+ setups := imageSwitchSetups(t, true)
+ setups["image"]["ocr_model_id"] = "model-b"
+ result, _, err := maybeDispatchImage(t.Context(), db, utility.FileTypeVISUAL,
+ "invoice.png", picturePNG(t), map[string]any{"tenant_id": "tenant-1"}, setups, false, visionSettings{})
+ if err != nil || len(result.JSON) != 1 {
+ t.Fatalf("err=%v result=%+v", err, result)
+ }
+ item := result.JSON[0].ToMap()
+ if fail {
+ if item["text"] != "" || !strings.Contains(strings.Join(result.Warnings, "\n"), "fixture OCR unavailable") {
+ t.Fatalf("failure result=%+v warnings=%v", item, result.Warnings)
+ }
+ } else if item["text"] != "Remote OCR text." || len(result.Warnings) != 0 {
+ t.Fatalf("success result=%+v warnings=%v", item, result.Warnings)
+ }
+ if item["image"] == "" || item["image"] == nil {
+ t.Fatal("remote OCR lost the image attachment")
+ }
+ ctx, cancel := context.WithTimeout(t.Context(), time.Second)
+ defer cancel()
+ for range deepdocpdf.DeepDocConcurrency() {
+ release, err := parser.AcquireImageMedia(ctx)
+ if err != nil {
+ t.Fatalf("image-media admission leaked after dispatch: %v", err)
+ }
+ defer release()
+ }
+ })
+ }
+}
+
+// TestImageOCRFailureRetainsAttachment verifies that failures remain visible
+// without dropping the image or substituting local OCR.
+func TestImageOCRFailureRetainsAttachment(t *testing.T) {
+ for _, provider := range []string{"PaddleOCR.local", "PaddleOCR"} {
+ t.Run(provider, func(t *testing.T) {
+ db, requests := imageOCRFixture(t, provider, true)
+ setups := imageSwitchSetups(t, true)
+ setups["image"]["ocr_model_id"] = "model-b"
+ res, _, err := maybeDispatchImage(t.Context(), db, utility.FileTypeVISUAL,
+ "invoice.png", picturePNG(t), map[string]any{"tenant_id": "tenant-1"}, setups, false, visionSettings{})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(requests.list()) != 1 || !strings.Contains(strings.Join(res.Warnings, "\n"), "fixture OCR unavailable") {
+ t.Fatalf("OCR failure was not reported: requests=%v warnings=%v", requests.list(), res.Warnings)
+ }
+ item := res.JSON[0].ToMap()
+ if item["text"] != "" || item["image"] == "" || item["image"] == nil {
+ t.Fatalf("failure must retain the attachment, not substitute local OCR: %+v", item)
+ }
+ })
+ }
+}
+
+// TestImageOCRInvalidSelectionNeverFallsBack rejects inaccessible or invalid
+// model/instance records before making an OCR request.
+func TestImageOCRInvalidSelectionNeverFallsBack(t *testing.T) {
+ cases := []struct {
+ name, tenant, ref, table, field string
+ value any
+ want string
+ }{
+ {name: "missing tenant", ref: "model-b", want: "tenant"},
+ {name: "foreign tenant", tenant: "tenant-2", ref: "model-b", want: "not found"},
+ {name: "missing model", tenant: "tenant-1", ref: "missing", want: "not found"},
+ {name: "disabled model", tenant: "tenant-1", ref: "model-b", table: "tenant_model", field: "status", value: "inactive", want: "disabled"},
+ {name: "wrong type", tenant: "tenant-1", ref: "model-b", table: "tenant_model", field: "model_type", value: int(entity.ModelTypeChat), want: "ocr"},
+ {name: "disabled instance", tenant: "tenant-1", ref: "model-b", table: "tenant_model_instance", field: "status", value: "inactive", want: "disabled"},
+ {name: "mismatched instance provider", tenant: "tenant-1", ref: "model-b", table: "tenant_model_instance", field: "provider_id", value: "other", want: "provider"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR.local", false)
+ if tc.table != "" {
+ id := "model-b"
+ if tc.table == "tenant_model_instance" {
+ id = "instance-b"
+ }
+ if err := db.Table(tc.table).Where("id = ?", id).Update(tc.field, tc.value).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ setups := imageSwitchSetups(t, true)
+ setups["image"]["ocr_model_id"] = tc.ref
+ res, _, err := maybeDispatchImage(t.Context(), db, utility.FileTypeVISUAL,
+ "invoice.png", picturePNG(t), map[string]any{"tenant_id": tc.tenant}, setups, false, visionSettings{})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(requests.list()) != 0 || !strings.Contains(strings.ToLower(strings.Join(res.Warnings, "\n")), tc.want) {
+ t.Fatalf("selection was not rejected: requests=%v warnings=%v", requests.list(), res.Warnings)
+ }
+ if res.JSON[0].ToMap()["text"] != "" {
+ t.Fatal("invalid selection silently fell back to another OCR source")
+ }
+ })
+ }
+}
+
+// TestImageOCRSelectionRespectsSwitchAndSVG keeps disabled OCR and native SVG
+// text extraction independent of a saved model selection.
+func TestImageOCRSelectionRespectsSwitchAndSVG(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR.local", false)
+ for _, tc := range []struct {
+ name, filename, text string
+ ocr bool
+ data []byte
+ }{
+ {"off", "invoice.png", "", false, picturePNG(t)},
+ {"svg", "invoice.svg", "SVG invoice", true, []byte(`<svg xmlns="http://www.w3.org/2000/svg"><text>SVG invoice</text></svg>`)},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ setups := imageSwitchSetups(t, tc.ocr)
+ setups["image"]["ocr_model_id"] = "model-b"
+ res, _, err := maybeDispatchImage(t.Context(), db, utility.FileTypeVISUAL,
+ tc.filename, tc.data, map[string]any{"tenant_id": "tenant-1"}, setups, false, visionSettings{})
+ if err != nil || len(res.JSON) != 1 {
+ t.Fatalf("err=%v result=%+v", err, res)
+ }
+ if res.JSON[0].ToMap()["text"] != tc.text || len(requests.list()) != 0 {
+ t.Fatalf("switch or SVG bypass broken: %+v requests=%v", res, requests.list())
+ }
+ })
+ }
+}
+
+// TestImageOCRModelConfigValidation rejects non-string model IDs at setup time.
+func TestImageOCRModelConfigValidation(t *testing.T) {
+ _, err := NewParserComponent(map[string]any{"image": map[string]any{"ocr_enabled": true, "ocr_model_id": 123}})
+ if err == nil || !strings.Contains(err.Error(), "ocr_model_id") {
+ t.Fatalf("non-string model id must be rejected, got %v", err)
+ }
+}
+
+// TestImageOCRDoesNotUseGlobalEndpoint prevents an incomplete selected instance
+// from silently borrowing a process-global server address.
+func TestImageOCRDoesNotUseGlobalEndpoint(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR.local", false)
+ t.Setenv("PADDLEOCR_BASE_URL", "http://global.invalid")
+ t.Setenv("PADDLEOCR_API_URL", "http://global.invalid")
+ if err := db.Model(&entity.TenantModelInstance{}).Where("id = ?", "instance-b").Update("extra", "{}").Error; err != nil {
+ t.Fatal(err)
+ }
+ _, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ if err == nil || !strings.Contains(err.Error(), "no base URL") || len(requests.list()) != 0 {
+ t.Fatalf("selected local model must not borrow a global endpoint: %v", err)
+ }
+}
+
+// TestImageOCRKeepsCloudSSRFGuard preserves public-address validation for cloud
+// OCR requests even when the model was explicitly selected.
+func TestImageOCRKeepsCloudSSRFGuard(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR", false)
+ common.AllowAnyHostForTest = false
+ _, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ if err == nil || !strings.Contains(err.Error(), "non-public address") || len(requests.list()) != 0 {
+ t.Fatalf("cloud transport policy changed: err=%v requests=%v", err, requests.list())
+ }
+}
+
+// TestImageOCRRejectsOtherOCRDrivers restricts this selector to PaddleOCR.
+func TestImageOCRRejectsOtherOCRDrivers(t *testing.T) {
+ db, requests := imageOCRFixture(t, "MinerU", false)
+ _, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ if err == nil || !strings.Contains(err.Error(), "requires a PaddleOCR") || len(requests.list()) != 0 {
+ t.Fatalf("unsupported driver accepted: err=%v requests=%v", err, requests.list())
+ }
+}
+
+// TestImageOCRReadsInstanceJSONAndRotatedCredentials verifies that each request
+// reads the selected instance's current structured credentials.
+func TestImageOCRReadsInstanceJSONAndRotatedCredentials(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR.local", false)
+ var instance entity.TenantModelInstance
+ if err := db.Where("id = ?", "instance-b").Take(&instance).Error; err != nil {
+ t.Fatal(err)
+ }
+ var extra map[string]string
+ if err := json.Unmarshal([]byte(instance.Extra), &extra); err != nil {
+ t.Fatal(err)
+ }
+ for _, token := range []string{"first-key", "rotated-key"} {
+ key := fmt.Sprintf(`{"api_key":{"PADDLEOCR_BASE_URL":%q,"PADDLEOCR_ACCESS_TOKEN":%q}}`, extra["base_url"], token)
+ if err := db.Model(&instance).Updates(map[string]any{"api_key": key, "extra": "{}"}).Error; err != nil {
+ t.Fatal(err)
+ }
+ text, err := extractSelectedImageOCR(t.Context(), db, "tenant-1", "model-b", picturePNG(t))
+ got := requests.list()
+ if err != nil || text != "Selected instance B." || got[len(got)-1].auth != "Bearer "+token {
+ t.Fatalf("instance JSON or rotation lost: text=%q err=%v requests=%v", text, err, got)
+ }
+ }
+}
+
+// TestImageOCRAndVisionRemainIndependent checks combined Parser output with
+// selected OCR enabled and disabled while global vision stays enabled.
+func TestImageOCRAndVisionRemainIndependent(t *testing.T) {
+ original := resolveTenantModelByType
+ t.Cleanup(func() { resolveTenantModelByType = original })
+ resolveTenantModelByType = func(_ context.Context, _ *gorm.DB, _ string, kind entity.ModelType) (modelModule.ModelDriver, string, *modelModule.APIConfig, int, error) {
+ if kind != entity.ModelTypeImage2Text {
+ t.Fatalf("unexpected default model lookup: %v", kind)
+ }
+ return &imagePromptCaptureDriver{}, "vision", &modelModule.APIConfig{}, 0, nil
+ }
+ for _, enabled := range []bool{true, false} {
+ t.Run(fmt.Sprint(enabled), func(t *testing.T) {
+ db, requests := imageOCRFixture(t, "PaddleOCR.local", false)
+ params := map[string]any{"enable_vision_enhancement": true,
+ "image": map[string]any{"ocr_enabled": enabled, "ocr_model_id": "model-b"}}
+ c, err := NewParserComponent(params)
+ if err != nil {
+ t.Fatal(err)
+ }
+ out, err := c.Invoke(t.Context(), db, map[string]any{
+ "name": "invoice.png", "binary": picturePNG(t), "tenant_id": "tenant-1"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ text := out["json"].([]parser.DocItem)[0].ToMap()["text"]
+ want := "captured"
+ calls := 0
+ if enabled {
+ want = "Selected instance B.\ncaptured"
+ calls = 1
+ }
+ if text != want || len(requests.list()) != calls {
+ t.Fatalf("OCR/vision coupling changed: text=%v requests=%v", text, requests.list())
+ }
+ })
+ }
+}
+
+// TestImageOCRFailureReachesProgressMessages checks the actual Parser progress
+// callback, not just the dispatch helper's returned warnings.
+func TestImageOCRFailureReachesProgressMessages(t *testing.T) {
+ db, _ := imageOCRFixture(t, "PaddleOCR.local", true)
+ c, err := NewParserComponent(map[string]any{
+ "image": map[string]any{"ocr_enabled": true, "ocr_model_id": "model-b"},
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ var messages []string
+ ctx := runtime.WithProgressMessageCallback(t.Context(), func(_ string, message string) {
+ messages = append(messages, message)
+ })
+ out, err := c.Invoke(ctx, db, map[string]any{
+ "name": "invoice.png", "binary": picturePNG(t), "tenant_id": "tenant-1"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(strings.Join(messages, "\n"), "WARNING: image OCR unavailable") ||
+ !strings.Contains(strings.Join(messages, "\n"), "fixture OCR unavailable") {
+ t.Fatalf("failure absent from actual Parser progress: %q", messages)
+ }
+ if item := out["json"].([]parser.DocItem)[0].ToMap(); item["image"] == "" || item["text"] != "" {
+ t.Fatalf("failure lost attachment or substituted text: %+v", item)
+ }
+}
diff --git a/internal/ingestion/component/media_dispatch.go b/internal/ingestion/component/media_dispatch.go
index 7977560a41..c411d4bce9 100644
--- a/internal/ingestion/component/media_dispatch.go
+++ b/internal/ingestion/component/media_dispatch.go
@@ -76,9 +76,8 @@ func maybeDispatchVideo(
fmt.Errorf("Parser: video parsing is not yet supported; underlying video analysis capability is pending")
}
-// Image dispatch: OCR, or the document text of an SVG, followed by optional
-// IMAGE2TEXT enhancement.
-
+// maybeDispatchImage extracts local or selected-model OCR (native text for SVG),
+// preserves the original image and optionally appends global vision enhancement.
func maybeDispatchImage(
ctx context.Context,
db *gorm.DB,
@@ -123,12 +122,20 @@ func maybeDispatchImage(
return parser.ParseResult{}, true, err
}
} else {
- img, err := decodeDispatchImage(binary, useOCR)
+ ocrModelID := strings.TrimSpace(getStringOr(setup, "ocr_model_id", ""))
+ img, err := decodeDispatchImage(binary, useOCR && ocrModelID == "")
if err != nil {
return parser.ParseResult{}, true, err
}
if useOCR {
- text, ocrErr = extractImageText(ctx, img)
+ if ocrModelID == "" {
+ text, ocrErr = extractImageText(ctx, img)
+ } else {
+ // Selected OCR uses original bytes, so media admission need not
+ // cover database resolution or remote inference.
+ release()
+ text, ocrErr = extractSelectedImageOCR(ctx, db, getStringOr(inputs, "tenant_id", ""), ocrModelID, binary)
+ }
}
}
release()
@@ -192,6 +199,8 @@ func maybeDispatchImage(
return parsed, true, nil
}
+// decodeDispatchImage validates dimensions and raster limits for all image
+// sources, decoding pixels only when local DeepDoc OCR needs them.
func decodeDispatchImage(data []byte, decodeRaster bool) (image.Image, error) {
config, _, err := image.DecodeConfig(bytes.NewReader(data))
if err != nil {
@@ -206,7 +215,7 @@ func decodeDispatchImage(data []byte, decodeRaster bool) (image.Image, error) {
if err := parser.CheckImageRasterLimit(config.Width, config.Height); err != nil {
return nil, fmt.Errorf("parser: %w", err)
}
- // VLM consumes the original bytes; only local OCR needs a decoded raster.
+ // VLM and PaddleOCR consume the original bytes; only DeepDoc needs a raster.
if !decodeRaster {
return nil, nil
}
diff --git a/internal/ingestion/component/parser.go b/internal/ingestion/component/parser.go
index f2f1512a06..3dc3c4c863 100644
--- a/internal/ingestion/component/parser.go
+++ b/internal/ingestion/component/parser.go
@@ -277,6 +277,11 @@ func (c *ParserComponent) Check() error {
return errors.New("parser: image ocr_enabled must be a boolean")
}
}
+ if raw, exists := img["ocr_model_id"]; exists {
+ if _, isString := raw.(string); !isString {
+ return errors.New("parser: image ocr_model_id must be a string")
+ }
+ }
// An image needs at least one text source: local OCR or the global
// vision enhancement. With neither, the item carries no text and the
// Tokenizer drops it, so reject the configuration at build time
diff --git a/internal/ingestion/component/pdf_vision_dispatch.go b/internal/ingestion/component/pdf_vision_dispatch.go
index f11cd1b5a3..53897b6496 100644
--- a/internal/ingestion/component/pdf_vision_dispatch.go
+++ b/internal/ingestion/component/pdf_vision_dispatch.go
@@ -283,8 +283,8 @@ func defaultIsMonkeyOCRv2LayoutModelID(ctx context.Context, db *gorm.DB, tenantI
if db == nil || strings.TrimSpace(modelID) == "" {
return false
}
- driver, _, _, _, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
- return err == nil && strings.EqualFold(driver.Name(), "monkeyocrv2")
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
+ return err == nil && strings.EqualFold(resolved.driver.Name(), "monkeyocrv2")
}
func monkeyOCRv2ParseRequest(ctx context.Context, apiURL, filename string, binary []byte, timeout time.Duration) ([]byte, error) {
@@ -582,8 +582,11 @@ var resolveMinerUModelForDispatch = defaultResolveMinerUModelForDispatch
func defaultResolveMinerUModelForDispatch(ctx context.Context, db *gorm.DB, tenantID, modelID string) (modelModule.ModelDriver, string, *modelModule.APIConfig, error) {
modelID = strings.TrimSpace(modelID)
if modelID != "" && !strings.Contains(modelID, "@") {
- driver, modelName, apiConfig, _, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
- return driver, modelName, apiConfig, err
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
+ if err != nil {
+ return nil, "", nil, err
+ }
+ return resolved.driver, resolved.model.ModelName, resolved.apiConfig, nil
}
if modelID != "" {
driver, modelName, apiConfig, _, err := resolveModelConfig(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
@@ -612,8 +615,11 @@ var resolvePaddleOCRModelForDispatch = defaultResolvePaddleOCRModelForDispatch
func defaultResolvePaddleOCRModelForDispatch(ctx context.Context, db *gorm.DB, tenantID, modelID string) (modelModule.ModelDriver, string, *modelModule.APIConfig, error) {
if strings.TrimSpace(modelID) != "" && !strings.Contains(modelID, "@") {
- driver, modelName, apiConfig, _, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
- return driver, modelName, apiConfig, err
+ resolved, err := resolveModelConfigByID(ctx, db, tenantID, entity.ModelTypeOCR, modelID)
+ if err != nil {
+ return nil, "", nil, err
+ }
+ return resolved.driver, resolved.model.ModelName, resolved.apiConfig, nil
}
driver, modelName, apiConfig, _, err := resolveTenantOCRModelByProvider(ctx, db, tenantID, "PaddleOCR")
return driver, modelName, apiConfig, err
diff --git a/internal/ingestion/pipeline/image_ocr_test.go b/internal/ingestion/pipeline/image_ocr_test.go
new file mode 100644
index 0000000000..351cab397e
--- /dev/null
+++ b/internal/ingestion/pipeline/image_ocr_test.go
@@ -0,0 +1,209 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package pipeline
+
+import (
+ "bytes"
+ "context"
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "image"
+ "image/png"
+ "net/http"
+ "net/http/httptest"
+ "reflect"
+ "strings"
+ "testing"
+
+ "github.com/glebarez/sqlite"
+ "gorm.io/gorm"
+ "gorm.io/gorm/logger"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/entity"
+ "ragflow/internal/ingestion/component"
+ "ragflow/internal/ingestion/component/chunker"
+)
+
+type imageOCREmbedder struct{ texts []string }
+
+// MaxTokens gives the fixture enough room for the invoice's OCR text.
+func (*imageOCREmbedder) MaxTokens() int { return 2048 }
+
+// BatchSize bounds the embedding fixture's request size.
+func (*imageOCREmbedder) BatchSize() int { return 16 }
+
+// Encode captures the exact indexed text and supplies deterministic vectors.
+func (e *imageOCREmbedder) Encode(_ context.Context, texts []string) ([]component.EmbeddingResult, error) {
+ e.texts = append(e.texts, texts...)
+ out := make([]component.EmbeddingResult, len(texts))
+ for i := range out {
+ out[i] = component.EmbeddingResult{Vector: []float64{0.2, 0.8}, TokenCount: 8}
+ }
+ return out, nil
+}
+
+// TestImageOCRSavedConfigToSearchableChunk runs the real config cleaner, SQLite
+// persistence, resolver, OCR driver, Parser, decorated OneChunker and Tokenizer.
+// Only OCR inference, object storage and embedding inference are test doubles.
+func TestImageOCRSavedConfigToSearchableChunk(t *testing.T) {
+ var imageBytes bytes.Buffer
+ if err := png.Encode(&imageBytes, image.NewRGBA(image.Rect(0, 0, 12, 12))); err != nil {
+ t.Fatal(err)
+ }
+ const text = "Invoice INV-21030 total 42."
+ seen := make(chan []byte, 1)
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/layout-parsing" || r.Header.Get("Authorization") != "Bearer fixture-key" {
+ t.Errorf("wrong selected instance request: %s %s", r.URL.Path, r.Header.Get("Authorization"))
+ }
+ var request struct {
+ File string `json:"file"`
+ FileType int `json:"fileType"`
+ Algorithm string `json:"algorithm"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+ t.Error(err)
+ }
+ if request.FileType != 1 || request.Algorithm != "PP-OCRv6" {
+ t.Errorf("not the selected image model: %+v", request)
+ }
+ data, _ := base64.StdEncoding.DecodeString(request.File)
+ seen <- data
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = fmt.Fprintf(w, `{"errorCode":0,"result":{"layoutParsingResults":[{"markdown":{"text":%q}}]}}`, text)
+ }))
+ defer server.Close()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+ if err != nil {
+ t.Fatal(err)
+ }
+ sqlDB, err := db.DB()
+ if err != nil {
+ t.Fatal(err)
+ }
+ sqlDB.SetMaxOpenConns(1)
+ defer sqlDB.Close()
+ if err := db.AutoMigrate(&entity.Knowledgebase{}, &entity.TenantModelProvider{}, &entity.TenantModelInstance{}, &entity.TenantModel{}); err != nil {
+ t.Fatal(err)
+ }
+ registry, err := DefaultRegistry()
+ if err != nil {
+ t.Fatal(err)
+ }
+ template, ok := registry.Get("picture")
+ if !ok {
+ t.Fatal("picture template missing")
+ }
+ dsl, err := json.Marshal(template.DSL)
+ if err != nil {
+ t.Fatal(err)
+ }
+ const parserID = "Parser:ViewsCaptureLight"
+ config := BuildParserConfig(dsl, map[string]any{parserID: map[string]any{
+ "image": map[string]any{"ocr_enabled": true, "ocr_model_id": "ocr-model", "output_format": "json"},
+ "enable_vision_enhancement": false,
+ }})
+ for _, row := range []any{
+ &entity.Knowledgebase{ID: "kb-1", TenantID: "tenant-1", Name: "Image OCR fixture", ParserConfig: config},
+ &entity.TenantModelProvider{ID: "ocr-provider", TenantID: "tenant-1", ProviderName: "PaddleOCR.local"},
+ &entity.TenantModelInstance{ID: "ocr-instance", ProviderID: "ocr-provider", InstanceName: "selected",
+ Status: "active", APIKey: "fixture-key", Extra: fmt.Sprintf(`{"base_url":%q}`, server.URL)},
+ &entity.TenantModel{ID: "ocr-model", ProviderID: "ocr-provider", InstanceID: "ocr-instance",
+ ModelName: "PP-OCRv6", Status: "active", ModelType: int(entity.ModelTypeOCR)},
+ } {
+ if err := db.Create(row).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+ var saved entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-1").Take(&saved).Error; err != nil {
+ t.Fatal(err)
+ }
+ params := saved.ParserConfig[parserID].(map[string]any)
+ if params["image"].(map[string]any)["ocr_model_id"] != "ocr-model" {
+ t.Fatal("image model selection did not survive save/readback")
+ }
+ parserComponent, err := component.NewParserComponent(params)
+ if err != nil {
+ t.Fatal(err)
+ }
+ inputs := map[string]any{"name": "invoice.png", "file_type": "image", "binary": imageBytes.Bytes(),
+ "tenant_id": "tenant-1", "kb_id": "kb-1", "doc_id": "doc-1"}
+ parsed, err := parserComponent.Invoke(t.Context(), db, inputs)
+ if err != nil {
+ t.Fatal(err)
+ }
+ select {
+ case data := <-seen:
+ if !bytes.Equal(data, imageBytes.Bytes()) {
+ t.Fatal("OCR received different image bytes")
+ }
+ default:
+ t.Fatal("OCR model not invoked")
+ }
+ factory, _, _, ok := runtime.DefaultRegistry.Lookup("OneChunker")
+ if !ok {
+ t.Fatal("OneChunker not registered")
+ }
+ chunkComponent, err := factory("OneChunker", nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ originalUploader := chunker.ChunkImageUploader
+ var uploaded []byte
+ chunker.ChunkImageUploader = func(_ context.Context, kbID, chunkID string, data []byte) (string, error) {
+ uploaded = append([]byte(nil), data...)
+ return kbID + "-" + chunkID, nil
+ }
+ t.Cleanup(func() { chunker.ChunkImageUploader = originalUploader })
+ for key, value := range parsed {
+ inputs[key] = value
+ }
+ chunked, err := chunkComponent.Invoke(t.Context(), db, inputs)
+ if err != nil {
+ t.Fatal(err)
+ }
+ embedder := &imageOCREmbedder{}
+ tokenizer, err := component.NewTokenizerComponentWithResolver(map[string]any{
+ "search_method": []string{"embedding"}, "filename_embd_weight": 0,
+ }, func(context.Context, string, string) (component.Embedder, string, error) {
+ return embedder, "fixture-embedding", nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ for key, value := range chunked {
+ inputs[key] = value
+ }
+ indexable, err := tokenizer.Invoke(t.Context(), db, inputs)
+ if err != nil {
+ t.Fatal(err)
+ }
+ chunks := indexable["chunks"].([]map[string]any)
+ if len(chunks) != 1 || chunks[0]["text"] != text {
+ t.Fatalf("searchable OCR text was lost: %+v", chunks)
+ }
+ if !reflect.DeepEqual(embedder.texts, []string{"invoice.png", text}) || !bytes.Equal(uploaded, imageBytes.Bytes()) {
+ t.Fatalf("embedding input=%q image preserved=%v", embedder.texts, bytes.Equal(uploaded, imageBytes.Bytes()))
+ }
+ if id, _ := chunks[0]["img_id"].(string); !strings.HasPrefix(id, "kb-1-") {
+ t.Fatalf("indexed image reference lost: %+v", chunks[0])
+ }
+ if _, ok := chunks[0]["q_2_vec"]; !ok {
+ t.Fatalf("embedding vector missing: %+v", chunks[0])
+ }
+}
diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts
index 743a328857..a5e0d612c3 100644
--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -2774,7 +2774,15 @@ Best for: Documents with flowing, contextually connected content — such as boo
'Use a vision model to parse image and table blocks; when off, they are treated as plain text.',
imageOcr: 'OCR',
imageOcrTip:
- 'Extract text from uploaded images locally. Vision enhancement adds descriptions independently of this switch.',
+ 'Extract text from uploaded images with local OCR or the selected PaddleOCR model. Vision enhancement adds descriptions independently of this switch.',
+ imageOcrModel: 'OCR model',
+ imageOcrLocal: 'DeepDoc',
+ imageOcrModelTip:
+ 'Choose DeepDoc for local OCR, or an added PaddleOCR or PaddleOCR.local model. Turning OCR off keeps this choice but skips OCR; SVG text is read directly.',
+ imageOcrModelsError:
+ 'Could not load OCR models. Your selection is unchanged. Try again later, or choose DeepDoc for local OCR.',
+ imageOcrNoModels:
+ 'No PaddleOCR models added. Use DeepDoc for local OCR, or add a PaddleOCR model in model settings.',
imageTextSourceRequired:
'Images need a text source: keep OCR or vision enhancement on.',
visionEnhancementPromptTip:
diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts
index 2aee01f4cd..531f3c2944 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -2350,7 +2350,15 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
'所有解析后的 sections 会按原始顺序合并为 1 个 chunk。',
imageOcr: 'OCR',
imageOcrTip:
- '从上传的图片中本地提取文字。视觉增强独立于该开关,为图片补充描述。',
+ '使用本地 OCR 或所选 PaddleOCR 模型提取图片文字。视觉增强独立于该开关,为图片补充描述。',
+ imageOcrModel: 'OCR 模型',
+ imageOcrLocal: 'DeepDoc',
+ imageOcrModelTip:
+ '选择 DeepDoc 使用本地 OCR,或选择已添加的 PaddleOCR 或 PaddleOCR.local 模型。关闭 OCR 会保留选择但不执行 OCR;SVG 直接读取文字。',
+ imageOcrModelsError:
+ 'OCR 模型加载失败,已保留当前选择。请稍后重试,或选择 DeepDoc 使用本地 OCR。',
+ imageOcrNoModels:
+ '尚未添加 PaddleOCR 模型。可使用本地 DeepDoc OCR,或在模型设置中添加 PaddleOCR 模型。',
imageTextSourceRequired: '图片需要文本来源,请保留 OCR 或视觉增强。',
visionEnhancementPromptTip:
'自定义视觉模型的指令。留空则使用内置提示词。',
diff --git a/web/src/pages/agent/form/parser-form/image-form-fields.test.tsx b/web/src/pages/agent/form/parser-form/image-form-fields.test.tsx
index 194e8ca49d..a3aacbe7f7 100644
--- a/web/src/pages/agent/form/parser-form/image-form-fields.test.tsx
+++ b/web/src/pages/agent/form/parser-form/image-form-fields.test.tsx
@@ -2,6 +2,9 @@ import { fireEvent, render, screen } from '@testing-library/react';
import { FormProvider, useForm } from 'react-hook-form';
import { FileType } from '@/constants/file';
import message from '@/components/ui/message';
+import { useFetchAllAddedModels } from '@/hooks/use-llm-request';
+import en from '@/locales/en';
+import zh from '@/locales/zh';
import { ImageFormFields } from './image-form-fields';
jest.mock('@/components/ui/message', () => ({
@@ -10,24 +13,49 @@ jest.mock('@/components/ui/message', () => ({
}));
jest.mock('react-i18next', () => ({
- useTranslation: () => ({ t: (key: string) => key }),
+ useTranslation: () => ({
+ t: (key: string) => (key === 'flow.imageOcrLocal' ? 'DeepDoc' : key),
+ }),
+}));
+
+jest.mock('@/hooks/use-llm-request', () => ({
+ useFetchAllAddedModels: jest.fn(() => ({
+ data: [],
+ isFetched: true,
+ isError: false,
+ })),
+}));
+
+jest.mock('../../context', () => ({
+ useOwnerTenantId: () => 'canvas-owner',
+}));
+
+jest.mock('@/components/llm-select/llm-label', () => ({
+ __esModule: true,
+ default: () => null,
+ MissingModelLabel: ({ value }: { value: string }) => (
+ <span>Missing: {value}</span>
+ ),
}));
jest.mock('@/components/ragflow-form', () => ({
- RAGFlowFormItem: ({ name, children }: any) => {
+ RAGFlowFormItem: ({ name, children, description }: any) => {
const {
Controller,
useFormContext,
}: typeof import('react-hook-form') = require('react-hook-form');
const { control } = useFormContext();
return (
- <Controller
- name={name}
- control={control}
- render={({ field }) =>
- typeof children === 'function' ? children(field) : children
- }
- />
+ <>
+ <Controller
+ name={name}
+ control={control}
+ render={({ field }) =>
+ typeof children === 'function' ? children(field) : children
+ }
+ />
+ {description}
+ </>
);
},
}));
@@ -37,26 +65,233 @@ const warningMock = message.warning as jest.Mock;
function ParserImageForm({
visionEnabled = false,
ocrEnabled = true,
+ modelId = '',
}: {
visionEnabled?: boolean;
ocrEnabled?: boolean;
+ modelId?: string;
}) {
const form = useForm({
defaultValues: {
enable_vision_enhancement: visionEnabled,
vlm: { llm_id: '', system_prompt: '' },
- setups: [{ fileFormat: FileType.Image, ocr_enabled: ocrEnabled }],
+ setups: [
+ {
+ fileFormat: FileType.Image,
+ ocr_enabled: ocrEnabled,
+ ocr_model_id: modelId,
+ },
+ ],
},
});
return (
<FormProvider {...form}>
<ImageFormFields prefix="setups.0" />
+ <pre data-testid="saved-values">{JSON.stringify(form.watch())}</pre>
</FormProvider>
);
}
beforeEach(() => {
warningMock.mockClear();
+ (useFetchAllAddedModels as jest.Mock).mockReturnValue({
+ data: [],
+ isFetched: true,
+ isError: false,
+ });
+});
+
+describe('image OCR model selection', () => {
+ const models = [
+ {
+ model_id: 'local-b',
+ name: 'PP-OCRv6',
+ provider_name: 'PaddleOCR.local',
+ instance_name: 'Local B',
+ model_type: ['ocr'],
+ },
+ {
+ model_id: 'cloud-b',
+ name: 'PaddleOCR-VL-1.5',
+ provider_name: 'PaddleOCR',
+ instance_name: 'Cloud B',
+ model_type: ['ocr'],
+ },
+ {
+ model_id: 'mineru',
+ name: 'Unsupported OCR',
+ provider_name: 'MinerU',
+ instance_name: 'Other',
+ model_type: ['ocr'],
+ },
+ {
+ model_id: 'vision',
+ name: 'Not an OCR model',
+ provider_name: 'PaddleOCR',
+ instance_name: 'Vision',
+ model_type: ['vision'],
+ },
+ ];
+
+ it('defaults to local OCR and fetches the canvas owner models', () => {
+ render(<ParserImageForm />);
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent('DeepDoc');
+ expect(useFetchAllAddedModels).toHaveBeenCalledWith('ocr', 'canvas-owner');
+ });
+
+ it('names the built-in OCR model DeepDoc in English and Chinese', () => {
+ expect(en.translation.flow.imageOcrLocal).toBe('DeepDoc');
+ expect(zh.translation.flow.imageOcrLocal).toBe('DeepDoc');
+ });
+
+ it('switches from an enrolled model back to DeepDoc without persisting a sentinel', () => {
+ (useFetchAllAddedModels as jest.Mock).mockReturnValue({
+ data: models,
+ isFetched: true,
+ isError: false,
+ });
+ render(<ParserImageForm />);
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ fireEvent.click(screen.getByText('PP-OCRv6'));
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":"local-b"',
+ );
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ fireEvent.click(screen.getByText('DeepDoc'));
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent('DeepDoc');
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":""',
+ );
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ fireEvent.click(screen.getByText('PaddleOCR-VL-1.5'));
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":"cloud-b"',
+ );
+ });
+
+ it('distinguishes a successful empty list from a failed request', () => {
+ render(<ParserImageForm />);
+ expect(screen.getByRole('status')).toHaveTextContent(
+ 'flow.imageOcrNoModels',
+ );
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ expect(screen.getAllByText('DeepDoc')).toHaveLength(2);
+ });
+
+ it('shows a request failure and a missing saved model after loading ends', () => {
+ const modelQuery = useFetchAllAddedModels as jest.Mock;
+ modelQuery.mockReturnValue({
+ data: [],
+ isFetched: false,
+ isError: false,
+ });
+ const { rerender } = render(<ParserImageForm modelId="deleted-model" />);
+ expect(
+ screen.queryByText('Missing: deleted-model'),
+ ).not.toBeInTheDocument();
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ modelQuery.mockReturnValue({
+ data: [],
+ isFetched: true,
+ isError: true,
+ });
+ rerender(<ParserImageForm modelId="deleted-model" />);
+ expect(screen.getByRole('alert')).toHaveTextContent(
+ 'flow.imageOcrModelsError',
+ );
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent(
+ 'Missing: deleted-model',
+ );
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":"deleted-model"',
+ );
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ fireEvent.click(screen.getByText('DeepDoc'));
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":""',
+ );
+ });
+
+ it('preserves cached models and the selected ID when refetch fails', () => {
+ (useFetchAllAddedModels as jest.Mock).mockReturnValue({
+ data: models,
+ isFetched: true,
+ isError: true,
+ });
+ render(<ParserImageForm modelId="cloud-b" />);
+ expect(screen.getByRole('alert')).toHaveTextContent(
+ 'flow.imageOcrModelsError',
+ );
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent(
+ 'PaddleOCR-VL-1.5',
+ );
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":"cloud-b"',
+ );
+ expect(screen.queryByText('Missing: cloud-b')).not.toBeInTheDocument();
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ });
+
+ it('keeps DeepDoc selected when the first model request fails', () => {
+ (useFetchAllAddedModels as jest.Mock).mockReturnValue({
+ data: [],
+ isFetched: true,
+ isError: true,
+ });
+ render(<ParserImageForm />);
+ expect(screen.getByRole('alert')).toHaveTextContent(
+ 'flow.imageOcrModelsError',
+ );
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent('DeepDoc');
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":""',
+ );
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ expect(screen.getAllByText('DeepDoc')).toHaveLength(2);
+ });
+
+ it('offers only supported enrolled OCR models and saves their IDs', () => {
+ (useFetchAllAddedModels as jest.Mock).mockReturnValue({
+ data: models,
+ isFetched: true,
+ });
+ render(<ParserImageForm />);
+ fireEvent.click(screen.getByTestId('image-ocr-model'));
+ expect(screen.queryByText('Unsupported OCR')).not.toBeInTheDocument();
+ expect(screen.queryByText('Not an OCR model')).not.toBeInTheDocument();
+ fireEvent.click(screen.getByText('PP-OCRv6'));
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":"local-b"',
+ );
+ });
+
+ it('preserves the selected model while OCR is off and restores it on re-enable', () => {
+ (useFetchAllAddedModels as jest.Mock).mockReturnValue({
+ data: models,
+ isFetched: true,
+ });
+ render(<ParserImageForm visionEnabled modelId="cloud-b" />);
+ fireEvent.click(screen.getByRole('switch'));
+ expect(screen.queryByTestId('image-ocr-model')).not.toBeInTheDocument();
+ expect(screen.getByTestId('saved-values')).toHaveTextContent(
+ '"ocr_model_id":"cloud-b"',
+ );
+ fireEvent.click(screen.getByRole('switch'));
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent(
+ 'PaddleOCR-VL-1.5',
+ );
+ });
+
+ it('keeps a deleted model visible instead of silently choosing local OCR', () => {
+ render(<ParserImageForm modelId="deleted-model" />);
+ expect(screen.getByTestId('image-ocr-model')).toHaveTextContent(
+ 'Missing: deleted-model',
+ );
+ });
});
describe('image OCR switch guard', () => {
diff --git a/web/src/pages/agent/form/parser-form/image-form-fields.tsx b/web/src/pages/agent/form/parser-form/image-form-fields.tsx
index a67a14616b..61700adb4c 100644
--- a/web/src/pages/agent/form/parser-form/image-form-fields.tsx
+++ b/web/src/pages/agent/form/parser-form/image-form-fields.tsx
@@ -1,9 +1,19 @@
+import { MissingModelLabel } from '@/components/llm-select/llm-label';
+import { buildModelTree } from '@/components/model-tree-select';
import { RAGFlowFormItem } from '@/components/ragflow-form';
+import { TreeSelect } from '@/components/tree-select';
import message from '@/components/ui/message';
import { Switch } from '@/components/ui/switch';
-import { useCallback } from 'react';
+import { useFetchAllAddedModels } from '@/hooks/use-llm-request';
+import {
+ ComponentPropsWithoutRef,
+ forwardRef,
+ useCallback,
+ useMemo,
+} from 'react';
import { useFormContext, useWatch } from 'react-hook-form';
import { useTranslation } from 'react-i18next';
+import { useOwnerTenantId } from '../../context';
import { CommonProps } from './interface';
import { ParserFormSchemaType } from './schema';
import { buildFieldNameWithPrefix } from './utils';
@@ -13,6 +23,30 @@ type ImageOcrSwitchProps = {
onCheckedChange: (checked: boolean) => void;
};
+const DeepDocModelId = '__image_ocr_deepdoc__';
+
+// Keep the UI-only option out of the form and serialized parser configuration.
+const ImageOCRModelSelect = forwardRef<
+ HTMLButtonElement,
+ ComponentPropsWithoutRef<typeof TreeSelect>
+>(function ImageOCRModelSelect({ value, onChange, allowClear, ...props }, ref) {
+ const handleModelChange = useCallback(
+ (modelId: string) => {
+ onChange?.(modelId === DeepDocModelId ? '' : modelId);
+ },
+ [onChange],
+ );
+ return (
+ <TreeSelect
+ {...props}
+ ref={ref}
+ value={value || DeepDocModelId}
+ onChange={handleModelChange}
+ allowClear={allowClear && !!value}
+ />
+ );
+});
+
// OCR can only be turned off while the global vision enhancement is on: with
// neither, the image carries no text and the backend rejects the canvas.
function ImageOcrSwitch({ checked, onCheckedChange }: ImageOcrSwitchProps) {
@@ -37,28 +71,97 @@ function ImageOcrSwitch({ checked, onCheckedChange }: ImageOcrSwitchProps) {
return <Switch checked={checked} onCheckedChange={handleCheckedChange} />;
}
-// The image setup carries a single switch: run local OCR or not. The vision
-// model and its description prompt belong to the global enhancement block (see
-// VisionEnhancementFormFields); response language is not a setting anywhere and
-// follows the knowledge base, which also drives tokenization.
-export function ImageFormFields({ prefix }: CommonProps) {
+/** Lists enrolled PaddleOCR models using the canvas owner's tenant context. */
+function ImageOCRModelField({ prefix }: CommonProps) {
const { t } = useTranslation();
+ const ownerTenantId = useOwnerTenantId();
+ const { data, isFetched, isError } = useFetchAllAddedModels(
+ 'ocr',
+ ownerTenantId,
+ );
+ const models = useMemo(
+ () =>
+ buildModelTree(
+ data.filter(
+ (model) =>
+ model.model_id &&
+ ['paddleocr', 'paddleocr.local'].includes(
+ model.provider_name.toLowerCase(),
+ ),
+ ),
+ ['ocr'],
+ ),
+ [data],
+ );
+ const renderMissingModel = useCallback(
+ (value: string) => (
+ <MissingModelLabel value={value} ownerTenantId={ownerTenantId} />
+ ),
+ [ownerTenantId],
+ );
+ const options = useMemo(
+ () => [{ id: DeepDocModelId, title: t('flow.imageOcrLocal') }, ...models],
+ [models, t],
+ );
+ const description = isError ? (
+ <span role="alert" className="text-state-error">
+ {t('flow.imageOcrModelsError')}
+ </span>
+ ) : isFetched && models.length === 0 ? (
+ <span role="status">{t('flow.imageOcrNoModels')}</span>
+ ) : undefined;
return (
<RAGFlowFormItem
- name={buildFieldNameWithPrefix('ocr_enabled', prefix)}
- label={t('flow.imageOcr')}
- tooltip={t('flow.imageOcrTip')}
- horizontal={true}
- labelClassName="w-full"
- valueClassName="w-8"
+ name={buildFieldNameWithPrefix('ocr_model_id', prefix)}
+ label={t('flow.imageOcrModel')}
+ tooltip={t('flow.imageOcrModelTip')}
+ description={description}
>
{(field) => (
- <ImageOcrSwitch
- checked={!!field.value}
- onCheckedChange={field.onChange}
+ <ImageOCRModelSelect
+ ref={field.ref}
+ data={options}
+ value={field.value}
+ onChange={field.onChange}
+ placeholder={t('flow.imageOcrLocal')}
+ loading={!isFetched}
+ renderMissingValue={renderMissingModel}
+ allowClear
+ showSearch
+ defaultExpandAll
+ testId="image-ocr-model"
/>
)}
</RAGFlowFormItem>
);
}
+
+/** Keeps optional OCR selection separate from the global VLM enhancement. */
+export function ImageFormFields({ prefix }: CommonProps) {
+ const { t } = useTranslation();
+ const ocrEnabled = useWatch({
+ name: buildFieldNameWithPrefix('ocr_enabled', prefix),
+ });
+
+ return (
+ <>
+ <RAGFlowFormItem
+ name={buildFieldNameWithPrefix('ocr_enabled', prefix)}
+ label={t('flow.imageOcr')}
+ tooltip={t('flow.imageOcrTip')}
+ horizontal={true}
+ labelClassName="w-full"
+ valueClassName="w-8"
+ >
+ {(field) => (
+ <ImageOcrSwitch
+ checked={!!field.value}
+ onCheckedChange={field.onChange}
+ />
+ )}
+ </RAGFlowFormItem>
+ {ocrEnabled && <ImageOCRModelField prefix={prefix} />}
+ </>
+ );
+}
diff --git a/web/src/pages/agent/form/parser-form/schema.test.ts b/web/src/pages/agent/form/parser-form/schema.test.ts
index 1797d77a38..2d302afb4d 100644
--- a/web/src/pages/agent/form/parser-form/schema.test.ts
+++ b/web/src/pages/agent/form/parser-form/schema.test.ts
@@ -3,6 +3,30 @@ import { ParserFields } from '../../constant/pipeline';
import { FormSchema } from './schema';
describe('parser FormSchema', () => {
+ it('keeps the explicit image OCR model through schema save/readback', () => {
+ const values = {
+ setups: [
+ {
+ fileFormat: FileType.Image,
+ ocr_enabled: true,
+ ocr_model_id: 'model-b',
+ },
+ ],
+ };
+ expect(
+ FormSchema.parse(JSON.parse(JSON.stringify(FormSchema.parse(values)))),
+ ).toEqual(values);
+ });
+
+ it('rejects non-string image OCR model IDs', () => {
+ expect(
+ FormSchema.safeParse({
+ setups: [
+ { fileFormat: FileType.Image, ocr_enabled: true, ocr_model_id: 123 },
+ ],
+ }).success,
+ ).toBe(false);
+ });
it('accepts video and audio setups without a model', () => {
const result = FormSchema.safeParse({
setups: [
diff --git a/web/src/pages/agent/form/parser-form/schema.ts b/web/src/pages/agent/form/parser-form/schema.ts
index d14959b723..ab2d61c0e6 100644
--- a/web/src/pages/agent/form/parser-form/schema.ts
+++ b/web/src/pages/agent/form/parser-form/schema.ts
@@ -13,6 +13,7 @@ export const SetupSchema = z
// the new boolean contract. Legacy setups may still carry a parse_method
// only; normalizeParserFormValues migrates them on load.
ocr_enabled: z.boolean().optional(),
+ ocr_model_id: z.string().optional(),
lang: z.string().optional(),
fields: z.array(z.string()).optional(),
// Per-setup vlm is only used by Audio (its ASR model); the vision model
diff --git a/web/src/pages/agent/utils.test.ts b/web/src/pages/agent/utils.test.ts
index 24dd6e6406..58edba29a4 100644
--- a/web/src/pages/agent/utils.test.ts
+++ b/web/src/pages/agent/utils.test.ts
@@ -1,5 +1,6 @@
import { RAGFlowNodeType } from '@/interfaces/database/agent';
import { FileType } from '@/constants/file';
+import { transformApiConfigToForm } from '@/utils/pipeline-operator';
import { Operator } from './constant';
import {
generateNodeNamesWithIncreasingIndex,
@@ -13,6 +14,34 @@ import {
} from './utils';
describe('transformParserParams vision settings', () => {
+ it.each(['model-b', ''])(
+ 'saves the explicit image OCR selection %j',
+ (modelId) => {
+ const result: Record<string, any> = transformParserParams({
+ enable_vision_enhancement: false,
+ setups: [
+ {
+ fileFormat: FileType.Image,
+ ocr_enabled: true,
+ ocr_model_id: modelId,
+ },
+ ],
+ } as any);
+ expect(result.image).toMatchObject({
+ ocr_enabled: true,
+ ocr_model_id: modelId,
+ });
+ expect(result.vlm.llm_id).toBe('');
+ const reloaded = transformApiConfigToForm(
+ Operator.Parser,
+ JSON.parse(JSON.stringify(result)),
+ );
+ const savedAgain: Record<string, any> = transformParserParams(
+ reloaded as any,
+ );
+ expect(savedAgain.image).toEqual(result.image);
+ },
+ );
it('saves the normalized global settings when the node form was not opened', () => {
const result = transformParserParams({
setups: [
@@ -46,7 +75,7 @@ describe('transformParserParams vision settings', () => {
});
});
- it('writes the image family as a switch and nothing else', () => {
+ it('writes the image OCR switch without retired vision fields', () => {
// The saved shape is the contract the Go parser reads, so pin it: the
// switch out, and the retired per-family keys never written back.
const result = transformParserParams({
diff --git a/web/src/pages/agent/utils.ts b/web/src/pages/agent/utils.ts
index 067cafdb4a..04c51b345b 100644
--- a/web/src/pages/agent/utils.ts
+++ b/web/src/pages/agent/utils.ts
@@ -204,6 +204,7 @@ function transformObjectArrayToPureArray(
: [];
}
+/** Serializes parser form fields without losing the selected image OCR model. */
export function transformParserParams(params: ParserFormSchemaType) {
// Save global vision options from the normalized form alongside the
// per-family setups, including nodes whose form has not been opened.
@@ -271,6 +272,7 @@ export function transformParserParams(params: ParserFormSchemaType) {
filteredSetup = {
...filteredSetup,
ocr_enabled: cur.ocr_enabled,
+ ocr_model_id: cur.ocr_model_id,
};
break;
case FileType.Email: