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
5 changes: 5 additions & 0 deletions src/VecSim/algorithms/hnsw/hnsw.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
#include "VecSim/vec_sim_index.h"
#include "VecSim/spaces/computer/preprocessors.h"
#include "VecSim/quantization/sq8_mean.h"
#include "VecSim/quantization/turboquant_components.h"
#include <span>
#include "VecSim/tombstone_interface.h"

Expand Down Expand Up @@ -106,6 +107,10 @@ class HNSWIndex : public VecSimIndexAbstract<DataType, DistType>,
// A quantizer that learns storedDataSize from data needs deferred backend creation.
void setQuantizationMean(std::span<const float> mean) noexcept {
assert(this->isQuantized && curElementCount == 0 && mean.size() == this->dim);
if (auto *codec = vecsim::quantization::GetTurboQuantCodec(this->getIndexCalculator())) {
codec->setMean(mean);
return;
}
if constexpr (QuantInput<DataType> && std::is_same_v<DistType, float>) {
if (this->metric == VecSimMetric_L2) {
setSQ8Mean<VecSimMetric_L2>(mean);
Expand Down
1 change: 1 addition & 0 deletions src/VecSim/algorithms/hnsw/hnsw_base_tests_friends.h
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,4 @@ INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_updateVectorsTwiceBeforeIngesti
INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_updateVectorsAsync_Test)
INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_addRelabelAndUpdateTogetherUnderLoad_Test)
INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_queryWhileUpdating_Test)
friend class TurboQuantTest;
2 changes: 1 addition & 1 deletion src/VecSim/algorithms/hnsw/hnsw_serializer.h
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ class HNSWSerializer : public Serializer {
DEPRECATED = 2, // Last deprecated version
V3,
V4,
V5, // scalar quantization fields (quantType + mean vector)
V5, // quantization fields (quantType + mean vector, or TQ2/TQ3 fitted state)
INVALID
};

Expand Down
18 changes: 12 additions & 6 deletions src/VecSim/algorithms/hnsw/hnsw_serializer_impl.h
Original file line number Diff line number Diff line change
Expand Up @@ -266,12 +266,18 @@ void HNSWIndex<DataType, DistType>::saveIndexFields(std::ofstream &output) const
// V5 fields: scalar quantization support (between factory params and index build params)
if (this->quantType != VecSimQuant_NONE) {
writeBinaryPOD(output, this->quantType);
// Write mean vector (dim floats). Empty vector means no mean (zero-mean quantization).
bool hasMean = !this->serializedMeanVector.empty();
writeBinaryPOD(output, hasMean);
if (hasMean) {
output.write(reinterpret_cast<const char *>(this->serializedMeanVector.data()),
this->dim * sizeof(float));
if (const auto *codec =
vecsim::quantization::GetTurboQuantCodec(this->getIndexCalculator())) {
// TQ2/TQ3 write their fitted state (including the full rotation) instead of a mean.
codec->saveFitted(output);
} else {
// Write mean vector (dim floats). Empty vector means no mean (zero-mean quantization).
bool hasMean = !this->serializedMeanVector.empty();
writeBinaryPOD(output, hasMean);
if (hasMean) {
output.write(reinterpret_cast<const char *>(this->serializedMeanVector.data()),
this->dim * sizeof(float));
}
}
}

Expand Down
1 change: 1 addition & 0 deletions src/VecSim/algorithms/hnsw/hnsw_tiered_tests_friends.h
Original file line number Diff line number Diff line change
Expand Up @@ -97,3 +97,4 @@ INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_updateVectorsTwiceBeforeIngesti
INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_updateVectorsAsync_Test)
INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_addRelabelAndUpdateTogetherUnderLoad_Test)
INDEX_TEST_FRIEND_CLASS(HNSWTieredIndexTestBasic_queryWhileUpdating_Test)
friend class TurboQuantTest;
62 changes: 58 additions & 4 deletions src/VecSim/index_factories/hnsw_factory.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,17 @@
#include "VecSim/types/bfloat16.h"
#include "VecSim/types/float16.h"
#include "VecSim/types/sq4.h"
#include "VecSim/types/turboquant.h"
#include "VecSim/quantization/turboquant_components.h"

#include <type_traits>

using bfloat16 = vecsim_types::bfloat16;
using float16 = vecsim_types::float16;
using sq8 = vecsim_types::sq8;
using sq4 = vecsim_types::sq4;
using vecsim::quantization::isTurboQuant;
using vecsim::quantization::turboQuantBits;

