vindex.nu

vindex.nu — a vector index: search the k nearest of n d-dim vectors by cosine or L2. Two builders share one search surface:

EXACT — brute force over every vector (the ground truth). IVF-flat — a k-means coarse quantiser (nlist centroids) with inverted lists; a query scores only the nprobe nearest clusters, trading recall for speed on a knob.

Cosine precomputes each vector's L2 norm, so a candidate costs one dot product. Scores are "smaller = nearer" (cosine: 1 − cossim; L2: squared distance), so the same top-k machinery serves both. The index serialises to one .vix byte blob and loads back to identical results.

( vx_build_exact data n dim metric ) → VIndex ( vx_build_ivf data n dim metric nlist niter seed ) → VIndex ( vx_search idx q k nprobe out_ids out_dists ) → i (results found) ( vx_free idx ) → v ( vx_save idx ) → ( Vec u ) ( vx_load bytes ) → !*VIndex String

metric: VX_COSINE (0) or VX_L2 (1).

API

: i VX_COSINE 0

: i VX_L2 1

: VIndex

: VIndex {
    ( Vec f ) data  // n·dim, row-major
    ( Vec f ) norm  // n L2 norms (for cosine)
    i n
    i dim
    i metric
    i nlist  // 0 = exact
    ( Vec f ) cent  // nlist·dim centroids
    ( Vec f ) cnorm  // nlist norms
    ( Vec i ) list_off  // nlist+1 CSR offsets into members
    ( Vec i ) members  // n vector ids grouped by cluster
}

@ vx_build_exact ( Vec f ) data i n i dim i metric → *VIndex

@ vx_build_ivf ( Vec f ) data i n i dim i metric i nlist i niter i seed → *VIndex

@ vx_search * VIndex idx ( Vec f ) q i k i nprobe ( Vec i ) out_ids ( Vec f ) out_dists → i

Fill out_ids/out_dists (cleared first) with the k nearest of query q. nprobe is ignored for an exact index. Returns the number found.

@ vx_n * VIndex idx → i

@ vx_dim * VIndex idx → i

@ vx_nlist * VIndex idx → i

@ vx_free * VIndex idx → v

@ vx_save * VIndex idx → ( Vec u )

@ vx_load ( Vec u ) b → !*VIndex String