txtai: using the complete indexes¶

txtai exposes RaBitQ-Library through its rabitq ANN backend. Applications can select an IVF-RaBitQ or HNSW-RaBitQ index within txtai's embedding-search workflow, while txtai handles the surrounding application API and result conversion.

This walkthrough was checked on October 21, 2026 against txtai commit 0ea7cb0d8234. It describes the downstream adapter at that revision; it is a source snapshot, not a verification of every published txtai package. Consult the current configuration reference for later changes.

Select the backend¶

In an existing txtai embeddings configuration, select backend: rabitq and add the corresponding settings. This fragment uses four-bit IVF-RaBitQ:

backend: rabitq
rabitq:
  mode: ivf
  nbits: 4

Keep your existing embedding model and other application settings. Install optional dependencies according to txtai's installation guide; its adapter imports both rabitqlib and scikit-learn. The inspected package configuration declares rabitqlib>=0.7.0 in its ann extra. The fragment above selects the backend, rather than providing a complete model-and-data example.

clusters controls the KMeans centroid count in both modes: IVF-RaBitQ uses these centroids for partitioning, while HNSW-RaBitQ uses them for residual quantization. nprobe controls how many IVF-RaBitQ clusters are searched. For HNSW-RaBitQ, select mode: hnsw and use m, efconstruction, and efsearch. Both modes accept 1–9 quantization bits; IVF-RaBitQ also accepts nbits: 32 for original-vector reranking. Measure recall and latency on representative queries when choosing precision and search parameters.

How the integration works¶

The adapter source shows the boundary between the projects:

Stage	txtai's role	RaBitQ-Library's role
Build	Converts embeddings to contiguous float32 and uses scikit-learn KMeans to produce centroids and assignments.	Builds `IvfIndex` or `HnswIndex` with the inner-product metric.
Search	Selects `nprobe` or `ef`, drops missing-result IDs, and converts returned distances to scores with `1 - distance`.	Searches the native index and returns IDs and distances; quantized modes return estimates, while IVF-RaBitQ raw mode uses original-vector reranking.
Persistence	Calls the backend's save/load methods.	Stores and restores the native index state.
Updates	Routes IVF-RaBitQ append/delete requests to the backend.	Adds vectors or removes them from search.

This is an example of integrating complete indexes: txtai calls the Python index APIs without implementing RaBitQ encoding or graph traversal itself.

Boundaries to keep in mind¶

At the inspected revision, txtai enables append/delete only for IVF-RaBitQ. Its HNSW-RaBitQ adapter raises NotImplementedError for append/delete through the ANN base class, even though RaBitQ-Library itself supports HNSW-RaBitQ updates. IVF-RaBitQ additions reuse the original clusters, and deletions retain their storage; txtai recommends rebuilding when new data differs enough to affect recall. See its versioned configuration documentation for these limits.

The adapter requests inner-product search and converts its 1 - dot distance convention back to scores. For normalized database and query embeddings, these are cosine-similarity estimates in quantized modes; normalization does not remove quantization error.

The source inspection establishes the integration path. It does not establish production deployment scale or a performance gain, and this configuration has not been exercised end to end in this documentation update.

For maintainer checks against future library versions, see the downstream compatibility procedure.

To use the same indexes directly, follow the library's Python quick start and HNSW-RaBitQ guide. To integrate only quantization into your own index, see the zvec walkthrough.