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
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.mdindex 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.mdindex 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.pyindex 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 Iteratorfrom pathlib import Pathfrom typing import Anydiff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.pyindex 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_scorefrom openviking.retrieve.retrieval_stats import get_stats_collectorfrom openviking.server.identity import RequestContextfrom openviking.storage import VikingDBManager, VikingDBManagerProxy-from openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import get_current_telemetryfrom openviking.utils.time_utils import parse_iso_datetimefrom 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 thresholdeffective_threshold = score_threshold if score_threshold is not None else self.threshold@@ -136,9 +135,10 @@ class HierarchicalRetriever:query_vector = Nonesparse_query_vector = Noneif 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_resultsif 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 summariesrelations = []- 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.pyindex 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 analysisif 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.queriesfor 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_urisdiff --git a/openviking/telemetry/operation.py b/openviking/telemetry/operation.pyindex 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",+ }@staticmethoddef _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:continuepruned_value = cls._prune_zero_metrics(summary[key])diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pyindex 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.asyncioasync 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.pyindex 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 summaryassert "vector" in summaryassert 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 summaryassert "semantic_nodes" not in summaryassert "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.pyindex 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