VSAG

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.

HGraph supports experimental, opt-in adaptive alpha for PiPNN L2 builds; see the HGraph parameter guide.

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 HGraph index, building it with random vectors, and performing a k-NN search — shown in C++, Python, and TypeScript.

#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("hgraph", R"(
        {"dtype":"float32","metric_type":"l2","dim":128,
         "index_param":{"base_quantization_type":"fp32","max_degree":16,
         "ef_construction":100,"alpha":1.2}})").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"({"hgraph":{"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;
}

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,
    "index_param": {"base_quantization_type": "fp32", "max_degree": 16,
                    "ef_construction": 100, "alpha": 1.2},
})
index = pyvsag.Index("hgraph", 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({"hgraph": {"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}")

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,
    index_param: { base_quantization_type: "fp32", max_degree: 16,
                   ef_construction: 100, alpha: 1.2 },
});
const index = new Index("hgraph", 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({ hgraph: { 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++: 103_index_hgraph.cpp
• Python: 103_index_hgraph.py
• TypeScript: 103_index_hgraph.ts

Building from Source

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

Who's Using VSAG

• OceanBase
• TuGraph
• GreptimeDB
• Hologres
• PolarDB

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.2 (ETA Dec. 2026)

• Adaptive and Concurrent Search

  • Elastic ef_search: Adapt search effort to individual queries to balance recall and latency.
  • Multi-Core Search Scalability: Improve concurrent search throughput through better cache utilization, memory access, and NUMA awareness.

• Unified Indexing and Hybrid Retrieval

  • HGraph v2: Integrate capabilities from LazyHGraph, MCI, and Pyramid into a unified index with comprehensive filtering and search optimizations.
  • Dense–Sparse Hybrid Search: Support retrieval that combines dense and sparse similarity with configurable query-time weights.
  • SINDI_V2: Complete the sparse-vector index introduced in v1.1 as a work in progress, with optimized in-memory and disk-based search.
  • Hamming Distance: Enable similarity search over binary vectors.
  • Grouped Retrieval: Support multiple vectors per entity with collapsed and expanded search results.

• Faster Index Construction and Balanced Partitioning

  • GPU-Accelerated HGraph Construction: Accelerate graph building with GPU computation.
  • Random Projection Tree Partitioning: Provide balanced, reproducible partitions for clustering and parallel index construction.
  • Balanced K-Means: Add capacity-constrained clustering to produce balanced IVF partitions.
  • Efficient Graph Merging and Reuse: Reuse existing graph structures during index merging and parameter tuning to reduce construction costs.

• Advanced Quantization

  • SAQ Quantization: Introduce code adjustment and dimension segmentation for improved quantization efficiency and accuracy.
  • Multi-Centroid Residual RaBitQ: Improve compression quality by quantizing residuals around multiple centroids.
  • Efficient Scalar Quantization: Optimize local SQ4/SQ8 computation and reduce redundant storage between search and reranking.

• Index Diagnostics and Capacity Planning

  • New Index Diagnostics: Expand index inspection and query analysis to help identify index-quality and search-performance bottlenecks.
  • Dataset Profiling and Visualization: Analyze vector distributions, sparsity, clustering structure, and distance characteristics.

Our Publications

1. Elastic Index Selection for Label-Hybrid AKNN Search [VLDB, 2026]
   Mingyu Yang, Wenxuan Xia, Wentao Li, Raymond Chi-Wing Wong, Wei Wang
   PDF | DOI

2. 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

3. 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 | DOI

4. Quantization Meets Projection: A Happy Marriage for Approximate k-Nearest Neighbor Search [VLDB, 2026]
   Mingyu Yang, Liuchang Jing, Wentao Li, Wei Wang
   PDF | DOI

5. 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

Reference

VSAG draws on the following works for graph construction, vector quantization, filtered search, and integer compression:

1. Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs [TPAMI, 2020]
   Yu. A. Malkov, D. A. Yashunin
   Hierarchical graph construction and search in HGraph.
   PDF | DOI

2. Efficient K-Nearest Neighbor Graph Construction for Generic Similarity Measures [WWW, 2011]
   Wei Dong, Moses Charikar, Kai Li
   NN-Descent neighbor refinement underlying the ODescent graph builder.
   PDF | DOI

3. PiPNN: Ultra-Scalable Graph-Based Nearest Neighbor Indexing [arXiv, 2026]
   Tobias Rubel, Richard Wen, Laxman Dhulipala, Lars Gottesbüren, Rajesh Jayaram, Jakub Łącki
   Parallel graph construction in the PiPNN builder used by HGraph and Pyramid.
   PDF | CODE

4. Product Quantization for Nearest Neighbor Search [TPAMI, 2011]
   Hervé Jégou, Matthijs Douze, Cordelia Schmid
   Subspace codebooks and lookup-table distance computation in the product quantizer.
   PDF | DOI

5. RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search [SIGMOD, 2024]
   Jianyang Gao, Cheng Long
   Randomized binary quantization and distance estimation in the RaBitQ quantizer.
   PDF | DOI | CODE

Contributors

Star History

License

Apache License 2.0