💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows
Python agentsaiai-agentsembeddingsinformation-retrievallanguage-modellarge-language-modelsllmnlppythonragretrieval-augmented-generationsearchsearch-enginesemantic-searchsentence-embeddingstransformerstxtaivector-databasevector-search
"""
IVFSparse ANN module tests
"""
import os
import tempfile
from unittest.mock import patch
import numpy as np
from scipy.sparse import csr_matrix
from sklearn.cluster import MiniBatchKMeans
from txtai.ann import SparseANNFactory
from .base import SparseTest
class TestIVFSparse(SparseTest):
"""
IVFSparse ANN tests.
"""
def testIVFSparse(self):
"""
Test IVFSparse backend
"""
# Generate test record
insert = self.generate(500, 30522)
append = self.generate(500, 30522)
# Count of records
count = insert.shape[0] + append.shape[0]
# Create ANN
path = os.path.join(tempfile.gettempdir(), "ivfsparse")
ann = SparseANNFactory.create({"backend": "ivfsparse", "ivfsparse": {"nlist": 2, "nprobe": 2, "sample": 1.0}})
# Test indexing
ann.index(insert)
ann.append(append)
# Validate search results
results = [x[0] for x in ann.search(insert[5], 10)[0]]
self.assertIn(5, results)
# Validate save/load/delete
ann.save(path)
ann.load(path)
# Validate count
self.assertEqual(ann.count(), count)
# Test delete
ann.delete([0])
self.assertEqual(ann.count(), count - 1)
# Deleting the same id again or an id that was never indexed is a no-op for the count
ann.delete([0])
ann.delete([count + 100])
self.assertEqual(ann.count(), count - 1)
# Re-validate search results
results = [x[0] for x in ann.search(append[0], 10)[0]]
self.assertIn(insert.shape[0], results)
# Save and reload index with deletes
ann.save(path)
ann.load(path)
self.assertEqual(ann.count(), count - 1)
# Close ANN
ann.close()
# Test cluster pruning
ann = SparseANNFactory.create({"backend": "ivfsparse", "ivfsparse": {"nlist": 15, "nprobe": 1, "sample": 1.0}})
ann.index(insert)
self.assertLessEqual(len(ann.blocks), 15)
ann.close()
def testIVFSparseDeleteArray(self):
"""
Test IVFSparse with ids deleted using a NumPy array
"""
# Generate test record
data = self.generate(50, 30522)
# Create ANN
path = os.path.join(tempfile.gettempdir(), "ivfsparse.deletes")
ann = SparseANNFactory.create({"backend": "ivfsparse"})
ann.index(data)
# Test delete with ids passed in as a NumPy array
ann.delete(np.array([0, 1]))
self.assertEqual(ann.count(), 48)
# Validate save/load
ann.save(path)
ann.load(path)
self.assertEqual(ann.count(), 48)
# Close ANN
ann.close()
def testIVFSparseSortOrder(self):
"""
Test IVFSparse returns results sorted by score descending
"""
# Generate test data
data = self.generate(50, 30522)
ann = SparseANNFactory.create({"backend": "ivfsparse"})
ann.index(data)
# Each result list must be ranked by score descending
for results in ann.search(data[:5], 10):
scores = [score for _, score in results]
self.assertEqual(scores, sorted(scores, reverse=True))
ann.close()
def testIVFSparseTopnOverLimit(self):
"""
Test IVFSparse topn when limit exceeds the number of indexed documents
"""
# Generate a small dataset (5 documents)
data = self.generate(5, 30522)
ann = SparseANNFactory.create({"backend": "ivfsparse"})
ann.index(data)
# Search with limit (10) greater than document count (5)
results = ann.search(data[0], 10)
self.assertGreater(len(results[0]), 0)
# Batch search with multiple queries exceeding document count
results = ann.search(data, 10)
self.assertEqual(len(results), data.shape[0])
for result in results:
self.assertGreater(len(result), 0)
ann.close()
def testIVFSparseNFeatures(self):
"""
Test IVFSparse nfeatures setting limits model training to the top n features
"""
# Generate test data
data = self.generate(500, 100)
# Capture the feature count passed to model training
features = []
fit = MiniBatchKMeans.fit
def logfit(self, x, *args, **kwargs):
features.append(x.shape[1])
return fit(self, x, *args, **kwargs)
# nfeatures unset trains on the full feature space
ann = SparseANNFactory.create({"backend": "ivfsparse", "ivfsparse": {"nlist": 2}})
with patch("txtai.ann.sparse.ivfsparse.MiniBatchKMeans.fit", logfit):
ann.index(data)
ann.close()
# nfeatures limits training to the top n features
ann = SparseANNFactory.create({"backend": "ivfsparse", "ivfsparse": {"nlist": 2, "nfeatures": 10}})
with patch("txtai.ann.sparse.ivfsparse.MiniBatchKMeans.fit", logfit):
ann.index(data)
ann.close()
self.assertEqual(features, [100, 10])
def testIVFSparseMixedDtypes(self):
"""
Test float32 and float64 queries after appending float64 rows
"""
# Index float32 rows and append a float64 row
ann = SparseANNFactory.create({"backend": "ivfsparse"})
ann.index(csr_matrix([[1, 0], [0, 1]], dtype=np.float32))
ann.append(csr_matrix([[0.5, 0.5]], dtype=np.float64))
# Validate scores for both query types without losing the existing rows
for dtype in [np.float32, np.float64]:
results = ann.search(csr_matrix([[1, 0]], dtype=dtype), 3)[0]
self.assertEqual(results, [(0, 1.0), (2, 0.5), (1, 0.0)])
ann.close()
def testIVFSparseAppendMaxima(self):
"""
Test appended rows update block maxima before query probing
"""
# Build two distinct blocks and preserve their initial summaries
ann = SparseANNFactory.create({"backend": "ivfsparse", "ivfsparse": {"nlist": 2, "nprobe": 1}})
ann.index(csr_matrix([[1, 0, 0]] * 40 + [[0, 1, 0]] * 40, dtype=np.float64))
before = ann.centroids.copy()
# Append a row whose maximum differs from the full block maximum
ann.append(csr_matrix([[0.5, 0, 2]], dtype=np.float64))
self.assertEqual(ann.search(csr_matrix([[0, 0.1, 1]], dtype=np.float64), 1)[0], [(80, 2.0)])
cluster = next(key for key, ids in ann.ids.items() if 80 in ids)
np.testing.assert_array_equal(ann.centroids[cluster].toarray(), [[1, 0, 2]])
np.testing.assert_array_equal(ann.centroids[1 - cluster].toarray(), before[1 - cluster].toarray())
# Touch the other block while retaining the previous maximum
ann.append(csr_matrix([[0, 2, 0]], dtype=np.float64))
for key, block in ann.blocks.items():
np.testing.assert_array_equal(ann.centroids[key].toarray(), block.max(axis=0).toarray())
self.assertEqual(ann.centroids.format, "csr")
self.assertEqual(ann.centroids.shape, (2, 3))
ann.close()