VSAG

C++ · Python · Open source (Apache 2.0)

High-performance vector indexing,
built for billion-scale search.

VSAG is a C++ library for approximate nearest-neighbor search. It ships production-ready HGraph, IVF, SINDI, Pyramid and BruteForce indexes with SIMD-accelerated distance kernels, quantization, and a unified builder API — with first-class Python bindings via pyvsag.

Get started Star on GitHub
Index types
7+
License
Apache 2.0
Language bindings
C++ · Python · Node.js
Built at
Ant Group

Why VSAG

Engineered for production similarity search

SIMD-accelerated kernels

AVX2 / AVX-512 / NEON distance kernels, integer and float quantization (SQ4/SQ8, PQ, RaBitQ), and careful memory layout for hot paths.

A family of indexes

HGraph, IVF, SINDI, Pyramid and BruteForce — one builder-style API, one serialization format, one set of ops. Legacy HNSW and DiskANN remain available.

Adaptive runtime

Index::Tune with the ELP optimizer searches the graph entry-point and beam parameters to keep recall and latency on target as workloads drift.

Flexible serialization

Serialize to BinarySet, streams, or user-supplied write callbacks. Zero-copy ReaderSet keeps cold indexes on disk and hot tiers in memory.

Range & hybrid search

Radius search, filtered search with user predicates, and a hybrid dense + sparse index for RAG and retrieval pipelines.

Pluggable resources

Bring your own Allocator and ThreadPool via Resource to integrate cleanly with the host database or service runtime.

Quickstart

Up and running in a few lines

Python (pyvsag)

pip install numpy pyvsag
import pyvsag, numpy as np

index = pyvsag.Index("hgraph", """
{
  "dtype": "float32",
  "metric_type": "l2",
  "dim": 128,
  "index_param": { "base_quantization_type": "sq8" }
}""")

ids  = np.arange(10000, dtype=np.int64)
vecs = np.random.rand(10000, 128).astype("float32")
index.build(vectors=vecs, ids=ids, num_elements=10000, dim=128)

q = np.random.rand(128).astype("float32")
I, D = index.knn_search(vector=q, k=10, parameters='{"hgraph":{"ef_search":100}}')
print("ids:", I)
print("distances:", D)

C++

// link against libvsag, C++17
#include <vsag/vsag.h>
#include <iostream>

auto result = vsag::Factory::CreateIndex("hgraph", R"({
  "dtype": "float32", "metric_type": "l2", "dim": 128,
  "index_param": { "base_quantization_type": "sq8" }
})");
auto index = result.value();

auto dataset = vsag::Dataset::Make();
dataset->Dim(128)->NumElements(n)->Float32Vectors(data)->Ids(ids)->Owner(false);
index->Build(dataset);

auto q = vsag::Dataset::Make();
q->Dim(128)->NumElements(1)->Float32Vectors(query)->Owner(false);
auto r = index->KnnSearch(q, 10, R"({"hgraph":{"ef_search":100}})");
if (!r.has_value()) { std::cerr << r.error().message << "\n"; return 1; }
auto res = r.value();
for (int64_t i = 0; i < res->GetDim(); ++i) {
  std::cout << res->GetIds()[i] << " " << res->GetDistances()[i] << "\n";
}

Need more? Read the full documentation, browse examples/, or try the parameter reference.

Indexes

Pick the right algorithm for your workload

Index Best for Memory Build Query
brute_force Exact ground-truth baseline, small datasets High Instant Slow
hgraph General-purpose, high recall, quantized graph Medium Fast Very fast
ivf High-throughput batch search, GPU-friendly training Low–Medium Fast Fast
sindi Sparse vectors (BM25-style, learned sparse) Low Fast Very fast
pyramid Multi-tenant / partitioned corpora Medium Fast Fast
hnsw Deprecated Classic hierarchical navigable small world High Medium Fast
diskann Deprecated Billion-scale corpora on SSD Low (RAM) Medium Fast (I/O bound)

Ecosystem

Where VSAG runs today

Language bindings

Native C++ API, pyvsag on PyPI, and a TypeScript / Node.js binding published as vsag on npm.

Benchmarks & tooling

A first-class tools/eval runner, dataset loaders for SIFT / GIST / MS MARCO, and scripts to reproduce the numbers in our papers.

Community

Built in the open

VSAG is developed by engineers and researchers across industry and academia. Open issues, send pull requests, or join the conversation.

Open an issue Contributing guide

“A unified builder API for graph, inverted and disk-based indexes — with honest benchmarks and a serialization layer that actually survives production upgrades.”