Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix: integrate rerank into hierarchical retriever (#599)

mildred52273c707242914
diff --git a/docs/en/concepts/07-retrieval.md b/docs/en/concepts/07-retrieval.md
index 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 Method
diff --git a/docs/zh/concepts/07-retrieval.md b/docs/zh/concepts/07-retrieval.md
index 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.py
index 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 RerankConfig
from openviking_cli.utils.logger import get_logger
+from openviking_cli.utils.rerank import RerankClient
logger = get_logger(__name__)
@@ -68,8 +69,7 @@ class HierarchicalRetriever:
# Initialize rerank client only if config is available
if 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 search
candidates = 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.py
index 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 rank
Returns:
- 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 sequentially
data = result["result"]["data"]
+ if len(data) != len(documents):
+ logger.warning(
+ "[RerankClient] Unexpected rerank result length: expected=%s actual=%s",
+ len(documents),
+ len(data),
+ )
+ return None
scores = [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
@classmethod
def from_config(cls, config) -> Optional["RerankClient"]:
diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.py
new file mode 100644
index 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 == []