Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat(retrievers): add optional reranker stage to HybridRetriever (#4133)

maoxin123408e650047bfb
diff --git a/camel/retrievers/__init__.py b/camel/retrievers/__init__.py
index 45e0f17a9..eb3d344bc 100644
--- a/camel/retrievers/__init__.py
+++ b/camel/retrievers/__init__.py
@@ -14,6 +14,7 @@
# ruff: noqa: I001
from .auto_retriever import AutoRetriever
from .base import BaseRetriever
+from .base_rerank import BaseRerankRetriever
from .bm25_retriever import BM25Retriever
from .jina_rerank_retriever import JinaRerankRetriever
from .cohere_rerank_retriever import CohereRerankRetriever
@@ -21,11 +22,12 @@ from .vector_retriever import VectorRetriever
from .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.py
new file mode 100644
index 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 NotImplementedError
diff --git a/camel/retrievers/cohere_rerank_retriever.py b/camel/retrievers/cohere_rerank_retriever.py
index 6e0fa6f5b..8109cd9d1 100644
--- a/camel/retrievers/cohere_rerank_retriever.py
+++ b/camel/retrievers/cohere_rerank_retriever.py
@@ -14,13 +14,13 @@
import os
from typing import Any, Dict, List, Optional
-from camel.retrievers import BaseRetriever
+from camel.retrievers.base_rerank import BaseRerankRetriever
from camel.utils import api_keys_required, dependencies_required
DEFAULT_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.py
index 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, Union
from camel.embeddings import BaseEmbedding
from camel.retrievers import BaseRetriever, BM25Retriever, VectorRetriever
+from camel.retrievers.base_rerank import BaseRerankRetriever
from camel.storages import BaseVectorStorage
from 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 BM25
retrievers.
@@ -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.py
index 8e1d68baa..96d478be2 100644
--- a/camel/retrievers/jina_rerank_retriever.py
+++ b/camel/retrievers/jina_rerank_retriever.py
@@ -14,7 +14,7 @@
import os
from typing import Any, Dict, List, Union
-from camel.retrievers import BaseRetriever
+from camel.retrievers.base_rerank import BaseRerankRetriever
from camel.types.enums import JinaRerankerModelType
from camel.utils import api_keys_required, dependencies_required
@@ -22,7 +22,7 @@ DEFAULT_TOP_K_RESULTS = 1
JINA_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.py
index 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']) == 2
assert 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'