namespace HNSWFactory {

Expand Down Expand Up @@ -57,6 +61,10 @@ template <VecSimMetric Metric, typename StorageType = sq8>
[[nodiscard]] constexpr bool QuantizationParamsSupported(VecSimQuantType quant_type,
VecSimType type,
VecSimMetric resolved_metric) {
// TurboQuant has FP32 inner-product kernels only; cosine requires normalized input.
if (quant_type == VecSimQuant_TQ2 || quant_type == VecSimQuant_TQ3) {
return type == VecSimType_FLOAT32 && resolved_metric == VecSimMetric_IP;
}
// Reject unknown quantizers instead of silently creating an unquantized index.
if (quant_type != VecSimQuant_SQ8 && quant_type != VecSimQuant_SQ4) {
return false;
Expand Down Expand Up @@ -98,6 +106,23 @@ VecSimIndex *NewIndex_Quantized(const HNSWParams *hnswParams,
return index;
}

// The codec constructor rejects an unsupported dim or a nonfinite mean.
static VecSimIndex *NewIndex_TurboQuant(const HNSWParams *hnswParams,
AbstractIndexInitParams abstractInitParams) {
auto components = vecsim::quantization::CreateTurboQuantIndexComponents(
abstractInitParams.allocator, abstractInitParams.dim, turboQuantBits(hnswParams->quantType),
static_cast<const VecSimTurboQuantParams *>(hnswParams->quantParams));
abstractInitParams.storedDataSize =
vecsim::quantization::GetTurboQuantCodec(components.indexCalculator)->storageBytes();
abstractInitParams.isQuantized = true;
auto index =
NewIndex_ChooseMultiOrSingle<float, float>(hnswParams, abstractInitParams, components);
#ifdef BUILD_TESTS
index->quantType = hnswParams->quantType;
#endif
return index;
}

VecSimIndex *NewIndex(const VecSimParams *params, bool is_normalized) {
const HNSWParams *hnswParams = &params->algoParams.hnswParams;
AbstractIndexInitParams abstractInitParams =
Expand All @@ -111,6 +136,10 @@ VecSimIndex *NewIndex(const VecSimParams *params, bool is_normalized) {
return NULL;
}

if (isTurboQuant(hnswParams->quantType)) {
return NewIndex_TurboQuant(hnswParams, abstractInitParams);
}

if (hnswParams->quantType == VecSimQuant_SQ4) {
if (metric == VecSimMetric_L2) {
return NewIndex_Quantized<float, VecSimMetric_L2, sq4>(
Expand Down Expand Up @@ -216,7 +245,10 @@ size_t EstimateInitialSize(const HNSWParams *params, bool is_normalized, bool wi
sizeof(QuantPreprocessor<float, VecSimMetric_L2, true>));
static_assert(sizeof(QuantPreprocessor<float, VecSimMetric_L2, false, sq4>) ==
sizeof(QuantPreprocessor<float, VecSimMetric_L2>));
if (with_mean) {
if (isTurboQuant(params->quantType)) {
est += vecsim::quantization::EstimateTurboQuantComponentsMemory(
params->dim, turboQuantBits(params->quantType));
} else if (with_mean) {
est += allocations_overhead +
sizeof(DistanceCalculatorWithNorm<float, float, VecSimMetric_L2>);
est += allocations_overhead + sizeof(MultiPreprocessorsContainer<float, 1>);
Expand Down Expand Up @@ -264,7 +296,16 @@ size_t EstimateElementSize(const HNSWParams *params, bool with_mean) {

size_t stored_data_size;
// Preserve the element estimator's existing contract: return a size and validate in NewIndex.
if (params->quantType == VecSimQuant_SQ4) {
if (isTurboQuant(params->quantType)) {
if (params->type != VecSimType_FLOAT32 ||
(params->metric != VecSimMetric_IP && params->metric != VecSimMetric_Cosine) ||
!vecsim::quantization::TurboQuant::dimSupported(params->dim)) {
return SIZE_MAX;
}
stored_data_size = params->quantType == VecSimQuant_TQ2
? vecsim_types::tq2::storage_bytes_count(params->dim)
: vecsim_types::tq3::storage_bytes_count(params->dim);
} else if (params->quantType == VecSimQuant_SQ4) {
stored_data_size =
params->metric == VecSimMetric_L2
? GetQuantizedStoredDataSize<VecSimMetric_L2, sq4>(params->dim, with_mean)
Expand Down Expand Up @@ -361,11 +402,13 @@ static bool InitializeParams(std::ifstream &source_params, HNSWParams &params,
std::underlying_type_t<VecSimQuantType> raw_quant_type;
Serializer::readBinaryPOD(source_params, raw_quant_type);
if (raw_quant_type != VecSimQuant_NONE && raw_quant_type != VecSimQuant_SQ8 &&
raw_quant_type != VecSimQuant_SQ4) {
raw_quant_type != VecSimQuant_SQ4 && raw_quant_type != VecSimQuant_TQ2 &&
raw_quant_type != VecSimQuant_TQ3) {
return false;
}
params.quantType = static_cast<VecSimQuantType>(raw_quant_type);
if (params.quantType != VecSimQuant_NONE) {
// TQ2/TQ3 store fitted state here instead; the loader reads it with the codec.
if (params.quantType != VecSimQuant_NONE && !isTurboQuant(params.quantType)) {
bool hasMean = false;
Serializer::readBinaryPOD(source_params, hasMean);
if (hasMean) {
Expand Down Expand Up @@ -417,6 +460,17 @@ VecSimIndex *NewIndex(const std::string &location, bool is_normalized) {
return NULL;
}

if (isTurboQuant(params.quantType)) {
auto codec = vecsim::quantization::TurboQuant::loadFitted(
input, abstractInitParams.allocator, params.dim, turboQuantBits(params.quantType));
abstractInitParams.isQuantized = true;
abstractInitParams.storedDataSize = codec->storageBytes();
auto components = vecsim::quantization::CreateTurboQuantIndexComponents(
abstractInitParams.allocator, std::move(codec));
return NewIndex_ChooseMultiOrSingle<float, float>(input, &params, abstractInitParams,
components, version);
}

if (params.quantType == VecSimQuant_SQ4) {
if (metric == VecSimMetric_L2) {
return LoadIndex_Quantized<float, VecSimMetric_L2, sq4>(
Expand Down
16 changes: 14 additions & 2 deletions src/VecSim/index_factories/tiered_factory.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@

using bfloat16 = vecsim_types::bfloat16;
using float16 = vecsim_types::float16;
using vecsim::quantization::isTurboQuant;

namespace TieredFactory {

Expand All @@ -40,7 +41,8 @@ static inline BFParams NewBFParams(const TieredIndexParams *params) {
}

static inline bool RequiresQuantizationTraining(const TieredIndexParams *params) {
return params->primaryIndexParams->algoParams.hnswParams.quantType == VecSimQuant_SQ8 &&
const auto type = params->primaryIndexParams->algoParams.hnswParams.quantType;
return (type == VecSimQuant_SQ8 || isTurboQuant(type)) &&
params->specificParams.tieredHnswParams.QuantNormalizationSetSize > 0;
}

Expand All @@ -53,6 +55,8 @@ static inline bool IsQuantizationSupported(const TieredIndexParams *params) {

if constexpr (!QuantInput<DataType> || !std::is_same_v<DistType, float>) {
return false;
} else if constexpr (std::is_same_v<DataType, float>) {
return hnsw_params.quantType == VecSimQuant_SQ8 || isTurboQuant(hnsw_params.quantType);
} else {
return hnsw_params.quantType == VecSimQuant_SQ8;
}
Expand All @@ -68,7 +72,15 @@ inline VecSimIndex *NewIndex(const TieredIndexParams *params) {
auto management_layer_allocator = VecSimAllocator::newVecsimAllocator();
VecSimParams backend_params = *params->primaryIndexParams;
vecsim_stl::vector<float> initial_mean(management_layer_allocator);
if (RequiresQuantizationTraining(params)) {
VecSimTurboQuantParams tq_params{.mean = nullptr, .seed = VECSIM_TURBOQUANT_DEFAULT_SEED};
if (RequiresQuantizationTraining(params) && isTurboQuant(hnsw_params.quantType)) {
// TQ2/TQ3 always carry a mean. Start from zero; tiered installs the trained mean.
if (const auto *config =
static_cast<const VecSimTurboQuantParams *>(hnsw_params.quantParams)) {
tq_params.seed = config->seed;
}
backend_params.algoParams.hnswParams.quantParams = &tq_params;
} else if (RequiresQuantizationTraining(params)) {
// Allocate the final SQ8 WithMean layout now. The factory copies this temporary mean;
// tiered keeps the graph empty until it installs the mean accumulated from FLAT.
initial_mean.resize(hnsw_params.dim, 0.0f);
Expand Down
Loading
Loading