Skip to content

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

fix(rag): bound MongoDB search candidates (#3316)

Jingbo Chai16bd55791ff1
diff --git a/src/agentscope/rag/_vdb/_mongodb.py b/src/agentscope/rag/_vdb/_mongodb.py
index 8ae414026..f6029b8d6 100644
--- a/src/agentscope/rag/_vdb/_mongodb.py
+++ b/src/agentscope/rag/_vdb/_mongodb.py
@@ -321,13 +321,16 @@ class MongoDBStore(VectorStoreBase):
) -> list[VectorSearchResult]:
"""Find the most similar records to a query vector.
+ The search considers at least 100 candidates and targets 20 times
+ ``top_k``, capped at MongoDB's 10,000-candidate limit.
+
Args:
collection (`str`):
The collection to search.
query_vector (`list[float]`):
The query embedding vector.
top_k (`int`, defaults to ``5``):
- Maximum number of results to return.
+ Maximum number of results to return. Cannot exceed 10,000.
metadata_filter (`dict[str, Any] | None`, optional):
If provided, restrict the search to records whose
``chunk.metadata`` matches every ``key == value`` pair
@@ -338,7 +341,13 @@ class MongoDBStore(VectorStoreBase):
Returns:
`list[VectorSearchResult]`:
Results ordered by descending similarity score.
+
+ Raises:
+ `ValueError`:
+ If ``top_k`` exceeds MongoDB's 10,000-candidate ANN limit.
"""
+ if top_k > 10_000:
+ raise ValueError("top_k cannot exceed MongoDB's 10000 ANN limit")
await self._ensure_index_ready(collection)
col = self._col(collection)
@@ -346,7 +355,7 @@ class MongoDBStore(VectorStoreBase):
"index": self._index_name,
"path": "vector",
"queryVector": query_vector,
- "numCandidates": max(100, top_k * 20),
+ "numCandidates": min(10_000, max(100, top_k * 20)),
"limit": top_k,
}
filter_expr = self._build_metadata_filter(metadata_filter)
diff --git a/tests/rag_vdb_mongodb_test.py b/tests/rag_vdb_mongodb_test.py
index 0ac038d8c..f8b2d7a8d 100644
--- a/tests/rag_vdb_mongodb_test.py
+++ b/tests/rag_vdb_mongodb_test.py
@@ -478,6 +478,104 @@ class MongoDBStoreTest(IsolatedAsyncioTestCase):
],
)
+ async def test_search_candidate_limits(self) -> None:
+ """Search caps candidates while preserving the requested limit."""
+ await self.store.create_collection("kb-1", dimensions=3)
+ record = _make_record("A", [1.0, 0.0, 0.0], document_id="doc-1")
+ record.chunk.metadata["kb_scope"] = "kb-a"
+ await self.store.insert("kb-1", [record])
+ col = self._fake_client["test-db"]["kb-1"]
+
+ for top_k, num_candidates, metadata_filter in [
+ (None, 100, None),
+ (500, 10_000, None),
+ (501, 10_000, {"kb_scope": "kb-a"}),
+ (10_000, 10_000, None),
+ ]:
+ with self.subTest(top_k=top_k):
+ search_kwargs: dict[str, Any] = {}
+ if top_k is not None:
+ search_kwargs["top_k"] = top_k
+ if metadata_filter is not None:
+ search_kwargs["metadata_filter"] = metadata_filter
+
+ with patch.object(
+ col,
+ "aggregate",
+ wraps=col.aggregate,
+ ) as aggregate:
+ results = await self.store.search(
+ "kb-1",
+ query_vector=[1.0, 0.0, 0.0],
+ **search_kwargs,
+ )
+
+ vector_search: dict[str, Any] = {
+ "index": "vector_index",
+ "path": "vector",
+ "queryVector": [1.0, 0.0, 0.0],
+ "numCandidates": num_candidates,
+ "limit": 5 if top_k is None else top_k,
+ }
+ if metadata_filter is not None:
+ vector_search["filter"] = {
+ "$and": [{"chunk.metadata.kb_scope": {"$eq": "kb-a"}}],
+ }
+ aggregate.assert_awaited_once_with(
+ [
+ {"$vectorSearch": vector_search},
+ {
+ "$project": {
+ "document_id": 1,
+ "chunk": 1,
+ "score": {"$meta": "vectorSearchScore"},
+ },
+ },
+ ],
+ )
+ self.assertEqual(
+ _dump_results(results),
+ [
+ {
+ "score": 1.0,
+ "document_id": "doc-1",
+ "chunk": {
+ "content": {
+ "type": "text",
+ "text": "A",
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "finished_at": None,
+ },
+ "source": "doc-1.txt",
+ "chunk_index": 0,
+ "total_chunks": 1,
+ "metadata": {"kb_scope": "kb-a"},
+ },
+ },
+ ],
+ )
+
+ async def test_search_top_k_exceeds_limit(self) -> None:
+ """An oversized search is rejected before accessing MongoDB."""
+ store = MongoDBStore(uri="mongodb://mock", database="test-db")
+ with (
+ patch.object(store, "_ensure_index_ready") as ensure_index_ready,
+ patch.object(
+ store,
+ "get_client",
+ return_value=self._fake_client,
+ ) as get_client,
+ ):
+ with self.assertRaisesRegex(ValueError, "top_k.*10000"):
+ await store.search(
+ "kb-1",
+ query_vector=[1.0, 0.0, 0.0],
+ top_k=10_001,
+ )
+ ensure_index_ready.assert_not_awaited()
+ get_client.assert_not_called()
+
async def test_delete_by_document_id(self) -> None:
"""delete removes all records of one document only."""
await self.store.create_collection("kb-1", dimensions=3)