Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix: integrate rerank into hierarchical retriever (#599)
mildred52273c707242914
diff --git a/docs/en/concepts/07-retrieval.md b/docs/en/concepts/07-retrieval.mdindex 7fb73c919..4dd5f87e2 100644--- a/docs/en/concepts/07-retrieval.md+++ b/docs/en/concepts/07-retrieval.md@@ -137,6 +137,7 @@ Rerank refines candidate results in THINKING mode.- Rerank AK/SK configured- Using THINKING mode (default for search())+- If rerank returns an invalid result or the API call fails, retrieval falls back to vector scores### Scoring Methoddiff --git a/docs/zh/concepts/07-retrieval.md b/docs/zh/concepts/07-retrieval.mdindex fc0a11d44..4b4e50abc 100644--- a/docs/zh/concepts/07-retrieval.md+++ b/docs/zh/concepts/07-retrieval.md@@ -137,6 +137,7 @@ Rerank 在 THINKING 模式下对候选结果精排。- 配置了 Rerank AK/SK- 使用 THINKING 模式(search() 默认)+- 如果 rerank 返回无效结果或 API 调用失败,会回退到向量分数### 评分方式diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.pyindex c2d485987..e725df891 100644--- a/openviking/retrieve/hierarchical_retriever.py+++ b/openviking/retrieve/hierarchical_retriever.py@@ -26,6 +26,7 @@ from openviking_cli.retrieve.types import ()from openviking_cli.utils.config import RerankConfigfrom openviking_cli.utils.logger import get_logger+from openviking_cli.utils.rerank import RerankClientlogger = get_logger(__name__)@@ -68,8 +69,7 @@ class HierarchicalRetriever:# Initialize rerank client only if config is availableif rerank_config and rerank_config.is_available():- # TODO: Support later - initialize RerankClient here- self._rerank_client = None+ self._rerank_client = RerankClient.from_config(rerank_config)logger.info(f"[HierarchicalRetriever] Rerank config available, threshold={self.threshold}")@@ -84,7 +84,7 @@ class HierarchicalRetriever:query: TypedQuery,ctx: RequestContext,limit: int = 5,- mode: RetrieverMode = RetrieverMode.THINKING,+ mode: str = RetrieverMode.THINKING,score_threshold: Optional[float] = None,score_gte: bool = False,scope_dsl: Optional[Dict[str, Any]] = None,@@ -142,7 +142,12 @@ class HierarchicalRetriever:)# Step 3: Merge starting points- starting_points = self._merge_starting_points(query.query, root_uris, global_results)+ starting_points = self._merge_starting_points(+ query.query,+ root_uris,+ global_results,+ mode=mode,+ )# Step 4: Recursive searchcandidates = await self._recursive_search(@@ -191,6 +196,38 @@ class HierarchicalRetriever:)return results+ def _rerank_scores(+ self,+ query: str,+ documents: List[str],+ fallback_scores: List[float],+ ) -> List[float]:+ """Return rerank scores or fall back to vector scores."""+ if not self._rerank_client or not documents:+ return fallback_scores++ try:+ scores = self._rerank_client.rerank_batch(query, documents)+ except Exception as e:+ logger.warning(+ "[HierarchicalRetriever] Rerank failed, fallback to vector scores: %s", e+ )+ return fallback_scores++ if not scores or len(scores) != len(documents):+ logger.warning(+ "[HierarchicalRetriever] Invalid rerank result, fallback to vector scores"+ )+ return fallback_scores++ normalized_scores: List[float] = []+ for score, fallback in zip(scores, fallback_scores):+ if isinstance(score, (int, float)):+ normalized_scores.append(float(score))+ else:+ normalized_scores.append(fallback)+ return normalized_scores+def _merge_starting_points(self,query: str,@@ -206,15 +243,12 @@ class HierarchicalRetriever:seen = set()# Results from global search- docs = []+ default_scores = [r.get("_score", 0.0) for r in global_results]if self._rerank_client and mode == RetrieverMode.THINKING:- for r in global_results:- # todo: multi-modal- doc = r["abstract"]- docs.append(doc)- rerank_scores = self._rerank_client.rerank_batch(query, docs)+ docs = [str(r.get("abstract", "")) for r in global_results]+ query_scores = self._rerank_scores(query, docs, default_scores)for i, r in enumerate(global_results):- points.append((r["uri"], rerank_scores[i]))+ points.append((r["uri"], query_scores[i]))seen.add(r["uri"])else:for r in global_results:@@ -300,19 +334,10 @@ class HierarchicalRetriever:if not results:continue- query_scores = []+ query_scores = [r.get("_score", 0.0) for r in results]if self._rerank_client and mode == RetrieverMode.THINKING:- documents = []- for r in results:- # todo: multi-modal- doc = r["abstract"]- documents.append(doc)-- rerank_scores = self._rerank_client.rerank_batch(query, documents)- query_scores = rerank_scores- else:- for r in results:- query_scores.append(r.get("_score", 0))+ documents = [str(r.get("abstract", "")) for r in results]+ query_scores = self._rerank_scores(query, documents, query_scores)for r, score in zip(results, query_scores):uri = r.get("uri", "")diff --git a/openviking_cli/utils/rerank.py b/openviking_cli/utils/rerank.pyindex fc0058caf..10192c973 100644--- a/openviking_cli/utils/rerank.py+++ b/openviking_cli/utils/rerank.py@@ -79,7 +79,7 @@ class RerankClient:SignerV4.sign(r, credentials)return r- def rerank_batch(self, query: str, documents: List[str]) -> List[float]:+ def rerank_batch(self, query: str, documents: List[str]) -> Optional[List[float]]:"""Batch rerank documents against a query.@@ -88,7 +88,8 @@ class RerankClient:documents: List of document texts to rankReturns:- List of rerank scores for each document (same order as input)+ List of rerank scores for each document (same order as input),+ or None when rerank fails and the caller should fall back"""if not documents:return []@@ -111,7 +112,7 @@ class RerankClient:response = requests.request(method=req.method,- url=f"http://{self.host}{req.path}",+ url=f"https://{self.host}{req.path}",headers=req.headers,data=req.body,timeout=30,@@ -121,10 +122,17 @@ class RerankClient:# print(f"[RerankClient] Raw response: {result}")if "result" not in result or "data" not in result["result"]:logger.warning(f"[RerankClient] Unexpected response format: {result}")- return [0.0] * len(documents)+ return None# Each document is a separate group, data array returns scores for each group sequentiallydata = result["result"]["data"]+ if len(data) != len(documents):+ logger.warning(+ "[RerankClient] Unexpected rerank result length: expected=%s actual=%s",+ len(documents),+ len(data),+ )+ return Nonescores = [item.get("score", 0.0) for item in data]logger.debug(f"[RerankClient] Reranked {len(documents)} documents")@@ -132,7 +140,7 @@ class RerankClient:except Exception as e:logger.error(f"[RerankClient] Rerank failed: {e}")- return [0.0] * len(documents)+ return None@classmethoddef from_config(cls, config) -> Optional["RerankClient"]:diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pynew file mode 100644index 000000000..ffaea6a8f--- /dev/null+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py@@ -0,0 +1,268 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0++"""Hierarchical retriever rerank behavior tests."""++import pytest++from openviking.retrieve.hierarchical_retriever import HierarchicalRetriever, RetrieverMode+from openviking.server.identity import RequestContext, Role+from openviking_cli.retrieve.types import ContextType, TypedQuery+from openviking_cli.session.user_id import UserIdentifier+from openviking_cli.utils.config import RerankConfig+++class DummyEmbedResult:+ def __init__(self) -> None:+ self.dense_vector = [1.0]+ self.sparse_vector = {"hello": 1.0}+++class DummyEmbedder:+ def embed(self, _query: str) -> DummyEmbedResult:+ return DummyEmbedResult()+++class DummyStorage:+ def __init__(self) -> None:+ self.collection_name = "context"+ self.global_search_calls = []+ self.child_search_calls = []++ async def collection_exists_bound(self) -> bool:+ return True++ async def search_global_roots_in_tenant(+ self,+ ctx,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ limit: int = 10,+ ):+ self.global_search_calls.append(+ {+ "ctx": ctx,+ "query_vector": query_vector,+ "sparse_query_vector": sparse_query_vector,+ "context_type": context_type,+ "target_directories": target_directories,+ "extra_filter": extra_filter,+ "limit": limit,+ }+ )+ return [+ {+ "uri": "viking://resources/root-a",+ "abstract": "root A",+ "_score": 0.2,+ "level": 1,+ "context_type": "resource",+ },+ {+ "uri": "viking://resources/root-b",+ "abstract": "root B",+ "_score": 0.8,+ "level": 1,+ "context_type": "resource",+ },+ ]++ async def search_children_in_tenant(+ self,+ ctx,+ parent_uri: str,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ limit: int = 10,+ ):+ self.child_search_calls.append(+ {+ "ctx": ctx,+ "parent_uri": parent_uri,+ "query_vector": query_vector,+ "sparse_query_vector": sparse_query_vector,+ "context_type": context_type,+ "target_directories": target_directories,+ "extra_filter": extra_filter,+ "limit": limit,+ }+ )+ if parent_uri == "viking://resources":+ return [+ {+ "uri": "viking://resources/file-a",+ "abstract": "child A",+ "_score": 0.2,+ "level": 2,+ "context_type": "resource",+ "category": "doc",+ },+ {+ "uri": "viking://resources/file-b",+ "abstract": "child B",+ "_score": 0.8,+ "level": 2,+ "context_type": "resource",+ "category": "doc",+ },+ ]+ return []+++class FakeRerankClient:+ def __init__(self, scores):+ self.scores = list(scores)+ self.calls = []+ self._cursor = 0++ def rerank_batch(self, query: str, documents: list[str]):+ self.calls.append((query, list(documents)))+ start = self._cursor+ end = start + len(documents)+ self._cursor = end+ return list(self.scores[start:end])+++def _ctx() -> RequestContext:+ return RequestContext(user=UserIdentifier("acc1", "user1", "agent1"), role=Role.USER)+++def _query() -> TypedQuery:+ return TypedQuery(query="hello", context_type=ContextType.RESOURCE, intent="")+++def _config() -> RerankConfig:+ return RerankConfig(ak="ak", sk="sk", threshold=0.1)++[email protected](autouse=True)+def _disable_viking_fs(monkeypatch):+ monkeypatch.setattr("openviking.retrieve.hierarchical_retriever.get_viking_fs", lambda: None)+++def test_retriever_initializes_rerank_client(monkeypatch):+ fake_client = FakeRerankClient([0.9, 0.1])++ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )++ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=DummyEmbedder(),+ rerank_config=_config(),+ )++ assert retriever._rerank_client is fake_client+++def test_merge_starting_points_prefers_rerank_scores_in_thinking_mode(monkeypatch):+ fake_client = FakeRerankClient([0.95, 0.05])+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )++ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=DummyEmbedder(),+ rerank_config=_config(),+ )++ starting_points = retriever._merge_starting_points(+ "hello",+ ["viking://resources"],+ [+ {"uri": "viking://resources/root-a", "abstract": "root A", "_score": 0.2},+ {"uri": "viking://resources/root-b", "abstract": "root B", "_score": 0.8},+ ],+ mode=RetrieverMode.THINKING,+ )++ assert starting_points[:2] == [+ ("viking://resources/root-a", 0.95),+ ("viking://resources/root-b", 0.05),+ ]+ assert fake_client.calls == [("hello", ["root A", "root B"])]+++async def test_retrieve_uses_rerank_scores_in_thinking_mode(monkeypatch):+ fake_client = FakeRerankClient([0.95, 0.05, 0.11, 0.95])+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )++ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=DummyEmbedder(),+ rerank_config=_config(),+ )++ result = await retriever.retrieve(_query(), ctx=_ctx(), limit=2, mode=RetrieverMode.THINKING)++ assert [ctx.uri for ctx in result.matched_contexts] == [+ "viking://resources/file-b",+ "viking://resources/file-a",+ ]+ assert fake_client.calls[0] == ("hello", ["root A", "root B"])+ assert fake_client.calls[1] == ("hello", ["child A", "child B"])+++async def test_retrieve_falls_back_to_vector_scores_when_rerank_returns_none(monkeypatch):+ class NoneRerankClient(FakeRerankClient):+ def rerank_batch(self, query: str, documents: list[str]):+ self.calls.append((query, list(documents)))+ return None++ fake_client = NoneRerankClient([])+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )++ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=DummyEmbedder(),+ rerank_config=_config(),+ )++ result = await retriever.retrieve(_query(), ctx=_ctx(), limit=2, mode=RetrieverMode.THINKING)++ assert [ctx.uri for ctx in result.matched_contexts] == [+ "viking://resources/file-b",+ "viking://resources/file-a",+ ]+ assert fake_client.calls+++async def test_quick_mode_skips_rerank(monkeypatch):+ fake_client = FakeRerankClient([0.95, 0.05, 0.05, 0.95])+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",+ lambda config: fake_client,+ )++ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=DummyEmbedder(),+ rerank_config=_config(),+ )++ result = await retriever.retrieve(_query(), ctx=_ctx(), limit=2, mode=RetrieverMode.QUICK)++ assert [ctx.uri for ctx in result.matched_contexts] == [+ "viking://resources/file-b",+ "viking://resources/file-a",+ ]+ assert fake_client.calls == []