Skip to content

[8.2] [MOD-10654] [MOD-10694] Enhance SVS Debug Info Iterator #739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 7, 2025
Merged

[8.2] [MOD-10654] [MOD-10694] Enhance SVS Debug Info Iterator #739

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions src/VecSim/algorithms/hnsw/hnsw.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2143,12 +2143,12 @@ VecSimDebugInfoIterator *HNSWIndex<DataType, DistType>::debugInfoIterator() cons
.fieldValue = {FieldValue{.uintegerValue = info.hnswInfo.entrypoint}}});

infoIterator->addInfoField(
VecSim_InfoField{.fieldName = VecSimCommonStrings::HNSW_EPSILON_STRING,
VecSim_InfoField{.fieldName = VecSimCommonStrings::EPSILON_STRING,
.fieldType = INFOFIELD_FLOAT64,
.fieldValue = {FieldValue{.floatingPointValue = info.hnswInfo.epsilon}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::HNSW_NUM_MARKED_DELETED,
.fieldName = VecSimCommonStrings::NUM_MARKED_DELETED,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.hnswInfo.numberOfMarkedDeletedNodes}}});

Expand Down
8 changes: 8 additions & 0 deletions src/VecSim/algorithms/hnsw/hnsw_tiered.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1145,6 +1145,9 @@ VecSimIndexDebugInfo TieredHNSWIndex<DataType, DistType>::debugInfo() const {
HnswTieredInfo hnswTieredInfo = {.pendingSwapJobsThreshold = this->pendingSwapJobsThreshold};
info.tieredInfo.specificTieredBackendInfo.hnswTieredInfo = hnswTieredInfo;

info.tieredInfo.backgroundIndexing =
info.tieredInfo.frontendCommonInfo.indexSize > 0 ? VecSimBool_TRUE : VecSimBool_FALSE;

return info;
}

Expand All @@ -1154,6 +1157,11 @@ VecSimDebugInfoIterator *TieredHNSWIndex<DataType, DistType>::debugInfoIterator(
// Get the base tiered fields.
auto *infoIterator = VecSimTieredIndex<DataType, DistType>::debugInfoIterator();

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_BACKGROUND_INDEXING_STRING,
.fieldType = INFOFIELD_INT64,
.fieldValue = {FieldValue{.integerValue = info.tieredInfo.backgroundIndexing}}});

// Tiered HNSW specific param.
infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_HNSW_SWAP_JOBS_THRESHOLD_STRING,
Expand Down
70 changes: 69 additions & 1 deletion src/VecSim/algorithms/svs/svs.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -374,7 +374,7 @@ class SVSIndex : public VecSimIndexAbstract<svs_details::vecsim_dt<DataType>, fl
VecSimDebugInfoIterator *debugInfoIterator() const override {
VecSimIndexDebugInfo info = this->debugInfo();
// For readability. Update this number when needed.
size_t numberOfInfoFields = 10;
size_t numberOfInfoFields = 23;
VecSimDebugInfoIterator *infoIterator =
new VecSimDebugInfoIterator(numberOfInfoFields, this->allocator);

Expand All @@ -384,10 +384,78 @@ class SVSIndex : public VecSimIndexAbstract<svs_details::vecsim_dt<DataType>, fl
.fieldValue = {
FieldValue{.stringValue = VecSimAlgo_ToString(info.commonInfo.basicInfo.algo)}}});
this->addCommonInfoToIterator(infoIterator, info.commonInfo);

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::BLOCK_SIZE_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.commonInfo.basicInfo.blockSize}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_QUANT_BITS_STRING,
.fieldType = INFOFIELD_STRING,
.fieldValue = {
FieldValue{.stringValue = VecSimQuantBits_ToString(info.svsInfo.quantBits)}}});

infoIterator->addInfoField(
VecSim_InfoField{.fieldName = VecSimCommonStrings::SVS_ALPHA_STRING,
.fieldType = INFOFIELD_FLOAT64,
.fieldValue = {FieldValue{.floatingPointValue = info.svsInfo.alpha}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_GRAPH_MAX_DEGREE_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.graphMaxDegree}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_CONSTRUCTION_WS_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.constructionWindowSize}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_MAX_CANDIDATE_POOL_SIZE_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.maxCandidatePoolSize}}});

infoIterator->addInfoField(
VecSim_InfoField{.fieldName = VecSimCommonStrings::SVS_PRUNE_TO_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.pruneTo}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_USE_SEARCH_HISTORY_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.useSearchHistory}}});

infoIterator->addInfoField(
VecSim_InfoField{.fieldName = VecSimCommonStrings::SVS_NUM_THREADS_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.numThreads}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::NUM_MARKED_DELETED,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.numberOfMarkedDeletedNodes}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_SEARCH_WS_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.searchWindowSize}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::SVS_SEARCH_BC_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.searchBufferCapacity}}});

