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.5: accepts the names 0.9 will use (
capacity, routing, ef_search,
k-means nbits) and deprecates the 0.8 spellings they replace
(notes).
- 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).
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.5"
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
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.