RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
feat(parser): require a text source for images when vision enhancement is off (#20839)
jay77721deb1235be41d
diff --git a/internal/ingestion/component/media_dispatch.go b/internal/ingestion/component/media_dispatch.goindex 10fdeda2cb..424aa67a25 100644--- a/internal/ingestion/component/media_dispatch.go+++ b/internal/ingestion/component/media_dispatch.go@@ -96,11 +96,12 @@ func maybeDispatchImage(return parser.ParseResult{}, false, nil}method := getStringOr(setup, "parse_method", "")- ocrEnabled, hasOCRFlag := setup["ocr_enabled"].(bool)+ _, hasOCRFlag := setup["ocr_enabled"].(bool)// ocr_enabled is the OCR switch. Legacy setups omit it and encode the same// choice in parse_method: "ocr"/empty selects local OCR, any other value is- // a VLM model reference that also implies OCR is off.- useOCR := (hasOCRFlag && ocrEnabled) || (!hasOCRFlag && (method == "" || strings.EqualFold(method, "ocr")))+ // a VLM model reference that also implies OCR is off. The selection itself+ // lives in imageSetupRunsOCR (parser.go), shared with Check().+ useOCR := imageSetupRunsOCR(setup)release, err := parser.AcquireImageMedia(ctx)if err != nil {return parser.ParseResult{}, true, errdiff --git a/internal/ingestion/component/media_dispatch_test.go b/internal/ingestion/component/media_dispatch_test.goindex 2c737d164f..9e5d844e87 100644--- a/internal/ingestion/component/media_dispatch_test.go+++ b/internal/ingestion/component/media_dispatch_test.go@@ -112,12 +112,20 @@ func TestMaybeDispatchImageOCRIndependentOfVision(t *testing.T) {}t.Cleanup(func() { resolveTenantModelByType = originalResolver })imageSetup["ocr_enabled"] = tc.ocr+ params["enable_vision_enhancement"] = tc.enabledcomponent, err := NewParserComponent(params)+ if !tc.ocr && !tc.enabled {+ // Neither text source is configured: construction must fail+ // instead of producing an index-nothing pipeline.+ if err == nil || !strings.Contains(err.Error(), "no text source") {+ t.Fatalf("err = %v, want no-text-source construction error", err)+ }+ return+ }if err != nil {t.Fatal(err)}pc := component.(*ParserComponent)- pc.enableVisionEnhancement = tc.enabledresult, err := pc.Invoke(t.Context(), nil, map[string]any{"name": "photo.png", "file_type": "image", "binary": data, "tenant_id": tc.tenant})if err != nil {t.Fatal(err)diff --git a/internal/ingestion/component/parser.go b/internal/ingestion/component/parser.goindex ec8aacbdf5..1234c34116 100644--- a/internal/ingestion/component/parser.go+++ b/internal/ingestion/component/parser.go@@ -274,10 +274,29 @@ func (c *ParserComponent) Check() error {return errors.New("parser: image ocr_enabled must be a boolean")}}+ // 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+ // instead of indexing nothing silently.+ if !c.enableVisionEnhancement && !imageSetupRunsOCR(img) {+ return errors.New("parser: image has no text source: OCR is off and vision enhancement is disabled")+ }}return nil}+// imageSetupRunsOCR mirrors the OCR selection in maybeDispatchImage+// (media_dispatch.go): the ocr_enabled switch wins when present, otherwise+// the legacy parse_method reading applies ("ocr"/empty runs local OCR).++func imageSetupRunsOCR(setup schema.ParserSetup) bool {+ if ocrEnabled, hasOCRFlag := setup["ocr_enabled"].(bool); hasOCRFlag {+ return ocrEnabled+ }+ method := getStringOr(setup, "parse_method", "")+ return method == "" || strings.EqualFold(method, "ocr")+}+func defaultSetups() map[string]schema.ParserSetup {return map[string]schema.ParserSetup{"pdf": {diff --git a/internal/ingestion/component/parser_check_test.go b/internal/ingestion/component/parser_check_test.goindex baa53134a1..bc3539055f 100644--- a/internal/ingestion/component/parser_check_test.go+++ b/internal/ingestion/component/parser_check_test.go@@ -23,8 +23,9 @@ import ("ragflow/internal/ingestion/component/schema")-// TestParserComponent_Check covers construction-time validation for parser-// methods that require language configuration.+// TestParserComponent_Check covers construction-time validation: the pdf+// parse_method whitelist, the image ocr_enabled type, and the image+// text-source requirement (OCR off + vision enhancement off is rejected).//// audio/video vlm.llm_id is not validated: Python's check() has no// such branch, and audio resolves its model at dispatch time with a@@ -101,8 +102,11 @@ func TestParserComponent_Check(t *testing.T) {enhance: true,},{- name: "image: model reference with lang → pass",- setups: map[string]schema.ParserSetup{"image": {"parse_method": "vlm_xyz", "lang": "English"}},+ // A legacy model reference disables OCR by construction, so without+ // the enhancement there is no text source left.+ name: "image: model reference without enhancement → error",+ setups: map[string]schema.ParserSetup{"image": {"parse_method": "vlm_xyz", "lang": "English"}},+ wantErr: "no text source",},{// Absent parse_method matches the backend's legacy inference, which@@ -119,8 +123,14 @@ func TestParserComponent_Check(t *testing.T) {wantErr: "ocr_enabled must be a boolean",},{- name: "image: boolean ocr_enabled → pass",- setups: map[string]schema.ParserSetup{"image": {"ocr_enabled": false}},+ name: "image: ocr_enabled false without enhancement → error",+ setups: map[string]schema.ParserSetup{"image": {"ocr_enabled": false}},+ wantErr: "no text source",+ },+ {+ name: "image: ocr_enabled false with enhancement → pass",+ setups: map[string]schema.ParserSetup{"image": {"ocr_enabled": false}},+ enhance: true,},{name: "image: ocr_enabled alongside a stale parse_method → pass (switch wins)",diff --git a/web/src/locales/en.ts b/web/src/locales/en.tsindex 6eb89129cc..f5a25287ee 100644--- a/web/src/locales/en.ts+++ b/web/src/locales/en.ts@@ -2779,6 +2779,8 @@ Best for: Documents with flowing, contextually connected content — such as booimageOcr: 'OCR',imageOcrTip:'Extract text from uploaded images locally. Vision enhancement adds descriptions independently of this switch.',+ imageTextSourceRequired:+ 'Images need a text source: keep OCR or vision enhancement on.',visionEnhancementPromptTip:'Custom instruction for the vision model. Leave empty to use the built-in prompt.',enableChildrenDelimiters: 'Child chunk are used for retrieval',diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.tsindex 3b5f531f22..2a39f10a69 100644--- a/web/src/locales/zh.ts+++ b/web/src/locales/zh.ts@@ -2356,6 +2356,7 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 RimageOcr: 'OCR',imageOcrTip:'从上传的图片中本地提取文字。视觉增强独立于该开关,为图片补充描述。',+ imageTextSourceRequired: '图片需要文本来源,请保留 OCR 或视觉增强。',visionEnhancementPromptTip:'自定义视觉模型的指令。留空则使用内置提示词。',enableVisionEnhancement: '启用视觉增强',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.tsxnew file mode 100644index 0000000000..194e8ca49d--- /dev/null+++ b/web/src/pages/agent/form/parser-form/image-form-fields.test.tsx@@ -0,0 +1,89 @@+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 { ImageFormFields } from './image-form-fields';++jest.mock('@/components/ui/message', () => ({+ __esModule: true,+ default: { warning: jest.fn() },+}));++jest.mock('react-i18next', () => ({+ useTranslation: () => ({ t: (key: string) => key }),+}));++jest.mock('@/components/ragflow-form', () => ({+ RAGFlowFormItem: ({ name, children }: 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+ }+ />+ );+ },+}));++const warningMock = message.warning as jest.Mock;++function ParserImageForm({+ visionEnabled = false,+ ocrEnabled = true,+}: {+ visionEnabled?: boolean;+ ocrEnabled?: boolean;+}) {+ const form = useForm({+ defaultValues: {+ enable_vision_enhancement: visionEnabled,+ vlm: { llm_id: '', system_prompt: '' },+ setups: [{ fileFormat: FileType.Image, ocr_enabled: ocrEnabled }],+ },+ });+ return (+ <FormProvider {...form}>+ <ImageFormFields prefix="setups.0" />+ </FormProvider>+ );+}++beforeEach(() => {+ warningMock.mockClear();+});++describe('image OCR switch guard', () => {+ it('blocks turning OCR off while vision enhancement is off', () => {+ render(<ParserImageForm visionEnabled={false} ocrEnabled={true} />);++ fireEvent.click(screen.getByRole('switch'));++ expect(warningMock).toHaveBeenCalledWith('flow.imageTextSourceRequired');+ expect(screen.getByRole('switch')).toHaveAttribute('aria-checked', 'true');+ });++ it('allows turning OCR off while vision enhancement is on', () => {+ render(<ParserImageForm visionEnabled={true} ocrEnabled={true} />);++ fireEvent.click(screen.getByRole('switch'));++ expect(warningMock).not.toHaveBeenCalled();+ expect(screen.getByRole('switch')).toHaveAttribute('aria-checked', 'false');+ });++ it('always allows turning OCR on', () => {+ render(<ParserImageForm visionEnabled={false} ocrEnabled={false} />);++ fireEvent.click(screen.getByRole('switch'));++ expect(warningMock).not.toHaveBeenCalled();+ expect(screen.getByRole('switch')).toHaveAttribute('aria-checked', 'true');+ });+});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.tsxindex e95d3da7c8..a67a14616b 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,42 @@import { RAGFlowFormItem } from '@/components/ragflow-form';+import message from '@/components/ui/message';import { Switch } from '@/components/ui/switch';+import { useCallback } from 'react';+import { useFormContext, useWatch } from 'react-hook-form';import { useTranslation } from 'react-i18next';import { CommonProps } from './interface';+import { ParserFormSchemaType } from './schema';import { buildFieldNameWithPrefix } from './utils';+type ImageOcrSwitchProps = {+ checked: boolean;+ onCheckedChange: (checked: boolean) => void;+};++// 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) {+ const { t } = useTranslation();+ const { control } = useFormContext<ParserFormSchemaType>();+ const visionEnabled = useWatch({+ control,+ name: 'enable_vision_enhancement',+ });++ const handleCheckedChange = useCallback(+ (next: boolean) => {+ if (!next && !visionEnabled) {+ message.warning(t('flow.imageTextSourceRequired'));+ return;+ }+ onCheckedChange(next);+ },+ [onCheckedChange, visionEnabled, t],+ );++ 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@@ -21,7 +54,10 @@ export function ImageFormFields({ prefix }: CommonProps) {valueClassName="w-8">{(field) => (- <Switch checked={!!field.value} onCheckedChange={field.onChange} />+ <ImageOcrSwitch+ checked={!!field.value}+ onCheckedChange={field.onChange}+ />)}</RAGFlowFormItem>);diff --git a/web/src/pages/agent/form/parser-form/schema.test.ts b/web/src/pages/agent/form/parser-form/schema.test.tsindex 71add82be3..1797d77a38 100644--- a/web/src/pages/agent/form/parser-form/schema.test.ts+++ b/web/src/pages/agent/form/parser-form/schema.test.ts@@ -35,4 +35,34 @@ describe('parser FormSchema', () => {});expect(withFields.success).toBe(true);});++ it('rejects image OCR off without vision enhancement', () => {+ const result = FormSchema.safeParse({+ setups: [{ fileFormat: FileType.Image, ocr_enabled: false }],+ enable_vision_enhancement: false,+ });+ expect(result.success).toBe(false);+ if (!result.success) {+ expect(result.error.issues[0]?.path).toEqual([+ 'setups',+ 0,+ 'ocr_enabled',+ ]);+ }+ });++ it('accepts image OCR off with vision enhancement on', () => {+ const result = FormSchema.safeParse({+ setups: [{ fileFormat: FileType.Image, ocr_enabled: false }],+ enable_vision_enhancement: true,+ });+ expect(result.success).toBe(true);+ });++ it('accepts image OCR on without vision enhancement', () => {+ const result = FormSchema.safeParse({+ setups: [{ fileFormat: FileType.Image, ocr_enabled: true }],+ });+ expect(result.success).toBe(true);+ });});diff --git a/web/src/pages/agent/form/parser-form/schema.ts b/web/src/pages/agent/form/parser-form/schema.tsindex 893e47c304..d14959b723 100644--- a/web/src/pages/agent/form/parser-form/schema.ts+++ b/web/src/pages/agent/form/parser-form/schema.ts@@ -58,20 +58,40 @@ export const SetupSchema = z}});-export const FormSchema = z.object({- setups: z.array(SetupSchema).min(1, i18n.t('flow.atLeastOneFileType')),- // Global vision enhancement: one switch + img2txt model + description prompt,- // sitting at the params top level alongside the per-family setups (see the- // backend Parser component contract). Response language is intentionally not- // here: captions are indexed text, so they follow the knowledge base language- // that also drives tokenization, and can never disagree with it.- vlm: z- .object({- llm_id: z.string().optional(),- system_prompt: z.string().optional(),- })- .optional(),- enable_vision_enhancement: z.boolean().optional(),-});+export const FormSchema = z+ .object({+ setups: z.array(SetupSchema).min(1, i18n.t('flow.atLeastOneFileType')),+ // Global vision enhancement: one switch + img2txt model + description prompt,+ // sitting at the params top level alongside the per-family setups (see the+ // backend Parser component contract). Response language is intentionally not+ // here: captions are indexed text, so they follow the knowledge base language+ // that also drives tokenization, and can never disagree with it.+ vlm: z+ .object({+ llm_id: z.string().optional(),+ system_prompt: z.string().optional(),+ })+ .optional(),+ enable_vision_enhancement: z.boolean().optional(),+ })+ .superRefine((values, ctx) => {+ // An image needs at least one text source: local OCR or the global vision+ // enhancement. Reject the dead configuration at save time so a canvas that+ // indexes nothing cannot be written (mirrors the backend Check()).+ if (values.enable_vision_enhancement) {+ return;+ }+ const imageIndex = values.setups.findIndex(+ (setup) =>+ setup.fileFormat === FileType.Image && setup.ocr_enabled === false,+ );+ if (imageIndex >= 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['setups', imageIndex, 'ocr_enabled'],+ message: i18n.t('flow.imageTextSourceRequired'),+ });+ }+ });export type ParserFormSchemaType = z.infer<typeof FormSchema>;diff --git a/web/src/pages/agent/form/parser-form/vision-form-fields.test.tsx b/web/src/pages/agent/form/parser-form/vision-form-fields.test.tsxindex 9ab2c62c1e..6dc81c6571 100644--- a/web/src/pages/agent/form/parser-form/vision-form-fields.test.tsx+++ b/web/src/pages/agent/form/parser-form/vision-form-fields.test.tsx@@ -1,11 +1,18 @@import { fireEvent, render, screen } from '@testing-library/react';import { FormProvider, useForm } from 'react-hook-form';+import message from '@/components/ui/message';+import { FileType } from '@/constants/file';import { VisionEnhancementFormFields } from './vision-form-fields';jest.mock('@/hooks/use-llm-request', () => ({useFetchDefaultModelDictionary: () => ({ img2txt_id: 'model-A' }),}));+jest.mock('@/components/ui/message', () => ({+ __esModule: true,+ default: { warning: jest.fn() },+}));+jest.mock('../../context', () => ({ useOwnerTenantId: () => 'tenant-1' }));jest.mock('react-i18next', () => ({@@ -106,3 +113,51 @@ describe('global vision model selection', () => {expect(screen.getByLabelText('Vision model')).toHaveValue('model-B');});});++const visionWarningMock = message.warning as jest.Mock;++function ParserVisionFormWithImage({+ ocrEnabled = false,+}: {+ ocrEnabled?: boolean;+}) {+ const form = useForm({+ defaultValues: {+ enable_vision_enhancement: true,+ vlm: { llm_id: 'model-B', system_prompt: '' },+ setups: [{ fileFormat: FileType.Image, ocr_enabled: ocrEnabled }],+ },+ });+ return (+ <FormProvider {...form}>+ <VisionEnhancementFormFields />+ </FormProvider>+ );+}++describe('vision enhancement switch guard', () => {+ beforeEach(() => {+ visionWarningMock.mockClear();+ });++ it('blocks turning enhancement off while image OCR is off', () => {+ render(<ParserVisionFormWithImage ocrEnabled={false} />);++ fireEvent.click(screen.getByRole('switch'));++ expect(visionWarningMock).toHaveBeenCalledWith(+ 'flow.imageTextSourceRequired',+ );+ // Still on: the model and prompt fields stay visible.+ expect(screen.getByLabelText('Vision model')).toBeInTheDocument();+ });++ it('allows turning enhancement off while image OCR is on', () => {+ render(<ParserVisionFormWithImage ocrEnabled={true} />);++ fireEvent.click(screen.getByRole('switch'));++ expect(visionWarningMock).not.toHaveBeenCalled();+ expect(screen.queryByLabelText('Vision model')).not.toBeInTheDocument();+ });+});diff --git a/web/src/pages/agent/form/parser-form/vision-form-fields.tsx b/web/src/pages/agent/form/parser-form/vision-form-fields.tsxindex 0cb94bfac9..0403744ffe 100644--- a/web/src/pages/agent/form/parser-form/vision-form-fields.tsx+++ b/web/src/pages/agent/form/parser-form/vision-form-fields.tsx@@ -3,8 +3,10 @@ import {ModelTypeMap,} from '@/components/model-tree-select';import { RAGFlowFormItem } from '@/components/ragflow-form';+import message from '@/components/ui/message';import { Switch } from '@/components/ui/switch';import { Textarea } from '@/components/ui/textarea';+import { FileType } from '@/constants/file';import { ModelTypeToField } from '@/constants/llm';import { useFetchDefaultModelDictionary } from '@/hooks/use-llm-request';import { useCallback } from 'react';@@ -24,11 +26,26 @@ function VisionEnhancementSwitch({enabled,onEnabledChange,}: VisionEnhancementSwitchProps) {+ const { t } = useTranslation();const form = useFormContext<ParserFormSchemaType>();const defaultModelDictionary = useFetchDefaultModelDictionary();const handleCheckedChange = useCallback((checked: boolean) => {+ // Turning the enhancement off while an image setup runs without OCR+ // leaves the image with no text source, so keep it on and say why.+ if (!checked) {+ const setups = form.getValues('setups') ?? [];+ const imageOcrOff = setups.some(+ (setup) =>+ setup?.fileFormat === FileType.Image &&+ setup?.ocr_enabled === false,+ );+ if (imageOcrOff) {+ message.warning(t('flow.imageTextSourceRequired'));+ return;+ }+ }onEnabledChange(checked);if (checked && !form.getValues('vlm.llm_id')) {const modelId = defaultModelDictionary[ModelTypeToField.vision];@@ -37,7 +54,7 @@ function VisionEnhancementSwitch({}}},- [onEnabledChange, form, defaultModelDictionary],+ [onEnabledChange, form, defaultModelDictionary, t],);return <Switch checked={!!enabled} onCheckedChange={handleCheckedChange} />;