infoIterator->addInfoField(
VecSim_InfoField{.fieldName = VecSimCommonStrings::SVS_LEANVEC_DIM_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.svsInfo.leanvecDim}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::EPSILON_STRING,
.fieldType = INFOFIELD_FLOAT64,
.fieldValue = {FieldValue{.floatingPointValue = info.svsInfo.epsilon}}});

return infoIterator;
}

Expand Down
33 changes: 32 additions & 1 deletion src/VecSim/algorithms/svs/svs_tiered.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -750,12 +750,17 @@ class TieredSVSIndex : public VecSimTieredIndex<DataType, float> {

VecSimIndexDebugInfo debugInfo() const override {
auto info = Base::debugInfo();

SvsTieredInfo svsTieredInfo = {.trainingTriggerThreshold = this->trainingTriggerThreshold,
.updateTriggerThreshold = this->updateTriggerThreshold,
.updateJobWaitTime = this->updateJobWaitTime,
.indexUpdateScheduled =
static_cast<bool>(this->indexUpdateScheduled.test())};
info.tieredInfo.specificTieredBackendInfo.svsTieredInfo = svsTieredInfo;
info.tieredInfo.backgroundIndexing =
svsTieredInfo.indexUpdateScheduled && info.tieredInfo.frontendCommonInfo.indexSize > 0
? VecSimBool_TRUE
: VecSimBool_FALSE;
return info;
}

Expand All @@ -770,7 +775,33 @@ class TieredSVSIndex : public VecSimTieredIndex<DataType, float> {
VecSimDebugInfoIterator *debugInfoIterator() const override {
// Get the base tiered fields.
auto *infoIterator = Base::debugInfoIterator();
// TODO: Add SVS specific info.
VecSimIndexDebugInfo info = this->debugInfo();

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_BACKGROUND_INDEXING_STRING,
.fieldType = INFOFIELD_INT64,
.fieldValue = {FieldValue{.integerValue = info.tieredInfo.backgroundIndexing}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_SVS_TRAINING_THRESHOLD_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {
FieldValue{.uintegerValue = info.tieredInfo.specificTieredBackendInfo.svsTieredInfo
.trainingTriggerThreshold}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_SVS_UPDATE_THRESHOLD_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {
FieldValue{.uintegerValue = info.tieredInfo.specificTieredBackendInfo.svsTieredInfo
.updateTriggerThreshold}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_SVS_THREADS_RESERVE_TIMEOUT_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{
.uintegerValue =
info.tieredInfo.specificTieredBackendInfo.svsTieredInfo.updateJobWaitTime}}});
return infoIterator;
}

Expand Down
41 changes: 39 additions & 2 deletions src/VecSim/utils/vec_utils.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,14 +49,22 @@ const char *VecSimCommonStrings::MEMORY_STRING = "MEMORY";
const char *VecSimCommonStrings::HNSW_EF_RUNTIME_STRING = "EF_RUNTIME";
const char *VecSimCommonStrings::HNSW_M_STRING = "M";
const char *VecSimCommonStrings::HNSW_EF_CONSTRUCTION_STRING = "EF_CONSTRUCTION";
const char *VecSimCommonStrings::HNSW_EPSILON_STRING = "EPSILON";
const char *VecSimCommonStrings::EPSILON_STRING = "EPSILON";
const char *VecSimCommonStrings::HNSW_MAX_LEVEL = "MAX_LEVEL";
const char *VecSimCommonStrings::HNSW_ENTRYPOINT = "ENTRYPOINT";
const char *VecSimCommonStrings::HNSW_NUM_MARKED_DELETED = "NUMBER_OF_MARKED_DELETED";
const char *VecSimCommonStrings::NUM_MARKED_DELETED = "NUMBER_OF_MARKED_DELETED";

const char *VecSimCommonStrings::SVS_SEARCH_WS_STRING = "SEARCH_WINDOW_SIZE";
const char *VecSimCommonStrings::SVS_CONSTRUCTION_WS_STRING = "CONSTRUCTION_WINDOW_SIZE";
const char *VecSimCommonStrings::SVS_SEARCH_BC_STRING = "SEARCH_BUFFER_CAPACITY";
const char *VecSimCommonStrings::SVS_USE_SEARCH_HISTORY_STRING = "USE_SEARCH_HISTORY";
const char *VecSimCommonStrings::SVS_ALPHA_STRING = "ALPHA";
const char *VecSimCommonStrings::SVS_QUANT_BITS_STRING = "QUANT_BITS";
const char *VecSimCommonStrings::SVS_GRAPH_MAX_DEGREE_STRING = "GRAPH_MAX_DEGREE";
const char *VecSimCommonStrings::SVS_MAX_CANDIDATE_POOL_SIZE_STRING = "MAX_CANDIDATE_POOL_SIZE";
const char *VecSimCommonStrings::SVS_PRUNE_TO_STRING = "PRUNE_TO";
const char *VecSimCommonStrings::SVS_NUM_THREADS_STRING = "NUM_THREADS";
const char *VecSimCommonStrings::SVS_LEANVEC_DIM_STRING = "LEANVEC_DIMENSION";

const char *VecSimCommonStrings::BLOCK_SIZE_STRING = "BLOCK_SIZE";
const char *VecSimCommonStrings::SEARCH_MODE_STRING = "LAST_SEARCH_MODE";
Expand All @@ -68,8 +76,15 @@ const char *VecSimCommonStrings::TIERED_BACKGROUND_INDEXING_STRING = "BACKGROUND
const char *VecSimCommonStrings::TIERED_BUFFER_LIMIT_STRING = "TIERED_BUFFER_LIMIT";
const char *VecSimCommonStrings::FRONTEND_INDEX_STRING = "FRONTEND_INDEX";
const char *VecSimCommonStrings::BACKEND_INDEX_STRING = "BACKEND_INDEX";
// Tiered HNSW specific
const char *VecSimCommonStrings::TIERED_HNSW_SWAP_JOBS_THRESHOLD_STRING =
"TIERED_HNSW_SWAP_JOBS_THRESHOLD";
// Tiered SVS specific
const char *VecSimCommonStrings::TIERED_SVS_TRAINING_THRESHOLD_STRING =
"TIERED_SVS_TRAINING_THRESHOLD";
const char *VecSimCommonStrings::TIERED_SVS_UPDATE_THRESHOLD_STRING = "TIERED_SVS_UPDATE_THRESHOLD";
const char *VecSimCommonStrings::TIERED_SVS_THREADS_RESERVE_TIMEOUT_STRING =
"TIERED_SVS_THREADS_RESERVE_TIMEOUT";

// Log levels
const char *VecSimCommonStrings::LOG_DEBUG_STRING = "debug";
Expand Down Expand Up @@ -216,6 +231,28 @@ const char *VecSimSearchMode_ToString(VecSearchMode vecsimSearchMode) {
return NULL;
}

const char *VecSimQuantBits_ToString(VecSimSvsQuantBits quantBits) {
switch (quantBits) {
case VecSimSvsQuant_NONE:
return "NONE";
case VecSimSvsQuant_Scalar:
return "Scalar";
case VecSimSvsQuant_4:
return "4";
case VecSimSvsQuant_8:
return "8";
case VecSimSvsQuant_4x4:
return "4x4";
case VecSimSvsQuant_4x8:
return "4x8";
case VecSimSvsQuant_4x8_LeanVec:
return "4x8_LeanVec";
case VecSimSvsQuant_8x8_LeanVec:
return "8x8_LeanVec";
}
return NULL;
}

size_t VecSimType_sizeof(VecSimType type) {
switch (type) {
case VecSimType_FLOAT32:
Expand Down
19 changes: 17 additions & 2 deletions src/VecSim/utils/vec_utils.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,15 +49,23 @@ struct VecSimCommonStrings {
static const char *HNSW_EF_RUNTIME_STRING;
static const char *HNSW_EF_CONSTRUCTION_STRING;
static const char *HNSW_M_STRING;
static const char *HNSW_EPSILON_STRING;
static const char *EPSILON_STRING;
static const char *HNSW_MAX_LEVEL;
static const char *HNSW_ENTRYPOINT;
static const char *HNSW_NUM_MARKED_DELETED;
static const char *NUM_MARKED_DELETED;
// static const char *HNSW_VISITED_NODES_POOL_SIZE_STRING;

static const char *SVS_SEARCH_WS_STRING;
static const char *SVS_CONSTRUCTION_WS_STRING;
static const char *SVS_SEARCH_BC_STRING;
static const char *SVS_USE_SEARCH_HISTORY_STRING;
static const char *SVS_ALPHA_STRING;
static const char *SVS_QUANT_BITS_STRING;
static const char *SVS_GRAPH_MAX_DEGREE_STRING;
static const char *SVS_MAX_CANDIDATE_POOL_SIZE_STRING;
static const char *SVS_PRUNE_TO_STRING;
static const char *SVS_NUM_THREADS_STRING;
static const char *SVS_LEANVEC_DIM_STRING;

static const char *BLOCK_SIZE_STRING;
static const char *SEARCH_MODE_STRING;
Expand All @@ -69,7 +77,12 @@ struct VecSimCommonStrings {
static const char *TIERED_BUFFER_LIMIT_STRING;
static const char *FRONTEND_INDEX_STRING;
static const char *BACKEND_INDEX_STRING;
// tiered HNSW specific
static const char *TIERED_HNSW_SWAP_JOBS_THRESHOLD_STRING;
// tiered SVS specific
static const char *TIERED_SVS_TRAINING_THRESHOLD_STRING;
static const char *TIERED_SVS_UPDATE_THRESHOLD_STRING;
static const char *TIERED_SVS_THREADS_RESERVE_TIMEOUT_STRING;

// Log levels
static const char *LOG_DEBUG_STRING;
Expand Down Expand Up @@ -100,6 +113,8 @@ const char *VecSimMetric_ToString(VecSimMetric vecsimMetric);

const char *VecSimSearchMode_ToString(VecSearchMode vecsimSearchMode);

const char *VecSimQuantBits_ToString(VecSimSvsQuantBits quantBits);

size_t VecSimType_sizeof(VecSimType vecsimType);

/** Returns the size in bytes of a stored or query vector */
Expand Down
2 changes: 1 addition & 1 deletion src/VecSim/vec_sim.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ extern "C" VecSimResolveCode VecSimIndex_ResolveParams(VecSimIndex *index, VecSi
VecSimParamResolver_OK) {
return res;
}
} else if (!strcasecmp(rparams[i].name, VecSimCommonStrings::HNSW_EPSILON_STRING)) {
} else if (!strcasecmp(rparams[i].name, VecSimCommonStrings::EPSILON_STRING)) {
if ((res = _ResolveParams_Epsilon(index_type, rparams[i], qparams, query_type)) !=
VecSimParamResolver_OK) {
return res;
Expand Down
8 changes: 7 additions & 1 deletion src/VecSim/vec_sim_common.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,12 @@ typedef enum {
VecSimOption_DISABLE = 2,
} VecSimOptionMode;

typedef enum {
VecSimBool_TRUE = 1,
VecSimBool_FALSE = 0,
VecSimBool_UNSET = -1,
} VecSimBool;

// Distance metric
typedef enum { VecSimMetric_L2, VecSimMetric_IP, VecSimMetric_Cosine } VecSimMetric;

Expand Down Expand Up @@ -379,7 +385,7 @@ typedef struct {
bfInfoStruct bfInfo; // The brute force index info.

uint64_t management_layer_memory; // Memory consumption of the management layer.
bool backgroundIndexing; // Determines if the index is currently being indexed in the
VecSimBool backgroundIndexing; // Determines if the index is currently being indexed in the
// background.
size_t bufferLimit; // Maximum number of vectors allowed in the flat buffer.
} tieredInfoStruct;
Expand Down
9 changes: 3 additions & 6 deletions src/VecSim/vec_sim_tiered_index.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,6 +359,9 @@ VecSimIndexDebugInfo VecSimTieredIndex<DataType, DistType>::debugInfo() const {
};
info.commonInfo.basicInfo = basic_info;

// NOTE: backgroundIndexing needs to be set by the backend index.
info.tieredInfo.backgroundIndexing = VecSimBool_UNSET;

switch (backendInfo.commonInfo.basicInfo.algo) {
case VecSimAlgo_HNSWLIB:
info.tieredInfo.backendInfo.hnswInfo = backendInfo.hnswInfo;
Expand All @@ -376,7 +379,6 @@ VecSimIndexDebugInfo VecSimTieredIndex<DataType, DistType>::debugInfo() const {
info.tieredInfo.frontendCommonInfo = frontendInfo.commonInfo;
info.tieredInfo.bfInfo = frontendInfo.bfInfo;

info.tieredInfo.backgroundIndexing = frontendInfo.commonInfo.indexSize > 0;
info.tieredInfo.management_layer_memory = this->allocator->getAllocationSize();
info.tieredInfo.bufferLimit = this->flatBufferLimit;
return info;
Expand All @@ -402,11 +404,6 @@ VecSimDebugInfoIterator *VecSimTieredIndex<DataType, DistType>::debugInfoIterato
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.tieredInfo.management_layer_memory}}});

infoIterator->addInfoField(VecSim_InfoField{
.fieldName = VecSimCommonStrings::TIERED_BACKGROUND_INDEXING_STRING,
.fieldType = INFOFIELD_UINT64,
.fieldValue = {FieldValue{.uintegerValue = info.tieredInfo.backgroundIndexing}}});

infoIterator->addInfoField(
VecSim_InfoField{.fieldName = VecSimCommonStrings::TIERED_BUFFER_LIMIT_STRING,
.fieldType = INFOFIELD_UINT64,
Expand Down
Loading
Loading