Skip to content

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

Refactor: Add rerank_candidates_count, knn top_k and num_candidates to /api/v1/retrieval (#18768)

Wang Qi68b893cd1a9c
diff --git a/api/apps/restful_apis/chunk_api.py b/api/apps/restful_apis/chunk_api.py
index a18a6dc10f..b157e78be9 100644
--- a/api/apps/restful_apis/chunk_api.py
+++ b/api/apps/restful_apis/chunk_api.py
@@ -378,9 +378,32 @@ async def retrieval_test(tenant_id):
doc_ids = None
similarity_threshold = float(req.get("similarity_threshold", 0.2))
vector_similarity_weight = float(req.get("vector_similarity_weight", 0.3))
- top = int(req.get("top_k", 1024))
- if top <= 0:
- return get_error_data_result("`top_k` must be greater than 0")
+ if "top_k" in req:
+ logging.warning("`top_k` is deprecated for POST /api/v1/retrieval; use `knn_top_k` instead.")
+ knn_top_k_parameter = "knn_top_k" if "knn_top_k" in req else "top_k"
+ try:
+ knn_top_k = int(req.get(knn_top_k_parameter, 1024))
+ except (TypeError, ValueError):
+ return get_error_data_result(f"`{knn_top_k_parameter}` should be an integer")
+ if knn_top_k <= 0:
+ return get_error_data_result(f"`{knn_top_k_parameter}` must be greater than 0")
+ try:
+ knn_num_candidates = int(req.get("knn_num_candidates", max(2048, knn_top_k)))
+ except (TypeError, ValueError):
+ return get_error_data_result("`knn_num_candidates` should be an integer")
+ if knn_num_candidates < knn_top_k:
+ return get_error_data_result("`knn_num_candidates` must be greater than or equal to `knn_top_k`")
+ try:
+ rerank_candidates_count = int(req.get("rerank_candidates_count", 64))
+ except (TypeError, ValueError):
+ return get_error_data_result("`rerank_candidates_count` should be an integer")
+ if rerank_candidates_count <= 0:
+ return get_error_data_result("`rerank_candidates_count` must be greater than 0")
+ if rerank_candidates_count < page * size:
+ return get_error_data_result(f"`rerank_candidates_count` must be at least `page` multiplied by `page_size` ({page * size})")
+ include_knowledge_compilation = req.get("include_knowledge_compilation", True)
+ if not isinstance(include_knowledge_compilation, bool):
+ return get_error_data_result("`include_knowledge_compilation` should be a boolean")
highlight_val = req.get("highlight", None)
if highlight_val is None:
highlight = False
@@ -420,10 +443,13 @@ async def retrieval_test(tenant_id):
similarity_threshold,
vector_similarity_weight,
doc_ids=doc_ids,
- knn_top_k=top,
+ knn_top_k=knn_top_k,
+ knn_num_candidates=knn_num_candidates,
rerank_mdl=rerank_mdl,
highlight=highlight,
rank_feature=label_question(question, kbs),
+ must_not=None if include_knowledge_compilation else {"exists": "compile_kwd"},
+ rerank_candidates_count=rerank_candidates_count,
)
if toc_enhance:
chat_model_config = get_tenant_default_model_by_type(kb.tenant_id, LLMType.CHAT)
diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.md
index 70ef65bf86..3fd8fa9a8d 100644
--- a/docs/references/http_api_reference.md
+++ b/docs/references/http_api_reference.md
@@ -2810,7 +2810,10 @@ Retrieves chunks from specified datasets.
- `"page_size"`: `integer`
- `"similarity_threshold"`: `float`
- `"vector_similarity_weight"`: `float`
- - `"top_k"`: `integer`
+ - `"top_k"`: `integer` (deprecated; use `"knn_top_k"`)
+ - `"knn_top_k"`: `integer`
+ - `"knn_num_candidates"`: `integer`
+ - `"rerank_candidates_count"`: `integer`
- `"rerank_id"`: `string`
- `"keyword"`: `boolean`
- `"highlight"`: `boolean`
@@ -2818,6 +2821,7 @@ Retrieves chunks from specified datasets.
- `"metadata_condition"`: `object`
- `"use_kg"`: `boolean`
- `"toc_enhance"`: `boolean`
+ - `"include_knowledge_compilation"`: `boolean`
##### Request example
@@ -2831,6 +2835,10 @@ curl --request POST \
"question": "What is advantage of ragflow?",
"dataset_ids": ["b2a62730759d11ef987d0242ac120004"],
"document_ids": ["77df9ef4759a11ef8bdd0242ac120004"],
+ "knn_top_k": 1024,
+ "knn_num_candidates": 2048,
+ "rerank_candidates_count": 64,
+ "include_knowledge_compilation": true,
"metadata_condition": {
"logic": "and",
"conditions": [
@@ -2866,7 +2874,15 @@ curl --request POST \
- `"vector_similarity_weight"`: (*Body parameter*), `float`
The weight of vector cosine similarity. Defaults to `0.3`. If x represents the weight of vector cosine similarity, then (1 - x) is the term similarity weight.
- `"top_k"`: (*Body parameter*), `integer`
+ **Deprecated.** An alias for `"knn_top_k"`. If both parameters are provided, `"knn_top_k"` takes precedence.
+- `"knn_top_k"`: (*Body parameter*), `integer`
The number of chunks engaged in vector cosine computation. Defaults to `1024`.
+- `"knn_num_candidates"`: (*Body parameter*), `integer`
+ The number of approximate nearest-neighbor candidates considered for vector search. It must be greater than or equal to `"knn_top_k"`. Defaults to the greater of `2048` and `"knn_top_k"`. This parameter currently applies only to Elasticsearch.
+- `"rerank_candidates_count"`: (*Body parameter*), `integer`
+ The number of initial retrieval candidates to rank. It must be at least `"page"` multiplied by `"page_size"`. Defaults to `64`.
+- `"include_knowledge_compilation"`: (*Body parameter*), `boolean`
+ Whether to include knowledge-compilation chunks in the results. Defaults to `true`.
- `"use_kg"`: (*Body parameter*), `boolean`
Whether to search chunks related to the generated knowledge graph for multi-hop queries. Defaults to `False`. Before enabling this, ensure you have successfully constructed a knowledge graph for the specified datasets. See [here](../guides/dataset/advanced/construct_knowledge_graph.md) for details.
- `"toc_enhance"`: (*Body parameter*), `boolean`
diff --git a/test/testcases/restful_api/test_retrieval.py b/test/testcases/restful_api/test_retrieval.py
index 0674b23ea2..19936aa89d 100644
--- a/test/testcases/restful_api/test_retrieval.py
+++ b/test/testcases/restful_api/test_retrieval.py
@@ -259,7 +259,7 @@ def test_retrieval_vector_similarity_and_top_k_contract(rest_client, ensure_pars
("top_k 10", {"top_k": 10}, 0, ""),
("top_k 1", {"top_k": 1}, 0, ""),
("top_k -1", {"top_k": -1}, 102, "`top_k` must be greater than 0"),
- ("top_k alpha", {"top_k": "a"}, 100, "invalid literal for int()"),
+ ("top_k alpha", {"top_k": "a"}, 102, "`top_k` should be an integer"),
]
for scenario_name, updates, expected_code, expected_message in cases:
payload = {"question": "chunk", "dataset_ids": [dataset_id]}