HNSW

Source header: cuvs/neighbors/hnsw.hpp

hnswlib index wrapper params

neighbors::hnsw::HnswHierarchy

Hierarchy for HNSW index when converting from CAGRA index

NOTE: When the value is NONE, the HNSW index is built as a base-layer-only index.

1
enum class HnswHierarchy {
2
  NONE
3
};

Values

neighbors::hnsw::[[deprecated

Create a CAGRA index parameters compatible with HNSW index

1
[[deprecated("Use cagra::index_params::from_hnsw_params instead")]]
2
cuvs::neighbors::cagra::index_params to_cagra_params(
3
raft::matrix_extent<int64_t> dataset,
4
int M,
5
int ef_construction,
6
cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded);

• IMPORTANT NOTE *

The reference HNSW index and the corresponding from-CAGRA generated HNSW index will NOT produce the same recalls and QPS for the same parameter ef. The graphs are different internally. For the same ef, the from-CAGRA index likely has a slightly higher recall and slightly lower QPS. However, the Recall-QPS curves should be similar (i.e. the points are just shifted along the curve).

Usage example:

Parameters

Returns

void

hnswlib index wrapper

neighbors::hnsw::index

hnswlib index wrapper

1
template <typename T>
2
struct index;

neighbors::hnsw::index::index

load a base-layer-only hnswlib index originally saved from a built CAGRA index. This is a virtual class and it cannot be used directly. To create an index, use the factory function cuvs::neighbors::hnsw::from_cagra from the header cuvs/neighbors/hnsw.hpp

1
index(int dim, cuvs::distance::DistanceType metric, HnswHierarchy hierarchy = HnswHierarchy::NONE);

Parameters

Returns

void

neighbors::hnsw::index::get_index

Get underlying index

1
virtual void const* get_index() const = 0;

Returns

virtual void const*

neighbors::hnsw::index::set_ef

Set ef for search

1
virtual void set_ef(int ef) const = 0;

Parameters

Returns

virtual void

neighbors::hnsw::index::file_path

Get file path for disk-backed index

1
virtual std::string file_path() const;

Returns

virtual std::string

HNSW index extend parameters

neighbors::hnsw::extend_params

HNSW index extend parameters

1
struct extend_params {
2
  int num_threads;
3
};

Fields

Build HNSW index on the GPU

neighbors::hnsw::build

Build an HNSW index on the GPU

1
std::unique_ptr<index<float>> build(
2
raft::resources const& res,
3
const index_params& params,
4
raft::host_matrix_view<const float, int64_t, raft::row_major> dataset);

The resulting graph is compatible for HNSW search, but is not an exact equivalent of the graph built by the HNSW.

The HNSW index construction parameters M and ef_construction are the main parameters to control the graph degree and graph quality. We have additional options that can be used to fine tune graph building on the GPU (see cuvs::neighbors::cagra::index_params). In case the index does not fit the host or GPU memory, we would use disk as temporary storage. In such cases it is important to set ace_params.build_dir to a fast disk with sufficient storage size.

NOTE: This function requires CUDA headers to be available at compile time.

Usage example:

Parameters

Returns

std::unique_ptr<index<float>>

Additional overload: neighbors::hnsw::build

Build an HNSW index on the GPU

1
std::unique_ptr<index<half>> build(
2
raft::resources const& res,
3
const index_params& params,
4
raft::host_matrix_view<const half, int64_t, raft::row_major> dataset);

The resulting graph is compatible for HNSW search, but is not an exact equivalent of the graph built by the HNSW.

The HNSW index construction parameters M and ef_construction are the main parameters to control the graph degree and graph quality. We have additional options that can be used to fine tune graph building on the GPU (see cuvs::neighbors::cagra::index_params). In case the index does not fit the host or GPU memory, we would use disk as temporary storage. In such cases it is important to set ace_params.build_dir to a fast disk with sufficient storage size.

NOTE: This function requires CUDA headers to be available at compile time.

Usage example:

Parameters

Returns

std::unique_ptr<index<half>>

Additional overload: neighbors::hnsw::build

Build an HNSW index on the GPU

1
std::unique_ptr<index<uint8_t>> build(
2
raft::resources const& res,
3
const index_params& params,
4
raft::host_matrix_view<const uint8_t, int64_t, raft::row_major> dataset);

The resulting graph is compatible for HNSW search, but is not an exact equivalent of the graph built by the HNSW.

The HNSW index construction parameters M and ef_construction are the main parameters to control the graph degree and graph quality. We have additional options that can be used to fine tune graph building on the GPU (see cuvs::neighbors::cagra::index_params). In case the index does not fit the host or GPU memory, we would use disk as temporary storage. In such cases it is important to set ace_params.build_dir to a fast disk with sufficient storage size.

NOTE: This function requires CUDA headers to be available at compile time.

Usage example:

Parameters

Returns

std::unique_ptr<index<uint8_t>>

Additional overload: neighbors::hnsw::build

Build an HNSW index on the GPU

1
std::unique_ptr<index<int8_t>> build(
2
raft::resources const& res,
3
const index_params& params,
4
raft::host_matrix_view<const int8_t, int64_t, raft::row_major> dataset);

The resulting graph is compatible for HNSW search, but is not an exact equivalent of the graph built by the HNSW.

The HNSW index construction parameters M and ef_construction are the main parameters to control the graph degree and graph quality. We have additional options that can be used to fine tune graph building on the GPU (see cuvs::neighbors::cagra::index_params). In case the index does not fit the host or GPU memory, we would use disk as temporary storage. In such cases it is important to set ace_params.build_dir to a fast disk with sufficient storage size.

NOTE: This function requires CUDA headers to be available at compile time.

Usage example:

Parameters

Returns

std::unique_ptr<index<int8_t>>

Load CAGRA index as hnswlib index

neighbors::hnsw::from_cagra

Construct an hnswlib index from a CAGRA index NOTE: When hnsw::index_params.hierarchy is:

1. 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.
2. CPU: The returned index is mutable and can be extended with additional vectors. The serialized index is also compatible with the original hnswlib library.

1
std::unique_ptr<index<float>> from_cagra(
2
raft::resources const& res,
3
const index_params& params,
4
const cuvs::neighbors::cagra::index<float, uint32_t>& cagra_index,
5
std::optional<raft::host_matrix_view<const float, int64_t, raft::row_major>> dataset =
6
std::nullopt);

Usage example:

Parameters

Returns

std::unique_ptr<index<float>>

Additional overload: neighbors::hnsw::from_cagra

Construct an hnswlib index from a CAGRA index NOTE: When hnsw::index_params.hierarchy is:

1. 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.
2. CPU: The returned index is mutable and can be extended with additional vectors. The serialized index is also compatible with the original hnswlib library.

1
std::unique_ptr<index<half>> from_cagra(
2
raft::resources const& res,
3
const index_params& params,
4
const cuvs::neighbors::cagra::index<half, uint32_t>& cagra_index,
5
std::optional<raft::host_matrix_view<const half, int64_t, raft::row_major>> dataset =
6
std::nullopt);

Usage example:

Parameters

Returns

std::unique_ptr<index<half>>

Additional overload: neighbors::hnsw::from_cagra

Construct an hnswlib index from a CAGRA index NOTE: When hnsw::index_params.hierarchy is:

1. 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.
2. CPU: The returned index is mutable and can be extended with additional vectors. The serialized index is also compatible with the original hnswlib library.

1
std::unique_ptr<index<uint8_t>> from_cagra(
2
raft::resources const& res,
3
const index_params& params,
4
const cuvs::neighbors::cagra::index<uint8_t, uint32_t>& cagra_index,
5
std::optional<raft::host_matrix_view<const uint8_t, int64_t, raft::row_major>> dataset =
6
std::nullopt);

Usage example:

Parameters

Returns

std::unique_ptr<index<uint8_t>>

Additional overload: neighbors::hnsw::from_cagra

Construct an hnswlib index from a CAGRA index NOTE: When hnsw::index_params.hierarchy is:

1. 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.
2. CPU: The returned index is mutable and can be extended with additional vectors. The serialized index is also compatible with the original hnswlib library.

1
std::unique_ptr<index<int8_t>> from_cagra(
2
raft::resources const& res,
3
const index_params& params,
4
const cuvs::neighbors::cagra::index<int8_t, uint32_t>& cagra_index,
5
std::optional<raft::host_matrix_view<const int8_t, int64_t, raft::row_major>> dataset =
6
std::nullopt);

Usage example:

Parameters

Returns

std::unique_ptr<index<int8_t>>

Extend HNSW index with additional vectors

neighbors::hnsw::extend

Add new vectors to an HNSW index NOTE: The HNSW index can only be extended when the hnsw::index_params.hierarchy is CPU when converting from a CAGRA index.

1
void extend(raft::resources const& res,
2
const extend_params& params,
3
raft::host_matrix_view<const float, int64_t, raft::row_major> additional_dataset,
4
index<float>& idx);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::extend

Add new vectors to an HNSW index NOTE: The HNSW index can only be extended when the hnsw::index_params.hierarchy is CPU when converting from a CAGRA index.

1
void extend(raft::resources const& res,
2
const extend_params& params,
3
raft::host_matrix_view<const half, int64_t, raft::row_major> additional_dataset,
4
index<half>& idx);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::extend

Add new vectors to an HNSW index NOTE: The HNSW index can only be extended when the hnsw::index_params.hierarchy is CPU when converting from a CAGRA index.

1
void extend(raft::resources const& res,
2
const extend_params& params,
3
raft::host_matrix_view<const uint8_t, int64_t, raft::row_major> additional_dataset,
4
index<uint8_t>& idx);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::extend

Add new vectors to an HNSW index NOTE: The HNSW index can only be extended when the hnsw::index_params.hierarchy is CPU when converting from a CAGRA index.

1
void extend(raft::resources const& res,
2
const extend_params& params,
3
raft::host_matrix_view<const int8_t, int64_t, raft::row_major> additional_dataset,
4
index<int8_t>& idx);

Usage example:

Parameters

Returns

void

Build CAGRA index and search with hnswlib

neighbors::hnsw::search_params

Build CAGRA index and search with hnswlib

1
struct search_params : cuvs::neighbors::search_params {
2
  int ef;
3
  int num_threads;
4
};

Fields

Search hnswlib index

neighbors::hnsw::search

Search HNSW index constructed from a CAGRA index NOTE: The HNSW index can only be searched by the hnswlib wrapper in cuVS when the hierarchy is NONE, as the format is not compatible with the original hnswlib.

1
void search(raft::resources const& res,
2
const search_params& params,
3
const index<float>& idx,
4
raft::host_matrix_view<const float, int64_t, raft::row_major> queries,
5
raft::host_matrix_view<uint64_t, int64_t, raft::row_major> neighbors,
6
raft::host_matrix_view<float, int64_t, raft::row_major> distances);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::search

Search HNSW index constructed from a CAGRA index NOTE: The HNSW index can only be searched by the hnswlib wrapper in cuVS when the hierarchy is NONE, as the format is not compatible with the original hnswlib.

1
void search(raft::resources const& res,
2
const search_params& params,
3
const index<half>& idx,
4
raft::host_matrix_view<const half, int64_t, raft::row_major> queries,
5
raft::host_matrix_view<uint64_t, int64_t, raft::row_major> neighbors,
6
raft::host_matrix_view<float, int64_t, raft::row_major> distances);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::search

Search HNSWindex constructed from a CAGRA index NOTE: The HNSW index can only be searched by the hnswlib wrapper in cuVS when the hierarchy is NONE, as the format is not compatible with the original hnswlib.

1
void search(raft::resources const& res,
2
const search_params& params,
3
const index<uint8_t>& idx,
4
raft::host_matrix_view<const uint8_t, int64_t, raft::row_major> queries,
5
raft::host_matrix_view<uint64_t, int64_t, raft::row_major> neighbors,
6
raft::host_matrix_view<float, int64_t, raft::row_major> distances);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::search

Search HNSW index constructed from a CAGRA index NOTE: The HNSW index can only be searched by the hnswlib wrapper in cuVS when the hierarchy is NONE, as the format is not compatible with the original hnswlib.

1
void search(raft::resources const& res,
2
const search_params& params,
3
const index<int8_t>& idx,
4
raft::host_matrix_view<const int8_t, int64_t, raft::row_major> queries,
5
raft::host_matrix_view<uint64_t, int64_t, raft::row_major> neighbors,
6
raft::host_matrix_view<float, int64_t, raft::row_major> distances);

Usage example:

Parameters

Returns

void

Deserialize CAGRA index as hnswlib index

neighbors::hnsw::serialize

Serialize the HNSW index to file NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void serialize(raft::resources const& res, const std::string& filename, const index<float>& idx);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::serialize

Serialize the HNSW index to file NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void serialize(raft::resources const& res, const std::string& filename, const index<half>& idx);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::serialize

Serialize the HNSW index to file NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void serialize(raft::resources const& res, const std::string& filename, const index<uint8_t>& idx);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::serialize

Serialize the HNSW index to file NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void serialize(raft::resources const& res, const std::string& filename, const index<int8_t>& idx);

Usage example:

Parameters

Returns

void

neighbors::hnsw::deserialize

De-serialize a CAGRA index saved to a file as an hnswlib index NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void deserialize(raft::resources const& res,
2
const index_params& params,
3
const std::string& filename,
4
int dim,
5
cuvs::distance::DistanceType metric,
6
index<float>** index);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::deserialize

De-serialize a CAGRA index saved to a file as an hnswlib index NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void deserialize(raft::resources const& res,
2
const index_params& params,
3
const std::string& filename,
4
int dim,
5
cuvs::distance::DistanceType metric,
6
index<half>** index);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::deserialize

De-serialize a CAGRA index saved to a file as an hnswlib index NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void deserialize(raft::resources const& res,
2
const index_params& params,
3
const std::string& filename,
4
int dim,
5
cuvs::distance::DistanceType metric,
6
index<uint8_t>** index);

Usage example:

Parameters

Returns

void

Additional overload: neighbors::hnsw::deserialize

De-serialize a CAGRA index saved to a file as an hnswlib index NOTE: When hierarchy is NONE, the saved hnswlib index is immutable and can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. However, when hierarchy is CPU, the saved hnswlib index is compatible with the original hnswlib library.

1
void deserialize(raft::resources const& res,
2
const index_params& params,
3
const std::string& filename,
4
int dim,
5
cuvs::distance::DistanceType metric,
6
index<int8_t>** index);

Usage example:

Parameters

Returns

void