Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(vector-store): rank Euclidean results by distance in Qdrant and Pinecone (#2116)

Tymurba38aa270b56
diff --git a/semantica/vector_store/pinecone_store.py b/semantica/vector_store/pinecone_store.py
index 43bd3616..0119d369 100644
--- a/semantica/vector_store/pinecone_store.py
+++ b/semantica/vector_store/pinecone_store.py
@@ -81,7 +81,7 @@ class PineconeClient:
# Map metric names
metric_map = {
"cosine": "cosine",
- "euclidean": "euclidean_distance",
+ "euclidean": "euclidean",
"dot": "dotproduct",
}
pinecone_metric = metric_map.get(metric.lower(), "cosine")
@@ -129,13 +129,30 @@ class PineconeClient:
except Exception as e:
raise ProcessingError(f"Failed to get index: {str(e)}")
+ def get_index_metric(self, index_name: str) -> Optional[str]:
+ """Read the metric from the control-plane index description."""
+ try:
+ description = self.client.describe_index(index_name)
+ metric = (
+ description.get("metric")
+ if isinstance(description, dict)
+ else description.metric
+ )
+ return metric if isinstance(metric, str) else None
+ except Exception as e:
+ self.logger.warning(
+ f"Could not determine index metric for '{index_name}': {e}"
+ )
+ return None
+
class PineconeIndex:
"""Pinecone index wrapper."""
- def __init__(self, index: Any):
+ def __init__(self, index: Any, metric: Optional[str] = None):
"""Initialize Pinecone index wrapper."""
self.index = index
+ self.metric = metric
self.logger = get_logger("pinecone_index")
def upsert_vectors(
@@ -191,19 +208,16 @@ class PineconeIndex:
results = []
for match in response.matches:
+ score = float(match.score)
+ if self.metric == "euclidean":
+ similarity = 1.0 / (1.0 + max(0.0, score))
+ else:
+ # Preserve the existing normalization for cosine and dotproduct.
+ similarity = (score / (1.0 + abs(score)) + 1.0) / 2.0
results.append(
{
"id": match.id,
- # Pinecone's native score is already "higher is better" but its
- # range depends on the configured metric (bounded for cosine,
- # unbounded for dotproduct). Squash with x/(1+|x|) instead of
- # clamping distance-to-zero, since the latter collapses every
- # score >= 1.0 to an identical 1.0 and destroys ranking order
- # for dotproduct/unnormalized-vector indexes.
- "score": (
- float(match.score) / (1.0 + abs(float(match.score))) + 1.0
- )
- / 2.0,
+ "score": similarity,
"metadata": match.metadata or {},
"vector": None,
"distance": None,
@@ -441,7 +455,9 @@ class PineconeStore:
# Get the index
pinecone_index = self.client.get_index(index_name)
- self.index = PineconeIndex(pinecone_index)
+ self.index = PineconeIndex(
+ pinecone_index, metric=self.client.get_index_metric(index_name)
+ )
self.search_engine = PineconeSearch(self.index)
self.dimension = dimension
@@ -469,7 +485,9 @@ class PineconeStore:
try:
pinecone_index = self.client.get_index(index_name)
- self.index = PineconeIndex(pinecone_index)
+ self.index = PineconeIndex(
+ pinecone_index, metric=self.client.get_index_metric(index_name)
+ )
self.search_engine = PineconeSearch(self.index)
if self.dimension is None:
try:
diff --git a/semantica/vector_store/qdrant_store.py b/semantica/vector_store/qdrant_store.py
index 6e6b85b6..faa193f5 100644
--- a/semantica/vector_store/qdrant_store.py
+++ b/semantica/vector_store/qdrant_store.py
@@ -126,6 +126,7 @@ class QdrantCollection:
"""Initialize Qdrant collection wrapper."""
self.client = client
self.collection_name = collection_name
+ self._vectors_config = None
self.logger = get_logger("qdrant_collection")
def upsert_points(self, points: List[PointStruct], **options) -> Dict[str, Any]:
@@ -153,6 +154,17 @@ class QdrantCollection:
raise ProcessingError("Qdrant not available")
try:
+ if self._vectors_config is None:
+ try:
+ info = self.client.get_collection(self.collection_name)
+ self._vectors_config = info.config.params.vectors
+ except Exception as e:
+ self.logger.warning(f"Could not determine collection distance: {e}")
+ vector_config = self._vectors_config
+ if isinstance(vector_config, dict):
+ vector_config = vector_config.get(options.get("using"))
+ distance = getattr(vector_config, "distance", None)
+
# qdrant-client >=1.10.0: query_points() supersedes the removed search().
# It returns a QueryResponse whose .points attribute is a list of
# ScoredPoint objects (id, score, payload, …).
@@ -168,17 +180,16 @@ class QdrantCollection:
results = []
for point in response.points:
+ score = float(point.score)
+ if distance in ("Euclid", "Manhattan"):
+ similarity = 1.0 / (1.0 + max(0.0, score))
+ else:
+ # Preserve the existing normalization for Cosine and unbounded Dot.
+ similarity = (score / (1.0 + abs(score)) + 1.0) / 2.0
results.append(
{
"id": point.id,
- # See pinecone_store.py PineconeIndex.search_vectors for why
- # this uses x/(1+|x|) rather than clamping distance-to-zero:
- # Qdrant's Dot distance metric is unbounded, and the old
- # clamped formula collapsed every score >= 1.0 to 1.0.
- "score": (
- float(point.score) / (1.0 + abs(float(point.score))) + 1.0
- )
- / 2.0,
+ "score": similarity,
"metadata": point.payload or {},
"vector": None,
"distance": None,
diff --git a/tests/vector_store/test_pinecone_score_direction.py b/tests/vector_store/test_pinecone_score_direction.py
new file mode 100644
index 00000000..985b9687
--- /dev/null
+++ b/tests/vector_store/test_pinecone_score_direction.py
@@ -0,0 +1,82 @@
+"""Metric-aware Pinecone scores using the existing fake-client pattern."""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import numpy as np
+import pytest
+
+from semantica.vector_store.pinecone_store import (
+ PineconeClient,
+ PineconeIndex,
+ PineconeStore,
+)
+
+
[email protected](autouse=True)
+def pinecone_available(monkeypatch):
+ monkeypatch.setattr(
+ "semantica.vector_store.pinecone_store.PINECONE_AVAILABLE", True
+ )
+
+
[email protected]("create", [False, True])
[email protected]("description_type", [dict, SimpleNamespace])
+ "metric,native_metric,raw_scores,expected",
+ [
+ ("euclidean", "euclidean", [0.0, 1.0, 3.0], [1.0, 0.5, 0.25]),
+ ("cosine", "cosine", [1.0, 0.0, -1.0], [0.75, 0.5, 0.25]),
+ ("dot", "dotproduct", [50.0, 2.0, -1.0], [101 / 102, 5 / 6, 0.25]),
+ ],
+)
+def test_scores_follow_created_or_attached_metric(
+ create, description_type, metric, native_metric, raw_scores, expected
+):
+ client = MagicMock()
+ index = client.Index.return_value
+ client.describe_index.return_value = description_type(metric=native_metric)
+ index.query.return_value = SimpleNamespace(
+ matches=[
+ SimpleNamespace(id=str(i), score=score, metadata={})
+ for i, score in enumerate(raw_scores)
+ ]
+ )
+ store = PineconeStore(api_key="test-key", dimension=2)
+ store.client = PineconeClient(client)
+ if create:
+ store.create_index("vectors", dimension=2, metric=metric)
+ else:
+ store.get_index("vectors")
+
+ results = store.search_vectors(np.array([1.0, 0.0]), k=3)
+ scores = [result["score"] for result in results]
+ assert [result["id"] for result in results] == ["0", "1", "2"]
+ assert scores == pytest.approx(expected)
+ assert scores == sorted(scores, reverse=True)
+ if create:
+ assert client.create_index.call_args.kwargs["metric"] == native_metric
+
+
+def test_unavailable_metric_keeps_existing_scores():
+ client = MagicMock()
+ client.describe_index.side_effect = RuntimeError("description unavailable")
+ index = client.Index.return_value
+ index.query.return_value = SimpleNamespace(
+ matches=[SimpleNamespace(id="a", score=2.0, metadata={})]
+ )
+ store = PineconeStore(api_key="test-key", dimension=2)
+ store.client = PineconeClient(client)
+ store.get_index("vectors")
+
+ results = store.search_vectors(np.array([1.0, 0.0]))
+ assert results[0]["score"] == pytest.approx(5 / 6)
+
+
+def test_direct_index_without_metric_keeps_existing_scores():
+ index = MagicMock()
+ index.query.return_value = SimpleNamespace(
+ matches=[SimpleNamespace(id="a", score=2.0, metadata={})]
+ )
+ results = PineconeIndex(index).search_vectors([1.0, 0.0])
+ assert results[0]["score"] == pytest.approx(5 / 6)
diff --git a/tests/vector_store/test_qdrant_score_direction.py b/tests/vector_store/test_qdrant_score_direction.py
new file mode 100644
index 00000000..ac0669bd
--- /dev/null
+++ b/tests/vector_store/test_qdrant_score_direction.py
@@ -0,0 +1,93 @@
+"""Metric-aware Qdrant scores against the real local backend."""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import numpy as np
+import pytest
+
+from semantica.vector_store.qdrant_store import QdrantCollection, QdrantStore
+
+qdrant = pytest.importorskip("qdrant_client")
+models = pytest.importorskip("qdrant_client.models")
+
+
[email protected]("reopen", [False, True])
+ "metric,vectors,expected",
+ [
+ ("Euclidean", [[1.0, 0.0], [2.0, 0.0], [4.0, 0.0]], [1.0, 0.5, 0.25]),
+ ("Cosine", [[1.0, 0.0], [0.0, 1.0], [-1.0, 0.0]], [0.75, 0.5, 0.25]),
+ ("Dot", [[50.0, 0.0], [2.0, 0.0], [-1.0, 0.0]], [101 / 102, 5 / 6, 0.25]),
+ ],
+)
+def test_scores_follow_created_or_reopened_metric(
+ tmp_path, metric, vectors, expected, reopen
+):
+ path = str(tmp_path / "qdrant")
+ store = QdrantStore()
+ store.client = qdrant.QdrantClient(path=path)
+ try:
+ store.create_collection("vectors", vector_size=2, distance=metric)
+ store.insert_vectors(vectors, ids=[1, 2, 3])
+ if reopen:
+ store.client.close()
+ store = QdrantStore()
+ store.client = qdrant.QdrantClient(path=path)
+ store.get_collection("vectors")
+
+ results = store.search_vectors(np.array([1.0, 0.0]), limit=10)
+ assert [result["id"] for result in results] == [1, 2, 3]
+ scores = [result["score"] for result in results]
+ assert scores == pytest.approx(expected)
+ assert scores == sorted(scores, reverse=True)
+ finally:
+ store.client.close()
+
+
+ "distance", [models.Distance.EUCLID, models.Distance.MANHATTAN]
+)
[email protected]("named", [False, True])
+def test_direct_wrapper_reads_external_collection_metric(distance, named):
+ client = qdrant.QdrantClient(":memory:")
+ try:
+ config = models.VectorParams(size=2, distance=distance)
+ if named:
+ config = {
+ "distance": config,
+ "dot": models.VectorParams(size=2, distance=models.Distance.DOT),
+ }
+ client.create_collection("external", vectors_config=config)
+ points = []
+ for i, dot in enumerate([50.0, 2.0, -1.0], start=1):
+ vector = [float(i - 1), 0.0]
+ if named:
+ vector = {"distance": vector, "dot": [dot, 0.0]}
+ points.append(models.PointStruct(id=i, vector=vector))
+ client.upsert("external", points=points)
+ collection = QdrantCollection(client, "external")
+ options = {"using": "distance"} if named else {}
+ results = collection.search_points(np.array([0.0, 0.0]), limit=3, **options)
+ scores = [result["score"] for result in results]
+ assert [result["id"] for result in results] == [1, 2, 3]
+ assert scores == pytest.approx([1.0, 0.5, 1 / 3])
+ assert scores == sorted(scores, reverse=True)
+ if named:
+ results = collection.search_points(np.array([1.0, 0.0]), using="dot")
+ assert [result["id"] for result in results] == [1, 2, 3]
+ assert [result["score"] for result in results] == pytest.approx(
+ [101 / 102, 5 / 6, 0.25]
+ )
+ finally:
+ client.close()
+
+
+def test_unavailable_collection_metric_keeps_existing_scores():
+ client = MagicMock()
+ client.get_collection.side_effect = RuntimeError("description unavailable")
+ client.query_points.return_value = SimpleNamespace(
+ points=[SimpleNamespace(id=1, score=2.0, payload={})]
+ )
+ results = QdrantCollection(client, "vectors").search_points(np.array([1.0, 0.0]))
+ assert results[0]["score"] == pytest.approx(5 / 6)