diff --git a/src/VecSim/spaces/computer/preprocessors.h b/src/VecSim/spaces/computer/preprocessors.h index 4746458d2..1cab517a6 100644 --- a/src/VecSim/spaces/computer/preprocessors.h +++ b/src/VecSim/spaces/computer/preprocessors.h @@ -272,10 +272,9 @@ class QuantPreprocessor : public PreprocessorInterface { using OUTPUT_TYPE = uint8_t; using MetadataType = float; // Quantized storage metadata is always FP32. - // SQ4's centered IP correction x_mean_ip describes the reconstructed vector, like the other + // The centered IP correction x_mean_ip describes the reconstructed vector, like the other // stored sums, so it is accumulated from the generated codes instead of the input values. - static constexpr bool kMeanIpFromCodes = - WithNorm && Metric == VecSimMetric_IP && std::is_same_v; + static constexpr bool kMeanIpFromCodes = WithNorm && Metric == VecSimMetric_IP; static_assert(Metric == VecSimMetric_L2 || Metric == VecSimMetric_IP || Metric == VecSimMetric_Cosine, @@ -288,8 +287,7 @@ class QuantPreprocessor : public PreprocessorInterface { void quantize(const DataType *input, OUTPUT_TYPE *quantized) const { assert(input && quantized); - float x_mean_ip = 0.0f; // only used for WithNorm - auto [min_val, max_val] = find_min_max(input, x_mean_ip); + auto [min_val, max_val] = find_min_max(input); // Calculate scaling factor (typed as MetadataType because they end up as metadata). const MetadataType diff = (max_val - min_val); @@ -330,7 +328,7 @@ class QuantPreprocessor : public PreprocessorInterface { // the metadata rather than round it. This is the write path, once per vector. uint64_t q0{}, q1{}, q2{}, q3{}; // only used for L2 - // For centered SQ4 IP, the mean correction is accumulated from the codes as they are + // For centered IP, the mean correction is accumulated from the codes as they are // generated (see kMeanIpFromCodes), in coordinate order with one accumulator. const double d_min = min_val, d_delta = delta; [[maybe_unused]] double reconstructed_mean_ip = 0.0; @@ -413,10 +411,6 @@ class QuantPreprocessor : public PreprocessorInterface { d_delta * d_delta * q_sum_squares); } - if constexpr (kMeanIpFromCodes) { - x_mean_ip = static_cast(reconstructed_mean_ip); - } - // Metadata uses MetadataType. Use memcpy because the metadata offset (after the // quantized body, packed for SQ4) is not guaranteed to be sizeof(MetadataType)-aligned. void *meta_dst = quantized + StorageType::data_bytes_count(this->dim); @@ -425,7 +419,7 @@ class QuantPreprocessor : public PreprocessorInterface { if constexpr (Metric == VecSimMetric_L2) buf[n++] = sum_squares; if constexpr (WithNorm && Metric == VecSimMetric_IP) - buf[n++] = x_mean_ip; + buf[n++] = static_cast(reconstructed_mean_ip); memcpy(meta_dst, buf, n * sizeof(MetadataType)); } @@ -666,7 +660,7 @@ class QuantPreprocessor : public PreprocessorInterface { return value; } - std::pair find_min_max(const DataType *input, float &x_mean_ip) const { + std::pair find_min_max(const DataType *input) const { if constexpr (!WithNorm) { auto [min_it, max_it] = std::minmax_element(input, input + dim); return {to_fp32(*min_it), to_fp32(*max_it)}; @@ -675,18 +669,11 @@ class QuantPreprocessor : public PreprocessorInterface { float value = first_input_value - mean[0]; float min_val = value; float max_val = value; - // x_mean_ip only feeds the IP correction term (see DistanceCalculatorWithNorm); the - // normalized L2 correction cancels the mean terms exactly, so skip the extra work. - if constexpr (Metric == VecSimMetric_IP && !kMeanIpFromCodes) - x_mean_ip = first_input_value * mean[0]; - for (size_t i = 1; i < dim; ++i) { const float input_value = to_fp32(input[i]); value = input_value - mean[i]; min_val = std::min(min_val, value); max_val = std::max(max_val, value); - if constexpr (Metric == VecSimMetric_IP && !kMeanIpFromCodes) - x_mean_ip += input_value * mean[i]; } return {min_val, max_val}; } diff --git a/tests/unit/test_components.cpp b/tests/unit/test_components.cpp index 6744756b3..bb6c72653 100644 --- a/tests/unit/test_components.cpp +++ b/tests/unit/test_components.cpp @@ -1487,7 +1487,7 @@ void checkSQ8Bytes(size_t dim) { const double reconstructed = kMin + kStep * codes[i]; sum += reconstructed; sum_squares += reconstructed * reconstructed; - mean_ip += double(input_fp32[i]) * mean[i]; + mean_ip += (reconstructed + mean[i]) * mean[i]; } std::vector expected_metadata = {float(kMin), float(kStep), float(sum)}; if constexpr (Metric == VecSimMetric_L2) { @@ -1562,6 +1562,65 @@ TEST(PreprocessorsTest, QuantizedStorageSQ8BytesUnchanged) { checkSQ8BytesAllModes(); } +template +void checkSQ8CenteredIPReconstruction() { + // The endpoints fix min=-4 and max=7. The interior values do not fall exactly on + // the 255-step quantization grid, so an input-based correction fails this case. + const std::vector centered = {-4.0f, 7.0f, 0.25f, 1.5f, -2.75f, 3.25f, 4.5f}; + const std::vector mean = {2.0f, -3.0f, 4.0f, 1.0f, -2.0f, 3.0f, -1.0f}; + const std::vector expected_codes = {0, 255, 99, 128, 29, 168, 197}; + auto allocator = VecSimAllocator::newVecsimAllocator(); + // Exercise every remainder of the four-wide quantization loop. + for (size_t dim : {4u, 5u, 6u, 7u}) { + SCOPED_TRACE(::testing::Message() << "dim=" << dim << " fp16=" + << (std::is_same_v)); + std::vector input(dim); + for (size_t i = 0; i < dim; ++i) { + input[i] = fromFloat(centered[i] + mean[i]); + } + auto components = CreateQuantizedIndexComponents( + allocator, dim, mean.data()); + std::unique_ptr> calculator(components.indexCalculator); + std::unique_ptr preprocessors(components.preprocessors); + auto blob = preprocessors->preprocessForStorage(input.data(), dim * sizeof(DataType)); + const auto *bytes = static_cast(blob.get()); + ASSERT_EQ(std::vector(bytes, bytes + dim), + std::vector(expected_codes.begin(), expected_codes.begin() + dim)); + + const double min = -4.0; + const double delta = float(11.0f / 255.0f); + double mean_ip = 0.0, input_mean_ip = 0.0, self_ip = 0.0; + for (size_t i = 0; i < dim; ++i) { + const double reconstructed = min + delta * expected_codes[i] + mean[i]; + mean_ip += reconstructed * mean[i]; + input_mean_ip += double(centered[i] + mean[i]) * mean[i]; + self_ip += reconstructed * reconstructed; + } + ASSERT_GT(std::abs(mean_ip - input_mean_ip), 0.01); + EXPECT_FLOAT_EQ(load_unaligned(bytes + dim + 3 * sizeof(float)), float(mean_ip)); + EXPECT_NEAR(calculator->calcDistance(blob.get(), blob.get(), dim), 1.0 - self_ip, 5e-5); + + // In-place quantization must produce the identical complete blob even though the + // input values are overwritten before the correction is finished. + auto *container = + dynamic_cast *>(preprocessors.get()); + ASSERT_NE(container, nullptr); + auto *quantizer = dynamic_cast *>( + container->getPreprocessors()[0]); + ASSERT_NE(quantizer, nullptr); + const size_t blob_size = sq8::storage_bytes_count(dim); + std::vector in_place(std::max(blob_size, dim * sizeof(DataType))); + std::memcpy(in_place.data(), input.data(), dim * sizeof(DataType)); + quantizer->preprocessStorageInPlace(in_place.data(), in_place.size()); + EXPECT_EQ(std::memcmp(in_place.data(), bytes, blob_size), 0); + } +} + +TEST(PreprocessorsTest, SQ8CenteredIPCorrectionMatchesReconstructedValues) { + checkSQ8CenteredIPReconstruction(); + checkSQ8CenteredIPReconstruction(); +} + // Parameterized test class for QuantPreprocessor with different metrics class QuantPreprocessorMetricTest : public testing::TestWithParam { protected: @@ -1990,7 +2049,7 @@ class QuantPreprocessorWithNormMetricTestBase : public testing::TestWithParam(expected_query_body[i]); - expected_x_mean_ip += widened_blob[i] * mean_vec[i]; expected_y_sum += query_value; expected_y_sum_squares += query_value * query_value; expected_y_mean_ip += widened_blob[i] * mean_vec[i]; @@ -2011,6 +2069,11 @@ class QuantPreprocessorWithNormMetricTestBase : public testing::TestWithParam(baseline_storage + dim); + const double delta = load_unaligned(baseline_storage + dim + sizeof(float)); + for (size_t i = 0; i < dim; ++i) { + expected_x_mean_ip += (min + delta * baseline_storage[i] + mean_vec[i]) * mean_vec[i]; + } vecsim_stl::vector mean_vector(allocator); for (size_t i = 0; i < dim; ++i) {