Skip to content

Build and run agents you can see, understand and trust.

fix(rag): normalize scores using the Qdrant collection metric (#3958)

qkycir9f5bb33021a9
diff --git a/src/agentscope/rag/_vdb/_qdrant.py b/src/agentscope/rag/_vdb/_qdrant.py
index d63d7f209..acee62b00 100644
--- a/src/agentscope/rag/_vdb/_qdrant.py
+++ b/src/agentscope/rag/_vdb/_qdrant.py
@@ -313,7 +313,21 @@ class QdrantStore(VectorStoreBase):
`list[VectorSearchResult]`:
Results ordered by descending similarity score.
"""
- response = await self.get_client().query_points(
+ from qdrant_client import models
+
+ client = self.get_client()
+ collection_info = await client.get_collection(collection)
+ vectors = collection_info.config.params.vectors
+ if isinstance(vectors, dict):
+ vectors = vectors.get("")
+ if not isinstance(vectors, models.VectorParams):
+ raise ValueError(
+ "QdrantStore.search requires an unnamed dense vector.",
+ )
+ # The constructor's metric only applies to newly created collections.
+ # Read the actual schema, including after an external recreation.
+ distance = vectors.distance
+ response = await client.query_points(
collection_name=collection,
query=query_vector,
limit=top_k,
@@ -322,7 +336,11 @@ class QdrantStore(VectorStoreBase):
)
# ``Euclid`` / ``Manhattan`` are distances, so negate them to
# keep ``score`` higher-is-better like ``Cosine`` / ``Dot``.
- sign = -1 if self._distance in ("Euclid", "Manhattan") else 1
+ sign = (
+ -1
+ if distance in (models.Distance.EUCLID, models.Distance.MANHATTAN)
+ else 1
+ )
return [
VectorSearchResult(
score=sign * point.score,
diff --git a/tests/rag_vdb_qdrant_test.py b/tests/rag_vdb_qdrant_test.py
index 698bb259e..f90e1e463 100644
--- a/tests/rag_vdb_qdrant_test.py
+++ b/tests/rag_vdb_qdrant_test.py
@@ -2,6 +2,7 @@
"""Unit tests for the QdrantStore class."""
from contextlib import AsyncExitStack
from importlib.util import find_spec
+from tempfile import TemporaryDirectory
from types import SimpleNamespace
from unittest import skipUnless
from unittest.async_case import IsolatedAsyncioTestCase
@@ -94,6 +95,130 @@ def _make_record(
)
+class QdrantMetricTest(IsolatedAsyncioTestCase):
+ """Real collection metadata determines search score semantics."""
+
+ async def asyncSetUp(self) -> None:
+ """Create an in-memory Qdrant store before each test."""
+ self._exit_stack = AsyncExitStack()
+ self.store = await self._exit_stack.enter_async_context(
+ QdrantStore(location=":memory:"),
+ )
+
+ async def asyncTearDown(self) -> None:
+ """Close the store after each test."""
+ await self._exit_stack.aclose()
+
+ async def test_existing_collection_metric_controls_ranking(self) -> None:
+ """Reopened collections retain distance ranking and thresholds."""
+
+ class QueryEmbedding:
+ """Return the fixed query vector without a model service."""
+
+ dimensions = 3
+ supports_multimodal = False
+
+ async def __call__(self, queries: list) -> SimpleNamespace:
+ return SimpleNamespace(
+ embeddings=[[1.0, 0.0, 0.0] for _ in queries],
+ )
+
+ for metric in ("Euclid", "Manhattan"):
+ with self.subTest(metric=metric), TemporaryDirectory() as path:
+ async with QdrantStore(path=path, distance=metric) as writer:
+ await writer.create_collection("existing", dimensions=3)
+ await writer.insert(
+ "existing",
+ [
+ _make_record(name, [value, 0.0, 0.0], name)
+ for name, value in (
+ ("exact", 1.0),
+ ("near", 2.0),
+ ("far", 11.0),
+ )
+ ],
+ )
+ # The default is a creation option, not the existing metric.
+ async with QdrantStore(path=path) as reader:
+ kb = KnowledgeBase(
+ name="existing",
+ description="Existing distance collection",
+ embedding_model=QueryEmbedding(),
+ vector_store=reader,
+ collection="existing",
+ )
+ hits = await kb.search(["query"], top_k=3)
+ self.assertEqual(
+ [(hit.document_id, hit.score) for hit in hits],
+ [("exact", 0.0), ("near", -1.0), ("far", -10.0)],
+ )
+ filtered = await kb.search(
+ ["query"],
+ top_k=3,
+ score_threshold=-1.0,
+ )
+ self.assertEqual(
+ [hit.document_id for hit in filtered],
+ ["exact", "near"],
+ )
+
+ async def test_metric_tracks_external_collection_recreation(self) -> None:
+ """A live store does not retain a deleted collection's old metric."""
+ from qdrant_client import models
+
+ client = self.store.get_client()
+ for metric, expected in (("Euclid", -1.0), ("Dot", 2.0)):
+ with self.subTest(metric=metric):
+ await client.create_collection(
+ "recreated",
+ vectors_config=models.VectorParams(
+ size=3,
+ distance=metric,
+ ),
+ )
+ try:
+ await self.store.insert(
+ "recreated",
+ [_make_record("near", [2.0, 0.0, 0.0], "near")],
+ )
+ hits = await self.store.search(
+ "recreated",
+ [1.0, 0.0, 0.0],
+ )
+ self.assertEqual(hits[0].score, expected)
+ finally:
+ await client.delete_collection("recreated")
+
+ async def test_default_dense_vector_in_named_config(self) -> None:
+ """The empty vector name is Qdrant's default query target."""
+ from qdrant_client import models
+
+ client = self.store.get_client()
+ await client.create_collection(
+ "default-named",
+ vectors_config={
+ "": models.VectorParams(size=3, distance="Euclid"),
+ "named": models.VectorParams(size=3, distance="Dot"),
+ },
+ )
+ record = _make_record("near", [2.0, 0.0, 0.0], "near")
+ await client.upsert(
+ "default-named",
+ points=[
+ models.PointStruct(
+ id=1,
+ vector={"": record.vector},
+ payload={
+ "document_id": record.document_id,
+ "chunk": record.chunk.model_dump(mode="json"),
+ },
+ ),
+ ],
+ )
+ hits = await self.store.search("default-named", [1.0, 0.0, 0.0])
+ self.assertEqual(hits[0].score, -1.0)
+
+
class QdrantStoreTest(IsolatedAsyncioTestCase):
"""The test cases for the QdrantStore class."""