Repository navigation
[MOD-21133] Implement MVP SQ8 for FP64 - #1121
alexd-redis wants to merge 8 commits into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1121 +/- ##
==========================================
+ Coverage 97.52% 97.57% +0.05%
==========================================
Files 157 160 +3
Lines 10012 10150 +138
==========================================
+ Hits 9764 9904 +140
+ Misses 248 246 -2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
| Metric == VecSimMetric_Cosine); | ||
|
|
||
| public: | ||
| SQ8FP64Preprocessor(std::shared_ptr<VecSimAllocator> allocator, size_t dim); |
There was a problem hiding this comment.
I'm wondering if we extend QuantPreprocessor to support FP64 instead of introducing a parallel implementation? Most of the preprocessing flow is identical. The arithmetic and metadata types could follow the storage type, with direct division retained for FP64 where reciprocal overflow matters. Is there a concrete constraint that makes sharing the implementation impractical?
| squares += value * value; | ||
| } | ||
| } | ||
| const double metadata[] = {minimum, delta, sum, squares}; |
There was a problem hiding this comment.
The FP64 IP and L2 kernels only consume the codes, minimum, and delta. Do we need the stored/query sums and sums of squares yet? Unless another consumer requires them, could we avoid computing and storing unused metadata?
| // Cosine storage and query inputs must already be normalized by the caller. | ||
| template <VecSimMetric Metric> | ||
| IndexComponents<double, double> | ||
| CreateSQ8FP64IndexComponents(const std::shared_ptr<VecSimAllocator> &allocator, size_t dim) { |
There was a problem hiding this comment.
Could we extend the existing quantized component factory and preprocessor to support FP64 instead of adding parallel implementations? Most of the setup and preprocessing flow is shared. Precision-specific arithmetic can remain separate where necessary.
| // SQ8 bytes followed by double reconstruction metadata; distinct from the FP32 SQ8 layout. | ||
| struct sq8_fp64 : quantized_metadata { | ||
| using value_type = uint8_t; | ||
| using metadata_type = double; |
There was a problem hiding this comment.
Keeping minimum and delta as double makes sense for general FP64 support. A constant vector [100000001, 100000001] has zero codes; storing its minimum as float rounds it to 100000000 and gives squared L2 distance 2 against the original vector instead of 0. Delta also needs double to cover ranges such as 1e100 and 1e-300, where float would overflow or underflow. I would keep these two fields as double and focus metadata savings on the unused sums discussed separately.
| const double close[] = {1.0, 1.0 + std::ldexp(1.0, -40)}; | ||
| const auto precise = preprocessors->preprocessForStorage(close, sizeof(close)); | ||
| EXPECT_DOUBLE_EQ(readMetadata(precise.get(), 2, sq8_fp64::DELTA), std::ldexp(1.0, -40) / 255); | ||
| EXPECT_NEAR(calculator->calcDistance(precise.get(), precise.get(), 2), 0.0, 1e-40); |
There was a problem hiding this comment.
Could we also add a stored-to-stored precision regression with two distinct blobs sharing a large minimum but differing by small code contributions, asserting a nonzero distance in both operand orders? This assertion compares a blob with itself, while the dedicated small-residual test exercises stored-to-query L2. A distinct-blob case would protect the cancellation-resistant stored-to-stored formula against being replaced with naive reconstructed subtraction.
Describe the changes in the pull request
Add reusable, untrained FP64 SQ8 components with double metadata, queries and distance results. For
[1e8, 1e8 + 1]versus[1e8, 1e8], squared L2 remains1instead of losing the difference through float narrowing.Share the stored-query L2 loop between SQ8 FP32 and FP64 using precision derived from the storage type; preserve arithmetic order and unaligned reads.
Scope is component support; cosine inputs must already be normalized. Training, public quantized-index admission and persistence are excluded. Disk integration belongs to [MOD-19593 Implement FLOAT64 vectors in disk HNSW](https://redislabs.atlassian.net/browse/MOD-19593); the FP64 persisted layout/version must be chosen there alongside trained-SQ8 compatibility.
Which issues this PR fixes
Main objects this PR modified
Validation
Mark if applicable
Note
Medium Risk
New numerical distance/preprocessing code on the core VecSim path; behavior is precision-sensitive but isolated behind new FP64 SQ8 types and heavily tested, with no serialization/API changes in this PR.
Overview
Adds an MVP scalar-quantized (SQ8) path for
doublevectors with double metadata, full-precision queries, and double distance results—aimed at cases like large nearby values where FP32 narrowing would erase tiny L2 gaps.The change introduces
vecsim_types::sq8_fp64,SQ8FP64Preprocessor(storage/query/in-place quantization), scalar L2/IP kernels for stored–stored and stored–query modes,GetDistFuncdispatch inspaces.cpp, andCreateSQ8FP64IndexComponentsto wire calculator + preprocessor. Cosine assumes inputs are already normalized; training, index admission, and persistence are out of scope here.Shared L2 helper:
quantized_kernels.hgains a genericStoredQueryL2driven by each storage type’smetadata_type; existingFP32_L2Sqrdelegates to it.sq8now declaresmetadata_type = floatexplicitly.Unit tests cover layouts, extreme magnitudes, unaligned blobs, ranking preservation (e.g.
1e8offsets), and analytical error bounds.Reviewed by Cursor Bugbot for commit 50fb62c. Bugbot is set up for automated code reviews on this repo. Configure here.