Skip to content

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

Fix: add hint url for local AI (#20039)

Lynncf1b20ca26b3
diff --git a/conf/models/funasr.json b/conf/models/funasr.json
index ddecb98dad..9383a86a8c 100644
--- a/conf/models/funasr.json
+++ b/conf/models/funasr.json
@@ -7,6 +7,7 @@
"asr": "audio/transcriptions",
"models": "models"
},
+ "url_hint": "http://host.docker.internal:8000/v1",
"class": "local",
"models": [
{
diff --git a/conf/models/gpustack.json b/conf/models/gpustack.json
index 15ef693c96..c555e56752 100644
--- a/conf/models/gpustack.json
+++ b/conf/models/gpustack.json
@@ -5,5 +5,6 @@
"models": "v1/models",
"embedding": "v1-openai/embeddings"
},
+ "url_hint": "http://host.docker.internal:80/v1",
"class": "local"
}
diff --git a/conf/models/llmman.json b/conf/models/llmman.json
index 804dc96473..4b550d08a7 100644
--- a/conf/models/llmman.json
+++ b/conf/models/llmman.json
@@ -5,5 +5,6 @@
"models": "models",
"embedding": "embeddings"
},
+ "url_hint": "http://host.docker.internal:17434/v1",
"class": "local"
}
diff --git a/conf/models/lmstudio.json b/conf/models/lmstudio.json
index 4c0f4b989e..5e92ce19b9 100644
--- a/conf/models/lmstudio.json
+++ b/conf/models/lmstudio.json
@@ -5,5 +5,6 @@
"models": "models",
"embedding": "embeddings"
},
+ "url_hint": "http://host.docker.internal:1234/v1",
"class": "local"
}
diff --git a/conf/models/localai.json b/conf/models/localai.json
index 301e3b5f30..fd0b3049c8 100644
--- a/conf/models/localai.json
+++ b/conf/models/localai.json
@@ -6,5 +6,6 @@
"embedding": "embeddings",
"rerank": "rerank"
},
+ "url_hint": "http://host.docker.internal:8080/v1",
"class": "local"
}
diff --git a/conf/models/mineru_local.json b/conf/models/mineru_local.json
index f0dad7a48b..86102b2728 100644
--- a/conf/models/mineru_local.json
+++ b/conf/models/mineru_local.json
@@ -4,6 +4,7 @@
"doc_parse": "file_parse",
"task": "tasks"
},
+ "url_hint": "http://host.docker.internal:9987",
"class": "local",
"models": [
{
diff --git a/conf/models/monkeyocrv2.json b/conf/models/monkeyocrv2.json
index 5de92771c1..e658b97139 100644
--- a/conf/models/monkeyocrv2.json
+++ b/conf/models/monkeyocrv2.json
@@ -3,6 +3,7 @@
"url_suffix": {
"doc_parse": "parse"
},
+ "url_hint": "http://host.docker.internal:8000",
"class": "local",
"models": [
{
diff --git a/conf/models/ollama.json b/conf/models/ollama.json
index cab76fe2c4..f4c0ff4e0a 100644
--- a/conf/models/ollama.json
+++ b/conf/models/ollama.json
@@ -6,5 +6,6 @@
"models": "api/tags",
"embedding": "api/embed"
},
+ "url_hint": "http://host.docker.internal:11434",
"class": "local"
}
diff --git a/conf/models/paddleocr_local.json b/conf/models/paddleocr_local.json
index 6efda9a5e2..4097b430ed 100644
--- a/conf/models/paddleocr_local.json
+++ b/conf/models/paddleocr_local.json
@@ -3,6 +3,7 @@
"url_suffix": {
"ocr": "layout-parsing"
},
+ "url_hint": "http://host.docker.internal:8080",
"class": "local",
"models": [
{
diff --git a/conf/models/vllm.json b/conf/models/vllm.json
index 5ab96a4cd1..38bfb95b50 100644
--- a/conf/models/vllm.json
+++ b/conf/models/vllm.json
@@ -7,5 +7,6 @@
"embedding": "embeddings",
"rerank": "rerank"
},
+ "url_hint": "http://host.docker.internal:8000/v1",
"class": "local"
}
diff --git a/conf/models/xinference.json b/conf/models/xinference.json
index b77e9de00b..f85d93e869 100644
--- a/conf/models/xinference.json
+++ b/conf/models/xinference.json
@@ -8,5 +8,6 @@
"asr": "v1/audio/transcriptions",
"tts": "v1/audio/speech"
},
+ "url_hint": "http://host.docker.internal:9997",
"class": "local"
}
diff --git a/internal/entity/models/model.go b/internal/entity/models/model.go
index 5d360bfca4..861b54b4bd 100644
--- a/internal/entity/models/model.go
+++ b/internal/entity/models/model.go
@@ -192,6 +192,10 @@ type Provider struct {
Features Features `json:"features"`
Class string `json:"class"`
ModelDriver ModelDriver
+ // URLHint is a display-only example endpoint shown as the URL input's
+ // placeholder. Unlike URL, it is never used to build requests and never
+ // pre-fills the form.
+ URLHint string `json:"url_hint"`
}
// ProviderManager manages provider and model operations
@@ -388,6 +392,9 @@ func (pm *ProviderManager) ListProviders() ([]map[string]interface{}, error) {
"model_types": modelTypes,
"url_suffix": provider.URLSuffix,
}
+ if provider.URLHint != "" {
+ providerData["url_hint"] = provider.URLHint
+ }
providers = append(providers, providerData)
}
diff --git a/internal/entity/models/model_test.go b/internal/entity/models/model_test.go
index d7c6c7b483..6a0c8442f3 100644
--- a/internal/entity/models/model_test.go
+++ b/internal/entity/models/model_test.go
@@ -264,6 +264,36 @@ func TestProviderConfigsLoadURLSuffixKeys(t *testing.T) {
}
}
+// url_hint is a display-only example endpoint: every self-hosted provider
+// advertises one so the UI can hint a base URL, and hosted providers must not
+// (their fixed endpoint comes from `url`).
+func TestProviderConfigsLoadURLHint(t *testing.T) {
+ dir, restore := setupProviderTestDir(t, "cohere.json", "ollama.json")
+ defer restore()
+
+ if err := InitProviderManager(dir); err != nil {
+ t.Fatalf("InitProviderManager: %v", err)
+ }
+
+ pm := GetProviderManager()
+
+ ollama := pm.FindProvider("Ollama")
+ if ollama == nil {
+ t.Fatal("Ollama provider not found")
+ }
+ if ollama.URLHint == "" {
+ t.Error("Ollama url_hint is empty, want an example endpoint")
+ }
+
+ cohere := pm.FindProvider("Cohere")
+ if cohere == nil {
+ t.Fatal("Cohere provider not found")
+ }
+ if cohere.URLHint != "" {
+ t.Errorf("Cohere url_hint=%q, want empty", cohere.URLHint)
+ }
+}
+
func TestProviderConfigRejectsUnknownURLSuffixKey(t *testing.T) {
dir := t.TempDir()
config := []byte(`{
diff --git a/web/jest-setup.ts b/web/jest-setup.ts
index 8a86e2eb0c..dc2501f893 100644
--- a/web/jest-setup.ts
+++ b/web/jest-setup.ts
@@ -21,6 +21,14 @@ if (typeof globalThis.TransformStream === 'undefined') {
Object.assign(globalThis, { TransformStream });
}
+// jsdom does not implement CSS.supports; css-support.ts calls it at module scope
+if (typeof globalThis.CSS === 'undefined') {
+ (globalThis as Record<string, unknown>).CSS = {};
+}
+if (typeof globalThis.CSS.supports !== 'function') {
+ globalThis.CSS.supports = () => false;
+}
+
// Vite's import.meta.glob is rewritten to this stub by jest-esbuild-transformer.cjs
(globalThis as Record<string, unknown>).jestImportMetaGlob = () => ({});
diff --git a/web/src/interfaces/database/llm.ts b/web/src/interfaces/database/llm.ts
index 1a6f7dd200..0ca2dab9f6 100644
--- a/web/src/interfaces/database/llm.ts
+++ b/web/src/interfaces/database/llm.ts
@@ -46,6 +46,12 @@ export interface IAvailableProvider {
model_types: string[];
url: { default?: string; [key: string]: string | undefined };
has_instance: boolean;
+ /**
+ * Display-only example endpoint from the provider catalog
+ * (`conf/models/*.json`). Rendered as the endpoint input's placeholder;
+ * never used to build requests nor to pre-fill the form.
+ */
+ url_hint?: string;
}
export interface IProviderInstance {
diff --git a/web/src/pages/user-setting/setting-model/instance-card/hooks.tsx b/web/src/pages/user-setting/setting-model/instance-card/hooks.tsx
index 24d4f734da..c638e64224 100644
--- a/web/src/pages/user-setting/setting-model/instance-card/hooks.tsx
+++ b/web/src/pages/user-setting/setting-model/instance-card/hooks.tsx
@@ -108,6 +108,10 @@ function pickDefaultUrl(
* `base_url` dropdown options for the current provider.
* Used to pre-fill the URL field with the provider's default URL when
* creating a new instance.
+ *
+ * Also exposes `url_hint`: a display-only example endpoint that becomes
+ * the endpoint input's placeholder. Providers that ship no default URL
+ * (most self-hosted ones) still get a useful hint.
*/
export function useProviderBaseUrlOptions(providerName: string) {
const { data: availableProviders } = useFetchAvailableProviders();
@@ -145,7 +149,9 @@ export function useProviderBaseUrlOptions(providerName: string) {
return options.length > 0 ? options : undefined;
}, [currentProvider]);
- return { baseUrlOptions, availableProviders };
+ const urlHint = useMemo(() => currentProvider?.url_hint, [currentProvider]);
+
+ return { baseUrlOptions, availableProviders, urlHint };
}
// ---------------------------------------------------------------------------
@@ -727,6 +733,7 @@ export function useFormFields(
initialValues: Record<string, any>,
baseUrlOptions: SelectOption[] | undefined,
hideWhenInstanceExists: (values: any) => boolean,
+ urlHint?: string,
) {
const { fields, defaultValues } = useProviderFields({
llmFactory: providerName,
@@ -740,6 +747,7 @@ export function useFormFields(
initialValues,
baseUrlOptions,
hideWhenInstanceExists,
+ urlHint,
});
const formFields = useMemo(
diff --git a/web/src/pages/user-setting/setting-model/instance-card/provider-instance-card.tsx b/web/src/pages/user-setting/setting-model/instance-card/provider-instance-card.tsx
index 8fbab965ad..c1da77b43f 100644
--- a/web/src/pages/user-setting/setting-model/instance-card/provider-instance-card.tsx
+++ b/web/src/pages/user-setting/setting-model/instance-card/provider-instance-card.tsx
@@ -124,7 +124,7 @@ const GenericProviderInstanceCard = forwardRef<
isDraft ? providerName : '',
);
const hideWhenInstanceExists = useHideWhenInstanceExists(instanceNameSet);
- const { baseUrlOptions } = useProviderBaseUrlOptions(providerName);
+ const { baseUrlOptions, urlHint } = useProviderBaseUrlOptions(providerName);
const { instanceDetails } = useLazyInstanceDetails(
providerName,
instance.id,
@@ -146,6 +146,7 @@ const GenericProviderInstanceCard = forwardRef<
initialValues,
baseUrlOptions,
hideWhenInstanceExists,
+ urlHint,
);
useFormResetOnDetailsLoad(
formRef,
diff --git a/web/src/pages/user-setting/setting-model/provider-schema/constants.ts b/web/src/pages/user-setting/setting-model/provider-schema/constants.ts
index 2ea2f4e5b0..2c51665a47 100644
--- a/web/src/pages/user-setting/setting-model/provider-schema/constants.ts
+++ b/web/src/pages/user-setting/setting-model/provider-schema/constants.ts
@@ -73,3 +73,17 @@ export const LIST_MODEL_FIELD_NAMES = new Set<string>([
'max_tokens',
'is_tools',
]);
+
+/**
+ * Endpoint fields whose placeholder comes from the provider catalog.
+ *
+ * A provider that declares a display-only `url_hint` in `GET /providers`
+ * (see `conf/models/*.json`) shows that URL as the input placeholder
+ * instead of the generic i18n hint. The catalog wins so that the example
+ * URL lives next to the provider definition rather than in a locale file.
+ */
+export const URL_HINT_FIELD_NAMES = new Set<string>([
+ 'base_url',
+ 'mineru_apiserver',
+ 'paddleocr_api_url',
+]);
diff --git a/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.test.tsx b/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.test.tsx
new file mode 100644
index 0000000000..d4c2d00845
--- /dev/null
+++ b/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.test.tsx
@@ -0,0 +1,65 @@
+/*
+ * 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.
+ */
+
+import { renderHook } from '@testing-library/react';
+
+import { LLMFactory } from '@/constants/llm';
+
+import { useProviderFields } from './use-provider-fields';
+
+jest.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const renderFields = (urlHint?: string) =>
+ renderHook(() =>
+ useProviderFields({
+ llmFactory: LLMFactory.Ollama,
+ hideWhenInstanceExists: () => false,
+ urlHint,
+ }),
+ ).result.current.fields;
+
+const placeholderOf = (fields: unknown[], name: string) =>
+ (fields as { name: string; placeholder?: string }[]).find(
+ (field) => field.name === name,
+ )?.placeholder;
+
+describe('provider endpoint placeholder', () => {
+ it('shows the catalog url_hint instead of the generic hint', () => {
+ expect(
+ placeholderOf(
+ renderFields('http://host.docker.internal:11434'),
+ 'base_url',
+ ),
+ ).toBe('http://host.docker.internal:11434');
+ });
+
+ it('falls back to the i18n hint when the catalog has no url_hint', () => {
+ expect(placeholderOf(renderFields(), 'base_url')).toBe(
+ 'baseUrlNameMessage',
+ );
+ });
+
+ it('never leaks url_hint into other fields', () => {
+ expect(
+ placeholderOf(
+ renderFields('http://host.docker.internal:11434'),
+ 'api_key',
+ ),
+ ).toBe('apiKeyMessage');
+ });
+});
diff --git a/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.tsx b/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.tsx
index dff957a388..cf80abb7f3 100644
--- a/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.tsx
+++ b/web/src/pages/user-setting/setting-model/provider-schema/hooks/use-provider-fields.tsx
@@ -20,7 +20,11 @@ import { InputSelect } from '@/components/ui/input-select';
import { useTranslate } from '@/hooks/common-hooks';
import { useMemo } from 'react';
import { ControllerRenderProps, FieldValues } from 'react-hook-form';
-import { LIST_MODEL_FIELD_NAMES, LIST_MODEL_PROVIDERS } from '../constants';
+import {
+ LIST_MODEL_FIELD_NAMES,
+ LIST_MODEL_PROVIDERS,
+ URL_HINT_FIELD_NAMES,
+} from '../constants';
import { getProviderConfig } from '../field-config';
import type { FieldConfig, SelectOption } from '../types';
@@ -31,6 +35,10 @@ interface UseProviderFieldsParams {
initialValues?: Record<string, any>;
baseUrlOptions?: SelectOption[];
hideWhenInstanceExists: (values: Record<string, any>) => boolean;
+ // Display-only example endpoint from the provider catalog
+ // (`GET /providers` → `url_hint`), rendered as the endpoint field's
+ // placeholder. Never used as a form value.
+ urlHint?: string;
}
/**
@@ -94,6 +102,7 @@ export const useProviderFields = ({
initialValues,
baseUrlOptions,
hideWhenInstanceExists,
+ urlHint,
}: UseProviderFieldsParams) => {
const { t } = useTranslate('setting');
@@ -191,7 +200,10 @@ export const useProviderFields = ({
!hasModelNameField || !LIST_MODEL_FIELD_NAMES.has(field.name),
)
.map((field) => {
- const placeholderText = resolveText(field.placeholder, llmFactory, t);
+ const placeholderText =
+ urlHint && URL_HINT_FIELD_NAMES.has(field.name)
+ ? urlHint
+ : resolveText(field.placeholder, llmFactory, t);
const tooltipText = resolveText(field.tooltip, llmFactory, t);
const validation = field.validation
? {
@@ -273,6 +285,7 @@ export const useProviderFields = ({
llmFactory,
hasModelNameField,
viewMode,
+ urlHint,
]);
const defaultValues: FieldValues = useMemo(() => {