Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: resolve embedding-model fallbacks from deployment env, never guess (backport of #2191) (#2192)

Edwin Jose92f31cb538fe
diff --git a/src/api/settings/helpers.py b/src/api/settings/helpers.py
index 938d0ef5b..c0c7b5440 100644
--- a/src/api/settings/helpers.py
+++ b/src/api/settings/helpers.py
@@ -62,14 +62,27 @@ def _default_llm_model(provider: str) -> str:
def _default_embedding_model(provider: str) -> str:
- """Return the default embedding model for a provider."""
- from config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL
+ """Return a fallback embedding model for `provider` on provider-removal
+ reshuffle, or "" if none can be assumed safe.
+
+ No provider gets a hardcoded model name here. A provider name like
+ "openai" or "watsonx" doesn't reliably tell you which models are
+ actually deployed — it's frequently an internal OpenAI/watsonx-
+ compatible gateway with a curated, deployment-specific model subset.
+ A hardcoded guess can silently select a model the gateway doesn't
+ serve, breaking every ingestion with no clear signal why (see
+ incident: hardcoded "text-embedding-3-small" was selected in an
+ environment whose gateway only served "text-embedding-3-large").
+
+ Instead, defer to whatever the deployment itself declared via
+ EMBEDDING_MODEL/EMBEDDING_PROVIDER (see
+ ``get_declared_default_embedding_model``). If the deployment hasn't
+ declared a default for this provider, return "" and force the admin
+ to pick a model the settings UI confirms is actually available.
+ """
+ from config.embedding_constants import get_declared_default_embedding_model
- return {
- "openai": OPENAI_DEFAULT_EMBEDDING_MODEL,
- "watsonx": "ibm/granite-embedding-278m-multilingual",
- "ollama": "nomic-embed-text",
- }.get(provider, "")
+ return get_declared_default_embedding_model(provider)
async def _affected_embedding_models(
diff --git a/src/config/embedding_constants.py b/src/config/embedding_constants.py
index 58219d6d8..99a229a70 100644
--- a/src/config/embedding_constants.py
+++ b/src/config/embedding_constants.py
@@ -1,4 +1,33 @@
"""Embedding model constants."""
+import os
+
OPENAI_DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small"
-OPENAI_EMBEDDING_MODEL_PREFIX = "text-embedding"
\ No newline at end of file
+OPENAI_EMBEDDING_MODEL_PREFIX = "text-embedding"
+
+
+def get_declared_default_embedding_model(provider: str) -> str:
+ """Return the deployment-declared default embedding model for `provider`.
+
+ Sourced directly from the EMBEDDING_MODEL / EMBEDDING_PROVIDER env vars
+ the deployment is expected to set (Helm values / operator ConfigMap) to
+ describe what this specific environment's embedding backend actually
+ serves. Read directly rather than through ConfigManager's env-override
+ path, which is skipped once the config has been manually edited — a
+ protection against clobbering a user's own choices that shouldn't also
+ block resolving a fallback when the user hasn't made one.
+
+ Returns "" when the deployment hasn't declared a default for this
+ provider. Callers MUST NOT substitute a hardcoded guess in that case —
+ "openai" (and any other provider name) can mean anything from the real
+ public API to an internal gateway with a curated model subset, so no
+ single hardcoded model name is safe across deployments. A hardcoded
+ guess here previously selected "text-embedding-3-small" in an
+ environment whose gateway only served "text-embedding-3-large",
+ silently failing every ingestion.
+ """
+ declared_provider = os.environ.get("EMBEDDING_PROVIDER", "")
+ declared_model = os.environ.get("EMBEDDING_MODEL", "")
+ if declared_provider == provider and declared_model:
+ return declared_model
+ return ""
diff --git a/src/services/langflow_file_service.py b/src/services/langflow_file_service.py
index 474ec11a4..4e821f50c 100644
--- a/src/services/langflow_file_service.py
+++ b/src/services/langflow_file_service.py
@@ -133,14 +133,16 @@ class LangflowFileService:
return
try:
- from config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL
+ from config.embedding_constants import get_declared_default_embedding_model
from config.settings import get_index_name, get_openrag_config
from utils.embedding_fields import ensure_embedding_field_exists
from utils.embeddings import create_index_body
config = get_openrag_config()
index_name = get_index_name()
- model_name = embedding_model or OPENAI_DEFAULT_EMBEDDING_MODEL
+ model_name = embedding_model or get_declared_default_embedding_model(
+ config.knowledge.embedding_provider
+ )
embedding_dimensions = await self._detect_embedding_dimensions(
model_name,
config.knowledge.embedding_provider,
diff --git a/src/services/search_service.py b/src/services/search_service.py
index 0f9585518..105cd697a 100644
--- a/src/services/search_service.py
+++ b/src/services/search_service.py
@@ -8,7 +8,7 @@ from typing import Any
from agentd.tool_decorator import tool
from auth_context import get_auth_context
-from config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL
+from config.embedding_constants import get_declared_default_embedding_model
from config.settings import clients, get_embedding_model, get_index_name, get_openrag_config
from utils.container_utils import transform_localhost_url
from utils.logging_config import get_logger
@@ -172,7 +172,13 @@ class SearchService:
# Strategy: Use provided model, or default to the configured embedding
# model. This assumes documents are embedded with that model by default.
# Future enhancement: Could auto-detect available models in corpus.
- embedding_model = embedding_model or get_embedding_model() or OPENAI_DEFAULT_EMBEDDING_MODEL
+ embedding_model = (
+ embedding_model
+ or get_embedding_model()
+ or get_declared_default_embedding_model(
+ get_openrag_config().knowledge.embedding_provider
+ )
+ )
embedding_field_name = get_embedding_field_name(embedding_model)
logger.info(
diff --git a/src/utils/embeddings.py b/src/utils/embeddings.py
index 01b6c5086..837c8df94 100644
--- a/src/utils/embeddings.py
+++ b/src/utils/embeddings.py
@@ -13,7 +13,7 @@ async def create_index_body(
Returns:
OpenSearch index body configuration
"""
- from config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL
+ from config.embedding_constants import get_declared_default_embedding_model
from config.settings import (
ACL_PRINCIPAL_LABELS_MAPPING,
OPENSEARCH_NUMBER_OF_REPLICAS,
@@ -22,10 +22,11 @@ async def create_index_body(
get_openrag_config,
)
+ config = get_openrag_config()
resolved_embedding_model = (
embedding_model
- or get_openrag_config().knowledge.embedding_model
- or OPENAI_DEFAULT_EMBEDDING_MODEL
+ or config.knowledge.embedding_model
+ or get_declared_default_embedding_model(config.knowledge.embedding_provider)
)
properties = {
diff --git a/tests/unit/test_settings_provider_removal_defaults.py b/tests/unit/test_settings_provider_removal_defaults.py
index eb58b321f..7bd4f36cb 100644
--- a/tests/unit/test_settings_provider_removal_defaults.py
+++ b/tests/unit/test_settings_provider_removal_defaults.py
@@ -22,7 +22,6 @@ from config.config_manager import (
ProvidersConfig,
WatsonXConfig,
)
-from config.embedding_constants import OPENAI_DEFAULT_EMBEDDING_MODEL
from config.model_constants import (
ANTHROPIC_DEFAULT_LANGUAGE_MODEL,
OPENAI_DEFAULT_LANGUAGE_MODEL,
@@ -100,8 +99,10 @@ class TestDefaultLlmModel:
class TestDefaultEmbeddingModel:
- def test_openai_returns_static_default(self):
- assert _default_embedding_model("openai") == OPENAI_DEFAULT_EMBEDDING_MODEL
+ def test_openai_returns_empty(self):
+ """ "openai" often means an internal OpenAI-compatible gateway with a
+ curated model set — never guess, force an explicit, validated pick."""
+ assert _default_embedding_model("openai") == ""
def test_ollama_returns_empty(self):
assert _default_embedding_model("ollama") == ""
@@ -112,6 +113,22 @@ class TestDefaultEmbeddingModel:
def test_unknown_provider_returns_empty(self):
assert _default_embedding_model("nonexistent") == ""
+ def test_uses_deployment_declared_default_when_set(self, monkeypatch):
+ """When the deployment declares EMBEDDING_MODEL/EMBEDDING_PROVIDER
+ (Helm values / operator ConfigMap), the fallback should use it
+ instead of returning empty — this is what lets a correctly
+ configured deployment self-heal after a provider removal."""
+ monkeypatch.setenv("EMBEDDING_PROVIDER", "openai")
+ monkeypatch.setenv("EMBEDDING_MODEL", "text-embedding-3-large")
+ assert _default_embedding_model("openai") == "text-embedding-3-large"
+
+ def test_ignores_declared_default_for_a_different_provider(self, monkeypatch):
+ """A declared default for "openai" must not leak into the fallback
+ for a provider it wasn't declared for."""
+ monkeypatch.setenv("EMBEDDING_PROVIDER", "openai")
+ monkeypatch.setenv("EMBEDDING_MODEL", "text-embedding-3-large")
+ assert _default_embedding_model("watsonx") == ""
+
# ---------------------------------------------------------------------------
# _first_configured_llm_provider
@@ -251,7 +268,9 @@ class TestProviderRemovalEmbeddingDefault:
config.knowledge.embedding_provider = fb
config.knowledge.embedding_model = _default_embedding_model(fb)
- def test_remove_ollama_falls_back_to_openai_embedding(self):
+ def test_remove_ollama_falls_back_to_openai_empty_embedding(self):
+ """OpenAI's embedding catalog isn't guessed — the admin must pick
+ one the settings UI confirms is actually available."""
config = _make_config(
openai=True,
ollama=True,
@@ -260,7 +279,7 @@ class TestProviderRemovalEmbeddingDefault:
)
self._simulate_embedding_removal(config, "ollama")
assert config.knowledge.embedding_provider == "openai"
- assert config.knowledge.embedding_model == OPENAI_DEFAULT_EMBEDDING_MODEL
+ assert config.knowledge.embedding_model == ""
def test_remove_openai_falls_back_to_watsonx_empty_embedding(self):
config = _make_config(
@@ -273,7 +292,8 @@ class TestProviderRemovalEmbeddingDefault:
assert config.knowledge.embedding_provider == "watsonx"
assert config.knowledge.embedding_model == ""
- def test_remove_watsonx_falls_back_to_openai_embedding(self):
+ def test_remove_watsonx_falls_back_to_openai_empty_embedding(self):
+ """Same as above: watsonx -> openai fallback must not guess a model."""
config = _make_config(
openai=True,
watsonx=True,
@@ -282,7 +302,7 @@ class TestProviderRemovalEmbeddingDefault:
)
self._simulate_embedding_removal(config, "watsonx")
assert config.knowledge.embedding_provider == "openai"
- assert config.knowledge.embedding_model == OPENAI_DEFAULT_EMBEDDING_MODEL
+ assert config.knowledge.embedding_model == ""
def test_no_change_if_different_provider_removed(self):
config = _make_config(