lht129/vsag

GitHub License GitHub Release GitHub Contributors

PyPI - Version PyPI - Python Version

What is VSAG

VSAG is a vector indexing library used for similarity search. The indexing algorithm allows users to search through various sizes of vector sets, especially those that cannot fit in memory. The library also provides methods for generating parameters based on vector dimensions and data scale, allowing developers to use it without understanding the algorithm’s principles. VSAG is written in C++ and provides a Python wrapper package called pyvsag and a Node.js/TypeScript binding package called vsag.

Performance

The VSAG algorithm SINDI for sparse vector search achieves a breakthrough in performance, substantially outperforming previous state-of-the-art (SOTA) solutions. In our internal tests on a 40-core Intel(R) Xeon(R) Silver 4210R CPU, VSAG’s QPS exceeds that of the previous SOTA algorithm, Zilliz, by 166% on the sparse-full(8M) at 98% recall. While the official ann-benchmarks on sparse track runs on an Azure Standard D8lds v5 VM, we plan to submit our results under the official benchmark environment soon to formally validate this performance leap.

sparse-full-inner-product

The VSAG algorithm achieves a significant boost of efficiency and outperforms the previous state-of-the-art (SOTA) by a clear margin. Specifically, VSAG’s QPS exceeds that of the previous SOTA algorithm, Glass, by over 100%, and the baseline algorithm, HNSWLIB, by over 300% according to the ann-benchmark result on the GIST dataset at 90% recall. The test in ann-benchmarks is running on an r6i.16xlarge machine on AWS with --parallelism 31, single-CPU, and hyperthreading disabled. The result is as follows:

gist-960-euclidean

Getting Started

Quickstart

Below is a minimal example of creating an HNSW index, building it with random vectors, and performing a k-NN search — shown in C++, Python, and TypeScript.

C++

#include <vsag/vsag.h>
#include <iostream>
#include <random>

int main() {
    // Prepare data
    int64_t num_vectors = 1000, dim = 128;
    auto ids = new int64_t[num_vectors];
    auto vectors = new float[dim * num_vectors];
    std::mt19937 rng(47);
    std::uniform_real_distribution<float> dist;
    for (int64_t i = 0; i < num_vectors; ++i) ids[i] = i;
    for (int64_t i = 0; i < dim * num_vectors; ++i) vectors[i] = dist(rng);

    auto base = vsag::Dataset::Make();
    base->NumElements(num_vectors)->Dim(dim)->Ids(ids)->Float32Vectors(vectors);

    // Create and build index
    auto index = vsag::Factory::CreateIndex("hnsw", R"(
        {"dtype":"float32","metric_type":"l2","dim":128,
         "hnsw":{"max_degree":16,"ef_construction":100}})").value();
    index->Build(base);

    // Search
    auto query_vector = new float[dim];
    for (int64_t i = 0; i < dim; ++i) query_vector[i] = dist(rng);
    auto query = vsag::Dataset::Make();
    query->NumElements(1)->Dim(dim)->Float32Vectors(query_vector)->Owner(true);

    auto result = index->KnnSearch(query, 10, R"({"hnsw":{"ef_search":100}})").value();
    for (int64_t i = 0; i < result->GetDim(); ++i)
        std::cout << result->GetIds()[i] << ": " << result->GetDistances()[i] << std::endl;
    return 0;
}

Python

import pyvsag
import numpy as np
import json

dim = 128
num_elements = 1000

ids = list(range(num_elements))
data = np.float32(np.random.random((num_elements, dim)))

# Create and build index
index_params = json.dumps({
    "dtype": "float32", "metric_type": "l2", "dim": dim,
    "hnsw": {"max_degree": 16, "ef_construction": 100},
})
index = pyvsag.Index("hnsw", index_params)
index.build(vectors=data, ids=ids, num_elements=num_elements, dim=dim)

# Search
query = np.float32(np.random.random(dim))
search_params = json.dumps({"hnsw": {"ef_search": 100}})
result_ids, result_dists = index.knn_search(vector=query, k=10, parameters=search_params)
for rid, rdist in zip(result_ids, result_dists):
    print(f"{rid}: {rdist}")

TypeScript (Node.js)

import { Index } from "vsag";

