Implementation of IndexIVFRaBitQFastScan #4596

alibeklfc · 2025-09-30T04:20:21Z

Summary:
Introduction

This diff implements IndexIVFRaBitQFastScan, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search.

Implementation

New Source and Header Files: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ.
Batched Processing: The new index inherits from IndexIVFFastScan. It processes 32 database vectors simultaneously using SIMD operations.
Specialized Post-processing Handler: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations.
LUT: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes.
Centered parameter: Implements both centered and non-centered query quantization modes
Query Offset Parameter: Added a query offset parameter similarly as in D81787307

Testing

Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations
All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan.

Results
ivfrabitq2
ivfrabitq1

Performance Dependency: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb.

Differential Revision: D83264335

facebook-github-bot · 2025-09-30T04:20:33Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating diff in D83264335.

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T04:30:42Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating diff in D83264335.

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T04:47:18Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating diff in D83264335.

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T16:06:11Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

facebook-github-bot · 2025-09-30T16:14:29Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

Summary: Pull Request resolved: #4596 **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T16:18:19Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

facebook-github-bot · 2025-09-30T16:29:50Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

Summary: Pull Request resolved: #4596 **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T16:40:23Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

facebook-github-bot · 2025-09-30T16:41:33Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

Summary: Pull Request resolved: #4596 **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T17:39:09Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

Summary: Pull Request resolved: #4596 **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

alexanderguzhva · 2025-09-30T18:00:09Z

faiss/IndexFastScan.cpp

    using accu_t = typename C::T;

+    // Check if this is RaBitQ for specialized distance computation
+    const IndexRaBitQFastScan* rabitq_index =


This totally violates the fundamentals of object-oriented programming. The base class IndexFastScan must know nothing about a derived class IndexRaBitQFastScan. Please consider reorganizing this.

alexanderguzhva · 2025-09-30T18:02:03Z

faiss/IndexFastScan.cpp

