Skip to content

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

Fix: correct rerank #17296 - add prefetch_size (#18300)

Wang Qi5659476a3019
diff --git a/agent/tools/retrieval.py b/agent/tools/retrieval.py
index 813ee22030..bee162f3fb 100644
--- a/agent/tools/retrieval.py
+++ b/agent/tools/retrieval.py
@@ -58,6 +58,7 @@ class RetrievalParam(ToolParamBase):
self.similarity_threshold = 0.2
self.keywords_similarity_weight = 0.5
self.top_n = 8
+ self.prefetch_size = 64
self.top_k = 1024
self.dataset_ids = []
self.kb_ids = [] # Deprecated: keep for backward compatibility
@@ -207,6 +208,7 @@ class Retrieval(ToolBase, ABC):
aggs=True,
rerank_mdl=rerank_mdl,
rank_feature=label_question(query, kbs),
+ prefetch_size=self._param.prefetch_size,
)
if self.check_if_canceled("Retrieval processing"):
return
diff --git a/api/apps/restful_apis/bot_api.py b/api/apps/restful_apis/bot_api.py
index 16ef203b4e..4038877d19 100644
--- a/api/apps/restful_apis/bot_api.py
+++ b/api/apps/restful_apis/bot_api.py
@@ -349,6 +349,7 @@ async def retrieval_test_embedded(tenant_id=None):
vector_similarity_weight = float(req.get("vector_similarity_weight", 0.3))
use_kg = req.get("use_kg", False)
top = int(req.get("top_k", 1024))
+ prefetch_size = int(req.get("prefetch_size", 64))
if top <= 0:
return get_error_data_result("`top_k` must be greater than 0")
langs = req.get("cross_languages", [])
@@ -358,7 +359,7 @@ async def retrieval_test_embedded(tenant_id=None):
search_config = {}
async def _retrieval():
- nonlocal similarity_threshold, vector_similarity_weight, top, rerank_id
+ nonlocal similarity_threshold, vector_similarity_weight, top, rerank_id, prefetch_size
local_doc_ids = list(doc_ids) if doc_ids else []
tenant_ids = []
_question = question
@@ -387,6 +388,8 @@ async def retrieval_test_embedded(tenant_id=None):
top = int(search_config.get("top_k", top))
if not req.get("rerank_id"):
rerank_id = search_config.get("rerank_id", "")
+ if not req.get("prefetch_size"):
+ prefetch_size = int(search_config.get("prefetch_size", 100))
else:
meta_data_filter = req.get("meta_data_filter") or {}
if meta_data_filter.get("method") in ["auto", "semi_auto"]:
@@ -447,6 +450,7 @@ async def retrieval_test_embedded(tenant_id=None):
rerank_mdl=rerank_mdl,
highlight=req.get("highlight"),
rank_feature=labels,
+ prefetch_size=prefetch_size,
)
if use_kg:
default_chat_model = await thread_pool_exec(get_tenant_default_model_by_type, kb.tenant_id, LLMType.CHAT)
diff --git a/api/apps/restful_apis/chat_api.py b/api/apps/restful_apis/chat_api.py
index e3ba9cfd54..51306aa8b3 100644
--- a/api/apps/restful_apis/chat_api.py
+++ b/api/apps/restful_apis/chat_api.py
@@ -200,6 +200,7 @@ def _build_default_completion_dialog():
prompt_config=deepcopy(_DEFAULT_DIRECT_CHAT_PROMPT_CONFIG),
kb_ids=[],
top_n=6,
+ prefetch_size=64,
top_k=1024,
rerank_id="",
similarity_threshold=0.1,
@@ -461,6 +462,7 @@ async def create():
req.setdefault("llm_setting", {})
req.setdefault("description", "A helpful Assistant")
req.setdefault("top_n", 6)
+ req.setdefault("prefetch_size", 64)
req.setdefault("top_k", 1024)
req.setdefault("rerank_id", "")
req.setdefault("similarity_threshold", 0.1)
diff --git a/api/apps/services/dataset_api_service.py b/api/apps/services/dataset_api_service.py
index fdceb392c0..1ec150dc2c 100644
--- a/api/apps/services/dataset_api_service.py
+++ b/api/apps/services/dataset_api_service.py
@@ -1030,6 +1030,7 @@ async def search(dataset_id: str, tenant_id: str, req: dict):
page = int(req.get("page", 1))
size = int(req.get("size", 30))
+ prefetch_size = int(req.get("prefetch_size", 64))
question = req.get("question", "")
doc_ids = req.get("doc_ids", [])
use_kg = req.get("use_kg", False)
@@ -1065,6 +1066,7 @@ async def search(dataset_id: str, tenant_id: str, req: dict):
similarity_threshold = float(search_config.get("similarity_threshold", similarity_threshold))
vector_similarity_weight = float(search_config.get("vector_similarity_weight", vector_similarity_weight))
top = max(1, min(int(search_config.get("top_k", top)), 2048))
+ prefetch_size = int(search_config.get("prefetch_size", 100))
use_kg = search_config.get("use_kg", use_kg)
langs = search_config.get("cross_languages", langs)
logging.debug(
@@ -1144,6 +1146,7 @@ async def search(dataset_id: str, tenant_id: str, req: dict):
rerank_mdl=rerank_mdl,
rank_feature=labels,
trace_id=search_id,
+ prefetch_size=prefetch_size,
)
if use_kg:
@@ -1410,6 +1413,7 @@ async def search_datasets(tenant_id: str, req: dict):
kb_ids = req.get("dataset_ids", [])
page = int(req.get("page", 1))
size = int(req.get("size", 30))
+ prefetch_size = int(req.get("prefetch_size", 64))
question = req.get("question", "")
doc_ids = req.get("doc_ids", [])
use_kg = req.get("use_kg", False)
@@ -1457,6 +1461,7 @@ async def search_datasets(tenant_id: str, req: dict):
similarity_threshold = float(search_config.get("similarity_threshold", similarity_threshold))
vector_similarity_weight = float(search_config.get("vector_similarity_weight", vector_similarity_weight))
top = max(1, min(int(search_config.get("top_k", top)), 2048))
+ prefetch_size = int(search_config.get("prefetch_size", 100))
use_kg = search_config.get("use_kg", use_kg)
langs = search_config.get("cross_languages", langs)
logging.debug(
@@ -1541,6 +1546,7 @@ async def search_datasets(tenant_id: str, req: dict):
rank_feature=labels,
trace_id=search_id,
must_not=None if req.get("include_knowledge_compilation", True) else {"exists": "compile_kwd"},
+ prefetch_size=prefetch_size,
)
if use_kg:
diff --git a/api/db/db_models.py b/api/db/db_models.py
index cadcf1c7b5..e6cf7a00ea 100644
--- a/api/db/db_models.py
+++ b/api/db/db_models.py
@@ -1475,6 +1475,7 @@ class Dialog(DataBaseModel):
vector_similarity_weight = FloatField(default=0.3)
top_n = IntegerField(default=6)
+ prefetch_size = IntegerField(default=64)
top_k = IntegerField(default=1024)
@@ -2412,6 +2413,7 @@ def migrate_db():
alter_db_add_column(migrator, "document", "suffix", EmptyStringCharField(max_length=32, null=False, default="", help_text="The real file extension suffix", index=True))
alter_db_add_column(migrator, "api_4_conversation", "errors", TextField(null=True, help_text="errors"))
alter_db_add_column(migrator, "dialog", "meta_data_filter", JSONField(null=True, default={}))
+ alter_db_add_column(migrator, "dialog", "prefetch_size", IntegerField(default=64))
alter_db_column_type(migrator, "canvas_template", "title", JSONField(null=True, default=dict, help_text="Canvas title"))
alter_db_column_type(migrator, "canvas_template", "description", JSONField(null=True, default=dict, help_text="Canvas description"))
alter_db_add_column(migrator, "user_canvas", "canvas_category", CharField(max_length=32, null=False, default="agent_canvas", help_text="agent_canvas|dataflow_canvas", index=True))
diff --git a/api/db/services/dialog_service.py b/api/db/services/dialog_service.py
index 5058f155fa..d8d235356f 100644
--- a/api/db/services/dialog_service.py
+++ b/api/db/services/dialog_service.py
@@ -222,6 +222,7 @@ class DialogService(CommonService):
cls.model.similarity_threshold,
cls.model.vector_similarity_weight,
cls.model.top_n,
+ cls.model.prefetch_size,
cls.model.top_k,
cls.model.do_refer,
cls.model.rerank_id,
@@ -664,6 +665,7 @@ async def async_chat(dialog, messages, stream=True, **kwargs):
text_attachments_content, image_attachments, image_files = get_files_content(messages[-1], llm_model_config["model_type"])
prompt_config = dialog.prompt_config
+ prefetch_size = getattr(dialog, "prefetch_size", 64)
include_reference_metadata, metadata_fields = _resolve_reference_metadata(prompt_config, request_payload=kwargs)
field_map = KnowledgebaseService.get_field_map(dialog.kb_ids)
logging.debug(f"field_map retrieved: {field_map}")
@@ -737,6 +739,7 @@ async def async_chat(dialog, messages, stream=True, **kwargs):
similarity_threshold=0.2,
vector_similarity_weight=0.3,
doc_ids=scoped_doc_ids,
+ prefetch_size=prefetch_size,
),
internet_enabled=use_web_search,
)
@@ -776,6 +779,7 @@ async def async_chat(dialog, messages, stream=True, **kwargs):
aggs=True,
rerank_mdl=rerank_mdl,
rank_feature=label_question(" ".join(questions), kbs),
+ prefetch_size=prefetch_size,
)
if prompt_config.get("toc_enhance"):
cks = await retriever.retrieval_by_toc(" ".join(questions), kbinfos["chunks"], tenant_ids, chat_mdl, dialog.top_n)
@@ -1824,6 +1828,7 @@ async def async_ask(question, kb_ids, tenant_id, chat_llm_name=None, search_conf
rerank_mdl=rerank_mdl,
rank_feature=label_question(question, kbs),
trace_id=search_id,
+ prefetch_size=search_config.get("prefetch_size", 100),
)
if include_reference_metadata:
logging.debug(
@@ -1925,6 +1930,7 @@ async def gen_mindmap(question, kb_ids, tenant_id, search_config={}):
aggs=False,
rerank_mdl=rerank_mdl,
rank_feature=label_question(question, kbs),
+ prefetch_size=search_config.get("prefetch_size", 100),
)
mindmap = MindMapExtractor(chat_mdl)
mind_map = await mindmap([c["content_with_weight"] for c in ranks["chunks"]])
diff --git a/rag/nlp/search.py b/rag/nlp/search.py
index be34d5b6a7..6acf475247 100644
--- a/rag/nlp/search.py
+++ b/rag/nlp/search.py
@@ -16,7 +16,6 @@
import json
import logging
import re
-import math
from collections import OrderedDict, defaultdict
from dataclasses import dataclass
@@ -552,42 +551,17 @@ class Dealer:
def hybrid_similarity(self, ans_embd, ins_embd, ans, inst):
return self.qryr.hybrid_similarity(ans_embd, ins_embd, rag_tokenizer.tokenize(ans).split(), rag_tokenizer.tokenize(inst).split())
- @staticmethod
- def _rerank_window(page_size: int, top: int = 0) -> int:
- """Candidate-window size shared by retrieval's block fetch and slice.
-
- ``retrieval`` reuses this value BOTH as the backend block size and as
- the modulus for extracting a single page from a (re)ranked block::
-
- req["page"] = global_offset // window # which block to fetch
- begin = global_offset % window # where the page starts
-
- For those two to agree the window MUST be an exact multiple of
- ``page_size``; otherwise blocks and pages drift apart and deep
- pagination silently drops results and returns short pages.
-
- The window targets a provider-friendly pool of ~64 candidates, bounded
- by ``top`` when given (i.e. when an external reranker is active), and is
- always rounded UP to a whole number of pages to preserve the invariant.
- """
- if page_size <= 1:
- return min(30, top) if top > 0 else 30
- window = math.ceil(64 / page_size) * page_size
- if top > 0:
- window = min(window, math.ceil(top / page_size) * page_size)
- return window
-
async def retrieval(
self,
question,
embd_mdl,
tenant_ids,
kb_ids,
- page,
- page_size,
+ page, # MUST be 1 when rerank_mdl is specified
+ page_size, # it is topn when rerank_mdl is specified
similarity_threshold=0.2,
vector_similarity_weight=0.3,
- top=1024,
+ top=1024, # for knn, no need to let user pass in.
doc_ids=None,
aggs=True,
rerank_mdl=None,
@@ -595,24 +569,34 @@ class Dealer:
rank_feature: dict | None = {PAGERANK_FLD: 10},
trace_id=None,
must_not: dict | None = None,
+ prefetch_size=64,
):
+ """
+ Pagination is neither efficient nor reliable for this retrieval when rerank is enabled because the system must:
+ - Prefetch more records than the requested page_size.
+ - Rerank those records to calculate similarity scores.
+ - Filter out records below than the similarity threshold.
+ When requesting page 2, the system must still process all candidates needed for page 1,
+ resulting in a significant waste of time and computational resources. (without cache)
+ Moreover, when prefetch_size expands into the next retrieval window, new records are added to the candidate set and the entire set is reranked.
+ That meant the previous returned pages might not be the same as the current returned pages, which is not acceptable for pagination.
+ """
ranks = {"total": 0, "chunks": [], "doc_aggs": {}}
if not question:
return ranks
- # Candidate window for block-based pagination. It MUST stay a multiple
- # of page_size so the block fetched (global_offset // RERANK_LIMIT) and
- # the in-block page slice (global_offset % RERANK_LIMIT) stay aligned;
- # see _rerank_window. When an external reranker is active the pool is
- # also bounded by top.
- RERANK_LIMIT = self._rerank_window(page_size, top if rerank_mdl else 0)
page = max(page, 1)
- global_offset = (page - 1) * page_size
+ if page * page_size > prefetch_size:
+ raise Exception(f"prefetch_size({prefetch_size}) must be greater than page * page_size({page * page_size}) to ensure correct pagination.")
+ if rerank_mdl is not None and page != 1:
+ raise Exception(f"Pagination is not supported when rerank_mdl is specified. Please set page=1 to retrieve the top {page_size} results.")
+
+ prefetch_page = 1
req = {
"kb_ids": kb_ids,
"doc_ids": doc_ids,
- "page": global_offset // RERANK_LIMIT + 1,
- "size": RERANK_LIMIT,
+ "page": prefetch_page,
+ "size": prefetch_size,
"question": question,
"vector": True,
"topk": top,
@@ -622,7 +606,7 @@ class Dealer:
}
if isinstance(must_not, dict) and must_not:
req["must_not"] = must_not
- logging.debug(f"[Search] global_offset={global_offset}, rerank_limit={RERANK_LIMIT}, page_size={page_size}, page={page}")
+ logging.info(f"[Search] page={page}, page_size={page_size}, prefetch_size={prefetch_size}")
if isinstance(tenant_ids, str):
tenant_ids = tenant_ids.split(",")
@@ -716,7 +700,7 @@ class Dealer:
ranks["doc_aggs"] = []
return ranks
- begin = global_offset % RERANK_LIMIT
+ begin = (page - 1) * page_size
end = begin + page_size
page_idx = valid_idx[begin:end]
diff --git a/test/unit_test/api/db/services/test_gaussdb_dialog_sql.py b/test/unit_test/api/db/services/test_gaussdb_dialog_sql.py
index d8a51608d9..e510d36430 100644
--- a/test/unit_test/api/db/services/test_gaussdb_dialog_sql.py
+++ b/test/unit_test/api/db/services/test_gaussdb_dialog_sql.py
@@ -1696,6 +1696,7 @@ def test_tc_sql_1001_use_sql_none_falls_back_to_retrieval(
aggs=True,
rerank_mdl=None,
rank_feature=None,
+ prefetch_size=64,
)
assert results[-1]["answer"] == "fallback answer"
assert results[-1]["reference"] == _expected_fallback_reference(kb_id)
@@ -1744,6 +1745,7 @@ def test_tc_sql_1002_validator_rejection_falls_back_to_retrieval(
aggs=True,
rerank_mdl=None,
rank_feature=None,
+ prefetch_size=64,
)
assert results[-1]["answer"] == "fallback answer"
assert results[-1]["reference"] == _expected_fallback_reference(kb_id)
@@ -1794,6 +1796,7 @@ def test_tc_sql_1003_sql_timeout_falls_back_to_retrieval(
aggs=True,
rerank_mdl=None,
rank_feature=None,
+ prefetch_size=64,
)
assert results[-1]["answer"] == "fallback answer"
assert results[-1]["reference"] == _expected_fallback_reference(kb_id)
diff --git a/test/unit_test/rag/test_search_pagination.py b/test/unit_test/rag/test_search_pagination.py
index 5427b05777..230eb58534 100644
--- a/test/unit_test/rag/test_search_pagination.py
+++ b/test/unit_test/rag/test_search_pagination.py
@@ -13,17 +13,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-"""Unit tests for the block-based pagination window used by Dealer.retrieval.
+"""Unit tests for prefetch-based pagination in Dealer.retrieval."""
-retrieval reuses RERANK_LIMIT both as the backend block size
-(req["page"] = global_offset // RERANK_LIMIT) and as the modulus for slicing a
-page out of a (re)ranked block (begin = global_offset % RERANK_LIMIT). If the
-window is not an exact multiple of page_size, blocks and pages drift apart, so
-deep pages silently drop results and come back short. These tests pin that
-invariant and verify cross-block pagination loses nothing.
-"""
-
-import math
import sys
import types
@@ -39,93 +30,92 @@ class _DummyFulltextQueryer:
_fake_query.FulltextQueryer = _DummyFulltextQueryer
+_fake_tokenizer = types.ModuleType("rag.nlp.rag_tokenizer")
sys.modules.setdefault("rag.nlp.query", _fake_query)
+sys.modules.setdefault("rag.nlp.rag_tokenizer", _fake_tokenizer)
sys.modules.setdefault("common.settings", types.ModuleType("common.settings"))
-from rag.nlp.search import Dealer # noqa: E402
-
-_rerank_window = Dealer._rerank_window
-
-# (page_size, top) combinations, including the common page sizes (10, 30) that
-# do NOT divide 64 -- the exact case the old `min(..., 64)` clamp broke -- plus
-# tiny / large / page-aligned tops.
-GRID = [(page_size, top) for page_size in (1, 5, 7, 10, 30, 50, 64) for top in (0, 5, 30, 50, 55, 64, 100, 1024)]
-
-
-def _paginate(total, page_size, top, rerank):
- """Replay retrieval's block-fetch + in-block slice over `total` candidates.
-
- Returns the concatenated global positions actually surfaced across every
- page, exactly as Dealer.retrieval would emit them.
- """
- window = _rerank_window(page_size, top if rerank else 0)
- # The backend caps the candidate pool at `top` when an external reranker is
- # active; otherwise the whole result set is windowed.
- cap = min(total, top) if (rerank and top > 0) else total
- surfaced = []
- page = 1
- while (page - 1) * page_size < cap:
- global_offset = (page - 1) * page_size
- block_index = global_offset // window
- block_start = block_index * window
- block = list(range(block_start, min(block_start + window, cap)))
- begin = global_offset % window
- surfaced.extend(block[begin : begin + page_size])
- page += 1
- return window, cap, surfaced
-
-
[email protected]("page_size,top", GRID)
-def test_window_is_page_aligned(page_size, top):
- """The window must be a positive whole multiple of page_size."""
- for rerank in (False, True):
- window = _rerank_window(page_size, top if rerank else 0)
- assert window >= 1
- if page_size > 1:
- assert window % page_size == 0, (page_size, top, rerank, window)
-
-
[email protected]("page_size,top", GRID)
-def test_pagination_loses_nothing(page_size, top):
- """Walking every page reconstructs the candidate pool exactly: in order,
- no gaps, no duplicates, and no short interior pages."""
- total = 250
- for rerank in (False, True):
- window, cap, surfaced = _paginate(total, page_size, top, rerank)
- assert surfaced == list(range(cap)), (
- f"page_size={page_size} top={top} rerank={rerank} window={window} cap={cap}: missing={sorted(set(range(cap)) - set(surfaced))[:10]} dups={len(surfaced) != len(set(surfaced))}"
+from rag.nlp.search import Dealer, settings # noqa: E402
+
+
+def _search_result(total):
+ ids = [f"chunk-{i}" for i in range(total)]
+ fields = {
+ chunk_id: {
+ "_score": 1.0,
+ "content_ltks": chunk_id,
+ "content_with_weight": chunk_id,
+ "doc_id": "doc-1",
+ "docnm_kwd": "doc",
+ "kb_id": "kb-1",
+ }
+ for chunk_id in ids
+ }
+ return Dealer.SearchResult(total=total, ids=ids, query_vector=[0.1], field=fields, highlight={})
+
+
[email protected](("page", "page_size", "prefetch_size"), [(1, 10, 64), (6, 10, 64), (7, 10, 70)])
+async def test_retrieval_prefetches_once_and_slices_requested_page(monkeypatch, page, page_size, prefetch_size):
+ requests = []
+
+ async def fake_search(self, req, *args, **kwargs):
+ requests.append(req)
+ return _search_result(prefetch_size)
+
+ async def keep_all_chunks(self, search_result):
+ return search_result
+
+ monkeypatch.setattr(Dealer, "search", fake_search)
+ monkeypatch.setattr(Dealer, "_prune_deleted_chunks", keep_all_chunks)
+ monkeypatch.setattr(settings, "DOC_ENGINE_INFINITY", True, raising=False)
+ monkeypatch.setattr(settings, "DOC_ENGINE_OCEANBASE", False, raising=False)
+ monkeypatch.setattr(settings, "DOC_ENGINE_SERENEDB", False, raising=False)
+ monkeypatch.setattr(settings, "DOC_ENGINE_GAUSSDB", False, raising=False)
+
+ ranks = await Dealer.__new__(Dealer).retrieval(
+ question="question",
+ embd_mdl=object(),
+ tenant_ids=["tenant-1"],
+ kb_ids=["kb-1"],
+ page=page,
+ page_size=page_size,
+ similarity_threshold=0.0,
+ aggs=False,
+ prefetch_size=prefetch_size,
+ )
+
+ assert len(requests) == 1
+ assert requests[0]["page"] == 1
+ assert requests[0]["size"] == prefetch_size
+ begin = (page - 1) * page_size
+ assert [chunk["chunk_id"] for chunk in ranks["chunks"]] == [f"chunk-{i}" for i in range(begin, begin + page_size)]
+
+
+async def test_retrieval_rejects_page_beyond_prefetch_size():
+ with pytest.raises(Exception, match=r"prefetch_size\(64\) must be greater than page \* page_size\(70\)"):
+ await Dealer.__new__(Dealer).retrieval(
+ question="question",
+ embd_mdl=object(),
+ tenant_ids=["tenant-1"],
+ kb_ids=["kb-1"],
+ page=7,
+ page_size=10,
+ prefetch_size=64,
)
-def test_reported_regression_page7_not_short():
- """The reported case: page_size=10, top=1024, reranker on. Page 7 (global
- offset 60) used to return only 4 of 10 results because the window was
- clamped to 64 (not a multiple of 10)."""
- page_size, top = 10, 1024
- window = _rerank_window(page_size, top)
- assert window % page_size == 0
- assert window >= 64 # still a provider-friendly ~64 candidate pool
-
- total = 250
- _, cap, surfaced = _paginate(total, page_size, top, rerank=True)
- # Page 7 spans global positions 60..69 and must be full and contiguous.
- assert surfaced[60:70] == list(range(60, 70))
- assert len(surfaced) == cap
-
-
-def test_matches_legacy_window_on_non_buggy_paths():
- """Where the old formula already produced a page-aligned value, the new
- window is unchanged (no behavioral regression on the non-buggy paths)."""
-
- def legacy(page_size, top, rerank):
- limit = math.ceil(64 / page_size) * page_size if page_size > 1 else 1
- limit = max(30, limit)
- if rerank and top > 0:
- limit = min(limit, top, 64)
- return limit
-
- for page_size in (1, 5, 7, 10, 30, 50, 64):
- # The non-rerank path was always page-aligned already -> must match.
- assert _rerank_window(page_size, 0) == legacy(page_size, 0, False)
+async def test_retrieval_rejects_pagination_with_reranker():
+ with pytest.raises(Exception, match="Pagination is not supported when rerank_mdl is specified"):
+ await Dealer.__new__(Dealer).retrieval(
+ question="question",
+ embd_mdl=object(),
+ tenant_ids=["tenant-1"],
+ kb_ids=["kb-1"],
+ page=2,
+ page_size=10,
+ rerank_mdl=object(),
+ prefetch_size=64,
+ )
diff --git a/web/src/components/prefetch-size-item.tsx b/web/src/components/prefetch-size-item.tsx
new file mode 100644
index 0000000000..b991c51882
--- /dev/null
+++ b/web/src/components/prefetch-size-item.tsx
@@ -0,0 +1,48 @@
+/*
+ * 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 { FormLayout } from '@/constants/form';
+import { useTranslation } from 'react-i18next';
+import { z } from 'zod';
+import { SliderInputFormField } from './slider-input-form-field';
+
+export const prefetchSizeSchema = {
+ prefetch_size: z.number().int().min(64).max(256),
+};
+
+interface PrefetchSizeFormFieldProps {
+ defaultValue?: number;
+ name?: string;
+}
+
+export function PrefetchSizeFormField({
+ defaultValue = 64,
+ name = 'prefetch_size',
+}: PrefetchSizeFormFieldProps) {
+ const { t } = useTranslation();
+
+ return (
+ <SliderInputFormField
+ name={name}
+ label={t('chat.prefetchSize')}
+ tooltip={t('chat.prefetchSizeTip')}
+ min={64}
+ max={256}
+ defaultValue={defaultValue}
+ layout={FormLayout.Vertical}
+ ></SliderInputFormField>
+ );
+}
diff --git a/web/src/components/top-select.tsx b/web/src/components/top-select.tsx
index 0276a16ce0..3b017f1006 100644
--- a/web/src/components/top-select.tsx
+++ b/web/src/components/top-select.tsx
@@ -16,24 +16,28 @@
import { forwardRef, useMemo } from 'react';
import { useTranslation } from 'react-i18next';
+import { FormLayout } from '@/constants/form';
import { SelectWithSearch } from './originui/select-with-search';
-import { RAGFlowFormItem } from './ragflow-form';
+import { SliderInputFormField } from './slider-input-form-field';
type TopSelectProps = {
+ max?: number;
value?: number;
onChange?(value: number): void;
};
export const TopSelect = forwardRef<HTMLButtonElement, TopSelectProps>(
- function TopSelect({ value = 10, onChange }, ref) {
+ function TopSelect({ max = 100, value = 10, onChange }, ref) {
const { t } = useTranslation();
const sizeChangerOptions = useMemo(() => {
- return [10, 20, 50, 100].map((x) => ({
- label: <span>{t('common.top', { top: x })}</span>,
- value: x.toString(),
- }));
- }, [t]);
+ return [10, 20, 50, 100]
+ .filter((x) => x <= max)
+ .map((x) => ({
+ label: <span>{t('common.top', { top: x })}</span>,
+ value: x.toString(),
+ }));
+ }, [max, t]);
return (
<SelectWithSearch
@@ -50,8 +54,12 @@ export function TopSelectFormItem() {
const { t } = useTranslation();
return (
- <RAGFlowFormItem label={t('knowledgeConfiguration.top')} name="size">
- <TopSelect></TopSelect>
- </RAGFlowFormItem>
+ <SliderInputFormField
+ name="size"
+ label={t('chat.topN')}
+ min={1}
+ max={100}
+ layout={FormLayout.Vertical}
+ ></SliderInputFormField>
);
}
diff --git a/web/src/interfaces/database/agent.ts b/web/src/interfaces/database/agent.ts
index 21011904fb..7a690d9dce 100644
--- a/web/src/interfaces/database/agent.ts
+++ b/web/src/interfaces/database/agent.ts
@@ -165,6 +165,7 @@ export interface IRetrievalForm {
similarity_threshold?: number;
keywords_similarity_weight?: number;
top_n?: number;
+ prefetch_size?: number;
top_k?: number;
rerank_id?: string;
tenant_rerank_id?: string;
diff --git a/web/src/interfaces/database/chat.ts b/web/src/interfaces/database/chat.ts
index fea56e8593..c6482c8c52 100644
--- a/web/src/interfaces/database/chat.ts
+++ b/web/src/interfaces/database/chat.ts
@@ -80,6 +80,7 @@ export interface IDialog {
similarity_threshold: number;
top_k: number;
top_n: number;
+ prefetch_size: number;
rerank_id?: string;
tenant_rerank_id?: string;
meta_data_filter: MetaDataFilter;
diff --git a/web/src/interfaces/request/knowledge.ts b/web/src/interfaces/request/knowledge.ts
index 1e9c71fb4a..6b0193b4b8 100644
--- a/web/src/interfaces/request/knowledge.ts
+++ b/web/src/interfaces/request/knowledge.ts
@@ -1,5 +1,7 @@
export interface ITestRetrievalRequestBody {
question: string;
+ size: number;
+ prefetch_size: number;
similarity_threshold: number;
vector_similarity_weight: number;
rerank_id?: string;
diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts
index 0a5c722f08..4c7e9c4861 100644
--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -1067,6 +1067,11 @@ This auto-tagging feature enhances retrieval by adding another layer of domain-s
'Your prompts or instructions for the LLM, including but not limited to its role, the desired length, tone, and language of its answers. If your model has native support for reasoning, you can add //no_thinking add the prompt to stop reasoning.',
topN: 'Top N',
topNTip: `Not all chunks with similarity score above the 'similarity threshold' will be sent to the LLM. This selects 'Top N' chunks from the retrieved ones.`,
+ prefetchSize: 'Prefetch size',
+ prefetchSizeTip:
+ 'The number of candidate chunks retrieved before the next processing step.',
+ prefetchSizeValidation:
+ 'Prefetch size must be greater than or equal to Top N.',
variable: 'Variable',
variableTip: `Used together with RAGFlow's chat assistant management APIs, variables can help develop more flexible system prompt strategies. The defined variables will be used by 'System prompt' as part of the prompts for the LLM. {knowledge} is a reserved special variable representing chunks retrieved from specified dataset(s), and all variables should be enclosed in curly braces {} in the 'System prompt'. See https://ragflow.io/docs/dev/set_chat_variables for details.`,
add: 'Add',
diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts
index 631ea37bbb..8d0fb9af5a 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -961,6 +961,9 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
'当LLM回答问题时,你需要LLM遵循的说明,比如角色设计、答案长度和答案语言等。如果您的模型原生支持在问答中推理,可以通过 //no_thinking 关闭自动推理。',
topN: 'Top N',
topNTip: `并非所有相似度得分高于“相似度阈值”的块都会被提供给大语言模型。 LLM 只能看到这些“Top N”块。`,
+ prefetchSize: '预取数量',
+ prefetchSizeTip: '在进行下一步计算之前检索的预取候选分块数量。',
+ prefetchSizeValidation: '预取数量必须大于或等于 Top N。',
variable: '变量',
variableTip: `你可以通过对话 API,并配合变量设置来动态调整大模型的系统提示词。
{knowledge}为系统预留变量,代表从指定知识库召回的文本块。
diff --git a/web/src/pages/agent/constant/index.tsx b/web/src/pages/agent/constant/index.tsx
index 1b88803bc0..583e26a4d2 100644
--- a/web/src/pages/agent/constant/index.tsx
+++ b/web/src/pages/agent/constant/index.tsx
@@ -87,6 +87,7 @@ export enum RetrievalFrom {
export const initialRetrievalValues = {
query: AgentGlobalsSysQueryWithBrace,
top_n: 8,
+ prefetch_size: 64,
top_k: 1024,
kb_ids: [],
rerank_id: '',
diff --git a/web/src/pages/agent/form/retrieval-form/next.tsx b/web/src/pages/agent/form/retrieval-form/next.tsx
index d46d5fa61e..c2f0dfb6c0 100644
--- a/web/src/pages/agent/form/retrieval-form/next.tsx
+++ b/web/src/pages/agent/form/retrieval-form/next.tsx
@@ -9,6 +9,10 @@ import {
import { RAGFlowFormItem } from '@/components/ragflow-form';
import { RerankFormFields } from '@/components/rerank';
import { SimilaritySliderFormField } from '@/components/similarity-slider';
+import {
+ PrefetchSizeFormField,
+ prefetchSizeSchema,
+} from '@/components/prefetch-size-item';
import { TopNFormField } from '@/components/top-n-item';
import {
@@ -50,6 +54,7 @@ export const RetrievalPartialSchema = {
similarity_threshold: z.coerce.number(),
keywords_similarity_weight: z.coerce.number().min(0).max(1),
top_n: z.coerce.number(),
+ ...prefetchSizeSchema,
top_k: z.coerce.number(),
dataset_ids: z.array(z.string()),
rerank_id: z.string(),
@@ -185,6 +190,7 @@ function RetrievalForm({ node }: INextOperatorForm) {
similarityWeightType="keyword"
isTooltipShown
></SimilaritySliderFormField>
+ <PrefetchSizeFormField></PrefetchSizeFormField>
<TopNFormField></TopNFormField>
{hideKnowledgeGraphField || (
<>
diff --git a/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx b/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
index 17a9537463..40f3239140 100644
--- a/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
+++ b/web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
@@ -4,6 +4,7 @@ import { FormContainer } from '@/components/form-container';
import { MetadataFilter } from '@/components/metadata-filter';
import { RerankFormFields } from '@/components/rerank';
import { SimilaritySliderFormField } from '@/components/similarity-slider';
+import { PrefetchSizeFormField } from '@/components/prefetch-size-item';
import { TopNFormField } from '@/components/top-n-item';
import { Form } from '@/components/ui/form';
@@ -67,6 +68,7 @@ const RetrievalForm = () => {
similarityWeightType="keyword"
isTooltipShown
></SimilaritySliderFormField>
+ <PrefetchSizeFormField></PrefetchSizeFormField>
<TopNFormField></TopNFormField>
{hideKnowledgeGraphField || (
<>
diff --git a/web/src/pages/dataset/testing/testing-form.tsx b/web/src/pages/dataset/testing/testing-form.tsx
index d6a67c8e2f..cf884e17ad 100644
--- a/web/src/pages/dataset/testing/testing-form.tsx
+++ b/web/src/pages/dataset/testing/testing-form.tsx
@@ -6,6 +6,10 @@ import { z } from 'zod';
import { CrossLanguageFormField } from '@/components/cross-language-form-field';
import { FormContainer } from '@/components/form-container';
+import {
+ PrefetchSizeFormField,
+ prefetchSizeSchema,
+} from '@/components/prefetch-size-item';
import {
MetadataFilter,
MetadataFilterSchema,
@@ -56,17 +60,23 @@ export default function TestingForm({
const { id } = useParams();
const knowledgeBaseId = id;
- const formSchema = z.object({
- question: z.string().min(1, {
- message: t('knowledgeDetails.testTextPlaceholder'),
- }),
- ...similarityThresholdSchema,
- ...vectorSimilarityWeightSchema,
- ...topKSchema,
- dataset_ids: z.array(z.string()).optional(),
- ...MetadataFilterSchema,
- size: z.number().optional(),
- });
+ const formSchema = z
+ .object({
+ question: z.string().min(1, {
+ message: t('knowledgeDetails.testTextPlaceholder'),
+ }),
+ ...similarityThresholdSchema,
+ ...vectorSimilarityWeightSchema,
+ ...topKSchema,
+ dataset_ids: z.array(z.string()).optional(),
+ ...MetadataFilterSchema,
+ size: z.number().int().min(1).max(100),
+ ...prefetchSizeSchema,
+ })
+ .refine((values) => values.prefetch_size >= values.size, {
+ message: t('chat.prefetchSizeValidation'),
+ path: ['prefetch_size'],
+ });
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema),
@@ -76,6 +86,7 @@ export default function TestingForm({
...initialTopKValue,
dataset_ids: [knowledgeBaseId],
size: 10,
+ prefetch_size: 64,
},
});
@@ -109,6 +120,7 @@ export default function TestingForm({
name={'cross_languages'}
></CrossLanguageFormField>
<MetadataFilter prefix=""></MetadataFilter>
+ <PrefetchSizeFormField></PrefetchSizeFormField>
<TopSelectFormItem></TopSelectFormItem>
</FormContainer>
</div>
diff --git a/web/src/pages/next-chats/chat/app-settings/chat-prompt-engine.tsx b/web/src/pages/next-chats/chat/app-settings/chat-prompt-engine.tsx
index 921dccec0c..63f1db5b00 100644
--- a/web/src/pages/next-chats/chat/app-settings/chat-prompt-engine.tsx
+++ b/web/src/pages/next-chats/chat/app-settings/chat-prompt-engine.tsx
@@ -3,6 +3,7 @@
import { Collapse } from '@/components/collapse';
import { CrossLanguageFormField } from '@/components/cross-language-form-field';
import { MetadataFilter } from '@/components/metadata-filter';
+import { PrefetchSizeFormField } from '@/components/prefetch-size-item';
import { RerankFormFields } from '@/components/rerank';
import { SimilaritySliderFormField } from '@/components/similarity-slider';
import { SwitchFormField } from '@/components/switch-fom-field';
@@ -207,6 +208,9 @@ export function ChatPromptEngine({ prefix = '' }: ChatPromptEngineProps) {
similarityName={prefixName(prefix, 'similarity_threshold')}
similarityWeightName={prefixName(prefix, 'vector_similarity_weight')}
></SimilaritySliderFormField>
+ <PrefetchSizeFormField
+ name={prefixName(prefix, 'prefetch_size')}
+ ></PrefetchSizeFormField>
<TopNFormField name={prefixName(prefix, 'top_n')}></TopNFormField>
<SwitchFormField
diff --git a/web/src/pages/next-chats/chat/app-settings/chat-settings.tsx b/web/src/pages/next-chats/chat/app-settings/chat-settings.tsx
index 3b1dd9d9e7..56c9b46443 100644
--- a/web/src/pages/next-chats/chat/app-settings/chat-settings.tsx
+++ b/web/src/pages/next-chats/chat/app-settings/chat-settings.tsx
@@ -72,6 +72,7 @@ export function ChatSettings({ hasSingleChatBox }: ChatSettingsProps) {
},
},
top_n: 8,
+ prefetch_size: 64,
similarity_threshold: 0.2,
vector_similarity_weight: 0.2,
top_k: 1024,
diff --git a/web/src/pages/next-chats/chat/app-settings/use-chat-setting-schema.tsx b/web/src/pages/next-chats/chat/app-settings/use-chat-setting-schema.tsx
index cdfe5040bc..a575b1f3bf 100644
--- a/web/src/pages/next-chats/chat/app-settings/use-chat-setting-schema.tsx
+++ b/web/src/pages/next-chats/chat/app-settings/use-chat-setting-schema.tsx
@@ -3,6 +3,7 @@ import {
LlmSettingFieldSchema,
} from '@/components/llm-setting-items/next';
import { MetadataFilterSchema } from '@/components/metadata-filter';
+import { prefetchSizeSchema } from '@/components/prefetch-size-item';
import { rerankFormSchema } from '@/components/rerank';
import {
similarityThresholdSchema,
@@ -71,6 +72,7 @@ export function useChatSettingSchema() {
...vectorSimilarityWeightSchema,
...similarityThresholdSchema,
...topnSchema,
+ ...prefetchSizeSchema,
...MetadataFilterSchema,
})
.superRefine((value, ctx) => {
diff --git a/web/src/pages/next-chats/hooks/use-create-chat.ts b/web/src/pages/next-chats/hooks/use-create-chat.ts
index f195ff48aa..574d36857d 100644
--- a/web/src/pages/next-chats/hooks/use-create-chat.ts
+++ b/web/src/pages/next-chats/hooks/use-create-chat.ts
@@ -44,6 +44,7 @@ export const useCreateChatDialog = () => {
similarity_threshold: 0.2,
vector_similarity_weight: 0.3,
top_n: 8,
+ prefetch_size: 64,
top_k: 1024,
}),
[t, defaultModelDictionary?.llm_id],
diff --git a/web/src/pages/next-search/search-setting-hooks.ts b/web/src/pages/next-search/search-setting-hooks.ts
index 5c7fee8745..d536f9ea02 100644
--- a/web/src/pages/next-search/search-setting-hooks.ts
+++ b/web/src/pages/next-search/search-setting-hooks.ts
@@ -23,6 +23,7 @@ import {
} from '@/components/llm-setting-items/next';
import { MetadataFilterSchema } from '@/components/metadata-filter';
import { ModelTypeMap } from '@/components/model-tree-select';
+import { prefetchSizeSchema } from '@/components/prefetch-size-item';
import { useModelValidIds } from '@/hooks/use-llm-request';
import { useEffect, useMemo } from 'react';
import { Control, UseFormTrigger, useWatch } from 'react-hook-form';
@@ -44,6 +45,7 @@ export const SearchSettingFormSchema = z
rerank_id: z.string(),
use_rerank: z.boolean(),
top_k: z.number(),
+ ...prefetchSizeSchema,
summary: z.boolean(),
llm_setting: z.object({ ...LlmSettingFieldSchema, ...LLMIdFormField }),
related_search: z.boolean(),
diff --git a/web/src/pages/next-search/search-setting.tsx b/web/src/pages/next-search/search-setting.tsx
index 0edb085398..6f3ba5793d 100644
--- a/web/src/pages/next-search/search-setting.tsx
+++ b/web/src/pages/next-search/search-setting.tsx
@@ -20,6 +20,7 @@ import AvatarNameDescription from '@/components/avatar-name-description';
import { KnowledgeBaseFormField } from '@/components/knowledge-base-item';
import { LlmSettingFieldItems } from '@/components/llm-setting-items/next';
import { MetadataFilter } from '@/components/metadata-filter';
+import { PrefetchSizeFormField } from '@/components/prefetch-size-item';
import { SimilaritySliderFormField } from '@/components/similarity-slider';
import { Button } from '@/components/ui/button';
import {
@@ -110,6 +111,7 @@ function SearchSetting({
rerank_id: search_config?.rerank_id || '',
use_rerank: search_config?.rerank_id ? true : false,
top_k: search_config?.top_k || 1024,
+ prefetch_size: search_config?.prefetch_size ?? 100,
summary: search_config?.summary || false,
chat_id: search_config?.chat_id || '',
llm_setting: {
@@ -399,6 +401,10 @@ function SearchSetting({
similarityWeightName="search_config.vector_similarity_weight"
numberInputClassName="rounded-sm"
></SimilaritySliderFormField>
+ <PrefetchSizeFormField
+ name="search_config.prefetch_size"
+ defaultValue={100}
+ ></PrefetchSizeFormField>
{/* Rerank Model */}
<FormField
control={formMethods.control}
diff --git a/web/src/pages/next-search/search-view.tsx b/web/src/pages/next-search/search-view.tsx
index 90b0c293e2..e96c6b5d45 100644
--- a/web/src/pages/next-search/search-view.tsx
+++ b/web/src/pages/next-search/search-view.tsx
@@ -231,6 +231,7 @@ export default function SearchingView({
</div>
<div className="w-44">
<TopSelect
+ max={searchData.search_config.prefetch_size ?? 100}
value={pageSize}
onChange={handleTopChange}
></TopSelect>
diff --git a/web/src/pages/next-searches/hooks.ts b/web/src/pages/next-searches/hooks.ts
index 89286b7315..9cf988c767 100644
--- a/web/src/pages/next-searches/hooks.ts
+++ b/web/src/pages/next-searches/hooks.ts
@@ -203,6 +203,7 @@ export interface ISearchAppDetailProps {
summary: boolean;
llm_setting: IllmSettingProps & IllmSettingEnableProps;
top_k: number;
+ prefetch_size: number;
use_kg: boolean;
vector_similarity_weight: number;
web_search: boolean;