CAGRA#

CAGRA 是一种基于图的最近邻算法，专为 GPU 加速而构建。CAGRA 在小批量和大批量搜索场景下均展现了最先进的索引构建和查询性能。

#include <raft/neighbors/cagra.h>

索引构建参数#

enum cuvsCagraGraphBuildAlgo#

用于表示构建 CAGRA 图使用的 ANN 算法的枚举。

值

enumerator AUTO_SELECT#
enumerator IVF_PQ#
enumerator NN_DESCENT#
enumerator ITERATIVE_CAGRA_SEARCH#
typedef struct cuvsCagraCompressionParams *cuvsCagraCompressionParams_t#
typedef struct cuvsIvfPqParams *cuvsIvfPqParams_t#
typedef struct cuvsCagraIndexParams *cuvsCagraIndexParams_t#
cuvsError_t cuvsCagraIndexParamsCreate(
cuvsCagraIndexParams_t *params
)#

分配 CAGRA 索引参数，并填充默认值。

参数:

params – [in] 要分配的 cuvsCagraIndexParams_t

返回:

cuvsError_t

cuvsError_t cuvsCagraIndexParamsDestroy(
cuvsCagraIndexParams_t params
)#

释放 CAGRA 索引参数。

参数:

params – [in]

返回:

cuvsError_t

cuvsError_t cuvsCagraCompressionParamsCreate(
cuvsCagraCompressionParams_t *params
)#

分配 CAGRA 压缩参数，并填充默认值。

参数:

params – [in] 要分配的 cuvsCagraCompressionParams_t

返回:

cuvsError_t

cuvsError_t cuvsCagraCompressionParamsDestroy(
cuvsCagraCompressionParams_t params
)#

释放 CAGRA 压缩参数。

参数:

params – [in]

返回:

cuvsError_t

struct cuvsCagraCompressionParams#
#include <cagra.h>

VPQ 压缩参数。

公共成员

uint32_t pq_bits#

经过 PQ 压缩后向量元素的位长。

可能的值：[4, 5, 6, 7, 8]。

提示：'pq_bits' 越小，索引大小越小，搜索性能越好，但召回率越低。

uint32_t pq_dim#

经过 PQ 压缩后向量的维度。当为零时，使用启发式方法选择最优值。

TODO: 目前 dim 必须是 pq_dim 的倍数。

uint32_t vq_n_centers#

向量量化 (VQ) 码本大小 - “粗粒度聚类中心” 的数量。当为零时，使用启发式方法选择最优值。

uint32_t kmeans_n_iters#

搜索 kmeans 中心（VQ 和 PQ 阶段）的迭代次数。

double vq_kmeans_trainset_fraction#

在迭代 kmeans 构建（VQ 阶段）期间使用的数据比例。当为零时，使用启发式方法选择最优值。

double pq_kmeans_trainset_fraction#

在迭代 kmeans 构建（PQ 阶段）期间使用的数据比例。当为零时，使用启发式方法选择最优值。

struct cuvsIvfPqParams#
#include <cagra.h>
struct cuvsCagraIndexParams#
#include <cagra.h>

构建 CAGRA 索引的补充参数。

公共成员

cuvsDistanceType metric#

距离类型。

size_t intermediate_graph_degree#

用于剪枝的输入图的度。

size_t graph_degree#

输出图的度。

enum cuvsCagraGraphBuildAlgo build_algo#

构建 knn 图的 ANN 算法。

size_t nn_descent_niter#

如果使用 NN_DESCENT 构建，则运行的迭代次数

cuvsCagraCompressionParams_t compression#

可选：如果需要压缩，请指定压缩参数。

注意：这是实验性的新 API，请谨慎使用。

cuvsIvfPqParams_t graph_build_params#

可选：当 build_algo = IVF_PQ 时指定 ivf pq 参数

索引搜索参数#

enum cuvsCagraSearchAlgo#

用于表示搜索 CAGRA 索引使用的算法的枚举。

值

enumerator SINGLE_CTA#

用于大批量。

enumerator MULTI_CTA#

用于小批量。

enumerator MULTI_KERNEL#
enumerator AUTO#
enum cuvsCagraHashMode#

用于表示搜索 CAGRA 索引时使用的 Hash 模式的枚举。

值

enumerator HASH#
enumerator SMALL#
enumerator AUTO_HASH#
typedef struct cuvsCagraSearchParams *cuvsCagraSearchParams_t#
cuvsError_t cuvsCagraSearchParamsCreate(
cuvsCagraSearchParams_t *params
)#

分配 CAGRA 搜索参数，并填充默认值。

参数:

