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. |