🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat(retrievers): add optional reranker stage to HybridRetriever (#4133)
maoxin123408e650047bfb
diff --git a/camel/retrievers/__init__.py b/camel/retrievers/__init__.pyindex 45e0f17a9..eb3d344bc 100644--- a/camel/retrievers/__init__.py+++ b/camel/retrievers/__init__.py@@ -14,6 +14,7 @@# ruff: noqa: I001from .auto_retriever import AutoRetrieverfrom .base import BaseRetriever+from .base_rerank import BaseRerankRetrieverfrom .bm25_retriever import BM25Retrieverfrom .jina_rerank_retriever import JinaRerankRetrieverfrom .cohere_rerank_retriever import CohereRerankRetriever@@ -21,11 +22,12 @@ from .vector_retriever import VectorRetrieverfrom .hybrid_retrival import HybridRetriever__all__ = [- 'BaseRetriever',- 'VectorRetriever','AutoRetriever','BM25Retriever',- 'JinaRerankRetriever',+ 'BaseRerankRetriever',+ 'BaseRetriever','CohereRerankRetriever','HybridRetriever',+ 'JinaRerankRetriever',+ 'VectorRetriever',]diff --git a/camel/retrievers/base_rerank.py b/camel/retrievers/base_rerank.pynew file mode 100644index 000000000..c53de80e0--- /dev/null+++ b/camel/retrievers/base_rerank.py@@ -0,0 +1,57 @@+# ========= Copyright 2023-2026 @ CAMEL-AI.org. 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.+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========+from abc import abstractmethod+from typing import Any, Dict, List++from camel.retrievers.base import BaseRetriever++DEFAULT_TOP_K_RESULTS = 1+++class BaseRerankRetriever(BaseRetriever):+ r"""Abstract base class for re-ranking retrievers.++ A re-ranking retriever takes a query together with a list of already+ retrieved results (for example, the output of a :class:`VectorRetriever`,+ a :class:`BM25Retriever`, or a :class:`HybridRetriever`) and re-orders+ those results by their semantic relevance to the query, typically using a+ cross-encoder or a dedicated re-ranking API.++ Unlike first-stage retrievers, re-rankers do not ingest content, so the+ :meth:`process` method is not required and is left unimplemented.+ """++ @abstractmethod+ def query(+ self,+ query: str,+ retrieved_result: List[Dict[str, Any]],+ top_k: int = DEFAULT_TOP_K_RESULTS,+ ) -> List[Dict[str, Any]]:+ r"""Re-ranks the given retrieved results against the query.++ Args:+ query (str): The query string used for re-ranking.+ retrieved_result (List[Dict[str, Any]]): The content to be+ re-ranked, typically the output of a first-stage retriever.+ Each item should contain a ``'text'`` entry.+ top_k (int, optional): The number of top results to return after+ re-ranking. Must be a positive integer. (default:+ :obj:`DEFAULT_TOP_K_RESULTS`)++ Returns:+ List[Dict[str, Any]]: The re-ranked results, each containing the+ original data plus an updated ``'similarity score'``.+ """+ raise NotImplementedErrordiff --git a/camel/retrievers/cohere_rerank_retriever.py b/camel/retrievers/cohere_rerank_retriever.pyindex 6e0fa6f5b..8109cd9d1 100644--- a/camel/retrievers/cohere_rerank_retriever.py+++ b/camel/retrievers/cohere_rerank_retriever.py@@ -14,13 +14,13 @@import osfrom typing import Any, Dict, List, Optional-from camel.retrievers import BaseRetriever+from camel.retrievers.base_rerank import BaseRerankRetrieverfrom camel.utils import api_keys_required, dependencies_requiredDEFAULT_TOP_K_RESULTS = 1-class CohereRerankRetriever(BaseRetriever):+class CohereRerankRetriever(BaseRerankRetriever):r"""An implementation of the `BaseRetriever` using the `Cohere Re-ranking`model.diff --git a/camel/retrievers/hybrid_retrival.py b/camel/retrievers/hybrid_retrival.pyindex 01fc35664..885cbe22b 100644--- a/camel/retrievers/hybrid_retrival.py+++ b/camel/retrievers/hybrid_retrival.py@@ -15,6 +15,7 @@ from typing import Any, Dict, List, Optional, Unionfrom camel.embeddings import BaseEmbeddingfrom camel.retrievers import BaseRetriever, BM25Retriever, VectorRetriever+from camel.retrievers.base_rerank import BaseRerankRetrieverfrom camel.storages import BaseVectorStoragefrom camel.utils import dependencies_required@@ -163,6 +164,8 @@ class HybridRetriever(BaseRetriever):vector_retriever_similarity_threshold: float = 0.5,bm25_retriever_top_k: int = 50,return_detailed_info: bool = False,+ reranker: Optional[BaseRerankRetriever] = None,+ rerank_input_top_k: int = 50,) -> Dict[str, Any]:r"""Executes a hybrid retrieval query using both vector and BM25retrievers.@@ -178,6 +181,15 @@ class HybridRetriever(BaseRetriever):threshold for vector retriever.bm25_retriever_top_k (int): Top results from BM25 retriever.return_detailed_info (bool): Return detailed info if True.+ reranker (Optional[BaseRerankRetriever]): An optional re-ranking+ retriever (e.g. :class:`CohereRerankRetriever` or+ :class:`JinaRerankRetriever`). When provided, the fused+ results are re-ordered by the reranker before being truncated+ to ``top_k``, forming a retrieve -> fuse -> rerank pipeline.+ (default: :obj:`None`)+ rerank_input_top_k (int): The number of top fused candidates fed+ into the reranker. Only used when ``reranker`` is provided.+ (default: :obj:`50`)Returns:Union[@@ -216,15 +228,28 @@ class HybridRetriever(BaseRetriever):top_k=bm25_retriever_top_k,)+ # When a reranker is used, fuse a larger candidate pool first and let+ # the reranker decide the final top_k ordering.+ fusion_top_k = (+ max(top_k, rerank_input_top_k) if reranker is not None else top_k+ )+all_retrieved_info = self._sort_rrf_scores(vector_retriever_results,bm25_retriever_results,- top_k,+ fusion_top_k,vector_weight,bm25_weight,rank_smoothing_factor,)+ if reranker is not None and all_retrieved_info:+ all_retrieved_info = reranker.query(+ query=query,+ retrieved_result=all_retrieved_info, # type: ignore[arg-type]+ top_k=top_k,+ )+retrieved_info = {"Original Query": query,"Retrieved Context": (diff --git a/camel/retrievers/jina_rerank_retriever.py b/camel/retrievers/jina_rerank_retriever.pyindex 8e1d68baa..96d478be2 100644--- a/camel/retrievers/jina_rerank_retriever.py+++ b/camel/retrievers/jina_rerank_retriever.py@@ -14,7 +14,7 @@import osfrom typing import Any, Dict, List, Union-from camel.retrievers import BaseRetriever+from camel.retrievers.base_rerank import BaseRerankRetrieverfrom camel.types.enums import JinaRerankerModelTypefrom camel.utils import api_keys_required, dependencies_required@@ -22,7 +22,7 @@ DEFAULT_TOP_K_RESULTS = 1JINA_RERANK_API_URL = "https://api.jina.ai/v1/rerank"-class JinaRerankRetriever(BaseRetriever):+class JinaRerankRetriever(BaseRerankRetriever):r"""An implementation of the `BaseRetriever` using the `Jina AI Reranker`model.diff --git a/test/retrievers/test_hybrid_retriever.py b/test/retrievers/test_hybrid_retriever.pyindex c354686a7..da34c9327 100644--- a/test/retrievers/test_hybrid_retriever.py+++ b/test/retrievers/test_hybrid_retriever.py@@ -60,3 +60,38 @@ def test_sort_rrf_scores_integration(mock_hybrid_retriever):assert len(results['Retrieved Context']) == 2assert results['Retrieved Context'][0]['text'] == 'Document 2'assert results['Retrieved Context'][1]['text'] == 'Document 1'+++def test_query_with_reranker(mock_hybrid_retriever):+ # A mock reranker that reverses the fused order and returns top_k items.+ def _rerank(query, retrieved_result, top_k):+ reranked = list(reversed(retrieved_result))[:top_k]+ for i, item in enumerate(reranked):+ item['similarity score'] = 1.0 - i * 0.1+ return reranked++ reranker = MagicMock()+ reranker.query = MagicMock(side_effect=_rerank)++ results = mock_hybrid_retriever.query(+ query="some query about document 1",+ top_k=2,+ return_detailed_info=True,+ reranker=reranker,+ )++ # Reranker must have been invoked once with the fused candidates.+ reranker.query.assert_called_once()+ _, kwargs = reranker.query.call_args+ assert kwargs['top_k'] == 2++ # The reranker receives the full fused candidate pool (Document 2,+ # Document 1, Document 3 by RRF), reverses it, and returns the top 2.+ _, kwargs = reranker.query.call_args+ assert len(kwargs['retrieved_result']) == 3++ # Final order should reflect the reranker's reordering, not the raw RRF.+ context = results['Retrieved Context']+ assert len(context) == 2+ assert context[0]['text'] == 'Document 3'+ assert context[1]['text'] == 'Document 1'