AnnVectorIndex<T>

Models & Types · AiDotNet.RetrievalAugmentedGeneration.VectorSearch.Indexes

A dependency-free approximate-nearest-neighbour index (Flat / IVF / PQ / IVFPQ) implemented on the AiDotNet Tensors stack via AnnIndex. This is the native replacement for the external FaissNet-backed index whose IVF/PQ path is blocked by an incomplete MKL redistribution: it takes no external native dependency and, when a GPU backend is attached, dispatches its distance / assignment / PQ scans to the fused ANN kernels (IAnnBackend) across all supported backends, falling back to the managed CPU reference otherwise.

Implements: IVectorIndex<T>

For Beginners

You just add and remove vectors by id and search — the training and rebuilding that IVF/PQ need happen automatically behind the scenes the first time you query after a change.

How It Works

The underlying AnnIndex trains its coarse quantizer / PQ codebooks once on a representative sample and does not support in-place deletion, so this adapter keeps the live vectors as the source of truth and lazily (re)builds the index on the next Search after any mutation. That keeps the simple incremental IVectorIndex contract (Add / Remove / Search) correct over an index that is fundamentally train-then-populate.

Scale hardening — incremental add. Discarding and retraining the whole ANN index on every mutation is O(n) per query after any change. When the index is already built and either Flat or a trained IVF/PQ/IVFPQ index, and only additions (no removals, overwrites, GPU re-attach, or dimension changes) have happened since the last build, the newly-added vectors are appended to the live AnnIndex via Add incrementally rather than rebuilt from scratch — the trained quantizer / codebooks are reused. A removal (or the first build, or a not-yet-trained index) forces a full rebuild. Ordinals stay contiguous and in insertion order, so the ordinal-to-id map and the search results are equivalent to the original full-rebuild path.

Scale hardening — persistence.Save / Load serialize the configuration plus the live vectors (id -> float[]) and insertion order to JSON (Newtonsoft). Because AnnIndex is not itself serializable, Load reconstructs the adapter from the persisted vectors and parameters; the deterministic seeded k-means makes the rebuilt index reproducible, so a loaded index returns the same search results as the saved one.

Constructors

Constructor Summary
AnnVectorIndex(AnnVectorIndexType indexType, int dimension, AnnVectorMetric metric, int nlist, int nprobe, int m, int ksub, int seed) Creates a native ANN vector index.

Properties

Property Summary
AnnVectorIndexType IndexType { get; } The ANN index structure this index was created with.
AnnVectorMetric Metric { get; } The distance metric this index was created with.
int Count { get; }

Methods

Method Summary
AnnVectorIndex<T> Load(string path) Reconstructs an AnnVectorIndex previously written by Save.
List<ValueTuple<string, T>> Search(Vector<T> query, int k)
bool Remove(string id)
void Add(string id, Vector<T> vector)
void AddBatch(Dictionary<string, Vector<T>> vectors)
void AttachGpu(IDirectGpuBackend backend) Attaches a GPU backend so search/training dispatch to the fused ANN kernels when available.
void Clear()
void Save(string path) Persists the index configuration, the live vectors (id -> stored float[]) and their insertion order to path as JSON.