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
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.pyindex 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 = Nonesimilarity_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.mdindex 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.pyindex 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]}