const dim = 128;
const numVectors = 1000;

const ids = new BigInt64Array(numVectors);
const vectors = new Float32Array(dim * numVectors);
for (let i = 0; i < numVectors; i++) ids[i] = BigInt(i);
for (let i = 0; i < dim * numVectors; i++) vectors[i] = Math.random();

// Create and build index
const indexParams = JSON.stringify({
    dtype: "float32", metric_type: "l2", dim,
    hnsw: { max_degree: 16, ef_construction: 100 },
});
const index = new Index("hnsw", indexParams);
index.build(vectors, ids, numVectors, dim);

// Search
const query = new Float32Array(dim);
for (let i = 0; i < dim; i++) query[i] = Math.random();

const searchParams = JSON.stringify({ hnsw: { ef_search: 100 } });
const { ids: resultIds, distances } = index.knnSearch(query, 10, searchParams);
for (let i = 0; i < 10; i++) {
    console.log(`${resultIds[i]}: ${distances[i]}`);
}

Integrate with CMake

If you have already installed vsag (e.g. cmake --install build-release or via a distribution package), the recommended path is to use the shipped CMake package config and the imported vsag::vsag target:

# CMakeLists.txt
cmake_minimum_required (VERSION 3.18)
project (myproject CXX)

set (CMAKE_CXX_STANDARD 11)
set (CMAKE_CXX_STANDARD_REQUIRED ON)

find_package (vsag CONFIG REQUIRED)

add_executable (vsag-cmake-example src/main.cpp)
target_link_libraries (vsag-cmake-example PRIVATE vsag::vsag)

Point CMake at the install prefix via -DCMAKE_PREFIX_PATH=/path/to/install if vsag is not in a system location.

Alternatively, to fetch and build vsag from source as part of your project:

# CMakeLists.txt
cmake_minimum_required (VERSION 3.18)
project (myproject CXX)

set (CMAKE_CXX_STANDARD 11)
set (CMAKE_CXX_STANDARD_REQUIRED ON)

include (FetchContent)
FetchContent_Declare (
  vsag
  GIT_REPOSITORY https://github.com/antgroup/vsag
  GIT_TAG main
)
FetchContent_MakeAvailable (vsag)

add_executable (vsag-cmake-example src/main.cpp)
target_include_directories (vsag-cmake-example SYSTEM PRIVATE ${vsag_SOURCE_DIR}/include)
target_link_libraries (vsag-cmake-example PRIVATE vsag)
add_dependencies (vsag-cmake-example vsag)

Examples

C++, Python, and TypeScript examples are provided. Please explore the examples directory for details.

We suggest you start with:

C++: 101_index_hnsw.cpp
Python: example_hnsw.py
TypeScript: 101_index_hnsw.ts

Building from Source

Please read the DEVELOPMENT guide for instructions on how to build.

Who’s Using VSAG

vsag_users

If your system uses VSAG, then feel free to make a pull request to add it to the list.

How to Contribute

Although VSAG is initially developed by the Vector Database Team at Ant Group, it’s the work of the community, and contributions are always welcome! See CONTRIBUTING for ways to get started.

Need help filing an issue? Run /create-issue inside Claude Code, OpenCode or Codex, or use the tools/issue-helper/ shell wrapper. The drafting rules live in .github/ISSUE_TEMPLATE/ISSUE_GUIDE.md.

Community

Thrive together in VSAG community with users and developers from all around the world.

Discuss at discord.
Follow us on Weixin Official Accounts（微信公众平台）to get the latest news.

Roadmap v1.0 (ETA Mar. 2026)

