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. When the value is CPU, a full index is built with a CPU-constructed hierarchy. When the value is GPU, a full index is built with a GPU-constructed hierarchy.
Values
neighbors::hnsw::HnswOutputFormat
Output artifact format for an HNSW index
HNSWLIB produces the standard hnswlib index format. GRAPH_ONLY stores the graph separately from vectors. The current implementation requires HnswHierarchy::GPU and disk-backed ACE. Load a graph-only artifact with the two-filename deserialize overload, which reads the vectors from a separate local dataset.
Values
neighbors::hnsw::index_params
Fields
neighbors::hnsw::[[deprecated
Create a CAGRA index parameters compatible with HNSW index
- 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
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
Parameters
Returns
void
neighbors::hnsw::index::get_index
Get underlying index
Returns
virtual void const*
neighbors::hnsw::index::set_ef
Set ef for search
Parameters
Returns
virtual void
neighbors::hnsw::index::file_path
Get file path for disk-backed index
Returns
virtual std::string
HNSW index extend parameters
neighbors::hnsw::extend_params
HNSW index extend parameters
Fields
Build HNSW index on the GPU
neighbors::hnsw::build
Build an HNSW index on the GPU
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
Additional overload: neighbors::hnsw::build
Build an HNSW index on the GPU
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
Additional overload: neighbors::hnsw::build
Build an HNSW index on the GPU
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
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:
NONE: This method uses the filesystem to write the CAGRA index in/tmp/<random_number>.binbefore 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.GPU: The hierarchy is constructed on the GPU. Whenoutput_formatisGRAPH_ONLY, the GPU-built hierarchy is stored as graph links only. Reload it with the two-filenamedeserializeoverload so vectors can be reconstructed from the local dataset.
Usage example:
Parameters
Returns
Additional overload: neighbors::hnsw::from_cagra
Construct an hnswlib index from a CAGRA index NOTE: When hnsw::index_params.hierarchy is:
NONE: This method uses the filesystem to write the CAGRA index in/tmp/<random_number>.binbefore 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.GPU: The hierarchy is constructed on the GPU. Whenoutput_formatisGRAPH_ONLY, the GPU-built hierarchy is stored as graph links only. Reload it with the two-filenamedeserializeoverload so vectors can be reconstructed from the local dataset.
Usage example:
Parameters
Returns
Additional overload: neighbors::hnsw::from_cagra
Construct an hnswlib index from a CAGRA index NOTE: When hnsw::index_params.hierarchy is:
NONE: This method uses the filesystem to write the CAGRA index in/tmp/<random_number>.binbefore 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.GPU: The hierarchy is constructed on the GPU. Whenoutput_formatisGRAPH_ONLY, the GPU-built hierarchy is stored as graph links only. Reload it with the two-filenamedeserializeoverload so vectors can be reconstructed from the local dataset.
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:
NONE: This method uses the filesystem to write the CAGRA index in/tmp/<random_number>.binbefore 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.GPU: The hierarchy is constructed on the GPU. Whenoutput_formatisGRAPH_ONLY, the GPU-built hierarchy is stored as graph links only. Reload it with the two-filenamedeserializeoverload so vectors can be reconstructed from the local dataset.
Usage example:
Parameters
Returns
std::unique_ptr<index<int8_t>>
Additional overload: neighbors::hnsw::from_cagra
Construct an hnswlib index from a device-standard CAGRA index.
When the index has an attached device dataset view, dataset may be omitted. Otherwise pass a host matrix with the vectors (same contract as device_padded_index).
Parameters
Returns
Additional overload: neighbors::hnsw::from_cagra
Construct an hnswlib index from a host-built CAGRA index. Requires dataset for in-memory indices — host builds do not store vectors in the index.
Parameters
Returns
Additional overload: neighbors::hnsw::from_cagra
Construct an hnswlib index from a host-built CAGRA index (standard dataset layout). Requires dataset for in-memory indices — host builds do not store vectors in the index.
Parameters
Returns
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.
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.
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.
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.
Usage example:
Parameters
Returns
void
Build CAGRA index and search with hnswlib
neighbors::hnsw::search_params
Build CAGRA index and search with hnswlib
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. When output_format is GRAPH_ONLY, search uses the in-memory index reconstructed from the graph-only artifact produced by the two-filename deserialize overload.
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. When output_format is GRAPH_ONLY, search uses the in-memory index reconstructed from the graph-only artifact produced by the two-filename deserialize overload.
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. When output_format is GRAPH_ONLY, search uses the in-memory index reconstructed from the graph-only artifact produced by the two-filename deserialize overload.
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. When output_format is GRAPH_ONLY, search uses the in-memory index reconstructed from the graph-only artifact produced by the two-filename deserialize overload.
Usage example:
Parameters
Returns
void
Serialize and deserialize HNSW indexes
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. When output_format is GRAPH_ONLY, the saved artifact stores the graph only. Load it with the two-filename deserialize overload and a local dataset.
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. When output_format is GRAPH_ONLY, the saved artifact stores the graph only. Load it with the two-filename deserialize overload and a local dataset.
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. When output_format is GRAPH_ONLY, the saved artifact stores the graph only. Load it with the two-filename deserialize overload and a local dataset.
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. When output_format is GRAPH_ONLY, the saved artifact stores the graph only. Load it with the two-filename deserialize overload and a local dataset.
Usage example:
Parameters
Returns
void
neighbors::hnsw::deserialize
Deserialize 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. This overload loads HNSWLIB artifacts. Use the two-filename overload for graph-only artifacts.
Usage example:
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Deserialize 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. This overload loads HNSWLIB artifacts. Use the two-filename overload for graph-only artifacts.
Usage example:
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Deserialize 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. This overload loads HNSWLIB artifacts. Use the two-filename overload for graph-only artifacts.
Usage example:
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Deserialize 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. This overload loads HNSWLIB artifacts. Use the two-filename overload for graph-only artifacts.
Usage example:
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Deserialize a graph-only HNSW artifact and attach its dataset
The graph artifact supplies the index dimensions, metric, and construction metadata. The attached dataset must have the recorded shape, but its element type may differ from the type used to construct the graph. The output pointer selects the attached dataset type. The loader accepts row-major .npy files and ANN benchmark binary files with a [uint32 rows, uint32 cols] header. Binary extensions must match the output index type: .fbin for float, .f16bin or .fp16.fbin for half, .u8bin for uint8_t, and .i8bin for int8_t.
Usage example:
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Parameters
Returns
void
Additional overload: neighbors::hnsw::deserialize
Parameters
Returns
void