+    if (rabitq_index != nullptr) {
+        // Use RaBitQHeapHandler for RaBitQ (direct processing, no
+        // post-processing needed)
+        RaBitQHeapHandler<C> rabitq_handler(


same story here and below

alexanderguzhva · 2025-09-30T18:03:18Z

faiss/IndexIVFFastScan.cpp

+        idx_t query_offset = 0) {
+    // Check if this is IndexIVFRaBitQFastScan and create specialized handler
+    if (index) {
+        auto* rabitq_index = dynamic_cast<const IndexIVFRaBitQFastScan*>(index);


same story about IndexIVFFastScan and IndexIVFRaBitQFastScan

alexanderguzhva · 2025-09-30T18:06:05Z

faiss/IndexIVFRaBitQFastScan.cpp

+    float v_min = std::numeric_limits<float>::max();
+    float v_max = std::numeric_limits<float>::lowest();
+
+    if (centered) {


do I get it correct that this is a copy-pasted code from impl/RaBitQuantizer.cpp? This creates a need to synchronize the changes between this code and impl/RaBitQuantizer.cpp. Please reorganize the code to have only 1 instance of these facilities, if possible

alexanderguzhva · 2025-09-30T18:07:29Z

@alibeklfc I would strongly recommend refactoring the candidate code

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

facebook-github-bot · 2025-09-30T18:26:49Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

meta-codesync · 2025-10-02T17:29:15Z

@alibeklfc has exported this pull request. If you are a Meta employee, you can view the originating Diff in D83264335.

alibeklfc · 2025-10-02T17:40:34Z

@alexanderguzhva Thank you for your valuable feedback!

I have addressed your comments. The IndexFastScan and IndexIVFFastScan do not know anything about the child classes now. I have made the make_knn_handler function part of the main class and we override it in the child classes.

I have also created the RaBitQUtils namespace to eliminate code duplication.

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

Summary: **Introduction** This diff adds a new index called the IndexRaBitQFastScan algorithm. The algorithm is based on the existing IndexRaBitQ but achieves higher speed as it processes batches of 32 data vectors concurrently. It leverages the established IndexFastScan architecture to enable efficient batch processing and parallelism. **Implementation** * **New Source and Header Files**: Added implementations for IndexRaBitQFastScan, following a similar interface to IndexRaBitQ. * **Batched Processing**: The search operation processes multiple (32) data vectors in a single batch, taking advantage of low-level parallelism to improve throughput. * **Specialized Post-processing Handler**: A dedicated handler was added for IndexRaBitQFastScan to perform necessary post-processing during search because the LUT accumulates only partial distances. Unlike AQ Fast Scan's simple scalar post-processing, RaBitQ requires complex distance adjustments depending on both query and database vector factors. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexRaBitQ due to an extra quantization step in the IndexFastScan architecture. Specifically: * The LUT computes a float value as c1 * inner_product + c2 * popcount, which is then quantized. This quantization can cause the results to differ slightly from those of IndexRaBitQ. * It is possible to avoid this by storing only the inner_product in the LUT, but doing so would require calculating all data vector popcounts during search, introducing a tradeoff between speed and accuracy. * With the idea proposed in diff D80904214, the algorithm can be modified in the future to eliminate the popcount calculation step, potentially improving both efficiency and accuracy. * **Query Offset Parameter**: RaBitQ uses query factors in distance calculations that should be computed in `compute_float_LUT` method (the most efficient place since we are calculating `rotated_qq` anyways) and used for final distance calculations in handlers. However, the previous version of `compute_quantized_LUT` that calls `compute_float_LUT` did not know the query_offset, preventing proper storage of query factors at their global indices. To solve this, I added the extra parameter `query_offset` to both `compute_quantized_LUT` and `compute_float_LUT` methods. After this change, computed query factors can be accessed by the correct global query index during distance calculations, avoiding expensive recalculation. **Testing** * Conducted comprehensive tests in the test_rabitq suite covering accuracy comparisons with IndexRaBitQ for L2 and Inner Product metrics, encoding/decoding consistency, query quantization bit settings, small dataset functionality, performance against PQFastScan, serialization, memory management, error handling, and thread safety. * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** results_rabitq * **Performance Dependency**: Performance measurements confirm that IndexRaBitQFastScan is notably faster than IndexRaBitQ when the qb value is high. While the original IndexRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. * **Parallelized Training Loop**: The training loop is parallelized, greatly reducing training time. This parallelism should also be added to the original IndexRaBitQ. * **Consistency Across Metrics**: The performance advantages of IndexRaBitQFastScan hold true for both L2 and Inner Product metrics, demonstrating robustness across different distance measures. * One of the next steps is to benchmark IndexRaBitQFastScan against other algorithms to evaluate its performance in a broader context. Differential Revision: D81787307

Summary: **Introduction** This diff implements `IndexIVFRaBitQFastScan`, a high-performance approximate nearest neighbor search index that combines Inverted File (IVF) partitioning, RaBitQ quantization, and FastScan batch processing for significant performance improvements in vector similarity search. **Implementation** * **New Source and Header Files**: Added implementations for IndexIVFRaBitQFastScan, following a similar interface to IndexIVFRaBitQ. * **Batched Processing**: The new index inherits from `IndexIVFFastScan`. It processes 32 database vectors simultaneously using SIMD operations. * **Specialized Post-processing Handler**: Extends the FastScan framework with RaBitQ-aware handler factories that automatically detect and optimize for RaBitQ indices, maintaining compatibility with existing IVF search parameters while enabling specialized optimizations. * **LUT**: IndexRaBitQFastScan produces slightly different results than IndexIVFRaBitQ due to an extra quantization step in the IndexFastScan architecture. Computes lookup tables using query residuals (query minus coarse centroid) with probe-specific query factors, ensuring accurate distance calculations across different inverted list probes. * **Centered parameter**: Implements both centered and non-centered query quantization modes * **Query Offset Parameter**: Added a query offset parameter similarly as in D81787307 **Testing** * Includes extensive test suite covering performance benchmarks, distance calculation correctness, recall measurements, and cross-validation against reference implementations * All tests passed successfully, validating the correctness and robustness of IndexRaBitQFastScan. **Results** ivfrabitq2 ivfrabitq1 * **Performance Dependency**: Performance measurements confirm that IndexIVFRaBitQFastScan is notably faster than IndexIVFRaBitQ when the qb value is high. While the original IndexIVFRaBitQ experiences increased runtime with higher qb values, the fast scan variant maintains consistent runtime regardless of qb. Differential Revision: D83264335

alexanderguzhva · 2025-10-02T22:28:01Z

@alibeklfc thanks, let me go through both diffs carefully. Would you like to have #4595 commited prior to #4596?

alibeklfc · 2025-10-03T14:11:02Z

@alexanderguzhva #4595 should be committed before #4596, but I want both of them to commit as soon as possible for benchmarking and internal usage. Thank you!

alexanderguzhva · 2025-10-06T01:10:06Z

@alibeklfc let's deal with #4595 first, because might need some work

meta-cla bot added the CLA Signed label Sep 30, 2025

facebook-github-bot added fb-exported meta-exported labels Sep 30, 2025

alibeklfc changed the title ~~Implementation of IndexIVFRaBitQFastScan~~ IndexIVFRaBitQFastScan and IndexRaBitQFastScan Sep 30, 2025

facebook-github-bot force-pushed the export-D83264335 branch from 95ff1a9 to 0fa69c9 Compare September 30, 2025 04:30

alibeklfc changed the title ~~IndexIVFRaBitQFastScan and IndexRaBitQFastScan~~ Implementation of IndexIVFRaBitQFastScan Sep 30, 2025

facebook-github-bot force-pushed the export-D83264335 branch from 0fa69c9 to 91acfae Compare September 30, 2025 04:47

facebook-github-bot force-pushed the export-D83264335 branch from 91acfae to 6503695 Compare September 30, 2025 16:06

alibeklfc force-pushed the export-D83264335 branch from 6503695 to 34869f6 Compare September 30, 2025 16:14

facebook-github-bot force-pushed the export-D83264335 branch from 34869f6 to a50840a Compare September 30, 2025 16:18

alibeklfc force-pushed the export-D83264335 branch from a50840a to 75663c0 Compare September 30, 2025 16:29

facebook-github-bot force-pushed the export-D83264335 branch from 75663c0 to 48c78a9 Compare September 30, 2025 16:40

alibeklfc force-pushed the export-D83264335 branch from 48c78a9 to 08d0b29 Compare September 30, 2025 16:41

alibeklfc force-pushed the export-D83264335 branch from 08d0b29 to f390459 Compare September 30, 2025 17:39

alexanderguzhva suggested changes Sep 30, 2025

View reviewed changes

facebook-github-bot force-pushed the export-D83264335 branch from f390459 to fea8385 Compare September 30, 2025 18:26

facebook-github-bot force-pushed the export-D83264335 branch from fea8385 to 9fd9010 Compare October 2, 2025 17:28

facebook-github-bot force-pushed the export-D83264335 branch from 9fd9010 to 42058e0 Compare October 2, 2025 17:46

facebook-github-bot force-pushed the export-D83264335 branch from 42058e0 to 657e12f Compare October 2, 2025 17:59

facebook-github-bot force-pushed the export-D83264335 branch from 657e12f to 5a39a29 Compare October 2, 2025 19:11

alibeklfc added 2 commits October 2, 2025 14:42

facebook-github-bot force-pushed the export-D83264335 branch from 5a39a29 to 80a15bf Compare October 2, 2025 21:43

Implementation of IndexIVFRaBitQFastScan #4596

Are you sure you want to change the base?

Implementation of IndexIVFRaBitQFastScan #4596

Uh oh!

Conversation

alibeklfc commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

alexanderguzhva Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

alexanderguzhva Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

alexanderguzhva Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

alexanderguzhva Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

alexanderguzhva commented Sep 30, 2025

Uh oh!

facebook-github-bot commented Sep 30, 2025

Uh oh!

meta-codesync bot commented Oct 2, 2025

Uh oh!

alibeklfc commented Oct 2, 2025

Uh oh!

alexanderguzhva commented Oct 2, 2025

Uh oh!

alibeklfc commented Oct 3, 2025

Uh oh!

alexanderguzhva commented Oct 6, 2025

Uh oh!

Uh oh!