Skip to content

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

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.md
index 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 content
overview: 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 pipeline
match_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.md
index 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.models
diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
index 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.md
index 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.models
diff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.py
index 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 None
status = (
{
- "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.md
index 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 更新索引
```python
diff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.py
index 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, Vect
logger = 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 meta
return 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_operation
diff --git a/tests/server/test_api_observer.py b/tests/server/test_api_observer.py
index 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 == 200
body = 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):