本指南概述了 cuVS Benchmarks yaml 配置文件中可以指定的各种参数设置，并解释了它们对相应算法的影响，以帮助在不同召回率水平下进行基准测试时选择合适的设置。

cuVS 索引

cuvs_brute_force

使用 cuVS 暴力搜索索引进行精确搜索。暴力搜索没有额外的构建或搜索参数。

cuvs_ivf_flat

IVF-flat 使用倒排文件索引，将矢量划分为一系列聚类或列表，并以交错格式存储，该格式针对快速距离计算进行了优化。IVF-flat 索引的搜索将索引中的总矢量减少到用户指定的最近聚类（称为探针）内的矢量。

IVF-flat 是一种简单的算法，不会节省空间，但即使在较高的召回率水平下也能提供具有竞争力的搜索时间。

cuvs_ivf_pq

IVF-pq 是一种倒排文件索引，它将矢量划分为一系列聚类或列表，方式与上面的 IVF-flat 类似。不同之处在于 IVF-PQ 还使用乘积量化来压缩矢量，从而减小索引的内存占用。不幸的是，较高的压缩级别也会降低召回率，但在原始矢量仍然可用时，精炼步骤可以改善召回率。

cuvs_cagra

CAGRA 使用基于图的索引，该索引使用 IVF-PQ 创建一个中间的近似 kNN 图，然后进一步精炼和优化以创建最终的 kNN 图。CAGRA 使用此 kNN 图作为搜索索引。

对于不适合设备内存的大型数据集，`graph_memory_type 或 `internal_dataset_memory_type 选项会很有用。将 `internal_dataset_memory_type 设置为 `device 以外的值会对搜索速度产生负面影响。使用 `host_huge_page 选项仅在支持异构内存管理或原生支持 GPU 访问系统分配内存的平台（例如 Grace Hopper）上受支持。

为了微调 CAGRA 索引构建，我们可以使用以下设置自定义 IVF-PQ 索引构建器选项。这些设置仅在 `graph_build_algo == "IVF_PQ"` 时生效。建议使用单独的 IVF-PQ 索引进行实验，以找到在大型批处理下提供最大 QPS 的配置。召回率无需非常高，因为 CAGRA 会进一步优化 kNN 邻居图。某些默认值是根据数据集大小（假设为 [n_vecs, dim]）推导出来的。

参数	类型	必需	数据类型	默认值	描述
ivf_pq_build_nlist	构建	N	正整数 >0	sqrt(n_vecs)	将矢量划分为的聚类数量。值越大，每个聚类中的点越少，但这会影响索引构建时间，因为需要训练更多聚类。
ivf_pq_build_niter	构建	N	正整数 >0	25	训练聚类时使用的 k-means 迭代次数。
ivf_pq_build_ratio	构建	N	正整数 >0	10	`1/ratio 是用于训练聚类的训练点数量。
ivf_pq_pq_dim	构建	N	正整数。8 的倍数	dim/2 向上取整到 8	乘积量化后的矢量维度。当为 0 时，使用启发式方法选择此值。`pq_dim * `pq_bits 必须是 8 的倍数。
ivf_pq_build_pq_bits	构建	N	正整数 [4-8]	8	量化后矢量元素的位长度。
ivf_pq_build_codebook_kind	构建	N	[`cluster, `subspace`]	subspace	码本类型。有关更多详细信息，请参阅 IVF-PQ 索引概述
ivf_pq_build_nprobe	搜索	N	正整数 >0	min(2*dim, nlist)	对每个查询矢量进行搜索的最近聚类数量。值越大，召回率越高，但会在索引中搜索更多点。
ivf_pq_build_internalDistanceDtype	搜索	N	[float, `half`]	half	用于距离计算的精度。较低的精度可以提高性能，但会牺牲准确性。
ivf_pq_build_smemLutDtype	搜索	N	[float, `half, `fp8`]	fp8	在共享内存中查找表使用的精度。较低的精度可以提高性能，但会牺牲准确性。
ivf_pq_build_refine_ratio	搜索	N	正整数 >0	2	最初从索引中查询 `refine_ratio * k 个最近邻居，然后通过额外的精炼步骤仅选择最好的 `k 个邻居来提高召回率。

或者，如果 `graph_build_algo == "NN_DESCENT"`，则可以自定义以下参数

参数	类型	必需	数据类型	默认值	描述
nn_descent_niter	构建	N	正整数 >0	20	nn-descent 迭代次数
nn_descent_intermediate_graph_degree	构建	N	正整数 >0	cagra.intermediate_graph_degree * 1.5	nn-descent 迭代期间的中间图度数
nn_descent_termination_threshold	构建	N	正浮点数 >0	1e-4	nn-descent 收敛的早期停止阈值

cuvs_cagra_hnswlib

