Skip to content

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

fix(agent): compare retrieval KBs by resolved embedding model, not raw embd_id (#19206)

Zhu Lei13458475c097
diff --git a/agent/tools/retrieval.py b/agent/tools/retrieval.py
index 190d8f5f81..1ab7a6522e 100644
--- a/agent/tools/retrieval.py
+++ b/agent/tools/retrieval.py
@@ -23,7 +23,7 @@ from agent.tools.base import ToolParamBase, ToolBase, ToolMeta
from common.constants import LLMType
from api.db.services.doc_metadata_service import DocMetadataService
from common.metadata_utils import apply_meta_data_filter
-from api.db.services.knowledgebase_service import KnowledgebaseService
+from api.db.services.knowledgebase_service import KnowledgebaseService, validate_dataset_embedding_models
from api.db.services.llm_service import LLMBundle
from api.db.services.memory_service import MemoryService
from api.db.joint_services import memory_message_service
@@ -34,6 +34,21 @@ from rag.app.tag import label_question
from rag.prompts.generator import cross_languages, kb_prompt, memory_prompt
+def _shared_embedding_id(records, mismatch_message: str):
+ """Return a stored embedding id when records share one resolved model.
+
+ Comparison uses ``validate_dataset_embedding_models`` so a tenant_model
+ UUID and a legacy ``model@instance@provider`` composite are compatible
+ when they refer to the same model. Empty or unresolved names stay
+ isolated. The returned value is an original stored ``embd_id`` (UUID or
+ composite) for ``resolve_model_config``, not a normalized base name.
+ """
+ err = validate_dataset_embedding_models(records)
+ if err:
+ raise Exception(mismatch_message)
+ return next((rec.embd_id for rec in records if rec.embd_id), None)
+
+
class RetrievalParam(ToolParamBase):
"""
Define the Retrieval component parameters.
@@ -132,13 +147,12 @@ class Retrieval(ToolBase, ABC):
if not kbs:
raise Exception("No dataset is selected.")
- embd_nms = list(set([kb.embd_id for kb in kbs]))
- assert len(embd_nms) == 1, "Knowledge bases use different embedding models."
+ embd_id = _shared_embedding_id(kbs, "Knowledge bases use different embedding models.")
embd_mdl = None
- if embd_nms:
+ if embd_id:
tenant_id = self._canvas.get_tenant_id()
- embd_model_config = resolve_model_config(tenant_id, LLMType.EMBEDDING, embd_nms[0])
+ embd_model_config = resolve_model_config(tenant_id, LLMType.EMBEDDING, embd_id)
embd_mdl = LLMBundle(tenant_id, embd_model_config)
rerank_mdl = None
@@ -259,8 +273,7 @@ class Retrieval(ToolBase, ABC):
if not memory_list:
raise Exception("No memory is selected.")
- embd_names = list({memory.embd_id for memory in memory_list})
- assert len(embd_names) == 1, "Memory use different embedding models."
+ _shared_embedding_id(memory_list, "Memory use different embedding models.")
vars = self.get_input_elements_from_text(query_text)
vars = {k: o["value"] for k, o in vars.items()}
diff --git a/test/unit_test/agent/test_variable_ref_pattern_unit.py b/test/unit_test/agent/test_variable_ref_pattern_unit.py
index 9856c0837d..78cabe2851 100644
--- a/test/unit_test/agent/test_variable_ref_pattern_unit.py
+++ b/test/unit_test/agent/test_variable_ref_pattern_unit.py
@@ -148,7 +148,11 @@ def retrieval_module(monkeypatch, base_module):
install_module("api.db.services", package=True)
install_module("api.db.joint_services", package=True)
install_module("api.db.services.doc_metadata_service", DocMetadataService=type("DocMetadataService", (), {}))
- install_module("api.db.services.knowledgebase_service", KnowledgebaseService=type("KnowledgebaseService", (), {}))
+ install_module(
+ "api.db.services.knowledgebase_service",
+ KnowledgebaseService=type("KnowledgebaseService", (), {}),
+ validate_dataset_embedding_models=lambda _kbs: None,
+ )
install_module("api.db.services.llm_service", LLMBundle=type("LLMBundle", (), {}))
install_module("api.db.services.memory_service", MemoryService=type("MemoryService", (), {}))
install_module("api.db.joint_services.memory_message_service")
diff --git a/test/unit_test/agent/tools/test_retrieval_embedding_compat.py b/test/unit_test/agent/tools/test_retrieval_embedding_compat.py
new file mode 100644
index 0000000000..2a11211d89
--- /dev/null
+++ b/test/unit_test/agent/tools/test_retrieval_embedding_compat.py
@@ -0,0 +1,138 @@
+#
+# 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.
+#
+"""Regression tests for agent Retrieval KB/memory embedding compatibility.
+
+Datasets may store a tenant_model UUID or a ``model@instance@provider``
+composite in ``embd_id``. Chat/assistant selection treats those as compatible
+when they share a tenant_embd_id / base name. The Retrieval canvas component
+must use the same ``validate_dataset_embedding_models`` comparison rather than
+comparing raw ``embd_id`` strings.
+
+This test loads only the relevant function definitions via AST so it does not
+pull in the full ``api.db.db_models`` import chain.
+"""
+
+import ast
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+pytestmark = pytest.mark.p2
+
+_REPO_ROOT = Path(__file__).resolve().parents[4]
+_KB_SERVICE = _REPO_ROOT / "api" / "db" / "services" / "knowledgebase_service.py"
+_RETRIEVAL = _REPO_ROOT / "agent" / "tools" / "retrieval.py"
+
+TENANT_EMBD_ID = "aa6f9604a1d411f1a1fc65466754f1f9"
+COMPOSITE = "bge-m3:latest@Ollama local@Ollama"
+OTHER_COMPOSITE = "Qwen/Qwen3-Embedding-0.6B@1@SILICONFLOW"
+
+
+def _exec_functions(src_path, names, ns):
+ tree = ast.parse(src_path.read_text(encoding="utf-8"))
+ nodes = [node for node in tree.body if isinstance(node, ast.FunctionDef) and node.name in names]
+ missing = set(names) - {n.name for n in nodes}
+ assert not missing, f"missing functions in {src_path}: {missing}"
+ module = ast.Module(body=nodes, type_ignores=[])
+ exec(compile(module, str(src_path), "exec"), ns) # noqa: S102 - exec'ing AST-extracted functions from our own source file
+ return ns
+
+
+def _load_shared_embedding_id(resolved_names):
+ ns = {"get_composite_model_name_by_ids": lambda _ids: resolved_names}
+ _exec_functions(
+ _KB_SERVICE,
+ ("_base_model_name", "_kb_embedding_base_name", "validate_dataset_embedding_models"),
+ ns,
+ )
+ _exec_functions(_RETRIEVAL, ("_shared_embedding_id",), ns)
+ return ns["_shared_embedding_id"]
+
+
+def test_uuid_and_composite_with_same_tenant_embd_id_are_compatible():
+ check = _load_shared_embedding_id({TENANT_EMBD_ID: COMPOSITE})
+ kbs = [
+ SimpleNamespace(embd_id=TENANT_EMBD_ID, tenant_embd_id=TENANT_EMBD_ID),
+ SimpleNamespace(embd_id=COMPOSITE, tenant_embd_id=TENANT_EMBD_ID),
+ ]
+ embd_id = check(kbs, "Knowledge bases use different embedding models.")
+ assert embd_id in {TENANT_EMBD_ID, COMPOSITE}
+
+
+def test_uuid_and_composite_return_a_stored_model_id_not_a_base_name():
+ check = _load_shared_embedding_id({TENANT_EMBD_ID: COMPOSITE})
+ kbs = [
+ SimpleNamespace(embd_id=TENANT_EMBD_ID, tenant_embd_id=TENANT_EMBD_ID),
+ SimpleNamespace(embd_id=COMPOSITE, tenant_embd_id=TENANT_EMBD_ID),
+ ]
+ embd_id = check(kbs, "Knowledge bases use different embedding models.")
+ assert embd_id != "bge-m3:latest"
+ assert "@" in embd_id or embd_id == TENANT_EMBD_ID
+
+
+def test_different_embedding_models_still_fail():
+ check = _load_shared_embedding_id(
+ {
+ TENANT_EMBD_ID: COMPOSITE,
+ "b346fecb098e4305b58926f1bae6bbc9": OTHER_COMPOSITE,
+ }
+ )
+ kbs = [
+ SimpleNamespace(embd_id=TENANT_EMBD_ID, tenant_embd_id=TENANT_EMBD_ID),
+ SimpleNamespace(embd_id="b346fecb098e4305b58926f1bae6bbc9", tenant_embd_id="b346fecb098e4305b58926f1bae6bbc9"),
+ ]
+ with pytest.raises(Exception, match="Knowledge bases use different embedding models"):
+ check(kbs, "Knowledge bases use different embedding models.")
+
+
+def test_unresolved_uuid_does_not_match_a_different_composite():
+ check = _load_shared_embedding_id({})
+ kbs = [
+ SimpleNamespace(embd_id=TENANT_EMBD_ID, tenant_embd_id=TENANT_EMBD_ID),
+ SimpleNamespace(embd_id=COMPOSITE, tenant_embd_id=None),
+ ]
+ with pytest.raises(Exception, match="Knowledge bases use different embedding models"):
+ check(kbs, "Knowledge bases use different embedding models.")
+
+
+def test_empty_names_do_not_make_different_models_compatible():
+ check = _load_shared_embedding_id({})
+ kbs = [
+ SimpleNamespace(embd_id=COMPOSITE, tenant_embd_id=None),
+ SimpleNamespace(embd_id="", tenant_embd_id=None),
+ ]
+ with pytest.raises(Exception, match="Knowledge bases use different embedding models"):
+ check(kbs, "Knowledge bases use different embedding models.")
+
+
+def test_memory_uuid_and_composite_with_same_tenant_embd_id_are_compatible():
+ check = _load_shared_embedding_id({TENANT_EMBD_ID: COMPOSITE})
+ memories = [
+ SimpleNamespace(embd_id=TENANT_EMBD_ID, tenant_embd_id=TENANT_EMBD_ID),
+ SimpleNamespace(embd_id=COMPOSITE, tenant_embd_id=TENANT_EMBD_ID),
+ ]
+ assert check(memories, "Memory use different embedding models.") in {TENANT_EMBD_ID, COMPOSITE}
+
+
+def test_memory_different_embedding_models_still_fail():
+ check = _load_shared_embedding_id({})
+ memories = [
+ SimpleNamespace(embd_id=COMPOSITE, tenant_embd_id=None),
+ SimpleNamespace(embd_id=OTHER_COMPOSITE, tenant_embd_id=None),
+ ]
+ with pytest.raises(Exception, match="Memory use different embedding models"):
+ check(memories, "Memory use different embedding models.")