params – [in] 要分配的 cuvsCagraSearchParams_t

返回:

cuvsError_t

cuvsError_t cuvsCagraSearchParamsDestroy(
cuvsCagraSearchParams_t params
)#

释放 CAGRA 搜索参数。

参数:

params – [in]

返回:

cuvsError_t

struct cuvsCagraSearchParams#
#include <cagra.h>

搜索 CAGRA 索引的补充参数。

公共成员

size_t max_queries#

同时搜索的最大查询数（批量大小）。当为 0 时自动选择。

size_t itopk_size#

搜索期间保留的中间搜索结果数。

这是调整精度和搜索速度之间权衡的主要旋钮。值越大，搜索精度越高。

size_t max_iterations#

搜索迭代次数的上限。当为 0 时自动选择。

enum cuvsCagraSearchAlgo algo#

使用哪种搜索实现。

size_t team_size#

用于计算单个距离的线程数。可选值：4, 8, 16 或 32。

size_t search_width#

在每次迭代中选择作为搜索起始点的图节点数。也称为搜索宽度？

size_t min_iterations#

搜索迭代次数的下限。

size_t thread_block_size#

线程块大小。可选值：0, 64, 128, 256, 512, 1024。当为 0 时自动选择。

enum cuvsCagraHashMode hashmap_mode#

哈希表类型。当为 AUTO 时自动选择。

size_t hashmap_min_bitlen#

哈希表位长的下限。大于 8。

float hashmap_max_fill_rate#

哈希表填充率的上限。大于 0.1，小于 0.9。

uint32_t num_random_samplings#

初始随机种子节点选择的迭代次数。1 或更多。

uint64_t rand_xor_mask#

用于初始随机种子节点选择的位掩码。

索引#

typedef cuvsCagraIndex *cuvsCagraIndex_t#
cuvsError_t cuvsCagraIndexCreate(cuvsCagraIndex_t *index)#

分配 CAGRA 索引。

参数:

index – [in] 要分配的 cuvsCagraIndex_t

返回:

cagraError_t

cuvsError_t cuvsCagraIndexDestroy(cuvsCagraIndex_t index)#

释放 CAGRA 索引。

参数:

index – [in] 要释放的 cuvsCagraIndex_t

cuvsError_t cuvsCagraIndexGetDims(cuvsCagraIndex_t index, int *dim)#

获取 CAGRA 索引的维度。

参数:

  • index – [in] CAGRA 索引

  • dim – [out] 返回索引的维度

返回:

cuvsError_t

struct cuvsCagraIndex#
#include <cagra.h>

用于保存 cuvs::neighbors::cagra::index 地址及其活动训练数据类型的结构体。

索引构建#

cuvsError_t cuvsCagraBuild(
cuvsResources_t res,
cuvsCagraIndexParams_t params,
DLManagedTensor *dataset,
cuvsCagraIndex_t index
)#

使用底层 DLDeviceType 等于 kDLCUDA、kDLCUDAHost、kDLCUDAManaged 或 kDLCPU 的 DLManagedTensor 构建 CAGRA 索引。此外，可接受的底层类型包括

  1. kDLDataType.code == kDLFloat 且 kDLDataType.bits = 32

  2. kDLDataType.code == kDLFloat 且 kDLDataType.bits = 16

  3. kDLDataType.code == kDLInt 且 kDLDataType.bits = 8

  4. kDLDataType.code == kDLUInt 且 kDLDataType.bits = 8

#include <cuvs/core/c_api.h>
#include <cuvs/neighbors/cagra.h>

// Create cuvsResources_t
cuvsResources_t res;
cuvsError_t res_create_status = cuvsResourcesCreate(&res);

// Assume a populated `DLManagedTensor` type here
DLManagedTensor dataset;

// Create default index params
cuvsCagraIndexParams_t params;
cuvsError_t params_create_status = cuvsCagraIndexParamsCreate(&params);

// Create CAGRA index
cuvsCagraIndex_t index;
cuvsError_t index_create_status = cuvsCagraIndexCreate(&index);

// Build the CAGRA Index
cuvsError_t build_status = cuvsCagraBuild(res, params, &dataset, index);

// de-allocate `params`, `index` and `res`
cuvsError_t params_destroy_status = cuvsCagraIndexParamsDestroy(params);
cuvsError_t index_destroy_status = cuvsCagraIndexDestroy(index);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);
参数:
返回:

cuvsError_t

索引序列化#

警告

doxygengroup: 在项目“cuvs”的 doxygen xml 输出目录 ../../cpp/doxygen/_xml/ 中找不到组“cagra_c_index_serialize”