Neighbors IVF Flat

Source header: cuvs/neighbors/ivf_flat.h

IVF-Flat index build parameters

cuvsIvfFlatIndexParams

Supplemental parameters to build IVF-Flat Index

1 struct cuvsIvfFlatIndexParams { ... };

Fields

Name	Type	Description
`metric`	`cuvsDistanceType`	Distance type.
`metric_arg`	`float`	The argument used by some distance metrics.
`add_data_on_build`	`bool`	Whether to add the dataset content to the index, i.e.: - `true` means the index is filled with the dataset vectors and ready to search after calling `build`. - `false` means `build` only trains the underlying model (e.g. quantizer or clustering), but the index is left empty; you’d need to call `extend` on the index afterwards to populate it.
`n_lists`	`uint32_t`	The number of inverted lists (clusters)
`kmeans_n_iters`	`uint32_t`	The number of iterations searching for kmeans centers (index building).
`kmeans_trainset_fraction`	`double`	The fraction of data to use during iterative kmeans building.
`adaptive_centers`	`bool`	By default (adaptive_centers = false), the cluster centers are trained in `ivf_flat::build`, and never modified in `ivf_flat::extend`. As a result, you may need to retrain the index from scratch after invoking (`ivf_flat::extend`) a few times with new data, the distribution of which is no longer representative of the original training set. The alternative behavior (adaptive_centers = true) is to update the cluster centers for new data when it is added. In this case, `index.centers()` are always exactly the centroids of the data in the corresponding clusters. The drawback of this behavior is that the centroids depend on the order of adding new data (through the classification of the added data); that is, `index.centers()` “drift” together with the changing distribution of the newly added data.
`conservative_memory_allocation`	`bool`	By default, the algorithm allocates more space than necessary for individual clusters (`list_data`). This allows to amortize the cost of memory allocation and reduce the number of data copies during repeated calls to `extend` (extending the database). The alternative is the conservative allocation behavior; when enabled, the algorithm always allocates the minimum amount of memory required to store the given number of records. Set this flag to `true` if you prefer to use as little GPU memory for the database as possible.

cuvsIvfFlatIndexParamsCreate

