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.
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.
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:
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.
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("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;
}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,
"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}")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,
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]}`);
}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)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
Please read the DEVELOPMENT guide for instructions on how to build.
If your system uses VSAG, then feel free to make a pull request to add it to the list.
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.
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.
-
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.
- Elastic
-
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.
- HGraph Build Memory Estimator: Estimate peak construction memory before starting an index build.
- Pip-Installable Analysis Tools: Make index diagnostics available through
pyvsagwithout requiring a source build.
-
Lightweight Deployment and Storage Integration
- VSAG Lite: Provide a lightweight variant with essential indexing, search, update, and persistence capabilities for resource-constrained deployments.
- Pluggable Storage I/O: Extend custom reader and writer support for external storage integration.
- Lower Memory Footprint: Reduce redundant storage in immutable indexes and improve binary distribution packaging.
-
Python and RAG Ecosystem
- LangChain Integration: Provide a
pyvsagVectorStore adapter for document retrieval and RAG workflows. - Sparse Input Helpers: Simplify conversion from named term-weight mappings to SINDI-compatible sparse vectors.
- LangChain Integration: Provide a
-
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 | DOI -
Quantization Meets Projection: A Happy Marriage for Approximate k-Nearest Neighbor Search [VLDB, 2026]
Mingyu Yang, Liuchang Jing, Wentao Li, Wei Wang
PDF | DOI -
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 [TKDE]
Xiaoyao Zhong, Jiabao Jin, Peng Cheng, Mingyu Yang, Lei Chen, Haoyang Li, Zhitao Shen, Xuemin Lin, Heng Tao Shen, Jingkuan Song
PDF | DOI
VSAG draws on the following works for graph construction, vector quantization, filtered search, and integer compression:
-
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 -
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 -
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 -
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 -
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 -
Practical and Asymptotically Optimal Quantization of High-Dimensional Vectors in Euclidean Space for Approximate Nearest Neighbor Search [SIGMOD, 2025]
Jianyang Gao, Yutong Gou, Yuexuan Xu, Yongyi Yang, Cheng Long, Raymond Chi-Wing Wong
Multi-bit quantization in the extended RaBitQ implementation.
PDF | DOI -
SAQ: Pushing the Limits of Vector Quantization through Code Adjustment and Dimension Segmentation [SIGMOD, 2026]
Hui Li, Shiyuan Deng, Xiao Yan, Xiangyu Zhi, James Cheng
Code adjustment for the optional fast encoding path in the RaBitQ quantizer.
PDF | DOI -
MCI: A Maximal Clique Index for Efficient Arbitrary-Filtered Approximate Nearest Neighbor Search [arXiv, 2026]
Xiaowei Ye, Rong-Hua Li, Guoren Wang, Kaiwen Xue, Daiyin Wang, Xubin Li
Clique-based indexing and filtered search in HGraph's MCI mode.
PDF -
Quasi-succinct Indices [WSDM, 2013]
Sebastiano Vigna
Elias–Fano integer encoding in the compression implementation.
PDF | DOI
