Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 6 additions & 19 deletions src/VecSim/spaces/computer/preprocessors.h
Original file line number Diff line number Diff line change
Expand Up @@ -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<StorageType, vecsim_types::sq4>;
static constexpr bool kMeanIpFromCodes = WithNorm && Metric == VecSimMetric_IP;

static_assert(Metric == VecSimMetric_L2 || Metric == VecSimMetric_IP ||
Metric == VecSimMetric_Cosine,
Expand All @@ -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);
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -413,10 +411,6 @@ class QuantPreprocessor : public PreprocessorInterface {
d_delta * d_delta * q_sum_squares);
}

if constexpr (kMeanIpFromCodes) {
x_mean_ip = static_cast<MetadataType>(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);
Expand All @@ -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<MetadataType>(reconstructed_mean_ip);
memcpy(meta_dst, buf, n * sizeof(MetadataType));
}

Expand Down Expand Up @@ -666,7 +660,7 @@ class QuantPreprocessor : public PreprocessorInterface {
return value;
}

std::pair<float, float> find_min_max(const DataType *input, float &x_mean_ip) const {
std::pair<float, float> find_min_max(const DataType *input) const {
if constexpr (!WithNorm) {
auto [min_it, max_it] = std::minmax_element(input, input + dim);
return {to_fp32<DataType>(*min_it), to_fp32<DataType>(*max_it)};
Expand All @@ -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<DataType>(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};
}
Expand Down
69 changes: 66 additions & 3 deletions tests/unit/test_components.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<float> expected_metadata = {float(kMin), float(kStep), float(sum)};
if constexpr (Metric == VecSimMetric_L2) {
Expand Down Expand Up @@ -1562,6 +1562,65 @@ TEST(PreprocessorsTest, QuantizedStorageSQ8BytesUnchanged) {
checkSQ8BytesAllModes<vecsim_types::float16>();
}

template <typename DataType>
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<float> centered = {-4.0f, 7.0f, 0.25f, 1.5f, -2.75f, 3.25f, 4.5f};
const std::vector<float> mean = {2.0f, -3.0f, 4.0f, 1.0f, -2.0f, 3.0f, -1.0f};
const std::vector<uint8_t> 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<DataType, vecsim_types::float16>));
std::vector<DataType> input(dim);
for (size_t i = 0; i < dim; ++i) {
input[i] = fromFloat<DataType>(centered[i] + mean[i]);
}
auto components = CreateQuantizedIndexComponents<DataType, VecSimMetric_IP, sq8>(
allocator, dim, mean.data());
std::unique_ptr<IndexCalculatorInterface<float>> calculator(components.indexCalculator);
std::unique_ptr<PreprocessorsContainerAbstract> preprocessors(components.preprocessors);
auto blob = preprocessors->preprocessForStorage(input.data(), dim * sizeof(DataType));
const auto *bytes = static_cast<const uint8_t *>(blob.get());
ASSERT_EQ(std::vector<uint8_t>(bytes, bytes + dim),
std::vector<uint8_t>(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<float>(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<MultiPreprocessorsContainer<DataType, 1> *>(preprocessors.get());
ASSERT_NE(container, nullptr);
auto *quantizer = dynamic_cast<QuantPreprocessor<DataType, VecSimMetric_IP, true> *>(
container->getPreprocessors()[0]);
ASSERT_NE(quantizer, nullptr);
const size_t blob_size = sq8::storage_bytes_count<VecSimMetric_IP, true>(dim);
std::vector<uint8_t> 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<float>();
checkSQ8CenteredIPReconstruction<vecsim_types::float16>();
}

// Parameterized test class for QuantPreprocessor with different metrics
class QuantPreprocessorMetricTest : public testing::TestWithParam<VecSimMetric> {
protected:
Expand Down Expand Up @@ -1990,7 +2049,7 @@ class QuantPreprocessorWithNormMetricTestBase : public testing::TestWithParam<Ve
const size_t query_meta_offset = dim * sizeof(QueryType);
float centered[dim];
QueryType expected_query_body[dim];
float expected_x_mean_ip = 0.0f;
double expected_x_mean_ip = 0.0;
float expected_y_sum = 0.0f;
float expected_y_sum_squares = 0.0f;
float expected_y_mean_ip = 0.0f;
Expand All @@ -2002,7 +2061,6 @@ class QuantPreprocessorWithNormMetricTestBase : public testing::TestWithParam<Ve
expected_query_body[i] = original_blob[i];
}
const float query_value = to_fp32<QueryType>(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];
Expand All @@ -2011,6 +2069,11 @@ class QuantPreprocessorWithNormMetricTestBase : public testing::TestWithParam<Ve
constexpr size_t max_storage_baseline = dim * sizeof(uint8_t) + 4 * sizeof(float);
uint8_t baseline_storage[max_storage_baseline];
ComputeSQ8Quantization(centered, dim, baseline_storage);
const double min = load_unaligned<float>(baseline_storage + dim);
const double delta = load_unaligned<float>(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<float> mean_vector(allocator);
for (size_t i = 0; i < dim; ++i) {
Expand Down
Loading