Allocate IVF-Flat Index params, and populate with default values

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexParamsCreate(cuvsIvfFlatIndexParams_t* index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsIvfFlatIndexParams_t*`	cuvsIvfFlatIndexParams_t to allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatIndexParamsDestroy

De-allocate IVF-Flat Index params

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexParamsDestroy(cuvsIvfFlatIndexParams_t index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsIvfFlatIndexParams_t`

Returns

CUVS_EXPORT cuvsError_t

IVF-Flat index search parameters

cuvsIvfFlatSearchParams

Supplemental parameters to search IVF-Flat index

1 struct cuvsIvfFlatSearchParams { ... };

Fields

Name	Type	Description
`n_probes`	`uint32_t`	The number of clusters to search.

cuvsIvfFlatSearchParamsCreate

Allocate IVF-Flat search params, and populate with default values

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatSearchParamsCreate(cuvsIvfFlatSearchParams_t* params);

Parameters

Name	Direction	Type	Description
`params`	in	`cuvsIvfFlatSearchParams_t*`	cuvsIvfFlatSearchParams_t to allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatSearchParamsDestroy

De-allocate IVF-Flat search params

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatSearchParamsDestroy(cuvsIvfFlatSearchParams_t params);

Parameters

Name	Direction	Type	Description
`params`	in	`cuvsIvfFlatSearchParams_t`

Returns

CUVS_EXPORT cuvsError_t

IVF-Flat index

cuvsIvfFlatIndex

Struct to hold address of cuvs::neighbors::ivf_flat::index and its active trained dtype

1 typedef struct { ... } cuvsIvfFlatIndex;

Fields

Name	Type	Description
`addr`	`uintptr_t`
`dtype`	`DLDataType`

cuvsIvfFlatIndexCreate

Allocate IVF-Flat index

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexCreate(cuvsIvfFlatIndex_t* index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsIvfFlatIndex_t*`	cuvsIvfFlatIndex_t to allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatIndexDestroy

De-allocate IVF-Flat index

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexDestroy(cuvsIvfFlatIndex_t index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsIvfFlatIndex_t`	cuvsIvfFlatIndex_t to de-allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatIndexGetNLists

Get the number of clusters/inverted lists in the index

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexGetNLists(cuvsIvfFlatIndex_t index, int64_t* n_lists);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsIvfFlatIndex_t`	cuvsIvfFlatIndex_t Built IVF-Flat index
`n_lists`	out	`int64_t*`	Pointer to store the number of lists

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatIndexGetDim

Get the dimensionality of the indexed data

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexGetDim(cuvsIvfFlatIndex_t index, int64_t* dim);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsIvfFlatIndex_t`	cuvsIvfFlatIndex_t Built IVF-Flat index
`dim`	out	`int64_t*`	Pointer to store the dimensionality

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatIndexGetCenters

Get the cluster centers corresponding to the lists [n_lists, dim]

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatIndexGetCenters(cuvsIvfFlatIndex_t index, DLManagedTensor* centers);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsIvfFlatIndex_t`	cuvsIvfFlatIndex_t Built Ivf-Flat Index
`centers`	out	`DLManagedTensor*`	Preallocated array on host or device memory to store output, [n_lists, dim]

Returns

CUVS_EXPORT cuvsError_t

IVF-Flat index build

cuvsIvfFlatBuild

Build a IVF-Flat index with a DLManagedTensor which has underlying

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatBuild(cuvsResources_t res,
2 cuvsIvfFlatIndexParams_t index_params,
3 DLManagedTensor* dataset,
4 cuvsIvfFlatIndex_t index);

DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged, or kDLCPU. Also, acceptable underlying types are:

kDLDataType.code == kDLFloat and kDLDataType.bits = 32
kDLDataType.code == kDLInt and kDLDataType.bits = 8
kDLDataType.code == kDLUInt and kDLDataType.bits = 8

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`index_params`	in	`cuvsIvfFlatIndexParams_t`	cuvsIvfFlatIndexParams_t used to build IVF-Flat index
`dataset`	in	`DLManagedTensor*`	DLManagedTensor* training dataset
`index`	out	`cuvsIvfFlatIndex_t`	cuvsIvfFlatIndex_t Newly built IVF-Flat index

Returns

CUVS_EXPORT cuvsError_t

IVF-Flat index search

cuvsIvfFlatSearch

Search a IVF-Flat index with a DLManagedTensor which has underlying

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatSearch(cuvsResources_t res,
2 cuvsIvfFlatSearchParams_t search_params,
3 cuvsIvfFlatIndex_t index,
4 DLManagedTensor* queries,
5 DLManagedTensor* neighbors,
6 DLManagedTensor* distances,
7 cuvsFilter filter);

DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged. It is also important to note that the IVF-Flat Index must have been built with the same type of queries, such that index.dtype.code == queries.dl_tensor.dtype.code Types for input are:

queries: kDLDataType.code == kDLFloat and kDLDataType.bits = 32
neighbors: kDLDataType.code == kDLUInt and kDLDataType.bits = 32
distances: kDLDataType.code == kDLFloat and kDLDataType.bits = 32

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`search_params`	in	`cuvsIvfFlatSearchParams_t`	cuvsIvfFlatSearchParams_t used to search IVF-Flat index
`index`	in	`cuvsIvfFlatIndex_t`	ivfFlatIndex which has been returned by `ivfFlatBuild`
`queries`	in	`DLManagedTensor*`	DLManagedTensor* queries dataset to search
`neighbors`	out	`DLManagedTensor*`	DLManagedTensor* output `k` neighbors for queries
`distances`	out	`DLManagedTensor*`	DLManagedTensor* output `k` distances for queries
`filter`	in	`cuvsFilter`	cuvsFilter input filter that can be used to filter queries and neighbors based on the given bitset.

Returns

CUVS_EXPORT cuvsError_t

IVF-Flat C-API serialize functions

cuvsIvfFlatSerialize

Save the index to file.

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatSerialize(cuvsResources_t res,
2 const char* filename,
3 cuvsIvfFlatIndex_t index);

Experimental, both the API and the serialization format are subject to change.

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`filename`	in	`const char*`	the file name for saving the index
`index`	in	`cuvsIvfFlatIndex_t`	IVF-Flat index

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfFlatDeserialize

Load index from file.

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatDeserialize(cuvsResources_t res,
2 const char* filename,
3 cuvsIvfFlatIndex_t index);

Experimental, both the API and the serialization format are subject to change.

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`filename`	in	`const char*`	the name of the file that stores the index
`index`	out	`cuvsIvfFlatIndex_t`	IVF-Flat index loaded disk

Returns

CUVS_EXPORT cuvsError_t

IVF-Flat index extend

cuvsIvfFlatExtend

Extend the index with the new data.

1 CUVS_EXPORT cuvsError_t cuvsIvfFlatExtend(cuvsResources_t res,
2 DLManagedTensor* new_vectors,
3 DLManagedTensor* new_indices,
4 cuvsIvfFlatIndex_t index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`new_vectors`	in	`DLManagedTensor*`	DLManagedTensor* the new vectors to add to the index
`new_indices`	in	`DLManagedTensor*`	DLManagedTensor* vector of new indices for the new vectors
`index`	inout	`cuvsIvfFlatIndex_t`	IVF-Flat index to be extended

Returns

CUVS_EXPORT cuvsError_t