Skip to content

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

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.go
index 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, err
diff --git a/internal/ingestion/component/media_dispatch_test.go b/internal/ingestion/component/media_dispatch_test.go
index 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.enabled
component, 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.enabled
result, 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.go
index 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.go
index 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.ts
index 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 boo
imageOcr: '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.ts
index 3b5f531f22..2a39f10a69 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -2356,6 +2356,7 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
imageOcr: '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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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} />;