IVF-Flat#

IVF-Flat 方法是一种 ANN 算法。它使用倒排文件索引 (IVF) 和未经修改的（即 flat）向量。该算法提供简单的旋钮来减小整体搜索空间，并在准确性和速度之间进行权衡。

#include <raft/neighbors/ivf_flat.h>

索引构建参数#

typedef struct cuvsIvfFlatIndexParams *cuvsIvfFlatIndexParams_t#

cuvsError_t cuvsIvfFlatIndexParamsCreate( cuvsIvfFlatIndexParams_t *index_params )#

分配 IVF-Flat 索引参数，并填充默认值。

参数:: index_params – [in] 要分配的 cuvsIvfFlatIndexParams_t
返回:: cuvsError_t

cuvsError_t cuvsIvfFlatIndexParamsDestroy( cuvsIvfFlatIndexParams_t index_params )#

释放 IVF-Flat 索引参数。

参数:: index_params – [in]
返回:: cuvsError_t

struct cuvsIvfFlatIndexParams#

#include <ivf_flat.h>

构建 IVF-Flat 索引的补充参数。

公有成员

cuvsDistanceType metric#: 距离类型。

float metric_arg#: 某些距离指标使用的参数。

bool add_data_on_build#

是否将数据集内容添加到索引，即

true 表示索引已填充数据集向量，调用 build 后即可进行搜索。
false 表示 build 仅训练底层模型（例如量化器或聚类），但索引为空；之后需要对索引调用 extend 来填充它。

uint32_t n_lists#: 倒排列表（簇）的数量

uint32_t kmeans_n_iters#: 搜索 kmeans 中心（索引构建）的迭代次数。

double kmeans_trainset_fraction#: 迭代 kmeans 构建期间使用的数据比例。

bool adaptive_centers#

默认情况下 (adaptive_centers = false)，聚类中心在 ivf_flat::build 中训练，并且在 ivf_flat::extend 中从不修改。因此，在用新数据调用 (ivf_flat::extend) 几次后，您可能需要从头开始重新训练索引，这些新数据的分布可能不再代表原始训练集。

另一种行为 (adaptive_centers = true) 是在添加新数据时更新新数据的聚类中心。在这种情况下，index.centers() 始终是对应簇中数据的精确质心。这种行为的缺点是质心取决于添加新数据的顺序（通过对添加数据的分类）；也就是说，index.centers() 会随着新添加数据的分布变化而“漂移”。

bool conservative_memory_allocation#

默认情况下，算法会为单个簇 (list_data) 分配比所需更多的空间。这有助于分摊内存分配成本，并减少在重复调用 extend（扩展数据库）时的数据复制次数。

另一种选择是保守分配行为；启用时，算法始终分配存储给定数量记录所需的最小内存量。如果您希望尽可能少地使用 GPU 内存来存储数据库，请将此标志设置为 true。

索引搜索参数#

typedef struct cuvsIvfFlatSearchParams *cuvsIvfFlatSearchParams_t#

cuvsError_t cuvsIvfFlatSearchParamsCreate( cuvsIvfFlatSearchParams_t *params )#

分配 IVF-Flat 搜索参数，并填充默认值。

参数:: params – [in] 要分配的 cuvsIvfFlatSearchParams_t
返回:: cuvsError_t

cuvsError_t cuvsIvfFlatSearchParamsDestroy( cuvsIvfFlatSearchParams_t params )#

释放 IVF-Flat 搜索参数。

参数:: params – [in]
返回:: cuvsError_t

struct cuvsIvfFlatSearchParams#

#include <ivf_flat.h>

搜索 IVF-Flat 索引的补充参数。

公有成员

uint32_t n_probes#: 要搜索的簇数量。

索引#

typedef cuvsIvfFlatIndex *cuvsIvfFlatIndex_t#

cuvsError_t cuvsIvfFlatIndexCreate(cuvsIvfFlatIndex_t *index)#

分配 IVF-Flat 索引。

参数:: index – [in] 要分配的 cuvsIvfFlatIndex_t
返回:: cuvsError_t

cuvsError_t cuvsIvfFlatIndexDestroy(cuvsIvfFlatIndex_t index)#

释放 IVF-Flat 索引。

参数:: index – [in] 要释放的 cuvsIvfFlatIndex_t

