Scann

Source header: cuvs/neighbors/scann.hpp

ScaNN index build parameters

neighbors::experimental::scann::index_params

ANN parameters used by ScaNN to build index

1 struct index_params : cuvs::neighbors::index_params {
2   uint32_t n_leaves;
3   int64_t kmeans_n_rows_train;
4   uint32_t kmeans_n_iters;
5   float partitioning_eta;
6   float soar_lambda;
7   uint32_t pq_dim;
8   uint32_t pq_bits;
9   int64_t pq_n_rows_train;
10   uint32_t pq_train_iters;
11   bool reordering_bf16;
12   float reordering_noise_shaping_threshold;
13 };

Fields

Name	Type	Description
`n_leaves`	`uint32_t`	the number of leaves in the tree *
`kmeans_n_rows_train`	`int64_t`	the number of rows for training the tree structures *
`kmeans_n_iters`	`uint32_t`	the max number of iterations for training the tree structure *
`partitioning_eta`	`float`	the value of eta for AVQ adjustment during partitioning *
`soar_lambda`	`float`	the value of lambda for SOAR spilling *
`pq_dim`	`uint32_t`	the dimension of pq subspaces (must divide dataset dimension)*
`pq_bits`	`uint32_t`	the number of bits for pq codes (must be 4 or 8, for 16 and 256 codes respectively) *
`pq_n_rows_train`	`int64_t`	the number of rows for PQ training (internally capped to 100k) *
`pq_train_iters`	`uint32_t`	the max number of iterations for PQ training *
`reordering_bf16`	`bool`	whether to apply bf16 quantization of dataset vectors *
`reordering_noise_shaping_threshold`	`float`	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

ScaNN index type

neighbors::experimental::scann::index

ScaNN index.

The index stores the dataset and the ScaNN graph in device memory.

1 template <typename T, typename IdxT>
2 struct index;

neighbors::experimental::scann::index::metric

Distance metric used for clustering.

1 [[nodiscard]] constexpr inline auto metric() const noexcept -> cuvs::distance::DistanceType;

Returns

cuvs::distance::DistanceType

neighbors::experimental::scann::index::size

Total length of the index (number of vectors).

1 IdxT size() const noexcept;

Returns

IdxT

neighbors::experimental::scann::index::dim

Dimensionality of the data.

1 [[nodiscard]] constexpr inline auto dim() const noexcept -> uint32_t;

Returns

uint32_t

ScaNN index build functions

neighbors::experimental::scann::build

Build the index from the dataset for efficient search.

1 auto build(raft::resources const& handle,
2 const cuvs::neighbors::experimental::scann::index_params& params,
3 raft::device_matrix_view<const float, int64_t, raft::row_major> dataset)
4 -> cuvs::neighbors::experimental::scann::index<float, int64_t>;

Parameters

Name	Direction	Type	Description
`handle`		`raft::resources const&`
`params`		`const cuvs::neighbors::experimental::scann::index_params&`
`dataset`		`raft::device_matrix_view<const float, int64_t, raft::row_major>`

Returns

cuvs::neighbors::experimental::scann::index<float, int64_t>

neighbors::experimental::scann::serialize

Save the index to files in a directory

1 void serialize(raft::resources const& handle,
2 const std::string& file_prefix,
3 const cuvs::neighbors::experimental::scann::index<float, int64_t>& index);

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.

Parameters

Name	Direction	Type	Description
`handle`		`raft::resources const&`
`file_prefix`		`const std::string&`
`index`		`const cuvs::neighbors::experimental::scann::index<float, int64_t>&`

Returns

void

ScaNN serialize functions

Additional overload: neighbors::experimental::scann::serialize

Save the index to files in a directory

1 void serialize(raft::resources const& handle,
2 const std::string& file_prefix,
3 const cuvs::neighbors::experimental::scann::index<float, int64_t>& index);

This serializes the index into a list of files for integration into OSS ScaNN for use with search

Parameters

Name	Direction	Type	Description
`handle`		`raft::resources const&`
`file_prefix`		`const std::string&`
`index`		`const cuvs::neighbors::experimental::scann::index<float, int64_t>&`

Returns

void

1	struct index_params : cuvs::neighbors::index_params {
2	uint32_t n_leaves;
3	int64_t kmeans_n_rows_train;
4	uint32_t kmeans_n_iters;
5	float partitioning_eta;
6	float soar_lambda;
7	uint32_t pq_dim;
8	uint32_t pq_bits;
9	int64_t pq_n_rows_train;
10	uint32_t pq_train_iters;
11	bool reordering_bf16;
12	float reordering_noise_shaping_threshold;
13	};

1	auto build(raft::resources const& handle,
2	const cuvs::neighbors::experimental::scann::index_params& params,
3	raft::device_matrix_view<const float, int64_t, raft::row_major> dataset)
4	-> cuvs::neighbors::experimental::scann::index<float, int64_t>;

1	void serialize(raft::resources const& handle,
2	const std::string& file_prefix,
3	const cuvs::neighbors::experimental::scann::index<float, int64_t>& index);