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
fix: retrieve with the assistant's configured settings (#19016)
Martin Civáň175742590388
diff --git a/api/db/services/dialog_service.py b/api/db/services/dialog_service.pyindex 17c77f4b58..ad1c8c5c13 100644--- a/api/db/services/dialog_service.py+++ b/api/db/services/dialog_service.py@@ -2029,6 +2029,11 @@ async def rag_agent(dialog, messages, stream=True, **kwargs):thinking_mode=thinking_mode,text_attachments_content=text_attachments_content,system_prompt=_render_reasoning_system_prompt(dialog, prompt_config, kwargs),+ similarity_threshold=dialog.similarity_threshold,+ vector_similarity_weight=dialog.vector_similarity_weight,+ top_n=dialog.top_n,+ rerank_candidates_count=dialog.rerank_candidates_count,+ top_k=dialog.top_k,)async def decorate_answer(answer):diff --git a/rag/advanced_rag/agentic_rag.py b/rag/advanced_rag/agentic_rag.pyindex 576b78df81..51e0bafeb2 100644--- a/rag/advanced_rag/agentic_rag.py+++ b/rag/advanced_rag/agentic_rag.py@@ -48,7 +48,7 @@ from common.token_utils import num_tokens_from_stringfrom rag.advanced_rag.agentic_rag_graph import _split_think_streamfrom rag.advanced_rag.harness.keywords import extract_weighted_keywordsfrom rag.advanced_rag.harness.stats import CountingChatModel, LLMUsageStats, in_phase, using_stats-from rag.advanced_rag.harness.tools.search import _compact_keywords+from rag.advanced_rag.harness.tools.search import _compact_keywords, _resolve_rerank_candidates, _resolve_top_k, _settingfrom rag.app.tag import label_questionfrom rag.llm.tool_decorator import toolfrom rag.prompts.generator import (@@ -235,8 +235,21 @@ class RAGTools:text_attachments_content: str = "",original_user_question: str = "",system_prompt: str = "",+ similarity_threshold: float | None = None,+ vector_similarity_weight: float | None = None,+ top_n: int | None = None,+ rerank_candidates_count: int | None = None,+ top_k: int | None = None,):self.tenant_ids = tenant_ids+ # Retrieval settings from the caller (a chat assistant's dialog row, an+ # agent's Retrieval component). The search tools fall back to their own+ # defaults on None, so an unconfigured caller is unaffected.+ self.similarity_threshold = similarity_threshold+ self.vector_similarity_weight = vector_similarity_weight+ self.top_n = top_n+ self.rerank_candidates_count = rerank_candidates_count+ self.top_k = top_k# The user's ORIGINAL, complete question as received from the chat layer# (before the outer smart agent may have rewritten/compressed it). The# outer LLM's `rag(question=...)` argument is model-generated and@@ -582,8 +595,8 @@ class RAGTools:question: str,keywords: str | list = "",doc_scope: list[str] | None = None,- top_n: int = 6,- similarity_threshold: float = 0.2,+ top_n: int | None = None,+ similarity_threshold: float | None = None,using_embedding: bool = False,) -> dict[str, list]:"""Retrieve chunks from the unstructured KBs for one question.@@ -596,6 +609,12 @@ class RAGTools:return {"chunks": [], "doc_aggs": []}if isinstance(keywords, list):keywords = ",".join(keywords)+ # Explicit argument wins, then the caller's configuration, then this+ # method's own defaults, which differ from the search tools' on purpose.+ if top_n is None:+ top_n = int(_setting(self, "top_n", 6))+ if similarity_threshold is None:+ similarity_threshold = _setting(self, "similarity_threshold", 0.2)logging.info(f"@retrieve: {question}@{keywords}")doc_scope = self.scoped_doc_ids(doc_scope)@@ -622,7 +641,17 @@ class RAGTools:question = question + " " + search_termsembd_mdl = self.embed_mdl if using_embedding else None- vector_weight = 0.7 if embd_mdl else 0+ vector_weight = _setting(self, "vector_similarity_weight", 0.7) if embd_mdl else 0+ knn_top_k = _resolve_top_k(self)+ rerank_candidates_count = _resolve_rerank_candidates(self, top_n)+ logging.debug(+ "retrieve: top_n=%s threshold=%s vector_weight=%s knn_top_k=%s rerank_candidates_count=%s",+ top_n,+ similarity_threshold,+ vector_weight,+ knn_top_k,+ rerank_candidates_count,+ )kbinfos = await settings.retriever.retrieval(question,embd_mdl,@@ -632,10 +661,12 @@ class RAGTools:top_n,similarity_threshold,vector_similarity_weight=vector_weight,+ knn_top_k=knn_top_k,aggs=True,highlight=True,doc_ids=doc_scope,rank_feature=label_question(question, self.kbs),+ rerank_candidates_count=rerank_candidates_count,)if not kbinfos:return {"chunks": [], "doc_aggs": []}diff --git a/rag/advanced_rag/harness/tools/search.py b/rag/advanced_rag/harness/tools/search.pyindex 91e6302d9e..f001742cd3 100644--- a/rag/advanced_rag/harness/tools/search.py+++ b/rag/advanced_rag/harness/tools/search.py@@ -45,6 +45,42 @@ from rag.advanced_rag.harness.tools.text_processing import ( # noqa: F401)+# Fallbacks for callers that supply no retrieval configuration: the values the+# search tools used unconditionally before RAGTools carried settings.+_DEFAULT_SIMILARITY_THRESHOLD = 0.2+_DEFAULT_HYBRID_VECTOR_WEIGHT = 0.3+_DEFAULT_TOP_N = 12+_DEFAULT_RERANK_CANDIDATES = 64+_DEFAULT_TOP_K = 1024+++def _setting(tools, name: str, default):+ """Read a retrieval setting off ``tools``. ``None`` means unset; 0.0 is a valid value."""+ value = getattr(tools, name, None)+ return default if value is None else value+++def _resolve_top_n(tools, top_n: int | None) -> int:+ """Explicit argument wins, then the caller's configuration, then the default."""+ if top_n is not None:+ return top_n+ return int(_setting(tools, "top_n", _DEFAULT_TOP_N))+++def _resolve_top_k(tools) -> int:+ """Size of the approximate-kNN candidate pool (ES ``k``, ``num_candidates`` is 2x).++ Recall, not ranking: a vector outside the pool cannot be returned at any weight.+ """+ return int(_setting(tools, "top_k", _DEFAULT_TOP_K))+++def _resolve_rerank_candidates(tools, top_n: int) -> int:+ """``Dealer.retrieval`` rejects ``page * page_size > rerank_candidates_count``, so+ the candidate set can never be smaller than the page it has to fill."""+ return max(int(_setting(tools, "rerank_candidates_count", _DEFAULT_RERANK_CANDIDATES)), top_n)++def _search_cache_key(effective_query: str, target_ids, top_n: int, doc_scope) -> tuple:"""Key a retrieval by what actually determines its result.@@ -75,8 +111,9 @@ def _normalize(kbinfos: dict, tenant_ids: list[str] | str | None) -> dict:async def hybrid_search(- tools, query: str, kb_ids: list[str] | None = None, top_n: int = 12, doc_scope: list[str] | None = None, keywords: str = "", retrieval_query: str = "", use_compiled: bool = False+ tools, query: str, kb_ids: list[str] | None = None, top_n: int | None = None, doc_scope: list[str] | None = None, keywords: str = "", retrieval_query: str = "", use_compiled: bool = False) -> dict:+ top_n = _resolve_top_n(tools, top_n)target_ids = kb_ids or list(dict.fromkeys(tools.kb_ids + [kb.id for kb in tools.sql_kbs]))if not target_ids:return {"chunks": [], "doc_aggs": []}@@ -104,8 +141,20 @@ async def hybrid_search(return cachedembd_mdl = tools.embed_mdl- vector_weight = 0.3 if embd_mdl else 0-+ # No embedding model means no vector leg, whatever the caller asked for.+ vector_weight = _setting(tools, "vector_similarity_weight", _DEFAULT_HYBRID_VECTOR_WEIGHT) if embd_mdl else 0++ similarity_threshold = _setting(tools, "similarity_threshold", _DEFAULT_SIMILARITY_THRESHOLD)+ knn_top_k = _resolve_top_k(tools)+ rerank_candidates_count = _resolve_rerank_candidates(tools, top_n)+ _LOG.debug(+ "[Hybrid search] top_n=%s threshold=%s vector_weight=%s knn_top_k=%s rerank_candidates_count=%s",+ top_n,+ similarity_threshold,+ vector_weight,+ knn_top_k,+ rerank_candidates_count,+ )kbinfos = await settings.retriever.retrieval(effective_query,embd_mdl,@@ -113,12 +162,14 @@ async def hybrid_search(target_ids,1,top_n,- 0.2,+ similarity_threshold,vector_similarity_weight=vector_weight,+ knn_top_k=knn_top_k,aggs=True,highlight=False,doc_ids=doc_scope,must_not={"exists": "compile_kwd"}, # plain retrieval = document chunks only; compiled products have their own tools+ rerank_candidates_count=rerank_candidates_count,)kbinfos = _normalize(kbinfos, tools.tenant_ids)# Preserve the RAW retrieved chunks in the central memory store BEFORE any@@ -145,7 +196,8 @@ async def hybrid_search(return kbinfos-async def vector_search(tools, query: str, kb_ids: list[str] | None = None, top_n: int = 12, keywords: str = "", retrieval_query: str = "", doc_scope: list[str] | None = None) -> dict:+async def vector_search(tools, query: str, kb_ids: list[str] | None = None, top_n: int | None = None, keywords: str = "", retrieval_query: str = "", doc_scope: list[str] | None = None) -> dict:+ top_n = _resolve_top_n(tools, top_n)if not tools.embed_mdl:_LOG.warning("vector_search: no embed_mdl available")return {"chunks": [], "doc_aggs": []}@@ -155,6 +207,9 @@ async def vector_search(tools, query: str, kb_ids: list[str] | None = None, top_target_ids = kb_ids or tools.kb_idsif hasattr(tools, "scoped_doc_ids"):doc_scope = tools.scoped_doc_ids(doc_scope)+ knn_top_k = _resolve_top_k(tools)+ rerank_candidates_count = _resolve_rerank_candidates(tools, top_n)+ _LOG.debug("[Vector search] top_n=%s knn_top_k=%s rerank_candidates_count=%s", top_n, knn_top_k, rerank_candidates_count)kbinfos = await settings.retriever.retrieval(effective_query,tools.embed_mdl,@@ -162,12 +217,14 @@ async def vector_search(tools, query: str, kb_ids: list[str] | None = None, top_target_ids,1,top_n,- 0.2,- vector_similarity_weight=1.0,+ 0.2, # pure-cosine floor, not the caller's hybrid threshold+ vector_similarity_weight=1.0, # vector-only by definition of this tool+ knn_top_k=knn_top_k,aggs=False,highlight=False,doc_ids=doc_scope,must_not={"exists": "compile_kwd"},+ rerank_candidates_count=rerank_candidates_count,)kbinfos = _normalize(kbinfos, tools.tenant_ids)try:@@ -180,12 +237,16 @@ async def vector_search(tools, query: str, kb_ids: list[str] | None = None, top_return kbinfos-async def bm25_search(tools, query: str, kb_ids: list[str] | None = None, top_n: int = 12, keywords: str = "", retrieval_query: str = "", doc_scope: list[str] | None = None) -> dict:+async def bm25_search(tools, query: str, kb_ids: list[str] | None = None, top_n: int | None = None, keywords: str = "", retrieval_query: str = "", doc_scope: list[str] | None = None) -> dict:+ top_n = _resolve_top_n(tools, top_n)_LOG.info(f'[BM25 search] Searching by keyword for "{query}" (keywords: {keywords})')target_ids = kb_ids or tools.kb_idseffective_query = f"{query} {retrieval_query}".strip()[:400] if retrieval_query else f"{query} {keywords}".strip() if keywords else queryif hasattr(tools, "scoped_doc_ids"):doc_scope = tools.scoped_doc_ids(doc_scope)+ knn_top_k = _resolve_top_k(tools)+ rerank_candidates_count = _resolve_rerank_candidates(tools, top_n)+ _LOG.debug("[BM25 search] top_n=%s knn_top_k=%s rerank_candidates_count=%s", top_n, knn_top_k, rerank_candidates_count)kbinfos = await settings.retriever.retrieval(effective_query,None,@@ -193,12 +254,14 @@ async def bm25_search(tools, query: str, kb_ids: list[str] | None = None, top_n:target_ids,1,top_n,- 0.0,- vector_similarity_weight=0,+ 0.0, # BM25 scores are not comparable to a hybrid threshold+ vector_similarity_weight=0, # keyword-only by definition of this tool+ knn_top_k=knn_top_k,aggs=False,highlight=False,doc_ids=doc_scope,must_not={"exists": "compile_kwd"},+ rerank_candidates_count=rerank_candidates_count,)kbinfos = _normalize(kbinfos, tools.tenant_ids)try:diff --git a/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py b/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.pyindex 86a7c18dfb..734c90e0c2 100644--- a/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py+++ b/test/unit_test/api/db/services/test_dialog_service_rag_agent_messages.py@@ -79,6 +79,11 @@ _DIALOG = SimpleNamespace(llm_setting={"temperature": 0.1},prompt_config={"reasoning": 1},meta_data_filter=None,+ similarity_threshold=0.2,+ vector_similarity_weight=0.3,+ top_n=6,+ rerank_candidates_count=64,+ top_k=1024,)_KB = SimpleNamespace(id="kb-1", tenant_id="tenant-1")diff --git a/test/unit_test/rag/advanced_rag/test_ragtools_retrieval_settings.py b/test/unit_test/rag/advanced_rag/test_ragtools_retrieval_settings.pynew file mode 100644index 0000000000..149d6f9256--- /dev/null+++ b/test/unit_test/rag/advanced_rag/test_ragtools_retrieval_settings.py@@ -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.+#+"""RAGTools carries the caller's retrieval settings through to the search tools."""++import pytest++from rag.advanced_rag.agentic_rag import RAGTools++pytestmark = pytest.mark.p1+++class FakeChatModel:+ max_length = 8192++ def clone(self):+ return self+++def test_settings_default_to_unset():+ """None, not a value: the search tools own the fallbacks."""+ tools = RAGTools([], FakeChatModel())++ assert tools.similarity_threshold is None+ assert tools.vector_similarity_weight is None+ assert tools.top_n is None+ assert tools.rerank_candidates_count is None+ assert tools.top_k is None+++def test_settings_are_carried_through():+ tools = RAGTools(+ [],+ FakeChatModel(),+ similarity_threshold=0.2,+ vector_similarity_weight=0.8,+ top_n=12,+ rerank_candidates_count=64,+ top_k=4096,+ )++ assert tools.similarity_threshold == 0.2+ assert tools.vector_similarity_weight == 0.8+ assert tools.top_n == 12+ assert tools.rerank_candidates_count == 64+ assert tools.top_k == 4096+++def test_zero_is_carried_through_not_treated_as_unset():+ tools = RAGTools([], FakeChatModel(), vector_similarity_weight=0.0, similarity_threshold=0.0)++ assert tools.vector_similarity_weight == 0.0+ assert tools.similarity_threshold == 0.0diff --git a/test/unit_test/rag/advanced_rag/test_search_retrieval_settings.py b/test/unit_test/rag/advanced_rag/test_search_retrieval_settings.pynew file mode 100644index 0000000000..da55e6703d--- /dev/null+++ b/test/unit_test/rag/advanced_rag/test_search_retrieval_settings.py@@ -0,0 +1,217 @@+#+# 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.+#+"""+The agentic search tools must retrieve with the caller's retrieval settings.++`hybrid_search` hardcoded `vector_similarity_weight=0.3`, `similarity_threshold=0.2`+and `top_n=12`, so a chat assistant's own tuning had no effect on any query the+agentic path made. The classic (non-agentic) chat path always honoured these+fields; the agentic search framework (#16859) reimplemented retrieval without them.++`vector_search` and `bm25_search` keep their own weights and thresholds: those are+what those tools mean, not a default standing in for configuration.+"""++import pytest++from rag.advanced_rag.harness.tools import search as search_tools++pytestmark = pytest.mark.p1+++class _Tools:+ """Minimal stand-in for RAGTools, carrying only what the search tools read."""++ def __init__(self, **settings):+ self.kb_ids = ["kb-1"]+ self.sql_kbs = []+ self.tenant_ids = ["t-1"]+ self.embed_mdl = object()+ self.search_cache = None+ for name, value in settings.items():+ setattr(self, name, value)+++class _Recorder:+ """Captures the arguments of the single retrieval call a search tool makes."""++ def __init__(self):+ self.args = None+ self.kwargs = None++ async def retrieval(self, *args, **kwargs):+ self.args, self.kwargs = args, kwargs+ return {"chunks": [], "doc_aggs": []}++ @staticmethod+ def retrieval_by_children(chunks, _tenant_ids):+ return chunks+++def recorder(monkeypatch):+ rec = _Recorder()+ monkeypatch.setattr(search_tools.settings, "retriever", rec)+ monkeypatch.setattr(search_tools, "_normalize", lambda kbinfos, tenant_ids: kbinfos)+ return rec+++def _top_k(rec):+ return rec.kwargs.get("knn_top_k")+++def _call(rec):+ """(page_size, similarity_threshold, vector_similarity_weight, rerank_candidates_count)."""+ return (+ rec.args[5],+ rec.args[6],+ rec.kwargs["vector_similarity_weight"],+ rec.kwargs.get("rerank_candidates_count"),+ )+++async def test_hybrid_search_uses_the_configured_settings(recorder):+ tools = _Tools(vector_similarity_weight=0.8, similarity_threshold=0.35, top_n=20, rerank_candidates_count=256, top_k=4096)++ await search_tools.hybrid_search(tools, query="q")++ assert _call(recorder) == (20, 0.35, 0.8, 256)+ assert _top_k(recorder) == 4096+++async def test_hybrid_search_falls_back_when_nothing_is_configured(recorder):+ """An unconfigured caller must behave exactly as before this change."""+ await search_tools.hybrid_search(_Tools(), query="q")++ assert _call(recorder) == (12, 0.2, 0.3, 64)+ assert _top_k(recorder) == 1024+++async def test_zero_weight_is_configuration_not_absence(recorder):+ """0.0 is a meaningful weight — it must not be mistaken for "unset"."""+ await search_tools.hybrid_search(_Tools(vector_similarity_weight=0.0, similarity_threshold=0.0), query="q")++ _, threshold, weight, _ = _call(recorder)+ assert weight == 0.0+ assert threshold == 0.0+++async def test_no_embedding_model_forces_the_vector_leg_off(recorder):+ """Whatever the caller configured, there is no vector leg without an embedder."""+ tools = _Tools(vector_similarity_weight=0.8)+ tools.embed_mdl = None++ await search_tools.hybrid_search(tools, query="q")++ assert _call(recorder)[2] == 0+++async def test_explicit_top_n_argument_beats_the_configuration(recorder):+ await search_tools.hybrid_search(_Tools(top_n=20), query="q", top_n=5)++ assert _call(recorder)[0] == 5+++async def test_rerank_candidates_is_never_smaller_than_the_page_it_must_fill(recorder):+ """Dealer.retrieval rejects page * page_size > rerank_candidates_count."""+ await search_tools.hybrid_search(_Tools(top_n=100, rerank_candidates_count=64), query="q")++ page_size, _, _, rerank_candidates = _call(recorder)+ assert page_size == 100+ assert rerank_candidates >= page_size+++async def test_vector_search_keeps_its_defining_weight(recorder):+ """Weight 1.0 is what this tool means, not a default standing in for configuration."""+ await search_tools.vector_search(_Tools(vector_similarity_weight=0.3, top_n=7), query="q")++ page_size, threshold, weight, _ = _call(recorder)+ assert (weight, threshold) == (1.0, 0.2)+ assert page_size == 7+++async def test_bm25_search_keeps_its_defining_weight(recorder):+ """Weight 0 is what this tool means, not a default standing in for configuration."""+ await search_tools.bm25_search(_Tools(vector_similarity_weight=0.8, top_n=7), query="q")++ page_size, threshold, weight, _ = _call(recorder)+ assert (weight, threshold) == (0, 0.0)+ assert page_size == 7+++async def test_top_k_reaches_every_search_tool(recorder):+ """The kNN candidate pool is recall for all three tools, not a hybrid-only knob."""+ for tool in (search_tools.hybrid_search, search_tools.vector_search, search_tools.bm25_search):+ await tool(_Tools(top_k=4096), query="q")+ assert _top_k(recorder) == 4096, tool.__name__+++async def test_ragtools_retrieve_honours_the_configuration(monkeypatch):+ """The naive fallback (`_naive_rag` -> `RAGTools.retrieve`) bypasses the search+ tools, so it has to resolve the same settings itself."""+ from rag.advanced_rag import agentic_rag++ rec = _Recorder()+ monkeypatch.setattr(agentic_rag.settings, "retriever", rec)+ monkeypatch.setattr(agentic_rag, "label_question", lambda _q, _kbs: None)++ tools = agentic_rag.RAGTools.__new__(agentic_rag.RAGTools)+ tools.kb_ids = ["kb-1"]+ tools.kbs = []+ tools.tenant_ids = ["t-1"]+ tools.embed_mdl = object()+ tools.doc_scope = None+ tools.similarity_threshold = 0.35+ tools.vector_similarity_weight = 0.8+ tools.top_n = 20+ tools.rerank_candidates_count = 256+ tools.top_k = 4096+ monkeypatch.setattr(type(tools), "scoped_doc_ids", lambda _self, scope: scope, raising=False)++ await tools.retrieve("q", using_embedding=True)++ assert rec.args[5] == 20+ assert rec.args[6] == 0.35+ assert rec.kwargs["vector_similarity_weight"] == 0.8+ assert rec.kwargs["knn_top_k"] == 4096+ assert rec.kwargs["rerank_candidates_count"] == 256+++async def test_ragtools_retrieve_keeps_its_own_defaults_when_unconfigured(monkeypatch):+ """Unconfigured callers keep this method's previous behaviour, which is not+ the same as the search tools' (top_n 6, vector weight 0.7)."""+ from rag.advanced_rag import agentic_rag++ rec = _Recorder()+ monkeypatch.setattr(agentic_rag.settings, "retriever", rec)+ monkeypatch.setattr(agentic_rag, "label_question", lambda _q, _kbs: None)++ tools = agentic_rag.RAGTools.__new__(agentic_rag.RAGTools)+ tools.kb_ids = ["kb-1"]+ tools.kbs = []+ tools.tenant_ids = ["t-1"]+ tools.embed_mdl = object()+ tools.doc_scope = None+ for name in ("similarity_threshold", "vector_similarity_weight", "top_n", "rerank_candidates_count", "top_k"):+ setattr(tools, name, None)+ monkeypatch.setattr(type(tools), "scoped_doc_ids", lambda _self, scope: scope, raising=False)++ await tools.retrieve("q", using_embedding=True)++ assert rec.args[5] == 6+ assert rec.args[6] == 0.2+ assert rec.kwargs["vector_similarity_weight"] == 0.7+ assert rec.kwargs["knn_top_k"] == 1024