RaBitQ-Library

RaBitQ-Library is a research-backed library for vector quantization and approximate nearest-neighbor search. See the research papers.

Why RaBitQ-Library

• Reference implementation. Developed with the RaBitQ authors: 1–9-bit codes with a theoretical error bound, plus indexes and clustering from the same research.
• Fast to build and search. Optimized SIMD kernels and batch scoring keep both indexing and queries fast; see the benchmarks.
• Use an index or the quantizer. Build ready-made indexes in Python or C++, or link only the core and FastScan components into your own engine, as zvec does.

News

• v0.8.4: input validation reads each batch once instead of twice (notes).
• v0.8.3: provisional rabitqlib.quant module: rotate, quantize, pack and score RaBitQ codes stored outside an index (notes).
• v0.8.2: three lines to an index: the first add trains, nbits defaults to 7 and search settings are optional; faster IVF-RaBitQ add (notes).

Earlier versions: all releases.

Vector indexes

Use the included indexes when you want construction, search, and save/load in one library. All three support L2 and inner product; normalize vectors for cosine search. Their structures, storage costs, and search parameters offer different QPS–recall tradeoffs.

Index	Search approach	Storage and updates
IVF-RaBitQ	Partitioned search with batch scoring.	1–9-bit codes or raw-vector reranking; add/remove.
HNSW-RaBitQ	Graph traversal over quantized vectors.	1–9-bit codes plus graph edges; add/remove and resize.
SymphonyQG	Graph search with batched distance estimation.	Raw or 4/8-bit storage; updates require rebuilding.

Native clustering methods prepare centroids and assignments for IVF-RaBitQ and HNSW-RaBitQ.

See the benchmarks for measured results, settings, and limitations.

Quick start

Python

python -m pip install --upgrade "rabitqlib>=0.8.4"

Wheels support CPython 3.11–3.14 on Linux x86-64/ARM64, Windows x86-64, and macOS 14+ ARM64. x86-64 requires AVX2/FMA and optionally uses AVX-512; ARM64 uses NEON. See platform requirements and source installation.

Build and search a small IVF-RaBitQ index with synthetic data; no dataset download is required. This example demonstrates the API, not performance.

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)

index = IvfIndex(64, 5, metric="l2")
index.add(data)  # the first add learns 5 centroids from data
ids, distances = index.search(queries, k=10, nprobe=5)  # probe all 5 clusters
print(ids.shape, distances.shape)  # (5, 10) (5, 10)

The first add learns the centroids from the data, then quantizes the vectors into their clusters. IDs identify added rows; distances here estimate squared L2 distance, with smaller values first. Without nprobe, search probes num_clusters / 16 clusters (at least one); probe more for higher recall. Quantization remains approximate even when all clusters are probed. The complete quick start explains result handling, measures recall while varying nprobe, and shows save/load. Code written for 0.7 still runs in 0.8 with deprecation warnings; see the migration guide.

For other indexes, see the HNSW-RaBitQ and SymphonyQG examples.

C++

Use the C++ integration guide for source builds, component linking, and installation. Start with the C++ index examples, or use the quantization components below in your own engine.

Quantization components

Integrate encoding and distance estimation into your own storage and search engine, independently of the included indexes.

Component	What it provides	Start here
rabitqlib::core	Rotation, per-vector encoding, query preparation, and distance estimation.	Core example · Stable v1 API
rabitqlib::fastscan	Batch encoding and lookup-table scoring over 32-vector layouts, built on core.	FastScan example

See component integration for build options and compatibility, the quantizer guide for encoding choices, and the core benchmark for component throughput and estimation error.

Adoption and resources

Built with RaBitQ-Library

Two examples of direct library integration:

Project	Integration
txtai	Uses the Python IVF-RaBitQ and HNSW-RaBitQ indexes as an embedding-search backend.
zvec	Uses core quantization in its own IVF-RaBitQ and HNSW-RaBitQ indexes, with FastScan batch scoring in IVF-RaBitQ.

The linked walkthroughs describe integration boundaries and provide versioned source references.

RaBitQ across the vector-search ecosystem

The projects below illustrate adoption of RaBitQ techniques across vector search. They do not necessarily depend on RaBitQ-Library; direct library integrations are listed above.

Further reading

• Documentation and algorithm overview.
• Papers and citations for the research behind the library.
• Release notes and 0.7 migration guide.
• GPU implementation in cuVS.

Contributing

Start with the contribution guide or starter tasks. Report bugs and request features through GitHub Issues.

Authors and acknowledgements

RaBitQ Library is led and maintained by Yutong Gou, and developed with Jianyang Gao, Yuexuan Xu, Jifan Shi, Zhonghao Yang, Tamim Ehsan, and Cheng Long. We thank Alexandr Guzhva, Li Liu, Chao Gao, Silu Huang, Jiabao Jin, Xiaoyao Zhong, and Jinjing Zhou for their valuable feedback.

License

RaBitQ Library is available under the Apache License 2.0.