vicinity

Approximate nearest-neighbor search. Each algorithm is a separate feature flag. Depend on only what you use.

Default distance is cosine; most graph indices L2-normalize on insert and operate on the cosine-equivalent unit sphere (so angular and inner product over normalized vectors fall out for free). True L2 distance is natively wired only in ivf_avq (which targets MIPS). The DistanceMetric enum in distance.rs is consumed by evaluation utilities and brute-force comparison; per-index metric selection is algorithm-specific.

Which index?

Which index?
├── General purpose: HNSW (default)
├── Memory constrained: HNSW + RaBitQ (SymphonyQG) or IVF-PQ
├── Disk-backed / large scale: DiskANN (experimental; file-based, mmap planned)
├── Streaming insert/delete: FreshGraph (per-op latency) or LsmIndex (write throughput)
├── Filtered search: ACORN (metadata filters) or Curator (label filters)
├── Batch/static: IVF-PQ or IVF-AVQ
└── Sparse vectors: SparseMIPS

For high-dimensional data (d ≥ 256), prefer SQ4U or SymphonyQG over plain HNSW. Quantized graph traversal reduces distance computation cost. At low dimensions (d ≤ 25), plain HNSW wins; quantization overhead outweighs savings.

Install

Each algorithm is a separate feature. Enable what you need:

[dependencies]
vicinity = { version = "0.8", features = ["hnsw"] }          # graph index
# vicinity = { version = "0.8", features = ["ivf_pq"] }      # compressed index
# vicinity = { version = "0.8", features = ["nsw"] }         # flat graph

Usage

HNSW

High recall, in-memory. Default index.

use vicinity::hnsw::HNSWIndex;

let mut index = HNSWIndex::builder(128).m(16).ef_search(50).build()?;
index.add_slice(0, &[0.1; 128])?;
index.add_slice(1, &[0.2; 128])?;
index.build()?;

let results = index.search(&[0.1; 128], 5, 50)?;
// results: Vec<(doc_id, distance)>

IVF-PQ

Compressed index. 32–64× less memory than HNSW, lower recall. Use for datasets that don't fit in RAM.

use vicinity::ivf_pq::{IVFPQIndex, IVFPQParams};

let params = IVFPQParams { num_clusters: 256, num_codebooks: 8, nprobe: 16, ..Default::default() };
let mut index = IVFPQIndex::new(128, params)?;
index.add_slice(0, &[0.1; 128])?;
index.add_slice(1, &[0.2; 128])?;
index.build()?;

let results = index.search(&[0.1; 128], 5)?;

Persistence

Save and load indexes with the serde feature:

[dependencies]
vicinity = { version = "0.8", features = ["hnsw", "serde"] }

// Save
index.save_to_file("my_index.json")?;

// Load
let index = HNSWIndex::load_from_file("my_index.json")?;

See examples/06_save_and_load.rs for a full example.

Benchmark

GloVe-25 (1.18M vectors, 25-d, angular distance), Apple Silicon, single-threaded:

Summary at best recall per algorithm:

Full numbers and SIFT-128 results in docs/benchmark-results.md.

Supported Algorithms

Each algorithm has a named feature flag:

Quantization: RaBitQ, SAQ (quantization feature, via qntz crate). PQ is part of ivf_pq.

See docs.rs for the full API.

Documentation

• User guide: quick start, distance metrics, LID, common pitfalls
• Benchmarks: recall/QPS tables across datasets
• ANN landscape: algorithmic principles, math foundations, research context
• References: bibliography for every algorithm in the crate

License

MIT OR Apache-2.0