ScaNN#
2026-09-01
5 min read time
ScaNN (Scalable Nearest Neighbors) is an ANN algorithm that combines partitioning with anisotropic vector quantization to provide fast, accurate nearest neighbor search.
#include <cuvs/neighbors/scann.hpp>
namespace cuvs::neighbors::scann
Index build parameters#
-
struct index_params : public cuvs::neighbors::index_params#
- #include <scann.hpp>
ANN parameters used by ScaNN to build index.
Public Members
-
uint32_t n_leaves = 1000#
the number of leaves in the tree
-
int64_t kmeans_n_rows_train = 100000#
the number of rows for training the tree structures
-
uint32_t kmeans_n_iters = 24#
the max number of iterations for training the tree structure
-
float partitioning_eta = 1#
the value of eta for AVQ adjustment during partitioning
-
float soar_lambda = 1#
the value of lambda for SOAR spilling
-
uint32_t pq_dim = 8#
the dimension of pq subspaces (must divide dataset dimension)
-
uint32_t pq_bits = 8#
the number of bits for pq codes (must be 4 or 8, for 16 and 256 codes respectively)
-
int64_t pq_n_rows_train = 100000#
the number of rows for PQ training (internally capped to 100k)
-
uint32_t pq_train_iters = 10#
the max number of iterations for PQ training
-
bool reordering_bf16 = false#
whether to apply bf16 quantization of dataset vectors
-
float reordering_noise_shaping_threshold = NAN#
Threshold T for computing AVQ eta = (dim - 1) ( T^2 / || x ||^2) / ( 1 - T^2 / || x ||^2)
When quantizing a vector x to x_q, AVQ minimizes the loss function L(x, x_q) = eta * || r_para ||^2 + || r_perp ||^2, where r = x - x_q, r_para = <r, x> * x / || x ||^2, r_perp = r - r_para
Compared to L2 loss, This produces an x_q which better approximates the dot product of a query vector with x
If the threshold is NAN, AVQ is not performed during bfloat16 quant
-
uint32_t n_leaves = 1000#
Index#
-
template<typename T, typename IdxT>
struct index : public cuvs::neighbors::index# - #include <scann.hpp>
ScaNN index.
The index stores the dataset and the ScaNN graph in device memory.
- Template Parameters:
T – data element type
IdxT – type of the vector indices (represent dataset.extent(0))
Public Functions
- inline constexpr auto metric(
Distance metric used for clustering.
- inline constexpr auto dim(
Dimensionality of the data.
- inline index(
- raft::resources const &res,
- cuvs::distance::DistanceType metric,
- uint32_t n_leaves,
- uint32_t pq_bits,
- uint32_t pq_dim,
- IdxT n_rows,
- IdxT dim,
- uint32_t pq_clusters,
- uint32_t pq_num_subspaces,
- bool reordering_bf16
Construct an empty index. It will need to be trained and populated with
build
Index build#
-
uint32_t n_leaves = 1000#
the number of leaves in the tree
-
int64_t kmeans_n_rows_train = 100000#
the number of rows for training the tree structures
-
uint32_t kmeans_n_iters = 24#
the max number of iterations for training the tree structure
-
float partitioning_eta = 1#
the value of eta for AVQ adjustment during partitioning
-
float soar_lambda = 1#
the value of lambda for SOAR spilling
-
uint32_t pq_dim = 8#
the dimension of pq subspaces (must divide dataset dimension)
-
uint32_t pq_bits = 8#
the number of bits for pq codes (must be 4 or 8, for 16 and 256 codes respectively)
-
int64_t pq_n_rows_train = 100000#
the number of rows for PQ training (internally capped to 100k)
-
uint32_t pq_train_iters = 10#
the max number of iterations for PQ training
-
bool reordering_bf16 = false#
whether to apply bf16 quantization of dataset vectors
-
float reordering_noise_shaping_threshold = NAN#
Threshold T for computing AVQ eta = (dim - 1) ( T^2 / || x ||^2) / ( 1 - T^2 / || x ||^2)
When quantizing a vector x to x_q, AVQ minimizes the loss function L(x, x_q) = eta * || r_para ||^2 + || r_perp ||^2, where r = x - x_q, r_para = <r, x> * x / || x ||^2, r_perp = r - r_para
Compared to L2 loss, This produces an x_q which better approximates the dot product of a query vector with x
If the threshold is NAN, AVQ is not performed during bfloat16 quant
- inline constexpr auto metric(
Distance metric used for clustering.
- IdxT size(
Total length of the index (number of vectors).
- inline constexpr auto dim(
Dimensionality of the data.
- ~index(
- inline index(
- raft::resources const &res,
- cuvs::distance::DistanceType metric,
- uint32_t n_leaves,
- uint32_t pq_bits,
- uint32_t pq_dim,
- IdxT n_rows,
- IdxT dim,
- uint32_t pq_clusters,
- uint32_t pq_num_subspaces,
- bool reordering_bf16
Construct an empty index. It will need to be trained and populated with
build
- inline index(
- raft::resources const &res,
- const index_params ¶ms,
- IdxT n_rows,
- IdxT dim
- inline raft::device_matrix_view<float, IdxT> centers(
- inline raft::device_matrix_view<const float, IdxT> centers(
- inline raft::device_vector_view<uint32_t, IdxT> labels(
- inline raft::device_vector_view<const uint32_t, IdxT> labels(
- inline raft::device_vector_view<uint32_t, IdxT> soar_labels(
- inline raft::device_vector_view<const uint32_t, IdxT> soar_labels(
- inline uint32_t n_rows(
- inline uint32_t n_leaves(
- inline uint32_t pq_dim(
- inline raft::device_matrix_view<const float, uint32_t, raft::row_major> pq_codebook(
- inline raft::device_matrix_view<float, uint32_t, raft::row_major> pq_codebook(
- inline raft::host_matrix_view<const uint8_t, IdxT, raft::row_major> quantized_residuals(
- inline raft::host_matrix_view<uint8_t, IdxT, raft::row_major> quantized_residuals(
- inline raft::host_matrix_view<const uint8_t, IdxT, raft::row_major> quantized_soar_residuals(
- inline raft::host_matrix_view<uint8_t, IdxT, raft::row_major> quantized_soar_residuals(
- inline raft::host_matrix_view<int16_t, IdxT, raft::row_major> bf16_dataset(
- inline raft::host_matrix_view<const int16_t, IdxT, raft::row_major> bf16_dataset(
- auto build(
- raft::resources const &handle,
- const cuvs::neighbors::experimental::scann::index_params ¶ms,
- raft::device_matrix_view<const float, int64_t, raft::row_major> dataset
Build the index from the dataset for efficient search.
- auto build(
- raft::resources const &handle,
- const cuvs::neighbors::experimental::scann::index_params ¶ms,
- raft::host_matrix_view<const float, int64_t, raft::row_major> dataset
Index serialize#
- void serialize(
- raft::resources const &handle,
- const std::string &file_prefix,
- const cuvs::neighbors::experimental::scann::index<float, int64_t> &index
Save the index to files in a directory.
This serializes the index into a list of files for integration into OSS ScaNN for use with search
NOTE: the implementation of ScaNN index build is EXPERIMENTAL and currently not subject to comprehensive, automated testing. Accuracy and performance are not guaranteed, and could diverge without warning.