Skip to content

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

Feature/search telemetry relations control (#2547)

Jiahui Zhou27e90ad9cdff
diff --git a/docs/en/guides/07-operation-telemetry.md b/docs/en/guides/07-operation-telemetry.md
index 27c6c5bee..3180fa482 100644
--- a/docs/en/guides/07-operation-telemetry.md
+++ b/docs/en/guides/07-operation-telemetry.md
@@ -243,6 +243,16 @@ This group appears on memory-extraction flows such as `session.commit`.
| `summary.memory.extract.stages.create_relations_ms` | Time spent creating used-URI relations |
| `summary.memory.extract.stages.flush_semantic_ms` | Time spent flushing semantic queue work |
+### `summary.search`
+
+| Field | Meaning |
+| --- | --- |
+| `summary.search.target_abstract.duration_ms` | Time spent prefetching abstracts for target URIs |
+| `summary.search.intent_analysis.duration_ms` | Time spent analyzing query intent |
+| `summary.search.embed_query.duration_ms` | Time spent embedding the query |
+| `summary.search.vector_retrieval.duration_ms` | Time spent in vector retrieval |
+| `summary.search.typed_queries_count` | Number of typed queries produced during planning |
+
### `summary.errors`
| Field | Meaning |
diff --git a/docs/zh/guides/07-operation-telemetry.md b/docs/zh/guides/07-operation-telemetry.md
index 4bb74e1cd..d6ad74c63 100644
--- a/docs/zh/guides/07-operation-telemetry.md
+++ b/docs/zh/guides/07-operation-telemetry.md
@@ -243,6 +243,16 @@ summary 顶层这 3 个基础字段总会存在:
| `summary.memory.extract.stages.create_relations_ms` | 创建 used-uri relations 的耗时 |
| `summary.memory.extract.stages.flush_semantic_ms` | flush semantic queue 的耗时 |
+### `summary.search`
+
+| 字段 | 含义 |
+| --- | --- |
+| `summary.search.target_abstract.duration_ms` | 为目标 URI 预取摘要的耗时 |
+| `summary.search.intent_analysis.duration_ms` | 查询意图分析耗时 |
+| `summary.search.embed_query.duration_ms` | 查询向量化耗时 |
+| `summary.search.vector_retrieval.duration_ms` | 向量召回阶段耗时 |
+| `summary.search.typed_queries_count` | 解析出的 typed query 数量 |
+
### `summary.errors`
| 字段 | 含义 |
diff --git a/openviking/pyagfs/helpers.py b/openviking/pyagfs/helpers.py
index 5483a05f0..e3a58cf77 100644
--- a/openviking/pyagfs/helpers.py
+++ b/openviking/pyagfs/helpers.py
@@ -6,6 +6,8 @@ This module provides high-level helper functions for common operations:
- download: Download files/directories from AGFS to local filesystem
"""
+from __future__ import annotations
+
from collections.abc import Iterator
from pathlib import Path
from typing import Any
diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.py
index 9d79a1710..62782bf36 100644
--- a/openviking/retrieve/hierarchical_retriever.py
+++ b/openviking/retrieve/hierarchical_retriever.py
@@ -22,14 +22,12 @@ from openviking.retrieve.memory_lifecycle import hotness_score
from openviking.retrieve.retrieval_stats import get_stats_collector
from openviking.server.identity import RequestContext
from openviking.storage import VikingDBManager, VikingDBManagerProxy
-from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import get_current_telemetry
from openviking.utils.time_utils import parse_iso_datetime
from openviking_cli.retrieve.types import (
ContextType,
MatchedContext,
QueryResult,
- RelatedContext,
TypedQuery,
)
from openviking_cli.utils.config import RerankConfig, RetrievalConfig
@@ -113,6 +111,7 @@ class HierarchicalRetriever:
scope_dsl: Additional scope constraints passed from public find/search filter
"""
t0 = time.monotonic()
+ telemetry = get_current_telemetry()
# Use custom threshold or default threshold
effective_threshold = score_threshold if score_threshold is not None else self.threshold
@@ -136,9 +135,10 @@ class HierarchicalRetriever:
query_vector = None
sparse_query_vector = None
if self.embedder:
- result: EmbedResult = await embed_compat(self.embedder, query.query, is_query=True)
- query_vector = result.dense_vector
- sparse_query_vector = result.sparse_vector
+ with telemetry.measure("search.embed_query"):
+ result: EmbedResult = await embed_compat(self.embedder, query.query, is_query=True)
+ query_vector = result.dense_vector
+ sparse_query_vector = result.sparse_vector
# Step 1: Determine starting directories based on explicit target dirs.
if target_dirs:
@@ -147,15 +147,16 @@ class HierarchicalRetriever:
root_uris = default_target_directories(ctx, context_type=query.context_type)
# Step 2: Global vector search to supplement starting points
- global_results = await self._global_vector_search(
- vector_proxy=vector_proxy,
- query_vector=query_vector,
- sparse_query_vector=sparse_query_vector,
- context_type=query.context_type.value if query.context_type else None,
- target_dirs=target_dirs,
- scope_dsl=scope_dsl,
- limit=max(limit, self.GLOBAL_SEARCH_TOPK),
- )
+ with telemetry.measure("search.vector_retrieval"):
+ global_results = await self._global_vector_search(
+ vector_proxy=vector_proxy,
+ query_vector=query_vector,
+ sparse_query_vector=sparse_query_vector,
+ context_type=query.context_type.value if query.context_type else None,
+ target_dirs=target_dirs,
+ scope_dsl=scope_dsl,
+ limit=max(limit, self.GLOBAL_SEARCH_TOPK),
+ )
# Debug: Print all URIs in global_results
if logger.isEnabledFor(logging.DEBUG):
@@ -195,25 +196,29 @@ class HierarchicalRetriever:
)
# Step 4: Recursive search
- candidates = await self._recursive_search(
- vector_proxy=vector_proxy,
- query=query.query,
- query_vector=query_vector,
- sparse_query_vector=sparse_query_vector,
- starting_points=starting_points,
- limit=limit,
- mode=mode,
- threshold=effective_threshold,
- score_gte=score_gte,
- context_type=query.context_type.value if query.context_type else None,
- target_dirs=target_dirs,
- scope_dsl=scope_dsl,
- initial_candidates=initial_candidates,
- level=level,
- )
+ with telemetry.measure("search.vector_retrieval"):
+ candidates = await self._recursive_search(
+ vector_proxy=vector_proxy,
+ query=query.query,
+ query_vector=query_vector,
+ sparse_query_vector=sparse_query_vector,
+ starting_points=starting_points,
+ limit=limit,
+ mode=mode,
+ threshold=effective_threshold,
+ score_gte=score_gte,
+ context_type=query.context_type.value if query.context_type else None,
+ target_dirs=target_dirs,
+ scope_dsl=scope_dsl,
+ initial_candidates=initial_candidates,
+ level=level,
+ )
# Step 6: Convert results
- matched = await self._convert_to_matched_contexts(candidates, ctx=ctx)
+ matched = await self._convert_to_matched_contexts(
+ candidates,
+ ctx=ctx,
+ )
final = matched[:limit]
@@ -549,20 +554,8 @@ class HierarchicalRetriever:
is controlled by ``retrieval.hotness_alpha`` (0 disables the boost).
"""
results = []
-
for c in candidates:
- # Read related contexts and get summaries
relations = []
- if get_viking_fs():
- related_uris = await get_viking_fs().get_relations(c.get("uri", ""), ctx=ctx)
- if related_uris:
- related_abstracts = await get_viking_fs().read_batch(
- related_uris[: self.MAX_RELATIONS], level="l0", ctx=ctx
- )
- for uri in related_uris[: self.MAX_RELATIONS]:
- abstract = related_abstracts.get(uri, "")
- if abstract:
- relations.append(RelatedContext(uri=uri, abstract=abstract))
semantic_score = c.get("_final_score", c.get("_score", 0.0))
# Fix: clamp inf/nan scores from vector search (#inf-score)
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 79643650c..72ed93a93 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -1367,19 +1367,21 @@ class VikingFS:
target_abstract = ""
if primary_target_uri:
try:
- target_abstract = await self.abstract(primary_target_uri, ctx=ctx)
+ with telemetry.measure("search.target_abstract"):
+ target_abstract = await self.abstract(primary_target_uri, ctx=ctx)
except Exception:
target_abstract = ""
# With session context: intent analysis
if session_summary or current_messages:
analyzer = IntentAnalyzer(max_recent_messages=5)
- query_plan = await analyzer.analyze(
- compression_summary=session_summary or "",
- messages=current_messages or [],
- current_message=query,
- target_abstract=target_abstract,
- )
+ with telemetry.measure("search.intent_analysis"):
+ query_plan = await analyzer.analyze(
+ compression_summary=session_summary or "",
+ messages=current_messages or [],
+ current_message=query,
+ target_abstract=target_abstract,
+ )
typed_queries = query_plan.queries
for tq in typed_queries:
tq.target_directories = retrieval_targets.target_directories
@@ -2390,10 +2392,11 @@ class VikingFS:
async def get_relations(self, uri: str, ctx: Optional[RequestContext] = None) -> List[str]:
"""Get all related URIs (backward compatible)."""
entries = await self.get_relation_table(uri, ctx=ctx)
+ real_ctx = self._ctx_or_default(ctx)
all_uris = []
for entry in entries:
for related in entry.uris:
- if self._is_accessible(related, self._ctx_or_default(ctx)):
+ if self._is_accessible(related, real_ctx):
all_uris.append(related)
return all_uris
diff --git a/openviking/telemetry/operation.py b/openviking/telemetry/operation.py
index 9d5343e2d..95fee9d0a 100644
--- a/openviking/telemetry/operation.py
+++ b/openviking/telemetry/operation.py
@@ -62,6 +62,12 @@ class TelemetrySummaryBuilder:
"summarize": "resource.flags.summarize",
"watch_enabled": "resource.flags.watch_enabled",
}
+ _SEARCH_DURATION_KEYS = {
+ "target_abstract": "search.target_abstract.duration_ms",
+ "intent_analysis": "search.intent_analysis.duration_ms",
+ "embed_query": "search.embed_query.duration_ms",
+ "vector_retrieval": "search.vector_retrieval.duration_ms",
+ }
@staticmethod
def _i(value: Any, default: int = 0) -> int:
@@ -163,9 +169,7 @@ class TelemetrySummaryBuilder:
llm_output_tokens = cls._i(counters.get("tokens.llm.output"), 0)
llm_total_tokens = cls._i(counters.get("tokens.llm.total"), 0)
llm_prompt_cached_tokens = cls._i(counters.get("tokens.llm.prompt_cached"), 0)
- llm_completion_reasoning_tokens = cls._i(
- counters.get("tokens.llm.completion_reasoning"), 0
- )
+ llm_completion_reasoning_tokens = cls._i(counters.get("tokens.llm.completion_reasoning"), 0)
embedding_total_tokens = cls._i(counters.get("tokens.embedding.total"), 0)
rerank_total_tokens = cls._i(counters.get("tokens.rerank.total"), 0)
stage_token_summary = cls._build_stage_token_summary(counters)
@@ -286,6 +290,18 @@ class TelemetrySummaryBuilder:
},
}
+ if cls._has_metric_prefix("search", counters, gauges):
+ search_summary = {
+ public_key: {
+ "duration_ms": cls._f(gauges.get(metric_key), 0.0),
+ }
+ for public_key, metric_key in cls._SEARCH_DURATION_KEYS.items()
+ }
+ typed_queries_count = gauges.get("search.typed_queries_count")
+ if typed_queries_count is not None:
+ search_summary["typed_queries_count"] = cls._i(typed_queries_count, 0)
+ summary["search"] = search_summary
+
if error_stage or error_code or error_message:
summary["errors"] = {
"stage": error_stage,
@@ -293,7 +309,16 @@ class TelemetrySummaryBuilder:
"message": error_message,
}
- for key in ("tokens", "queue", "vector", "semantic_nodes", "memory", "resource", "errors"):
+ for key in (
+ "tokens",
+ "queue",
+ "vector",
+ "semantic_nodes",
+ "memory",
+ "resource",
+ "search",
+ "errors",
+ ):
if key not in summary:
continue
pruned_value = cls._prune_zero_metrics(summary[key])
diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.py
index f01bea55e..1c5ab89de 100644
--- a/tests/retrieve/test_hierarchical_retriever_rerank.py
+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py
@@ -19,9 +19,15 @@ class DummyEmbedResult:
class DummyEmbedder:
+ def prepare_embedding_input(self, text: str) -> str:
+ return text
+
def embed(self, _query: str, is_query: bool = False) -> DummyEmbedResult:
return DummyEmbedResult()
+ async def embed_async(self, text: str, is_query: bool = False) -> DummyEmbedResult:
+ return self.embed(text, is_query=is_query)
+
class DummyStorage:
def __init__(self) -> None:
@@ -237,11 +243,6 @@ 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])
@@ -325,7 +326,7 @@ async def test_retrieve_uses_rerank_scores_in_thinking_mode(monkeypatch):
@pytest.mark.asyncio
async def test_retrieve_reranks_level_two_initial_candidates_in_thinking_mode(monkeypatch):
- fake_client = FakeRerankClient([0.05, 0.95])
+ fake_client = FakeRerankClient([0.11, 0.95])
monkeypatch.setattr(
"openviking.retrieve.hierarchical_retriever.RerankClient.from_config",
lambda config: fake_client,
@@ -475,3 +476,27 @@ async def test_retrieval_hotness_alpha_blends_when_configured(monkeypatch):
)
assert result[0].score == pytest.approx(0.9)
+
+
+async def test_convert_to_matched_contexts_returns_empty_relations():
+ retriever = HierarchicalRetriever(
+ storage=DummyStorage(),
+ embedder=None,
+ rerank_config=None,
+ )
+
+ result = await retriever._convert_to_matched_contexts(
+ [
+ {
+ "uri": "viking://resources/file-a",
+ "abstract": "child A",
+ "_score": 1.0,
+ "level": 2,
+ "context_type": "resource",
+ }
+ ],
+ ctx=_ctx(),
+ )
+
+ assert result[0].relations == []
diff --git a/tests/server/test_api_search.py b/tests/server/test_api_search.py
index 86e9db46f..634cdff67 100644
--- a/tests/server/test_api_search.py
+++ b/tests/server/test_api_search.py
@@ -561,6 +561,10 @@ async def test_find_telemetry_metrics(client_with_resource):
assert "tokens" not in summary
assert "vector" in summary
assert summary["vector"]["searches"] >= 0
+ assert "search" in summary
+ assert "vector_retrieval" in summary["search"]
+ assert "result_convert" not in summary["search"]
+ assert "request" not in summary["search"]
assert "queue" not in summary
assert "semantic_nodes" not in summary
assert "memory" not in summary
@@ -579,6 +583,10 @@ async def test_search_telemetry_metrics(client_with_resource):
body = resp.json()
summary = body["telemetry"]["summary"]
assert summary["operation"] == "search.search"
+ assert "search" in summary
+ assert "vector_retrieval" in summary["search"]
+ assert "result_convert" not in summary["search"]
+ assert "request" not in summary["search"]
if body["result"]["total"] > 0:
assert summary["vector"]["returned"] == body["result"]["total"]
else:
diff --git a/tests/telemetry/test_execution.py b/tests/telemetry/test_execution.py
index 7b4afc25e..7abe2077c 100644
--- a/tests/telemetry/test_execution.py
+++ b/tests/telemetry/test_execution.py
@@ -120,6 +120,27 @@ def test_operation_telemetry_summary_includes_resource_breakdown():
}
+def test_operation_telemetry_summary_includes_search_breakdown():
+ from openviking.telemetry.operation import OperationTelemetry
+
+ telemetry = OperationTelemetry(operation="search.find", enabled=True)
+ telemetry.set("search.target_abstract.duration_ms", 18.4)
+ telemetry.set("search.intent_analysis.duration_ms", 24.6)
+ telemetry.set("search.embed_query.duration_ms", 11.3)
+ telemetry.set("search.vector_retrieval.duration_ms", 88.1)
+ telemetry.set("search.typed_queries_count", 3)
+
+ summary = telemetry.finish().summary
+
+ assert summary["search"] == {
+ "target_abstract": {"duration_ms": 18.4},
+ "intent_analysis": {"duration_ms": 24.6},
+ "embed_query": {"duration_ms": 11.3},
+ "vector_retrieval": {"duration_ms": 88.1},
+ "typed_queries_count": 3,
+ }
+
+
def test_operation_telemetry_summary_omits_zero_valued_fields():
from openviking.telemetry.operation import OperationTelemetry