A research-backed C++17 library with Python bindings for 1-bit and multi-bit
vector quantization, IVF, HNSW, and SymphonyQG.
Documentation · Python package · Paper · Releases · Maintenance
-
September 2026 — IVF raw-vector reranking: Set
nbits=32to store raw float32 vectors for reranking. IVF now selects HACC automatically for 4–9-bit codes, using standard FastScan for 1–3 bits and raw vectors; manual overrides remain available. See the IVF documentation. -
September 2026 — Quantized SymphonyQG: SymphonyQG now supports optional 4-bit and 8-bit RaBitQ vector storage. Select QG-quant with
quantization_bits=4orquantization_bits=8; vanilla raw-vector QG remains the default. See the SymphonyQG documentation for details.
pip install rabitqlibPrebuilt wheels support Linux x86-64 and CPython 3.11–3.14. AVX2 + FMA is the portable CPU baseline; supported AVX-512 kernels are selected at runtime.
The following complete example builds a small IVF index and searches it. It uses deterministic synthetic data, so no dataset download is required.
import numpy as np
from rabitqlib import IvfIndex
rng = np.random.default_rng(42)
data = rng.standard_normal((500, 64)).astype(np.float32)
queries = rng.standard_normal((5, 64)).astype(np.float32)
# Assign vectors to five clusters and calculate their centroids.
cluster_ids = (np.arange(len(data)) % 5).astype(np.uint32)
centroids = np.stack(
[data[cluster_ids == cluster].mean(axis=0) for cluster in range(5)]
).astype(np.float32)
index = IvfIndex(
dim=64,
max_elements=len(data),
num_clusters=5,
nbits=4,
metric="l2",
)
index.build(data, centroids, cluster_ids)
ids, distances = index.search(queries, k=10, nprobe=5)
print(ids.shape, distances.shape) # (5, 10) (5, 10)
print(ids[0])Python bindings are also available for HnswIndex and SymqgIndex. See the
Python examples for index construction, querying, and index
persistence.
Build the Python bindings from source
Source builds require a C++17 compiler, CMake 3.15 or newer, and OpenMP. On Ubuntu or Debian:
sudo apt-get update
sudo apt-get install -y build-essential cmake libomp-dev
git clone https://github.com/VectorDB-NTU/RaBitQ-Library.git
cd RaBitQ-Library
python -m pip install .| Component | Best fit | Storage and search profile |
|---|---|---|
| Quantizer | Integrating RaBitQ into an existing system | Low-level 1-bit or multi-bit encoding and distance estimation. |
| IVF | Memory-efficient partitioned search | Stores quantized codes, or one-bit codes plus raw vectors for reranking. |
| HNSW | Graph search with compact vectors | Adds graph links and searches directly from quantized codes. |
| SymphonyQG | Fast graph search with a configurable memory/accuracy tradeoff | Uses raw vectors by default, or optional packed 4-bit/8-bit RaBitQ vectors, alongside per-neighborhood quantization data. |
IVF and SymphonyQG use FastScan for batched estimates, while HNSW uses single-code AVX2 or AVX-512 kernels.
In typical workloads, 4-bit, 5-bit, and 7-bit quantization can achieve roughly 90%, 95%, and 99% recall, respectively, without reranking. Actual results depend on the dataset, index configuration, and search parameters.
| Compact by design | Choose 1-bit or multi-bit codes to match your memory and accuracy target. |
| Accurate estimates | An asymptotically optimal theoretical error bound supports reliable ordering and reranking. |
| Fast on x86-64 | Dedicated AVX2 and AVX-512 kernels are selected through runtime CPU dispatch. |
| Ready for ANN search | Use the quantizer directly or build complete IVF, HNSW, and SymphonyQG indexes. |
The library supports Euclidean distance and inner product. Cosine search is available by normalizing vectors before using inner product.
RaBitQ is developed by the VectorDB group at Nanyang Technological University, Singapore. A GPU implementation is also available in cuvs_rabitq.
Average and maximum relative estimation error across six datasets; lower is better. Results from the SIGMOD camera-ready paper.
The projects below illustrate adoption of RaBitQ techniques across vector search; this is not a list of direct dependencies on RaBitQ-Library.
Integration story: How zvec integrates RaBitQ-Library traces its use of the library's quantizers and estimators inside zvec's IVF and HNSW implementations, with links to the source code.
 Milvus |
 Faiss |
 NVIDIA cuVS |
 Microsoft DiskANN |
 VSAG |
 VectorChord |
 Volcengine OpenSearch |
 CockroachDB |
 Elasticsearch |
 Apache Lucene |
 turbopuffer |
 Zvec |
 LanceDB |
 Databricks |
 ClickHouse |
 Qdrant |
 Weaviate |
