HNSW#

This is a wrapper for hnswlib, to load a CAGRA index as an immutable HNSW index. The loaded HNSW index is only compatible in cuVS, and can be searched using wrapper functions.

Index search parameters#

class cuvs.neighbors.hnsw.SearchParams(ef=200, *, num_threads=0)#

HNSW search parameters

Parameters:

ef: int, default = 200: Maximum number of candidate list size used during search.
num_threads: int, default = 0: Number of CPU threads used to increase search parallelism. When set to 0, the number of threads is automatically determined using OpenMP’s omp_get_max_threads().

Attributes:

ef
num_threads

Index#

class cuvs.neighbors.hnsw.Index#

HNSW index object. This object stores the trained HNSW index state which can be used to perform nearest neighbors searches.

Attributes:

trained

Index Conversion#

cuvs.neighbors.hnsw.from_cagra(IndexParams index_params, Index cagra_index, temporary_index_path=None, resources=None)[source]#

Returns an HNSW index from a CAGRA index.

NOTE: When index_params.hierarchy is:

NONE: This method uses the filesystem to write the CAGRA index

in /tmp/<random_number>.bin before reading it as an hnswlib index, then deleting the temporary file. The returned index is immutable and can only be searched by the hnswlib wrapper in cuVS, as the format is not

compatible with the original hnswlib.
CPU: The returned index is mutable and can be extended with
additional vectors. The serialized index is also compatible with the original hnswlib library.

Saving / loading the index is experimental. The serialization format is subject to change.

Parameters:

index_paramsIndexParams: Parameters to convert the CAGRA index to HNSW index.
cagra_indexcagra.Index: Trained CAGRA index.
temporary_index_pathstring, default = None: Path to save the temporary index file. If None, the temporary file will be saved in /tmp/<random_number>.bin.
resourcesOptional cuVS Resource handle for reusing CUDA resources.: If Resources aren’t supplied, CUDA resources will be allocated inside this function and synchronized before the function exits. If resources are supplied, you will need to explicitly synchronize yourself by calling resources.sync() before accessing the output.

Examples

>>> import cupy as cp
>>> from cuvs.neighbors import cagra
>>> from cuvs.neighbors import hnsw
>>> n_samples = 50000
>>> n_features = 50
>>> dataset = cp.random.random_sample((n_samples, n_features),
...                                   dtype=cp.float32)
>>> # Build index
>>> index = cagra.build(cagra.IndexParams(), dataset)
>>> # Serialize the CAGRA index to hnswlib base layer only index format
>>> hnsw_index = hnsw.from_cagra(hnsw.IndexParams(), index)

Index search#

cuvs.neighbors.hnsw.search(SearchParams search_params, Index index, queries, k, neighbors=None, distances=None, resources=None)[source]#

Find the k nearest neighbors for each query.

Parameters:

search_paramsSearchParams
indexIndex: Trained HNSW index.
queriesCPU array interface compliant matrix shape (n_samples, dim): Supported dtype [float, int]
kint: The number of neighbors.
neighborsOptional CPU array interface compliant matrix shape: (n_queries, k), dtype uint64_t. If supplied, neighbor indices will be written here in-place. (default None)
distancesOptional CPU array interface compliant matrix shape: (n_queries, k) If supplied, the distances to the neighbors will be written here in-place. (default None)
resourcesOptional cuVS Resource handle for reusing CUDA resources.: If Resources aren’t supplied, CUDA resources will be allocated inside this function and synchronized before the function exits. If resources are supplied, you will need to explicitly synchronize yourself by calling resources.sync() before accessing the output.

Examples

>>> import cupy as cp
>>> from cuvs.neighbors import cagra, hnsw
>>> n_samples = 50000
>>> n_features = 50
>>> n_queries = 1000
>>> dataset = cp.random.random_sample((n_samples, n_features),
...                                   dtype=cp.float32)
>>> # Build index
>>> index = cagra.build(cagra.IndexParams(), dataset)
>>> # Search using the built index
>>> queries = cp.random.random_sample((n_queries, n_features),
...                                   dtype=cp.float32)
>>> k = 10
>>> search_params = hnsw.SearchParams(
...     ef=200,
...     num_threads=0
... )
>>> # Convert CAGRA index to HNSW
>>> hnsw_index = hnsw.from_cagra(hnsw.IndexParams(), index)
>>> # Using a pooling allocator reduces overhead of temporary array
>>> # creation during search. This is useful if multiple searches
>>> # are performed with same query size.
>>> distances, neighbors = hnsw.search(search_params, index, queries,
...                                     k)
>>> neighbors = cp.asarray(neighbors)
>>> distances = cp.asarray(distances)

