Skip to content

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

fix(retrieval): allow find without rerank and preserve level-2 rerank scores (#754)

mildred52282307c328140
diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.py
index 15843445f..55f5b31aa 100644
--- a/openviking/retrieve/hierarchical_retriever.py
+++ b/openviking/retrieve/hierarchical_retriever.py
@@ -176,6 +176,12 @@ class HierarchicalRetriever:
# 从 global_results 中提取 level 2 的文件作为初始候选者
initial_candidates = [r for r in global_results if r.get("level", 2) == 2]
+ initial_candidates = self._prepare_initial_candidates(
+ query.query,
+ initial_candidates,
+ mode=mode,
+ )
+
# Step 4: Recursive search
candidates = await self._recursive_search(
vector_proxy=vector_proxy,
@@ -285,6 +291,8 @@ class HierarchicalRetriever:
points = []
seen = set()
+ global_results = [r for r in global_results if r.get("level", 2) != 2]
+
# Results from global search
default_scores = [r.get("_score", 0.0) for r in global_results]
if self._rerank_client and mode == RetrieverMode.THINKING:
@@ -310,6 +318,29 @@ class HierarchicalRetriever:
return points
+ def _prepare_initial_candidates(
+ self,
+ query: str,
+ global_results: List[Dict[str, Any]],
+ mode: str = RetrieverMode.THINKING,
+ ) -> List[Dict[str, Any]]:
+ """Extract level-2 global hits and preserve rerank scores for them."""
+ initial_candidates = [dict(r) for r in global_results if r.get("level", 2) == 2]
+ if not initial_candidates:
+ return []
+
+ default_scores = [r.get("_score", 0.0) for r in initial_candidates]
+ if self._rerank_client and mode == RetrieverMode.THINKING:
+ docs = [str(r.get("abstract", "")) for r in initial_candidates]
+ query_scores = self._rerank_scores(query, docs, default_scores)
+ else:
+ query_scores = default_scores
+
+ for candidate, score in zip(initial_candidates, query_scores):
+ candidate["_score"] = score
+
+ return initial_candidates
+
async def _recursive_search(
self,
vector_proxy: VikingDBManagerProxy,
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index f8b8a3567..42e5e0f23 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -707,8 +707,6 @@ class VikingFS:
TypedQuery,
)
- if not self.rerank_config:
- raise RuntimeError("rerank_config is required for find")
if target_uri and target_uri not in {"/", "viking://"}:
self._ensure_access(target_uri, ctx)
diff --git a/tests/misc/test_vikingfs_find_without_rerank.py b/tests/misc/test_vikingfs_find_without_rerank.py
new file mode 100644
index 000000000..0b008aabd
--- /dev/null
+++ b/tests/misc/test_vikingfs_find_without_rerank.py
@@ -0,0 +1,91 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Regression test for VikingFS.find without rerank configuration."""
+
+import contextvars
+from unittest.mock import MagicMock
+
+import pytest
+
+from openviking.server.identity import RequestContext, Role
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.retrieve.types import ContextType, MatchedContext, QueryResult
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _ctx() -> RequestContext:
+ return RequestContext(user=UserIdentifier("acc1", "user1", "agent1"), role=Role.USER)
+
+
+def _make_viking_fs() -> VikingFS:
+ fs = VikingFS.__new__(VikingFS)
+ fs.agfs = MagicMock()
+ fs.query_embedder = MagicMock(name="embedder")
+ fs.rerank_config = None
+ fs.vector_store = MagicMock(name="vector_store")
+ fs._bound_ctx = contextvars.ContextVar("vikingfs_bound_ctx_test", default=None)
+ fs._ensure_access = MagicMock()
+ fs._get_vector_store = MagicMock(return_value=fs.vector_store)
+ fs._get_embedder = MagicMock(return_value=fs.query_embedder)
+ fs._infer_context_type = MagicMock(return_value=ContextType.RESOURCE)
+ fs._ctx_or_default = MagicMock(return_value=_ctx())
+ return fs
+
+
+async def test_find_works_without_rerank_config(monkeypatch) -> None:
+ fs = _make_viking_fs()
+ request_ctx = _ctx()
+ captured = {}
+
+ class FakeRetriever:
+ def __init__(self, storage, embedder, rerank_config):
+ captured["storage"] = storage
+ captured["embedder"] = embedder
+ captured["rerank_config"] = rerank_config
+
+ async def retrieve(self, typed_query, ctx, limit, score_threshold, scope_dsl):
+ captured["typed_query"] = typed_query
+ captured["ctx"] = ctx
+ captured["limit"] = limit
+ captured["score_threshold"] = score_threshold
+ captured["scope_dsl"] = scope_dsl
+ return QueryResult(
+ query=typed_query,
+ matched_contexts=[
+ MatchedContext(
+ uri="viking://resources/docs/guide.md",
+ context_type=ContextType.RESOURCE,
+ score=0.9,
+ )
+ ],
+ searched_directories=["viking://resources/docs"],
+ )
+
+ monkeypatch.setattr(
+ "openviking.retrieve.hierarchical_retriever.HierarchicalRetriever",
+ FakeRetriever,
+ )
+
+ result = await fs.find(
+ "guide",
+ target_uri="viking://resources/docs",
+ limit=3,
+ score_threshold=0.2,
+ filter={"category": "doc"},
+ ctx=request_ctx,
+ )
+
+ assert result.total == 1
+ assert [ctx.uri for ctx in result.resources] == ["viking://resources/docs/guide.md"]
+ assert captured["storage"] is fs.vector_store
+ assert captured["embedder"] is fs.query_embedder
+ assert captured["rerank_config"] is None
+ assert captured["typed_query"].query == "guide"
+ assert captured["typed_query"].context_type == ContextType.RESOURCE
+ assert captured["typed_query"].target_directories == ["viking://resources/docs"]
+ assert captured["ctx"] == fs._ctx_or_default.return_value
+ assert captured["limit"] == 3
+ assert captured["score_threshold"] == 0.2
+ assert captured["scope_dsl"] == {"category": "doc"}
+ fs._ensure_access.assert_called_once_with("viking://resources/docs", request_ctx)
diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.py
index a7ead7bce..43ac04d6d 100644
--- a/tests/retrieve/test_hierarchical_retriever_rerank.py
+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py
@@ -115,6 +115,73 @@ class DummyStorage:
return []
+class LevelTwoGlobalStorage(DummyStorage):
+ 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/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",
+ },
+ ]
+
+ 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,
+ }
+ )
+ return []
+
+
class FakeRerankClient:
def __init__(self, scores):
self.scores = list(scores)
@@ -180,8 +247,18 @@ def test_merge_starting_points_prefers_rerank_scores_in_thinking_mode(monkeypatc
"hello",
["viking://resources"],
[
- {"uri": "viking://resources/root-a", "abstract": "root A", "_score": 0.2, "level": 1},
- {"uri": "viking://resources/root-b", "abstract": "root B", "_score": 0.8, "level": 1},
+ {
+ "uri": "viking://resources/root-a",
+ "abstract": "root A",
+ "_score": 0.2,
+ "level": 1,
+ },
+ {
+ "uri": "viking://resources/root-b",
+ "abstract": "root B",
+ "_score": 0.8,
+ "level": 1,
+ },
],
mode=RetrieverMode.THINKING,
)
@@ -217,6 +294,29 @@ async def test_retrieve_uses_rerank_scores_in_thinking_mode(monkeypatch):
assert fake_client.calls[1] == ("hello", ["child A", "child B"])
+async def test_retrieve_reranks_level_two_initial_candidates_in_thinking_mode(monkeypatch):
+ fake_client = FakeRerankClient([0.05, 0.95])
+ monkeypatch.setattr(
+ "openviking.retrieve.hierarchical_retriever.RerankClient.from_config",
+ lambda config: fake_client,
+ )
+
+ retriever = HierarchicalRetriever(
+ storage=LevelTwoGlobalStorage(),
+ 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 == [("hello", ["child A", "child B"])]
+
+
@pytest.mark.asyncio
async def test_retrieve_falls_back_to_vector_scores_when_rerank_returns_none(monkeypatch):
class NoneRerankClient(FakeRerankClient):