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
feat(observer): report vector metric and score scale (#5488)
Lusen Donga0421f015b71
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.mdindex 9577e8931..b54bb88c5 100644--- a/docs/en/api/06-retrieval.md+++ b/docs/en/api/06-retrieval.md@@ -103,10 +103,12 @@ class MatchedContext:abstract: str # L0 contentoverview: Optional[str] # L1 overview (optional for non-leaf nodes)category: str # Category- score: float # Relevance score (0-1)+ score: float # Relevance score; scale depends on the retrieval pipelinematch_reason: str # Why this matched```+`score` is not universally bounded to `[0, 1]`: its scale depends on the backend, metric and postprocessing. See [observer.vikingdb](18-observer.md#observer-vikingdb) for the runtime metric, pure-dense scale and its scope.+#### 3. Usage Examples**HTTP API**diff --git a/docs/en/api/18-observer.md b/docs/en/api/18-observer.mdindex b6bfdeadb..a87bc883e 100644--- a/docs/en/api/18-observer.md+++ b/docs/en/api/18-observer.md@@ -89,28 +89,29 @@ ov observer queue#### 1. API Implementation Overview-Get VikingDB status (collections, indexes, vector counts).+Get VikingDB status. The structured representation also reports the effective vector metric and pure-dense score scale when the backend can determine them from the loaded index.**Code Entry Points**:- `openviking/server/routers/observer.py:observer_vikingdb` - HTTP route-- `openviking/service/debug_service.py:ObserverService.vikingdb` - Core implementation-- `openviking/storage/observers/vikingdb_observer.py` - VikingDB observer+- `openviking/service/debug_service.py:ObserverService.account_vikingdb` - Core implementation- `crates/ov_cli/src/commands/observer.rs` - CLI command#### 2. Interface and Parameters-No parameters.+| Parameter | Type | Required | Default | Description |+| --- | --- | --- | --- | --- |+| `format` | string | No | `table` | `table` returns the existing human-readable status; `json` returns structured runtime details. |#### 3. Usage Examples**HTTP API**```-GET /api/v1/observer/vikingdb+GET /api/v1/observer/vikingdb?format=json``````bash-curl -X GET http://localhost:1933/api/v1/observer/vikingdb \+curl -X GET 'http://localhost:1933/api/v1/observer/vikingdb?format=json' \-H "X-API-Key: your-key"```@@ -160,12 +161,24 @@ ov observer vikingdb"name": "vikingdb","is_healthy": true,"has_errors": false,- "status": "Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55"+ "status": {+ "backend": "local",+ "collection": "context",+ "index": "default",+ "dimension": 1024,+ "vector_count": 55,+ "distance_metric": "cosine",+ "pure_dense_score_scale": "cosine_affine_0_1"+ }},"time": 0.1}```+For the local backend, `pure_dense_score_scale` is `cosine_affine_0_1`, `inner_product`, or `one_minus_squared_l2` for cosine, IP, or L2 respectively. Other backends report `backend_defined`; `distance_metric` is `null` when their loaded metadata does not expose it.++The field describes only a pure-dense vector score. Sparse fusion, time decay, reranking, and other retrieval stages can produce a different final `score` scale. Since v0.4.22, local pure-dense cosine uses `clamp((cosine_similarity + 1) / 2, 0, 1)`, including for existing indexes.+---### observer.modelsdiff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.mdindex 564bff9f4..73784d153 100644--- a/docs/zh/api/06-retrieval.md+++ b/docs/zh/api/06-retrieval.md@@ -104,10 +104,12 @@ class MatchedContext:abstract: str # L0 内容overview: Optional[str] # L1 概览(非叶子节点时可选)category: str # 分类- score: float # 相关性分数 (0-1)+ score: float # 相关性分数,尺度取决于检索流程match_reason: str # 匹配原因```+`score` 并非总在 `[0, 1]` 内,其尺度取决于后端、metric 和后处理。运行时 metric、纯 dense 尺度及其适用范围见 [observer.vikingdb](18-observer.md#observer-vikingdb)。+#### 3. 使用示例**HTTP API**diff --git a/docs/zh/api/18-observer.md b/docs/zh/api/18-observer.mdindex 980f94115..b520f0d9f 100644--- a/docs/zh/api/18-observer.md+++ b/docs/zh/api/18-observer.md@@ -89,28 +89,29 @@ ov observer queue#### 1. API 实现介绍-获取 VikingDB 状态(集合、索引、向量数量)。+获取 VikingDB 状态。结构化响应还会在后端能够从已加载索引中确定时,返回实际向量 metric 和纯 dense 分数尺度。**代码入口**:- `openviking/server/routers/observer.py:observer_vikingdb` - HTTP 路由-- `openviking/service/debug_service.py:ObserverService.vikingdb` - 核心实现-- `openviking/storage/observers/vikingdb_observer.py` - VikingDB 观察者+- `openviking/service/debug_service.py:ObserverService.account_vikingdb` - 核心实现- `crates/ov_cli/src/commands/observer.rs` - CLI 命令#### 2. 接口和参数说明-无参数。+| 参数 | 类型 | 必填 | 默认值 | 说明 |+| --- | --- | --- | --- | --- |+| `format` | string | 否 | `table` | `table` 返回原有可读状态;`json` 返回结构化运行时详情。 |#### 3. 使用示例**HTTP API**```-GET /api/v1/observer/vikingdb+GET /api/v1/observer/vikingdb?format=json``````bash-curl -X GET http://localhost:1933/api/v1/observer/vikingdb \+curl -X GET 'http://localhost:1933/api/v1/observer/vikingdb?format=json' \-H "X-API-Key: your-key"```@@ -160,12 +161,24 @@ ov observer vikingdb"name": "vikingdb","is_healthy": true,"has_errors": false,- "status": "Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55"+ "status": {+ "backend": "local",+ "collection": "context",+ "index": "default",+ "dimension": 1024,+ "vector_count": 55,+ "distance_metric": "cosine",+ "pure_dense_score_scale": "cosine_affine_0_1"+ }},"time": 0.1}```+对于 local 后端,cosine、IP 和 L2 对应的 `pure_dense_score_scale` 分别为 `cosine_affine_0_1`、`inner_product` 和 `one_minus_squared_l2`。其他后端返回 `backend_defined`;如果已加载的元数据没有暴露 metric,`distance_metric` 为 `null`。++该字段只描述纯 dense 向量分数。稀疏融合、时间衰减、rerank 等检索阶段可能产生不同尺度的最终 `score`。从 v0.4.22 起,local 纯 dense cosine 使用 `clamp((cosine_similarity + 1) / 2, 0, 1)`,已有索引也适用。+---### observer.modelsdiff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.pyindex 947c6368c..5aaa1438b 100644--- a/openviking/service/debug_service.py+++ b/openviking/service/debug_service.py@@ -365,19 +365,26 @@ class ObserverService:try:backend = await self._vikingdb.get_account_backend(ctx.account_id)healthy = await backend.health_check()- count = await backend.count() if healthy else 0+ info = await backend.get_collection_info() if healthy else Nonestatus = ({- "backend": backend._mode,- "collection": backend._collection_name,- "index": backend._index_name,- "dimension": backend.vector_dim,- "vector_count": count,+ "backend": info.get("backend") if info else backend._mode,+ "collection": info.get("name") if info else backend._collection_name,+ "index": info.get("index_name") if info else backend._index_name,+ "dimension": info.get("vector_dim") if info else backend.vector_dim,+ "vector_count": info.get("count", 0) if info else 0,+ "distance_metric": info.get("distance_metric") if info else None,+ "pure_dense_score_scale": (+ info.get("pure_dense_score_scale", "backend_defined")+ if info+ else "backend_defined"+ ),}if format == "json"else f"Account: {ctx.account_id}\nBackend: {backend._mode}\n"f"Collection: {backend._collection_name}\nIndex: {backend._index_name}\n"- f"Dimension: {backend.vector_dim}\nVector count: {count}"+ f"Dimension: {backend.vector_dim}\nVector count: "+ f"{info.get('count', 0) if info else 0}")return ComponentStatus(name="vikingdb",@@ -404,6 +411,8 @@ class ObserverService:"index": None,"dimension": None,"vector_count": 0,+ "distance_metric": None,+ "pure_dense_score_scale": "backend_defined","error": str(exc),}if format == "json"diff --git a/openviking/storage/vectordb/README.md b/openviking/storage/vectordb/README.mdindex 009050d40..64981a2ec 100644--- a/openviking/storage/vectordb/README.md+++ b/openviking/storage/vectordb/README.md@@ -444,6 +444,14 @@ for idx_name in indexes:print(f" - {idx_name}")```+#### 磁盘索引格式与 cosine 分数++本地 `index_meta.json` 的 `VectorIndex` 保存的是引擎内部表示。用户设置 `"Distance": "cosine"` 时,磁盘上会写成 `"Distance": "ip"` 加 `"NormalizeVector": true`,表示归一化后的内积,即 **cosine**。只有 `"NormalizeVector": false` 的 IP 索引才是普通内积。离线检查、审计或备份工具必须同时读取这两个字段,不能仅凭 `"Distance": "ip"` 判断 cosine 分数变更不适用。++`IndexMeta._get_user_meta()` 会反向转换;`collection.get_index_meta_data(index_name)` 返回用户可见的 `"Distance": "cosine"`。这个磁盘格式不记录引擎分数尺度:从 v0.4.22 起,local 的纯 dense cosine 分数使用 `clamp((cosine_similarity + 1) / 2, 0, 1)`,无需重建已有索引。普通 IP 分数不变,仍为内积。稀疏融合、时间衰减和 rerank 等处理后的分数不能直接套用此公式。++运行时可通过 [`GET /api/v1/observer/vikingdb?format=json`](../../../docs/zh/api/18-observer.md#observer-vikingdb) 查询当前账户索引的实际 metric 和纯 dense 分数尺度。+#### 3.2 更新索引```pythondiff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.pyindex 42fcca685..18b82f073 100644--- a/openviking/storage/viking_vector_index_backend.py+++ b/openviking/storage/viking_vector_index_backend.py@@ -51,6 +51,12 @@ from openviking_cli.utils.config.vectordb_config import DEFAULT_INDEX_NAME, Vectlogger = get_logger(__name__)+_LOCAL_PURE_DENSE_SCORE_SCALES = {+ "cosine": "cosine_affine_0_1",+ "ip": "inner_product",+ "l2": "one_minus_squared_l2",+}+RETRIEVAL_OUTPUT_FIELDS = ["uri","level",@@ -237,8 +243,9 @@ class _AsyncVectorAdapter:) or {}if self._adapter.mode in {"local", "cuvs"}:index_meta = collection.get_index_meta_data(index_name) or {}- if "ScalarIndex" in index_meta:- meta["ScalarIndex"] = index_meta["ScalarIndex"]+ for key in ("VectorIndex", "ScalarIndex"):+ if key in index_meta:+ meta[key] = index_meta[key]return metareturn await self.run(_get)@@ -510,12 +517,40 @@ class _SingleAccountBackend:async def get_collection_info(self) -> Optional[Dict[str, Any]]:if not await self.collection_exists():return None- config = self._collection_config+ meta = (+ await self._async_adapter.collection_meta(self._index_name)+ if self._mode in {"local", "cuvs"}+ else {}+ )+ vector_index = meta.get("VectorIndex") or {}+ distance_metric = vector_index.get("Distance")+ if not isinstance(distance_metric, str):+ distance_metric = None+ vector_dim = (+ vector_index.get("Dimension")+ or self._collection_config.get("vector_dim")+ or next(+ (+ field.get("Dim")+ for field in meta.get("Fields", [])+ if field.get("FieldType") == "vector"+ ),+ None,+ )+ )return {"name": self._collection_name,- "vector_dim": config.get("vector_dim"),+ "backend": self._mode,+ "index_name": self._index_name,+ "vector_dim": vector_dim,"count": await self.count(),"status": "active",+ "distance_metric": distance_metric,+ "pure_dense_score_scale": (+ _LOCAL_PURE_DENSE_SCORE_SCALES.get(distance_metric, "backend_defined")+ if self._mode == "local" and distance_metric is not None+ else "backend_defined"+ ),}@_backend_operationdiff --git a/tests/server/test_api_observer.py b/tests/server/test_api_observer.pyindex 40cfd3991..38baec111 100644--- a/tests/server/test_api_observer.py+++ b/tests/server/test_api_observer.py@@ -36,15 +36,27 @@ async def test_observer_queue_structured(client: httpx.AsyncClient):assert isinstance(result["status"]["summary"], dict)-async def test_observer_vikingdb(client: httpx.AsyncClient):- """GET /api/v1/observer/vikingdb should return VikingDB status."""- resp = await client.get("/api/v1/observer/vikingdb")+async def test_observer_vikingdb(client: httpx.AsyncClient, service):+ """VikingDB status should preserve table output and expose loaded index semantics."""+ table_resp = await client.get("/api/v1/observer/vikingdb")+ assert table_resp.status_code == 200+ assert isinstance(table_resp.json()["result"]["status"], str)++ manager = service.vikingdb_manager+ assert manager is not None+ backend = await manager.get_account_backend("default")+ backend._distance_metric = "l2"++ resp = await client.get("/api/v1/observer/vikingdb", params={"format": "json"})assert resp.status_code == 200body = resp.json()assert body["status"] == "ok"result = body["result"]- assert "name" in result- assert "is_healthy" in result+ assert result["name"] == "vikingdb"+ assert result["is_healthy"] is True+ assert result["status"]["backend"] == "local"+ assert result["status"]["distance_metric"] == "cosine"+ assert result["status"]["pure_dense_score_scale"] == "cosine_affine_0_1"async def test_observer_models(client: httpx.AsyncClient):