Skip to content

armgit / txtai

Public Imported from GitHub
0

💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows

7.0 KB
Raw Blame
"""
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()