- CMake 3.15 or newer
- a C++17 compiler with OpenMP support
- an x86-64 CPU supported by the selected kernels: most paths accept either AVX2 with FMA or AVX-512F/BW/DQ with FMA
CPU dispatch details
Most SIMD entry points select AVX-512 kernels when AVX-512F, AVX-512BW, and AVX-512DQ are detected; otherwise they use AVX2 when AVX2 and FMA are available. AVX-512 VPOPCNTDQ enables additional popcount kernels. The HNSW AVX-512 core path also checks for AVX2 and FMA. AVX-512 translation units are compiled with FMA enabled.
Clone and build the library and example programs:
git clone https://github.com/VectorDB-NTU/RaBitQ-Library.git
cd RaBitQ-Library
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallelRelease builds enable native CPU tuning by default. To build a binary that can
be moved between AVX2- and AVX-512-capable machines, configure with
-DRABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF; the ISA-specific kernels will still
be selected at runtime.
The C++ API and ABI are still evolving. For reproducible builds, pin a release or commit and include RaBitQ-Library as a Git submodule:
git submodule add https://github.com/VectorDB-NTU/RaBitQ-Library.git third_party/rabitqlib
git submodule update --init --recursiveAdd the library and link its namespaced target in the consuming project's
CMakeLists.txt:
set(RABITQ_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
add_subdirectory(third_party/rabitqlib)
target_link_libraries(my_program PRIVATE rabitqlib::rabitqlib)Update the pinned revision deliberately when you are ready to adopt upstream changes:
git -C third_party/rabitqlib fetch
git -C third_party/rabitqlib checkout <release-or-commit>
git add third_party/rabitqlibOptional: install the C++ library
Installation is useful for package managers, container images, and shared server environments. Disable native optimization when the installed library may run on a different CPU from the build machine:
cmake -S . -B build \
-DRABITQ_BUILD_SAMPLES=OFF \
-DRABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build --parallel
cmake --install buildConsume the installed package with:
find_package(rabitqlib CONFIG REQUIRED)
target_link_libraries(my_program PRIVATE rabitqlib::rabitqlib)For a non-system prefix, point CMake to the installation when configuring the consumer:
cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/.local"
cmake --build build --parallelThe downstream consumer test provides a minimal complete example of the installed-package workflow.
Both integration methods require OpenMP on the consuming system.
The index example executables are written to bin/. Their source code shows
the complete indexing and querying workflows:
A separate RaBitQ quantization example demonstrates the lower-level quantizer API; it is provided as source and is not currently a CMake target.
To build and run the C++ test suite:
cmake -S . -B build -DRABITQ_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failureGoogleTest is downloaded during test configuration. For a full benchmark on
the GIST dataset, see example.sh. More detailed API and
algorithm guidance is available in the documentation.
If RaBitQ helps your research or system, please cite:
Jianyang Gao, Yutong Gou, Yuexuan Xu, Yongyi Yang, Cheng Long, and Raymond Chi-Wing Wong. “Practical and Asymptotically Optimal Quantization of High-Dimensional Vectors in Euclidean Space for Approximate Nearest Neighbor Search.” Proceedings of the ACM on Management of Data 3, 3, Article 202 (June 2025), 26 pages. https://doi.org/10.1145/3725413.
Yutong Gou, Jianyang Gao, Yuexuan Xu, and Cheng Long. “SymphonyQG: Towards Symphonious Integration of Quantization and Graph for Approximate Nearest Neighbor Search.” Proceedings of the ACM on Management of Data 3, 1, Article 80 (February 2025), 26 pages. https://doi.org/10.1145/3709730.
Jianyang Gao and Cheng Long. “RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search.” Proceedings of the ACM on Management of Data 2, 3, Article 167 (May 2024), 27 pages. https://doi.org/10.1145/3654970.
Contributions are welcome, including documentation and examples. Start with your first contribution or choose a small starter task. The guide explains which build, test, and formatting checks apply to your change.
See maintenance and feedback for the current maintainer. Use GitHub Issues for bugs, feature requests, and usage or contribution questions.
RaBitQ Library is developed by Yutong Gou, Jianyang Gao, Yuexuan Xu, Jifan Shi, and Zhonghao Yang. We thank Alexandr Guzhva, Li Liu, Chao Gao, Silu Huang, Jiabao Jin, Xiaoyao Zhong, and Jinjing Zhou for their valuable feedback.
RaBitQ Library is available under the Apache License 2.0.