fix(vector-store): normalize Milvus cosine scores

Author: zc277584121

src/vector_store/milvus.py

@@ -376,16 +376,16 @@ async def query(
 
         results: list[VectorQueryResult] = []
         for hit in batches[0] if batches else []:
-            distance = float(hit.get("distance", 0.0))
-            if max_distance is not None and distance > max_distance:
+            cosine_distance = self._hit_cosine_distance(hit)
+            if max_distance is not None and cosine_distance > max_distance:
                 continue
 
             entity = cast(dict[str, Any], hit.get("entity") or {})
             vector_id = str(hit.get(ID_FIELD) or entity.get(ID_FIELD))
             results.append(
                 VectorQueryResult(
                     id=vector_id,
-                    score=distance,
+                    score=cosine_distance,
                     metadata=self._entity_metadata(entity),
                 )
             )
@@ -397,6 +397,14 @@ async def query(
         )
         return results
 
+    def _hit_cosine_distance(self, hit: dict[str, Any]) -> float:
+        """Return Honcho cosine distance from a Milvus search hit."""
+        if "distance" in hit:
+            return float(hit["distance"])
+        if "score" in hit:
+            return 1.0 - float(hit["score"])
+        return 0.0
+
     def _output_fields(self, include_attributes: bool | list[str]) -> list[str] | None:
         """Translate Honcho projection settings to Milvus output fields."""
         if include_attributes is True:

tests/vector_store/test_milvus.py

@@ -5,6 +5,7 @@
 import logging
 import re
 from pathlib import Path
+from typing import Any, cast
 
 import pytest
 
@@ -23,6 +24,29 @@ def _helper_store() -> MilvusVectorStore:
     return object.__new__(MilvusVectorStore)
 
 
+class _ScoreOnlySearchClient:
+    def has_collection(self, *, collection_name: str) -> bool:
+        assert collection_name
+        return True
+
+    def search(self, **kwargs: Any) -> list[list[dict[str, Any]]]:
+        assert kwargs["search_params"] == {"metric_type": "COSINE"}
+        return [
+            [
+                {
+                    "id": "vec_close",
+                    "score": 0.9,
+                    "entity": {"message_id": "msg_1"},
+                },
+                {
+                    "id": "vec_far",
+                    "score": 0.2,
+                    "entity": {"message_id": "msg_2"},
+                },
+            ]
+        ]
+
+
 def test_collection_name_is_valid_stable_and_bounded() -> None:
     store = _helper_store()
     namespace = "honcho.doc." + ("workspace.with-dashes" * 30)
@@ -72,6 +96,25 @@ def test_projection_settings_map_to_milvus_output_fields() -> None:
     ]
 
 
+@pytest.mark.asyncio
+async def test_query_converts_milvus_score_to_cosine_distance(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(settings.EMBEDDING, "VECTOR_DIMENSIONS", 4)
+    store = _helper_store()
+    store.client = cast(Any, _ScoreOnlySearchClient())
+
+    results = await store.query(
+        "honcho.msg.test",
+        [1.0, 0.0, 0.0, 0.0],
+        max_distance=0.5,
+    )
+
+    assert [result.id for result in results] == ["vec_close"]
+    assert abs(results[0].score - 0.1) < 1e-12
+    assert results[0].metadata == {"message_id": "msg_1"}
+
+
 @pytest.mark.asyncio
 async def test_milvus_lite_round_trip(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path