Spheni

A lightweight vector search library focused on memory-efficient approximate nearest neighbor search.

Index

1. Overview
2. Features
3. Getting Started
4. API Reference
5. Benchmarks
6. Roadmap
7. References

Overview

The goal of Spheni is to be focused on memory efficiency rather than accuracy, and act a candidate generation system.

It implements inverted indexing and product quantization with residual encoding to reduce memory usage while supporting fast similarity search.

With Cohere 1M Embeddings, the current benchmark reports up to 213.9x compression (13.69 MB index at M=8) and up to 94.20% Recall@10-in-100 (M=64, nprobe=32), with the baseline at 80.1x compression and 83.25% Recall@10-in-100 (M=32, nprobe=32).

Features

• Indexes: Flat, IVF, FlatPQ, IVF-PQ
• Metrics: Cosine similarity, L2 distance
• Operations: train, add, search

Getting Started

Build

Requirements:

• CMake >= 3.15
• A C++20 compiler (GCC/Clang)

Quick build

chmod +x build.sh
./build.sh

After building, this repository produces build/libspheni.a. You only need the public header (include/spheni.h) and the static library (libspheni.a) to consume Spheni in another project.

Usage

g++ -std=c++20 -O3 main.cpp -I /path/to/spheni/include /path/to/libspheni.a -o main

Example

Check out examples/ folder for more.

#include "spheni.h"
#include <iostream>

int main() {
        // define
        spheni::IVFSpec spec{{3, spheni::Metric::Cosine, true}, 2, 1};
        spheni::IVFIndex index(spec);

        long long ids[] = {0, 1, 2};
        float vecs[] = {
            1.0f, 0.0f, 0.0f, 0.0f, 1.0f, 0.0f, 1.0f, 1.0f, 0.0f,
        };
        // train
        index.train(ids, vecs);

        float query[] = {1.0f, 0.2f, 0.0f};
        // search
        auto hits = index.search(query, 3);

        for (const auto &h : hits) {
                std::cout << h.id << " " << h.score << "\n";
        }
        return 0;
}

API Reference

Detailed public API documentation is available in docs/api-reference.md.

Benchmarks

Current Benchmark Report (single-core run, 200 queries, Recall@k-in-100).
Legacy Report is also available.

Roadmap

• Implement save/load for seralized data
• Implement multithreading with OpenMP wherever applicable
• Implement OPQ (tough for me)
• SIMD vectorizations

References

Papers

1. FAISS: ArXiv Paper
2. Near Neighbor Search in Large Metric Spaces
3. The Binary Vector as the Basis of an Inverted Index File
4. Product Quantization for Nearest Neighbour Search

Blogs

1. A Bhayani - Product Quantization
2. W Lin - Building a high recall vector database serving 1 billion embeddings from a single machine