Index save#

cuvs.neighbors.hnsw.save(filename, Index index, resources=None)[source]#

Saves the CAGRA index to a file as an hnswlib index. If the index was constructed with hnsw.IndexParams(hierarchy="none"), then the saved index is immutable and can only be searched by the hnswlib wrapper in cuVS, as the format is not compatible with the original hnswlib. However, if the index was constructed with hnsw.IndexParams(hierarchy="cpu"), then the saved index is mutable and compatible with the original hnswlib.

Saving / loading the index is experimental. The serialization format is subject to change.

Parameters:

filenamestring: Name of the file.
indexIndex: Trained HNSW index.
resourcesOptional cuVS Resource handle for reusing CUDA resources.: If Resources aren’t supplied, CUDA resources will be allocated inside this function and synchronized before the function exits. If resources are supplied, you will need to explicitly synchronize yourself by calling resources.sync() before accessing the output.

Examples

>>> import cupy as cp
>>> from cuvs.neighbors import cagra
>>> n_samples = 50000
>>> n_features = 50
>>> dataset = cp.random.random_sample((n_samples, n_features),
...                                   dtype=cp.float32)
>>> # Build index
>>> cagra_index = cagra.build(cagra.IndexParams(), dataset)
>>> # Serialize and deserialize the cagra index built
>>> hnsw_index = hnsw.from_cagra(hnsw.IndexParams(), cagra_index)
>>> hnsw.save("my_index.bin", hnsw_index)

Index load#

cuvs.neighbors.hnsw.load(IndexParams index_params, filename, dim, dtype, metric=u'sqeuclidean', resources=None)[source]#

Loads an HNSW index. If the index was constructed with hnsw.IndexParams(hierarchy="none"), then the loaded index is immutable and can only be searched by the hnswlib wrapper in cuVS, as the format is not compatible with the original hnswlib. However, if the index was constructed with hnsw.IndexParams(hierarchy="cpu"), then the loaded index is mutable and compatible with the original hnswlib.

Saving / loading the index is experimental. The serialization format is subject to change, therefore loading an index saved with a previous version of cuVS is not guaranteed to work.

Parameters:

index_paramsIndexParams

Parameters that were used to convert CAGRA index to HNSW index.

filenamestring

Name of the file.

dimint

Dimensions of the training dataest

dtypenp.dtype of the saved index

Valid values for dtype: [np.float32, np.byte, np.ubyte]

metricstring denoting the metric type, default=”sqeuclidean”

Valid values for metric: [“sqeuclidean”, “inner_product”], where

sqeuclidean is the euclidean distance without the square root operation, i.e.: distance(a,b) = sum_i (a_i - b_i)^2,
inner_product distance is defined as distance(a, b) = sum_i a_i * b_i.

resourcesOptional cuVS Resource handle for reusing CUDA resources.

If Resources aren’t supplied, CUDA resources will be allocated inside this function and synchronized before the function exits. If resources are supplied, you will need to explicitly synchronize yourself by calling resources.sync() before accessing the output.

Returns:

indexHnswIndex

Examples

>>> import cupy as cp
>>> from cuvs.neighbors import cagra
>>> from cuvs.neighbors import hnsw
>>> n_samples = 50000
>>> n_features = 50
>>> dataset = cp.random.random_sample((n_samples, n_features),
...                                   dtype=cp.float32)
>>> # Build index
>>> index = cagra.build(cagra.IndexParams(), dataset)
>>> # Serialize the CAGRA index to hnswlib base layer only index format
>>> hnsw.save("my_index.bin", index)
>>> index = hnsw.load("my_index.bin", n_features, np.float32,
...                   "sqeuclidean")