这是一个基准测试，它实现了 `CAGRA 构建的 `HNSW 搜索之间的互操作性。它使用 `CAGRA 构建的图作为 `hnswlib 索引的基础层，仅在基础层内搜索查询（这通过对 `hnswlib 的一个简单补丁实现）。

`build : 与 CAGRA 的 `build 相同

`search : 与 Hnswlib 的 `search 相同

FAISS 索引

faiss_gpu_flat

在 GPU 上使用 FAISS flat 索引，该索引使用暴力搜索执行精确搜索，并且没有额外的构建或搜索参数。

faiss_gpu_ivf_flat

IVF-flat 使用倒排文件索引，将矢量划分为一系列聚类或列表，并以交错格式存储，该格式针对快速距离计算进行了优化。IVF-flat 索引的搜索将索引中的总矢量减少到用户指定的最近聚类（称为探针）内的矢量。

IVF-flat 是一种简单的算法，不会节省空间，但即使在较高的召回率水平下也能提供具有竞争力的搜索时间。

参数	类型	必需	数据类型	默认值	描述
nlists	构建	是	正整数 >0		将矢量划分为的聚类数量。值越大，每个聚类中的点越少，但这会影响索引构建时间，因为需要训练更多聚类
ratio	构建	N	正整数 >0	2	`1/ratio 是用于训练聚类的训练点数量。
nprobe	搜索	是	正整数 >0		对每个查询矢量进行搜索的最近聚类数量。值越大，召回率越高，但会在索引中搜索更多点。

faiss_gpu_ivf_pq

IVF-pq 是一种倒排文件索引，它将矢量划分为一系列聚类或列表，方式与上面的 IVF-flat 类似。不同之处在于 IVF-PQ 还使用乘积量化来压缩矢量，从而减小索引的内存占用。不幸的是，较高的压缩级别也会降低召回率，但在原始矢量仍然可用时，精炼步骤可以改善召回率。

参数	类型	必需	数据类型	默认值	描述
nlist	构建	是	正整数 >0		将矢量划分为的聚类数量。值越大，每个聚类中的点越少，但这会影响索引构建时间，因为需要训练更多聚类。
ratio	构建	N	正整数 >0	2	`1/ratio 是用于训练聚类的训练点数量。
M_ratio	构建	是	正整数。2 的幂 [8-64]		每个矢量的块或子量化器数量的比例。通过 `dims / `M_ratio 计算得出
usePrecomputed	构建	N	布尔值	false	使用预计算的查找表来加速搜索，代价是增加内存使用。
useFloat16	构建	N	布尔值	false	在聚类步骤中使用半精度浮点数。
nprobe	搜索	是	正整数 >0		对每个查询矢量进行搜索的最近聚类数量。值越大，召回率越高，但会在索引中搜索更多点。
refine_ratio	搜索	N	正数 >=1	1	最初从索引中查询 `refine_ratio * k 个最近邻居，然后通过额外的精炼步骤仅选择最好的 `k 个邻居来提高召回率。

faiss_cpu_flat

在 CPU 上使用 FAISS flat 索引，该索引使用暴力搜索执行精确搜索，并且没有额外的构建或搜索参数。

参数	类型	必需	数据类型	默认值	描述
numThreads	搜索	N	正整数 >0	1	用于查询的线程数。

faiss_cpu_ivf_flat

在 CPU 上使用 FAISS IVF-Flat 索引

参数	类型	必需	数据类型	默认值	描述
nlists	构建	是	正整数 >0		将矢量划分为的聚类数量。值越大，每个聚类中的点越少，但这会影响索引构建时间，因为需要训练更多聚类
ratio	构建	N	正整数 >0	2	`1/ratio 是用于训练聚类的训练点数量。
nprobe	搜索	是	正整数 >0		对每个查询矢量进行搜索的最近聚类数量。值越大，召回率越高，但会在索引中搜索更多点。
numThreads	搜索	N	正整数 >0	1	用于查询的线程数。

faiss_cpu_ivf_pq

在 CPU 上使用 FAISS IVF-PQ 索引

参数	类型	必需	数据类型	默认值	描述
nlist	构建	是	正整数 >0		将矢量划分为的聚类数量。值越大，每个聚类中的点越少，但这会影响索引构建时间，因为需要训练更多聚类。
ratio	构建	N	正整数 >0	2	`1/ratio 是用于训练聚类的训练点数量。
M	构建	是	正整数。2 的幂 [8-64]		每个矢量的块或子量化器数量的比例。通过 `dims / `M_ratio 计算得出
usePrecomputed	构建	N	布尔值	false	使用预计算的查找表来加速搜索，代价是增加内存使用。
bitsPerCode	构建	N	正整数 [4-8]	8	表示每个量化码的位数。
nprobe	搜索	是	正整数 >0		对每个查询矢量进行搜索的最近聚类数量。值越大，召回率越高，但会在索引中搜索更多点。
refine_ratio	搜索	N	正数 >=1	1	最初从索引中查询 `refine_ratio * k 个最近邻居，然后通过额外的精炼步骤仅选择最好的 `k 个邻居来提高召回率。
numThreads	搜索	N	正整数 >0	1	用于查询的线程数。

HNSW

hnswlib

参数	类型	必需	数据类型	默认值	描述
efConstruction	构建	是	正整数 >0		控制索引时间和准确性。值越大，索引质量越高。在某个点之后，增加此值将不再提高质量。
M	构建	是	正整数。通常在 2-100 之间		构建期间为每个新元素创建的双向链接数量。较高的值适用于较高的内在维度和/或高召回率，较低的值适用于内在维度较低和/或低召回率的数据集。也影响算法的内存消耗。
numThreads	构建	N	正整数 >0	1	用于构建索引的线程数。
ef	搜索	是	正整数 >0		用于搜索的最近邻居动态列表的大小。值越高，搜索越准确但越慢。不能低于 `k。
numThreads	搜索	N	正整数 >0	1	用于查询的线程数。

请参阅 hnswlib 的 HNSW 算法参数指南，了解有关这些参数的更多信息。