struct cuvsIvfFlatIndex#: #include <ivf_flat.h>

用于保存 cuvs::neighbors::ivf_flat::index 的地址及其活动的训练 dtype 的结构体。

索引构建#

cuvsError_t cuvsIvfFlatBuild( cuvsResources_t res, cuvsIvfFlatIndexParams_t index_params, DLManagedTensor *dataset, cuvsIvfFlatIndex_t index )#

使用底层 DLDeviceType 等于 kDLCUDA, kDLCUDAHost, kDLCUDAManaged 或 kDLCPU 的 DLManagedTensor 构建 IVF-Flat 索引。此外，可接受的底层类型为

kDLDataType.code == kDLFloat and kDLDataType.bits = 32
kDLDataType.code == kDLInt and kDLDataType.bits = 8
kDLDataType.code == kDLUInt and kDLDataType.bits = 8

#include <cuvs/core/c_api.h>
#include <cuvs/neighbors/ivf_flat.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
cuvsIvfFlatIndexParams_t index_params;
cuvsError_t params_create_status = cuvsIvfFlatIndexParamsCreate(&index_params);

// Create IVF-Flat index
cuvsIvfFlatIndex_t index;
cuvsError_t index_create_status = cuvsIvfFlatIndexCreate(&index);

// Build the IVF-Flat Index
cuvsError_t build_status = cuvsIvfFlatBuild(res, index_params, &dataset, index);

// de-allocate `index_params`, `index` and `res`
cuvsError_t params_destroy_status = cuvsIvfFlatIndexParamsDestroy(index_params);
cuvsError_t index_destroy_status = cuvsIvfFlatIndexDestroy(index);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);

参数:

res – [in] cuvsResources_t 不透明 C 句柄
index_params – [in] 用于构建 IVF-Flat 索引的 cuvsIvfFlatIndexParams_t
dataset – [in] DLManagedTensor* 训练数据集
index – [out] 新构建的 IVF-Flat 索引 cuvsIvfFlatIndex_t

返回:

cuvsError_t

索引搜索#

cuvsError_t cuvsIvfFlatSearch( cuvsResources_t res, cuvsIvfFlatSearchParams_t search_params, cuvsIvfFlatIndex_t index, DLManagedTensor *queries, DLManagedTensor *neighbors, DLManagedTensor *distances, cuvsFilter filter )#

使用底层 DLDeviceType 等于 kDLCUDA, kDLCUDAHost, kDLCUDAManaged 的 DLManagedTensor 搜索 IVF-Flat 索引。需要注意的是，IVF-Flat 索引必须使用与 queries 相同的类型构建，使得 index.dtype.code == queries.dl_tensor.dtype.code 输入类型如下

queries: kDLDataType.code == kDLFloat and kDLDataType.bits = 32
neighbors: kDLDataType.code == kDLUInt and kDLDataType.bits = 32
distances: kDLDataType.code == kDLFloat and kDLDataType.bits = 32

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

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

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

// Create default search params
cuvsIvfFlatSearchParams_t search_params;
cuvsError_t params_create_status = cuvsIvfFlatSearchParamsCreate(&search_params);

// Search the `index` built using `ivfFlatBuild`
cuvsError_t search_status = cuvsIvfFlatSearch(res, search_params, index, &queries, &neighbors,
&distances);

// de-allocate `search_params` and `res`
cuvsError_t params_destroy_status = cuvsIvfFlatSearchParamsDestroy(search_params);
cuvsError_t res_destroy_status = cuvsResourcesDestroy(res);

参数:

res – [in] cuvsResources_t 不透明 C 句柄
search_params – [in] 用于搜索 IVF-Flat 索引的 cuvsIvfFlatSearchParams_t
index – [in] 由 ivfFlatBuild 返回的 ivfFlatIndex
queries – [in] DLManagedTensor* 要搜索的查询数据集
neighbors – [out] DLManagedTensor* 查询的输出 k 个近邻
distances – [out] DLManagedTensor* 查询的输出 k 个距离
filter – [in] cuvsFilter 输入过滤器，可用于根据给定的位集过滤查询和近邻。

索引序列化#

警告

doxygengroup: Cannot find group “ivf_flat_c_index_serialize” in doxygen xml output for project “cuvs” from directory: ../../cpp/doxygen/_xml/