Versatile Data Type Support
- FP32 Vectors: For standard, high-precision retrieval scenarios.
- INT8, BF16, FP16 Vectors: Natively support quantized embedding models to reduce memory footprint.
- Sparse Vectors: To enhance text retrieval capabilities.
Optimized Index Types
- HGraph (Graph Index): For scenarios demanding high recall and low latency.
- LazyHGraph (Adaptive Graph Index): Uses exact BruteForce for small FP32 datasets and automatically converts to HGraph after a configurable threshold. Deletes in the flat phase physically remove vectors and shrink storage instead of leaving tombstones. Vector updates use the same public API in both flat and graph phases.
- IVF (Inverted File Index): Optimized for large-scale search (high k) and batch queries.
- SINDI (Sparse Inverted Non-redundant Distance Index): Optimized sparse vector index.
Advanced Quantization Methods
- RaBitQ (BQ): Extreme compression for minimal memory usage.
- PQ (Product Quantization): Flexible compression for tuning the memory-recall trade-off.
- SQ4 & SQ8 (Scalar Quantization): Balanced performance with minimal recall loss for memory and speed gains.
Cross-Platform CPU Optimizations
- x86_64: SSE, AVX, AVX2, AVX512, AMX.
- ARM: Neon, SVE.
- Optional Libraries: Supports Intel-MKL and OpenBLAS for accelerated matrix multiplication.
Granular Resource Management
- Memory Isolation: Per-index memory allocators for tenant-level memory management.
- CPU Control: Supports custom thread pools to scale ingestion and search throughput.

Our Publications

Elastic Index Selection for Label-Hybrid AKNN Search [VLDB, 2026]
Mingyu Yang, Wenxuan Xia, Wentao Li, Raymond Chi-Wing Wong, Wei Wang
PDF | DOI
FGIM: a Fast Graph-based Indexes Merging Framework for Approximate Nearest Neighbor Search [SIGMOD, 2026]
Zekai Wu, Jiabao Jin, Peng Cheng, Xiaoyao Zhong, Lei Chen, Yongxin Tong, Zhitao Shen, Jingkuan Song, Heng Tao Shen, Xuemin Lin
PDF | DOI
SINDI: an Efficient Index for Approximate Maximum Inner Product Search on Sparse Vectors [ICDE, 2026]
Ruoxuan Li, Xiaoyao Zhong, Jiabao Jin, Peng Cheng, Wangze Ni, Lei Chen, Zhitao Shen, Wei Jia, Xiangyu Wang, Xuemin Lin, Heng Tao Shen, Jingkuan Song
PDF
Quantization Meets Projection: A Happy Marriage for Approximate k-Nearest Neighbor Search [VLDB, 2026]
Mingyu Yang, Liuchang Jing, Wentao Li, Wei Wang
PDF
VSAG: An Optimized Search Framework for Graph-based Approximate Nearest Neighbor Search [VLDB (industry), 2025]
Xiaoyao Zhong, Haotian Li, Jiabao Jin, Mingyu Yang, Deming Chu, Xiangyu Wang, Zhitao Shen, Wei Jia, George Gu, Yi Xie, Xuemin Lin, Heng Tao Shen, Jingkuan Song, Peng Cheng
PDF | DOI
Effective and General Distance Computation for Approximate Nearest Neighbor Search [ICDE, 2025]
Mingyu Yang, Wentao Li, Jiabao Jin, Xiaoyao Zhong, Xiangyu Wang, Zhitao Shen, Wei Jia, Wei Wang
PDF | DOI
EnhanceGraph: A Continuously Enhanced Graph-based Index for High-dimensional Approximate Nearest Neighbor Search [arxiv, 2025]
Xiaoyao Zhong, Jiabao Jin, Peng Cheng, Mingyu Yang, Lei Chen, Haoyang Li, Zhitao Shen, Xuemin Lin, Heng Tao Shen, Jingkuan Song
PDF

Reference

VSAG referenced the following works during its implementation:

RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search [SIGMOD, 2024]
Jianyang Gao, Cheng Long
PDF | DOI | CODE

Quasi-succinct Indices [WSDM, 2013]
Sebastiano Vigna
PDF | DOI

Contributors

_LHT129	_inabao	_{Xiangyu Wang}	_{ShawnShawnYou}	_jac	_Roxanne
_Cooper	_Carrot-77	_{Deming Chu}	_azl	_{L J. Yun}	_baoyuan
_jingyueob	_XFMENG17	_{Ant OSS}	_{Jiangtian Feng}	_{Sun Jiayu}	_Danbaiwq
_{HuMing He}	_{Jiacai Liu}	_{Liyao Xiong}	_mly	_Xinger	_cubicc
_dasurax	_{Zihao Wang}	_wei	_LightWant	_liric24	_{Mingyu Yang}
_mukejane	_lhd	_stuBirdFly

Star History

License

Apache License 2.0