命名空间 faiss

namespace faiss

实现具有许多变体的 k 均值聚类。

版权所有 (c) Facebook, Inc. 及其附属公司。

此源代码已获得 MIT 许可，该许可位于此源代码树的 LICENSE 文件中。

IDSelector 旨在定义要处理的向量子集（用于删除或作为搜索的子集）

PQ4 SIMD 打包和累积函数

基本内核使用 bbs = nb * 2 * 16 个向量累积 nq 查询向量，并生成该向量的输出矩阵。 对于 nq * nb <= 4 来说很有趣，否则寄存器溢出变得太大。

这些函数的实现分布在 3 个 cpp 文件中，以减少并行编译时间。 模板被显式实例化。

此文件包含用于计算距离的内核的回调。

在整个库中，向量以 float * 指针的形式提供。 当在一批中一起处理（添加/搜索）多个向量时，大多数算法都可以优化。 在这种情况下，它们作为矩阵传递。 当大小为 d 的 n 个向量作为 float * x 提供时，向量 i 的分量 j 为

x[ i * d + j ]

其中 0 <= i < n 且 0 <= j < d。 换句话说，矩阵始终是紧凑的。 当指定矩阵的大小时，我们称其为 n*d 矩阵，这意味着行优先存储。

I/O 函数可以读取/写入文件名、文件句柄或抽象介质的对象。

读取函数返回应该用 delete 释放的对象。 这些对象中的所有引用都归该对象所有。

倒排列表的定义 + 几个实现该接口的常见类。

由于 IVF（倒排文件）索引对于大规模用例非常有用，因此我们将与它们相关的几个函数分组到这个小型库中。 大多数函数都适用于 IndexIVF 和嵌入在 IndexPreTransform 中的 IndexIVF。

在此文件中，实现了超出 L2 和内积的额外指标

实现几个神经网络层，主要用于支持 QINCo

定义几个将转换应用于一组向量的对象 通常这些是预处理步骤。

类型定义

using IndexIDMap = IndexIDMapTemplate<Index>

using IndexBinaryIDMap = IndexIDMapTemplate<IndexBinary>

using IndexIDMap2 = IndexIDMap2Template<Index>

using IndexBinaryIDMap2 = IndexIDMap2Template<IndexBinary>

using IVFSearchParameters = SearchParametersIVF

using IndexReplicas = IndexReplicasTemplate<Index>

using IndexBinaryReplicas = IndexReplicasTemplate<IndexBinary>

using IndexShards = IndexShardsTemplate<Index>

using IndexBinaryShards = IndexShardsTemplate<IndexBinary>

using ConcatenatedInvertedLists = HStackInvertedLists

using idx_t = int64_t

所有向量索引都是这种类型

typedef HeapArray<CMin<float, int64_t>> float_minheap_array_t

typedef HeapArray<CMin<int, int64_t>> int_minheap_array_t

typedef HeapArray<CMax<float, int64_t>> float_maxheap_array_t

typedef HeapArray<CMax<int, int64_t>> int_maxheap_array_t

枚举

enum MetricType

用于 Faiss 索引和算法的向量比较的度量空间。

大多数算法都支持内积和 L2，其中平面（暴力破解）索引支持用于向量比较的其他度量类型。

值

enumerator METRIC_INNER_PRODUCT

最大内积搜索

enumerator METRIC_L2

平方 L2 搜索

enumerator METRIC_L1

L1 (又名 cityblock)

enumerator METRIC_Linf

无穷距离

enumerator METRIC_Lp

L_p 距离，p 由 faiss::Index metric_arg 给出

enumerator METRIC_Canberra

scipy.spatial.distance 中定义的一些其他度量

enumerator METRIC_BrayCurtis

enumerator METRIC_JensenShannon

enumerator METRIC_Jaccard

sum_i(min(a_i, b_i)) / sum_i(max(a_i, b_i)) 其中 a_i, b_i > 0

enumerator METRIC_NaNEuclidean

平方欧几里得距离，忽略 NaN。

enumerator METRIC_ABS_INNER_PRODUCT

abs(x | y)：到超平面的距离

函数

Index *clone_index(const Index*)

Quantizer *clone_Quantizer(const Quantizer *quant)

IndexBinary *clone_binary_index(const IndexBinary *index)

float kmeans_clustering(size_t d, size_t n, size_t k, const float *x, float *centroids)

简化的接口

参数：

• d – 数据维度

• n – 训练向量的数量

• k – 输出质心的数量

• x – 训练集（大小为 n * d）

• centroids – 输出质心（大小为 k * d）

返回值：

最终量化误差

std::string reverse_index_factory(const faiss::Index *index)

std::string reverse_index_factory(const faiss::IndexBinary *index)

template<typename PQDecoderT>
inline float distance_single_code_generic(const size_t M, const size_t nbits, const float *sim_table, const uint8_t *code)

返回到单个代码的距离。

template<typename PQDecoderT> inline void distance_four_codes_generic (const size_t M, const size_t nbits, const float *sim_table, const uint8_t *__restrict code0, const uint8_t *__restrict code1, const uint8_t *__restrict code2, const uint8_t *__restrict code3, float &result0, float &result1, float &result2, float &result3)

组合 distance_single_code() 的 4 个操作。通用版本。

template<typename PQDecoderT>
inline float distance_single_code(const size_t M, const size_t nbits, const float *sim_table, const uint8_t *code)

template<typename PQDecoderT> inline void distance_four_codes (const size_t M, const size_t nbits, const float *sim_table, const uint8_t *__restrict code0, const uint8_t *__restrict code1, const uint8_t *__restrict code2, const uint8_t *__restrict code3, float &result0, float &result1, float &result2, float &result3)

void handleExceptions(std::vector<std::pair<int, std::exception_ptr>> &exceptions)

处理来自工作线程的多个异常，抛出一个适当的异常，该异常聚合了信息。pair int 是生成异常的线程

std::string demangle_cpp_symbol(const char *name)

使 typeid 更具可读性

int search_from_candidates(const HNSW &hnsw, DistanceComputer &qdis, ResultHandler<HNSW::C> &res, HNSW::MinimaxHeap &candidates, VisitedTable &vt, HNSWStats &stats, int level, int nres_in = 0, const SearchParametersHNSW *params = nullptr)

HNSWStats greedy_update_nearest(const HNSW &hnsw, DistanceComputer &qdis, int level, HNSW::storage_idx_t &nearest, float &d_nearest)

std::priority_queue<HNSW::Node> search_from_candidate_unbounded(const HNSW &hnsw, const HNSW::Node &node, DistanceComputer &qdis, int ef, VisitedTable *vt, HNSWStats &stats)

void search_neighbors_to_add(HNSW &hnsw, DistanceComputer &qdis, std::priority_queue<HNSW::NodeDistCloser> &results, int entry_point, float d_entry_point, int level, VisitedTable &vt, bool reference_version = false)

void read_index_header(Index *idx, IOReader *f)

void read_direct_map(DirectMap *dm, IOReader *f)

void read_ivf_header(IndexIVF *ivf, IOReader *f, std::vector<std::vector<idx_t>> *ids = nullptr)

void read_InvertedLists(IndexIVF *ivf, IOReader *f, int io_flags)

ArrayInvertedLists *set_array_invlist(IndexIVF *ivf, std::vector<std::vector<idx_t>> &ids)

void read_ProductQuantizer(ProductQuantizer *pq, IOReader *f)

void read_ScalarQuantizer(ScalarQuantizer *ivsc, IOReader *f)

uint32_t fourcc(const char sx[4])

将一个4字符的字符串转换为一个可以轻松写入和读取的uint32_t

uint32_t fourcc(const std::string &sx)

void fourcc_inv(uint32_t x, char str[5])

std::string fourcc_inv(uint32_t x)

std::string fourcc_inv_printable(uint32_t x)

void smawk(const idx_t nrows, const idx_t ncols, const float *x, idx_t *argmins)

SMAWK算法。找到单调矩阵的行最小值。

公开此功能以进行测试。

参数：

• nrows – 行数

• ncols – 列数

• x – 输入矩阵，大小为 (nrows, ncols)

• argmins – 每行的 argmin

double kmeans1d(const float *x, size_t n, size_t nclusters, float *centroids)

通过动态规划实现精确的一维 K-Means 算法

出自 Allan Grønlund, Kasper Green Larsen, Alexander Mathiasen, Jesper Sindahl Nielsen, Stefan Schneider, Mingzhou Song 的论文 “Fast Exact k-Means, k-Medians and Bregman Divergence Clustering in 1D”，ArXiV’17

第 2.2 节

https://arxiv.org/abs/1701.07204

参数：

• x – 输入一维数组

• n – 输入数组长度

• nclusters – 簇的数量

• centroids – 输出质心，大小为 nclusters

返回值：

不平衡因子

void pq4_pack_codes(const uint8_t *codes, size_t ntotal, size_t M, size_t nb, size_t bbs, size_t nsq, uint8_t *blocks)

打包代码以供 SIMD 内核使用。未使用的字节设置为 0。

参数：

• codes – 输入代码，大小为 (ntotal, ceil(M / 2))

• ntotal – 输入代码的数量

• nb – 输出代码的数量（ntotal 四舍五入到 bbs 的倍数）

• nsq – 子量化器的数量（= M 四舍五入到 2 的倍数）

• bbs – 数据库块的大小（32 的倍数）

• blocks – 输出数组，大小为 nb * nsq / 2。

void pq4_pack_codes_range(const uint8_t *codes, size_t M, size_t i0, size_t i1, size_t bbs, size_t nsq, uint8_t *blocks)

与 pack_codes 相同，但在给定的输出范围内写入，其余部分保持不变。假设输入时分配的条目为 0。

参数：

• codes – 输入代码，大小为 (i1 - i0, ceil(M / 2))

• i0 – 要写入的第一个输出代码

• i1 – 要写入的最后一个输出代码

• blocks – 输出数组，大小至少为 ceil(i1 / bbs) * bbs * nsq / 2

uint8_t pq4_get_packed_element(const uint8_t *data, size_t bbs, size_t nsq, size_t vector_id, size_t sq)

从打包的代码表中获取单个元素

参数：

• vector_id – 向量 ID

• sq – 子量化器 (< nsq)

void pq4_set_packed_element(uint8_t *data, uint8_t code, size_t bbs, size_t nsq, size_t vector_id, size_t sq)

将单个元素“code”设置到打包的代码表中

参数：

• vector_id – 向量 ID

• sq – 子量化器 (< nsq)

void pq4_pack_LUT(int nq, int nsq, const uint8_t *src, uint8_t *dest)

打包查找表以供内核使用。

参数：

• nq – 查询的数量

• nsq – 子量化器的数量（2 的倍数）

• src – 输入数组，大小为 (nq, 16)

• dest – 输出数组，大小为 (nq, 16)

void pq4_accumulate_loop(int nq, size_t nb, int bbs, int nsq, const uint8_t *codes, const uint8_t *LUT, SIMDResultHandler &res, const NormTableScaler *scaler)

循环遍历数据库元素并将结果累积到结果处理程序中

参数：

• nq – 查询的数量

• nb – 数据库元素的数量

• bbs – 数据库块的大小（32 的倍数）

• nsq – 子量化器的数量（2 的倍数）

• codes – 打包的代码数组

• LUT – 打包的查找表

• scaler – 用于缩放编码范数的缩放器

int pq4_qbs_to_nq(int qbs)

int pq4_preferred_qbs(int nq)

返回查询数量的块中的首选分解。

int pq4_pack_LUT_qbs(int fqbs, int nsq, const uint8_t *src, uint8_t *dest)

打包查找表以供内核使用。

参数：

• qbs – 4 位编码的查询块数，从它推导出处理的查询总数 (nq)

• nsq – 子量化器的数量（2 的倍数）

• src – 输入数组，大小为 (nq, 16)

• dest – 输出数组，大小为 (nq, 16)

返回值：

nq

int pq4_pack_LUT_qbs_q_map(int qbs, int nsq, const uint8_t *src, const int *q_map, uint8_t *dest)

与 pq4_pack_LUT_qbs 相同，除了源向量使用 q_map 重新映射

void pq4_accumulate_loop_qbs(int qbs, size_t nb, int nsq, const uint8_t *codes, const uint8_t *LUT, SIMDResultHandler &res, const NormTableScaler *scaler = nullptr)

运行累加循环。

参数：

• qbs – 4 位编码的查询数量

• nb – 数据库代码的数量（bbs 的倍数）

• nsq – 子量化器的数量

• codes – 编码的数据库向量（打包）

• LUT – 查找表（打包）

• res – 结果的回调函数

• scaler – 用于缩放编码范数的缩放器

void beam_search_encode_step(size_t d, size_t K, const float *cent, size_t n, size_t beam_size, const float *residuals, size_t m, const int32_t *codes, size_t new_beam_size, int32_t *new_codes, float *new_residuals, float *new_distances, Index *assign_index = nullptr, ApproxTopK_mode_t approx_topk = ApproxTopK_mode_t::EXACT_TOPK)

通过从质心表中采样来编码残差。

这是残差量化器的单个编码步骤。 它允许低级别访问编码函数，主要用于单元测试。

参数：

• n – 要处理的向量数

• residuals – 要编码的向量，大小为 (n, beam_size, d)

• cent – 质心，大小为 (K, d)

• beam_size – 输入束大小

• m – 上一个编码步骤的代码大小

• codes – 束的上一步的代码数组 (n, beam_size, m)

• new_beam_size – 输出束大小（应 <= K * beam_size）

• new_codes – 输出代码，大小为 (n, new_beam_size, m + 1)

• new_residuals – 输出残差，大小为 (n, new_beam_size, d)

• new_distances – 输出距离，大小为 (n, new_beam_size)

• assign_index – 如果非 NULL，将用于执行分配

void beam_search_encode_step_tab(size_t K, size_t n, size_t beam_size, const float *codebook_cross_norms, size_t ldc, const uint64_t *codebook_offsets, const float *query_cp, size_t ldqc, const float *cent_norms_i, size_t m, const int32_t *codes, const float *distances, size_t new_beam_size, int32_t *new_codes, float *new_distances, ApproxTopK_mode_t approx_topk = ApproxTopK_mode_t::EXACT_TOPK)

使用向量与码本的点积来编码一组向量

参数：

• K – 码本中的向量数

• n – 要编码的向量数

• beam_size – 输入束大小

• codebook_cross_norms – 此码本与先前编码的 m 个码本的内积

• codebook_offsets – 每个先前码本在 codebook_cross_norms 中的偏移量

• query_cp – 查询向量与 ??? 的点积

• cent_norms_i – 质心的范数

template<class Consumer, class ...Types>
Consumer::T dispatch_knn_ResultHandler(size_t nx, float *vals, int64_t *ids, size_t k, MetricType metric, const IDSelector *sel, Consumer &consumer, Types... args)

template<class Consumer, class ...Types>
Consumer::T dispatch_range_ResultHandler(RangeSearchResult *res, float radius, MetricType metric, const IDSelector *sel, Consumer &consumer, Types... args)

Index *index_factory(int d, const char *description, MetricType metric = METRIC_L2)

使用字符串中描述的处理步骤序列构建索引。

IndexBinary *index_binary_factory(int d, const char *description)

void write_index(const Index *idx, const char *fname, int io_flags = 0)

void write_index(const Index *idx, FILE *f, int io_flags = 0)

void write_index(const Index *idx, IOWriter *writer, int io_flags = 0)

void write_index_binary(const IndexBinary *idx, const char *fname)

void write_index_binary(const IndexBinary *idx, FILE *f)

void write_index_binary(const IndexBinary *idx, IOWriter *writer)

Index *read_index(const char *fname, int io_flags = 0)

Index *read_index(FILE *f, int io_flags = 0)

Index *read_index(IOReader *reader, int io_flags = 0)

IndexBinary *read_index_binary(const char *fname, int io_flags = 0)

IndexBinary *read_index_binary(FILE *f, int io_flags = 0)

IndexBinary *read_index_binary(IOReader *reader, int io_flags = 0)

void write_VectorTransform(const VectorTransform *vt, const char *fname)

void write_VectorTransform(const VectorTransform *vt, IOWriter *f)

VectorTransform *read_VectorTransform(const char *fname)

VectorTransform *read_VectorTransform(IOReader *f)

ProductQuantizer *read_ProductQuantizer(const char *fname)

ProductQuantizer *read_ProductQuantizer(IOReader *reader)

void write_ProductQuantizer(const ProductQuantizer *pq, const char *fname)

void write_ProductQuantizer(const ProductQuantizer *pq, IOWriter *f)

void write_InvertedLists(const InvertedLists *ils, IOWriter *f)

InvertedLists *read_InvertedLists(IOReader *reader, int io_flags = 0)

void initialize_IVFPQ_precomputed_table(int &use_precomputed_table, const Index *quantizer, const ProductQuantizer &pq, AlignedTable<float> &precomputed_table, bool by_residual, bool verbose)

为具有按残差和 METRIC_L2 的 IVFPQ 预先计算距离表

参数：

• use_precomputed_table – (I/O) =-1: 强制禁用 =0: 启发式决定 (默认: 仅当表 < precomputed_tables_max_bytes 时使用), 设置输出上的 use_precomputed_table =1: 适用于所有量化器的表 (大小 256 * nlist * M) =2: MultiIndexQuantizer 的特定版本 (更紧凑)

• precomputed_table – 用于初始化的预计算表

inline uint64_t lo_build(uint64_t list_id, uint64_t offset)

inline uint64_t lo_listno(uint64_t lo)

inline uint64_t lo_offset(uint64_t lo)

constexpr bool is_similarity_metric(MetricType metric_type)

此函数用于区分最小和最大索引，因为我们需要以灵活的方式支持相似性和非相似性指标

template<int A = 32>
inline bool is_aligned_pointer(const void *x)

inline uint16_t encode_bf16(const float f)

inline float decode_bf16(const uint16_t v)

float fvec_L2sqr(const float *x, const float *y, size_t d)

两个向量之间的L2距离的平方。

float fvec_inner_product(const float *x, const float *y, size_t d)

内积

float fvec_L1(const float *x, const float *y, size_t d)

L1 距离。

float fvec_Linf(const float *x, const float *y, size_t d)

无穷距离

void fvec_inner_product_batch_4(const float *x, const float *y0, const float *y1, const float *y2, const float *y3, const size_t d, float &dis0, float &dis1, float &dis2, float &dis3)

内积的特殊版本，用于计算x和yi之间的4个距离，以提高性能。

void fvec_L2sqr_batch_4(const float *x, const float *y0, const float *y1, const float *y2, const float *y3, const size_t d, float &dis0, float &dis1, float &dis2, float &dis3)

L2sqr 的特殊版本，用于计算 x 和 yi 之间的 4 个距离，注重性能。

void pairwise_L2sqr(int64_t d, int64_t nq, const float *xq, int64_t nb, const float *xb, float *dis, int64_t ldq = -1, int64_t ldb = -1, int64_t ldd = -1)

计算向量集之间的成对距离

参数：

• d – 向量的维度

• nq – 查询向量的数量

• nb – 数据库向量的数量

• xq – 查询向量 (大小 nq * d)

• xb – 数据库向量 (大小 nb * d)

• dis – 输出距离 (大小 nq * nb)

• ldq, ldb, ldd – 矩阵的步长

void fvec_inner_products_ny(float *ip, const float *x, const float *y, size_t d, size_t ny)

void fvec_L2sqr_ny(float *dis, const float *x, const float *y, size_t d, size_t ny)

void fvec_L2sqr_ny_transposed(float *dis, const float *x, const float *y, const float *y_sqlen, size_t d, size_t d_offset, size_t ny)

size_t fvec_L2sqr_ny_nearest(float *distances_tmp_buffer, const float *x, const float *y, size_t d, size_t ny)

size_t fvec_L2sqr_ny_nearest_y_transposed(float *distances_tmp_buffer, const float *x, const float *y, const float *y_sqlen, size_t d, size_t d_offset, size_t ny)

float fvec_norm_L2sqr(const float *x, size_t d)

向量的平方范数

void fvec_norms_L2(float *norms, const float *x, size_t d, size_t nx)

计算一组向量的 L2 范数

参数：

• norms – 输出范数，大小为 nx

• x – 向量集，大小为 nx * d

void fvec_norms_L2sqr(float *norms, const float *x, size_t d, size_t nx)

与 fvec_norms_L2 相同，但计算的是平方范数

void fvec_renorm_L2(size_t d, size_t nx, float *x)

void inner_product_to_L2sqr(float *dis, const float *nr1, const float *nr2, size_t n1, size_t n2)

void fvec_add(size_t d, const float *a, const float *b, float *c)

计算向量 c := a + b

c 和 a 可以重叠，c 和 b 可以重叠

参数：

• a – 大小为 d

• b – 大小为 d

• c – 大小为 d

void fvec_add(size_t d, const float *a, float b, float *c)

计算 c := a + b，其中 a, c 是向量，b 是标量

c 和 a 可以重叠

参数：

• a – 大小为 d

• c – 大小为 d

void fvec_sub(size_t d, const float *a, const float *b, float *c)

计算向量 c := a - b

c 和 a 可以重叠，c 和 b 可以重叠

参数：

• a – 大小为 d

• b – 大小为 d

• c – 大小为 d

void fvec_inner_products_by_idx(float *ip, const float *x, const float *y, const int64_t *ids, size_t d, size_t nx, size_t ny)

计算 x 与由 ids 定义的 ny 个向量子集 y 之间的内积

ip(i, j) = inner_product(x(i, :), y(ids(i, j), :))

参数：

• ip – 输出数组，大小 nx * ny

• x – 第一项向量，大小 nx * d

• y – 第二项向量，大小 (max(ids) + 1) * d

• ids – 从 y 中采样的 id，大小 nx * ny

void fvec_L2sqr_by_idx(float *dis, const float *x, const float *y, const int64_t *ids, size_t d, size_t nx, size_t ny)

计算 x 与由 ids 定义的 ny 个向量子集 y 之间的平方 L2 距离

dis(i, j) = inner_product(x(i, :), y(ids(i, j), :))

参数：

• dis – 输出数组，大小 nx * ny

• x – 第一项向量，大小 nx * d

• y – 第二项向量，大小 (max(ids) + 1) * d

• ids – 从 y 中采样的 id，大小 nx * ny

void pairwise_indexed_L2sqr(size_t d, size_t n, const float *x, const int64_t *ix, const float *y, const int64_t *iy, float *dis)

计算 dis[j] = L2sqr(x[ix[j]], y[iy[j]]) 对于所有 j=0..n-1

参数：

• x – 大小 (max(ix) + 1, d)

• y – 大小 (max(iy) + 1, d)

• ix – 大小 n

• iy – 大小 n

• dis – 大小 n

void pairwise_indexed_inner_product(size_t d, size_t n, const float *x, const int64_t *ix, const float *y, const int64_t *iy, float *dis)

计算 dis[j] = inner_product(x[ix[j]], y[iy[j]]) 对于所有 j=0..n-1

参数：

• x – 大小 (max(ix) + 1, d)

• y – 大小 (max(iy) + 1, d)

• ix – 大小 n

• iy – 大小 n

• dis – 大小 n

void knn_inner_product(const float *x, const float *y, size_t d, size_t nx, size_t ny, float_minheap_array_t *res, const IDSelector *sel = nullptr)

返回 nx 个向量 x 中每个向量在 ny 个向量 y 中，关于最大内积的 k 个最近邻。

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 ny * d

• res – 结果堆结构，也提供 k。输出时已排序

void knn_inner_product(const float *x, const float *y, size_t d, size_t nx, size_t ny, size_t k, float *distances, int64_t *indexes, const IDSelector *sel = nullptr)

返回 nx 个向量 x 在 ny 个向量 y 中，针对内积度量的 k 个最近邻。

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 ny * d

• distances – 输出距离，大小为 nq * k

• indexes – 输出向量 ID，大小为 nq * k

void knn_L2sqr(const float *x, const float *y, size_t d, size_t nx, size_t ny, float_maxheap_array_t *res, const float *y_norm2 = nullptr, const IDSelector *sel = nullptr)

返回 nx 个向量 x 在 ny 个向量 y 中，针对 L2 距离的 k 个最近邻

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 ny * d

• res – 结果堆结构，也提供 k。输出时已排序

• y_norm2 – (可选) y 向量的范数 (nullptr 或大小为 ny)

• sel – 在向量的这个子集中搜索

void knn_L2sqr(const float *x, const float *y, size_t d, size_t nx, size_t ny, size_t k, float *distances, int64_t *indexes, const float *y_norm2 = nullptr, const IDSelector *sel = nullptr)

返回 nx 个向量 x 在 ny 个向量 y 中，针对 L2 距离的 k 个最近邻

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 ny * d

• distances – 输出距离，大小为 nq * k

• indexes – 输出向量 ID，大小为 nq * k

• y_norm2 – (可选) y 向量的范数 (nullptr 或大小为 ny)

• sel – 在向量的这个子集中搜索

void knn_inner_products_by_idx(const float *x, const float *y, const int64_t *subset, size_t d, size_t nx, size_t ny, size_t nsubset, size_t k, float *vals, int64_t *ids, int64_t ld_ids = -1)

在一组由 ID 索引的 ny 向量中，为 nx 个查询查找最大内积邻居。 可能对重新排序预选向量列表很有用

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 (max(ids) + 1) * d

• ids – 要考虑的数据库向量子集，大小为 (nx, nsubset)

• res – 结果结构

• ld_ids – ids 数组的步长。 -1：使用 nsubset，0：所有查询都处理相同的子集

void knn_L2sqr_by_idx(const float *x, const float *y, const int64_t *subset, size_t d, size_t nx, size_t ny, size_t nsubset, size_t k, float *vals, int64_t *ids, int64_t ld_subset = -1)

查找一组由 IDs 索引的 ny 向量集合中，nx 个查询向量的最近邻。可能对重新排序预选向量列表有用。

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 (max(ids) + 1) * d

• subset – 要考虑的数据库向量子集，大小为 (nx, nsubset)

• res – rIDesult 结构

• ld_subset – 子集数组的步长。-1: 使用 nsubset, 0: 所有查询处理相同的子集

void range_search_L2sqr(const float *x, const float *y, size_t d, size_t nx, size_t ny, float radius, RangeSearchResult *result, const IDSelector *sel = nullptr)

返回 nx 个向量 x 在 ny 个向量 y 中，相对于最大内积的 k 个最近邻。

参数：

• x – 查询向量，大小 nx * d

• y – 数据库向量，大小为 ny * d

• radius – 围绕 x 向量的搜索半径

• result – 结果结构

void range_search_inner_product(const float *x, const float *y, size_t d, size_t nx, size_t ny, float radius, RangeSearchResult *result, const IDSelector *sel = nullptr)

与内积相似性的 range_search_L2sqr 相同

void compute_PQ_dis_tables_dsub2(size_t d, size_t ksub, const float *centroids, size_t nx, const float *x, bool is_inner_product, float *dis_tables)

PQ2 的专用函数

void fvec_madd(size_t n, const float *a, float bf, const float *b, float *c)

计算 c := a + bf * b，对于表 a、b 和 c

参数：

• n – 表的大小

• a – 大小为 n

• b – 大小为 n

• c – 结果表，大小为 n

int fvec_madd_and_argmin(size_t n, const float *a, float bf, const float *b, float *c)

与 fvec_madd 相同，也返回结果表中的最小值的索引

返回值：

表 c 的最小值的索引

bool exhaustive_L2sqr_fused_cmax(const float *x, const float *y, size_t d, size_t nx, size_t ny, Top1BlockResultHandler<CMax<float, int64_t>> &res, const float *y_norms)

template<class Consumer, class ...Types>
Consumer::T dispatch_VectorDistance(size_t d, MetricType metric, float metric_arg, Consumer &consumer, Types... args)

void pairwise_extra_distances(int64_t d, int64_t nq, const float *xq, int64_t nb, const float *xb, MetricType mt, float metric_arg, float *dis, int64_t ldq = -1, int64_t ldb = -1, int64_t ldd = -1)

void knn_extra_metrics(const float *x, const float *y, size_t d, size_t nx, size_t ny, MetricType mt, float metric_arg, size_t k, float *distances, int64_t *indexes)

FlatCodesDistanceComputer *get_extra_distance_computer(size_t d, MetricType mt, float metric_arg, size_t nb, const float *xb)

获取一个 DistanceComputer，它引用了这种距离类型，并索引了一个大小为 nb 的扁平数组。

inline uint16_t encode_fp16(float x)

inline float decode_fp16(uint16_t x)

void bitvec_print(const uint8_t *b, size_t d)

void fvecs2bitvecs(const float *x, uint8_t *b, size_t d, size_t n)

void bitvecs2fvecs(const uint8_t *b, float *x, size_t d, size_t n)

void fvec2bitvec(const float *x, uint8_t *b, size_t d)

void bitvec_shuffle(size_t n, size_t da, size_t db, const int *order, const uint8_t *a, uint8_t *b)

将比特从 b(i, j) := a(i, order[j]) 混洗

void hammings(const uint8_t *a, const uint8_t *b, size_t na, size_t nb, size_t nbytespercode, hamdis_t *dis)

计算 na 和 nb 个二进制向量之间的一组汉明距离

参数：

• a – 大小为 na * nbytespercode

• b – 大小为 nb * nbytespercode

• nbytespercode – 应该是 8 的倍数

• dis – 输出距离，大小为 na * nb

void hammings_knn_hc(int_maxheap_array_t *ha, const uint8_t *a, const uint8_t *b, size_t nb, size_t ncodes, int ordered, ApproxTopK_mode_t approx_topk_mode = ApproxTopK_mode_t::EXACT_TOPK)

返回一组二进制查询向量的 k 个最小汉明距离，使用最大堆。

参数：

• a – 查询，大小为 ha->nh * ncodes

• b – 数据库，大小为 nb * ncodes

• nb – 数据库向量的数量

• ncodes – 二进制代码的大小（字节）

• ordered – 如果 != 0：按递减距离对结果排序（对于 k/n > 0.01 可能是瓶颈）

• approx_topk_mode – 允许使用近似 top-k 功能来加速堆

void hammings_knn(int_maxheap_array_t *ha, const uint8_t *a, const uint8_t *b, size_t nb, size_t ncodes, int ordered)

void hammings_knn_mc(const uint8_t *a, const uint8_t *b, size_t na, size_t nb, size_t k, size_t ncodes, int32_t *distances, int64_t *labels)

返回一组二进制查询向量的 k 个最小汉明距离，使用计数最大值。

参数：

• a – 查询，大小为 na * ncodes

• b – 数据库，大小为 nb * ncodes

• na – 查询向量的数量

• nb – 数据库向量的数量

• k – 要返回的向量/距离的数量

• ncodes – 二进制代码的大小（字节）

• distances – 从每个查询向量到其 k 个最近邻居的输出距离

• labels – 输出每个查询向量的 k 个最近邻居的 ID

void hamming_range_search(const uint8_t *a, const uint8_t *b, size_t na, size_t nb, int radius, size_t ncodes, RangeSearchResult *result)

与 hammings_knn 相同，只是我们在使用半径进行范围搜索

void hamming_count_thres(const uint8_t *bs1, const uint8_t *bs2, size_t n1, size_t n2, hamdis_t ht, size_t ncodes, size_t *nptr)

size_t match_hamming_thres(const uint8_t *bs1, const uint8_t *bs2, size_t n1, size_t n2, hamdis_t ht, size_t ncodes, int64_t *idx, hamdis_t *dis)

void crosshamming_count_thres(const uint8_t *dbs, size_t n, hamdis_t ht, size_t ncodes, size_t *nptr)

inline hamdis_t hamming(const uint64_t *bs1, const uint64_t *bs2, size_t nwords)

void generalized_hammings_knn_hc(int_maxheap_array_t *ha, const uint8_t *a, const uint8_t *b, size_t nb, size_t code_size, int ordered = true)

广义汉明距离（= 相同代码字节数计数）

void pack_bitstrings(size_t n, size_t M, int nbit, const int32_t *unpacked, uint8_t *packed, size_t code_size)

打包一组大小为 M * nbit 的 n 个代码

参数：

• n – 要打包的代码数量

• M – 每个代码的基本代码数量

• nbit – 每个基本代码的比特数

• unpacked – 输入的未打包代码，大小 (n, M)

• packed – 输出的打包代码，大小 (n, code_size)

• code_size – 应该 >= ceil(M * nbit / 8)

void pack_bitstrings(size_t n, size_t M, const int32_t *nbits, const int32_t *unpacked, uint8_t *packed, size_t code_size)

打包一组大小可变的 n 个代码

参数：

nbit – 每个条目的比特数（大小为 M）

void unpack_bitstrings(size_t n, size_t M, int nbit, const uint8_t *packed, size_t code_size, int32_t *unpacked)

解包一组大小为 M * nbit 的 n 个代码

参数：

• n – 要打包的代码数量

• M – 每个代码的基本代码数量

• nbit – 每个基本代码的比特数

• unpacked – 输入的未打包代码，大小 (n, M)

• packed – 输出的打包代码，大小 (n, code_size)

• code_size – 应该 >= ceil(M * nbit / 8)

void unpack_bitstrings(size_t n, size_t M, const int32_t *nbits, const uint8_t *packed, size_t code_size, int32_t *unpacked)

解包一组大小可变的 n 个代码

参数：

nbit – 每个条目的比特数（大小为 M）

template<size_t nbits, typename T>
inline T hamming(const uint8_t *bs1, const uint8_t *bs2)

template<size_t nbits>
inline hamdis_t hamming(const uint64_t *bs1, const uint64_t *bs2)

template<>
inline hamdis_t hamming<64>(const uint64_t *pa, const uint64_t *pb)

template<>
inline hamdis_t hamming<128>(const uint64_t *pa, const uint64_t *pb)

template<>
内联 hamdis_t hamming<256>(const uint64_t *pa, const uint64_t *pb)

内联 int generalized_hamming_64(uint64_t a)

内联 int popcount32(uint32_t x)

内联 int popcount64(uint64_t x)

SPECIALIZED_HC (4)

SPECIALIZED_HC (8)

SPECIALIZED_HC (16)

SPECIALIZED_HC (20)

SPECIALIZED_HC (32)

SPECIALIZED_HC (64)

模板<class Consumer, class ...Types>
Consumer::T dispatch_HammingComputer(int code_size, Consumer &consumer, Types... args)

模板<class C>
内联 void heap_pop(size_t k, typename C::T *bh_val, typename C::TI *bh_ids)

从由 bh_val[0..k-1] 和 bh_ids[0..k-1] 定义的堆中弹出顶部元素。在输出时，k-1 处的元素未定义。

模板<class C>
inline void heap_push(size_t k, typename C::T *bh_val, typename C::TI *bh_ids, typename C::T val, typename C::TI id)

将元素 (val, ids) 推入堆 bh_val[0..k-2] 和 bh_ids[0..k-2]。 输出时，元素位于 k-1。

template<class C>
inline void heap_replace_top(size_t k, typename C::T *bh_val, typename C::TI *bh_ids, typename C::T val, typename C::TI id)

替换由 bh_val[0..k-1] 和 bh_ids[0..k-1] 定义的堆中的顶部元素，并且对于相同的 bh_val[] 值，也按 bh_ids[] 值排序。

template<typename T>
inline void minheap_pop(size_t k, T *bh_val, int64_t *bh_ids)

template<typename T>
inline void minheap_push(size_t k, T *bh_val, int64_t *bh_ids, T val, int64_t ids)

template<typename T>
inline void minheap_replace_top(size_t k, T *bh_val, int64_t *bh_ids, T val, int64_t ids)

template<typename T>
inline void maxheap_pop(size_t k, T *bh_val, int64_t *bh_ids)

template<typename T>
inline void maxheap_push(size_t k, T *bh_val, int64_t *bh_ids, T val, int64_t ids)

template<typename T>
inline void maxheap_replace_top(size_t k, T *bh_val, int64_t *bh_ids, T val, int64_t ids)

template<class C>
inline void heap_pop(size_t k, std::pair<typename C::T, typename C::TI> *bh)

从由 bh_val[0..k-1] 和 bh_ids[0..k-1] 定义的堆中弹出顶部元素。在输出时，k-1 处的元素未定义。

template<class C>
inline void heap_push(size_t k, std::pair<typename C::T, typename C::TI> *bh, typename C::T val, typename C::TI id)

将元素 (val, ids) 推入堆 bh_val[0..k-2] 和 bh_ids[0..k-2]。 输出时，元素位于 k-1。

template<class C>
inline void heap_replace_top(size_t k, std::pair<typename C::T, typename C::TI> *bh, typename C::T val, typename C::TI id)

替换由 bh_val[0..k-1] 和 bh_ids[0..k-1] 定义的堆中的顶部元素，并且对于相同的 bh_val[] 值，也按 bh_ids[] 值排序。

template<class C>
inline void heap_heapify(size_t k, typename C::T *bh_val, typename C::TI *bh_ids, const typename C::T *x = nullptr, const typename C::TI *ids = nullptr, size_t k0 = 0)

template<typename T>
inline void minheap_heapify(size_t k, T *bh_val, int64_t *bh_ids, const T *x = nullptr, const int64_t *ids = nullptr, size_t k0 = 0)

template<typename T>
inline void maxheap_heapify(size_t k, T *bh_val, int64_t *bh_ids, const T *x = nullptr, const int64_t *ids = nullptr, size_t k0 = 0)

template<class C>
inline void heap_addn(size_t k, typename C::T *bh_val, typename C::TI *bh_ids, const typename C::T *x, const typename C::TI *ids, size_t n)

template<typename T>
inline void minheap_addn(size_t k, T *bh_val, int64_t *bh_ids, const T *x, const int64_t *ids, size_t n)

template<typename T>
inline void maxheap_addn(size_t k, T *bh_val, int64_t *bh_ids, const T *x, const int64_t *ids, size_t n)

template<typename C>
inline size_t heap_reorder(size_t k, typename C::T *bh_val, typename C::TI *bh_ids)

template<typename T>
inline size_t minheap_reorder(size_t k, T *bh_val, int64_t *bh_ids)

template<typename T>
inline size_t maxheap_reorder(size_t k, T *bh_val, int64_t *bh_ids)

template<class C>
inline void indirect_heap_pop(size_t k, const typename C::T *bh_val, typename C::TI *bh_ids)

template<class C>
inline void indirect_heap_push(size_t k, const typename C::T *bh_val, typename C::TI *bh_ids, typename C::TI id)

template<class idx_t, class C>
void merge_knn_results(size_t n, size_t k, typename C::TI nshard, const typename C::T *all_distances, const idx_t *all_labels, typename C::T *distances, idx_t *labels)

合并来自多个分片的结果表。假设每个分片的结果都已排序。请注意，C 比较器相对于通常的 top-k 元素堆是反向的，因为我们希望最好的（即 L2 的最低）结果位于顶部，而不是最差的结果。此外，它需要保存分片 ID 的索引（即，通常 int32 足够）。

参数：

• all_distances – 大小 (nshard, n, k)

• all_labels – 大小 (nshard, n, k)

• distances – 输出距离，大小 (n, k)

• labels – 输出标签，大小 (n, k)

template<typename T>
inline T cmin_nextafter(T x)

template<typename T>
inline T cmax_nextafter(T x)

template<>
inline float cmin_nextafter<float>(float x)

template<>
inline float cmax_nextafter<float>(float x)

template<>
inline uint16_t cmin_nextafter<uint16_t>(uint16_t x)

template<>
inline uint16_t cmax_nextafter<uint16_t>(uint16_t x)

template<class C>
C::T partition_fuzzy(typename C::T *vals, typename C::TI *ids, size_t n, size_t q_min, size_t q_max, size_t *q_out)

将表分区为 0:q 和 q:n，其中所有高于 q 的元素都 >= 所有低于 q 的元素（对于 C = CMax，对于 CMin，比较结果相反）

返回分区阈值。元素 q:n 在输出时被销毁。

template<class C>
inline C::T partition(typename C::T *vals, typename C::TI *ids, size_t n, size_t q)

当分区不模糊时使用的简化接口

void simd_histogram_8(const uint16_t *data, int n, uint16_t min, int shift, int *hist)

底层 SIMD 直方图函数 8-bin 直方图，对应于 (x - min) >> shift。范围之外的值会被忽略。数据表应该按照 32 字节对齐。

void simd_histogram_16(const uint16_t *data, int n, uint16_t min, int shift, int *hist)

16-bin 直方图的相同函数

void float_rand(float *x, size_t n, int64_t seed)

void float_randn(float *x, size_t n, int64_t seed)

void int64_rand(int64_t *x, size_t n, int64_t seed)

void byte_rand(uint8_t *x, size_t n, int64_t seed)

void int64_rand_max(int64_t *x, size_t n, uint64_t max, int64_t seed)

void rand_perm(int *perm, size_t n, int64_t seed)

void rand_perm_splitmix64(int *perm, size_t n, int64_t seed)

void rand_smooth_vectors(size_t n, size_t d, float *x, int64_t seed)

inline simd16uint16 min(simd16uint16 a, simd16uint16 b)

inline simd16uint16 max(simd16uint16 a, simd16uint16 b)

inline simd16uint16 combine2x2(simd16uint16 a, simd16uint16 b)

inline uint32_t cmp_ge32(simd16uint16 d0, simd16uint16 d1, simd16uint16 thr)

inline uint32_t cmp_le32(simd16uint16 d0, simd16uint16 d1, simd16uint16 thr)

inline simd16uint16 hadd(const simd16uint16 &a, const simd16uint16 &b)

inline void cmplt_min_max_fast(const simd16uint16 candidateValues, const simd16uint16 candidateIndices, const simd16uint16 currentValues, const simd16uint16 currentIndices, simd16uint16 &minValues, simd16uint16 &minIndices, simd16uint16 &maxValues, simd16uint16 &maxIndices)

inline simd32uint8 uint16_to_uint8_saturate(simd16uint16 a, simd16uint16 b)

inline uint32_t get_MSBs(simd32uint8 a)

获取每个字节的最高有效位

inline simd32uint8 blendv(simd32uint8 a, simd32uint8 b, simd32uint8 mask)

使用mask中每个字节的最高有效位（MSB）在a和b之间选择一个字节。

inline void cmplt_min_max_fast(const simd8uint32 candidateValues, const simd8uint32 candidateIndices, const simd8uint32 currentValues, const simd8uint32 currentIndices, simd8uint32 &minValues, simd8uint32 &minIndices, simd8uint32 &maxValues, simd8uint32 &maxIndices)

inline simd8float32 hadd(simd8float32 a, simd8float32 b)

inline simd8float32 unpacklo(simd8float32 a, simd8float32 b)

inline simd8float32 unpackhi(simd8float32 a, simd8float32 b)

inline simd8float32 fmadd(simd8float32 a, simd8float32 b, simd8float32 c)

inline void cmplt_and_blend_inplace(const simd8float32 candidateValues, const simd8uint32 candidateIndices, simd8float32 &lowestValues, simd8uint32 &lowestIndices)

inline void cmplt_min_max_fast(const simd8float32 candidateValues, const simd8uint32 candidateIndices, const simd8float32 currentValues, const simd8uint32 currentIndices, simd8float32 &minValues, simd8uint32 &minIndices, simd8float32 &maxValues, simd8uint32 &maxIndices)

inline simd16uint16 combine4x2(simd32uint16 a, simd32uint16 b)

内联 simd16uint16 min(const simd16uint16 &av, const simd16uint16 &bv)

inline simd16uint16 max(const simd16uint16 &av, const simd16uint16 &bv)

inline simd16uint16 combine2x2(const simd16uint16 &a, const simd16uint16 &b)

inline uint32_t cmp_ge32(const simd16uint16 &d0, const simd16uint16 &d1, const simd16uint16 &thr)

inline uint32_t cmp_le32(const simd16uint16 &d0, const simd16uint16 &d1, const simd16uint16 &thr)

inline simd32uint8 uint16_to_uint8_saturate(const simd16uint16 &a, const simd16uint16 &b)

inline uint32_t get_MSBs(const simd32uint8 &a)

获取每个字节的最高有效位

inline simd32uint8 blendv(const simd32uint8 &a, const simd32uint8 &b, const simd32uint8 &mask)

使用mask中每个字节的最高有效位（MSB）在a和b之间选择一个字节。

inline simd8float32 hadd(const simd8float32 &a, const simd8float32 &b)

inline simd8float32 unpacklo(const simd8float32 &a, const simd8float32 &b)

inline simd8float32 unpackhi(const simd8float32 &a, const simd8float32 &b)

inline simd8float32 fmadd(const simd8float32 &a, const simd8float32 &b, const simd8float32 &c)

void fvec_argsort(size_t n, const float *vals, size_t *perm)

浮点数组的间接排序

参数：

• n – 数组的大小

• vals – 要排序的数组，大小为 n

• perm – 输出：[0..n-1] 的排列，使得 vals[perm[i + 1]] >= vals[perm[i]]

void fvec_argsort_parallel(size_t n, const float *vals, size_t *perm)

与 fvec_argsort 相同，并行化处理

void bucket_sort(size_t nval, const uint64_t *vals, uint64_t nbucket, int64_t *lims, int64_t *perm, int nt = 0)

对值列表进行桶排序

参数：

• vals – 要排序的值，大小为 nval，最大值为 nbucket - 1

• lims – 桶的输出限制，大小为 nbucket + 1

• perm – 输出桶，桶 i 的元素位于 perm[lims[i]:lims[i + 1]] 中

• nt – 线程数（0 = 纯顺序代码）

void matrix_bucket_sort_inplace(size_t nrow, size_t ncol, int32_t *vals, int32_t nbucket, int64_t *lims, int nt = 0)

原地桶排序（注意内存=>int32），输入值位于 nrow * col 矩阵中，我们希望将行号存储在输出中。

参数：

• vals – 要排序的正值，大小为 nrow * ncol，最大值为 nbucket - 1

• lims – 桶的输出限制，大小为 nbucket + 1

• nt – 线程数（0 = 纯顺序代码）

void matrix_bucket_sort_inplace(size_t nrow, size_t ncol, int64_t *vals, int64_t nbucket, int64_t *lims, int nt = 0)

与 int64 元素相同

void hashtable_int64_to_int64_init(int log2_capacity, int64_t *tab)

用于 int64 -> int64 的哈希表实现，带有外部存储，用于快速批量添加和查找。

tab 的大小为 2 * (1 << log2_capacity)，n 是要添加或搜索的元素数

在同一批次中添加多个值：任意一个被添加到不同的批次中：较新的批次会覆盖旧的批次。如果容量耗尽，则引发异常。

void hashtable_int64_to_int64_add(int log2_capacity, int64_t *tab, size_t n, const int64_t *keys, const int64_t *vals)

void hashtable_int64_to_int64_lookup(int log2_capacity, const int64_t *tab, size_t n, const int64_t *keys, int64_t *vals)

std::string get_compile_options()

获取编译选项

std::string get_version()

double getmillisecs()

自某个任意时间点以来经过的毫秒数

size_t get_mem_usage_kb()

获取当前RSS使用量，单位为kB

uint64_t get_cycles()

void reflection(const float *u, float *x, size_t n, size_t d, size_t nu)

void matrix_qr(int m, int n, float *a)

计算m > n时QR分解的Q

参数：

a – 大小为 n * m：输入矩阵和输出Q

void ranklist_handle_ties(int k, int64_t *idx, const float *dis)

距离应已排序。 对具有相同距离的索引进行排序

size_t ranklist_intersection_size(size_t k1, const int64_t *v1, size_t k2, const int64_t *v2)

计算v1和v2之间的共同元素数量。算法 = 排序 + 二分法，以避免重复计数

size_t merge_result_table_with(size_t n, size_t k, int64_t *I0, float *D0, const int64_t *I1, const float *D1, bool keep_min = true, int64_t translation = 0)

将一个结果表合并到另一个结果表中

参数：

• I0, D0 – 第一个结果表，大小为 (n, k)

• I1, D1 – 第二个结果表，大小为 (n, k)

• keep_min – 如果为true，则保留最小值，否则保留最大值

• translation – 将此值添加到所有 I1 的索引

返回值：

从第二个表获取的值的数量

double imbalance_factor(int n, int k, const int64_t *assign)

平衡的分配的IF值为1

double imbalance_factor(int k, const int *hist)

相同，将直方图作为输入

int ivec_hist(size_t n, const int *v, int vmax, int *hist)

计算v上的直方图

void bincode_hist(size_t n, size_t nbits, const uint8_t *codes, int *hist)

计算代码数组上位的直方图

参数：

• codes – size(n, nbits / 8)

• hist – size(nbits): 代码数组中1的数量

uint64_t ivec_checksum(size_t n, const int32_t *a)

计算表上的校验和。

uint64_t bvec_checksum(size_t n, const uint8_t *a)

计算表上的校验和。

void bvecs_checksum(size_t n, size_t d, const uint8_t *a, uint64_t *cs)

计算矩阵行的校验和

参数：

• n – 行数

• d – 每行的大小

• a – 要处理的矩阵，大小为 n * d

• cs – 输出校验和，大小为 n

const float *fvecs_maybe_subsample(size_t d, size_t *n, size_t nmax, const float *x, bool verbose = false, int64_t seed = 1234)

如果向量数量过多，则随机子采样一组向量

参数：

• d – 向量的维度

• n – 输入时：输入向量的数量，输出时：输出向量的数量

• nmax – 要保留的最大向量数

• x – 输入数组，大小为 *n-by-d

• seed – 用于采样的随机种子

返回值：

x 或使用 new [] 分配的数组，包含 *n 个向量

void binary_to_real(size_t d, const uint8_t *x_in, float *x_out)

将二进制向量转换为 +1/-1 值的浮点向量。

参数：

• d – 向量的维度 (8 的倍数)

• x_in – 输入二进制向量 (大小为 d / 8 的 uint8_t 表)

• x_out – 输出浮点向量 (大小为 d 的 float 表)

void real_to_binary(size_t d, const float *x_in, uint8_t *x_out)

将浮点向量转换为二进制向量。分量 > 0 的转换为 1，其他的转换为 0。

参数：

• d – 向量的维度 (8 的倍数)

• x_in – 输入浮点向量 (大小为 d 的 float 表)

• x_out – 输出二进制向量 (大小为 d / 8 的 uint8_t 表)

uint64_t hash_bytes(const uint8_t *bytes, int64_t n)

一个合理的哈希函数

bool check_openmp()

OpenMP 注释是否被遵守。

变量

FAISS_API HNSWStats hnsw_stats

FAISS_API int product_quantizer_compute_codes_bs

FAISS_API int distance_compute_min_k_reservoir

FAISS_API bool simd_result_handlers_accept_virtual

FAISS_API int index2layer_sa_encode_bs

FAISS_API int index_factory_verbose

设置为 > 0 以从 index_factory 获取更多日志

const int IO_FLAG_SKIP_STORAGE = 1

跳过基于图的索引的存储

const int IO_FLAG_READ_ONLY = 2

const int IO_FLAG_ONDISK_SAME_DIR = 4

const int IO_FLAG_SKIP_IVF_DATA = 8

const int IO_FLAG_SKIP_PRECOMPUTE_TABLE = 16

const int IO_FLAG_PQ_SKIP_SDC_TABLE = 32

const int IO_FLAG_MMAP = IO_FLAG_SKIP_IVF_DATA | 0x646f0000

FAISS_API IndexBinaryHashStats indexBinaryHash_stats

FAISS_API FastScanStats FastScan_stats

FAISS_API bool check_compatible_for_merge_expensive_check

FAISS_API IndexIVFStats indexIVF_stats

FAISS_API IVFFastScanStats IVFFastScan_stats

FAISS_API size_t precomputed_table_max_bytes

FAISS_API int index_ivfpq_add_core_o_bs

FAISS_API IndexIVFPQStats indexIVFPQ_stats

FAISS_API IndexPQStats indexPQ_stats

FAISS_API int multi_index_quantizer_search_bs

FAISS_API int rowwise_minmax_sa_encode_bs

执行 sa_encode 和 sa_decode 的块大小

FAISS_API int rowwise_minmax_sa_decode_bs

FAISS_API int distance_compute_blas_threshold

FAISS_API int distance_compute_blas_query_bs

FAISS_API int distance_compute_blas_database_bs

FAISS_API size_t hamming_batch_size

static constexpr uint8_t hamdis_tab_ham_bytes[256] = {0, 1, 1, 2, 1, 2, 2, 3, 1, 2, 2, 3, 2, 3, 3, 4, 1, 2, 2, 3, 2, 3, 3, 4, 2, 3, 3, 4, 3, 4, 4, 5, 1, 2, 2, 3, 2, 3, 3, 4, 2, 3, 3, 4, 3, 4, 4, 5, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 1, 2, 2, 3, 2, 3, 3, 4, 2, 3, 3, 4, 3, 4, 4, 5, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 3, 4, 4, 5, 4, 5, 5, 6, 4, 5, 5, 6, 5, 6, 6, 7, 1, 2, 2, 3, 2, 3, 3, 4, 2, 3, 3, 4, 3, 4, 4, 5, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 3, 4, 4, 5, 4, 5, 5, 6, 4, 5, 5, 6, 5, 6, 6, 7, 2, 3, 3, 4, 3, 4, 4, 5, 3, 4, 4, 5, 4, 5, 5, 6, 3, 4, 4, 5, 4, 5, 5, 6, 4, 5, 5, 6, 5, 6, 6, 7, 3, 4, 4, 5, 4, 5, 5, 6, 4, 5, 5, 6, 5, 6, 6, 7, 4, 5, 5, 6, 5, 6, 6, 7, 5, 6, 6, 7, 6, 7, 7, 8}

FAISS_API PartitionStats partition_stats

FAISS_API int bucket_sort_verbose

增加 bucket_sort 函数的详细程度

struct AutoTuneCriterion

#include <AutoTune.h>

评估标准。 返回[0,1]之间的性能度量，值越高越好。

被 faiss::IntersectionCriterion, faiss::OneRecallAtRCriterion 继承

公共函数

AutoTuneCriterion(idx_t nq, idx_t nnn)

void set_groundtruth(int gt_nnn, const float *gt_D_in, const idx_t *gt_I_in)

初始化 gt_D 和 gt_I 向量。 必须在评估之前调用

参数：

• gt_D_in – 大小 nq * gt_nnn

• gt_I_in – 大小 nq * gt_nnn

virtual double evaluate(const float *D, const idx_t *I) const = 0

评估标准。

参数：

• D – 大小 nq * nnn

• I – 大小 nq * nnn

返回值：

该标准，介于 0 和 1 之间。越大越好。

inline virtual ~AutoTuneCriterion()

公共成员

idx_t nq

此标准评估的查询数

idx_t nnn

查询应请求的 NN 数

idx_t gt_nnn

评估标准所需的 GT NN 数

std::vector<float> gt_D

基本真值距离（大小 nq * gt_nnn）

std::vector<idx_t> gt_I

基本真值索引（大小 nq * gt_nnn）

struct OneRecallAtRCriterion : public faiss::AutoTuneCriterion

公共函数

OneRecallAtRCriterion(idx_t nq, idx_t R)

virtual double evaluate(const float *D, const idx_t *I) const override

评估标准。

参数：

• D – 大小 nq * nnn

• I – 大小 nq * nnn

返回值：

该标准，介于 0 和 1 之间。越大越好。

inline ~OneRecallAtRCriterion() override

设置基准真值。

初始化 gt_D 和 gt_I 向量。 必须在评估之前调用

参数：

• gt_D_in – 大小 nq * gt_nnn

• gt_I_in – 大小 nq * gt_nnn

公共成员

召回率计算中考虑的最近邻数量。

查询的数量。

此标准评估的查询数

索引返回的最近邻数量。

查询应请求的 NN 数

基准真值中的最近邻数量。

评估标准所需的 GT NN 数

基准真值距离。

基本真值距离（大小 nq * gt_nnn）

基准真值索引。

基本真值索引（大小 nq * gt_nnn）

用于评估两个结果列表交集的标准。

公共函数

构造函数。

评估给定结果的交集。

评估标准。

参数：

• D – 大小 nq * nnn

• I – 大小 nq * nnn

返回值：

该标准，介于 0 和 1 之间。越大越好。

析构函数。

设置基准真值。

初始化 gt_D 和 gt_I 向量。 必须在评估之前调用

参数：

• gt_D_in – 大小 nq * gt_nnn

• gt_I_in – 大小 nq * gt_nnn

公共成员

考虑交集中的最近邻数量。

查询的数量。

此标准评估的查询数

索引返回的最近邻数量。

查询应请求的 NN 数

基准真值中的最近邻数量。

评估标准所需的 GT NN 数

基准真值距离。

基本真值距离（大小 nq * gt_nnn）

基准真值索引。

基本真值索引（大小 nq * gt_nnn）

操作点。

#include <AutoTune.h>

维护实验结果列表。每个操作点都是一个 (perf, t, key) 三元组，其中 perf 越高，t 越低越好。key 字段是操作点的任意标识符。

包括在 (perf, t) 空间中提取 Pareto 最优操作点的原语。

公共成员

double perf

性能指标（Criterion 的输出）。

double t

相应的执行时间（毫秒）。

std::string key

标识此操作点的键。

int64_t cno

整数标识符。

操作点集合。

公共函数

构造函数。

int merge_with(const OperatingPoints &other, const std::string &prefix = "")

将其他操作点添加到此操作点，并在键上添加前缀

void clear()

bool add(double perf, double t, const std::string &key, size_t cno = 0)

添加性能指标。返回它是否是一个最佳点

double t_for_perf(double perf) const

获取获得给定性能指标所需的时间

void display(bool only_optimal = true) const

易于阅读的输出

void all_to_gnuplot(const char *fname) const

输出为易于gnuplot解析的格式

void optimal_to_gnuplot(const char *fname) const

公共成员

std::vector<OperatingPoint> all_pts

所有操作点

std::vector<OperatingPoint> optimal_pts

最佳操作点，按性能排序

struct ParameterRange

#include <AutoTune.h>

参数的可能值，从最小/最不准确到最大/最准确排序

公共成员

std::string name

std::vector<double> values

struct ParameterSpace

#include <AutoTune.h>

使用关于 Faiss 索引的先验知识来提取可调参数。

由 faiss::gpu::GpuParameterSpace 子类化

公共函数

ParameterSpace()

size_t n_combinations() const

组合数，= 值大小的乘积

bool combination_ge(size_t c1, size_t c2) const

返回元组意义上组合 c1 >= c2 是否成立

std::string combination_name(size_t cno) const

获取组合的字符串表示形式

void display() const

在 stdout 上打印描述

ParameterRange &add_range(const std::string &name)

添加新参数（如果存在，则返回它）

virtual void initialize(const Index *index)

使用索引的合理参数进行初始化

void set_index_parameters(Index *index, size_t cno) const

在索引上设置参数组合

void set_index_parameters(Index *index, const char *param_string) const

设置由字符串描述的参数组合

virtual void set_index_parameter(Index *index, const std::string &name, double val) const

设置一个参数，返回设置是否成功

void update_bounds(size_t cno, const OperatingPoint &op, double *upper_bound_perf, double *lower_bound_t) const

对于给定的另一个操作点op，找到配置cno的性能上限和t的下限

void explore(Index *index, size_t nq, const float *xq, const AutoTuneCriterion &crit, OperatingPoints *ops) const

探索操作点

参数：

• index – 要运行的索引

• xq – 查询向量 (大小 nq * index.d)

• crit – 选择标准

• ops – 结果操作点

inline virtual ~ParameterSpace()

公共成员

std::vector<ParameterRange> parameter_ranges

所有可调参数

int verbose

探索期间的详细程度

int n_experiments

优化期间的实验次数 (0 = 尝试所有组合)

size_t batchsize

一次提交的最大查询数。

bool thread_over_batches

在批处理中使用多线程（用于基准测试独立的单次搜索很有用）

double min_test_duration

多次运行测试，直到它们至少达到此持续时间（以避免 MT 模式下的抖动）

struct Cloner

#include <clone_index.h>

Cloner 类，可用于使用其他克隆函数覆盖类。 上面的克隆函数只调用 Cloner::clone_Index。

子类为 faiss::gpu::ToCPUCloner, faiss::gpu::ToGpuCloner, faiss::gpu::ToGpuClonerMultiple

公共函数

virtual VectorTransform *clone_VectorTransform(const VectorTransform*)

virtual Index *clone_Index(const Index*)

virtual IndexIVF *clone_IndexIVF(const IndexIVF*)

inline virtual ~Cloner()

struct ClusteringParameters

#include <Clustering.h>

聚类参数类。 可以传递给 Clustering 对象的构造函数。

被 faiss::Clustering, faiss::ProgressiveDimClusteringParameters 继承

公共成员

int niter = 25

聚类迭代的次数

int nredo = 1

重新聚类这么多次，并保留目标函数最好的聚类结果

bool verbose = false

bool spherical = false

是否在每次迭代后对质心进行归一化（对于内积聚类有用）

bool int_centroids = false

每次迭代后，是否将质心坐标四舍五入为整数？

bool update_index = false

每次迭代后重新训练索引？

bool frozen_centroids = false

使用作为输入提供的质心的子集，并且在迭代过程中不更改它们

int min_points_per_centroid = 39

如果每个质心提供的训练向量少于此数量，则会写入警告。 请注意，每个质心少于 1 个点会引发异常。

int max_points_per_centroid = 256

限制数据集的大小，否则训练集会被二次采样

int seed = 1234

随机数生成器的种子。 负值会导致使用 std::high_resolution_clock 播种内部 rng。

size_t decode_block_size = 32768

当训练集被编码时，编解码器解码器的批量大小

bool check_input_data_for_NaNs = true

是否检查输入数据中的 NaN

bool use_faster_subsampling = false

是否对子抽样使用基于 splitmix64 的随机数生成器，该生成器速度更快，但可能会选择重复点。

struct ClusteringIterationStats

公共成员

float obj

目标值（索引报告的距离之和）

double time

迭代的秒数

double time_search

仅用于搜索的秒数

double imbalance_factor

迭代的不平衡因子

int nsplit

集群拆分的数量

struct Clustering : public faiss::ClusteringParameters

#include <Clustering.h>

基于分配的 K-means 聚类 - 质心更新迭代

聚类基于 Index 对象，该对象将训练点分配给质心。 因此，在每次迭代中，质心都会添加到索引中。

在输出时，质心表设置为最新版本的质心，并且它们也会添加到索引中。 如果质心表在输入时非空，则也将其用于初始化。

被 faiss::Clustering1D 继承

公共函数

Clustering(int d, int k)

Clustering(int d, int k, const ClusteringParameters &cp)

virtual void train(idx_t n, const float *x, faiss::Index &index, const float *x_weights = nullptr)

运行 k 均值训练

参数：

• x – 训练向量，大小为 n * d

• index – 用于分配的索引

• x_weights – 与每个向量关联的权重：NULL 或大小为 n

void train_encoded(idx_t nx, const uint8_t *x_in, const Index *codec, Index &index, const float *weights = nullptr)

使用编码向量运行

除了 train() 的参数之外，win 还需要一个编解码器作为参数来解码输入向量。

参数：

codec – 用于解码向量的编解码器（nullptr = 向量实际上是浮点数）

void post_process_centroids()

在每次质心更新后对质心进行后处理。 包括可选的 L2 归一化和最近整数舍入

inline virtual ~Clustering()

公共成员

size_t d

向量的维度

size_t k

质心的数量

std::vector<float> centroids

质心 (k * d) 如果在训练的输入上设置了质心，它们将用作初始化

std::vector<ClusteringIterationStats> iteration_stats

聚类的每次迭代的统计信息

int niter = 25

聚类迭代的次数

int nredo = 1

重新聚类这么多次，并保留目标函数最好的聚类结果

bool verbose = false

bool spherical = false

是否在每次迭代后对质心进行归一化（对于内积聚类有用）

bool int_centroids = false

每次迭代后，是否将质心坐标四舍五入为整数？

bool update_index = false

每次迭代后重新训练索引？

bool frozen_centroids = false

使用作为输入提供的质心的子集，并且在迭代过程中不更改它们

int min_points_per_centroid = 39

如果每个质心提供的训练向量少于此数量，则会写入警告。 请注意，每个质心少于 1 个点会引发异常。

int max_points_per_centroid = 256

限制数据集的大小，否则训练集会被二次采样

int seed = 1234

随机数生成器的种子。 负值会导致使用 std::high_resolution_clock 播种内部 rng。

size_t decode_block_size = 32768

当训练集被编码时，编解码器解码器的批量大小

bool check_input_data_for_NaNs = true

是否检查输入数据中的 NaN

bool use_faster_subsampling = false

是否对子抽样使用基于 splitmix64 的随机数生成器，该生成器速度更快，但可能会选择重复点。

struct Clustering1D : public faiss::Clustering

#include <Clustering.h>

精确的一维聚类算法

因为它不使用索引，所以它不重载 train() 函数

公共函数

explicit Clustering1D(int k)

Clustering1D(int k, const ClusteringParameters &cp)

void train_exact(idx_t n, const float *x)

inline virtual ~Clustering1D()

virtual void train(idx_t n, const float *x, faiss::Index &index, const float *x_weights = nullptr)

运行 k 均值训练

参数：

• x – 训练向量，大小为 n * d

• index – 用于分配的索引

• x_weights – 与每个向量关联的权重：NULL 或大小为 n

void train_encoded(idx_t nx, const uint8_t *x_in, const Index *codec, Index &index, const float *weights = nullptr)

使用编码向量运行

除了 train() 的参数之外，win 还需要一个编解码器作为参数来解码输入向量。

参数：

codec – 用于解码向量的编解码器（nullptr = 向量实际上是浮点数）

void post_process_centroids()

在每次质心更新后对质心进行后处理。 包括可选的 L2 归一化和最近整数舍入

公共成员

size_t d

向量的维度

size_t k

质心的数量

std::vector<float> centroids

质心 (k * d) 如果在训练的输入上设置了质心，它们将用作初始化

std::vector<ClusteringIterationStats> iteration_stats

聚类的每次迭代的统计信息

int niter = 25

聚类迭代的次数

int nredo = 1

重新聚类这么多次，并保留目标函数最好的聚类结果

bool verbose = false

bool spherical = false

是否在每次迭代后对质心进行归一化（对于内积聚类有用）

bool int_centroids = false

每次迭代后，是否将质心坐标四舍五入为整数？

bool update_index = false

每次迭代后重新训练索引？

bool frozen_centroids = false

使用作为输入提供的质心的子集，并且在迭代过程中不更改它们

int min_points_per_centroid = 39

如果每个质心提供的训练向量少于此数量，则会写入警告。 请注意，每个质心少于 1 个点会引发异常。

int max_points_per_centroid = 256

限制数据集的大小，否则训练集会被二次采样

int seed = 1234

随机数生成器的种子。 负值会导致使用 std::high_resolution_clock 播种内部 rng。

size_t decode_block_size = 32768

当训练集被编码时，编解码器解码器的批量大小

bool check_input_data_for_NaNs = true

是否检查输入数据中的 NaN

bool use_faster_subsampling = false

是否对子抽样使用基于 splitmix64 的随机数生成器，该生成器速度更快，但可能会选择重复点。

struct ProgressiveDimClusteringParameters : public faiss::ClusteringParameters

继承自 faiss::ProgressiveDimClustering

公共函数

ProgressiveDimClusteringParameters()

公共成员

int progressive_dim_steps

增量步骤的数量

bool apply_pca

对输入应用PCA

int niter = 25

聚类迭代的次数

int nredo = 1

重新聚类这么多次，并保留目标函数最好的聚类结果

bool verbose = false

bool spherical = false

是否在每次迭代后对质心进行归一化（对于内积聚类有用）

bool int_centroids = false

每次迭代后，是否将质心坐标四舍五入为整数？

bool update_index = false

每次迭代后重新训练索引？

bool frozen_centroids = false

使用作为输入提供的质心的子集，并且在迭代过程中不更改它们

int min_points_per_centroid = 39

如果每个质心提供的训练向量少于此数量，则会写入警告。 请注意，每个质心少于 1 个点会引发异常。

int max_points_per_centroid = 256

限制数据集的大小，否则训练集会被二次采样

int seed = 1234

随机数生成器的种子。 负值会导致使用 std::high_resolution_clock 播种内部 rng。

size_t decode_block_size = 32768

当训练集被编码时，编解码器解码器的批量大小

bool check_input_data_for_NaNs = true

是否检查输入数据中的 NaN

bool use_faster_subsampling = false

是否对子抽样使用基于 splitmix64 的随机数生成器，该生成器速度更快，但可能会选择重复点。

struct ProgressiveDimIndexFactory

#include <Clustering.h>

调用时生成适合聚类的索引。

被 faiss::gpu::GpuProgressiveDimIndexFactory 继承

公共函数

virtual Index *operator()(int dim)

所有权转移给调用者

inline virtual ~ProgressiveDimIndexFactory()

struct ProgressiveDimClustering : public faiss::ProgressiveDimClusteringParameters

#include <Clustering.h>

使用渐进维度的 K-means 聚类

聚类首先在维度 1 中发生，然后以指数方式增加维度直到 d（I 步）。 这通常在 PCA 转换（可选）之后应用。 参考

“改进的用于高维近似的残差向量量化

最近邻搜索”

Shicong Liu, Hongtao Lu, Junru Shao, AAAI’15

https://arxiv.org/abs/1509.05195

公共函数

ProgressiveDimClustering(int d, int k)

ProgressiveDimClustering(int d, int k, const ProgressiveDimClusteringParameters &cp)

void train(idx_t n, const float *x, ProgressiveDimIndexFactory &factory)

inline virtual ~ProgressiveDimClustering()

公共成员

size_t d

向量的维度

size_t k

质心的数量

std::vector<float> centroids

质心 (k * d)

std::vector<ClusteringIterationStats> iteration_stats

聚类的每次迭代的统计信息

int progressive_dim_steps

增量步骤的数量

bool apply_pca

对输入应用PCA

int niter = 25

聚类迭代的次数

int nredo = 1

重新聚类这么多次，并保留目标函数最好的聚类结果

bool verbose = false

bool spherical = false

是否在每次迭代后对质心进行归一化（对于内积聚类有用）

bool int_centroids = false

每次迭代后，是否将质心坐标四舍五入为整数？

bool update_index = false

每次迭代后重新训练索引？

bool frozen_centroids = false

使用作为输入提供的质心的子集，并且在迭代过程中不更改它们

int min_points_per_centroid = 39

如果每个质心提供的训练向量少于此数量，则会写入警告。 请注意，每个质心少于 1 个点会引发异常。

int max_points_per_centroid = 256

限制数据集的大小，否则训练集会被二次采样

int seed = 1234

随机数生成器的种子。 负值会导致使用 std::high_resolution_clock 播种内部 rng。

size_t decode_block_size = 32768

当训练集被编码时，编解码器解码器的批量大小

bool check_input_data_for_NaNs = true

是否检查输入数据中的 NaN

bool use_faster_subsampling = false

是否对子抽样使用基于 splitmix64 的随机数生成器，该生成器速度更快，但可能会选择重复点。

struct AdditiveQuantizer : public faiss::Quantizer

#include <AdditiveQuantizer.h>

加性量化器的抽象结构

与乘积量化器不同，乘积量化器中解码后的向量是 M 个子向量的串联，加性量化器将 M 个子向量相加得到解码后的向量。

由 faiss::LocalSearchQuantizer, faiss::ProductAdditiveQuantizer, faiss::ResidualQuantizer 继承

公共类型

enum Search_type_t

编码搜索的执行方式和向量的编码方式。

值

enumerator ST_decompress

解压缩数据库向量

enumerator ST_LUT_nonorm

使用 LUT，不包含范数（适用于 IP 或归一化向量）

enumerator ST_norm_from_LUT

从查找表计算范数（成本为 O(M^2)）

enumerator ST_norm_float

使用 LUT，并将 float32 范数与向量一起存储

enumerator ST_norm_qint8

使用 LUT，并存储 8bit 量化范数

enumerator ST_norm_qint4

enumerator ST_norm_cqint8

使用 LUT，并存储非均匀量化范数

enumerator ST_norm_cqint4

enumerator ST_norm_lsq2x4

使用 2x4 位 lsq 作为范数量化器（用于快速扫描）

enumerator ST_norm_rq2x4

使用 2x4 位 rq 作为范数量化器（用于快速扫描）

公共函数

void compute_codebook_tables()

uint64_t encode_norm(float norm) const

将范数编码为 norm_bits 位

uint32_t encode_qcint(float x) const

通过非均匀标量量化编码范数

float decode_qcint(uint32_t c) const

通过非均匀标量量化解码范数

AdditiveQuantizer(size_t d, const std::vector<size_t> &nbits, Search_type_t search_type = ST_decompress)

AdditiveQuantizer()

当 d、M 和 nbits 被设置后，计算派生值

void set_derived_values()

训练范数量化器。

void train_norm(size_t n, const float *norms)

inline virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

virtual void compute_codes_add_centroids(const float *x, uint8_t *codes, size_t n, const float *centroids = nullptr) const = 0

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

• centroids – 要添加到 x 的质心，大小为 n * d

void pack_codes(size_t n, const int32_t *codes, uint8_t *packed_codes, int64_t ld_codes = -1, const float *norms = nullptr, const float *centroids = nullptr) const

将一系列代码打包为位紧凑格式

参数：

• codes – 要打包的代码，大小为 n * code_size

• packed_codes – 输出位紧凑代码

• ld_codes – 代码的前导维度

• norms – 向量的范数（大小为 n）。如果需要但未提供，将会被计算

• centroids – 要添加到 x 的质心，大小为 n * d

virtual void decode(const uint8_t *codes, float *x, size_t n) const override

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

virtual void decode_unpacked(const int32_t *codes, float *x, size_t n, int64_t ld_codes = -1) const

解码一组非打包格式的向量

参数：

• codes – 要解码的代码，大小为 n * ld_codes

• x – 输出向量，大小为 n * d

template<bool is_IP, Search_type_t effective_search_type>
float compute_1_distance_LUT(const uint8_t *codes, const float *LUT) const

void decode_64bit(idx_t n, float *x) const

用于解码 64 位字中代码的函数

virtual void compute_LUT(size_t n, const float *xq, float *LUT, float alpha = 1.0f, long ld_lut = -1) const

计算内积查找表。在质心搜索函数中使用。

参数：

• xq – 查询向量，大小 (n, d)

• LUT – 查找表，大小 (n, total_codebook_size)

• alpha – 计算 alpha * 内积

• ld_lut – LUT 的前导维度

void knn_centroids_inner_product(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels) const

精确 IP 搜索

void compute_centroid_norms(float *norms) const

对于 L2 搜索，我们需要质心的 L2 范数

参数：

norms – 输出范数表，大小 total_codebook_size

void knn_centroids_L2(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels, const float *centroid_norms) const

精确 L2 搜索，使用预先计算的范数

virtual ~AdditiveQuantizer()

virtual void train(size_t n, const float *x) = 0

训练量化器

参数：

x – 训练向量，大小为 n * d

公共成员

size_t M

码本数量

std::vector<size_t> nbits

每一步的比特数

std::vector<float> codebooks

码本

std::vector<uint64_t> codebook_offsets

码本 #i 存储在码本表 codebooks 的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size x d

size_t tot_bits = 0

总比特数 (索引 + 范数)

size_t norm_bits = 0

为范数分配的比特数

size_t total_codebook_size = 0

码本的大小 (向量个数)

bool only_8bit = false

是否所有 nbits = 8 (使用更快的解码器)

bool verbose = false

训练期间是否输出详细信息？

bool is_trained = false

是否已训练

std::vector<float> norm_tabs

ST_norm_lsq2x4 和 ST_norm_rq2x4 的辅助数据，存储 4 位 fastscan 的码本条目的范数

IndexFlat1D qnorm

存储和搜索范数

std::vector<float> centroid_norms

所有码本条目的范数（大小为 total_codebook_size）

std::vector<float> codebook_cross_products

所有码本条目与之前码本的点积，大小为 sum(codebook_offsets[m] * 2^nbits[m], m=0..M-1)

size_t max_mem_distances = 5 * (size_t(1) << 30)

范数和距离矩阵与波束搜索可能会变得很大，因此使用此项来控制可以分配的内存量

Search_type_t search_type

也决定了代码中的内容。

float norm_min = NAN

范数量化的最小值/最大值

float norm_max = NAN

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct RangeSearchResult

#include <AuxIndexStructures.h>

目的是拥有一个简单的结果结构，同时最大限度地减少结果中的内存复制数量。可以重载方法 do_allocation 以在脚本语言（如 Lua 或 Python）的矩阵类型中分配结果表。

公共函数

explicit RangeSearchResult(size_t nq, bool alloc_lims = true)

lims 必须在输入到 range_search 时进行分配。

virtual void do_allocation()

当 lims 包含每个查询的结果条目数时调用

virtual ~RangeSearchResult()

公共成员

size_t nq

查询数量

size_t *lims

大小 (nq + 1)

idx_t *labels

查询 i 的结果是 labels[lims[i]:lims[i+1]]

float *distances

相应的距离（未排序）

size_t buffer_size

使用的结果缓冲区的大小

struct BufferList

#include <AuxIndexStructures.h>

用于在复制到 RangeSearchResult 对象之前存储结果的临时缓冲区列表。

由 faiss::RangeSearchPartialResult 子类化

公共函数

explicit BufferList(size_t buffer_size)

~BufferList()

void append_buffer()

创建一个新缓冲区

void add(idx_t id, float dis)

添加一个结果，如果需要，可能会附加一个新的缓冲区

void copy_range(size_t ofs, size_t n, idx_t *dest_ids, float *dest_dis)

将缓冲区中视为线性数据的偏移量ofs:ofs+n-1的元素复制到表dest_ids, dest_dis中

公共成员

size_t buffer_size

std::vector<Buffer> buffers

size_t wp

最后一个缓冲区中的写指针。

struct Buffer

公共成员

idx_t *ids

float *dis

struct RangeQueryResult

#include <AuxIndexStructures.h>

单个查询的结果结构

公共函数

void add(float dis, idx_t id)

由搜索函数调用以报告新结果

公共成员

idx_t qno

size_t nres

RangeSearchPartialResult *pres

struct RangeSearchPartialResult : public faiss::BufferList

#include <AuxIndexStructures.h>

缓冲区中的条目按查询拆分

公共函数

explicit RangeSearchPartialResult(RangeSearchResult *res_in)

最终结果将存储在 res_in 中

RangeQueryResult &new_result(idx_t qno)

开始新的结果

void finalize()

void set_lims()

在 do_allocation 之前由 range_search 调用

void copy_result(bool incremental = false)

在 do_allocation 之后由 range_search 调用

void append_buffer()

创建一个新缓冲区

void add(idx_t id, float dis)

添加一个结果，如果需要，可能会附加一个新的缓冲区

void copy_range(size_t ofs, size_t n, idx_t *dest_ids, float *dest_dis)

将缓冲区中视为线性数据的偏移量ofs:ofs+n-1的元素复制到表dest_ids, dest_dis中

公共成员

RangeSearchResult *res

std::vector<RangeQueryResult> queries

每个查询的查询 ID + 结果数量。

size_t buffer_size

std::vector<Buffer> buffers

size_t wp

最后一个缓冲区中的写指针。

公共静态函数

static void merge(std::vector<RangeSearchPartialResult*> &partial_results, bool do_delete = true)

将一组 PartialResult 合并为一个 RangeSearchResult。输出时，partialresults 为空！

struct InterruptCallback

由 faiss::TimeoutCallback 继承

公共函数

virtual bool want_interrupt() = 0

inline virtual ~InterruptCallback()

公共静态函数

static void clear_instance()

static void check()

检查

• 是否设置了中断回调

• 如果是，则回调返回 true，然后抛出异常。不应从多个线程调用。

static bool is_interrupted()

与 check() 相同，但如果发生中断则返回 true，而不是抛出异常。可以从多个线程调用。

static size_t get_period_hint(size_t flops)

假设每次迭代都需要一定数量的 flops，那么检查中断的合理间隔是多少？

公共静态属性

static std::mutex lock

static std::unique_ptr<InterruptCallback> instance

struct TimeoutCallback : public faiss::InterruptCallback

公共函数

virtual bool want_interrupt() override

void set_timeout(double timeout_in_seconds)

公共成员

std::chrono::time_point<std::chrono::steady_clock> start

double timeout

公共静态函数

static void reset(double timeout_in_seconds)

static void clear_instance()

static void check()

检查

• 是否设置了中断回调

• 如果是，则回调返回 true，然后抛出异常。不应从多个线程调用。

static bool is_interrupted()

与 check() 相同，但如果发生中断则返回 true，而不是抛出异常。可以从多个线程调用。

static size_t get_period_hint(size_t flops)

假设每次迭代都需要一定数量的 flops，那么检查中断的合理间隔是多少？

公共静态属性

static std::mutex lock

static std::unique_ptr<InterruptCallback> instance

struct VisitedTable

#include <AuxIndexStructures.h>

set implementation optimized for fast access.

公共函数

inline explicit VisitedTable(int size)

inline void set(int no)

set flag #no to true

inline bool get(int no) const

get flag #no

inline void advance()

reset all flags to false

公共成员

std::vector<uint8_t> visited

uint8_t visno

struct CodePacker

#include <CodePacker.h>

Packing consists in combining a fixed number of codes of constant size (code_size) into a block of data where they may (or may not) be interleaved for efficient consumption by distance computation kernels. This exists for the “fast_scan” indexes on CPU and for some GPU kernels.

Subclassed by faiss::CodePackerFlat, faiss::CodePackerPQ4

公共函数

virtual void pack_1(const uint8_t *flat_code, size_t offset, uint8_t *block) const = 0

virtual void unpack_1(const uint8_t *block, size_t offset, uint8_t *flat_code) const = 0

virtual void pack_all(const uint8_t *flat_codes, uint8_t *block) const

virtual void unpack_all(const uint8_t *block, uint8_t *flat_codes) const

inline virtual ~CodePacker()

公共成员

size_t code_size

size_t nvec

size_t block_size

struct CodePackerFlat : public faiss::CodePacker

#include <CodePacker.h>

Trivial code packer where codes are stored one by one

公共函数

explicit CodePackerFlat(size_t code_size)

virtual void pack_1(const uint8_t *flat_code, size_t offset, uint8_t *block) const final

virtual void unpack_1(const uint8_t *block, size_t offset, uint8_t *flat_code) const final

virtual void pack_all(const uint8_t *flat_codes, uint8_t *block) const final

virtual void unpack_all(const uint8_t *block, uint8_t *flat_codes) const final

公共成员

size_t code_size

size_t nvec

size_t block_size

struct DistanceComputer

被 faiss::FlatCodesDistanceComputer, faiss::NegativeDistanceComputer 继承

公共函数

virtual void set_query(const float *x) = 0

在计算距离之前被调用。 指针 x 在 operator () 被调用时应该保持有效。

virtual float operator()(idx_t i) = 0

计算向量 i 到当前查询的距离

inline virtual void distances_batch_4(const idx_t idx0, const idx_t idx1, const idx_t idx2, const idx_t idx3, float &dis0, float &dis1, float &dis2, float &dis3)

计算当前查询到 4 个存储向量的距离。 某些 DistanceComputer 实现可能极大地受益于此。

virtual float symmetric_dis(idx_t i, idx_t j) = 0

计算两个存储向量之间的距离

inline virtual ~DistanceComputer()

struct NegativeDistanceComputer : public faiss::DistanceComputer

公共函数

inline explicit NegativeDistanceComputer(DistanceComputer *basedis)

inline virtual void set_query(const float *x) override

在计算距离之前被调用。 指针 x 在 operator () 被调用时应该保持有效。

inline virtual float operator()(idx_t i) override

计算向量 i 到当前查询的距离

inline virtual void distances_batch_4(const idx_t idx0, const idx_t idx1, const idx_t idx2, const idx_t idx3, float &dis0, float &dis1, float &dis2, float &dis3) override

计算当前查询到 4 个存储向量的距离。 某些 DistanceComputer 实现可能极大地受益于此。

inline virtual float symmetric_dis(idx_t i, idx_t j) override

计算两个存储向量之间的距离

inline virtual ~NegativeDistanceComputer()

公共成员

DistanceComputer *basedis

owned by this

struct FlatCodesDistanceComputer : public faiss::DistanceComputer

Subclassed by faiss::ScalarQuantizer::SQDistanceComputer

公共函数

inline FlatCodesDistanceComputer(const uint8_t *codes, size_t code_size)

inline FlatCodesDistanceComputer()

inline virtual float operator()(idx_t i) override

计算向量 i 到当前查询的距离

virtual float distance_to_code(const uint8_t *code) = 0

compute distance of current query to an encoded vector

inline virtual ~FlatCodesDistanceComputer()

virtual void set_query(const float *x) = 0

在计算距离之前被调用。 指针 x 在 operator () 被调用时应该保持有效。

inline virtual void distances_batch_4(const idx_t idx0, const idx_t idx1, const idx_t idx2, const idx_t idx3, float &dis0, float &dis1, float &dis2, float &dis3)

计算当前查询到 4 个存储向量的距离。 某些 DistanceComputer 实现可能极大地受益于此。

virtual float symmetric_dis(idx_t i, idx_t j) = 0

计算两个存储向量之间的距离

公共成员

const uint8_t *codes

size_t code_size

class FaissException : public std::exception

#include <FaissException.h>

Faiss 异常的基类。

公共函数

explicit FaissException(const std::string &msg)

FaissException(const std::string &msg, const char *funcName, const char *file, int line)

const char *what() const noexcept override

来自 std::exception

公共成员

std::string msg

struct TransformedVectors

#include <FaissException.h>

用于一组可能已转换向量的 RAII 对象（仅在它们确实被转换时才会被释放）

公共函数

inline TransformedVectors(const float *x_orig, const float *x)

inline ~TransformedVectors()

公共成员

const float *x

bool own_x

template<class C>
struct ResultHandler

被 faiss::HeapBlockResultHandler< C, use_sel >::SingleResultHandler, faiss::RangeSearchBlockResultHandler< C, use_sel >::SingleResultHandler, faiss::ReservoirTopN< C >, faiss::Top1BlockResultHandler< C, use_sel >::SingleResultHandler 继承

公共函数

virtual bool add_result(typename C::T dis, typename C::TI idx) = 0

inline virtual ~ResultHandler()

公共成员

C::T threshold = C::neutral()

struct SearchParametersHNSW : public faiss::SearchParameters

公共函数

inline ~SearchParametersHNSW()

公共成员

int efSearch = 16

bool check_relative_distance = true

bool bounded_queue = true

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct HNSW

公共类型

using storage_idx_t = int32_t

向量的内部存储（32 位：开销较大）

using C = CMax<float, int64_t>

typedef std::pair<float, storage_idx_t> Node

公共函数

void set_default_probas(int M, float levelMult)

初始化 assign_probas 和 cum_nneighbor_per_level，使其在 0 级上具有 2*M 个链接，在 > 0 级上具有 M 个链接

void set_nb_neighbors(int level_no, int n)

设置此级别的邻居数（在添加任何内容之前）

int nb_neighbors(int layer_no) const

此级别的邻居数

int cum_nb_neighbors(int layer_no) const

到此级别（不包括）的累积邻居数

void neighbor_range(idx_t no, int layer_no, size_t *begin, size_t *end) const

顶点 no 在 layer_no 的邻居表中的条目范围

explicit HNSW(int M = 32)

唯一强制参数：邻居数

int random_level()

为新点选择一个随机级别

void fill_with_random_links(size_t n)

将 n 个随机级别添加到表（用于调试...）

void add_links_starting_from(DistanceComputer &ptdis, storage_idx_t pt_id, storage_idx_t nearest, float d_nearest, int level, omp_lock_t *locks, VisitedTable &vt, bool keep_max_size_level0 = false)

void add_with_locks(DistanceComputer &ptdis, int pt_level, int pt_id, std::vector<omp_lock_t> &locks, VisitedTable &vt, bool keep_max_size_level0 = false)

在所有级别 <= pt_level 上添加点 pt_id，并为其构建链接结构。

HNSWStats search(DistanceComputer &qdis, ResultHandler<C> &res, VisitedTable &vt, const SearchParametersHNSW *params = nullptr) const

用于单点，单线程的搜索接口

void search_level_0(DistanceComputer &qdis, ResultHandler<C> &res, idx_t nprobe, const storage_idx_t *nearest_i, const float *nearest_d, int search_type, HNSWStats &search_stats, VisitedTable &vt, const SearchParametersHNSW *params = nullptr) const

仅从给定顶点在第 0 层搜索

void reset()

void clear_neighbor_tables(int level)

void print_neighbor_stats(int level) const

int prepare_level_tab(size_t n, bool preset_levels = false)

void permute_entries(const idx_t *map)

公共成员

std::vector<double> assign_probas

分配到每层的概率 (总和=1)

std::vector<int> cum_nneighbor_per_level

每层存储的邻居数量（累积），首次添加后不应更改

std::vector<int> levels

每个向量的层级（基础层级 = 1），大小 = ntotal

std::vector<size_t> offsets

offsets[i] 是向量 i 存储在 neighbors 数组中的偏移量, 大小为 ntotal + 1

std::vector<storage_idx_t> neighbors

neighbors[offsets[i]:offsets[i+1]] 是所有层级向量 i 的邻居列表。这是所有存储的去处。

storage_idx_t entry_point = -1

搜索结构中的入口点（具有最大层级的点之一）

faiss::RandomGenerator rng

int max_level = -1

最大层级

int efConstruction = 40

构建时的扩展因子

int efSearch = 16

搜索时的扩展因子

bool check_relative_distance = true

在搜索期间：我们是否检查下一个最佳距离是否足够好？

bool search_bounded_queue = true

在探索期间使用有界队列

公共静态函数

static void shrink_neighbor_list(DistanceComputer &qdis, std::priority_queue<NodeDistFarther> &input, std::vector<NodeDistFarther> &output, int max_size, bool keep_max_size_level0 = false)

struct MinimaxHeap

#include <HNSW.h>

允许快速操作的堆结构

公共类型

typedef faiss::CMax<float, storage_idx_t> HC

公共函数

inline explicit MinimaxHeap(int n)

void push(storage_idx_t i, float v)

float max() const

int size() const

void clear()

int pop_min(float *vmin_out = nullptr)

int count_below(float thresh)

公共成员

int n

int k

int nvalid

ids：std::vector<storage_idx_t>

dis：std::vector<float>

结构体 NodeDistCloser

#include <HNSW.h>

用于将 (id, 距离) 对从最近到最远或相反的顺序进行排序。

公共函数

NodeDistCloser(float d, int id)

operator<(const NodeDistCloser &obj1) const

公共成员

d：float

id：int

结构体 NodeDistFarther

公共函数

NodeDistFarther(float d, int id)

operator<(const NodeDistFarther &obj1) const

公共成员

d：float

id：int

结构体 HNSWStats

公共函数

reset()

跳数，也称为遍历的边数。

combine(const HNSWStats &other)

公共成员

n1：size_t = 0

n2：size_t = 0

搜索的向量数量。

ndis：size_t = 0

候选列表耗尽的查询数量。

nhops：size_t = 0

计算的距离数量。

结构体 IDSelector

#include <IDSelector.h>

封装要处理的ID集合。

被 PyCallbackIDSelector, faiss::IDSelectorAll, faiss::IDSelectorAnd, faiss::IDSelectorArray, faiss::IDSelectorBatch, faiss::IDSelectorBitmap, faiss::IDSelectorNot, faiss::IDSelectorOr, faiss::IDSelectorRange, faiss::IDSelectorTranslated, faiss::IDSelectorXOr 继承。

公共函数

virtual bool is_member(idx_t id) const = 0

virtual ~IDSelector()

结构体 IDSelectorRange : public faiss::IDSelector

#include <IDSelector.h>

位于 [imin, imax) 之间的 id。

公共函数

IDSelectorRange(idx_t imin, idx_t imax, bool assume_sorted = false)

virtual bool is_member(idx_t id) const final

void find_sorted_ids_bounds(size_t list_size, const idx_t *ids, size_t *jmin, size_t *jmax) const

对于已排序的 ID，查找存储有效 ID 的列表索引范围

inline ~IDSelectorRange() override

公共成员

idx_t imin

idx_t imax

bool assume_sorted

假设要处理的 ID 已排序。在某些情况下，这可以加快处理速度

struct IDSelectorArray : public faiss::IDSelector

#include <IDSelector.h>

元素的简单数组

is_member 调用效率很低，但某些操作可以直接使用 id。

公共函数

IDSelectorArray(size_t n, const idx_t *ids)

使用要处理的 ID 数组构造

参数：

• n – 要存储的 ID 数

• ids – 要存储的元素。指针在 IDSelectorArray 的生命周期内应保持有效

virtual bool is_member(idx_t id) const final

inline ~IDSelectorArray() override

公共成员

size_t n

const idx_t *ids

struct IDSelectorBatch : public faiss::IDSelector

#include <IDSelector.h>

来自集合的 ID。

构造函数传递的索引集合中重复的 ID 不会影响性能。

用于布隆过滤器和 GCC 的 unordered_set 实现的哈希函数只是 ID 的最低有效位。这对于随机 ID 或序列中的 ID 工作正常，但如果 lsb 始终相同，则会产生许多哈希冲突

公共函数

IDSelectorBatch(size_t n, const idx_t *indices)

使用要处理的 ID 数组构造

参数：

• n – 要存储的 ID 数

• ids – 要存储的元素。构造后可以释放指针

virtual bool is_member(idx_t id) const final

inline ~IDSelectorBatch() override

公共成员

std::unordered_set<idx_t> set

std::vector<uint8_t> bloom

int nbits

idx_t mask

struct IDSelectorBitmap : public faiss::IDSelector

#include <IDSelector.h>

每个元素一位。 使用位图构建，大小为 ceil(n / 8)。

公共函数

IDSelectorBitmap(size_t n, const uint8_t *bitmap)

使用二进制掩码构建

参数：

• n – 位图数组的大小

• bitmap – 如果 id / 8 < n 并且 bitmap[floor(i / 8)] 的位编号 (i%8) 为 1，则选择 id。

virtual bool is_member(idx_t id) const final

inline ~IDSelectorBitmap() override

公共成员

size_t n

const uint8_t *bitmap

struct IDSelectorNot : public faiss::IDSelector

#include <IDSelector.h>

反转另一个选择器的成员资格测试

公共函数

inline IDSelectorNot(const IDSelector *sel)

inline virtual bool is_member(idx_t id) const final

inline virtual ~IDSelectorNot()

公共成员

const IDSelector *sel

struct IDSelectorAll : public faiss::IDSelector

#include <IDSelector.h>

选择所有条目（对基准测试有用）

公共函数

inline virtual bool is_member(idx_t id) const final

inline virtual ~IDSelectorAll()

struct IDSelectorAnd : public faiss::IDSelector

#include <IDSelector.h>

对给定的两个 IDSelector 的 is_membership 结果执行 AND 运算。

公共函数

inline IDSelectorAnd(const IDSelector *lhs, const IDSelector *rhs)

inline virtual bool is_member(idx_t id) const final

inline virtual ~IDSelectorAnd()

公共成员

const IDSelector *lhs

const IDSelector *rhs

struct IDSelectorOr : public faiss::IDSelector

#include <IDSelector.h>

对两个给定的 IDSelector 的 is_membership 结果执行 OR 操作。

公共函数

inline IDSelectorOr(const IDSelector *lhs, const IDSelector *rhs)

inline virtual bool is_member(idx_t id) const final

inline virtual ~IDSelectorOr()

公共成员

const IDSelector *lhs

const IDSelector *rhs

struct IDSelectorXOr : public faiss::IDSelector

#include <IDSelector.h>

对两个给定的 IDSelector 的 is_membership 结果执行 XOR 操作。

公共函数

inline IDSelectorXOr(const IDSelector *lhs, const IDSelector *rhs)

inline virtual bool is_member(idx_t id) const final

inline virtual ~IDSelectorXOr()

公共成员

const IDSelector *lhs

const IDSelector *rhs

struct IOReader

由 PyCallbackIOReader、faiss::BufferedIOReader、faiss::FileIOReader、faiss::VectorIOReader 继承

公共函数

读取函数，从输入读取数据。

获取文件描述符。

IOReader 的虚析构函数。

公共成员

IOReader 的名称。

IOWriter 类。

子类包括 PyCallbackIOWriter, faiss::BufferedIOWriter, faiss::FileIOWriter, faiss::VectorIOWriter。

公共函数

写入函数，将数据写入输出。

获取文件描述符。

IOWriter 的虚析构函数。

公共成员

IOWriter 的名称。

VectorIOReader 类，从 std::vector 读取数据。

公共函数

读取函数，从 vector 中读取数据。

返回 -1，因为 vector 没有文件描述符。

公共成员

存储数据的 vector。

当前读指针的位置。

VectorIOReader 的名称。

VectorIOWriter 类，将数据写入 std::vector。

公共函数

写入函数，将数据写入 vector。

返回 -1，因为 vector 没有文件描述符。

公共成员

存储数据的 vector。

VectorIOWriter 的名称。

FileIOReader 类，从文件读取数据。

公共函数

FileIOReader(FILE *rf)

FileIOReader(const char *fname)

~FileIOReader() override

virtual size_t operator()(void *ptr, size_t size, size_t nitems) override

virtual int filedescriptor() override

公共成员

FILE *f = nullptr

bool need_close = false

std::string name

struct FileIOWriter : public faiss::IOWriter

公共函数

FileIOWriter(FILE *wf)

FileIOWriter(const char *fname)

~FileIOWriter() override

virtual size_t operator()(const void *ptr, size_t size, size_t nitems) override

virtual int filedescriptor() override

公共成员

FILE *f = nullptr

bool need_close = false

std::string name

struct BufferedIOReader : public faiss::IOReader

#include <io.h>

包装一个ioreader以进行缓冲读取，从而避免读取太小的块

公共函数

explicit BufferedIOReader(IOReader *reader, size_t bsz = 1024 * 1024)

参数：

bsz – 缓冲区大小（字节）。读取操作将分批完成，每批此大小

virtual size_t operator()(void *ptr, size_t size, size_t nitems) override

virtual int filedescriptor()

公共成员

IOReader *reader

size_t bsz

size_t ofs

输入流中的偏移量

size_t ofs2

返回给调用者的字节数

size_t b0

size_t b1

缓冲区中可用字节的范围

std::vector<char> buffer

std::string name

struct BufferedIOWriter : public faiss::IOWriter

公共函数

explicit BufferedIOWriter(IOWriter *writer, size_t bsz = 1024 * 1024)

virtual size_t operator()(const void *ptr, size_t size, size_t nitems) override

~BufferedIOWriter() override

virtual int filedescriptor()

公共成员

IOWriter *writer

size_t bsz

size_t ofs

size_t ofs2

从调用者接收的字节数

size_t b0

缓冲区中的数据量

std::vector<char> buffer

std::string name

struct ZnSphereSearch

#include <lattice_Zn.h>

返回球体中最接近查询的顶点。仅返回坐标，不返回 ID。

算法：所有点都是从一个原子向量经过排列和符号更改得出的。搜索函数找到最合适的原子和变换。

由 faiss::ZnSphereCodec 继承

公共函数

ZnSphereSearch(int dim, int r2)

float search(const float *x, float *c) const

查找最近的质心。 x 不需要标准化

float search(const float *x, float *c, float *tmp, int *tmp_int, int *ibest_out = nullptr) const

完整调用。需要外部分配的临时空间

void search_multi(int n, const float *x, float *c_out, float *dp_out)

公共成员

int dimS

int r2

int natom

std::vector<float> voc

size dim * ntatom

struct EnumeratedVectors

Subclassed by faiss::ZnSphereCodec, faiss::ZnSphereCodecRec

公共函数

inline explicit EnumeratedVectors(int dim)

virtual uint64_t encode(const float *x) const = 0

encode a vector from a collection

virtual void decode(uint64_t code, float *c) const = 0

decode it

void encode_multi(size_t nc, const float *c, uint64_t *codes) const

void decode_multi(size_t nc, const uint64_t *codes, float *c) const

void find_nn(size_t n, const uint64_t *codes, size_t nq, const float *xq, int64_t *idx, float *dis)

inline virtual ~EnumeratedVectors()

公共成员

uint64_t nv

size of the collection

int dim

struct Repeat

公共成员

float val

int n

struct Repeats

#include <lattice_Zn.h>

Repeats: used to encode a vector that has n occurrences of val. Encodes the signs and permutation of the vector. Useful for atoms.

Subclassed by faiss::ZnSphereCodec::CodeSegment

公共函数

Repeats(int dim = 0, const float *c = nullptr)

uint64_t count() const

uint64_t encode(const float *c) const

void decode(uint64_t code, float *c) const

公共成员

int dim

std::vector<Repeat> repeats

struct ZnSphereCodec : public faiss::ZnSphereSearch, public faiss::EnumeratedVectors

#include <lattice_Zn.h>

可以返回编码向量的 ID 的编解码器

使用 ZnSphereSearch 通过对排列和符号进行编码来编码向量。 依赖于 ZnSphereSearch，因为它使用原子数

被 faiss::ZnSphereCodecAlt 继承

公共函数

ZnSphereCodec(int dim, int r2)

uint64_t search_and_encode(const float *x) const

virtual void decode(uint64_t code, float *c) const override

decode it

virtual uint64_t encode(const float *x) const override

接收不需要是质心的向量

float search(const float *x, float *c) const

查找最近的质心。 x 不需要标准化

float search(const float *x, float *c, float *tmp, int *tmp_int, int *ibest_out = nullptr) const

完整调用。需要外部分配的临时空间

void search_multi(int n, const float *x, float *c_out, float *dp_out)

void encode_multi(size_t nc, const float *c, uint64_t *codes) const

void decode_multi(size_t nc, const uint64_t *codes, float *c) const

void find_nn(size_t n, const uint64_t *codes, size_t nq, const float *xq, int64_t *idx, float *dis)

公共成员

std::vector<CodeSegment> code_segments

uint64_t nv

size_t code_size

int dimS

int r2

int natom

std::vector<float> voc

size dim * ntatom

int dim

struct CodeSegment : public faiss::Repeats

公共函数

inline explicit CodeSegment(const Repeats &r)

uint64_t count() const

uint64_t encode(const float *c) const

void decode(uint64_t code, float *c) const

公共成员

uint64_t c0

int signbits

int dim

std::vector<Repeat> repeats

struct ZnSphereCodecRec : public faiss::EnumeratedVectors

#include <lattice_Zn.h>

递归球形编码器

使用维度上的递归分解来编码由 ZnSphereSearch 找到的质心。这些代码与 ZnSpehreCodec 的代码不兼容

公共函数

ZnSphereCodecRec(int dim, int r2)

uint64_t encode_centroid(const float *c) const

virtual void decode(uint64_t code, float *c) const override

decode it

virtual uint64_t encode(const float *x) const override

向量需要是质心（不适用于任意向量）

uint64_t get_nv(int ld, int r2a) const

uint64_t get_nv_cum(int ld, int r2t, int r2a) const

void set_nv_cum(int ld, int r2t, int r2a, uint64_t v)

void encode_multi(size_t nc, const float *c, uint64_t *codes) const

void encode_multi(size_t nc, const float *c, uint64_t *codes) const

void decode_multi(size_t nc, const uint64_t *codes, float *c) const

公共成员

void decode_multi(size_t nc, const uint64_t *codes, float *c) const

void find_nn(size_t n, const uint64_t *codes, size_t nq, const float *xq, int64_t *idx, float *dis)

void find_nn(size_t n, const uint64_t *codes, size_t nq, const float *xq, int64_t *idx, float *dis)

int r2

int r2

int log2_dim

int log2_dim

int code_size

size of the collection

int code_size

std::vector<uint64_t> all_nv

#include <lattice_Zn.h>

std::vector<uint64_t> all_nv

公共函数

std::vector<uint64_t> all_nv_cum

std::vector<uint64_t> all_nv_cum

接收不需要是质心的向量

int decode_cache_ld

decode it

int decode_cache_ld

std::vector<std::vector<float>> decode_cache

查找最近的质心。 x 不需要标准化

std::vector<std::vector<float> > decode_cache

完整调用。需要外部分配的临时空间

search_multi 函数 (int n, const float *x, float *c_out, float *dp_out)

encode_multi 函数 (size_t nc, const float *c, uint64_t *codes) const

decode_multi 函数 (size_t nc, const uint64_t *codes, float *c) const

find_nn 函数 (size_t n, const uint64_t *codes, size_t nq, const float *xq, int64_t *idx, float *dis)

公共成员

布尔变量 use_rec

ZnSphereCodecRec 类型的变量 znc_rec

CodeSegment 类型的向量 code_segments

uint64_t 类型的变量 nv

size_t 类型的变量 code_size

整型变量 dimS

整型变量 r2

整型变量 natom

浮点型向量 voc

size dim * ntatom

整型变量 dim

结构体 LocalSearchQuantizer，继承自 faiss::AdditiveQuantizer

#include <LocalSearchQuantizer.h>

LSQ/LSQ++ 的实现在以下两篇论文中描述：

重新审视加性量化，Julieta Martinez 等人，ECCV 2016

LSQ++：多码本量化中更低的运行时间和更高的召回率，Julieta Martinez 等人，ECCV 2018

此实现主要从 Julieta Martinez 的 Julia 实现翻译而来：(https://github.com/una-dinosauria/local-search-quantization, https://github.com/una-dinosauria/Rayuela.jl)

训练后的代码存储在 codebooks 中，在 PQ 和 RQ 中称为 centroids。

公共类型

枚举类型 Search_type_t

编码搜索的执行方式和向量的编码方式。

值

枚举值 ST_decompress

解压缩数据库向量

枚举值 ST_LUT_nonorm

使用 LUT，不包含范数（适用于 IP 或归一化向量）

枚举值 ST_norm_from_LUT

从查找表计算范数（成本为 O(M^2)）

枚举值 ST_norm_float

使用 LUT，并将 float32 范数与向量一起存储

枚举项 ST_norm_qint8

使用 LUT，并存储 8bit 量化范数

枚举项 ST_norm_qint4

枚举项 ST_norm_cqint8

使用 LUT，并存储非均匀量化范数

枚举项 ST_norm_cqint4

枚举项 ST_norm_lsq2x4

使用 2x4 位 lsq 作为范数量化器（用于快速扫描）

枚举项 ST_norm_rq2x4

使用 2x4 位 rq 作为范数量化器（用于快速扫描）

公共函数

LocalSearchQuantizer(size_t d, size_t M, size_t nbits, Search_type_t search_type = ST_decompress)

LocalSearchQuantizer()

~LocalSearchQuantizer() override

virtual void train(size_t n, const float *x) override

训练量化器

参数：

x – 训练向量，大小为 n * d

virtual void compute_codes_add_centroids(const float *x, uint8_t *codes, size_t n, const float *centroids = nullptr) const override

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

• n – 向量的数量

• centroids – 要添加到 x 的质心，大小为 n * d

void update_codebooks(const float *x, const int32_t *codes, size_t n)

根据编码更新码本

参数：

• x – 训练向量，大小为 n * d

• codes – 编码后的训练向量，大小为 n * M

• n – 向量的数量

void icm_encode(int32_t *codes, const float *x, size_t n, size_t ils_iters, std::mt19937 &gen) const

使用迭代条件模式（icm）根据码本编码向量。

参数：

• codes – 输出代码，大小为 n * M

• x – 要编码的向量，大小为 n * d

• n – 向量的数量

• ils_iters – 迭代局部搜索的迭代次数

void icm_encode_impl(int32_t *codes, const float *x, const float *unaries, std::mt19937 &gen, size_t n, size_t ils_iters, bool verbose) const

void icm_encode_step(int32_t *codes, const float *unaries, const float *binaries, size_t n, size_t n_iters) const

void perturb_codes(int32_t *codes, size_t n, std::mt19937 &gen) const

给编码添加一些扰动

参数：

• codes – 要扰动的编码，大小为 n * M

• n – 向量的数量

void perturb_codebooks(float T, const std::vector<float> &stddev, std::mt19937 &gen)

给码本添加一些扰动

参数：

• T – 模拟退火的温度

• stddev – 训练数据中每个维度的标准差

void compute_binary_terms(float *binaries) const

计算二元项

参数：

binaries – 二元项，大小为 M * M * K * K

void compute_unary_terms(const float *x, float *unaries, size_t n) const

计算一元项

参数：

• n – 向量的数量

• x – 要编码的向量，大小为 n * d

• unaries – 一元项，大小为 n * M * K

float evaluate(const int32_t *codes, const float *x, size_t n, float *objs = nullptr) const

用于计算重建误差的辅助函数

参数：

• codes – 编码后的编码，大小为 n * M

• x – 要编码的向量，大小为 n * d

• n – 向量的数量

• objs – 如果不为空，则将每个向量的重建误差存储到其中，大小为 n

void compute_codebook_tables()

uint64_t encode_norm(float norm) const

将范数编码为 norm_bits 位

uint32_t encode_qcint(float x) const

通过非均匀标量量化编码范数

float decode_qcint(uint32_t c) const

通过非均匀标量量化解码范数

void set_derived_values()

训练范数量化器。

void train_norm(size_t n, const float *norms)

inline virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

void pack_codes(size_t n, const int32_t *codes, uint8_t *packed_codes, int64_t ld_codes = -1, const float *norms = nullptr, const float *centroids = nullptr) const

将一系列代码打包为位紧凑格式

参数：

• codes – 要打包的代码，大小为 n * code_size

• packed_codes – 输出位紧凑代码

• ld_codes – 代码的前导维度

• norms – 向量的范数（大小为 n）。如果需要但未提供，将会被计算

• centroids – 要添加到 x 的质心，大小为 n * d

virtual void decode(const uint8_t *codes, float *x, size_t n) const override

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

virtual void decode_unpacked(const int32_t *codes, float *x, size_t n, int64_t ld_codes = -1) const

解码一组非打包格式的向量

参数：

• codes – 要解码的代码，大小为 n * ld_codes

• x – 输出向量，大小为 n * d

template<bool is_IP, Search_type_t effective_search_type>
float compute_1_distance_LUT(const uint8_t *codes, const float *LUT) const

void decode_64bit(idx_t n, float *x) const

用于解码 64 位字中代码的函数

virtual void compute_LUT(size_t n, const float *xq, float *LUT, float alpha = 1.0f, long ld_lut = -1) const

计算内积查找表。在质心搜索函数中使用。

参数：

• xq – 查询向量，大小 (n, d)

• LUT – 查找表，大小 (n, total_codebook_size)

• alpha – 计算 alpha * 内积

• ld_lut – LUT 的前导维度

void knn_centroids_inner_product(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels) const

精确 IP 搜索

void compute_centroid_norms(float *norms) const

对于 L2 搜索，我们需要质心的 L2 范数

参数：

norms – 输出范数表，大小 total_codebook_size

void knn_centroids_L2(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels, const float *centroid_norms) const

精确 L2 搜索，使用预先计算的范数

公共成员

size_t K

每个码本的代码数量

size_t train_iters = 25

训练中的迭代次数

size_t encode_ils_iters = 16

编码中的局部搜索迭代次数

size_t train_ils_iters = 8

训练中的局部搜索迭代次数

size_t icm_iters = 4

icm中的迭代次数

float p = 0.5f

温度因子

float lambd = 1e-2f

正则化因子

size_t chunk_size = 10000

一次编码的向量数量

int random_seed = 0x12345

随机生成器的种子

size_t nperts = 4

每个代码中的扰动数量

如果非NULL，则使用此编码器进行编码（由对象拥有）

lsq::IcmEncoderFactory *icm_encoder_factory = nullptr

bool update_codebooks_with_double = true

size_t M

码本数量

std::vector<size_t> nbits

每一步的比特数

std::vector<float> codebooks

码本

std::vector<uint64_t> codebook_offsets

码本 #i 存储在码本表 codebooks 的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size x d

size_t tot_bits = 0

总比特数 (索引 + 范数)

size_t norm_bits = 0

为范数分配的比特数

size_t total_codebook_size = 0

码本的大小 (向量个数)

bool only_8bit = false

是否所有 nbits = 8 (使用更快的解码器)

bool verbose = false

训练期间是否输出详细信息？

bool is_trained = false

是否已训练

std::vector<float> norm_tabs

ST_norm_lsq2x4 和 ST_norm_rq2x4 的辅助数据，存储 4 位 fastscan 的码本条目的范数

IndexFlat1D qnorm

存储和搜索范数

std::vector<float> centroid_norms

所有码本条目的范数（大小为 total_codebook_size）

std::vector<float> codebook_cross_products

所有码本条目与之前码本的点积，大小为 sum(codebook_offsets[m] * 2^nbits[m], m=0..M-1)

size_t max_mem_distances = 5 * (size_t(1) << 30)

范数和距离矩阵与波束搜索可能会变得很大，因此使用此项来控制可以分配的内存量

Search_type_t search_type

也决定了代码中的内容。

float norm_min = NAN

范数量化的最小值/最大值

float norm_max = NAN

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct DummyScaler

#include <LookupTableScaler.h>

无操作处理程序

公共函数

inline simd32uint8 lookup(const simd32uint8&, const simd32uint8&) const

inline simd16uint16 scale_lo(const simd32uint8&) const

inline simd16uint16 scale_hi(const simd32uint8&) const

template<class dist_t>
inline dist_t scale_one(const dist_t&) const

公共静态属性

static constexpr int nscale = 0

struct NormTableScaler

#include <LookupTableScaler.h>

消耗 2x4 位来将范数编码为标量加法量化器，因为范数的范围大于其他分量，因此需要进行缩放

公共函数

inline explicit NormTableScaler(int scale)

inline simd32uint8 lookup(const simd32uint8 &lut, const simd32uint8 &c) const

inline simd16uint16 scale_lo(const simd32uint8 &res) const

inline simd16uint16 scale_hi(const simd32uint8 &res) const

template<class dist_t>
inline dist_t scale_one(const dist_t &x) const

公共成员

int scale_int

simd16uint16 scale_simd

公共静态属性

static constexpr int nscale = 2

struct NNDescent

公共类型

using storage_idx_t = int

using KNNGraph = std::vector<nndescent::Nhood>

公共函数

explicit NNDescent(const int d, const int K)

~NNDescent()

void build(DistanceComputer &qdis, const int n, bool verbose)

void search(DistanceComputer &qdis, const int topk, idx_t *indices, float *dists, VisitedTable &vt) const

void reset()

void init_graph(DistanceComputer &qdis)

随机初始化 KNN 图。

void nndescent(DistanceComputer &qdis, bool verbose)

执行 NNDescent 算法。

void join(DistanceComputer &qdis)

对每个节点执行局部连接操作。

void update()

为每个节点采样新的邻居，以便稍后执行局部连接操作。

void generate_eval_set(DistanceComputer &qdis, std::vector<int> &c, std::vector<std::vector<int>> &v, int N)

采样少量点来评估构建的 KNNG 的质量。

float eval_recall(std::vector<int> &ctrl_points, std::vector<std::vector<int>> &acc_eval_set)

评估构建的 KNNG 的质量。

公共成员

bool has_built = false

int S = 10

int R = 100

int iter = 10

int search_L = 0

int random_seed = 2021

int K

int d

int L

int ntotal = 0

KNNGraph graph

std::vector<int> final_graph

struct NSG

公共类型

using storage_idx_t = int32_t

向量的内部存储（32 位：开销较大）

using Node = nsg::Node

using Neighbor = nsg::Neighbor

公共函数

explicit NSG(int R = 32)

void build(Index *storage, idx_t n, const nsg::Graph<idx_t> &knn_graph, bool verbose)

void reset()

void search ( DistanceComputer & dis , int k , idx_t * I , float * D , VisitedTable & vt ) const

void init_graph ( Index * storage , const nsg :: Graph < idx_t > & knn_graph )

template < bool collect_fullset , class index_t >
void search_on_graph ( const nsg :: Graph < index_t > & graph , DistanceComputer & dis , VisitedTable & vt , int ep , int pool_size , std :: vector < Neighbor > & retset , std :: vector < Node > & fullset ) const

void add_reverse_links ( int q , std :: vector < std :: mutex > & locks , DistanceComputer & dis , nsg :: Graph < Node > & graph )

void sync_prune(int q, std::vector<Node> &pool, DistanceComputer &dis, VisitedTable &vt, const nsg::Graph<idx_t> &knn_graph, nsg::Graph<Node> &graph)

void link(Index *storage, const nsg::Graph<idx_t> &knn_graph, nsg::Graph<Node> &graph, bool verbose)

int tree_grow(Index *storage, std::vector<int> &degrees)

int dfs(VisitedTable &vt, int root, int cnt) const

int attach_unlinked(Index *storage, VisitedTable &vt, VisitedTable &vt2, std::vector<int> &degrees)

void check_graph() const

公共成员

int ntotal = 0

节点数

int R

每个节点的邻居数

int L

构建时搜索路径的长度

int C

构建时候选池大小

int search_L = 16

搜索路径的长度

int enterpoint

入口点

std::shared_ptr<nsg::Graph<int32_t>> final_graph

NSG 图结构。

bool is_built = false

NSG 是否已构建。

RandomGenerator rng

随机数生成器

struct SimulatedAnnealingParameters

#include <PolysemousTraining.h>

用于模拟退火法的参数

被 faiss::PolysemousTraining, faiss::SimulatedAnnealingOptimizer 继承

公共函数

inline SimulatedAnnealingParameters()

公共成员

double init_temperature = 0.7

double temperature_decay = 0.9997893011688015

int n_iter = 500000

int n_redo = 2

int seed = 123

int verbose = 0

bool only_bit_flips = false

bool init_random = false

struct PermutationObjective

#include <PolysemousTraining.h>

损失函数的抽象类

被 faiss::ReproduceDistancesObjective 继承

公共函数

virtual double compute_cost(const int *perm) const = 0

virtual double cost_update(const int *perm, int iw, int jw) const

inline virtual ~PermutationObjective()

公共成员

int n

struct ReproduceDistancesObjective : public faiss::PermutationObjective

公共函数

double dis_weight(double x) const

double get_source_dis(int i, int j) const

virtual double compute_cost(const int *perm) const override

virtual double cost_update(const int *perm, int iw, int jw) const override

ReproduceDistancesObjective(int n, const double *source_dis_in, const double *target_dis_in, double dis_weight_factor)

void set_affine_target_dis(const double *source_dis_in)

inline ~ReproduceDistancesObjective() override

公共成员

double dis_weight_factor

std::vector<double> source_dis

“实际”校正距离（大小为 n^2）

const double *target_dis

需要的距离（大小为 n^2）

std::vector<double> weights

每个距离的权重（大小为 n^2）

int n

公共静态函数

static inline double sqr(double x)

static void compute_mean_stdev(const double *tab, size_t n2, double *mean_out, double *stddev_out)

struct SimulatedAnnealingOptimizer : public faiss::SimulatedAnnealingParameters

#include <PolysemousTraining.h>

用于排列的模拟退火优化算法。

公共函数

SimulatedAnnealingOptimizer(PermutationObjective *obj, const SimulatedAnnealingParameters &p)

记录成本函数的值

double optimize(int *perm)

double run_optimization(int *best_perm)

virtual ~SimulatedAnnealingOptimizer()

公共成员

PermutationObjective *obj

int n

排列的大小

FILE *logfile

RandomGenerator *rnd

double init_cost

记住优化的初始成本

double init_temperature = 0.7

double temperature_decay = 0.9997893011688015

int n_iter = 500000

int n_redo = 2

int seed = 123

int verbose = 0

bool only_bit_flips = false

bool init_random = false

struct PolysemousTraining : public faiss::SimulatedAnnealingParameters

#include <PolysemousTraining.h>

优化 ProductQuantizer 中索引的顺序

公共类型

enum Optimization_type_t

值

enumerator OT_None

enumerator OT_ReproduceDistances_affine

默认

enumerator OT_Ranking_weighted_diff

与_2相同，但使用y+的rank - y-的rank

公共函数

PolysemousTraining()

void optimize_pq_for_hamming(ProductQuantizer &pq, size_t n, const float *x) const

重新排序质心，使Hamming距离成为SDC距离的良好近似 (由 train 调用)

void optimize_ranking(ProductQuantizer &pq, size_t n, const float *x) const

由 optimize_pq_for_hamming 调用

void optimize_reproduce_distances(ProductQuantizer &pq) const

由 optimize_pq_for_hamming 调用

size_t memory_usage_per_thread(const ProductQuantizer &pq) const

确保我们不会耗尽内存

公共成员

Optimization_type_t optimization_type

int ntrain_permutation

使用1/4的训练点进行优化，最大值为ntrain_permutation。 如果ntrain_permutation == 0：在质心上训练

double dis_weight_factor

权重距离损失的exp衰减

size_t max_memory

如果训练需要超过该数量的RAM，则拒绝训练

std::string log_pattern

double init_temperature = 0.7

double temperature_decay = 0.9997893011688015

int n_iter = 500000

int n_redo = 2

int seed = 123

int verbose = 0

bool only_bit_flips = false

bool init_random = false

struct CodePackerPQ4 : public faiss::CodePacker

#include <pq4_fast_scan.h>

CodePacker API 用于 PQ4 快速扫描

公共函数

CodePackerPQ4(size_t nsq, size_t bbs)

virtual void pack_1(const uint8_t *flat_code, size_t offset, uint8_t *block) const final

virtual void unpack_1(const uint8_t *block, size_t offset, uint8_t *flat_code) const final

virtual void pack_all(const uint8_t *flat_codes, uint8_t *block) const

virtual void unpack_all(const uint8_t *block, uint8_t *flat_codes) const

公共成员

size_t nsq

size_t code_size

size_t nvec

size_t block_size

struct ProductAdditiveQuantizer : public faiss::AdditiveQuantizer

#include <ProductAdditiveQuantizer.h>

乘积加性量化器

乘积加性量化器是 AQ 和 PQ 的一种变体。它首先像 PQ 一样将向量空间划分为多个正交子空间。然后，它通过独立的加性量化器量化每个子空间。

由 faiss::ProductLocalSearchQuantizer, faiss::ProductResidualQuantizer 继承

公共类型

enum Search_type_t

编码搜索的执行方式和向量的编码方式。

值

enumerator ST_decompress

解压缩数据库向量

enumerator ST_LUT_nonorm

使用 LUT，不包含范数（适用于 IP 或归一化向量）

枚举值 ST_norm_from_LUT

从查找表计算范数（成本为 O(M^2)）

枚举值 ST_norm_float

使用 LUT，并将 float32 范数与向量一起存储

枚举值 ST_norm_qint8

使用 LUT，并存储 8bit 量化范数

枚举值 ST_norm_qint4

枚举值 ST_norm_cqint8

使用 LUT，并存储非均匀量化范数

枚举值 ST_norm_cqint4

枚举值 ST_norm_lsq2x4

使用 2x4 位 lsq 作为范数量化器（用于快速扫描）

枚举值 ST_norm_rq2x4

使用 2x4 位 rq 作为范数量化器（用于快速扫描）

公共函数

ProductAdditiveQuantizer(size_t d, const std::vector<AdditiveQuantizer*> &aqs, Search_type_t search_type = ST_decompress)

构建一个乘积加法量化器。

传入的加法量化器将被克隆到 ProductAdditiveQuantizer 对象中。

参数：

• d – 输入向量的维度

• aqs – 子加法量化器

• search_type – AQ搜索类型

ProductAdditiveQuantizer()

virtual ~ProductAdditiveQuantizer()

void init(size_t d, const std::vector<AdditiveQuantizer*> &aqs, Search_type_t search_type)

AdditiveQuantizer *subquantizer(size_t m) const

训练乘积加法量化器。

virtual void train(size_t n, const float *x) override

训练量化器

参数：

x – 训练向量，大小为 n * d

virtual void compute_codes_add_centroids(const float *x, uint8_t *codes, size_t n, const float *centroids = nullptr) const override

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

• centroids – 要添加到 x 的质心，大小为 n * d

void compute_unpacked_codes(const float *x, int32_t *codes, size_t n, const float *centroids = nullptr) const

virtual void decode_unpacked(const int32_t *codes, float *x, size_t n, int64_t ld_codes = -1) const override

解码一组非打包格式的向量

参数：

• codes – 要解码的代码，大小为 n * ld_codes

• x – 输出向量，大小为 n * d

virtual void decode(const uint8_t *codes, float *x, size_t n) const override

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

virtual void compute_LUT(size_t n, const float *xq, float *LUT, float alpha = 1.0f, long ld_lut = -1) const override

计算内积查找表。用于搜索功能。

参数：

• xq – 查询向量，大小 (n, d)

• LUT – 查找表，大小 (n, total_codebook_size)

• alpha – 计算 alpha * 内积

• ld_lut – LUT 的前导维度

void compute_codebook_tables()

uint64_t encode_norm(float norm) const

将范数编码为 norm_bits 位

uint32_t encode_qcint(float x) const

通过非均匀标量量化编码范数

float decode_qcint(uint32_t c) const

通过非均匀标量量化解码范数

void set_derived_values()

训练范数量化器。

void train_norm(size_t n, const float *norms)

inline virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

void pack_codes(size_t n, const int32_t *codes, uint8_t *packed_codes, int64_t ld_codes = -1, const float *norms = nullptr, const float *centroids = nullptr) const

将一系列代码打包为位紧凑格式

参数：

• codes – 要打包的代码，大小为 n * code_size

• packed_codes – 输出位紧凑代码

• ld_codes – 代码的前导维度

• norms – 向量的范数（大小为 n）。如果需要但未提供，将会被计算

• centroids – 要添加到 x 的质心，大小为 n * d

template<bool is_IP, Search_type_t effective_search_type>
float compute_1_distance_LUT(const uint8_t *codes, const float *LUT) const

void decode_64bit(idx_t n, float *x) const

用于解码 64 位字中代码的函数

void knn_centroids_inner_product(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels) const

精确 IP 搜索

void compute_centroid_norms(float *norms) const

对于 L2 搜索，我们需要质心的 L2 范数

参数：

norms – 输出范数表，大小 total_codebook_size

void knn_centroids_L2(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels, const float *centroid_norms) const

精确 L2 搜索，使用预先计算的范数

公共成员

size_t nsplits

我们将一个向量分割成的子向量的数量

std::vector<AdditiveQuantizer*> quantizers

size_t M

码本数量

std::vector<size_t> nbits

每一步的比特数

std::vector<float> codebooks

码本

std::vector<uint64_t> codebook_offsets

码本 #i 存储在码本表 codebooks 的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size x d

size_t tot_bits = 0

总比特数 (索引 + 范数)

size_t norm_bits = 0

为范数分配的比特数

size_t total_codebook_size = 0

码本的大小 (向量个数)

bool only_8bit = false

是否所有 nbits = 8 (使用更快的解码器)

bool verbose = false

训练期间是否输出详细信息？

bool is_trained = false

是否已训练

std::vector<float> norm_tabs

ST_norm_lsq2x4 和 ST_norm_rq2x4 的辅助数据，存储 4 位 fastscan 的码本条目的范数

IndexFlat1D qnorm

存储和搜索范数

std::vector<float> centroid_norms

所有码本条目的范数（大小为 total_codebook_size）

std::vector<float> codebook_cross_products

所有码本条目与之前码本的点积，大小为 sum(codebook_offsets[m] * 2^nbits[m], m=0..M-1)

size_t max_mem_distances = 5 * (size_t(1) << 30)

范数和距离矩阵与波束搜索可能会变得很大，因此使用此项来控制可以分配的内存量

Search_type_t search_type

也决定了代码中的内容。

float norm_min = NAN

范数量化的最小值/最大值

float norm_max = NAN

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct ProductLocalSearchQuantizer : public faiss::ProductAdditiveQuantizer

#include <ProductAdditiveQuantizer.h>

Product Local Search Quantizer

公共类型

enum Search_type_t

编码搜索的执行方式和向量的编码方式。

值

enumerator ST_decompress

解压缩数据库向量

enumerator ST_LUT_nonorm

使用 LUT，不包含范数（适用于 IP 或归一化向量）

enumerator ST_norm_from_LUT

从查找表计算范数（成本为 O(M^2)）

enumerator ST_norm_float

使用 LUT，并将 float32 范数与向量一起存储

enumerator ST_norm_qint8

使用 LUT，并存储 8bit 量化范数

enumerator ST_norm_qint4

枚举值 ST_norm_cqint8

使用 LUT，并存储非均匀量化范数

枚举值 ST_norm_cqint4

枚举值 ST_norm_lsq2x4

使用 2x4 位 lsq 作为范数量化器（用于快速扫描）

枚举值 ST_norm_rq2x4

使用 2x4 位 rq 作为范数量化器（用于快速扫描）

公共函数

ProductLocalSearchQuantizer(size_t d, size_t nsplits, size_t Msub, size_t nbits, Search_type_t search_type = ST_decompress)

构造一个乘积 LSQ 对象。

参数：

• d – 输入向量的维度

• nsplits – 我们将一个向量分割成的子向量的数量

• Msub – 每个 LSQ 的码本数量

• nbits – 每一步的比特数

• search_type – AQ搜索类型

ProductLocalSearchQuantizer()

void init(size_t d, const std::vector<AdditiveQuantizer*> &aqs, Search_type_t search_type)

AdditiveQuantizer *subquantizer(size_t m) const

训练乘积加法量化器。

virtual void train(size_t n, const float *x) override

训练量化器

参数：

x – 训练向量，大小为 n * d

virtual void compute_codes_add_centroids(const float *x, uint8_t *codes, size_t n, const float *centroids = nullptr) const override

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

• centroids – 要添加到 x 的质心，大小为 n * d

void compute_unpacked_codes(const float *x, int32_t *codes, size_t n, const float *centroids = nullptr) const

virtual void decode_unpacked(const int32_t *codes, float *x, size_t n, int64_t ld_codes = -1) const override

解码一组非打包格式的向量

参数：

• codes – 要解码的代码，大小为 n * ld_codes

• x – 输出向量，大小为 n * d

virtual void decode(const uint8_t *codes, float *x, size_t n) const override

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

virtual void compute_LUT(size_t n, const float *xq, float *LUT, float alpha = 1.0f, long ld_lut = -1) const override

计算内积查找表。用于搜索功能。

参数：

• xq – 查询向量，大小 (n, d)

• LUT – 查找表，大小 (n, total_codebook_size)

• alpha – 计算 alpha * 内积

• ld_lut – LUT 的前导维度

void compute_codebook_tables()

uint64_t encode_norm(float norm) const

将范数编码为 norm_bits 位

uint32_t encode_qcint(float x) const

通过非均匀标量量化编码范数

float decode_qcint(uint32_t c) const

通过非均匀标量量化解码范数

void set_derived_values()

训练范数量化器。

void train_norm(size_t n, const float *norms)

inline virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

void pack_codes(size_t n, const int32_t *codes, uint8_t *packed_codes, int64_t ld_codes = -1, const float *norms = nullptr, const float *centroids = nullptr) const

将一系列代码打包为位紧凑格式

参数：

• codes – 要打包的代码，大小为 n * code_size

• packed_codes – 输出位紧凑代码

• ld_codes – 代码的前导维度

• norms – 向量的范数（大小为 n）。如果需要但未提供，将会被计算

• centroids – 要添加到 x 的质心，大小为 n * d

template<bool is_IP, Search_type_t effective_search_type>
float compute_1_distance_LUT(const uint8_t *codes, const float *LUT) const

void decode_64bit(idx_t n, float *x) const

用于解码 64 位字中代码的函数

void knn_centroids_inner_product(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels) const

精确 IP 搜索

void compute_centroid_norms(float *norms) const

对于 L2 搜索，我们需要质心的 L2 范数

参数：

norms – 输出范数表，大小 total_codebook_size

计算欧几里得距离最近的k个质心。

精确 L2 搜索，使用预先计算的范数

公共成员

子向量的数量。

我们将一个向量分割成的子向量的数量

子向量的量化器。

量化器的数量（也即子向量的数量）。

码本数量

每个量化器使用的位数。

每一步的比特数

码本（质心）。

码本

每个码本在 `codebooks` 中的偏移量。

码本 #i 存储在码本表 codebooks 的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size x d

总位数。

总比特数 (索引 + 范数)

范数所用的位数。

为范数分配的比特数

所有码本的总大小。

码本的大小 (向量个数)

是否只使用8位量化器。

是否所有 nbits = 8 (使用更快的解码器)

是否启用详细模式。

训练期间是否输出详细信息？

是否已训练。

是否已训练

范数查找表。

ST_norm_lsq2x4 和 ST_norm_rq2x4 的辅助数据，存储 4 位 fastscan 的码本条目的范数

范数的索引。

存储和搜索范数

质心的范数。

所有码本条目的范数（大小为 total_codebook_size）

码本互乘积。

所有码本条目与之前码本的点积，大小为 sum(codebook_offsets[m] * 2^nbits[m], m=0..M-1)

距离计算时分配的最大内存量（以字节为单位）。

范数和距离矩阵与波束搜索可能会变得很大，因此使用此项来控制可以分配的内存量

搜索类型。

也决定了代码中的内容。

float norm_min = NAN

范数量化的最小值/最大值

float norm_max = NAN

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct ProductResidualQuantizer : public faiss::ProductAdditiveQuantizer

#include <ProductAdditiveQuantizer.h>

Product Residual Quantizer

公共类型

enum Search_type_t

编码搜索的执行方式和向量的编码方式。

值

enumerator ST_decompress

解压缩数据库向量

enumerator ST_LUT_nonorm

使用 LUT，不包含范数（适用于 IP 或归一化向量）

enumerator ST_norm_from_LUT

从查找表计算范数（成本为 O(M^2)）

enumerator ST_norm_float

使用 LUT，并将 float32 范数与向量一起存储

enumerator ST_norm_qint8

使用 LUT，并存储 8bit 量化范数

enumerator ST_norm_qint4

enumerator ST_norm_cqint8

使用 LUT，并存储非均匀量化范数

enumerator ST_norm_cqint4

enumerator ST_norm_lsq2x4

使用 2x4 位 lsq 作为范数量化器（用于快速扫描）

enumerator ST_norm_rq2x4

使用 2x4 位 rq 作为范数量化器（用于快速扫描）

公共函数

ProductResidualQuantizer(size_t d, size_t nsplits, size_t Msub, size_t nbits, Search_type_t search_type = ST_decompress)

Construct a product RQ object.

参数：

• d – 输入向量的维度

• nsplits – 我们将一个向量分割成的子向量的数量

• Msub – number of codebooks of each RQ

• nbits – 每一步的比特数

• search_type – AQ搜索类型

ProductResidualQuantizer()

void init(size_t d, const std::vector<AdditiveQuantizer*> &aqs, Search_type_t search_type)

AdditiveQuantizer *subquantizer(size_t m) const

训练乘积加法量化器。

virtual void train(size_t n, const float *x) override

训练量化器

参数：

x – 训练向量，大小为 n * d

计算代码，并添加质心

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

• centroids – 要添加到 x 的质心，大小为 n * d

计算解包的代码

解码解包的代码

解码一组非打包格式的向量

参数：

• codes – 要解码的代码，大小为 n * ld_codes

• x – 输出向量，大小为 n * d

解码

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

计算查找表（LUT）

计算内积查找表。用于搜索功能。

参数：

• xq – 查询向量，大小 (n, d)

• LUT – 查找表，大小 (n, total_codebook_size)

• alpha – 计算 alpha * 内积

• ld_lut – LUT 的前导维度

void compute_codebook_tables()

uint64_t encode_norm(float norm) const

将范数编码为 norm_bits 位

uint32_t encode_qcint(float x) const

通过非均匀标量量化编码范数

float decode_qcint(uint32_t c) const

通过非均匀标量量化解码范数

void set_derived_values()

训练范数量化器。

void train_norm(size_t n, const float *norms)

inline virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

将代码打包。

将一系列代码打包为位紧凑格式

参数：

• codes – 要打包的代码，大小为 n * code_size

• packed_codes – 输出位紧凑代码

• ld_codes – 代码的前导维度

• norms – 向量的范数（大小为 n）。如果需要但未提供，将会被计算

• centroids – 要添加到 x 的质心，大小为 n * d

模板<bool is_IP, Search_type_t effective_search_type>
计算 1 距离 LUT。

解码 64 位。

用于解码 64 位字中代码的函数

KNN 质心内积。

精确 IP 搜索

计算质心范数。

对于 L2 搜索，我们需要质心的 L2 范数

参数：

norms – 输出范数表，大小 total_codebook_size

KNN 质心 L2。

精确 L2 搜索，使用预先计算的范数

公共成员

分割数量。

我们将一个向量分割成的子向量的数量

量化器。

M。

码本数量

位数。

每一步的比特数

码本。

码本

码本偏移量。

码本 #i 存储在码本表 codebooks 的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size x d

总位数 = 0。

总比特数 (索引 + 范数)

范数位数 = 0。

为范数分配的比特数

total_codebook_size 的大小，初始值为 0。

码本的大小 (向量个数)

指示是否仅使用 8 位量化的布尔值，默认为 false。

是否所有 nbits = 8 (使用更快的解码器)

指示是否启用详细输出的布尔值，默认为 false。

训练期间是否输出详细信息？

指示量化器是否已训练的布尔值，默认为 false。

是否已训练

用于存储范数查找表的 `std::vector`。

ST_norm_lsq2x4 和 ST_norm_rq2x4 的辅助数据，存储 4 位 fastscan 的码本条目的范数

`IndexFlat1D` 类型的范数量化器。

存储和搜索范数

用于存储质心范数的 `std::vector`。

所有码本条目的范数（大小为 total_codebook_size）

用于存储码本互积的 `std::vector`。

所有码本条目与之前码本的点积，大小为 sum(codebook_offsets[m] * 2^nbits[m], m=0..M-1)

用于距离计算的最大内存量，默认为 `5 * (size_t(1) << 30)`。

范数和距离矩阵与波束搜索可能会变得很大，因此使用此项来控制可以分配的内存量

搜索类型。

也决定了代码中的内容。

向量范数的最小值，初始值为 NAN。

范数量化的最小值/最大值

向量范数的最大值，初始值为 NAN。

向量的维度。

输入向量的大小

量化码的大小。

每个索引向量的字节数

结构体 ProductQuantizer，继承自 faiss::Quantizer。

包含头文件 ProductQuantizer.h。

乘积量化器（Product Quantizer）。PQ 使用 k-means 进行训练，以最小化到质心的 L2 距离。 PQ 支持 L2 和内积搜索，但量化误差偏向于 L2 距离。

公共类型

枚举类型 train_type_t，表示训练类型。

初始化。

值

枚举器 Train_default，表示默认训练方式。

枚举器 Train_hot_start，表示热启动训练方式。

质心已初始化。

枚举器 Train_shared，表示跨 PQ 段共享字典的训练方式。

跨 PQ 段共享字典。

枚举器 Train_hypercube，表示使用 nbits-D 超立方体初始化质心的训练方式。

使用 nbits-D 超立方体初始化质心。

枚举器 Train_hypercube_pca。

使用 nbits-D 超立方体初始化质心。

公共函数

内联函数 get_centroids(size_t m, size_t i)。

返回与子向量 m 关联的质心。

常量内联函数 get_centroids(size_t m, size_t i) const。

virtual void train(size_t n, const float *x) override

训练量化器

参数：

x – 训练向量，大小为 n * d

ProductQuantizer(size_t d, size_t M, size_t nbits)

ProductQuantizer()

void set_derived_values()

当 d、M 和 nbits 被设置后，计算派生值

void set_params(const float *centroids, int m)

定义子量化器 m 的质心。

void compute_code(const float *x, uint8_t *code) const

使用乘积量化器量化一个向量。

virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

与 compute_code 相同，适用于多个向量

void compute_codes_with_assign_index(const float *x, uint8_t *codes, size_t n)

使用 assign_index 加速代码分配（非 const，因为索引已更改）

void decode(const uint8_t *code, float *x) const

从给定的代码解码一个向量（如果第三个参数，则解码 n 个向量）

virtual void decode(const uint8_t *code, float *x, size_t n) const override

解码一组向量

参数：

• codes – 输入代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

void compute_code_from_distance_table(const float *tab, uint8_t *code) const

如果我们碰巧预先计算了距离表，那么计算代码会更有效率。

void compute_distance_table(const float *x, float *dis_table) const

计算一个向量的距离表。

x = [x_0 x_1 .. x_(M-1)] 的距离表是一个 M * ksub 矩阵，包含

dis_table (m, j) = || x_m - c_(m, j)||^2，对于 m = 0..M-1 且 j = 0 .. ksub - 1

其中 c_(m, j) 是子量化器 m 的第 j 个质心。

参数：

• x – 输入向量，大小为 d

• dis_table – 输出表，大小为 M * ksub

void compute_inner_prod_table(const float *x, float *dis_table) const

void compute_distance_tables(size_t nx, const float *x, float *dis_tables) const

计算多个向量的距离表

参数：

• nx – 输入向量数

• x – 输入向量，大小为 nx * d

• dis_table – 输出表，大小为 nx * M * ksub

void compute_inner_prod_tables(size_t nx, const float *x, float *dis_tables) const

void search(const float *x, size_t nx, const uint8_t *codes, const size_t ncodes, float_maxheap_array_t *res, bool init_finalize_heap = true) const

执行搜索 (L2 距离)

参数：

• x – 查询向量，大小 nx * d

• nx – 查询向量的数量

• codes – 数据库编码，大小为 ncodes * code_size

• ncodes – 向量的数量

• res – 用于存储结果的堆数组 (nh == nx)

• init_finalize_heap – 初始化堆 (输入) 并排序 (输出) 吗？

void search_ip(const float *x, size_t nx, const uint8_t *codes, const size_t ncodes, float_minheap_array_t *res, bool init_finalize_heap = true) const

与 search 相同, 但使用内积相似度

void compute_sdc_table()

void search_sdc(const uint8_t *qcodes, size_t nq, const uint8_t *bcodes, const size_t ncodes, float_maxheap_array_t *res, bool init_finalize_heap = true) const

void sync_transposed_centroids()

将转置的质心与常规质心同步。如果直接编辑了质心，则需要调用此函数。

void clear_transposed_centroids()

清除转置质心表，以便不再使用。

公共成员

size_t M

子量化器的数量

size_t nbits

每个量化索引的比特数

size_t dsub

每个子向量的维度

size_t ksub

每个子量化器的质心数量

bool verbose

训练期间是否输出详细信息？

train_type_t train_type

ClusteringParameters cp

聚类过程中使用的参数

Index *assign_index

如果非 NULL，则使用此索引进行分配 (大小应为 d / M)

std::vector<float> centroids

质心表，大小为 M * ksub * dsub。布局：(M, ksub, dsub)

std::vector<float> transposed_centroids

转置的质心表，大小为 M * ksub * dsub。布局：(dsub, M, ksub)

std::vector<float> centroids_sq_lengths

质心的平方长度，大小为 M * ksub 布局：(M, ksub)

std::vector<float> sdc_table

对称距离表。

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct PQEncoderGeneric

公共函数

inline PQEncoderGeneric(uint8_t *code, int nbits, uint8_t offset = 0)

inline void encode(uint64_t x)

inline ~PQEncoderGeneric()

公共成员

uint8_t *code

这个向量的代码

uint8_t offset

const int nbits

每个子量化器索引的位数

uint8_t reg

struct PQEncoder8

公共函数

inline PQEncoder8(uint8_t *code, int nbits)

inline void encode(uint64_t x)

公共成员

uint8_t *code

struct PQEncoder16

公共函数

inline PQEncoder16(uint8_t *code, int nbits)

inline void encode(uint64_t x)

公共成员

uint16_t *code

struct PQDecoderGeneric

公共函数

inline PQDecoderGeneric(const uint8_t *code, int nbits)

inline uint64_t decode()

公共成员

const uint8_t *code

uint8_t offset

const int nbits

const uint64_t mask

uint8_t reg

struct PQDecoder8

公共函数

PQDecoder8(const uint8_t *code, int nbits)

uint64_t decode()

公共成员

const uint8_t *code

公共静态属性

static const int nbits = 8

struct PQDecoder16

公共函数

PQDecoder16(const uint8_t *code, int nbits)

uint64_t decode()

公共成员

const uint16_t *code

公共静态属性

static const int nbits = 16

struct Quantizer

#include <Quantizer.h>

量化器对象的一般接口

被 faiss::AdditiveQuantizer、faiss::ProductQuantizer、faiss::ScalarQuantizer 继承

公共函数

Quantizer(size_t d = 0, size_t code_size = 0)

virtual void train(size_t n, const float *x) = 0

训练量化器

参数：

x – 训练向量，大小为 n * d

virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const = 0

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

virtual void decode(const uint8_t *code, float *x, size_t n) const = 0

解码一组向量

参数：

• codes – 输入代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

virtual ~Quantizer()

公共成员

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct ResidualQuantizer : public faiss::AdditiveQuantizer

#include <ResidualQuantizer.h>

每个子量化器具有可变位数的残差量化器

残差质心存储在一个大的累积质心表中。 代码可以表示为大小为 (n, M) 的非压缩表，也可以表示为压缩输出 (n, code_size)。

公共类型

using train_type_t = int

初始化。

enum Search_type_t

编码搜索的执行方式和向量的编码方式。

值

enumerator ST_decompress

解压缩数据库向量

enumerator ST_LUT_nonorm

使用 LUT，不包含范数（适用于 IP 或归一化向量）

enumerator ST_norm_from_LUT

从查找表计算范数（成本为 O(M^2)）

enumerator ST_norm_float

使用 LUT，并将 float32 范数与向量一起存储

enumerator ST_norm_qint8

使用 LUT，并存储 8bit 量化范数

枚举值 ST_norm_qint4

枚举值 ST_norm_cqint8

使用 LUT，并存储非均匀量化范数

枚举值 ST_norm_cqint4

枚举值 ST_norm_lsq2x4

使用 2x4 位 lsq 作为范数量化器（用于快速扫描）

枚举值 ST_norm_rq2x4

使用 2x4 位 rq 作为范数量化器（用于快速扫描）

公共函数

ResidualQuantizer(size_t d, const std::vector<size_t> &nbits, Search_type_t search_type = ST_decompress)

ResidualQuantizer(size_t d, size_t M, size_t nbits, Search_type_t search_type = ST_decompress)

ResidualQuantizer()

virtual void train(size_t n, const float *x) override

训练残差量化器。

void initialize_from(const ResidualQuantizer &other, int skip_M = 0)

从 other 复制 M 个码本级别，从 skip_M 开始。

float retrain_AQ_codebook(size_t n, const float *x)

编码向量并计算使这些代码上的量化误差最小化的码本

参数：

• x – 训练向量，大小为 n * d

• n – 训练向量的数量，n >= total_codebook_size

返回值：

返回具有旧代码的新码本的量化误差

virtual void compute_codes_add_centroids(const float *x, uint8_t *codes, size_t n, const float *centroids = nullptr) const override

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

• centroids – 要添加到 x 的质心，大小为 n * d

void refine_beam(size_t n, size_t beam_size, const float *residuals, int new_beam_size, int32_t *new_codes, float *new_residuals = nullptr, float *new_distances = nullptr) const

低级别编码函数

参数：

• n – 要处理的向量数

• residuals – 要编码的向量，大小为 (n, beam_size, d)

• beam_size – 输入束大小

• new_beam_size – 输出束大小（应 <= K * beam_size）

• new_codes – 输出代码，大小为 (n, new_beam_size, m + 1)

• new_residuals – 输出残差，大小为 (n, new_beam_size, d)

• new_distances – 输出距离，大小为 (n, new_beam_size)

void refine_beam_LUT(size_t n, const float *query_norms, const float *query_cp, int new_beam_size, int32_t *new_codes, float *new_distances = nullptr) const

size_t memory_per_point(int beam_size = -1) const

Beam search 会消耗大量内存。此函数估计 refine_beam 使用的内存量以调整批处理大小

参数：

beam_size – 如果 != -1，则覆盖 beam size

void compute_codebook_tables()

uint64_t encode_norm(float norm) const

将范数编码为 norm_bits 位

uint32_t encode_qcint(float x) const

通过非均匀标量量化编码范数

float decode_qcint(uint32_t c) const

通过非均匀标量量化解码范数

void set_derived_values()

训练范数量化器。

void train_norm(size_t n, const float *norms)

inline virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

量化一组向量

参数：

• x – 输入向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

void pack_codes(size_t n, const int32_t *codes, uint8_t *packed_codes, int64_t ld_codes = -1, const float *norms = nullptr, const float *centroids = nullptr) const

将一系列代码打包为位紧凑格式

参数：

• codes – 要打包的代码，大小为 n * code_size

• packed_codes – 输出位紧凑代码

• ld_codes – 代码的前导维度

• norms – 向量的范数（大小为 n）。如果需要但未提供，将会被计算

• centroids – 要添加到 x 的质心，大小为 n * d

virtual void decode(const uint8_t *codes, float *x, size_t n) const override

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

virtual void decode_unpacked(const int32_t *codes, float *x, size_t n, int64_t ld_codes = -1) const

解码一组非打包格式的向量

参数：

• codes – 要解码的代码，大小为 n * ld_codes

• x – 输出向量，大小为 n * d

template<bool is_IP, Search_type_t effective_search_type>
float compute_1_distance_LUT(const uint8_t *codes, const float *LUT) const

void decode_64bit(idx_t n, float *x) const

用于解码 64 位字中代码的函数

virtual void compute_LUT(size_t n, const float *xq, float *LUT, float alpha = 1.0f, long ld_lut = -1) const

计算内积查找表。在质心搜索函数中使用。

参数：

• xq – 查询向量，大小 (n, d)

• LUT – 查找表，大小 (n, total_codebook_size)

• alpha – 计算 alpha * 内积

• ld_lut – LUT 的前导维度

void knn_centroids_inner_product(idx_t n, const float *xq, idx_t k, float *distances, idx_t *labels) const

精确 IP 搜索

计算质心范数。

对于 L2 搜索，我们需要质心的 L2 范数

参数：

norms – 输出范数表，大小 total_codebook_size

计算L2距离的k近邻质心。

精确 L2 搜索，使用预先计算的范数

公共成员

训练类型。

以下 Train_* 标志的二进制或运算。

int niter_codebook_refine = 5

码本细化的迭代次数。

int max_beam_size = 5

用于训练和编码的束大小。

int use_beam_LUT = 0

使用 LUT 进行束搜索。

ApproxTopK_mode_t approx_topk_mode = ApproxTopK_mode_t::EXACT_TOPK

当前使用的近似最小k计算模式。默认值为 EXACT_TOPK。

ProgressiveDimClusteringParameters cp

聚类参数。

ProgressiveDimIndexFactory *assign_index_factory = nullptr

如果非 NULL，则使用此索引进行分配。

M

码本数量

每个子量化器的位数。

每一步的比特数

码本。

码本

码本偏移量。

码本 #i 存储在码本表 codebooks 的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size x d

总位数。

总比特数 (索引 + 范数)

范数位数。

为范数分配的比特数

size_t total_codebook_size = 0

码本的大小 (向量个数)

总码本大小 size_t

是否所有 nbits = 8 (使用更快的解码器)

bool only_8bit = false

训练期间是否输出详细信息？

是否只使用 8 位 bool

是否已训练

bool verbose = false

ST_norm_lsq2x4 和 ST_norm_rq2x4 的辅助数据，存储 4 位 fastscan 的码本条目的范数

是否输出详细信息 bool

存储和搜索范数

bool is_trained = false

所有码本条目的范数（大小为 total_codebook_size）

是否已训练 bool

所有码本条目与之前码本的点积，大小为 sum(codebook_offsets[m] * 2^nbits[m], m=0..M-1)

std::vector<float> norm_tabs

范数和距离矩阵与波束搜索可能会变得很大，因此使用此项来控制可以分配的内存量

范数表 std::vector<float>

也决定了代码中的内容。

IndexFlat1D qnorm

范数量化的最小值/最大值

量化的范数 IndexFlat1D

std::vector<float> centroid_norms

输入向量的大小

质心范数 std::vector<float>

每个索引向量的字节数

公共静态属性

std::vector<float> codebook_cross_products

码本交叉乘积 std::vector<float>

size_t max_mem_distances = 5 * (size_t(1) << 30)

最大内存距离 size_t

Search_type_t search_type

搜索类型 Search_type_t

float norm_min = NAN

最小范数 float

float norm_max = NAN

最大范数 float

size_t d
维度 size_t

公共函数

inline explicit BlockResultHandler(size_t nq, const IDSelector *sel = nullptr)

inline virtual void begin_multiple(size_t i0_2, size_t i1_2)

inline virtual void add_results(size_t, size_t, const typename C::T*)

inline virtual void end_multiple()

inline virtual ~BlockResultHandler()

inline bool is_in_selection(idx_t i) const

公共成员

size_t nq

const IDSelector *sel

size_t i0 = 0

size_t i1 = 0

template<class C, bool use_sel = false>
struct Top1BlockResultHandler : public faiss::BlockResultHandler<C, false>

公共类型

using T = typename C::T

using TI = typename C::TI

公共函数

inline Top1BlockResultHandler(size_t nq, T *dis_tab, TI *ids_tab, const IDSelector *sel = nullptr)

inline virtual void begin_multiple(size_t i0, size_t i1) final

开始

inline void add_results(size_t j0, size_t j1, const T *dis_tab_2) final

为查询 i0..i1 和 j0..j1 添加结果

inline void add_result(const size_t i, const T dis, const TI idx)

inline virtual void add_results(size_t, size_t, const typename C::T*)

inline virtual void end_multiple()

inline bool is_in_selection(idx_t i) const

公共成员

T *dis_tab

TI *ids_tab

size_t nq

const IDSelector *sel

size_t i0

size_t i1

struct SingleResultHandler : public faiss::ResultHandler<C>

公共函数

inline explicit SingleResultHandler(Top1BlockResultHandler &hr)

inline void begin(const size_t current_idx_2)

开始查询 # i 的结果

inline virtual bool add_result(T dis, TI idx) final

为查询 i 添加一个结果

inline void end()

查询 i 的一系列结果已完成

公共成员

Top1BlockResultHandler &hr

TI min_idx

size_t current_idx = 0

C::T threshold = C::neutral()

template<class C, bool use_sel = false>
struct HeapBlockResultHandler : public faiss::BlockResultHandler<C, false>

公共类型

using T = typename C::T

using TI = typename C::TI

公共函数

inline HeapBlockResultHandler(size_t nq, T *heap_dis_tab, TI *heap_ids_tab, size_t k, const IDSelector *sel = nullptr)

inline virtual void begin_multiple(size_t i0_2, size_t i1_2) final

开始

inline void add_results(size_t j0, size_t j1, const T *dis_tab) final

为查询 i0..i1 和 j0..j1 添加结果

inline virtual void end_multiple() final

series of results for queries i0..i1 is done

inline virtual void add_results(size_t, size_t, const typename C::T*)

inline bool is_in_selection(idx_t i) const

公共成员

T *heap_dis_tab

TI *heap_ids_tab

int64_t k

size_t nq

const IDSelector *sel

size_t i0

size_t i1

struct SingleResultHandler : public faiss::ResultHandler<C>

公共函数

inline explicit SingleResultHandler(HeapBlockResultHandler &hr)

inline void begin(size_t i)

开始查询 # i 的结果

inline virtual bool add_result(T dis, TI idx) final

为查询 i 添加一个结果

inline void end()

查询 i 的一系列结果已完成

公共成员

HeapBlockResultHandler &hr

size_t k

T *heap_dis

TI *heap_ids

C::T threshold = C::neutral()

template<class C>
struct ReservoirTopN : public faiss::ResultHandler<C>

#include <ResultHandler.h>

单个查询的容器。

被 faiss::ReservoirBlockResultHandler< C, use_sel >::SingleResultHandler 继承

公共类型

using T = typename C::T

using TI = typename C::TI

公共函数

inline ReservoirTopN()

inline ReservoirTopN(size_t n, size_t capacity, T *vals, TI *ids)

inline virtual bool add_result(T val, TI id) final

inline void add(T val, TI id)

收缩模糊

收缩

转换为结果，参数：heap_dis (距离堆)，heap_ids (ID堆)

公共成员

值

ID

索引 i

数量 n

容量

阈值 = C::neutral()

模板类 ReservoirBlockResultHandler，允许指定 C (类型) 和 use_sel (布尔值，默认为 false)
结构体 ReservoirBlockResultHandler，继承自 BlockResultHandler<C, false>

公共类型

类型别名 T = C::T

类型别名 TI = C::TI

公共函数

构造函数：参数 nq (查询数量), heap_dis_tab (距离堆表), heap_ids_tab (ID堆表), k (k近邻), sel (ID选择器，默认为 nullptr)

开始处理多个结果：参数 i0_2 (起始索引), i1_2 (结束索引)

开始

添加结果：参数 j0 (起始索引), j1 (结束索引), dis_tab (距离表)

为查询 i0..i1 和 j0..j1 添加结果

结束处理多个结果

series of results for queries i0..i1 is done

添加结果 (BlockResultHandler的虚函数)

判断索引是否在选择器中 (BlockResultHandler的虚函数): 参数 i (索引)

公共成员

距离堆表

ID堆表

k 近邻数量

size_t capacity

std::vector<T> reservoir_dis

std::vector<TI> reservoir_ids

std::vector<ReservoirTopN<C>> reservoirs

size_t nq

const IDSelector *sel

size_t i0

size_t i1

struct SingleResultHandler : public faiss::ReservoirTopN<C>

公共类型

using T = typename C::T

using TI = typename C::TI

公共函数

inline explicit SingleResultHandler(ReservoirBlockResultHandler &hr)

inline void begin(size_t qno_2)

开始查询 # i 的结果

inline void end()

query qno的一系列结果已完成

inline virtual bool add_result(T val, TI id) final

inline void add(T val, TI id)

inline void shrink_fuzzy()

inline void shrink()

inline void to_result(T *heap_dis, TI *heap_ids) const

公共成员

hr：指向ReservoirBlockResultHandler的引用。

reservoir_dis：类型为T的距离向量。

reservoir_ids：类型为TI的ID向量。

qno：查询编号（size_t 类型）。

vals：指向类型为T的值数组的指针。

ids：指向类型为TI的ID数组的指针。

i：当前索引（size_t 类型）。

size_t n

size_t capacity

C::T threshold = C::neutral()

template<class C, bool use_sel = false>
struct RangeSearchBlockResultHandler : public faiss::BlockResultHandler<C, false>

公共类型

using T = typename C::T

using TI = typename C::TI

公共函数

inline RangeSearchBlockResultHandler(RangeSearchResult *res, float radius, const IDSelector *sel = nullptr)

inline virtual void begin_multiple(size_t i0_2, size_t i1_2)

开始

inline void add_results(size_t j0, size_t j1, const T *dis_tab)

为查询 i0..i1 和 j0..j1 添加结果

inline ~RangeSearchBlockResultHandler()

inline virtual void add_results(size_t, size_t, const typename C::T*)

inline virtual void end_multiple()

inline bool is_in_selection(idx_t i) const

公共成员

RangeSearchResult *res

T radius

std::vector<RangeSearchPartialResult*> partial_results

std::vector<size_t> j0s

int pr = 0

size_t nq

const IDSelector *sel

size_t i0

size_t i1

struct SingleResultHandler : public faiss::ResultHandler<C>

公共函数

inline explicit SingleResultHandler(RangeSearchBlockResultHandler &rh)

inline void begin(size_t i)

开始查询 # i 的结果

inline virtual bool add_result(T dis, TI idx) final

为查询 i 添加一个结果

inline void end()

查询 i 的一系列结果已完成

inline ~SingleResultHandler()

公共成员

RangeSearchPartialResult pres

RangeQueryResult *qr = nullptr

C::T threshold = C::neutral()

struct ScalarQuantizer : public faiss::Quantizer

#include <ScalarQuantizer.h>

The uniform quantizer has a range [vmin, vmax]. The range can be the same for all dimensions (uniform) or specific per dimension (default).

公共类型

enum QuantizerType

值

enumerator QT_8bit

8 bits per component

enumerator QT_4bit

4 bits per component

enumerator QT_8bit_uniform

same, shared range for all dimensions

enumerator QT_4bit_uniform

enumerator QT_fp16

enumerator QT_8bit_direct

fast indexing of uint8s

enumerator QT_6bit

6 bits per component

enumerator QT_bf16

enumerator QT_8bit_direct_signed

fast indexing of signed int8s ranging from [-128 to 127]

enum RangeStat

The uniform encoder can estimate the range of representable values of the unform encoder using different statistics. Here rs = rangestat_arg

值

枚举值 RS_minmax

[min - rs*(max-min), max + rs*(max-min)]

枚举值 RS_meanstd

[mean - std * rs, mean + std * rs]

枚举值 RS_quantiles

[Q(rs), Q(1-rs)]

枚举值 RS_optim

重建误差的交替优化

公共函数

ScalarQuantizer(size_t d, QuantizerType qtype)

ScalarQuantizer()

void set_derived_sizes()

基于 qtype 和 d 更新内部值

virtual void train(size_t n, const float *x) override

训练量化器

参数：

x – 训练向量，大小为 n * d

virtual void compute_codes(const float *x, uint8_t *codes, size_t n) const override

编码一组向量

参数：

• x – 要编码的向量，大小为 n * d

• codes – 输出编码，大小为 n * code_size

virtual void decode(const uint8_t *code, float *x, size_t n) const override

解码一组向量

参数：

• codes – 要解码的代码，大小为 n * code_size

• x – 输出向量，大小为 n * d

SQuantizer *select_quantizer() const

SQDistanceComputer *get_distance_computer(MetricType metric = METRIC_L2) const

InvertedListScanner *select_InvertedListScanner(MetricType mt, const Index *quantizer, bool store_pairs, const IDSelector *sel, bool by_residual = false) const

公共成员

QuantizerType qtype = QT_8bit

RangeStat rangestat = RS_minmax

float rangestat_arg = 0

size_t bits = 0

每个标量代码的位数

std::vector<float> trained

训练后的值（包括范围）

size_t d

输入向量的大小

size_t code_size

每个索引向量的字节数

struct SQDistanceComputer : public faiss::FlatCodesDistanceComputer

公共函数

inline SQDistanceComputer()

virtual float query_to_code(const uint8_t *code) const = 0

inline virtual float distance_to_code(const uint8_t *code) final

compute distance of current query to an encoded vector

inline virtual float operator()(idx_t i) override

计算向量 i 到当前查询的距离

virtual void set_query(const float *x) = 0

在计算距离之前被调用。 指针 x 在 operator () 被调用时应该保持有效。

inline virtual void distances_batch_4(const idx_t idx0, const idx_t idx1, const idx_t idx2, const idx_t idx3, float &dis0, float &dis1, float &dis2, float &dis3)

计算当前查询到 4 个存储向量的距离。 某些 DistanceComputer 实现可能极大地受益于此。

virtual float symmetric_dis(idx_t i, idx_t j) = 0

计算两个存储向量之间的距离

公共成员

const float *q

const uint8_t *codes

size_t code_size

struct SQuantizer

公共函数

virtual void encode_vector(const float *x, uint8_t *code) const = 0

对向量进行解码

SQuantizer 的析构函数

SIMD 结果处理器结构体

被以下类继承：faiss::SIMDResultHandlerToFloat, faiss::simd_result_handlers::DummyResultHandler, faiss::simd_result_handlers::FixedStorageHandler< NQ, BB >, faiss::simd_result_handlers::StoreResultHandler

公共函数

处理函数

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

设置块原点

设置正在计算的子矩阵

SIMDResultHandler 的析构函数

公共成员

是否使用 CMax

ID 的大小

是否使用字段

SIMD 结果处理器到浮点结构体

被以下类继承：faiss::simd_result_handlers::ResultHandlerCompare< C, false >, faiss::simd_result_handlers::ResultHandlerCompare< C, with_id_map >

公共函数

SIMDResultHandlerToFloat 的构造函数

开始处理

结束处理

处理函数

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

设置块原点

设置正在计算的子矩阵

公共成员

查询的数量

总数量

ID 映射

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<typename IndexT>
class ThreadedIndex : public IndexT

#include <ThreadedIndex.h>

线程集合中索引的持有者。 此类本身的接口不是线程安全的

被 faiss::IndexReplicasTemplate< IndexT >, faiss::IndexShardsTemplate< IndexT > 继承

公共函数

explicit ThreadedIndex(bool threaded)

explicit ThreadedIndex(int d, bool threaded)

~ThreadedIndex() override

virtual void addIndex(IndexT *index)

覆盖我们自己管理的索引。警告：一旦添加了索引，在关闭之前，从管理它的线程之外的任何其他线程触摸它都是不安全的。 使用 runOnIndex 在其上执行工作。

void removeIndex(IndexT *index)

删除我们自己管理的索引。 这将刷新该索引上的所有待处理工作，然后关闭其管理线程，并删除索引。

void runOnIndex(std::function<void(int, IndexT*)> f)

在索引的管理线程中，在所有索引上运行一个函数。 函数参数是（集合中的索引，索引指针）

void runOnIndex(std::function<void(int, const IndexT*)> f) const

void reset() override

faiss::Index API。 所有索引都收到相同的调用

inline int count() const

返回子索引的数量。

inline IndexT *at(size_t i)

返回第 i 个子索引。

inline const IndexT *at(size_t i) const

返回第 i 个子索引（const 版本）

公共成员

bool own_indices = false

我们是否负责删除包含的索引。

受保护的函数

virtual void onAfterAddIndex(IndexT *index)

在添加索引后立即调用。

virtual void onAfterRemoveIndex(IndexT *index)

在索引被移除后立即调用。

受保护的属性

std::vector<std::pair<IndexT*, std::unique_ptr<WorkerThread>>> indices_

Index 实例的集合，以及管理它们的工作线程（如果有）。

bool isThreaded_

这个索引是多线程的吗？

受保护的静态函数

static void waitAndHandleFutures(std::vector<std::future<bool>> &v)

struct SearchParameters

#include <Index.h>

可选搜索参数的父类。

具有额外搜索参数的子类应继承此类。对象字段的所有权始终属于调用者。

被 faiss::IndexRefineSearchParameters, faiss::SearchParametersHNSW, faiss::SearchParametersIVF, faiss::SearchParametersPQ, faiss::SearchParametersPreTransform, faiss::SearchParametersResidualCoarseQuantizer, faiss::gpu::SearchParametersCagra 继承

公共函数

inline virtual ~SearchParameters()

确保我们可以 dynamic_cast 这个

公共成员

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct Index

#include <Index.h>

索引的抽象结构，支持添加向量和搜索它们。

所有在添加或搜索时提供的向量都是 32 位浮点数组，尽管内部表示可能不同。

被 faiss::AdditiveCoarseQuantizer, faiss::IndexFastScan, faiss::IndexFlatCodes, faiss::IndexHNSW, faiss::IndexIVF, faiss::IndexIVFIndependentQuantizer, faiss::IndexNNDescent, faiss::IndexNSG, faiss::IndexPreTransform, faiss::IndexRandom, faiss::IndexRefine, faiss::IndexRowwiseMinMaxBase, faiss::IndexSplitVectors, faiss::MultiIndexQuantizer, faiss::gpu::GpuIndex 继承

公共类型

using component_t = float

using distance_t = float

公共函数

inline explicit Index(idx_t d = 0, MetricType metric = METRIC_L2)

virtual ~Index()

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add(idx_t n, const float *x) = 0

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const = 0

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reset() = 0

从数据库中删除所有元素。

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct Index2Layer : public faiss::IndexFlatCodes

#include <Index2Layer.h>

与 IndexIVFPQ 类似，但不包含倒排列表：编码以顺序方式存储。

该类主要用于存储可以随机访问的编码向量，未实现搜索功能。

公共类型

using component_t = float

using distance_t = float

公共函数

Index2Layer(Index *quantizer, size_t nlist, int M, int nbit = 8, MetricType metric = METRIC_L2)

Index2Layer()

~Index2Layer()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

未实现

virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void transfer_to_IVFPQ(IndexIVFPQ &other) const

将平面代码传输到 IVFPQ 索引

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

Level1Quantizer q1

第一层量化器

ProductQuantizer pq

第二层量化器总是一个 PQ

size_t code_size_1

第一层代码的大小 (ceil(log8(q1.nlist)))

size_t code_size_2

第二层代码的大小

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexAdditiveQuantizer : public faiss::IndexFlatCodes

#include <IndexAdditiveQuantizer.h>

additive 量化器的抽象类。搜索函数是通用的。

被以下类继承：faiss::IndexLocalSearchQuantizer, faiss::IndexProductLocalSearchQuantizer, faiss::IndexProductResidualQuantizer, faiss::IndexResidualQuantizer

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

explicit IndexAdditiveQuantizer(idx_t d, AdditiveQuantizer *aq, MetricType metric = METRIC_L2)

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

reconstruct_batch 函数

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

search_and_reconstruct 函数

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

compute_residual 函数

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

compute_residual_n 函数

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

aq: 指向 AdditiveQuantizer 对象的指针。

code_size: 每个码的大小（以字节为单位）。

codes: 存储编码的向量。

编码后的数据集，大小为 ntotal * code_size

d: 向量的维度。

向量维度

ntotal: 索引中的向量总数。

索引向量的总数

verbose: 是否启用详细输出。

详细级别

is_trained: 索引是否已训练。

如果 Index 不需要训练，或者如果已经完成训练，则设置

metric_type: 使用的度量类型。

此索引用于搜索的度量类型

metric_arg: 度量参数（如果需要）。

度量类型的参数

IndexResidualQuantizer: 基于残差量化器的 Index。

#include <IndexAdditiveQuantizer.h>

基于残差量化器的 Index。 存储的向量通过残差量化码进行近似。 也可以用作编解码器。

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexResidualQuantizer(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

IndexResidualQuantizer(int d, const std::vector<size_t> &nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

IndexResidualQuantizer()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

添加向量。

默认的 add 使用 sa_encode

重置索引。

从数据库中删除所有元素。

重建指定范围内的向量。

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

重建指定键值的向量。

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

返回辅助代码的大小。

生成的代码的大小（以字节为单位）

根据 ID 选择器移除向量。

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

调整条目顺序。

添加带有ID的向量。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

将向量分配到簇。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

重建一批向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

搜索并重建向量。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

计算残差向量。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算 n 个向量的残差向量。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

用于编码向量的残差量化器。

用于编码向量的残差量化器。

AdditiveQuantizer *aq

码的大小。

码的集合。

编码后的数据集，大小为 ntotal * code_size

向量的维度。

向量维度

faiss::IndexResidualQuantizer::ntotal目标ID=“structfaiss_1_1Index_1a6970683faa021b7a6f1a0865c0d4eccd”>idx_t ntotal

索引向量的总数

faiss::IndexResidualQuantizer::verbose目标ID=“structfaiss_1_1Index_1a5590d847c5c2b958affd2a05e58a6f23”>bool verbose

详细级别

faiss::IndexResidualQuantizer::is_trained目标ID=“structfaiss_1_1Index_1a6e92732617c4dbe364e7678dd8773a7f”>bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

faiss::IndexResidualQuantizer::metric_type目标ID=“structfaiss_1_1Index_1a8e18f641854b2bde83ecff0a2f9a6f4e”>MetricType metric_type

此索引用于搜索的度量类型

faiss::IndexResidualQuantizer::metric_arg目标ID=“structfaiss_1_1Index_1a6f60646d6877658ea4df05e0231ed232”>float metric_arg

度量类型的参数

struct IndexLocalSearchQuantizer : public faiss::IndexAdditiveQuantizer

公共类型

using Search_type_t = faiss::AdditiveQuantizer::Search_type_t

使用 component_t = float

使用 distance_t = float

公共函数

IndexLocalSearchQuantizer(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = faiss::AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

IndexLocalSearchQuantizer()

虚函数 void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

虚函数 void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

虚函数 void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

LocalSearchQuantizer lsq

AdditiveQuantizer *aq

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexProductResidualQuantizer : public faiss::IndexAdditiveQuantizer

#include <IndexAdditiveQuantizer.h>

基于乘积残差量化器的 Index。

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexProductResidualQuantizer(int d, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• nsplits – 残差量化器的数量

• Msub – 每个RQ的子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• nsplits – 残差量化器的数量

• Msub – 每个RQ的子量化器的数量

• nbits – 每个子向量索引的比特数

IndexProductResidualQuantizer()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

执行范围搜索。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

获取代码打包器。

检查是否与其他索引兼容，以便合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

从另一个索引合并数据。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

添加带ID的紧凑码 (Short Array Codes)。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

置换条目。

添加向量，带ID。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

分配向量到最近的簇。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

ProductResidualQuantizer prq

用于编码向量的乘积残差量化器。

AdditiveQuantizer *aq

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexProductLocalSearchQuantizer : public faiss::IndexAdditiveQuantizer

#include <IndexAdditiveQuantizer.h>

基于乘积局部搜索量化器的Index。

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

使用 component_t = float

使用 distance_t = float

公共函数

IndexProductLocalSearchQuantizer(int d, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• nsplits – 局部搜索量化器的数量

• Msub – 每个 LSQ 的子量化器数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• nsplits – 局部搜索量化器的数量

• Msub – 每个 LSQ 的子量化器数量

• nbits – 每个子向量索引的比特数

IndexProductLocalSearchQuantizer()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtualvoidreconstruct(idx_tkey, float *recons)const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtualsize_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtualsize_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inlinevirtualDistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

ProductLocalSearchQuantizer plsq

用于编码向量的乘积局部搜索量化器。

AdditiveQuantizer *aq

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct AdditiveCoarseQuantizer : public faiss::Index

#include <IndexAdditiveQuantizer.h>

一种“虚拟”索引，其中的元素是残差量化器的质心。

旨在用作 IndexIVF 中的粗量化器。

被 faiss::LocalSearchCoarseQuantizer, faiss::ResidualCoarseQuantizer 继承

公共类型

using component_t = float

using distance_t = float

公共函数

显式 AdditiveCoarseQuantizer(idx_t d = 0, AdditiveQuantizer *aq = nullptr, MetricType metric = METRIC_L2)

virtual void add(idx_t n, const float *x) override

不适用。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void reset() override

不适用。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查两个索引是否兼容以进行合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加子分配码 (sub-assignment codes) 到索引中。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

附加量化器。

std::vector<float> centroid_norms

质心的范数，用于 knn 搜索。

向量的维度。

向量维度

索引中的向量总数。

索引向量的总数

如果为 true，则启用详细输出。

详细级别

如果索引经过训练，则为 true。

如果 Index 不需要训练，或者如果已经完成训练，则设置

索引使用的度量类型。

此索引用于搜索的度量类型

度量函数的参数 (如果需要)。

度量类型的参数

残差粗量化器的搜索参数。

公共函数

析构函数。

公共成员

波束因子，用于加速搜索。

ID 选择器。

如果非空，则仅在搜索期间考虑这些 ID。

struct ResidualCoarseQuantizer : public faiss::AdditiveCoarseQuantizer

#include <IndexAdditiveQuantizer.h>

ResidualCoarseQuantizer 与默认的 AdditiveCoarseQuantizer 相比有点特殊，因为它可以在搜索时使用波束搜索（速度慢，但对于非常大的词汇表可能有用）。

公共类型

组件类型。

距离类型。

公共函数

void set_beam_factor(float new_beam_factor)

如果需要，计算质心范数。

ResidualCoarseQuantizer(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

ResidualCoarseQuantizer(int d, const std::vector<size_t> &nbits, MetricType metric = METRIC_L2)

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

void initialize_from(const ResidualCoarseQuantizer &other)

从 other 复制前 M 个码本级别。 用于将 ResidualQuantizer 裁剪到其前 M 个量化器。

ResidualCoarseQuantizer()

virtual void add(idx_t n, const float *x) override

不适用。

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void reset() override

不适用。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

ResidualQuantizer rq

用于编码向量的残差量化器。

float beam_factor = 4.0f

beam 大小和搜索 k 之间的因子。如果为负数，则使用精确的搜索到质心的方法

AdditiveQuantizer *aq

std::vector<float> centroid_norms

质心的范数，用于 knn 搜索。

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct LocalSearchCoarseQuantizer : public faiss::AdditiveCoarseQuantizer

公共类型

using component_t = float

using distance_t = float

公共函数

LocalSearchCoarseQuantizer(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

LocalSearchCoarseQuantizer()

virtual void add(idx_t n, const float *x) override

不适用。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

reset() override

不适用。

add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

LocalSearchQuantizer lsq

用于编码向量的残差量化器。

AdditiveQuantizer *aq

std::vector<float> centroid_norms

质心的范数，用于 knn 搜索。

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexAdditiveQuantizerFastScan : public faiss::IndexFastScan

#include <IndexAdditiveQuantizerFastScan.h>

IndexAQ 的快速扫描版本。目前适用于 4 位 AQ。

代码不是按顺序存储的，而是分组在大小为 bbs 的块中。这使得可以使用 SIMD 指令快速计算距离。

实现：12：带有 Q 内部循环的块循环，qbs 为 13：与存储结果的储层累加器相同 14：没有带堆累加器的 qbs 15：没有带储层累加器的 qbs

由 faiss::IndexLocalSearchQuantizerFastScan, faiss::IndexProductLocalSearchQuantizerFastScan, faiss::IndexProductResidualQuantizerFastScan, faiss::IndexResidualQuantizerFastScan 子类化

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

explicit IndexAdditiveQuantizerFastScan(AdditiveQuantizer *aq, MetricType metric = METRIC_L2, int bbs = 32)

void init(AdditiveQuantizer *aq, MetricType metric = METRIC_L2, int bbs = 32)

IndexAdditiveQuantizerFastScan()

~IndexAdditiveQuantizerFastScan() override

explicit IndexAdditiveQuantizerFastScan(const IndexAdditiveQuantizer &orig, int bbs = 32)

从现有 IndexAQ 构建

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

void estimate_norm_scale(idx_t n, const float *x)

virtual void compute_codes(uint8_t *codes, idx_t n, const float *x) const override

virtual void compute_float_LUT(float *lut, idx_t n, const float *x) const override

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量。

注意：IndexAdditiveQuantizerFastScan 对象中的代码是非连续的。但是此方法需要连续的表示形式。

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * code_size

• x – 输出向量，大小为 n * d

void init_fastscan(int d, size_t M, size_t nbits, MetricType metric, int bbs)

virtual void reset() override

从数据库中删除所有元素。

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

void compute_quantized_LUT(idx_t n, const float *x, uint8_t *lut, float *normalizers) const

template<bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

template<class C>
void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids(const IDSelector &sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

CodePacker *get_CodePacker() const

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

对输入向量进行编码，并将结果存储到字节数组中。

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

添加通过 `sa_encode` 编码的码字到索引中。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

加性量化器对象。

是否重新缩放向量的范数。

int norm_scale = 1

size_t max_train_points = 0

int implem = 0

int skip = 0

int bbs

int qbs = 0

size_t M

size_t nbits

size_t ksub

size_t code_size

size_t ntotal2

size_t M2

AlignedTable<uint8_t> codes

const uint8_t *orig_codes = nullptr

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexResidualQuantizerFastScan : public faiss::IndexAdditiveQuantizerFastScan

#include <IndexAdditiveQuantizerFastScan.h>

基于残差量化器的 Index。 存储的向量通过残差量化码进行近似。 也可以用作编解码器。

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexResidualQuantizerFastScan(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_rq2x4, int bbs = 32)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• metric – metric type

• search_type – AQ搜索类型

IndexResidualQuantizerFastScan()

void init(AdditiveQuantizer *aq, MetricType metric = METRIC_L2, int bbs = 32)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

void estimate_norm_scale(idx_t n, const float *x)

virtual void compute_codes(uint8_t *codes, idx_t n, const float *x) const override

virtual void compute_float_LUT(float *lut, idx_t n, const float *x) const override

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量。

注意：IndexAdditiveQuantizerFastScan 对象中的代码是非连续的。但是此方法需要连续的表示形式。

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * code_size

• x – 输出向量，大小为 n * d

void init_fastscan(int d, size_t M, size_t nbits, MetricType metric, int bbs)

virtual void reset() override

从数据库中删除所有元素。

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

void compute_quantized_LUT(idx_t n, const float *x, uint8_t *lut, float *normalizers) const

template<bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

template<class C>
void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids(const IDSelector &sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

CodePacker *get_CodePacker() const

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

ResidualQuantizer rq

用于编码向量的残差量化器。

AdditiveQuantizer *aq

bool rescale_norm = true

int norm_scale = 1

size_t max_train_points = 0

int implem = 0

int skip = 0

int bbs

int qbs = 0

size_t M

size_t nbits

size_t ksub

size_t code_size

size_t ntotal2

size_t M2

AlignedTable<uint8_t> codes

const uint8_t *orig_codes = nullptr

维度

向量维度

索引中的向量总数

索引向量的总数

是否启用详细输出

详细级别

索引是否已训练

如果 Index 不需要训练，或者如果已经完成训练，则设置

使用的距离度量类型

此索引用于搜索的度量类型

距离度量的参数（如果需要）

度量类型的参数

基于局部搜索量化器的 Index。存储的向量通过局部搜索量化码近似。 也可以用作编解码器

#include <IndexAdditiveQuantizerFastScan.h>

基于局部搜索量化器的索引。 存储的向量通过局部搜索量化码近似。 也可以用作编解码器

公共类型

搜索类型类型定义

组件类型定义 (float)

距离类型定义 (float)

公共函数

构造函数

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

• metric – metric type

• search_type – AQ搜索类型

默认构造函数

初始化索引

训练索引

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

估计归一化比例

计算向量的代码

计算浮点查找表 (LUT)

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量。

注意：IndexAdditiveQuantizerFastScan 对象中的代码是非连续的。但是此方法需要连续的表示形式。

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * code_size

• x – 输出向量，大小为 n * d

void init_fastscan(int d, size_t M, size_t nbits, MetricType metric, int bbs)

virtual void reset() override

从数据库中删除所有元素。

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

void compute_quantized_LUT(idx_t n, const float *x, uint8_t *lut, float *normalizers) const

template<bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12 ( idx_t n, const float * x, idx_t k, float * distances, idx_t * labels, int impl, const NormTableScaler * scaler ) const

template<class C>
void search_implem_14 ( idx_t n, const float * x, idx_t k, float * distances, idx_t * labels, int impl, const NormTableScaler * scaler ) const

虛擬 void 重建(idx_t 键, float* 重建) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

虛擬 size_t 移除ID(const IDSelector& sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

代碼打包器* 取得代碼打包器() const

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

LocalSearchQuantizer lsq

AdditiveQuantizer *aq

bool rescale_norm = true

int norm_scale = 1

size_t max_train_points = 0

int implem = 0

int skip = 0

int bbs

int qbs = 0

size_t M

size_t nbits

size_t ksub

size_t code_size

size_t ntotal2

size_t M2

AlignedTable<uint8_t> codes

const uint8_t *orig_codes = nullptr

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexProductResidualQuantizerFastScan : public faiss::IndexAdditiveQuantizerFastScan

#include <IndexAdditiveQuantizerFastScan.h>

基于乘积残差量化器的Index。 存储的向量通过乘积残差量化代码近似。 也可以用作编解码器

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexProductResidualQuantizerFastScan(int d, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_rq2x4, int bbs = 32)

构造函数。

参数：

• d – 输入向量的维度

• nsplits – 残差量化器的数量

• Msub – 每个RQ的子量化器的数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• nsplits – 残差量化器的数量

• Msub – 每个RQ的子量化器的数量

• nbits – 每个子向量索引的比特数

• metric – metric type

• search_type – AQ搜索类型

IndexProductResidualQuantizerFastScan()

void init(AdditiveQuantizer *aq, MetricType metric = METRIC_L2, int bbs = 32)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

void estimate_norm_scale(idx_t n, const float *x)

virtual void compute_codes(uint8_t *codes, idx_t n, const float *x) const override

virtual void compute_float_LUT(float *lut, idx_t n, const float *x) const override

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量。

注意：IndexAdditiveQuantizerFastScan 对象中的代码是非连续的。但是此方法需要连续的表示形式。

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * code_size

• x – 输出向量，大小为 n * d

void init_fastscan(int d, size_t M, size_t nbits, MetricType metric, int bbs)

virtual void reset() override

从数据库中删除所有元素。

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

void compute_quantized_LUT(idx_t n, const float *x, uint8_t *lut, float *normalizers) const

template<bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

template<class C>
void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids(const IDSelector &sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

CodePacker *get_CodePacker() const

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

ProductResidualQuantizer prq

用于编码向量的乘积残差量化器。

AdditiveQuantizer *aq

bool rescale_norm = true

int norm_scale = 1

size_t max_train_points = 0

int implem = 0

int skip = 0

int bbs

int qbs = 0

size_t M

size_t nbits

size_t ksub

size_t code_size

size_t ntotal2

size_t M2

AlignedTable<uint8_t> codes

const uint8_t *orig_codes = nullptr

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexProductLocalSearchQuantizerFastScan : public faiss::IndexAdditiveQuantizerFastScan

#include <IndexAdditiveQuantizerFastScan.h>

基于产品局部搜索量化器的 Index。存储的向量通过产品局部搜索量化代码进行近似。 也可以用作编解码器

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexProductLocalSearchQuantizerFastScan(int d, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_rq2x4, int bbs = 32)

构造函数。

参数：

• d – 输入向量的维度

• nsplits – 局部搜索量化器的数量

• Msub – 每个 LSQ 的子量化器数量

• nbits – 每个子向量索引的比特数

• d – 输入向量的维度

• nsplits – 局部搜索量化器的数量

• Msub – 每个 LSQ 的子量化器数量

• nbits – 每个子向量索引的比特数

• metric – metric type

• search_type – AQ搜索类型

IndexProductLocalSearchQuantizerFastScan()

void init(AdditiveQuantizer *aq, MetricType metric = METRIC_L2, int bbs = 32)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

估计范数缩放(norm scale)

计算编码(codes)

计算浮点型查找表(look-up table, LUT)

搜索

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

对称算术解码 (Symmetric Arithmetic decode)

解码一组向量。

注意：IndexAdditiveQuantizerFastScan 对象中的代码是非连续的。但是此方法需要连续的表示形式。

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * code_size

• x – 输出向量，大小为 n * d

初始化快速扫描

重置

从数据库中删除所有元素。

添加

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

计算量化的查找表(LUT)

模板 <bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

template<class C>
void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids(const IDSelector &sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

获取码打包器(Code Packer)

从另一个索引合并。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查是否兼容合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

使用ID添加。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

范围搜索。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

分配。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

ProductLocalSearchQuantizer plsq

用于编码向量的乘积局部搜索量化器。

AdditiveQuantizer *aq

bool rescale_norm = true

int norm_scale = 1

size_t max_train_points = 0

int implem = 0

int skip = 0

int bbs

int qbs = 0

size_t M

size_t nbits

size_t ksub

size_t code_size

size_t ntotal2

size_t M2

AlignedTable<uint8_t> codes

const uint8_t *orig_codes = nullptr

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexBinary

#include <IndexBinary.h>

二进制索引的抽象结构。

支持添加顶点并搜索它们。

所有查询都是对称的，因为代码和向量之间没有区别。

被 faiss::IndexBinaryFlat, faiss::IndexBinaryFromFloat, faiss::IndexBinaryHNSW, faiss::IndexBinaryHash, faiss::IndexBinaryIVF, faiss::IndexBinaryMultiHash, faiss::gpu::GpuIndexBinaryFlat 继承。

公共类型

using component_t = uint8_t

using distance_t = int32_t

公共函数

explicit IndexBinary(idx_t d = 0, MetricType metric = METRIC_L2)

virtual ~IndexBinary()

virtual void train(idx_t n, const uint8_t *x)

对有代表性的向量集合执行训练。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d / 8

virtual void add(idx_t n, const uint8_t *x) = 0

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const = 0

查询维度为 d 的 n 个向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

• distances – 输出成对距离，大小为 n*k

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k = 1) const

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

virtual void reset() = 0

从数据库中移除所有元素。

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。并非所有索引都支持。

virtual void reconstruct(idx_t key, uint8_t *recons) const

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

void display() const

显示实际的类名和更多信息。

virtual void merge_from(IndexBinary &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const IndexBinary &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

与IndexBinary的 add_with_ids 相同。

公共成员

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct IndexBinaryFlat : public faiss::IndexBinary

#include <IndexBinaryFlat.h>

Index，它存储完整的向量并执行穷举搜索。

公共类型

using component_t = uint8_t

using distance_t = int32_t

公共函数

explicit IndexBinaryFlat(idx_t d)

virtual void add(idx_t n, const uint8_t *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void reset() override

从数据库中移除所有元素。

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

• distances – 输出成对距离，大小为 n*k

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, uint8_t *recons) const override

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些 id。 请注意，由于索引结构的原因，此操作的语义与通常的语义不同：新的 id 会被移动。

inline IndexBinaryFlat()

virtual void train(idx_t n, const uint8_t *x)

对有代表性的向量集合执行训练。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

分配函数 (assign)： 给定 n 个查询向量 x，将它们分配到 k 个最近的簇 (cluster) 中，并将结果存储在 labels 中。

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

reconstruct_n: 重建索引中从 i0 开始的 ni 个向量，并将结果存储在 recons 中。

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

void display() const

显示实际的类名和更多信息。

virtual void merge_from(IndexBinary &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const IndexBinary &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

与IndexBinary的 add_with_ids 相同。

公共成员

std::vector<uint8_t> xb

database vectors, size ntotal * d / 8

bool use_heap = true

Select between using a heap or counting to select the k smallest values when scanning inverted lists.

size_t query_batch_size = 32

ApproxTopK_mode_t approx_topk_mode = ApproxTopK_mode_t::EXACT_TOPK

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct IndexBinaryFromFloat : public faiss::IndexBinary

#include <IndexBinaryFromFloat.h>

由 float Index 支持的 IndexBinary。

支持添加顶点并搜索它们。

所有查询都是对称的，因为代码和向量之间没有区别。

公共类型

using component_t = uint8_t

using distance_t = int32_t

公共函数

IndexBinaryFromFloat()

explicit IndexBinaryFromFloat(Index *index)

~IndexBinaryFromFloat()

virtual void add(idx_t n, const uint8_t *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void reset() override

从数据库中移除所有元素。

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

• distances – 输出成对距离，大小为 n*k

virtual void train(idx_t n, const uint8_t *x) override

对有代表性的向量集合执行训练。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k = 1) const

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。并非所有索引都支持。

virtual void reconstruct(idx_t key, uint8_t *recons) const

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

void display() const

显示实际的类名和更多信息。

virtual void merge_from(IndexBinary &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const IndexBinary &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

与IndexBinary的 add_with_ids 相同。

公共成员

Index *index = nullptr

bool own_fields = false

是否对象拥有索引指针。

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct IndexBinaryHash : public faiss::IndexBinary

#include <IndexBinaryHash.h>

仅使用前 b 位作为哈希值

公共类型

using InvertedListMap = std::unordered_map<idx_t, InvertedList>

using component_t = uint8_t

using distance_t = int32_t

公共函数

IndexBinaryHash(int d, int b)

IndexBinaryHash()

virtual void reset() override

从数据库中移除所有元素。

virtual void add(idx_t n, const uint8_t *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids) override

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

• distances – 输出成对距离，大小为 n*k

void display() const

size_t hashtable_size() const

训练索引。

对有代表性的向量集合执行训练。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d / 8

将向量分配到索引中的桶。

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

从索引中删除具有指定 ID 的向量。

从索引中删除 ID。并非所有索引都支持。

重构与给定键相关联的向量。

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

重构从 i0 开始的 ni 个向量。

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

搜索最近邻并重构它们。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

将另一个索引合并到该索引中。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查两个索引是否可以合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

返回辅助代码的大小。

生成的代码的大小（以字节为单位）

添加辅助代码。

与IndexBinary的 add_with_ids 相同。

公共成员

倒排列表的映射。

int b

int nflip

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct InvertedList

公共函数

void add(idx_t id, size_t code_size, const uint8_t *code)

公共成员

std::vector<idx_t> ids

std::vector<uint8_t> vecs

struct IndexBinaryHashStats

公共函数

inline IndexBinaryHashStats()

void reset()

公共成员

size_t nq

size_t n0

size_t nlist

size_t ndis

struct IndexBinaryMultiHash : public faiss::IndexBinary

#include <IndexBinaryHash.h>

仅使用前 b 位作为哈希值

公共类型

using Map = std::unordered_map<idx_t, std::vector<idx_t>>

using component_t = uint8_t

using distance_t = int32_t

公共函数

IndexBinaryMultiHash(int d, int nhash, int b)

默认构造函数。

析构函数。

重置索引，清除所有数据。

从数据库中移除所有元素。

x：指向包含向量数据的uint8_t数组的指针。

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

params：指向 SearchParameters 结构的指针，用于控制搜索行为。（可选）

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

• distances – 输出成对距离，大小为 n*k

size_t hashtable_size() const

virtual void train(idx_t n, const uint8_t *x)

对有代表性的向量集合执行训练。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k = 1) const

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。并非所有索引都支持。

virtual void reconstruct(idx_t key, uint8_t *recons) const

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

搜索并重构函数：用于在索引中搜索最近邻并重构它们。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

显示函数：用于打印索引的内部状态。

显示实际的类名和更多信息。

merge_from 函数：将另一个索引 otherIndex 合并到当前索引中，add_id 是一个偏移量，用于调整被合并索引的 ID。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

check_compatible_for_merge 函数：检查 otherIndex 是否与当前索引兼容，可以进行合并操作。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

sa_code_size 函数：返回辅助数据（SA）代码的大小（以字节为单位）。

生成的代码的大小（以字节为单位）

add_sa_codes 函数：添加辅助数据代码到索引中，codes 是代码的指针，xids 是与代码关联的 ID 的指针，n 是要添加的代码数量。

与IndexBinary的 add_with_ids 相同。

公共成员

storage：指向存储索引的 IndexBinaryFlat 对象的指针。

own_fields：一个布尔值，指示该索引是否拥有 storage 指向的 IndexBinaryFlat 对象的所有权。如果为 true，则索引在销毁时会删除该对象。

maps：一个 std::vector，包含多个 Map 对象，每个 Map 对象代表一个哈希映射。

int nhash

哈希映射的数量

int b

每个哈希映射的位数

int nflip

搜索时使用的翻转位数

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct IndexBinaryHNSW : public faiss::IndexBinary

#include <IndexBinaryHNSW.h>

HNSW 索引是一个普通的随机访问索引，其上构建了一个 HNSW 链接结构。

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = uint8_t

using distance_t = int32_t

公共函数

explicit IndexBinaryHNSW()

explicit IndexBinaryHNSW(int d, int M = 32)

explicit IndexBinaryHNSW(IndexBinary *storage, int M = 32)

~IndexBinaryHNSW() override

DistanceComputer *get_distance_computer() const

virtual void add(idx_t n, const uint8_t *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void train(idx_t n, const uint8_t *x) override

如果需要，训练存储。

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void reconstruct(idx_t key, uint8_t *recons) const override

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual void reset() override

从数据库中移除所有元素。

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k = 1) const

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。并非所有索引都支持。

virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

void display() const

显示实际的类名和更多信息。

virtual void merge_from(IndexBinary &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const IndexBinary &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

与IndexBinary的 add_with_ids 相同。

公共成员

HNSW hnsw

bool own_fields

IndexBinary *storage

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct IndexBinaryIVF : public faiss::IndexBinary

#include <IndexBinaryIVF.h>

基于倒排文件 (IVF) 的索引

在倒排文件中，量化器（IndexBinary 实例）为每个要添加的向量提供一个量化索引。量化索引映射到一个列表（也称为倒排列表或 posting 列表），向量的 id 存储在该列表中。

否则，该对象类似于 IndexIVF

公共类型

using component_t = uint8_t

using distance_t = int32_t

公共函数

IndexBinaryIVF(IndexBinary *quantizer, size_t d, size_t nlist)

倒排文件接受一个量化器（IndexBinary）作为输入，该量化器实现了将向量映射到列表标识符的函数。该指针是被借用的：在使用 IndexBinaryIVF 时，不应删除量化器。

IndexBinaryIVF()

~IndexBinaryIVF() override

virtual void reset() override

从数据库中移除所有元素。

virtual void train(idx_t n, const uint8_t *x) override

训练量化器。

virtual void add(idx_t n, const uint8_t *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids) override

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

void add_core(idx_t n, const uint8_t *x, const idx_t *xids, const idx_t *precomputed_idx)

向量加法的实现，其中向量分配是预定义的。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

void search_preassigned(idx_t n, const uint8_t *x, idx_t k, const idx_t *assign, const int32_t *centroid_dis, int32_t *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr) const

搜索一组向量，这些向量由IVF量化器预先量化。用查询结果填充相应的堆。search() 调用此函数。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

virtual BinaryInvertedListScanner *get_InvertedListScanner(bool store_pairs = false) const

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

void range_search_preassigned(idx_t n, const uint8_t *x, int radius, const idx_t *assign, const int32_t *centroid_dis, RangeSearchResult *result) const

virtual void reconstruct(idx_t key, uint8_t *recons) const override

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const override

Reconstruct a subset of the indexed vectors.

Overrides default implementation to bypass reconstruct() which requires direct_map to be maintained.

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – output array of reconstructed vectors, size ni * d / 8

virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

Overrides default implementation to avoid having to maintain direct_map and instead fetch the code offsets through the store_pairs flag in search_preassigned().

参数：

recons – reconstructed vectors size (n, k, d / 8)

virtual void reconstruct_from_offset(idx_t list_no, idx_t offset, uint8_t *recons) const

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

Useful for reconstructing when the direct_map is not maintained and the inv list offset is computed by search_preassigned() with store_pairs set.

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void merge_from(IndexBinary &other, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查是否与其他索引兼容以进行合并

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

获取列表大小

初始化直接映射

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型

替换倒排列表

分配

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

void display() const

显示实际的类名和更多信息。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

与IndexBinary的 add_with_ids 相同。

公共成员

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = true

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

bool use_heap = true

Select between using a heap or counting to select the k smallest values when scanning inverted lists.

bool per_invlist_search = false

收集每个批次的计算结果

DirectMap direct_map

map for direct access to the elements. Enables reconstruct().

IndexBinary *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

number of possible key values

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

struct BinaryInvertedListScanner

公共函数

virtual void set_query(const uint8_t *query_vector) = 0

现在开始处理这个查询。

virtual void set_list(idx_t list_no, uint8_t coarse_dis) = 0

接下来的代码来自这个倒排列表。

virtual uint32_t distance_to_code(const uint8_t *code) const = 0

计算单个查询到代码的距离。

virtual size_t scan_codes(size_t n, const uint8_t *codes, const idx_t *ids, int32_t *distances, idx_t *labels, size_t k) const = 0

计算到代码的距离。(distances, labels)应该组织成最小堆或最大堆。

参数：

• n – 要扫描的代码数量

• codes – 要扫描的代码 (n * code_size)

• ids – 对应的 id (如果 store_pairs 则忽略)

• distances – 堆距离 (大小为 k)

• labels – 堆标签 (大小为 k)

• k – 堆大小

virtual void scan_codes_range(size_t n, const uint8_t *codes, const idx_t *ids, int radius, RangeQueryResult &result) const = 0

inline virtual ~BinaryInvertedListScanner()

struct IndexFastScan : public faiss::Index

#include <IndexFastScan.h>

快速扫描版本的 IndexPQ 和 IndexAQ。目前适用于 4 位 PQ 和 AQ。

代码不是按顺序存储的，而是按大小为 bbs 的块分组的。这使得可以使用 SIMD 指令快速计算距离。尾随代码（为完成最后一个代码而添加的填充代码）是垃圾。

实现：12：带有 Q 内部循环的块循环，qbs 为 13：与存储结果的储层累加器相同 14：没有带堆累加器的 qbs 15：没有带储层累加器的 qbs

子类为 faiss::IndexAdditiveQuantizerFastScan, faiss::IndexPQFastScan

公共类型

using component_t = float

using distance_t = float

公共函数

void init_fastscan(int d, size_t M, size_t nbits, MetricType metric, int bbs)

IndexFastScan()

virtual void reset() override

从数据库中删除所有元素。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void compute_codes(uint8_t *codes, idx_t n, const float *x) const = 0

virtual void compute_float_LUT(float *lut, idx_t n, const float *x) const = 0

void compute_quantized_LUT(idx_t n, const float *x, uint8_t *lut, float *normalizers) const

template<bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

template<class C>
void search_implem_14 (idx_t n, const float * x, idx_t k, float * distances, idx_t * labels, int impl, const NormTableScaler * scaler) const

virtual void reconstruct (idx_t key, float * recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids (const IDSelector & sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

CodePacker * get_CodePacker () const

virtual void merge_from (Index & otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

sa_code_size() const

生成的代码的大小（以字节为单位）

sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

添加 SA 代码

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

实现

跳过

bbs

qbs

M

nbits

ksub

代码大小

ntotal2

M2

代码

原始代码

d

向量维度

ntotal

索引向量的总数

verbose

详细级别

是否已训练

如果 Index 不需要训练，或者如果已经完成训练，则设置

度量类型

此索引用于搜索的度量类型

度量参数

度量类型的参数

结构体 FastScanStats

公共函数

内联 FastScanStats 构造函数

内联 reset 函数

公共成员

t0

t1

t2

t3

结构体 IndexFlat，继承自 IndexFlatCodes

包含头文件 IndexFlat.h

Index 用于存储完整向量并执行穷举搜索

被 faiss::IndexFlatIP 和 faiss::IndexFlatL2 继承

公共类型

使用 component_t 作为 float 的别名

使用 distance_t 作为 float 的别名

公共函数

explicit IndexFlat(idx_t d, MetricType metric = METRIC_L2)

参数：

d – 输入向量的维度

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

void compute_distance_subset(idx_t n, const float *x, idx_t k, float *distances, const idx_t *labels) const

计算向量子集的距离

参数：

• x – 查询向量，大小为 n * d

• labels – 对于每个查询向量，应该比较的向量的索引，大小为 n * k

• distances – 相应的输出距离，大小为 n * k

inline float *get_xb()

inline const float *get_xb() const

inline IndexFlat()

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexFlatIP : public faiss::IndexFlat

公共类型

using component_t = float

using distance_t = float

公共函数

inline explicit IndexFlatIP(idx_t d)

inline IndexFlatIP()

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

void compute_distance_subset(idx_t n, const float *x, idx_t k, float *distances, const idx_t *labels) const

计算向量子集的距离

参数：

• x – 查询向量，大小为 n * d

• labels – 对于每个查询向量，应该比较的向量的索引，大小为 n * k

• distances – 相应的输出距离，大小为 n * k

inline float *get_xb()

inline const float *get_xb() const

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

x：训练样本的指针。

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

xids：与向量相对应的ID的指针。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

k：每个向量要分配给的最近聚类中心的数量。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

recons：输出，重建的向量的指针。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

params：搜索参数。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

key：向量的ID。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

keys：向量的ID的指针。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

每个向量的代码大小（以字节为单位）。

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexFlatL2 : public faiss::IndexFlat

被 faiss::IndexFlat1D 继承

公共类型

using component_t = float

using distance_t = float

公共函数

inline explicit IndexFlatL2(idx_t d)

参数：

d – 输入向量的维度

inline IndexFlatL2()

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

void sync_l2norms()

void clear_l2norms()

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

void compute_distance_subset(idx_t n, const float *x, idx_t k, float *distances, const idx_t *labels) const

计算向量子集的距离

参数：

• x – 查询向量，大小为 n * d

• labels – 对于每个查询向量，应该比较的向量的索引，大小为 n * k

• distances – 相应的输出距离，大小为 n * k

inline float *get_xb()

inline const float *get_xb() const

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

std::vector<float> cached_l2norms

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexFlat1D : public faiss::IndexFlatL2

包含头文件 IndexFlat.h

针对1D“向量”的优化版本。

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexFlat1D(bool continuous_update = true)

void update_permutation()

如果不是 continuous_update，在最后一次添加和第一次搜索之间调用此方法

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void reset() override

从数据库中删除所有元素。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

警告：返回的距离是L1而不是L2。

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

void sync_l2norms()

void clear_l2norms()

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

virtual void 重建(idx_t key, float* recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

void compute_distance_subset(idx_t n, const float *x, idx_t k, float *distances, const idx_t *labels) const

void 计算距离子集(idx_t n, const float* x, idx_t k, float* distances, const idx_t* labels) const

计算向量子集的距离

参数：

• x – 查询向量，大小为 n * d

• labels – 对于每个查询向量，应该比较的向量的索引，大小为 n * k

• distances – 相应的输出距离，大小为 n * k

inline float *get_xb()

inline float* 获取_xb()

inline const float *get_xb() const

inline const float* 获取_xb() const

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

virtual void sa编码(idx_t n, const float* x, uint8_t* bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

virtual void sa解码(idx_t n, const uint8_t* bytes, float* x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

virtual void 重建_n(idx_t i0, idx_t ni, float* recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual size_t sa_code_size() const override

virtual size_t sa代码大小() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

virtual size_t 移除_ids(const IDSelector& sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

inline virtual DistanceComputer* 获取距离计算器() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

CodePacker *get_CodePacker() const

CodePacker* 获取代码打包器() const

virtual void 检查是否可以合并(const &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void 合并来自( &otherIndex, add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

bool continuous_update = true

是否持续更新排列？

std::vector<idx_t> perm

排序后的数据库索引

std::vector<float> cached_l2norms

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexFlatCodes : public faiss::Index

#include <IndexFlatCodes.h>

Index 将所有向量编码为固定大小的代码（大小为 code_size）。存储位于 codes 向量中。

Subclassed by faiss::Index2Layer, faiss::IndexAdditiveQuantizer, faiss::IndexFlat, faiss::IndexLSH, faiss::IndexLattice, faiss::IndexNeuralNetCodec, faiss::IndexPQ, faiss::IndexScalarQuantizer

公共类型

using component_t = float

using distance_t = float

公共函数

IndexFlatCodes()

IndexFlatCodes(size_t code_size, idx_t d, MetricType metric = METRIC_L2)

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

Search implemented by decoding

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

公共成员

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexHNSW : public faiss::Index

#include <IndexHNSW.h>

HNSW 索引是一个普通的随机访问索引，其上构建了一个 HNSW 链接结构。

由 faiss::IndexHNSW2Level, faiss::IndexHNSWCagra, faiss::IndexHNSWFlat, faiss::IndexHNSWPQ, faiss::IndexHNSWSQ 继承

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = float

using distance_t = float

公共函数

explicit IndexHNSW(int d = 0, int M = 32, MetricType metric = METRIC_L2)

explicit IndexHNSW(Index *storage, int M = 32)

~IndexHNSW() override

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

void shrink_level_0_neighbors(int size)

void search_level_0(idx_t n, const float *x, idx_t k, const storage_idx_t *nearest, const float *nearest_d, float *distances, idx_t *labels, int nprobe = 1, int search_type = 1, const SearchParameters *params = nullptr) const

仅在第0层执行搜索，给定每个顶点的起始点。

参数：

search_type – 1: 每次 nprobe 执行一次搜索, 2: 将所有入口点入队

void init_level_0_from_knngraph(int k, const float *D, const idx_t *I)

替代的图构建方法

void init_level_0_from_entry_points(int npt, const storage_idx_t *points, const storage_idx_t *nearests)

替代的图构建方法

void reorder_links()

void link_singletons()

void permute_entries(const idx_t *perm)

virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

HNSW hnsw

bool own_fields = false

Index *storage = nullptr

bool init_level0 = true

bool keep_max_size_level0 = false

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexHNSWFlat : public faiss::IndexHNSW

#include <IndexHNSW.h>

Flat index topped with with a HNSW structure to access elements more efficiently.

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = float

using distance_t = float

公共函数

IndexHNSWFlat()

IndexHNSWFlat(int d, int M, MetricType metric = METRIC_L2)

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override // 重置索引

从数据库中删除所有元素。

void shrink_level_0_neighbors(int size) // 缩小第 0 层的邻居数量

void search_level_0(idx_t n, const float *x, idx_t k, const storage_idx_t *nearest, const float *nearest_d, float *distances, idx_t *labels, int nprobe = 1, int search_type = 1, const SearchParameters *params = nullptr) const

仅在第0层执行搜索，给定每个顶点的起始点。

参数：

search_type – 1: 每次 nprobe 执行一次搜索, 2: 将所有入口点入队

void init_level_0_from_knngraph(int k, const float *D, const idx_t *I)

替代的图构建方法

void init_level_0_from_entry_points(int npt, const storage_idx_t *points, const storage_idx_t *nearests)

替代的图构建方法

void reorder_links()

void link_singletons()

void permute_entries(const idx_t *perm)

virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

HNSW hnsw

bool own_fields = false

Index *storage = nullptr

bool init_level0 = true

bool keep_max_size_level0 = false

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexHNSWPQ : public faiss::IndexHNSW

#include <IndexHNSW.h>

PQ索引，顶部带有HNSW结构，以便更有效地访问元素。

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = float

using distance_t = float

公共函数

IndexHNSWPQ()

IndexHNSWPQ(int d, int pq_m, int M, int pq_nbits = 8, MetricType metric = METRIC_L2)

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

void shrink_level_0_neighbors(int size)

void search_level_0(idx_t n, const float *x, idx_t k, const storage_idx_t *nearest, const float *nearest_d, float *distances, idx_t *labels, int nprobe = 1, int search_type = 1, const SearchParameters *params = nullptr) const

仅在第0层执行搜索，给定每个顶点的起始点。

参数：

search_type – 1: 每次 nprobe 执行一次搜索, 2: 将所有入口点入队

void init_level_0_from_knngraph(int k, const float *D, const idx_t *I)

替代的图构建方法

void init_level_0_from_entry_points(int npt, const storage_idx_t *points, const storage_idx_t *nearests)

替代的图构建方法

重新排序链接

链接单例

置换条目

获取距离计算器

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

添加带ID的数据

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

分配

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

移除ID

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

重建批次

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

重建n个

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

搜索和重建

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

计算残差

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算n个残差

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取SA代码大小

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

HNSW hnsw

bool own_fields = false

Index *storage = nullptr

bool init_level0 = true

bool keep_max_size_level0 = false

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexHNSWSQ : public faiss::IndexHNSW

#include <IndexHNSW.h>

SQ 索引，顶部带有 HNSW 结构，以便更有效地访问元素。

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = float

using distance_t = float

公共函数

IndexHNSWSQ()

IndexHNSWSQ(int d, ScalarQuantizer::QuantizerType qtype, int M, MetricType metric = METRIC_L2)

虚拟 void add(idx_t n, const float *x) 覆盖


将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

虚拟 void train(idx_t n, const float *x) 覆盖

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

void shrink_level_0_neighbors(int size)

void search_level_0(idx_t n, const float *x, idx_t k, const storage_idx_t *nearest, const float *nearest_d, float *distances, idx_t *labels, int nprobe = 1, int search_type = 1, const SearchParameters *params = nullptr) const

仅在第0层执行搜索，给定每个顶点的起始点。

参数：

search_type – 1: 每次 nprobe 执行一次搜索, 2: 将所有入口点入队

void init_level_0_from_knngraph(int k, const float *D, const idx_t *I)

替代的图构建方法

void init_level_0_from_entry_points(int npt, const storage_idx_t *points, const storage_idx_t *nearests)

替代的图构建方法

void reorder_links()

void link_singletons()

void permute_entries(const idx_t *perm)

virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

HNSW hnsw

bool own_fields = false

Index *storage = nullptr

bool init_level0 = true

bool keep_max_size_level0 = false

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexHNSW2Level : public faiss::IndexHNSW

#include <IndexHNSW.h>

具有快速随机访问的 2 级代码结构

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = float

using distance_t = float

公共函数

IndexHNSW2Level()

IndexHNSW2Level(Index *quantizer, size_t nlist, int m_pq, int M)

void flip_to_ivf()

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

void shrink_level_0_neighbors(int size)

void search_level_0(idx_t n, const float *x, idx_t k, const storage_idx_t *nearest, const float *nearest_d, float *distances, idx_t *labels, int nprobe = 1, int search_type = 1, const SearchParameters *params = nullptr) const

仅在第0层执行搜索，给定每个顶点的起始点。

参数：

search_type – 1: 每次 nprobe 执行一次搜索, 2: 将所有入口点入队

void init_level_0_from_knngraph(int k, const float *D, const idx_t *I)

替代的图构建方法

void init_level_0_from_entry_points(int npt, const storage_idx_t *points, const storage_idx_t *nearests)

替代的图构建方法

void reorder_links()

void link_singletons()

void permute_entries(const idx_t *perm)

virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

重建一批向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

重建指定范围的向量。

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

HNSW hnsw

bool own_fields = false

Index *storage = nullptr

bool init_level0 = true

bool keep_max_size_level0 = false

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexHNSWCagra : public faiss::IndexHNSW

公共类型

typedef HNSW::storage_idx_t storage_idx_t

using component_t = float

using distance_t = float

公共函数

IndexHNSWCagra()

IndexHNSWCagra(int d, int M, MetricType metric = METRIC_L2)

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void train(idx_t n, const float *x)

如果需要，训练存储。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons)

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset()

从数据库中删除所有元素。

void shrink_level_0_neighbors(int size)

void search_level_0(idx_t n, const float *x, idx_t k, const storage_idx_t *nearest, const float *nearest_d, float *distances, idx_t *labels, int nprobe = 1, int search_type = 1, const SearchParameters *params = nullptr) const

仅在第0层执行搜索，给定每个顶点的起始点。

参数：

search_type – 1: 每次 nprobe 执行一次搜索, 2: 将所有入口点入队

初始化第0层来自 k-最近邻图 (knn-graph)。

替代的图构建方法

初始化第0层来自入口点。

替代的图构建方法

重新排序链接。

链接孤立点。

置换条目。

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

添加带有 id 的向量。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

分配向量到簇。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

移除满足选择器的 id。

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

批量重建向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

重建 n 个向量。

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

搜索并重建向量。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

计算残差。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

bool base_level_only = false

如果设置为 true，则索引是不可变的。 此选项用于将 knn 图从 GpuIndexCagra 复制到 IndexHNSWCagra 的基本级别，而不添加上层级别。 这样做可以搜索 HNSW 索引，但会移除添加向量的能力。

int num_base_level_search_entrypoints = 32

当 base_level_only 设置为 True 时，搜索功能仅搜索 HNSW 索引的基本级别 knn 图。 此参数通过随机选择一些点并使用最佳点来选择入口点。

HNSW hnsw

bool own_fields = false

Index *storage = nullptr

bool init_level0 = true

bool keep_max_size_level0 = false

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

template<typename IndexT>
struct IndexIDMapTemplate : public IndexT

#include <IndexIDMap.h>

Index 将搜索结果转换为 id

被 faiss::IndexIDMap2Template< IndexT > 继承

公共类型

using component_t = typename IndexT::component_t

using distance_t = typename IndexT::distance_t

公共函数

explicit IndexIDMapTemplate(IndexT *index)

void add_with_ids(idx_t n, const component_t *x, const idx_t *xids) override

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

void add(idx_t n, const component_t *x) override

这将会失败。请使用 add_with_ids

void search(idx_t n, const component_t *x, idx_t k, distance_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

void train(idx_t n, const component_t *x) override

void reset() override

size_t remove_ids(const IDSelector &sel) override

移除 ids 以适应 IndexFlat

void range_search(idx_t n, const component_t *x, distance_t radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

将`otherIndex`合并到当前索引中，并为所有添加的 ID 添加 `add_id` 偏移量。（重写）

检查 `otherIndex` 是否可以合并到当前索引中。（重写）

返回存储一个附加编码所需的字节数。（重写）

添加附加编码和对应的 ID。（重写）

析构函数。（重写）

默认构造函数。

公共成员

指向子索引的指针。

是否在析构函数中删除指针。

! 子索引

! 从索引中的位置到外部 id 的映射。

! 指针是否在析构函数中被删除。

template<typename IndexT>
struct IndexIDMap2Template : public faiss::IndexIDMapTemplate<IndexT>

#include <IndexIDMap.h>

与 IndexIDMap 相同，但也通过双向索引提供高效的重建实现。

公共类型

`IndexT` 的组件类型。

`IndexT` 的距离类型。

公共函数

显式构造函数，使用给定的子索引。

从头开始构建 `rev_map`。

从头开始构建 rev_map

添加向量及其对应的 id。（重写）

删除满足给定选择器的 id。（重写）

void reconstruct(idx_t key, component_t *recons) const override

void check_consistency() const

检查rev_map和id_map是否同步

void merge_from(IndexT &otherIndex, idx_t add_id = 0) override

inline ~IndexIDMap2Template() override

inline IndexIDMap2Template()

void add(idx_t n, const component_t *x) override

这将会失败。请使用 add_with_ids

void search(idx_t n, const component_t *x, idx_t k, distance_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

void train(idx_t n, const component_t *x) override

void reset() override

void range_search(idx_t n, const component_t *x, distance_t radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

void check_compatible_for_merge(const IndexT &otherIndex) const override

size_t sa_code_size() const override

void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

公共成员

std::unordered_map<idx_t, idx_t> rev_map

IndexT *index = nullptr

bool own_fields = false

! 子索引

std::vector<idx_t> id_map

! 指针是否在析构函数中被删除。

struct IDSelectorTranslated : public faiss::IDSelector

公共函数

inline IDSelectorTranslated(const std::vector<int64_t> &id_map, const IDSelector *sel)

inline IDSelectorTranslated(IndexBinaryIDMap &index_idmap, const IDSelector *sel)

inline IDSelectorTranslated(IndexIDMap &index_idmap, const IDSelector *sel)

inline virtual bool is_member(idx_t id) const override

公共成员

const std::vector<int64_t> &id_map

const IDSelector *sel

struct Level1Quantizer

#include <IndexIVF.h>

封装用于 IndexIVF 的量化器对象

该类隔离了独立于列表存储的字段（尤其是训练）

由 faiss::IndexIVFInterface, faiss::IndexShardsIVF 继承

公共函数

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

Level1Quantizer(Index *quantizer, size_t nlist)

Level1Quantizer()

~Level1Quantizer()

公共成员

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct SearchParametersIVF : public faiss::SearchParameters

由 faiss::IVFPQSearchParameters 继承

公共函数

inline virtual ~SearchParametersIVF()

公共成员

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

SearchParameters *quantizer_params = nullptr

void *inverted_list_context = nullptr

要传递给 InvertedLists 的上下文对象

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct IndexIVFInterface : public faiss::Level1Quantizer

被 faiss::IndexIVF, faiss::gpu::GpuIndexIVF 继承

公共函数

inline explicit IndexIVFInterface(Index *quantizer = nullptr, size_t nlist = 0)

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const = 0

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const = 0

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

inline virtual ~IndexIVFInterface()

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVF : public faiss::Index, public faiss::IndexIVFInterface

#include <IndexIVF.h>

基于倒排文件 (IVF) 的索引

在倒排文件中，量化器（一个 Index 实例）为要添加的每个向量提供一个量化索引。量化索引映射到一个列表（也称为倒排列表或帖子列表），其中存储了向量的 id。

倒排列表对象仅在训练后才是必需的。如果未从外部设置任何内容，则会自动使用 ArrayInvertedLists。

在搜索时，要搜索的向量也被量化，并且仅搜索与量化索引对应的列表。这通过使其成为非穷举的来加速搜索。可以使用多探针搜索来放宽此限制：选择几个（nprobe）量化索引并访问多个倒排列表。

子类实现了索引的后过滤，该过滤细化了从查询到数据库向量的距离估计。

由 faiss::IndexIVFAdditiveQuantizer, faiss::IndexIVFFastScan, faiss::IndexIVFFlat, faiss::IndexIVFPQ, faiss::IndexIVFScalarQuantizer, faiss::IndexIVFSpectralHash 继承

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVF(Index *quantizer, size_t d, size_t nlist, size_t code_size, MetricType metric = METRIC_L2)

倒排文件采用量化器（Index），该量化器实现将向量映射到列表标识符的函数。

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const = 0

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign)

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const

可以被子类重新定义以指示他们需要多少训练向量

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

~IndexIVF() override

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

IndexIVF()

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct InvertedListScanner

#include <IndexIVF.h>

处理查询的对象。 要扫描的倒排列表在外部提供。 该对象有很多状态，但 distance_to_code 和 scan_codes 可以在多个线程中调用

公共函数

inline InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr)

virtual void set_query(const float *query_vector) = 0

现在开始处理这个查询。

virtual void set_list(idx_t list_no, float coarse_dis) = 0

接下来的代码来自这个倒排列表。

virtual float distance_to_code(const uint8_t *code) const = 0

计算单个查询到代码的距离。

virtual size_t scan_codes(size_t n, const uint8_t *codes, const idx_t *ids, float *distances, idx_t *labels, size_t k) const

扫描一组代码，计算与当前查询的距离，并在必要时更新结果堆。默认实现调用 distance_to_code。

参数：

• n – 要扫描的代码数量

• codes – 要扫描的代码 (n * code_size)

• ids – 对应的 id (如果 store_pairs 则忽略)

• distances – 堆距离 (大小为 k)

• labels – 堆标签 (大小为 k)

• k – 堆大小

返回值：

执行的堆更新次数

virtual size_t iterate_codes(InvertedListsIterator *iterator, float *distances, idx_t *labels, size_t k, size_t &list_size) const

virtual void scan_codes_range(size_t n, const uint8_t *codes, const idx_t *ids, float radius, RangeQueryResult &result) const

扫描一组代码，计算与当前查询的距离，如果距离小于半径则更新结果

(默认实现失败)

virtual void iterate_codes_range(InvertedListsIterator *iterator, float radius, RangeQueryResult &result, size_t &list_size) const

inline virtual ~InvertedListScanner()

公共成员

idx_t list_no = -1

记住当前列表

bool keep_max = false

保持最大值而不是最小值

bool store_pairs

存储 invlist 中的位置而不是标签

const IDSelector *sel

在此 ID 子集中搜索

size_t code_size = 0

在 scan_codes 的默认实现中使用

struct IndexIVFStats

公共函数

inline IndexIVFStats()

void reset()

void add(const IndexIVFStats &other)

公共成员

size_t nq

size_t nlist

size_t ndis

size_t nheap_updates

double quantization_time

double search_time

struct IndexIVFAdditiveQuantizer : public faiss::IndexIVF

#include <IndexIVFAdditiveQuantizer.h>

IVF 加性量化器的抽象类。搜索函数是通用的。

被 faiss::IndexIVFLocalSearchQuantizer, faiss::IndexIVFProductLocalSearchQuantizer, faiss::IndexIVFProductResidualQuantizer, faiss::IndexIVFResidualQuantizer 继承

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFAdditiveQuantizer(AdditiveQuantizer *aq, Index *quantizer, size_t d, size_t nlist, MetricType metric = METRIC_L2)

explicit IndexIVFAdditiveQuantizer(AdditiveQuantizer *aq)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void sa_decode(idx_t n, const uint8_t *codes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

~IndexIVFAdditiveQuantizer() override

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

添加带ID的向量。

调用 encode_vectors 的默认实现

添加核心向量。

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

添加SA码。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

复制子集到另一个索引。

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取列表的大小。

检查ID是否已排序。

ID 是否已排序？

创建直接映射。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型。

替换倒排列表。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

获取补充量化的码本大小。

生成的代码的大小（以字节为单位）

编码补充量化值。

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

将向量分配到簇。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

重建一批向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n， const float *xs， float *residuals， const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n， const float *x， bool verbose， MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no， uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

AdditiveQuantizer *aq

int use_precomputed_table = 0

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFResidualQuantizer : public faiss::IndexIVFAdditiveQuantizer

#include <IndexIVFAdditiveQuantizer.h>

基于残差量化器的IndexIVF。 存储的向量通过残差量化代码进行近似。

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFResidualQuantizer(Index *量化器, size_t d, size_t nlist, const std::vector<size_t> &nbits, MetricType 度量 = METRIC_L2, Search_type_t 搜索类型 = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

IndexIVFResidualQuantizer(Index *量化器, size_t d, size_t nlist, size_t M, size_t nbits, MetricType 度量 = METRIC_L2, Search_type_t 搜索类型 = AdditiveQuantizer::ST_decompress)

IndexIVFResidualQuantizer()

virtual ~IndexIVFResidualQuantizer()

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void sa_decode(idx_t n, const uint8_t *codes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

将一个子集复制到另一个 IndexIVF 对象中。

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取指定列表的大小。

检查 ID 是否已排序。

ID 是否已排序？

创建一个直接映射。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射的类型。

替换倒排列表。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

返回辅助编码的大小。

生成的代码的大小（以字节为单位）

编码辅助信息。

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

分配向量到簇。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

批量重建向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

计算残差向量。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

批量计算残差向量。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取距离计算器

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

训练一级量化器

训练量化器并调用 train_residual 来训练子量化器。

获取粗糙码的大小

计算存储列表 ID 所需的字节数

编码列表编号

解码列表编号

公共成员

残差量化器

用于编码向量的残差量化器。

加性量化器

使用预计算表 (0 表示否，其他值表示是)

倒排列表

访问实际数据。

是否拥有倒排列表

码的大小

每个向量的代码大小，以字节为单位

并行模式

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

并行模式：无堆初始化

直接映射

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

按残差 (如果为真，则在残差上训练)

invlist中的代码是否编码了相对于质心的向量？

维度

向量维度

总数

索引向量的总数

详细模式

详细级别

是否已训练

如果 Index 不需要训练，或者如果已经完成训练，则设置

度量类型

此索引用于搜索的度量类型

度量参数

度量类型的参数

探测数量 (用于搜索的列表数量)

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFLocalSearchQuantizer : public faiss::IndexIVFAdditiveQuantizer

#include <IndexIVFAdditiveQuantizer.h>

基于残差量化器的IndexIVF。 存储的向量通过残差量化代码进行近似。

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFLocalSearchQuantizer(Index *quantizer, size_t d, size_t nlist, size_t M, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

IndexIVFLocalSearchQuantizer()

virtual ~IndexIVFLocalSearchQuantizer()

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void sa_decode(idx_t n, const uint8_t *codes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

LocalSearchQuantizer lsq

用于编码向量的LSQ量化器。

AdditiveQuantizer *aq

int use_precomputed_table = 0

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFProductResidualQuantizer : public faiss::IndexIVFAdditiveQuantizer

#include <IndexIVFAdditiveQuantizer.h>

基于乘积残差量化器的IndexIVF。存储的向量通过乘积残差量化代码近似表示。

公共类型

使用 Search_type_t = AdditiveQuantizer::Search_type_t

使用 component_t = float

使用 distance_t = float

公共函数

IndexIVFProductResidualQuantizer(Index *quantizer, size_t d, size_t nlist, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• nsplits – 残差量化器的数量

• Msub – 每个RQ的子量化器的数量

• nbits – 每个子向量索引的比特数

IndexIVFProductResidualQuantizer()

virtual ~IndexIVFProductResidualQuantizer()

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void sa_decode(idx_t n, const uint8_t *codes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

计算残差。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算多个向量的残差。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取距离计算器（Distance Computer）。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

训练第一层量化器（train_q1）。

训练量化器并调用 train_residual 来训练子量化器。

返回粗糙码的大小（coarse code size）。

计算存储列表 ID 所需的字节数

编码列表编号（list number）。

解码列表编号（list number）。

公共成员

产品残差量化器（Product Residual Quantizer）。

用于编码向量的乘积残差量化器。

加法量化器（Additive Quantizer）指针。

是否使用预计算表 (0:否，其他：是)。

倒排列表（Inverted Lists）指针，用于存储每个簇的向量 ID。

访问实际数据。

是否拥有倒排列表（own inverted lists），如果为 true，则在删除索引时会删除倒排列表。

码字的大小（code size），以字节为单位。

每个向量的代码大小，以字节为单位

并行模式（parallel mode）。

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

并行模式：不初始化堆（PARALLEL_MODE_NO_HEAP_INIT）。

直接映射（Direct Map），用于从向量 ID 查找对应的倒排列表。

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

是否通过残差进行量化（by residual），如果为 true，则使用残差向量进行量化，否则使用原始向量。

invlist中的代码是否编码了相对于质心的向量？

向量的维度（dimension）。

向量维度

索引中向量的总数（total number of vectors in the index）。

索引向量的总数

是否输出详细信息（verbose）。

详细级别

索引是否已训练（is trained）。

如果 Index 不需要训练，或者如果已经完成训练，则设置

距离度量类型（metric type）。

此索引用于搜索的度量类型

距离度量的参数（metric argument）。

度量类型的参数

size_t nprobe = 1

查询时的探针数量

max_codes：最大编码数量，默认值为 0。

查询时要访问的最大代码数量

quantizer：量化器，默认值为 nullptr。

quantizer that maps vectors to inverted lists

nlist：列表数量，默认值为 0。

倒排列表的数量

quantizer_trains_alone：量化器是否独立训练，默认值为 0 (false)。

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

own_fields：是否拥有字段，默认值为 false。

whether object owns the quantizer

cp：聚类参数。

to override default clustering params

clustering_index：聚类索引，默认值为 nullptr。

to override index used during clustering

struct IndexIVFProductLocalSearchQuantizer : public faiss::IndexIVFAdditiveQuantizer

#include <IndexIVFAdditiveQuantizer.h>

基于乘积局部搜索量化器的 IndexIVF。存储的向量通过乘积局部搜索量化码进行近似。

公共类型

Search_type_t：搜索类型，与 AdditiveQuantizer::Search_type_t 相同。

component_t：组件类型，为 float。

distance_t：距离类型，为 float。

公共函数

构造函数：IndexIVFProductLocalSearchQuantizer(Index *quantizer, size_t d, size_t nlist, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_decompress)

构造函数。

参数：

• d – 输入向量的维度

• nsplits – 局部搜索量化器的数量

• Msub – 每个 LSQ 的子量化器数量

• nbits – 每个子向量索引的比特数

默认构造函数：IndexIVFProductLocalSearchQuantizer()

虚析构函数：~IndexIVFProductLocalSearchQuantizer()

train_encoder：训练编码器函数，覆盖了基类的函数。

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

train_encoder_num_vectors：返回用于训练编码器的向量数量，覆盖了基类的函数。

可以被子类重新定义以指示他们需要多少训练向量

virtual void encode_vectors(idx_t n， const float *x， const idx_t *list_nos， uint8_t *codes， bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs， const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void sa_decode(idx_t n， const uint8_t *codes， float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reconstruct_from_offset(int64_t list_no， int64_t offset， float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n， const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n， const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n， const float *x， const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n， const float *x， const idx_t *xids， const idx_t *precomputed_idx， void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n， const uint8_t *codes， const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

对预先分配的倒排表执行范围搜索。

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

执行范围搜索。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

重构向量。

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

更新向量。

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

重构 n 个向量。

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

搜索并重构。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

搜索并返回代码(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

移除 ID (const IDSelector &sel) override

Dataset manipulation functions.

检查合并兼容性 (const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

从合并 (Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

获取代码打包器() const

复制子集到 (IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取列表大小(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

将列表编号编码到码字中。

从码字中解码列表编号。

公共成员

乘积局部搜索量化器。

用于编码向量的乘积局部搜索量化器。

AdditiveQuantizer *aq

int use_precomputed_table = 0

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFAdditiveQuantizerFastScan : public faiss::IndexIVFFastScan

#include <IndexIVFAdditiveQuantizerFastScan.h>

IVFAQ 的快速扫描版本。 目前适用于 4 位 AQ。

倒排列表中的代码不是顺序存储的，而是按大小为 bbs 的块分组的。 这使得可以使用 SIMD 指令非常快速地计算距离。

实现 (implem): 0: 自动选择实现 (默认) 1: orig 的搜索，重新实现 2: orig 的搜索，按 invlist 重新排序 10: 优化器 int16 搜索，在堆中收集结果，无 qbs 11: 相同，在存储池中收集结果 12: 优化器 int16 搜索，在堆中收集结果，使用 qbs 13: 相同，在存储池中收集结果

子类为 faiss::IndexIVFLocalSearchQuantizerFastScan, faiss::IndexIVFProductLocalSearchQuantizerFastScan, faiss::IndexIVFProductResidualQuantizerFastScan, faiss::IndexIVFResidualQuantizerFastScan

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFAdditiveQuantizerFastScan(Index *quantizer, AdditiveQuantizer *aq, size_t d, size_t nlist, MetricType metric = METRIC_L2, int bbs = 32)

void init(AdditiveQuantizer *aq, size_t nlist, MetricType metric, int bbs)

IndexIVFAdditiveQuantizerFastScan()

~IndexIVFAdditiveQuantizerFastScan() override

explicit IndexIVFAdditiveQuantizerFastScan(const IndexIVFAdditiveQuantizer &orig, int bbs = 32)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

void estimate_norm_scale(idx_t n, const float *x)

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const override

与常规 IVFAQ 编码器相同。代码在此时未按块重新组织

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual bool lookup_table_is_3d() const override

virtual void compute_LUT(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<float> &dis_tables, AlignedTable<float> &biases) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

void compute_LUT_uint8(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<uint8_t> &dis_tables, AlignedTable<uint16_t> &biases, float *normalizers) const

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker *get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n ( idx_t i0, idx_t ni, float *recons ) const override 提取一组向量.

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct ( idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr ) const override 搜索并重建向量。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes ( idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr ) const 搜索并返回码本。

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids ( const IDSelector &sel ) override 删除一批ID。

Dataset manipulation functions.

virtual void check_compatible_for_merge ( const Index &otherIndex ) const override 检查是否适合与其他索引合并.

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from ( Index &otherIndex, idx_t add_id ) override 从另一个索引合并。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取列表大小

检查ID是否已排序

ID 是否已排序？

创建直接映射

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型

替换倒排列表

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

获取辅助编码大小

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

AdditiveQuantizer *aq

bool rescale_norm = false

int norm_scale = 1

size_t max_train_points

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

InvertedLists *orig_invlists = nullptr

原始倒排列表（用于调试）

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFLocalSearchQuantizerFastScan : public faiss::IndexIVFAdditiveQuantizerFastScan

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFLocalSearchQuantizerFastScan(索引 *量化器, size_t d, size_t nlist, size_t M, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_lsq2x4, int bbs = 32)

IndexIVFLocalSearchQuantizerFastScan()

void init(AdditiveQuantizer *aq, size_t nlist, MetricType metric, int bbs)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

void estimate_norm_scale(idx_t n, const float *x)

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const override

与常规 IVFAQ 编码器相同。代码在此时未按块重新组织

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual bool lookup_table_is_3d() const override

virtual void compute_LUT(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<float> &dis_tables, AlignedTable<float> &biases) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

void compute_LUT_uint8(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<uint8_t> &dis_tables, AlignedTable<uint16_t> &biases, float *normalizers) const

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker *get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

检查是否可以合并

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

从另一个索引合并

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

将子集复制到另一个IndexIVF

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

LocalSearchQuantizer lsq

AdditiveQuantizer *aq

bool rescale_norm = false

int norm_scale = 1

size_t max_train_points

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

原始倒排列表。类型：InvertedLists*，默认值：nullptr。

原始倒排列表（用于调试）

倒排列表。类型：InvertedLists*，默认值：nullptr。

访问实际数据。

是否拥有倒排列表。类型：bool，默认值：false。

编码大小。类型：size_t，默认值：0。

每个向量的代码大小，以字节为单位

并行模式。类型：int，默认值：0。

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

PARALLEL_MODE_NO_HEAP_INIT。类型：const int，默认值：1024。

直接映射。类型：DirectMap。

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

是否使用残差。类型：bool，默认值：true。

invlist中的代码是否编码了相对于质心的向量？

向量维度。类型：int。

向量维度

索引中的向量总数。类型：idx_t。

索引向量的总数

是否启用详细模式。类型：bool。

详细级别

索引是否已训练。类型：bool。

如果 Index 不需要训练，或者如果已经完成训练，则设置

距离度量类型。类型：MetricType。

此索引用于搜索的度量类型

距离度量参数。类型：float。

度量类型的参数

搜索时访问的倒排列表数量。类型：size_t，默认值：1。

查询时的探针数量

每个向量的最大编码数。类型：size_t，默认值：0。

查询时要访问的最大代码数量

量化器。类型：Index*，默认值：nullptr。

quantizer that maps vectors to inverted lists

列表的数量。类型：size_t，默认值：0。

倒排列表的数量

量化器是否单独训练。类型：char，默认值：0。

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

是否拥有字段。类型：bool，默认值：false。

whether object owns the quantizer

聚类参数。类型：ClusteringParameters。

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFResidualQuantizerFastScan : public faiss::IndexIVFAdditiveQuantizerFastScan

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFResidualQuantizerFastScan(Index *quantizer, size_t d, size_t nlist, size_t M, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_lsq2x4, int bbs = 32)

IndexIVFResidualQuantizerFastScan()

void init(AdditiveQuantizer *aq, size_t nlist, MetricType metric, int bbs)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

void estimate_norm_scale(idx_t n, const float *x)

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const override

与常规 IVFAQ 编码器相同。代码在此时未按块重新组织

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual bool lookup_table_is_3d() const override

virtual void compute_LUT(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<float> &dis_tables, AlignedTable<float> &biases) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

void compute_LUT_uint8(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<uint8_t> &dis_tables, AlignedTable<uint16_t> &biases, float *normalizers) const

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker *get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

训练索引。

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取列表大小。

检查 ID 是否已排序。

ID 是否已排序？

创建直接映射。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型。

替换倒排列表。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

获取 SA 编码大小。

生成的代码的大小（以字节为单位）

进行 SA 编码。

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

分配。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

批量重建。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

计算残差。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算 n 个残差。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ResidualQuantizer rq

AdditiveQuantizer *aq

bool rescale_norm = false

int norm_scale = 1

size_t max_train_points

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

InvertedLists *orig_invlists = nullptr

原始倒排列表（用于调试）

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFProductLocalSearchQuantizerFastScan : public faiss::IndexIVFAdditiveQuantizerFastScan

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFProductLocalSearchQuantizerFastScan(Index *quantizer, size_t d, size_t nlist, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_lsq2x4, int bbs = 32)

IndexIVFProductLocalSearchQuantizerFastScan()

void init(AdditiveQuantizer *aq, size_t nlist, MetricType metric, int bbs)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

void estimate_norm_scale(idx_t n, const float *x)

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const override

与常规 IVFAQ 编码器相同。代码在此时未按块重新组织

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual bool lookup_table_is_3d() const override

virtual void compute_LUT(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<float> &dis_tables, AlignedTable<float> &biases) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

void compute_LUT_uint8(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<uint8_t> &dis_tables, AlignedTable<uint16_t> &biases, float *normalizers) const

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker *get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ProductLocalSearchQuantizer plsq

AdditiveQuantizer *aq

bool rescale_norm = false

int norm_scale = 1

size_t max_train_points

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

InvertedLists *orig_invlists = nullptr

原始倒排列表（用于调试）

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFProductResidualQuantizerFastScan : public faiss::IndexIVFAdditiveQuantizerFastScan

公共类型

using Search_type_t = AdditiveQuantizer::Search_type_t

using component_t = float

using distance_t = float

公共函数

IndexIVFProductResidualQuantizerFastScan(索引 *量化器, size_t d, size_t nlist, size_t nsplits, size_t Msub, size_t nbits, MetricType metric = METRIC_L2, Search_type_t search_type = AdditiveQuantizer::ST_norm_lsq2x4, int bbs = 32)

IndexIVFProductResidualQuantizerFastScan()

void init(加性量化器 *aq, size_t nlist, MetricType metric, int bbs)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

void estimate_norm_scale(idx_t n, const float *x)

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const override

与常规 IVFAQ 编码器相同。代码在此时未按块重新组织

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual bool lookup_table_is_3d() const override

virtual void compute_LUT(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<float> &dis_tables, AlignedTable<float> &biases) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

void compute_LUT_uint8(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<uint8_t> &dis_tables, AlignedTable<uint16_t> &biases, float *normalizers) const

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker *get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

搜索并重建。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ProductResidualQuantizer prq

AdditiveQuantizer *aq

bool rescale_norm = false

int norm_scale = 1

size_t max_train_points

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

InvertedLists *orig_invlists = nullptr

原始倒排列表（用于调试）

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFFastScan : public faiss::IndexIVF

#include <IndexIVFFastScan.h>

IVFPQ 和 IVFAQ 的快速扫描版本。目前适用于 4 位 PQ/AQ。

倒排列表中的代码不是顺序存储的，而是按大小为 bbs 的块分组的。 这使得可以使用 SIMD 指令非常快速地计算距离。

实现 (implem)：0：自动选择实现（默认） 1：原始搜索，重新实现 2：原始搜索，按 invlist 重新排序 10：优化器 int16 搜索，在堆中收集结果，无 qbs 11：同上，在水库中收集结果 12：优化器 int16 搜索，在堆中收集结果，使用 qbs 13：同上，在水库中收集结果 14：内部多线程 implem over nq * nprobe 15：与水库相同

对于范围搜索，仅支持 10 和 12。将 100 添加到 implem 以强制单线程扫描（粗量化器可能仍使用多个线程）。

由 faiss::IndexIVFAdditiveQuantizerFastScan, faiss::IndexIVFPQFastScan 子类化

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFFastScan(Index *quantizer, size_t d, size_t nlist, size_t code_size, MetricType metric = METRIC_L2)

IndexIVFFastScan()

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

~IndexIVFFastScan() override

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

确定查找表是否为 3D 的虚函数。

计算查找表的虚函数。

计算 uint8 类型的查找表。

执行搜索的虚函数。

分配向量，然后调用 search_preassign

执行预分配搜索的虚函数。

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

执行范围搜索的虚函数。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker* get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float* x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float* x) override

使用 NULL id 调用 add_with_ids。

virtual void add_core(idx_t n, const float* x, const idx_t* xids, const idx_t* precomputed_idx, void* inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void encode_vectors(idx_t n, const float* x, const idx_t* list_nos, uint8_t* codes, bool include_listno = false) const = 0

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void add_sa_codes(idx_t n, const uint8_t* codes, const idx_t* xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void train_encoder(idx_t n, const float* x, const idx_t* assign)

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const

可以被子类重新定义以指示他们需要多少训练向量

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

删除满足给定ID选择器的ID。

Dataset manipulation functions.

检查otherIndex是否兼容合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

从另一个索引合并数据。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

将索引的子集复制到另一个索引。

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取给定列表的大小。

检查ID是否已排序。

ID 是否已排序？

创建一个直接映射。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型。

替换倒排列表。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

返回共享分配符编码的大小。

生成的代码的大小（以字节为单位）

将数据编码为紧凑形式存储到字节数组中。

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

将向量分配到倒排列表。对于每个向量 `x[i]`，找到 `k` 个最近的聚类中心，并将它们的ID存储在 `labels[i * k : (i + 1) * k]` 中。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

InvertedLists *orig_invlists = nullptr

原始倒排列表（用于调试）

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct CoarseQuantized

公共成员

size_t nprobe

const float *dis = nullptr

const idx_t *ids = nullptr

struct IVFFastScanStats

公共函数

inline double Mcy_at(int i)

inline double Mcy_reservoir_at(int i)

inline IVFFastScanStats()

inline void reset()

公共成员

uint64_t times[10]

uint64_t t_compute_distance_tables

uint64_t t_round

uint64_t t_copy_pack

uint64_t t_scan

uint64_t t_to_flat

uint64_t reservoir_times[4]

double t_aq_encode

double t_aq_norm_encode

struct IndexIVFFlat : public faiss::IndexIVF

#include <IndexIVFFlat.h>

具有存储向量的倒排文件。 在这里，倒排文件预先选择要搜索的向量，但它们没有以其他方式进行编码，代码数组只包含原始的 float 条目。

被 faiss::IndexIVFFlatDedup 继承

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFFlat(Index *quantizer, size_t d, size_t nlist_, MetricType = METRIC_L2)

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr) override

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

IndexIVFFlat()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign)

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const

可以被子类重新定义以指示他们需要多少训练向量

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

将子集复制到。virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取列表大小。inline size_t get_list_size(size_t list_no) const

检查 ID 是否已排序。bool check_ids_sorted() const

ID 是否已排序？

创建直接映射。void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型。void set_direct_map_type(DirectMap::Type type)

替换倒排列表。void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

获取标量量化的码本大小。virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

标量量化编码函数。virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

分配 n 个向量到 k 个最近的簇。virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

从索引中重建向量。virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

计算向量 x 相对于索引中向量的残差。virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算多个向量相对于索引中向量的残差。virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取距离计算器（get distance computer）

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

训练 q1 (train q1)

训练量化器并调用 train_residual 来训练子量化器。

粗糙码的大小 (coarse code size)

计算存储列表 ID 所需的字节数

编码列表号 (encode list number)

解码列表号 (decode list number)

公共成员

倒排列表（inverted lists）

访问实际数据。

拥有倒排列表 (own inverted lists)

码的大小 (code size)

每个向量的代码大小，以字节为单位

并行模式 (parallel mode)

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

并行模式：无堆初始化 (PARALLEL_MODE_NO_HEAP_INIT)

直接映射 (direct map)

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

通过残差 (by residual)

invlist中的代码是否编码了相对于质心的向量？

维度 (dimension)

向量维度

总数 (total number of vectors)

索引向量的总数

详细模式 (verbose mode)

详细级别

是否已训练 (is trained)

如果 Index 不需要训练，或者如果已经完成训练，则设置

度量类型 (metric type)

此索引用于搜索的度量类型

度量参数 (metric argument)

度量类型的参数

探测数量 (number of probes)

查询时的探针数量

最大码数 (maximum number of codes)

查询时要访问的最大代码数量

量化器 (quantizer)

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFFlatDedup : public faiss::IndexIVFFlat

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFFlatDedup(Index *quantizer, size_t d, size_t nlist_, MetricType = METRIC_L2)

virtual void train(idx_t n, const float *x) override

也对训练集进行去重

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

为所有 IndexIVF* 类实现

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

未实现

virtual void update_vectors(int nv, const idx_t *idx, const float *v) override

未实现

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

未实现

inline IndexIVFFlatDedup()

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr) override

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void reset() override

从数据库中删除所有元素。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign)

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const

可以被子类重新定义以指示他们需要多少训练向量

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

制作直接映射（make direct map）。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型（set direct map type）。

替换倒排列表（replace inverted lists）。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

std::unordered_multimap<idx_t, idx_t> instances

将索引中存储的 ID 映射到相同向量的 ID。当向量是唯一的时候，它不会出现在 instances 映射中。

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFIndependentQuantizer : public faiss::Index

#include <IndexIVFIndependentQuantizer.h>

一个 IVF 索引，其量化器的输入维度与有效载荷大小不同。 要编码的向量通过 VectorTransform 从输入向量获得。

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFIndependentQuantizer(Index *quantizer, IndexIVF *index_ivf, VectorTransform *vt = nullptr)

inline IndexIVFIndependentQuantizer()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void reset() override

从数据库中删除所有元素。

~IndexIVFIndependentQuantizer() override

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

Index *quantizer = nullptr

量化器直接从输入向量馈送

VectorTransform *vt = nullptr

在应用 IVF 向量之前的变换

IndexIVF *index_ivf = nullptr

IVF 索引，控制 nlist 和 nprobe

bool own_fields = false

无论 *this 是否拥有这 3 个字段

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IVFPQSearchParameters : public faiss::SearchParametersIVF

公共函数

inline IVFPQSearchParameters()

inline ~IVFPQSearchParameters()

公共成员

size_t scan_table_threshold

使用表格计算还是即时计算？

int polysemous_ht

用于多义性过滤的汉明阈值。

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

SearchParameters *quantizer_params = nullptr

void *inverted_list_context = nullptr

要传递给 InvertedLists 的上下文对象

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct IndexIVFPQ : public faiss::IndexIVF

#include <IndexIVFPQ.h>

带有乘积量化器编码的倒排文件。每个残差向量被编码为乘积量化器代码。

由faiss::IndexIVFPQR子类化

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFPQ(Index *quantizer, size_t d, size_t nlist, size_t M, size_t nbits_per_idx, MetricType metric = METRIC_L2)

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr) override

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

void add_core_o(idx_t n, const float *x, const idx_t *xids, float *residuals_2, const idx_t *precomputed_idx = nullptr, void *inverted_list_context = nullptr)

与 add_core 相同，也

• 如果 residuals_2 != NULL，则输出第二级残差

• 接受 precomputed_idx = nullptr

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练乘积量化器

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

size_t find_duplicates(idx_t *ids, size_t *lims) const

在数据集中查找完全重复项。

重复项在预分配的数组中返回（请参见最大尺寸）。

参数：

• lims – 重复项组之间的限制（最大尺寸为 ntotal / 2 + 1）

• ids – ids[lims[i]] : ids[lims[i+1]-1] 是一组重复项（最大尺寸为 ntotal）

返回值：

n 找到的组数

void encode(idx_t key, const float *x, uint8_t *code) const

void encode_multiple(size_t n, idx_t *keys, const float *x, uint8_t *codes, bool compute_keys = false) const

对多个向量进行编码

参数：

• n – 要编码的向量数量

• keys – 这些向量的倒排列表 ID（大小为 n）

• x – 向量（大小为 n * d）

• codes – 输出代码（大小为 n * code_size）

• compute_keys – 如果为 false，则假定密钥已预先计算，否则计算它们

void decode_multiple(size_t n, const idx_t *keys, const uint8_t *xcodes, float *x) const

encode_multiple 的逆运算

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

void precompute_table()

构建预计算表

IndexIVFPQ()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

虚函数。给定一组预先分配的聚类以及到查询向量的距离，执行范围搜索。

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

虚函数。查找最近的 k 个向量。

分配向量，然后调用 search_preassign

虚函数。查找半径范围内的向量。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

虚函数。从索引中重建向量。

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

虚函数。更新索引中的向量。

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

虚函数。从索引中重建多个向量。

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

虚函数。查找最近的 k 个向量，并重建它们。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ProductQuantizer pq

产生代码

bool do_polysemous_training

训练后重新排序 PQ 质心？

PolysemousTraining *polysemous_training

如果为 NULL，则使用默认值

size_t scan_table_threshold

使用表格计算还是即时计算？

int polysemous_ht

用于多义性过滤的汉明阈值。

int use_precomputed_table

预先计算表，以在一定内存成本下加速查询预处理（仅用于带有 L2 度量的 by_residual）

AlignedTable<float> precomputed_table

如果 use_precompute_table 大小为 nlist * pq.M * pq.ksub

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFPQStats

#include <IndexIVFPQ.h>

统计数据对于内部线程处理是健壮的，但如果 IndexIVFPQ::search_preassigned 被多个线程调用则不成立

公共函数

inline IndexIVFPQStats()

void reset()

公共成员

size_t nrefine

精炼次数 (IVFPQR)

size_t n_hamming_pass

通过的汉明距离测试次数（对于多义词）

size_t search_cycles

size_t refine_cycles

仅适用于 IVFPQR

struct IndexIVFPQFastScan : public faiss::IndexIVFFastScan

#include <IndexIVFPQFastScan.h>

IVFPQ 的快速扫描版本。目前适用于 4 位 PQ。

倒排列表中的代码不是顺序存储的，而是按大小为 bbs 的块分组的。 这使得可以使用 SIMD 指令非常快速地计算距离。

实现 (implem): 0: 自动选择实现 (默认) 1: orig 的搜索，重新实现 2: orig 的搜索，按 invlist 重新排序 10: 优化器 int16 搜索，在堆中收集结果，无 qbs 11: 相同，在存储池中收集结果 12: 优化器 int16 搜索，在堆中收集结果，使用 qbs 13: 相同，在存储池中收集结果

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFPQFastScan(Index *quantizer, size_t d, size_t nlist, size_t M, size_t nbits, MetricType metric = METRIC_L2, int bbs = 32)

IndexIVFPQFastScan()

explicit IndexIVFPQFastScan(const IndexIVFPQ &orig, int bbs = 32)

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

void precompute_table()

构建预计算表，可能会更新 use_precomputed_table

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listno = false) const override

与常规 IVFPQ 编码器相同。代码此时未按块重新组织

virtual bool lookup_table_is_3d() const override

virtual void compute_LUT(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<float> &dis_tables, AlignedTable<float> &biases) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void init_fastscan(size_t M, size_t nbits, size_t nlist, MetricType metric, int bbs)

void init_code_packer()

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

void compute_LUT_uint8(size_t n, const float *x, const CoarseQuantized &cq, AlignedTable<uint8_t> &dis_tables, AlignedTable<uint16_t> &biases, float *normalizers) const

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void range_search_dispatch_implem(idx_t n, const float *x, float radius, RangeSearchResult &rres, const CoarseQuantized &cq_in, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_1(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

template<class C>
void search_implem_2(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_10(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_12(idx_t n, const float *x, SIMDResultHandlerToFloat &handler, const CoarseQuantized &cq, size_t *ndis_out, size_t *nlist_out, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const CoarseQuantized &cq, int impl, const NormTableScaler *scaler, const IVFSearchParameters *params = nullptr) const

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当 direct_map 未维护，且 inv list 偏移量通过设置了 store_pairs 的 search_preassigned() 计算时，可用于重建。

virtual CodePacker *get_CodePacker() const override

void reconstruct_orig_invlists()

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

添加向量到索引的核心函数。允许指定ID和预先计算的索引。

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs = false, const IDSelector *sel = nullptr) const

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

inline size_t get_list_size(size_t list_no) const

bool check_ids_sorted() const

ID 是否已排序？

void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

void set_direct_map_type(DirectMap::Type type)

void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ProductQuantizer pq

产生代码

int use_precomputed_table = 0

预计算表管理

AlignedTable<float> precomputed_table

如果 use_precompute_table 大小 (nlist, pq.M, pq.ksub)

int bbs

size_t M

size_t nbits

size_t ksub

size_t M2

int implem = 0

int skip = 0

int qbs = 0

size_t qbs2 = 0

InvertedLists *orig_invlists = nullptr

原始倒排列表（用于调试）

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFPQR : public faiss::IndexIVFPQ

#include <IndexIVFPQR.h>

具有附加 PQ 细化级别的 索引

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFPQR(Index *量化器, size_t d, size_t nlist, size_t M, size_t nbits_per_idx, size_t M_refine, size_t nbits_per_idx_refine)

virtual void reset() override

从数据库中删除所有元素。

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练两个乘积量化器

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr) override

与 add_with_ids 相同，但可以选择使用预先计算的列表 ID

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 设置 store_pairs 来计算 inv 列表偏移量时很有用。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

IndexIVFPQR()

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void add_core_o(idx_t n, const float *x, const idx_t *xids, float *residuals_2, const idx_t *precomputed_idx = nullptr, void *inverted_list_context = nullptr)

与 add_core 相同，也

• 如果 residuals_2 != NULL，则输出第二级残差

• 接受 precomputed_idx = nullptr

size_t find_duplicates(idx_t *ids, size_t *lims) const

在数据集中查找完全重复项。

重复项在预分配的数组中返回（请参见最大尺寸）。

参数：

• lims – 重复项组之间的限制（最大尺寸为 ntotal / 2 + 1）

• ids – ids[lims[i]] : ids[lims[i+1]-1] 是一组重复项（最大尺寸为 ntotal）

返回值：

n 找到的组数

void encode(idx_t key, const float *x, uint8_t *code) const

void encode_multiple(size_t n, idx_t *keys, const float *x, uint8_t *codes, bool compute_keys = false) const

对多个向量进行编码

参数：

• n – 要编码的向量数量

• keys – 这些向量的倒排列表 ID（大小为 n）

• x – 向量（大小为 n * d）

• codes – 输出代码（大小为 n * code_size）

• compute_keys – 如果为 false，则假定密钥已预先计算，否则计算它们

void decode_multiple(size_t n, const idx_t *keys, const uint8_t *xcodes, float *x) const

encode_multiple 的逆运算

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

void precompute_table()

构建预计算表

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

检查是否兼容以进行合并：virtual CodePacker *get_CodePacker() const

获取代码打包器：virtual void copy_subset_to(IndexIVF &other, InvertedLists::subset_type_t subset_type, idx_t a1, idx_t a2) const

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

复制子集到：inline size_t get_list_size(size_t list_no) const

获取列表大小：bool check_ids_sorted() const

ID 是否已排序？

检查 ID 是否已排序：void make_direct_map(bool new_maintain_direct_map = true)

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

创建直接映射：void set_direct_map_type(DirectMap::Type type)

设置直接映射类型：void replace_invlists(InvertedLists *il, bool own = false)

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

替换倒排列表：virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

获取辅助编码的大小：virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

辅助编码：virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

分配：virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

批量重建：virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ProductQuantizer refine_pq

第 3 层量化器

std::vector<uint8_t> refine_codes

相应的代码

float k_factor

在搜索中请求的 k 与从 IVFPQ 请求的 k 之间的因子

ProductQuantizer pq

产生代码

bool do_polysemous_training

训练后重新排序 PQ 质心？

PolysemousTraining *polysemous_training

如果为 NULL，则使用默认值

size_t scan_table_threshold

使用表格计算还是即时计算？

int polysemous_ht

用于多义性过滤的汉明阈值。

int use_precomputed_table

预先计算表，以在一定内存成本下加速查询预处理（仅用于带有 L2 度量的 by_residual）

AlignedTable<float> precomputed_table

如果 use_precompute_table 大小为 nlist * pq.M * pq.ksub

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexIVFSpectralHash : public faiss::IndexIVF

#include <IndexIVFSpectralHash.h>

倒排列表，存储大小为 nbit 的二进制码。在二进制转换之前，向量的维度从 dim d 通过 vt（默认为随机旋转）转换为 dim nbit。

每个坐标都从由 threshold_type 确定的值中减去，并分成大小为 period 的间隔。间隔的一半是 0 位，另一半是 1 位。

公共类型

enum ThresholdType

值

enumerator Thresh_global

全局阈值为 0

enumerator Thresh_centroid

与质心比较

enumerator Thresh_centroid_half

质心周围的中心间隔

enumerator Thresh_median

训练集的中位数

using component_t = float

using distance_t = float

公共函数

翻译: IndexIVFSpectralHash(Index *量化器, size_t d, size_t nlist, int nbit, float 周期)

IndexIVFSpectralHash()

翻译: virtual void 训练编码器(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

翻译: virtual void 编码向量(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

翻译: virtual InvertedListScanner *获取倒排列表扫描器(bool 存储配对, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

翻译: void 替换向量变换(VectorTransform *vt, bool own = false)

翻译: 替换一个空（且可能未训练）索引的向量变换。

翻译: void 替换向量变换(IndexPreTransform *index, bool own = false)

翻译: 便捷函数，用于从由 index_factory 构造的索引中获取 VT（应以“LSH”结尾）。

翻译: ~IndexIVFSpectralHash() override （析构函数）

virtual void reset() override

从数据库中删除所有元素。

virtual void train(idx_t n, const float *x) override

训练量化器并调用 train_encoder 来训练子量化器。

virtual void add(idx_t n, const float *x) override

使用 NULL id 调用 add_with_ids。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

调用 encode_vectors 的默认实现

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr)

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

virtual idx_t train_encoder_num_vectors() const

可以被子类重新定义以指示他们需要多少训练向量

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual CodePacker *get_CodePacker() const

将子集复制到另一个索引。

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取倒排列表的大小。

检查 ID 是否已排序。

ID 是否已排序？

创建直接映射，用于根据 ID 查找向量。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射的类型。

替换索引中的倒排列表。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

返回辅助属性代码的大小（以字节为单位）。

生成的代码的大小（以字节为单位）

将一个向量编码为辅助属性。

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

分配向量给倒排列表。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

重建一批向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

计算向量相对于重建向量的残差。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算 n 个向量的残差。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

将签名（Signature）解码为浮点数向量。

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

VectorTransform *vt = nullptr

transformation from d to nbit dim

bool own_fields = true

own the vt

int nbit = 0

nb of bits of the binary signature

float period = 0

interval size for 0s and 1s

ThresholdType threshold_type = Thresh_global

std::vector<float> trained

Trained threshold. size nlist * nbit or 0 if Thresh_global

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

struct IndexLattice : public faiss::IndexFlatCodes

#include <IndexLattice.h>

Index 编码一系列 Zn 格量化器的向量

公共类型

using component_t = float

using distance_t = float

公共函数

IndexLattice(idx_t d, int nsq, int scale_nbit, int r2)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

Search implemented by decoding

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

int nsq

子向量的数量

size_t dsq

子向量的维度

ZnSphereCodecAlt zn_sphere_codec

格量化器

int scale_nbit

用于编码比例的位数，每个子向量

int lattice_nbit

std::vector<float> trained

每个子量化器的向量范数的最小值和最大值

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexLSH : public faiss::IndexFlatCodes

#include <IndexLSH.h>

每个向量分量的符号被放入一个二进制签名中

公共类型

using component_t = float

using distance_t = float

公共函数

IndexLSH(idx_t d, int nbits, bool rotate_data = true, bool train_thresholds = false)

const float *apply_preprocess(idx_t n, const float *x) const

预处理并将输入调整为二值化数据所需的大小

参数：

x – 输入向量，大小为 n * d

返回值：

输出向量，大小为 n * bits。 可能与 x 是同一个指针，否则应由调用者删除

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

Search implemented by decoding

void transfer_thresholds(LinearTransform *vt)

将阈值转移到预处理阶段 (并取消 train_thresholds)

inline ~IndexLSH() override

IndexLSH()

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

排列条目。

添加带有 IDs 的向量。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

分配向量到最近的簇 (cluster)。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

重建一批向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

搜索并重建向量。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

计算残差。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算 n 个向量的残差。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

int nbits

每个向量的比特数。

bool rotate_data

是否对输入应用随机旋转。

bool train_thresholds

是否训练阈值或使用 0。

RandomRotationMatrix rrot

可选的随机旋转。

std::vector<float> thresholds

要比较的阈值

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexNeuralNetCodec : public faiss::IndexFlatCodes

被 faiss::IndexQINCo 继承

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexNeuralNetCodec(int d = 0, int M = 0, int nbits = 0, MetricType metric = METRIC_L2)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void sa_encode(idx_t n, const float *x, uint8_t *codes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *codes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

inline ~IndexNeuralNetCodec()

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

Search implemented by decoding

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

将向量分配到最近的簇，并将簇ID存储在 labels 中。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

根据给定的 keys 重建向量，并将结果存储在 recons 中。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

搜索最近邻并重建它们。 distances, labels 和 recons 被填入结果。 可以选择传递搜索参数。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

计算向量 x 和其重建版本之间的残差，重建版本由 key 标识。残差存储在 residual 中。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算多个向量 xs 和它们对应的重建版本（由 keys 标识）之间的残差，并将结果存储在 residuals 中。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

指向 NeuralNetCodec 的指针，默认为 nullptr。

码本的数量。

每个码本的位数。

每个向量的编码大小（字节）。

包含所有向量的编码。

编码后的数据集，大小为 ntotal * code_size

向量的维度。

向量维度

索引中向量的总数。

索引向量的总数

是否启用详细输出。

详细级别

索引是否已训练。

如果 Index 不需要训练，或者如果已经完成训练，则设置

使用的距离度量类型。

此索引用于搜索的度量类型

距离度量的参数 (例如，Lp 距离的 p)。

度量类型的参数

struct IndexQINCo : public faiss::IndexNeuralNetCodec

公共类型

using component_t = float

using distance_t = float

公共函数

IndexQINCo(int d, int M, int nbits, int L, int h, MetricType metric = METRIC_L2)

inline ~IndexQINCo()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void sa_encode(idx_t n, const float *x, uint8_t *codes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *codes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

inline virtual DistanceComputer * get_distance_computer ( ) const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void search ( idx_t n, const float * x, idx_t k, float * distances, idx_t * labels, const SearchParameters * params = nullptr ) const override

Search implemented by decoding

virtual void range_search ( idx_t n, const float * x, float radius, RangeSearchResult * result, const SearchParameters * params = nullptr ) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker * get_CodePacker ( ) const

virtual void check_compatible_for_merge ( const Index & otherIndex ) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from ( Index & otherIndex, idx_t add_id = 0 ) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes ( idx_t n, const uint8_t * x, const idx_t * xids ) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries ( const idx_t * perm )

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

QINCo qinco

NeuralNetCodec *net = nullptr

size_t M

size_t nbits

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexNNDescent : public faiss::Index

#include <IndexNNDescent.h>

NNDescent 索引是一个普通的随机访问索引，其顶部构建了一个 NNDescent 链接结构

由 faiss::IndexNNDescentFlat 继承

公共类型

using storage_idx_t = NNDescent::storage_idx_t

using component_t = float

using distance_t = float

公共函数

explicit IndexNNDescent(int d = 0, int K = 32, MetricType metric = METRIC_L2)

explicit IndexNNDescent(Index *storage, int K = 32)

~IndexNNDescent() override

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

NNDescent nndescent

Faiss 结果是 64 位的。

bool own_fields

Index *storage

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexNNDescentFlat : public faiss::IndexNNDescent

#include <IndexNNDescent.h>

Flat 索引，顶部带有 NNDescent 结构，以便更有效地访问元素。

公共类型

using storage_idx_t = NNDescent::storage_idx_t

using component_t = float

using distance_t = float

公共函数

IndexNNDescentFlat()

IndexNNDescentFlat(int d, int K, MetricType metric = METRIC_L2)

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float * x, float * residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

NNDescent nndescent

Faiss 结果是 64 位的。

bool own_fields

Index *storage

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexNSG : public faiss::Index

#include <IndexNSG.h>

NSG 索引是一个带 NSG 链接结构构建在顶部的普通随机访问索引。

被 faiss::IndexNSGFlat, faiss::IndexNSGPQ, faiss::IndexNSGSQ 继承。

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexNSG(int d = 0, int R = 32, MetricType metric = METRIC_L2)

explicit IndexNSG(Index *storage, int R = 32)

~IndexNSG() override

void build(idx_t n, const float *x, idx_t *knn_graph, int GK)

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

void check_knn_graph(const idx_t *knn_graph, idx_t n, int K) const

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算多个残差。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

获取 `sa` 代码的大小（以字节为单位）。

生成的代码的大小（以字节为单位）

将向量编码为 `sa` 代码。

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

将 `sa` 代码解码为向量。

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

从另一个索引合并。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查是否可以从另一个索引合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加 `sa` 代码。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

NSG nsg

链接结构。

bool own_fields = false

顺序存储。

Index *storage = nullptr

bool is_built = false

索引是否已构建。

int GK = 64

用于构建的 KNN 图的 K 值。

char build_type = 0

指示如何构建 knn 图

• 0: 使用暴力搜索构建 NSG

• 1: 使用 NNDescent 构建 NSG

int nndescent_S = 10

nndescent 的参数

int nndescent_R = 100

int nndescent_L

int nndescent_iter = 10

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexNSGFlat : public faiss::IndexNSG

#include <IndexNSG.h>

Flat 索引，顶部带有 NSG 结构，以便更有效地访问元素。

公共类型

using component_t = float

using distance_t = float

公共函数

IndexNSGFlat()

IndexNSGFlat(int d, int R, MetricType metric = METRIC_L2)

void build(idx_t n, const float *x, idx_t *knn_graph, int GK)

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

重置索引，删除所有向量。

从数据库中删除所有元素。

检查k近邻图。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

NSG nsg

链接结构。

bool own_fields = false

顺序存储。

Index *storage = nullptr

bool is_built = false

索引是否已构建。

int GK = 64

用于构建的 KNN 图的 K 值。

char build_type = 0

指示如何构建 knn 图

• 0: 使用暴力搜索构建 NSG

• 1: 使用 NNDescent 构建 NSG

int nndescent_S = 10

nndescent 的参数

int nndescent_R = 100

int nndescent_L

int nndescent_iter = 10

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexNSGPQ : public faiss::IndexNSG

#include <IndexNSG.h>

PQ索引，顶部带有NSG结构，以便更高效地访问元素。

公共类型

using component_t = float

using distance_t = float

公共函数

IndexNSGPQ()

IndexNSGPQ(int d, int pq_m, int M, int pq_nbits = 8)

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

构建索引。

向索引添加向量。

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

在索引中搜索最近邻。

搜索的入口点

从索引重建向量。

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

重置索引，移除所有向量。

从数据库中删除所有元素。

检查 KNN 图的有效性。

向索引添加带有 ID 的向量。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

在索引中执行范围搜索。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

将向量分配给最近的簇。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

从索引中删除 ID。

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

批量从索引重建向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

NSG nsg

链接结构。

bool own_fields = false

顺序存储。

Index *storage = nullptr

is_built = false

索引是否已构建。

GK = 64

用于构建的 KNN 图的 K 值。

build_type = 0

指示如何构建 knn 图

• 0: 使用暴力搜索构建 NSG

• 1: 使用 NNDescent 构建 NSG

nndescent_S = 10

nndescent 的参数

nndescent_R = 100

nndescent_L

nndescent_iter = 10

维度 d

向量维度

总向量数 ntotal

索引向量的总数

是否显示详细信息 verbose

详细级别

是否已训练 is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

距离类型 metric_type

此索引用于搜索的度量类型

距离参数 metric_arg

度量类型的参数

结构体 IndexNSGSQ : public faiss::IndexNSG

#include <IndexNSG.h>

SQ 索引，顶部带有 NSG 结构，以便更有效地访问元素。

公共类型

别名 component_t = float

别名 distance_t = float

公共函数

构造函数 IndexNSGSQ()

IndexNSGSQ(int d, ScalarQuantizer::QuantizerType qtype, int M, MetricType metric = METRIC_L2)

void build(idx_t n, const float *x, idx_t *knn_graph, int GK)

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void train(idx_t n, const float *x) override

如果需要，训练存储。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

搜索的入口点

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reset() override

从数据库中删除所有元素。

void check_knn_graph(const idx_t *knn_graph, idx_t n, int K) const

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

NSG nsg

链接结构。

bool own_fields = false

顺序存储。

Index *storage = nullptr

bool is_built = false

索引是否已构建。

int GK = 64

用于构建的 KNN 图的 K 值。

char build_type = 0

指示如何构建 knn 图

• 0: 使用暴力搜索构建 NSG

• 1: 使用 NNDescent 构建 NSG

int nndescent_S = 10

nndescent 的参数

int nndescent_R = 100

int nndescent_L

int nndescent_iter = 10

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexPQ : public faiss::IndexFlatCodes

#include <IndexPQ.h>

基于乘积量化器的Index。存储的向量通过PQ码近似表示。

公共类型

enum Search_type_t

如何在search_core中执行搜索

值

enumerator ST_PQ

非对称乘积量化器（默认）

enumerator ST_HE

代码上的汉明距离。

enumerator ST_generalized_HE

相同代码的数量

enumerator ST_SDC

对称乘积量化器 (SDC)

enumerator ST_polysemous

HE过滤器（使用ht）+ PQ组合。

enumerator ST_polysemous_generalize

广义汉明距离上的过滤器。

using component_t = float

using distance_t = float

公共函数

IndexPQ(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2)

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

IndexPQ()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

Search implemented by decoding

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual FlatCodesDistanceComputer *get_FlatCodesDistanceComputer() const override

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

void search_core_polysemous(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int polysemous_ht, bool generalized_hamming) const

void hamming_distance_histogram(idx_t n, const float *x, idx_t nb, const float *xb, int64_t *dist_histogram)

准备用于多义搜索的查询，但不是计算结果，而是获取汉明距离的直方图。 如果 xb != NULL，则可以在提供的数据集上计算

参数：

dist_histogram – (M * nbits + 1)

void hamming_distance_table(idx_t n, const float *x, int32_t *dis) const

计算查询和数据库之间的成对距离

参数：

• n – 查询向量的数量

• x – 查询向量，大小为 n * d

• dis – 输出距离，大小为 n * ntotal

virtual void add(idx_t n, const float *x) override

默认的 add 使用 sa_encode

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

ProductQuantizer pq

用于编码向量的乘积量化器。

bool do_polysemous_training

false = 标准 PQ

PolysemousTraining polysemous_training

用于多义训练的参数

Search_type_t search_type

bool encode_signs

int polysemous_ht

用于多义性的汉明阈值。

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct SearchParametersPQ : public faiss::SearchParameters

#include <IndexPQ.h>

从类中覆盖搜索参数

公共成员

IndexPQ::Search_type_t search_type

int polysemous_ht

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct IndexPQStats

#include <IndexPQ.h>

统计信息对于内部线程处理是稳健的，但如果 IndexPQ::search 被多个线程调用则不是。

公共函数

inline IndexPQStats()

void reset()

公共成员

size_t nq

size_t ncode

size_t n_hamming_pass

struct MultiIndexQuantizer : public faiss::Index

#include <IndexPQ.h>

Quantizer，其中质心是虚拟的：它们是子质心的笛卡尔积。

由 faiss::MultiIndexQuantizer2 继承。

公共类型

using component_t = float

using distance_t = float

公共函数

MultiIndexQuantizer(int d, size_t M, size_t nbits)

每个子向量索引的位数

参数：

• d – 输入向量的维度

• M – 子量化器的数量

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void add(idx_t n, const float *x) override

add 和 reset 将在运行时崩溃

virtual void reset() override

从数据库中删除所有元素。

inline MultiIndexQuantizer()

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

ProductQuantizer pq

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct MultiIndexQuantizer2 : public faiss::MultiIndexQuantizer

#include <IndexPQ.h>

MultiIndexQuantizer，其中 PQ 分配由子索引执行

公共类型

using component_t = float

using distance_t = float

公共函数

MultiIndexQuantizer2(int d, size_t M, size_t nbits, Index **indexes)

MultiIndexQuantizer2(int d, size_t nbits, Index *assign_index_0, Index *assign_index_1)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void add(idx_t n, const float *x) override

add 和 reset 将在运行时崩溃

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

std::vector<Index*> assign_indexes

维度为 d / M 的 M 个索引。

bool own_fields

ProductQuantizer pq

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexPQFastScan : public faiss::IndexFastScan

#include <IndexPQFastScan.h>

快速扫描版本的 IndexPQ。 目前适用于 4 位 PQ。

代码不是按顺序存储的，而是分组在大小为 bbs 的块中。这使得可以使用 SIMD 指令快速计算距离。

实现：12：带有 Q 内部循环的块循环，qbs 为 13：与存储结果的储层累加器相同 14：没有带堆累加器的 qbs 15：没有带储层累加器的 qbs

公共类型

using component_t = float

using distance_t = float

公共函数

IndexPQFastScan(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2, int bbs = 32)

IndexPQFastScan() = default

explicit IndexPQFastScan(const IndexPQ &orig, int bbs = 32)

从现有的 IndexPQ 构建

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void compute_codes(uint8_t *codes, idx_t n, const float *x) const override

virtual void compute_float_LUT(float *lut, idx_t n, const float *x) const override

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量。

注意： IndexPQFastScan 对象中的代码是不连续的。但是此方法需要连续的表示。

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * code_size

• x – 输出向量，大小为 n * d

void init_fastscan(int d, size_t M, size_t nbits, MetricType metric, int bbs)

virtual void reset() override

从数据库中删除所有元素。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

void compute_quantized_LUT(idx_t n, const float *x, uint8_t *lut, float *normalizers) const

template<bool is_max>
void search_dispatch_implem(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class Cfloat>
void search_implem_234(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const NormTableScaler *scaler) const

template<class C>
void search_implem_12(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

template<class C>
void search_implem_14(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, int impl, const NormTableScaler *scaler) const

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t remove_ids(const IDSelector &sel) override

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

CodePacker *get_CodePacker() const

将另一个索引合并到当前索引中。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查要合并的索引是否兼容。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加带有ID的向量到索引中。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

ProductQuantizer pq

int implem = 0

int skip = 0

int bbs

int qbs = 0

size_t M

size_t nbits

size_t ksub

size_t code_size

size_t ntotal2

size_t M2

AlignedTable<uint8_t> codes

const uint8_t *orig_codes = nullptr

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct SearchParametersPreTransform : public faiss::SearchParameters

公共成员

SearchParameters *index_params = nullptr

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct IndexPreTransform : public faiss::Index

#include <IndexPreTransform.h>

Index，它在将向量交给子索引之前，对向量应用 LinearTransform 变换

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexPreTransform(Index *index)

! 指针是否在析构函数中被删除

IndexPreTransform()

IndexPreTransform(VectorTransform *ltrans, Index *index)

ltrans 是索引之前的最后一个变换

void prepend_transform(VectorTransform *ltrans)

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids) override

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void reset() override

从数据库中删除所有元素。

virtual size_t remove_ids(const IDSelector &sel) override

从索引中删除ID。并非所有索引都支持。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

const float *apply_chain(idx_t n, const float *x) const

应用链中的变换。返回的 float * 可能等于 x，否则应该被释放。

void reverse_chain(idx_t n, const float *xt, float *x) const

反转链中的变换。可能不会为链中的所有变换实现，或者可能返回近似结果。

virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

~IndexPreTransform() override

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

std::vector<VectorTransform*> chain

Index *index

! 变换链

bool own_fields

! 子索引

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexRefineSearchParameters : public faiss::SearchParameters

公共函数

virtual ~IndexRefineSearchParameters() = default

公共成员

float k_factor = 1

SearchParameters *base_index_params = nullptr

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct IndexRefine : public faiss::Index

#include <IndexRefine.h>

Index 在 base_index（一个快速的索引）中查询，并使用精确搜索来优化结果，希望能提高结果。

由 faiss::IndexRefineFlat 继承

公共类型

using component_t = float

using distance_t = float

公共函数

IndexRefine(Index *base_index, Index *refine_index)

从空索引初始化

IndexRefine()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void reset() override

从数据库中删除所有元素。

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

sa_decode 从 index_refine 解码，假定 index_refine 更准确

~IndexRefine() override

将带有ID的数据添加到索引中。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

执行范围搜索。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

为向量分配标签。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

删除符合选择器ID的数据。

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

重建一批向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

从 i0 重建 ni 个向量。

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

搜索并重建向量。

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

计算残差。

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

计算 n 个向量的残差。

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

从另一个索引合并数据。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加补充分配码（supplementary assignment codes）。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

Index *base_index

用于预先选择要过滤的向量的更快索引。

Index *refine_index

精炼索引。

bool own_fields

是否应该释放基础索引？

bool own_refine_index

与精炼索引相同。

float k_factor = 1

搜索中请求的 k 和从 base_index 请求的 k 之间的因子（应 >= 1）。

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexRefineFlat : public faiss::IndexRefine

#include <IndexRefine.h>

精炼索引是 IndexFlat 的版本。 它有一个额外的构造函数，该构造函数接受一个元素表以添加到平面精炼索引中。

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexRefineFlat(Index *base_index)

IndexRefineFlat(Index *base_index, const float *xb)

IndexRefineFlat()

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void reset() override

从数据库中删除所有元素。

virtual void reconstruct(idx_t key, float *recons) const override

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

sa_decode 从 index_refine 解码，假定 index_refine 更准确

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

Index *base_index

用于预先选择要过滤的向量的更快索引。

Index *refine_index

精炼索引。

bool own_fields

是否应该释放基础索引？

bool own_refine_index

与精炼索引相同。

float k_factor = 1

搜索中请求的 k 和从 base_index 请求的 k 之间的因子（应 >= 1）。

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

template<typename IndexT>
class IndexReplicasTemplate : public faiss::ThreadedIndex<IndexT>

#include <IndexReplicas.h>

获取单独的 faiss::Index 实例，并拆分查询以发送到每个 Index 实例，并在完成后将结果连接在一起。每个索引都由单独的 CPU 线程管理。

公共类型

using component_t = typename IndexT::component_t

using distance_t = typename IndexT::distance_t

公共函数

explicit IndexReplicasTemplate(bool threaded = true)

所有子索引必须共享的维度将是添加的第一个子索引的维度

参数：

threaded – 我们是否为每个子索引使用一个线程，还是按顺序查询？

explicit IndexReplicasTemplate(idx_t d, bool threaded = true)

参数：

• d – 所有子索引必须共享的维度

• threaded – 我们是为每个子索引使用一个线程，还是按顺序查询？

explicit IndexReplicasTemplate(int d, bool threaded = true)

int 版本是由于 int 作为维度的隐式 bool 转换歧义

inline void add_replica(IndexT *index)

addIndex() 的别名

inline void remove_replica(IndexT *index)

removeIndex() 的别名

void train(idx_t n, const component_t *x) override

faiss::Index API。 所有索引都收到相同的调用

void add(idx_t n, const component_t *x) override

faiss::Index API。 所有索引都收到相同的调用

void search(idx_t n, const component_t *x, idx_t k, distance_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

faiss::Index API 查询被划分成每个子索引的切片，切片大小为 ceil(n / #indices)，#indices 为子索引的数量。

void reconstruct(idx_t, component_t *v) const override

从第一个索引重建。

void syncWithSubIndexes()

将顶层索引 (IndexShards) 与子索引中的数据同步。

virtual void addIndex(IndexT *index)

覆盖我们自己管理的索引。警告：一旦添加了索引，在关闭之前，从管理它的线程之外的任何其他线程触摸它都是不安全的。 使用 runOnIndex 在其上执行工作。

void removeIndex(IndexT *index)

删除我们自己管理的索引。 这将刷新该索引上的所有待处理工作，然后关闭其管理线程，并删除索引。

void runOnIndex(std::function<void(int, IndexT*)> f)

在索引的管理线程中，在所有索引上运行一个函数。 函数参数是（集合中的索引，索引指针）

void runOnIndex(std::function<void(int, const IndexT*)> f) const

void reset() override

faiss::Index API。 所有索引都收到相同的调用

inline int count() const

返回子索引的数量。

inline IndexT *at(size_t i)

返回第 i 个子索引。

inline const IndexT *at(size_t i) const

返回第 i 个子索引（const 版本）

公共成员

bool own_indices = false

我们是否负责删除包含的索引。

受保护的函数

virtual void onAfterAddIndex(IndexT *index) override

在添加索引后立即调用。

virtual void onAfterRemoveIndex(IndexT *index) override

在索引被移除后立即调用。

受保护的属性

std::vector<std::pair<IndexT*, std::unique_ptr<WorkerThread>>> indices_

Index 实例的集合，以及管理它们的工作线程（如果有）。

bool isThreaded_

这个索引是多线程的吗？

受保护的静态函数

static void waitAndHandleFutures(std::vector<std::future<bool>> &v)

struct IndexRowwiseMinMaxBase : public faiss::Index

#include <IndexRowwiseMinMax.h>

Provides base functions for rowwise normalizing indices.

Index 包装器，执行行向归一化到 [0,1]，保留系数。这只是一个向量编解码器索引。

基本上，此索引在调用 subindex::train() 和 subindex::sa_encode() 之前，对输入数据集中的每一行执行行向缩放到 [0,1]。 sa_encode() 调用将缩放系数（scaler 和 minv）存储在每个输出代码的开头。格式：[scaler][minv][subindex::sa_encode() 输出] sa_decode() 中的反缩放使用：output_rescaled = scaler * output + minv 完成

提供了一个额外的 ::train_inplace() 函数，以便在调用 subindex::train() 之前进行原地缩放，从而避免克隆输入数据集，但由于缩放和缩放返回而修改输入数据集。 由用户决定是否调用此函数来代替 ::train()

派生类为缩放系数提供不同的数据类型。 目前，可以使用 fp16 和 fp32 缩放系数的版本。

• fp16 版本为每个编码向量添加 4 个额外字节

• fp32 版本为每个编码向量添加 8 个额外字节

由 faiss::IndexRowwiseMinMax, faiss::IndexRowwiseMinMaxFP16 子类化

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexRowwiseMinMaxBase(Index *index)

IndexRowwiseMinMaxBase()

~IndexRowwiseMinMaxBase() override

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void reset() override

从数据库中删除所有元素。

virtual void train_inplace(idx_t n, float *x) = 0

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

Index *index

子索引

bool own_fields

指示是否需要在析构函数中释放子索引。

int d

向量维度

idx_t ntotal

索引向量的总数

是否详细输出

详细级别

是否已训练

如果 Index 不需要训练，或者如果已经完成训练，则设置

距离类型

此索引用于搜索的度量类型

距离参数

度量类型的参数

结构体 IndexRowwiseMinMaxFP16，继承自 IndexRowwiseMinMaxBase

#include <IndexRowwiseMinMax.h>

将缩放系数存储为 fp16 值。

公共类型

使用 component_t = float

使用 distance_t = float

公共函数

显式构造函数：IndexRowwiseMinMaxFP16(Index *index)

默认构造函数：IndexRowwiseMinMaxFP16()

虚函数，训练：train(idx_t n, const float *x)，重写基类方法

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

虚函数，原地训练：train_inplace(idx_t n, float *x)，重写基类方法

虚函数，获取 SA 编码大小：sa_code_size() const，重写基类方法

生成的代码的大小（以字节为单位）

虚函数，SA 编码：sa_encode(idx_t n, const float *x, uint8_t *bytes) const，重写基类方法

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

虚函数，SA 解码：sa_decode(idx_t n, const uint8_t *bytes, float *x) const，重写基类方法

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

虚函数，添加向量：add(idx_t n, const float *x)，重写基类方法

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void reset() override

从数据库中删除所有元素。

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

Index *index

子索引

bool own_fields

指示是否需要在析构函数中释放子索引。

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexRowwiseMinMax : public faiss::IndexRowwiseMinMaxBase

#include <IndexRowwiseMinMax.h>

将缩放系数存储为 fp32 值。

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexRowwiseMinMax(Index *index)

IndexRowwiseMinMax()

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void train_inplace(idx_t n, float *x) override

virtual size_t sa_code_size() const override

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

虚拟 void search(索引类型 n, const float *x, 索引类型 k, float *distances, 索引类型 *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

虚拟 void reset() override

从数据库中删除所有元素。

虚拟 void add_with_ids(索引类型 n, const float *x, const 索引类型 *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

虚拟 void range_search(索引类型 n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

虚拟 void assign(索引类型 n, const float *x, 索引类型 *labels, 索引类型 k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

虚拟 size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

虚拟 void reconstruct(索引类型 key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

虚拟 void reconstruct_batch(索引类型 n, const 索引类型 *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

虚拟 void reconstruct_n(索引类型 i0, 索引类型 ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查是否可以合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加标量量化码。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

底层索引。

子索引

是否拥有底层索引。

指示是否需要在析构函数中释放子索引。

向量维度。

向量维度

索引中的向量总数。

索引向量的总数

详细模式。

详细级别

索引是否经过训练。

如果 Index 不需要训练，或者如果已经完成训练，则设置

距离度量类型。

此索引用于搜索的度量类型

距离度量的参数。

度量类型的参数

基于标量量化器的平面索引。

#include <IndexScalarQuantizer.h>

构建在标量量化器上的平面索引。

公共类型

组件类型。

距离类型。

公共函数

构造函数。

构造函数。

参数：

• d – 输入向量的维度

• M – 子量化器的数量

• nbits – 每个子向量索引的比特数

默认构造函数。

x: 训练向量

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

params: 搜索参数

Search implemented by decoding

指向 FlatCodesDistanceComputer 对象的指针。

FlatCodesDistanceComputer 提供了一个 distance_to_code 方法

默认实现显式地使用 sa_decode 解码向量。

bytes: 输出数组，用于存储编码后的字节。

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码向量，大小为 n * sa_code_size()

x: 输出数组，用于存储解码后的向量。

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

x: 要添加的向量

默认的 add 使用 sa_encode

重置索引，删除所有向量。

从数据库中删除所有元素。

recons: 输出数组，用于存储重构的向量。

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

recons: 输出数组，用于存储重构的向量。

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

标量量化代码的大小（以字节为单位）。

生成的代码的大小（以字节为单位）

virtual size_t remove_ids(const IDSelector &sel) override

移除一些id。 注意，由于索引的结构，此操作的语义与通常的语义不同：新的id会被移动

inline virtual DistanceComputer *get_distance_computer() const override

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

CodePacker *get_CodePacker() const

virtual void check_compatible_for_merge(const Index &otherIndex) const override

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void merge_from(Index &otherIndex, idx_t add_id = 0) override

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void add_sa_codes(idx_t n, const uint8_t *x, const idx_t *xids) override

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void permute_entries(const idx_t *perm)

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

公共成员

ScalarQuantizer sq

用于编码向量。

size_t code_size

std::vector<uint8_t> codes

编码后的数据集，大小为 ntotal * code_size

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

struct IndexIVFScalarQuantizer : public faiss::IndexIVF

#include <IndexScalarQuantizer.h>

一个 IVF 实现，其中残差的分量使用标量量化器进行编码。所有距离计算都是非对称的，因此编码后的向量会被解码，并计算近似距离。

公共类型

using component_t = float

using distance_t = float

公共函数

IndexIVFScalarQuantizer(Index *量化器, size_t d, size_t nlist, ScalarQuantizer::QuantizerType qtype, MetricType metric = METRIC_L2, bool by_residual = true)

IndexIVFScalarQuantizer()

virtual void train_encoder(idx_t n, const float *x, const idx_t *assign) override

训练向量的编码器。

如果 by_residual 为 true，则会使用残差和相应的 assign 数组调用它，否则 x 是原始训练向量，assign=nullptr

virtual idx_t train_encoder_num_vectors() const override

可以被子类重新定义以指示他们需要多少训练向量

virtual void encode_vectors(idx_t n, const float *x, const idx_t *list_nos, uint8_t *codes, bool include_listnos = false) const override

将一组向量编码为它们在倒排列表中出现的形式

参数：

• list_nos – 量化器返回的倒排列表 ID（大小为 n）。 -1s 会被忽略。

• codes – 输出编码，大小为 n * code_size

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual void add_core(idx_t n, const float *x, const idx_t *xids, const idx_t *precomputed_idx, void *inverted_list_context = nullptr) override

预定义的向量分配的向量加法的实现。默认实现将代码提取交给 encode_vectors。

参数：

precomputed_idx – 输入向量的量化索引（大小为n）

virtual InvertedListScanner *get_InvertedListScanner(bool store_pairs, const IDSelector *sel) const override

获取此索引的扫描器（store_pairs 意味着忽略标签）

默认搜索实现使用它来计算距离

virtual void reconstruct_from_offset(int64_t list_no, int64_t offset, float *recons) const override

Reconstruct a vector given the location in terms of (inv list index + inv list offset) instead of the id.

当不维护 direct_map 并且通过 search_preassigned() 计算 inv list 偏移量且设置了 store_pairs 时，此方法对于重建非常有用。

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const override

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

重置索引。

从数据库中删除所有元素。

训练索引。

训练量化器并调用 train_encoder 来训练子量化器。

向索引中添加向量。

使用 NULL id 调用 add_with_ids。

向索引中添加向量，并指定其ID。

调用 encode_vectors 的默认实现

添加预先计算的编码和ID到索引中。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

执行预分配的搜索。 即，假定分配已经完成，并且距离已计算到粗糙的质心。

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

执行预分配的范围搜索。 即，假定分配已经完成，并且距离已计算到粗糙的质心。

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

分配向量，然后调用 search_preassign

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reconstruct(idx_t key, float *recons) const override

重建一个向量。仅当 maintain_direct_map 设置为 1 或 2 时有效

virtual void update_vectors(int nv, const idx_t *idx, const float *v)

更新向量的子集。

索引必须具有 direct_map

参数：

• nv – 要更新的向量数量

• idx – 要更新的向量索引，大小为 nv

• v – 新值的向量，大小为 nv*d

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const override

Reconstruct a subset of the indexed vectors.

覆盖默认实现以绕过 reconstruct()，它需要维护 direct_map。

参数：

• i0 – first vector to reconstruct

• ni – nb of vectors to reconstruct

• recons – 重构向量的输出数组，大小为 ni * d

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

重写默认实现，以避免维护 direct_map，而是通过 search_preassigned() 中的 store_pairs 标志获取代码偏移量。

参数：

recons – 重建的向量大小 (n, k, d)

void search_and_return_codes(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, uint8_t *recons, bool include_listno = false, const SearchParameters *params = nullptr) const

类似于搜索，但也返回与搜索结果的存储向量相对应的代码。

参数：

• codes – 代码 (n, k, code_size)

• include_listno – 将列表 ID 包含在代码中（在这种情况下，将 ceil(log8(nlist)) 添加到代码大小）

virtual size_t remove_ids(const IDSelector &sel) override

Dataset manipulation functions.

检查与合并的兼容性。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

从另一个索引合并数据。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

获取 CodePacker 对象。

将一个子集复制到另一个 IndexIVF。

将索引条目的一个子集复制到另一个索引，有关 subset_type 的含义，请参见 Invlists::copy_subset_to

获取列表的大小。

检查 ID 是否已排序。

ID 是否已排序？

创建直接映射。

初始化一个直接映射

参数：

new_maintain_direct_map – 如果为true，则创建直接映射，否则清除它

设置直接映射类型。

替换倒排列表。

替换倒排列表，如果 own_invlists 为真，则旧的倒排列表会被释放。

返回标量量化编码的大小。

生成的代码的大小（以字节为单位）

虚拟 void sa_encode(idx_t n, const float *x, uint8_t *bytes) const override

编码一组向量，sa_encode 将调用 encode_vector，并将 include_listno=true。

参数：

• n – 要编码的向量数

• x – 要编码的向量。

• bytes – 用于存储编码的输出数组。

返回值：

写入编码的字节数。

虚拟 void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

虚拟 void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ScalarQuantizer sq

InvertedLists *invlists = nullptr

访问实际数据。

bool own_invlists = false

size_t code_size = 0

每个向量的代码大小，以字节为单位

int parallel_mode = 0

并行模式决定了如何使用OpenMP并行化查询

0 (默认): 在查询上分割 1: 在倒排列表上并行化 2: 在两者上并行化 3: 以更细的粒度在查询上分割

PARALLEL_MODE_NO_HEAP_INIT: 二进制或与之前的值进行或运算，以防止堆被初始化和最终化

const int PARALLEL_MODE_NO_HEAP_INIT = 1024

DirectMap direct_map

可选的映射，将ID映射回倒排列表条目。 这使得 reconstruct() 成为可能

bool by_residual = true

invlist中的代码是否编码了相对于质心的向量？

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

template<typename IndexT>
struct IndexShardsTemplate : public faiss::ThreadedIndex<IndexT>

#include <IndexShards.h>

Index 将来自多个子索引的结果连接起来

由 faiss::IndexShardsIVF 子类化

公共类型

using component_t = typename IndexT::component_t

using distance_t = typename IndexT::distance_t

公共函数

explicit IndexShardsTemplate(bool threaded = false, bool successive_ids = true)

所有子索引必须共享的维度将是添加的第一个子索引的维度

参数：

• threaded – 我们是为每个子索引使用一个线程，还是顺序查询？

• successive_ids – 我们应该按每个子索引的大小偏移返回的 ID，还是按原样返回它们？

explicit IndexShardsTemplate(idx_t d, bool threaded = false, bool successive_ids = true)

参数：

• threaded – 我们是为每个子索引使用一个线程，还是顺序查询？

• successive_ids – 我们应该按每个子索引的大小偏移返回的 ID，还是按原样返回它们？

explicit IndexShardsTemplate(int d, bool threaded = false, bool successive_ids = true)

int 版本是由于 int 作为维度的隐式 bool 转换歧义

inline void add_shard(IndexT *index)

addIndex() 的别名

inline void remove_shard(IndexT *index)

removeIndex() 的别名

void add(idx_t n, const component_t *x) override

仅对实现 add_with_ids 的子索引支持

void add_with_ids(idx_t n, const component_t *x, const idx_t *xids) override

情况 (successive_ids, xids)

• true, non-NULL 错误：传入 ID 并请求对其进行偏移是没有意义的

• true, NULL OK：但应仅调用一次（在子索引上调用 add()）。

• false, non-NULL OK：将调用 add_with_ids，传入的 xids 均匀分布在分片上

• false, NULL OK：将从 ntotal 开始，在每个子索引上调用 add_with_ids

void search(idx_t n, const component_t *x, idx_t k, distance_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

void train(idx_t n, const component_t *x) override

virtual void syncWithSubIndexes()

将顶层索引 (IndexShards) 与子索引中的数据同步。

virtual void addIndex(IndexT *index)

覆盖我们自己管理的索引。警告：一旦添加了索引，在关闭之前，从管理它的线程之外的任何其他线程触摸它都是不安全的。 使用 runOnIndex 在其上执行工作。

void removeIndex(IndexT *index)

删除我们自己管理的索引。 这将刷新该索引上的所有待处理工作，然后关闭其管理线程，并删除索引。

void runOnIndex(std::function<void(int, IndexT*)> f)

在索引的管理线程中，在所有索引上运行一个函数。 函数参数是（集合中的索引，索引指针）

void runOnIndex(std::function<void(int, const IndexT*)> f) const

void reset() override

faiss::Index API。 所有索引都收到相同的调用

inline int count() const

返回子索引的数量。

inline IndexT *at(size_t i)

返回第 i 个子索引。

inline const IndexT *at(size_t i) const

返回第 i 个子索引（const 版本）

公共成员

bool successive_ids

bool own_indices = false

我们是否负责删除包含的索引。

受保护的函数

virtual void onAfterAddIndex(IndexT *index) override

在添加索引后立即调用。

virtual void onAfterRemoveIndex(IndexT *index) override

在索引被移除后立即调用。

受保护的属性

std::vector<std::pair<IndexT*, std::unique_ptr<WorkerThread>>> indices_

Index 实例的集合，以及管理它们的工作线程（如果有）。

bool isThreaded_

这个索引是多线程的吗？

受保护的静态函数

static void waitAndHandleFutures(std::vector<std::future<bool>> &v)

struct IndexShardsIVF : public faiss::IndexShardsTemplate<Index>, public faiss::Level1Quantizer

#include <IndexShardsIVF.h>

具有通用粗量化器的 IndexShards。 所有添加的索引都应该是 IndexIVFInterface 索引，以便可以调用 search_precomputed。

公共类型

using component_t = typename IndexT::component_t

using distance_t = typename IndexT::distance_t

公共函数

显式 IndexShardsIVF(Index *量化器, size_t nlist, bool threaded = false, bool successive_ids = true)

void addIndex(Index *index) override

void add_with_ids(idx_t n, const component_t *x, const idx_t *xids) override

void train(idx_t n, const component_t *x) override

void search(idx_t n, const component_t *x, idx_t k, distance_t *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

inline void add_shard(IndexT *index)

addIndex() 的别名

inline void remove_shard(IndexT *index)

removeIndex() 的别名

void add(idx_t n, const component_t *x) override

仅对实现 add_with_ids 的子索引支持

同步子索引

将顶层索引 (IndexShards) 与子索引中的数据同步。

添加索引

覆盖我们自己管理的索引。警告：一旦添加了索引，在关闭之前，从管理它的线程之外的任何其他线程触摸它都是不安全的。 使用 runOnIndex 在其上执行工作。

移除索引

删除我们自己管理的索引。 这将刷新该索引上的所有待处理工作，然后关闭其管理线程，并删除索引。

在索引上运行，参数是一个函数，该函数接受一个整数和一个IndexT指针。

在索引的管理线程中，在所有索引上运行一个函数。 函数参数是（集合中的索引，索引指针）

在索引上运行 (const 版本)，参数是一个函数，该函数接受一个整数和一个const IndexT指针。

重置

faiss::Index API。 所有索引都收到相同的调用

inline int count() const

返回子索引的数量。

inline IndexT *at(size_t i)

返回第 i 个子索引。

inline const IndexT *at(size_t i) const

返回第 i 个子索引（const 版本）

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

bool successive_ids

bool own_indices = false

我们是否负责删除包含的索引。

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

受保护的函数

virtual void onAfterAddIndex(IndexT *index) override

在添加索引后立即调用。

virtual void onAfterRemoveIndex(IndexT *index) override

在索引被移除后立即调用。

受保护的属性

std::vector<std::pair<IndexT*, std::unique_ptr<WorkerThread>>> indices_

Index 实例的集合，以及管理它们的工作线程（如果有）。

bool isThreaded_

这个索引是多线程的吗？

受保护的静态函数

static void waitAndHandleFutures(std::vector<std::future<bool>> &v)

struct BlockInvertedLists : public faiss::InvertedLists

#include <BlockInvertedLists.h>

按块组织的倒排列表。

与常规倒排列表不同，代码按大小为 block_size 字节的块组织，这些块表示一组 n_per_block。因此，代码分配总是向上舍入到 block_size 字节。这些代码也对齐在 32 字节边界上，以便与 SIMD 一起使用。

为避免误解，代码大小设置为 (size_t)(-1)，即使代码消耗的内存量可能是 block_size / n_per_block。

写入函数 add_entries 和 update_entries 对块对齐的数据进行操作。

公共类型

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

enumerator SUBSET_TYPE_INVLIST

公共函数

BlockInvertedLists(size_t nlist, size_t vec_per_block, size_t block_size)

BlockInvertedLists(size_t nlist, const CodePacker *packer)

BlockInvertedLists()

virtual size_t list_size(size_t list_no) const override

获取列表的大小

virtual const uint8_t *get_codes(size_t list_no) const override

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t *get_ids(size_t list_no) const override

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

size_t remove_ids(const IDSelector &sel)

从 InvertedLists 中移除 IDs

virtual size_t add_entries(size_t list_no, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) override

未实现

virtual void resize(size_t list_no, size_t new_size) override

~BlockInvertedLists() override

virtual void release_codes(size_t list_no, const uint8_t *codes) const

释放 get_codes 返回的代码（默认实现是空操作）

virtual void release_ids(size_t list_no, const idx_t *ids) const

释放 get_ids 返回的 IDs

virtual idx_t get_single_id(size_t list_no, size_t offset) const

返回值：

倒排列表中的单个 ID

virtual const uint8_t *get_single_code(size_t list_no, size_t offset) const

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

virtual void prefetch_lists(const idx_t *list_nos, int nlist) const

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

virtual bool is_empty(size_t list_no, void *inverted_list_context = nullptr) const

检查列表是否为空。

virtual InvertedListsIterator *get_iterator(size_t list_no, void *inverted_list_context = nullptr) const

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

virtual void update_entry(size_t list_no, size_t offset, idx_t id, const uint8_t *code)

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

size_t n_per_block = 0

size_t block_size = 0

const CodePacker *packer = nullptr

std::vector<AlignedTable<uint8_t>> codes

std::vector<std::vector<idx_t>> ids

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct BlockInvertedListsIOHook : public faiss::InvertedListsIOHook

公共函数

BlockInvertedListsIOHook()

virtual void write(const InvertedLists *ils, IOWriter *f) const override

将索引写入 IOWriter（包括 fourcc）

virtual InvertedLists *read(IOReader *f, int io_flags) const override

当 fourcc 与此类的 fourcc 匹配时调用

virtual InvertedLists *read_ArrayInvertedLists(IOReader *f, int io_flags, size_t nlist, size_t code_size, const std::vector<size_t> &sizes) const

从 ArrayInvertedLists 读取到此倒排列表类型中。 为使其工作，必须启用回调，并且 io_flag 必须设置为 IO_FLAG_SKIP_IVF_DATA | （fourcc 的 16 个高位）

(默认实现失败)

公共成员

const std::string key

fourcc 的字符串版本

const std::string classname

typeid.name

公共静态函数

static void add_callback(InvertedListsIOHook*)

static void print_callbacks()

static InvertedListsIOHook *lookup(int h)

static InvertedListsIOHook *lookup_classname(const std::string &classname)

struct DirectMap

#include <DirectMap.h>

Direct map: a way to map back from ids to inverted lists

公共类型

enum Type

值

enumerator NoMap

enumerator Array

enumerator Hashtable

公共函数

DirectMap()

void set_type(Type new_type, const InvertedLists *invlists, size_t ntotal)

set type and initialize

idx_t get(idx_t id) const

get an entry

inline bool no() const

for quick checks

void check_can_add(const idx_t *ids)

throw if Array and ids is not NULL

update the direct_map

void add_single_id(idx_t id, idx_t list_no, size_t offset)

non thread-safe version

void clear()

remove all entries

size_t remove_ids(const IDSelector &sel, InvertedLists *invlists)

remove ids from the InvertedLists, possibly using the direct map

operations on inverted lists that require translation with a DirectMap

void update_codes(InvertedLists *invlists, int n, const idx_t *ids, const idx_t *list_nos, const uint8_t *codes)

update entries, using the direct map

公共成员

Type type

std::vector<idx_t> array

map for direct access to the elements. Map ids to LO-encoded entries.

std::unordered_map<idx_t, idx_t> hashtable

struct DirectMapAdd

#include <DirectMap.h>

Thread-safe way of updating the direct_map.

公共类型

using Type = DirectMap::Type

公共函数

DirectMapAdd(DirectMap &direct_map, size_t n, const idx_t *xids)

void add(size_t i, idx_t list_no, size_t offset)

在 list_no 和 offset 位置添加向量 i (带有 id xids[i])

~DirectMapAdd()

公共成员

DirectMap &direct_map

DirectMap::Type type

size_t ntotal

size_t n

const idx_t *xids

std::vector<idx_t> all_ofs

struct InvertedListsIterator

公共函数

virtual ~InvertedListsIterator()

virtual bool is_available() const = 0

virtual void next() = 0

virtual std::pair<idx_t, const uint8_t*> get_id_and_codes() = 0

struct InvertedLists

#include <InvertedLists.h>

倒排列表多线程规则

• 允许并发读取访问

• 允许并发更新访问

• 对于调整大小和 add_entries，只允许并发访问不同的列表

由 faiss::ArrayInvertedLists, faiss::BlockInvertedLists, faiss::OnDiskInvertedLists, faiss::ReadOnlyInvertedLists 继承

公共类型

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

enumerator SUBSET_TYPE_INVLIST

公共函数

InvertedLists(size_t nlist, size_t code_size)

virtual ~InvertedLists()

virtual size_t list_size(size_t list_no) const = 0

获取列表的大小

virtual const uint8_t *get_codes(size_t list_no) const = 0

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

获取指定列表的 IDs。

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

释放指定列表的编码。

释放 get_codes 返回的代码（默认实现是空操作）

释放指定列表的 IDs。

释放 get_ids 返回的 IDs

获取指定列表中指定偏移量的单个 ID。

返回值：

倒排列表中的单个 ID

获取指定列表中指定偏移量的单个编码。

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

预取指定的列表。

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

检查指定的列表是否为空。

检查列表是否为空。

获取指定列表的迭代器。

获取 use_iterator 的列表的可迭代对象。

向指定列表添加一个条目。

向倒排列表添加一个条目。

向指定列表添加多个条目。

更新指定列表中指定偏移量的条目。

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) = 0

virtual void resize(size_t list_no, size_t new_size) = 0

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct ScopedCodes

公共函数

inline ScopedCodes(const InvertedLists *il, size_t list_no)

inline ScopedCodes(const InvertedLists *il, size_t list_no, size_t offset)

inline const uint8_t *get()

inline ~ScopedCodes()

公共成员

const InvertedLists *il

指向 uint8_t 类型的常量指针，名称为 `codes`。

类型为 `size_t` 的变量，名称为 `list_no`。

名为 `ScopedIds` 的结构体。

公共函数

内联构造函数 `ScopedIds`，接受一个指向 `InvertedLists` 对象的常量指针 `il` 和一个 `size_t` 类型的参数 `list_no`。

内联函数 `get`，返回一个指向常量 `idx_t` 类型的指针。

内联常量成员函数 `operator[]`，接受一个 `size_t` 类型的参数 `i` 并返回一个 `idx_t` 类型的值。

内联析构函数 `~ScopedIds`。

公共成员

指向常量 `InvertedLists` 类型的指针，名称为 `il`。

指向常量 `idx_t` 类型的指针，名称为 `ids`。

类型为 `size_t` 的变量，名称为 `list_no`。

名为 `ArrayInvertedLists` 的结构体，公有继承自 `faiss::InvertedLists`。

#include <InvertedLists.h>

作为倒排列表数组的简单（默认）实现。

公共类型

名为 `subset_type_t` 的枚举类型。

值

枚举成员 `SUBSET_TYPE_ID_RANGE`。

枚举成员 `SUBSET_TYPE_ID_MOD`。

枚举成员 `SUBSET_TYPE_ELEMENT_RANGE`。

枚举成员 `SUBSET_TYPE_INVLIST_FRACTION`。

枚举成员 `SUBSET_TYPE_INVLIST`。

公共函数

构造函数 `ArrayInvertedLists`，接受两个 `size_t` 类型的参数：`nlist` 和 `code_size`。

虚函数 `list_size`，接受一个 `size_t` 类型的参数 `list_no`，返回一个 `size_t` 类型的值，并且重写了父类的对应函数。

获取列表的大小

虚函数 `get_codes`，接受一个 `size_t` 类型的参数 `list_no`，返回一个指向常量 `uint8_t` 类型的指针，并且重写了父类的对应函数。

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

虚函数 `get_ids`，接受一个 `size_t` 类型的参数 `list_no`，返回一个指向常量 `idx_t` 类型的指针，并且重写了父类的对应函数。

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

虚函数 `add_entries`，接受一个 `size_t` 类型的参数 `list_no`、一个 `size_t` 类型的参数 `n_entry`、一个指向常量 `idx_t` 类型的指针 `ids` 和一个指向常量 `uint8_t` 类型的指针 `code`，返回一个 `size_t` 类型的值，并且重写了父类的对应函数。

更新条目。

调整大小。

void permute_invlists(const idx_t *map)

置换倒排列表，map 将 new_id 映射到 old_id

是否为空。

检查列表是否为空。

析构函数。

释放码字。

释放 get_codes 返回的代码（默认实现是空操作）

释放 ID。

释放 get_ids 返回的 IDs

获取单个 ID。

返回值：

倒排列表中的单个 ID

获取单个码字。

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

预取列表。

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

获取迭代器。

获取 use_iterator 的列表的可迭代对象。

添加条目。

向倒排列表添加一个条目。

更新条目。

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

std::vector<std::vector<uint8_t>> codes

std::vector<std::vector<idx_t>> ids

为索引准备的反向列表。

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct ReadOnlyInvertedLists : public faiss::InvertedLists

#include <InvertedLists.h>

invlists 对于所有写入函数都会失败

由 faiss::HStackInvertedLists、faiss::MaskedInvertedLists、faiss::SliceInvertedLists、faiss::StopWordsInvertedLists、faiss::VStackInvertedLists 继承

公共类型

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

enumerator SUBSET_TYPE_INVLIST

公共函数

inline ReadOnlyInvertedLists(size_t nlist, size_t code_size)

virtual size_t add_entries(size_t list_no, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void resize(size_t list_no, size_t new_size) override

virtual size_t list_size(size_t list_no) const = 0

获取列表的大小

virtual const uint8_t *get_codes(size_t list_no) const = 0

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t *get_ids(size_t list_no) const = 0

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

virtual void release_codes(size_t list_no, const uint8_t *codes) const

释放 get_codes 返回的代码（默认实现是空操作）

virtual void release_ids(size_t list_no, const idx_t *ids) const

释放 get_ids 返回的 IDs

virtual idx_t get_single_id(size_t list_no, size_t offset) const

返回值：

倒排列表中的单个 ID

virtual const uint8_t *get_single_code(size_t list_no, size_t offset) const

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

virtual void prefetch_lists(const idx_t *list_nos, int nlist) const

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

virtual bool is_empty(size_t list_no, void *inverted_list_context = nullptr) const

检查列表是否为空。

virtual InvertedListsIterator *get_iterator(size_t list_no, void *inverted_list_context = nullptr) const

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

virtual void update_entry(size_t list_no, size_t offset, idx_t id, const uint8_t *code)

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct HStackInvertedLists : public faiss::ReadOnlyInvertedLists

#include <InvertedLists.h>

倒排列表的水平堆叠。

公共类型

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

枚举器 SUBSET_TYPE_INVLIST

公共函数

HStackInvertedLists(int nil, const InvertedLists **ils)

通过连接 nil 个 InvertedLists 来构建。

virtual size_t list_size(size_t list_no) const override

获取列表的大小

virtual const uint8_t *get_codes(size_t list_no) const override

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t *get_ids(size_t list_no) const override

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

virtual void prefetch_lists(const idx_t *list_nos, int nlist) const override

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

virtual void release_codes(size_t list_no, const uint8_t *codes) const override

释放 get_codes 返回的代码（默认实现是空操作）

virtual void release_ids(size_t list_no, const idx_t *ids) const override

释放 get_ids 返回的 IDs

virtual idx_t get_single_id(size_t list_no, size_t offset) const override

返回值：

倒排列表中的单个 ID

virtual const uint8_t *get_single_code(size_t list_no, size_t offset) const override

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

virtual size_t add_entries(size_t list_no, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void resize(size_t list_no, size_t new_size) override

virtual bool is_empty(size_t list_no, void *inverted_list_context = nullptr) const

检查列表是否为空。

virtual InvertedListsIterator* get_iterator(size_t list_no, void *inverted_list_context = nullptr) const

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

virtual void update_entry(size_t list_no, size_t offset, idx_t id, const uint8_t *code)

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

std::vector<const InvertedLists*> ils

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct SliceInvertedLists : public faiss::ReadOnlyInvertedLists

#include <InvertedLists.h>

另一个 InvertedLists 中索引的垂直切片

公共类型

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

枚举器 SUBSET_TYPE_INVLIST

公共函数

SliceInvertedLists(const InvertedLists *il, idx_t i0, idx_t i1)

virtual size_t list_size(size_t list_no) const override

获取列表的大小

virtual const uint8_t *get_codes(size_t list_no) const override

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t *get_ids(size_t list_no) const override

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

virtual void release_codes(size_t list_no, const uint8_t *codes) const override

释放 get_codes 返回的代码（默认实现是空操作）

virtual void release_ids(size_t list_no, const idx_t *ids) const override

释放 get_ids 返回的 IDs

virtual idx_t get_single_id(size_t list_no, size_t offset) const override

返回值：

倒排列表中的单个 ID

virtual const uint8_t *get_single_code(size_t list_no, size_t offset) const override

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

virtual void prefetch_lists(const idx_t *list_nos, int nlist) const override

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

virtual size_t add_entries(size_t list_no, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void resize(size_t list_no, size_t new_size) override

virtual bool is_empty(size_t list_no, void *inverted_list_context = nullptr) const

检查列表是否为空。

virtual InvertedListsIterator *get_iterator(size_t list_no, void *inverted_list_context = nullptr) const

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

virtual void update_entry(size_t list_no, size_t offset, idx_t id, const uint8_t *code)

virtual void reset()

将`oivf`中的倒排列表合并到当前倒排列表，并加上偏移量 `add_id`。

从 oivf 移动所有条目（输出时为空）。

将倒排列表的一个子集复制到另一个倒排列表 `other` 中。`subset_type` 指定子集的类型，`a1` 和 `a2` 指定子集的范围或模式。

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

计算倒排列表的不平衡因子。这是列表中最大尺寸与平均尺寸的比率。

1= 完全平衡，>1：不平衡。

打印倒排列表的统计信息，例如列表数、总条目数和不平衡因子。

显示关于倒排列表的一些统计信息。

计算倒排列表中存储的总条目数。

汇总列表大小。

公共成员

指向底层 `InvertedLists` 对象的指针。

切片的起始索引。

切片的结束索引。

列表的数量。

number of possible key values

每个向量的代码大小（以字节为单位）。

每个向量的代码大小，以字节为单位

是否使用迭代器访问列表（默认值为 `false`）。

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

一个静态常量，表示无效的代码大小。

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

`VStackInvertedLists` 结构体，继承自 `ReadOnlyInvertedLists`。用于垂直堆叠多个倒排列表。

公共类型

定义子集类型的枚举。

值

按 ID 范围选择子集。

按 ID 模数选择子集。

按元素范围选择子集。

按倒排列表的比例选择子集。

按倒排列表选择子集。

公共函数

`VStackInvertedLists` 的构造函数。`nil` 是列表的数量，`ils` 是指向 `InvertedLists` 对象的指针数组。

通过连接 nil 个 InvertedLists 来构建。

返回指定列表 `list_no` 的大小。

获取列表的大小

返回指定列表 `list_no` 的代码。

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

返回指定列表 `list_no` 的 ID。

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

释放与倒排列表中一个条目相关联的代码。

释放 get_codes 返回的代码（默认实现是空操作）

释放与倒排列表中一个条目相关联的ID。

释放 get_ids 返回的 IDs

获取倒排列表中给定偏移量的单个ID。

返回值：

倒排列表中的单个 ID

获取倒排列表中给定偏移量的单个代码。

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

预取倒排列表到缓存中。

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

将多个条目添加到倒排列表中。

更新倒排列表中的多个条目。

调整倒排列表的大小。

检查倒排列表是否为空。

检查列表是否为空。

获取倒排列表的迭代器。

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

virtual void update_entry(size_t list_no, size_t offset, idx_t id, const uint8_t *code)

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

std::vector<const InvertedLists*> ils

std::vector<idx_t> cumsz

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

使用迭代器 = 假

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

无效代码大小 = (size_t)(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

结构体 MaskedInvertedLists : 公有ReadOnlyInvertedLists

#include <InvertedLists.h>

如果第一个倒排列表非空，则使用第一个倒排列表，否则使用第二个倒排列表。

如果 il1 有一些倒排列表太长，而 il0 具有那些的替换列表，而其他列表为空，则这非常有用。

公共类型

枚举 subset_type_t

值

枚举器 SUBSET_TYPE_ID_RANGE

枚举器 SUBSET_TYPE_ID_MOD

枚举器 SUBSET_TYPE_ELEMENT_RANGE

枚举器 SUBSET_TYPE_INVLIST_FRACTION

枚举器 SUBSET_TYPE_INVLIST

公共函数

MaskedInvertedLists(const InvertedLists *il0, const InvertedLists *il1)

virtual size_t 列表大小(size_t 列表编号) const 重载

获取列表的大小

virtual const uint8_t * 获取代码(size_t 列表编号) const 重载

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t * 获取ID(size_t 列表编号) const 重载

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

virtual void 释放代码(size_t 列表编号, const uint8_t * 代码) const 重载

释放 get_codes 返回的代码（默认实现是空操作）

virtual void 释放ID(size_t 列表编号, const idx_t * ID) const 重载

释放 get_ids 返回的 IDs

virtual idx_t 获取单个ID(size_t 列表编号, size_t 偏移量) const 重载

返回值：

倒排列表中的单个 ID

virtual const uint8_t * 获取单个代码(size_t 列表编号, size_t 偏移量) const 重载

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

nlist: 要预取的列表的数量。

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

实际添加的条目数量。

code: 用于更新的代码的数组。

new_size: 列表的新大小。

如果列表为空，则返回 `true`，否则返回 `false`。

检查列表是否为空。

指向新创建的 `InvertedListsIterator` 的指针。

获取 use_iterator 的列表的可迭代对象。

添加后的列表大小。

向倒排列表添加一个条目。

code: 用于更新的代码。

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

const InvertedLists *il0

const InvertedLists *il1

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct StopWordsInvertedLists : public faiss::ReadOnlyInvertedLists

#include <InvertedLists.h>

如果 il 中的倒排列表小于 maxsize，则返回它，否则返回一个空的倒排列表

公共类型

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

enumerator SUBSET_TYPE_INVLIST

公共函数

StopWordsInvertedLists(const InvertedLists *il, size_t maxsize)

virtual size_t list_size(size_t list_no) const override

获取列表的大小

virtual const uint8_t * get_codes(size_t list_no) const override

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t * get_ids(size_t list_no) const override

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

virtual void release_codes(size_t list_no, const uint8_t * codes) const override

释放 get_codes 返回的代码（默认实现是空操作）

virtual void release_ids(size_t list_no, const idx_t * ids) const override

释放 get_ids 返回的 IDs

virtual idx_t get_single_id(size_t list_no, size_t offset) const override

返回值：

倒排列表中的单个 ID

virtual const uint8_t * get_single_code(size_t list_no, size_t offset) const override

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

virtual void prefetch_lists(const idx_t * list_nos, int nlist) const override

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

virtual size_t add_entries(size_t list_no, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void resize(size_t list_no, size_t new_size) override

virtual bool is_empty(size_t list_no, void *inverted_list_context = nullptr) const

检查列表是否为空。

virtual InvertedListsIterator *get_iterator(size_t list_no, void *inverted_list_context = nullptr) const

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

virtual void update_entry(size_t list_no, size_t offset, idx_t id, const uint8_t *code)

virtual void reset()

void merge_from(InvertedLists *oivf, size_t add_id)

从 oivf 移动所有条目（输出时为空）。

size_t copy_subset_to(InvertedLists &other, subset_type_t subset_type, idx_t a1, idx_t a2) const

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

double imbalance_factor() const

1= 完全平衡，>1：不平衡。

void print_stats() const

显示关于倒排列表的一些统计信息。

size_t compute_ntotal() const

汇总列表大小。

公共成员

const InvertedLists *il0

size_t maxsize

size_t nlist

number of possible key values

size_t code_size

每个向量的代码大小，以字节为单位

bool use_iterator = false

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

static const size_t INVALID_CODE_SIZE = static_cast<size_t>(-1)

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

struct InvertedListsIOHook

#include <InvertedListsIOHook.h>

用于处理其他类型倒排列表对象的的回调。

在调用 read_index 或 read_InvertedLists 之前，应该使用 add_callback 注册回调函数。 默认情况下，会注册 OnDiskInvertedLists 的回调函数。 invlist 类型通过以下方式识别：

• 读取时的 key (fourcc)

• 写入时的类名 (由 typeid.name 给出)

被 faiss::BlockInvertedListsIOHook, faiss::OnDiskInvertedListsIOHook 继承

公共函数

InvertedListsIOHook(const std::string &key, const std::string &classname)

virtual void write(const InvertedLists *ils, IOWriter *f) const = 0

将索引写入 IOWriter（包括 fourcc）

virtual InvertedLists *read(IOReader *f, int io_flags) const = 0

当 fourcc 与此类的 fourcc 匹配时调用

virtual InvertedLists *read_ArrayInvertedLists(IOReader *f, int io_flags, size_t nlist, size_t code_size, const std::vector<size_t> &sizes) const

从 ArrayInvertedLists 读取到此倒排列表类型中。 为使其工作，必须启用回调，并且 io_flag 必须设置为 IO_FLAG_SKIP_IVF_DATA | （fourcc 的 16 个高位）

(默认实现失败)

inline virtual ~InvertedListsIOHook()

公共成员

const std::string key

fourcc 的字符串版本

const std::string classname

typeid.name

公共静态函数

static void add_callback(InvertedListsIOHook*)

static void print_callbacks()

static InvertedListsIOHook *lookup(int h)

static InvertedListsIOHook *lookup_classname(const std::string &classname)

struct OnDiskOneList

公共函数

OnDiskOneList()

公共成员

size_t size

size_t capacity

size_t offset

struct OnDiskInvertedLists : public faiss::InvertedLists

#include <OnDiskInvertedLists.h>

倒排列表的磁盘存储。

数据存储在内存映射的块中（基址指针 ptr，大小 totsize）。每个列表都是一块内存范围，其中包含 (object List)，该 (object List) 包含

• uint8_t codes[capacity * code_size]

• 紧随其后的是 idx_t ids[capacity]

在每个数组中，使用大小 <= capacity 的前几个元素，其余未初始化。

通过以下方式支持添加和调整大小：

• 将列表的容量向上取整为 2 的幂

• 维护一个空闲槽列表，按大小排序。

• 根据需要调整内存映射块的大小。

如果所有列表的大小 == 容量，并且没有可用的空闲槽，则 OnDiskInvertedLists 是紧凑的。

向 invlists 添加内容的速度很慢。对于增量添加，最好使用默认的 ArrayInvertedLists 对象，并使用 merge_from 将其转换为 OnDisk。

当已知将要访问一组列表时，调用 prefetch_lists 非常有用，它会启动一组线程并行读取列表。

公共类型

using List = OnDiskOneList

enum subset_type_t

值

enumerator SUBSET_TYPE_ID_RANGE

enumerator SUBSET_TYPE_ID_MOD

enumerator SUBSET_TYPE_ELEMENT_RANGE

enumerator SUBSET_TYPE_INVLIST_FRACTION

enumerator SUBSET_TYPE_INVLIST

公共函数

OnDiskInvertedLists(size_t nlist, size_t code_size, const char *filename)

是映射为只读的倒排列表

virtual size_t list_size(size_t list_no) const override

获取列表的大小

virtual const uint8_t *get_codes(size_t list_no) const override

获取倒排列表的代码，必须通过 release_codes 释放

返回值：

代码大小：list_size * code_size

virtual const idx_t *get_ids(size_t list_no) const override

获取倒排列表的 IDs，必须通过 release_ids 释放

返回值：

IDs 大小：list_size

virtual size_t add_entries(size_t list_no, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void update_entries(size_t list_no, size_t offset, size_t n_entry, const idx_t *ids, const uint8_t *code) override

virtual void resize(size_t list_no, size_t new_size) override

size_t merge_from_multiple(const InvertedLists **ils, int n_il, bool shift_ids = false, bool verbose = false)

size_t merge_from_1(const InvertedLists *il, bool verbose = false)

与用于单个倒排列表的 merge_from 相同

void crop_invlists(size_t l0, size_t l1)

将倒排列表限制为 l0:l1，而不触及内存映射区域

virtual void prefetch_lists(const idx_t *list_nos, int nlist) const override

准备以下列表（默认不执行任何操作）一个列表可以是 -1，因此是有符号的长整型

~OnDiskInvertedLists() override

void do_mmap()

void update_totsize(size_t new_totsize)

void resize_locked(size_t list_no, size_t new_size)

size_t allocate_slot(size_t capacity)

void free_slot(size_t offset, size_t capacity)

void set_all_lists_sizes(const size_t *sizes)

覆盖所有列表大小并创建一个打包存储

OnDiskInvertedLists()

virtual void release_codes(size_t list_no, const uint8_t *codes) const

释放 get_codes 返回的代码（默认实现是空操作）

virtual void release_ids(size_t list_no, const idx_t *ids) const

释放 get_ids 返回的 IDs

virtual idx_t get_single_id(size_t list_no, size_t offset) const

返回值：

倒排列表中的单个 ID

virtual const uint8_t *get_single_code(size_t list_no, size_t offset) const

返回值：

倒排列表中的单个代码（应使用 release_codes 释放）

virtual bool is_empty(size_t list_no, void *inverted_list_context = nullptr) const

检查列表是否为空。

virtual InvertedListsIterator *get_iterator(size_t list_no, void *inverted_list_context = nullptr) const

获取 use_iterator 的列表的可迭代对象。

virtual size_t add_entry(size_t list_no, idx_t theid, const uint8_t *code, void *inverted_list_context = nullptr)

向倒排列表添加一个条目。

更新条目。

重置。

从另一个倒排列表合并。

从 oivf 移动所有条目（输出时为空）。

将子集复制到另一个倒排列表。

将条目索引的子集复制到其他索引。

返回值：

复制的条目数。

计算不平衡因子。

1= 完全平衡，>1：不平衡。

打印统计信息。

显示关于倒排列表的一些统计信息。

计算总数。

汇总列表大小。

公共成员

列表的向量。

槽位的列表。

文件名。

总大小。

指针。

只读。

锁。

正在进行的预取。

预取的线程数。

列表的数量。

number of possible key values

代码大小。

每个向量的代码大小，以字节为单位

是否使用迭代器。

请求使用迭代器，而不是 get_codes / get_ids

公共静态属性

INVALID_CODE_SIZE 是一个静态常量 `size_t` 类型的成员，其值被设置为 `static_cast<size_t>(-1)`。 它很可能表示无效或未定义的代码大小值。

用于 BlockInvertedLists，其中代码被打包成组，并且单独的代码大小没有意义

`Slot` 是一个结构体，用于表示磁盘上倒排列表中的一个槽位。

公共函数

`Slot(size_t offset, size_t capacity)`: `Slot` 结构体的构造函数，接受槽位的 `offset` 和 `capacity` 作为参数。

`Slot()`: `Slot` 结构体的默认构造函数。

公共成员

`offset`: `Slot` 结构体的成员变量，表示槽位在磁盘上的偏移量。

`capacity`: `Slot` 结构体的成员变量，表示槽位的容量大小。

`OnDiskInvertedListsIOHook`: 一个结构体，继承自 `faiss::InvertedListsIOHook`，用于处理磁盘上倒排列表的 I/O 操作。

公共函数

`OnDiskInvertedListsIOHook()`: `OnDiskInvertedListsIOHook` 结构体的构造函数。

`write(const InvertedLists *ils, IOWriter *f) const override`: 虚函数，用于将倒排列表 `ils` 写入到 `IOWriter` 对象 `f` 中。

将索引写入 IOWriter（包括 fourcc）

`read(IOReader *f, int io_flags) const override`: 虚函数，用于从 `IOReader` 对象 `f` 中读取倒排列表，并返回一个指向新创建的 `InvertedLists` 对象的指针。 `io_flags` 用于传递 I/O 标志。

当 fourcc 与此类的 fourcc 匹配时调用

`read_ArrayInvertedLists(IOReader *f, int io_flags, size_t nlist, size_t code_size, const std::vector<size_t> &sizes) const override`: 虚函数，用于从 `IOReader` 对象 `f` 中读取一个数组形式的倒排列表。 `io_flags` 用于传递 I/O 标志, `nlist` 是列表数量，`code_size` 是代码大小, `sizes` 是一个包含每列大小的向量。

从 ArrayInvertedLists 读取到此倒排列表类型中。 为使其工作，必须启用回调，并且 io_flag 必须设置为 IO_FLAG_SKIP_IVF_DATA | （fourcc 的 16 个高位）

(默认实现失败)

公共成员

`key`: 一个 `std::string` 类型的常量成员，可能是用于标识该 I/O hook 的键值。 用于在注册表或其他查找机制中识别此类。

fourcc 的字符串版本

`classname`: 一个 `std::string` 类型的常量成员，表示类的名称。 在序列化和反序列化上下文中很有用。

typeid.name

公共静态函数

`add_callback(InvertedListsIOHook*)`: 一个静态函数，用于添加一个 `InvertedListsIOHook` 回调。 这可能用于注册自定义 I/O hook。

`print_callbacks()`: 一个静态函数，用于打印已注册的回调列表。 主要用于调试或日志记录。

`lookup(int)`: 一个静态函数，用于基于整数句柄 `h` 查找 `InvertedListsIOHook`。 返回指向已找到的 hook 的指针，如果未找到则返回 null。

`lookup_classname(const std::string& classname)`: 一个静态函数，用于基于类名称 `classname` 查找 `InvertedListsIOHook`。 返回指向已找到的 hook 的指针，如果未找到则返回 null。

`MatrixStats`：一个结构体，用于计算和报告矩阵数据的统计信息。

包含头文件 MatrixStats.h

报告数据集的一些统计信息并进行评论。

它是一个类而不是一个函数，以便所有统计信息也可以从代码中访问。

公共函数

`MatrixStats(size_t n, size_t d, const float *x)`：`MatrixStats` 结构体的构造函数，接受数据集的行数 `n`，列数 `d` 和指向数据 `x` 的指针作为参数。

void do_comment(const char *fmt, ...)

公共成员

std::string comments

size_t n = 0

size_t d = 0

size_t n_collision = 0

size_t n_valid = 0

size_t n0 = 0

double min_norm2 = HUGE_VALF

double max_norm2 = 0

uint64_t hash_value = 0

std::vector<PerDimStats> per_dim_stats

std::unordered_map<uint64_t, Occurrence> occurrences

char *buf

size_t nbuf

struct Occurrence

公共成员

size_t first

size_t count

struct PerDimStats

公共函数

void add(float x)

void compute_mean_std()

公共成员

size_t n = 0

各种特殊条目的计数

size_t n_nan = 0

size_t n_inf = 0

size_t n0 = 0

float min = HUGE_VALF

获取最小值/最大值和标准差值

float max = -HUGE_VALF

double sum = 0

double sum2 = 0

size_t n_valid = 0

double mean = NAN

double stddev = NAN

struct IndexSplitVectors : public faiss::Index

#include <MetaIndexes.h>

将输入向量分割成段，并将每个段分配给一个子索引，用于分配 MultiIndexQuantizer

公共类型

using component_t = float

using distance_t = float

公共函数

explicit IndexSplitVectors(idx_t d, bool threaded = false)

目前看到的维度的总和

void add_sub_index(Index*)

void sync_with_sub_indexes()

virtual void add(idx_t n, const float *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

virtual void train(idx_t n, const float *x) override

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void reset() override

从数据库中删除所有元素。

~IndexSplitVectors() override

virtual void add_with_ids(idx_t n, const float *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

bool own_fields

bool threaded

std::vector<Index*> sub_indexes

idx_t sum_d

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

度量类型

此索引用于搜索的度量类型

度量参数

度量类型的参数

返回随机结果的索引。 主要用于时间基准测试

#include <MetaIndexes.h>

返回随机结果的索引。主要用于时间基准测试。

公共类型

使用 float 作为 component_t 的别名。

使用 float 作为 distance_t 的别名。

公共函数

IndexRandom 构造函数，参数包括维度 d，总数 ntotal，随机种子 seed，以及度量类型 mt，默认值为 METRIC_L2。

添加向量，n 是向量的数量，x 是指向向量数据的指针。

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1。此函数将输入向量切分成小于 blocksize_add 的块，并调用 add_core。

参数：

• n – 向量的数量

• x – 输入矩阵，大小为 n * d

搜索最相似的向量，n 是查询向量的数量，x 是指向查询向量数据的指针，k 是要返回的最近邻的数量，distances 是指向距离数组的指针，labels 是指向标签数组的指针，params 是搜索参数。

查询 n 个维度为 d 的向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

重建向量，key 是向量的 ID，recons 是指向重建向量的指针。

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

重置索引，清除所有数据。

从数据库中删除所有元素。

IndexRandom 析构函数。

训练索引，n 是训练向量的数量，x 是指向训练向量数据的指针。

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

添加带有 ID 的向量，n 是向量的数量，x 是指向向量数据的指针，xids 是指向向量 ID 的指针。

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• xids – 如果非空，则为向量存储的 ID (大小为 n)

范围搜索，n 是查询向量的数量，x 是指向查询向量数据的指针，radius 是搜索半径，result 是指向范围搜索结果的指针，params 是搜索参数。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

分配向量，n 是查询向量的数量，x 是指向查询向量数据的指针，labels 是指向分配标签的指针，k 是要分配的最近邻的数量，默认为 1。

返回最接近查询 x 的 k 个向量的索引。

此函数与搜索相同，但仅返回邻居的标签。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• labels – 输出 NN 的标签，大小为 n*k

• k – 最近邻的数量

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• k – 提取的向量数

• distances – 输出成对距离，大小为 n*k

• labels – 输出 NN 的标签，大小为 n*k

• recons – 重建的向量大小 (n, k, d)

virtual void compute_residual(const float *x, float *residual, idx_t key) const

计算索引编码后的残差向量。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• x – 输入向量，大小为 d

• residual – 输出残差向量，大小为 d

• key – 编码后的索引，由搜索和分配返回

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const

计算索引编码后的残差向量（批量形式）。 等同于为每个向量调用 compute_residual。

残差向量是向量与可以通过索引中的表示解码的重构之间的差异。残差可以用于多阶段索引方法，例如 IndexIVF 的方法。

参数：

• n – 向量的数量

• xs – 输入向量，大小 (n x d)

• residuals – 输出残差向量，大小 (n x d)

• keys – 编码后的索引，由搜索和分配返回

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加选择性激活码 (selective activation codes)。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

随机种子。

向量维度。

向量维度

索引中的向量总数。

索引向量的总数

详细模式标志。

详细级别

真如果索引已被训练。

如果 Index 不需要训练，或者如果已经完成训练，则设置

使用的距离度量类型。

此索引用于搜索的度量类型

距离度量的参数（如果有）。

度量类型的参数

模板类，用于内存对齐分配。
内存对齐分配结构体。

公共函数

构造函数。

构造函数，指定大小。

返回每个元素的大小。

调整大小。

清除分配的内存。

返回当前大小。

返回已分配的总字节数。

返回指向已分配内存的指针。

返回指向已分配内存的const指针。

返回指向已分配内存的指针 (等同于 get())。

返回指向已分配内存的const指针 (等同于 get())。

inline T &operator[](size_t i)

inline 返回类型为 T 的const成员函数 operator[] (size_t i)

inline 析构函数 ~AlignedTableTightAlloc()

inline AlignedTableTightAlloc<T, A>& operator=(const AlignedTableTightAlloc<T, A>& other)

inline AlignedTableTightAlloc(const AlignedTableTightAlloc<T, A>& other)

公共成员

T* ptr

size_t numel

template <class T, int A = 32>
struct AlignedTable

公共函数

inline AlignedTable()

inline explicit AlignedTable(size_t n)

inline size_t itemsize() const

inline void resize(size_t n)

inline void clear()

inline size_t size() const

inline size_t nbytes() const

inline T* get()

inline const T* get() const

inline T* data()

inline const T* data() const

inline T& operator[](size_t i)

inline T operator[](size_t i) const

公共成员

AlignedTableTightAlloc<T, A> tab

size_t numel = 0

公共静态函数

static inline size_t round_capacity(size_t n)

template<typename C, uint32_t NBUCKETS, uint32_t N>
struct HeapWithBuckets

template<uint32_t NBUCKETS, uint32_t N>
struct HeapWithBuckets<CMax<float, int>, NBUCKETS, N>

公共静态函数

static inline void addn (const uint32_t n, const float *const __restrict distances, const uint32_t k, float *const __restrict bh_val, int32_t *const __restrict bh_ids)

static inline void bs_addn (const uint32_t beam_size, const uint32_t n_per_beam, const float *const __restrict distances, const uint32_t k, float *const __restrict bh_val, int32_t *const __restrict bh_ids)

static inline void addn (const uint32_t n, const float *const __restrict distances, const uint32_t k, float *const __restrict bh_val, int32_t *const __restrict bh_ids)

static inline void bs_addn (const uint32_t beam_size, const uint32_t n_per_beam, const float *const __restrict distances, const uint32_t k, float *const __restrict bh_val, int32_t *const __restrict bh_ids)

公共静态属性

static constexpr uint32_t NBUCKETS_8 = NBUCKETS / 8

template<typename C, uint32_t NBUCKETS, uint32_t N, typename HammingComputerT>
struct HeapWithBucketsForHamming32

template<uint32_t NBUCKETS, uint32_t N, typename HammingComputerT>
struct HeapWithBucketsForHamming32<CMax<int, int64_t>, NBUCKETS, N, HammingComputerT>

公共静态函数

static inline void addn (const uint32_t n, const HammingComputerT &hc, const uint8_t *const __restrict binaryVectors, const uint32_t k, int *const __restrict bh_val, int64_t *const __restrict bh_ids)

static inline void bs_addn (const uint32_t beam_size, const uint32_t n_per_beam, const HammingComputerT &hc, const uint8_t *const __restrict binary_vectors, const uint32_t k, int *const __restrict bh_val, int64_t *const __restrict bh_ids)

公共静态属性

static constexpr uint32_t NBUCKETS_8 = NBUCKETS / 8

template<typename C, uint32_t NBUCKETS, uint32_t N, typename HammingComputerT>
struct HeapWithBucketsForHamming16

template<uint32_t NBUCKETS, uint32_t N, typename HammingComputerT>
结构体 HeapWithBucketsForHamming16<CMax<int, int64_t>, NBUCKETS, N, HammingComputerT>

公共静态函数

static inline void addn (const uint32_t n, const HammingComputerT &hc, const uint8_t *const __restrict binaryVectors, const uint32_t k, int *const __restrict bh_val, int64_t *const __restrict bh_ids)

static inline void bs_addn (const uint32_t beam_size, const uint32_t n_per_beam, const HammingComputerT &hc, const uint8_t *const __restrict binary_vectors, const uint32_t k, int *const __restrict bh_val, int64_t *const __restrict bh_ids)

公共静态属性

static constexpr uint32_t NBUCKETS_16 = NBUCKETS / 16

template<MetricType mt>
结构体 VectorDistance

公共类型

using C = typename std::conditional<is_similarity_metric(mt), CMin<float, int64_t>, CMax<float, int64_t>>::type

公共函数

inline float operator()(const float *x, const float *y) const

inline float operator()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

内联 float 运算符()(const float *x, const float *y) const

公共成员

size_t d

float metric_arg

公共静态属性

static constexpr bool is_similarity = is_similarity_metric(mt)

template<class HammingComputer>
struct HCounterState

#include <hamming-inl.h>

该类维护到目前为止看到的最佳距离列表。

由于距离在一个有限的范围内（0 到 nbit），该对象维护每个可能距离的列表，并且只填充前 n 个列表，使得 n 个列表的大小之和小于 k。

公共函数

inline HCounterState(int *counters, int64_t *ids_per_dis, const uint8_t *x, int d, int k)

inline void update_counter(const uint8_t *y, size_t j)

公共成员

int *counters

int64_t *ids_per_dis

HammingComputer hc

int thres

int count_lt

int count_eq

int k

struct BitstringWriter

公共函数

inline BitstringWriter(uint8_t *code, size_t code_size)

inline void write(uint64_t x, int nbit)

公共成员

uint8_t *code

size_t code_size

size_t i

struct BitstringReader

公共函数

inline BitstringReader(const uint8_t *code, size_t code_size)

inline uint64_t read(int nbit)

公共成员

const uint8_t *code

size_t code_size

size_t i

struct HammingComputer4

公共函数

inline HammingComputer4()

inline HammingComputer4(const uint8_t *a, int code_size)

inline void set(const uint8_t *a, int code_size)

inline int hamming(const uint8_t *b) const

inline HammingComputer4()

inline HammingComputer4(const uint8_t *a, int code_size)

inline void set(const uint8_t *a, int code_size)

inline int hamming(const uint8_t *b) const

公共成员

uint32_t a0

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct HammingComputer8

公共函数

inline HammingComputer8()

inline HammingComputer8(const uint8_t *a, int code_size)

inline void set(const uint8_t *a, int code_size)

inline int hamming(const uint8_t *b) const

inline HammingComputer8()

inline HammingComputer8(const uint8_t *a, int code_size)

inline void set(const uint8_t *a, int code_size)

inline int hamming(const uint8_t *b) const

公共成员

uint64_t a0

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct HammingComputer16

公共函数

inline HammingComputer16()

inline HammingComputer16(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline HammingComputer16()

inline HammingComputer16(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

公共成员

uint64_t a0

uint64_t a1

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct HammingComputer20

公共函数

inline HammingComputer20()

inline HammingComputer20(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline HammingComputer20()

inline HammingComputer20(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

公共成员

uint64_t a0

uint64_t a1

uint32_t a2

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct HammingComputer32

公共函数

inline HammingComputer32()

inline HammingComputer32(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline HammingComputer32()

inline HammingComputer32(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

公共成员

uint64_t a0

uint64_t a1

uint64_t a2

uint64_t a3

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct HammingComputer64

公共函数

inline HammingComputer64()

inline HammingComputer64(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline HammingComputer64()

inline HammingComputer64(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

公共成员

uint64_t a0

uint64_t a1

uint64_t a2

uint64_t a3

uint64_t a4

uint64_t a5

uint64_t a6

uint64_t a7

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct HammingComputerDefault

继承自 faiss::HammingComputer< CODE_SIZE >

公共函数

inline HammingComputerDefault()

inline HammingComputerDefault(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8_2, int code_size)

inline int hamming(const uint8_t *b8) const

inline int get_code_size() const

inline HammingComputerDefault()

inline HammingComputerDefault(const uint8_t *a8, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline int get_code_size() const

公共成员

const uint8_t *a8

int quotient8

int remainder8

struct GenHammingComputer8

公共函数

inline GenHammingComputer8(const uint8_t *a, int code_size)

inline int hamming(const uint8_t *b) const

inline GenHammingComputer8(const uint8_t *a, int code_size)

inline int hamming(const uint8_t *b) const

公共成员

uint64_t a0

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size()

struct GenHammingComputer16

公共函数

inline GenHammingComputer16(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline GenHammingComputer16(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

公共成员

__m128i a

uint64_t a0

uint64_t a1

公共静态函数

static inline constexpr int get_code_size()

static inline constexpr int get_code_size ( )

struct GenHammingComputer32

公共函数

inline GenHammingComputer32 ( const uint8_t * a8, int code_size )

inline int hamming ( const uint8_t * b8 ) const

inline GenHammingComputer32 ( const uint8_t * a8, int code_size )

inline int hamming ( const uint8_t * b8 ) const

公共成员

__m256i a

uint64_t a0

uint64_t a1

uint64_t a2

uint64_t a3

公共静态函数

static inline constexpr int get_code_size ( )

static inline constexpr int get_code_size ( )

struct GenHammingComputerM8

公共函数

inline GenHammingComputerM8 ( const uint8_t * a8, int code_size )

inline int hamming(const uint8_t *b8) const

inline int get_code_size() const

inline GenHammingComputerM8(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline int get_code_size() const

公共成员

const uint64_t *a

int n

template<int CODE_SIZE>
struct HammingComputer : public faiss::HammingComputerDefault

公共函数

inline HammingComputer(const uint8_t *a, int code_size)

inline void set(const uint8_t *a8_2, int code_size)

inline void set(const uint8_t *a8, int code_size)

inline int hamming(const uint8_t *b8) const

inline int hamming(const uint8_t *b8) const

inline int get_code_size() const

inline int get_code_size() const

公共成员

const uint8_t *a8

int quotient8

int remainder8

template<typename C>
struct HeapArray

#include <Heap.h>

用于一组[最小|最大]堆的模板结构。它经过定制，因此堆的实际数据可以仅存在于紧凑数组中。

公共类型

typedef C::TI TI

typedef C::T T

公共函数

inline T *get_val(size_t key)

返回堆的值列表。

inline TI *get_ids(size_t key)

对应的标识符。

void heapify()

在添加之前准备所有堆

void addn(size_t nj, const T *vin, TI j0 = 0, size_t i0 = 0, int64_t ni = -1)

将 nj 个元素添加到堆 i0:i0+ni，具有连续的 ID

参数：

• nj – 要添加到每个堆的元素数量

• vin – 要添加的元素，大小为 ni * nj

• j0 – 将此值添加到要添加的 ID

• i0 – 要更新的第一个堆

• ni – 要更新的元素数量 (-1 = 使用 nh)

void addn_with_ids(size_t nj, const T *vin, const TI *id_in = nullptr, int64_t id_stride = 0, size_t i0 = 0, int64_t ni = -1)

与 addn 相同

参数：

• id_in – 要添加的元素的 ID，大小为 ni * nj

• id_stride – id_in 的步长

void addn_query_subset_with_ids(size_t nsubset, const TI *subset, size_t nj, const T *vin, const TI *id_in = nullptr, int64_t id_stride = 0)

与 addn_with_ids 相同，但仅适用于查询的子集

参数：

• nsubset – 要更新的查询条目的数量

• subset – 要更新的查询的索引，在 0..nh-1 范围内，大小为 nsubset

void reorder()

重新排序所有堆

void per_line_extrema(T *vals_out, TI *idx_out) const

这实际上不是一个堆函数。它只是找到数组 D 的每行极值

参数：

• vals_out – 每行的极值（大小为 nh，或 NULL）

• idx_out – 极值的索引（大小为 nh 或 NULL）

公共成员

size_t nh

堆的数量

size_t k

每个堆的分配大小

TI *ids

标识符（大小为 nh * k）

T *val

值（距离或相似度），大小为 nh * k

struct QINCoStep

公共函数

QINCoStep(int d, int K, int L, int h)

inline nn::FFN &get_residual_block(int i)

nn::Int32Tensor2D encode(const nn::Tensor2D &xhat, const nn::Tensor2D &x, nn::Tensor2D *residuals = nullptr) const

使用初始估计 xhat 对一组向量 x 进行编码。可以选择性地返回要添加到 xhat 的增量以形成新的 xhat

nn::Tensor2D decode(const nn::Tensor2D &xhat, const nn::Int32Tensor2D &codes) const

公共成员

int d

d: 输入维度, K: 码本大小, L: 残差块数量, h: 隐藏层维度

int K

int L

int h

nn::Embedding codebook

nn::Linear MLPconcat

std::vector<nn::FFN> residual_blocks

struct NeuralNetCodec

由 faiss::QINCo 继承

公共函数

inline NeuralNetCodec(int d, int M)

virtual nn::Tensor2D decode(const nn::Int32Tensor2D &codes) const = 0

virtual nn::Int32Tensor2D encode(const nn::Tensor2D &x) const = 0

inline virtual ~NeuralNetCodec()

公共成员

int d

int M

struct QINCo : public faiss::NeuralNetCodec

公共函数

QINCo(int d, int K, int L, int M, int h)

inline QINCoStep &get_step(int i)

virtual nn::Tensor2D decode(const nn::Int32Tensor2D &codes) const override

virtual nn::Int32Tensor2D encode(const nn::Tensor2D &x) const override

inline virtual ~QINCo()

公共成员

int K

int L

int h

nn::Embedding codebook0

std::vector<QINCoStep> steps

int d

int M

template<typename T_, typename TI_>
struct CMax

C 对象提供了键值存储的值的类型 T、键的类型 TI 以及执行的比较：CMax 用于递减序列，CMin 用于递增序列。 换句话说，对于给定的阈值 threshold，如果以下条件成立，则保留传入值 x：

C::cmp(threshold, x)

为真。

公共类型

typedef T_ T

typedef TI_ TI

typedef CMin<T_, TI_> Crev

公共静态函数

static inline bool cmp(T a, T b)

static inline bool cmp2(T a1, T b1, TI a2, TI b2)

static inline T neutral()

static inline T nextafter(T x)

公共静态属性

static const bool is_max = true

template<typename T_, typename TI_>
struct CMin

公共类型

typedef T_ T

typedef TI_ TI

typedef CMax<T_, TI_> Crev

公共静态函数

static inline bool cmp(T a, T b)

static inline bool cmp2(T a1, T b1, TI a2, TI b2)

static inline T neutral()

static inline T nextafter(T x)

公共静态属性

static const bool is_max = false

struct PartitionStats

公共函数

inline PartitionStats()

void reset()

公共成员

uint64_t bissect_cycles

uint64_t compress_cycles

struct RandomGenerator

#include <random.h>

random generator that can be used in multithreaded contexts

公共函数

int rand_int()

random positive integer

int64_t rand_int64()

随机 int64_t

int rand_int(int max)

生成 0 到 max-1 之间的随机整数

float rand_float()

介于 0 和 1 之间

double rand_double()

explicit RandomGenerator(int64_t seed = 1234)

公共成员

std::mt19937 mt

struct SplitMix64RandomGenerator

#include <random.h>

快速随机数生成器，不能在多线程上下文中使用。 基于 https://prng.di.unimi.it/

公共函数

int rand_int()

random positive integer

int64_t rand_int64()

随机 int64_t

int rand_int(int max)

生成 0 到 max-1 之间的随机整数

float rand_float()

介于 0 和 1 之间

double rand_double()

explicit SplitMix64RandomGenerator(int64_t seed = 1234)

uint64_t next()

公共成员

uint64_t state

struct simd256bit

#include <simdlib_avx2.h>

256 位表示，不解释为向量

AVX 256 位寄存器的简单包装器

目标是分离相同寄存器的不同解释（作为 uint8、uint16 或 uint32 的向量），提供打印函数，并为 AVX intrinsic 提供更易读的名称。 它并不试图详尽无遗，而是根据需要添加函数。

由 faiss::simd16uint16, faiss::simd16uint16, faiss::simd16uint16, faiss::simd32uint8, faiss::simd32uint8, faiss::simd32uint8, faiss::simd8float32, faiss::simd8float32, faiss::simd8float32, faiss::simd8uint32, faiss::simd8uint32, faiss::simd8uint32 继承

公共函数

inline simd256bit()

inline explicit simd256bit(__m256i i)

inline explicit simd256bit(__m256 f)

inline explicit simd256bit(const void *x)

inline void clear()

inline void storeu(void *ptr) const

内联函数，将SIMD 256位数据以非对齐的方式存储到指定内存地址。

inline void loadu(const void *ptr)

内联函数，从指定内存地址以非对齐的方式加载SIMD 256位数据。

inline void store(void *ptr) const

内联函数，将SIMD 256位数据存储到指定内存地址（需要对齐）。

inline void bin(char bits[257]) const

内联函数，将SIMD 256位数据转换为257个字符的二进制表示。

inline std::string bin() const

内联函数，返回SIMD 256位数据的二进制字符串表示。

inline bool is_same_as(simd256bit other) const

内联函数，检查当前SIMD 256位数据是否与另一个SIMD 256位数据相同。

inline simd256bit()

内联函数，默认构造函数。

inline explicit simd256bit(const void *x)

inline void bin(char bits[257]) const

内联函数，将SIMD 256位数据转换为257个字符的二进制表示。

inline std::string bin() const

内联函数，返回SIMD 256位数据的二进制字符串表示。

inline bool is_same_as(simd256bit other) const

内联函数，检查当前SIMD 256位数据是否与另一个SIMD 256位数据相同。

inline simd256bit()

内联函数，默认构造函数。

inline explicit simd256bit(const void *x)

公共成员

内联函数，显式构造函数，从指定内存地址加载数据。

inline void clear()

内联函数，清除SIMD 256位数据。

inline void storeu(void *ptr) const

内联函数，将SIMD 256位数据以非对齐的方式存储到指定内存地址。

inline void loadu(const void *ptr)

内联函数，从指定内存地址以非对齐的方式加载SIMD 256位数据。

inline void store(void *ptr) const

内联函数，将SIMD 256位数据存储到指定内存地址（需要对齐）。

struct simd16uint16 : public faiss::simd256bit, public faiss::simd256bit, public faiss::simd256bit

#include <simdlib_avx2.h>

uint16 中的 16 个元素的向量

公共函数

inline simd16uint16()

inline explicit simd16uint16(__m256i i)

inline explicit simd16uint16(int x)

inline explicit simd16uint16(uint16_t x)

inline explicit simd16uint16(simd256bit x)

inline explicit simd16uint16(const uint16_t *x)

inline explicit simd16uint16(uint16_t u0, uint16_t u1, uint16_t u2, uint16_t u3, uint16_t u4, uint16_t u5, uint16_t u6, uint16_t u7, uint16_t u8, uint16_t u9, uint16_t u10, uint16_t u11, uint16_t u12, uint16_t u13, uint16_t u14, uint16_t u15)

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

inline std::string dec() const

inline void set1(uint16_t x)

inline simd16uint16 operator*(const simd16uint16 &other) const

inline simd16uint16 operator>>(const int shift) const

inline simd16uint16 operator<<(const int shift) const

inline simd16uint16 operator+=(simd16uint16 other)

减赋值运算符

加法运算符

减法运算符

与运算符

或运算符

异或运算符

按位取反运算符

获取标量 0

大于等于掩码

小于等于掩码

大于掩码

内联 bool all_gt(const simd16uint16& thresh)const

内联 uint16_t operator[](int i)const

内联 void accu_min(const simd16uint16& incoming)

内联 void accu_max(const simd16uint16& incoming)

内联 simd16uint16()

内联 explicit simd16uint16(int x)

内联 explicit simd16uint16(uint16_t x)

内联 explicit simd16uint16(const simd256bit& x)

内联 explicit simd16uint16(const uint16_t* x)

内联 explicit simd16uint16(uint16_t u0, uint16_t u1, uint16_t u2, uint16_t u3, uint16_t u4, uint16_t u5, uint16_t u6, uint16_t u7, uint16_t u8, uint16_t u9, uint16_t u10, uint16_t u11, uint16_t u12, uint16_t u13, uint16_t u14, uint16_t u15)

内联 std::string elements_to_string(const char* fmt)const

内联 std::string hex()const

内联 std::string dec()const

内联 void set1(uint16_t x)

内联 simd16uint16 operator*(const simd16uint16& other)const

内联 simd16uint16 operator>>(const int shift)const

内联 simd16uint16 operator<<(const int shift)const

内联 simd16uint16 operator+=(const simd16uint16& other)

内联 simd16uint16 operator-=(const simd16uint16 &other)

内联 simd16uint16 operator+(const simd16uint16 &other) const

内联 simd16uint16 operator-(const simd16uint16 &other) const

内联 simd16uint16 operator&(const simd256bit &other) const

内联 simd16uint16 operator|(const simd256bit &other) const

内联 simd16uint16 operator^(const simd256bit &other) const

内联 simd16uint16 operator==(const simd16uint16 &other) const

内联 simd16uint16 operator~() const

内联 uint16_t get_scalar_0() const

内联 uint32_t ge_mask(const simd16uint16 &thresh) const

内联 uint32_t le_mask(const simd16uint16 &thresh) const

内联 uint32_t gt_mask(const simd16uint16 &thresh) const

内联 bool all_gt(const simd16uint16 &thresh) const

inline uint16_t operator[](int i) const

inline void accu_min(const simd16uint16 &incoming)

inline void accu_max(const simd16uint16 &incoming)

simd16uint16() = default

内联 explicit simd16uint16(int x)

内联 explicit simd16uint16(uint16_t x)

inline explicit simd16uint16(const uint16x8x2_t &v)

内联 explicit simd16uint16(uint16_t u0, uint16_t u1, uint16_t u2, uint16_t u3, uint16_t u4, uint16_t u5, uint16_t u6, uint16_t u7, uint16_t u8, uint16_t u9, uint16_t u10, uint16_t u11, uint16_t u12, uint16_t u13, uint16_t u14, uint16_t u15)

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline explicit simd16uint16(const T &x)

内联 explicit simd16uint16(const uint16_t* x)

inline void clear()

inline void storeu(uint16_t *ptr) const

inline void loadu(const uint16_t *ptr)

inline void store(uint16_t *ptr) const

inline void bin(char bits[257]) const

inline std::string bin() const

内联 std::string elements_to_string(const char* fmt)const

内联 std::string hex()const

内联 std::string dec()const

内联 void set1(uint16_t x)

内联 simd16uint16 operator*(const simd16uint16& other)const

内联 simd16uint16 operator>>(const int shift)const

内联 simd16uint16 operator<<(const int shift)const

inline simd16uint16 operator+=(const simd16uint16 &other)

inline simd16uint16 operator-=(const simd16uint16 &other)

inline simd16uint16 operator+(const simd16uint16 &other) const

inline simd16uint16 operator-(const simd16uint16 &other) const

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline simd16uint16 operator&(const T &other) const

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline simd16uint16 operator|(const T &other) const

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline simd16uint16 operator^(const T &other) const

inline simd16uint16 operator==(const simd16uint16 &other) const

template<typename T>
inline bool is_same_as(T other) const

内联 simd16uint16 operator~() const

内联 uint16_t get_scalar_0() const

inline uint32_t ge_mask(const simd16uint16 &thresh) const

inline uint32_t le_mask(const simd16uint16 &thresh) const

inline uint32_t gt_mask(const simd16uint16 &thresh) const

inline bool all_gt(const simd16uint16 &thresh) const

inline uint16_t operator[](int i) const

inline void accu_min(const simd16uint16 &incoming)

inline void accu_max(const simd16uint16 &incoming)

内联 simd16uint16()

内联 explicit simd16uint16(int x)

内联 explicit simd16uint16(uint16_t x)

inline explicit simd16uint16(const simd256bit &x)

内联 explicit simd16uint16(const uint16_t* x)

内联 explicit simd16uint16(uint16_t u0, uint16_t u1, uint16_t u2, uint16_t u3, uint16_t u4, uint16_t u5, uint16_t u6, uint16_t u7, uint16_t u8, uint16_t u9, uint16_t u10, uint16_t u11, uint16_t u12, uint16_t u13, uint16_t u14, uint16_t u15)

内联 std::string elements_to_string(const char* fmt)const

内联 std::string hex()const

内联 std::string dec()const

内联 void set1(uint16_t x)

内联 simd16uint16 operator*(const simd16uint16& other)const

内联 simd16uint16 operator>>(const int shift)const

内联 simd16uint16 operator<<(const int shift)const

inline simd16uint16 operator+=(const simd16uint16 &other)

inline simd16uint16 operator-=(const simd16uint16 &other)

inline simd16uint16 operator+(const simd16uint16 &other) const

inline simd16uint16 operator-(const simd16uint16 &other) const

inline simd16uint16 operator&(const simd256bit &other) const

inline simd16uint16 operator|(const simd256bit &other) const

inline simd16uint16 operator^(const simd256bit &other) const

inline simd16uint16 operator==(const simd16uint16 &other) const

内联 simd16uint16 operator~() const

内联 uint16_t get_scalar_0() const

inline uint32_t ge_mask(const simd16uint16 &thresh) const

inline uint32_t le_mask(const simd16uint16 &thresh) const

inline uint32_t gt_mask(const simd16uint16 &thresh) const

inline bool all_gt(const simd16uint16 &thresh) const

inline uint16_t operator[](int i) const

inline void accu_min(const simd16uint16 &incoming)

inline void accu_max(const simd16uint16 &incoming)

inline void storeu(void *ptr) const

inline void loadu(const void *ptr)

inline void store(void *ptr) const

inline bool is_same_as(simd256bit other) const

公共成员

uint16x8x2_t data

__m256i i

__m256 f

union faiss::simd256bit::[anonymous] [anonymous]

uint8_t u8[32]

uint16_t u16[16]

uint32_t u32[8]

float f32[8]

union faiss::simd256bit::[anonymous] [anonymous]

union faiss::simd256bit::[anonymous] [anonymous]

公共静态函数

template<typename F>
static inline simd16uint16 unary_func(const simd16uint16 &a, F &&f)

template<typename F>
static inline simd16uint16 binary_func(const simd16uint16 &a, const simd16uint16 &b, F &&f)

template<typename F>
static inline simd16uint16 unary_func(const simd16uint16 &a, F &&f)

template<typename F>
static inline simd16uint16 binary_func(const simd16uint16 &a, const simd16uint16 &b, F &&f)

友元

inline friend simd16uint16 operator==(const simd256bit lhs, const simd256bit rhs)

struct simd32uint8 : public faiss::simd256bit, public faiss::simd256bit, public faiss::simd256bit

公共函数

inline simd32uint8()

inline explicit simd32uint8(__m256i i)

inline explicit simd32uint8(int x)

inline explicit simd32uint8(uint8_t x)

inline explicit simd32uint8(simd256bit x)

inline explicit simd32uint8(const uint8_t *x)

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

inline std::string dec() const

inline void set1(uint8_t x)

inline simd32uint8 operator&(simd256bit other) const

inline simd32uint8 operator+(simd32uint8 other) const

inline simd32uint8 lookup_2_lanes(simd32uint8 idx) const

inline simd16uint16 lane0_as_uint16() const

inline simd16uint16 lane1_as_uint16() const

inline simd32uint8 operator+=(simd32uint8 other)

inline uint8_t operator[](int i) const

inline simd32uint8()

inline explicit simd32uint8(int x)

inline explicit simd32uint8(uint8_t x)

inline explicit simd32uint8(const simd256bit &x)

inline explicit simd32uint8(const uint8_t *x)

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

内联 std::string dec() const

内联 void set1(uint8_t x)

内联 simd32uint8 operator&(const simd256bit &other) const

inline simd32uint8 operator+(const simd32uint8 &other) const

inline simd32uint8 lookup_2_lanes(const simd32uint8 &idx) const

inline simd32uint8 operator+=(const simd32uint8 &other)

inline uint8_t operator[](int i) const

simd32uint8() = default

inline explicit simd32uint8(int x)

inline explicit simd32uint8(uint8_t x)

inline explicit simd32uint8(const uint8x16x2_t &v)

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline explicit simd32uint8(const T &x)

inline explicit simd32uint8(const uint8_t *x)

inline void clear()

inline void storeu(uint8_t *ptr) const

inline void loadu(const uint8_t *ptr)

inline void store(uint8_t *ptr) const

inline void bin(char bits[257]) const

inline std::string bin() const

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

内联 std::string dec() const

内联 void set1(uint8_t x)

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline simd32uint8 operator&(const T &other) const

inline simd32uint8 operator+(const simd32uint8 &other) const

inline simd32uint8 lookup_2_lanes(const simd32uint8 &idx) const

inline simd32uint8 operator+=(const simd32uint8 &other)

inline uint8_t operator[](int i) const

template<typename T>
inline bool is_same_as(T other) const

inline simd32uint8()

inline explicit simd32uint8(int x)

inline explicit simd32uint8(uint8_t x)

inline explicit simd32uint8(const simd256bit &x)

inline explicit simd32uint8(const uint8_t *x)

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

内联 std::string dec() const

内联 void set1(uint8_t x)

inline simd32uint8 operator&(const simd256bit &other) const

inline simd32uint8 operator+(const simd32uint8 &other) const

inline simd32uint8 lookup_2_lanes(const simd32uint8 &idx) const

inline simd32uint8 operator+=(const simd32uint8 &other)

inline uint8_t operator[](int i) const

inline void storeu(void *ptr) const

inline void loadu(const void *ptr)

inline void store(void *ptr) const

inline bool is_same_as(simd256bit other) const

公共成员

uint8x16x2_t data

__m256i i

__m256 f

union faiss::simd256bit::[anonymous] [anonymous]

uint8_t u8[32]

uint16_t u16[16]

uint32_t u32[8]

float f32[8]

union faiss::simd256bit::[anonymous] [anonymous]

union faiss::simd256bit::[anonymous] [anonymous]

公共静态函数

template<uint8_t _0, uint8_t _1, uint8_t _2, uint8_t _3, uint8_t _4, uint8_t _5, uint8_t _6, uint8_t _7, uint8_t _8, uint8_t _9, uint8_t _10, uint8_t _11, uint8_t _12, uint8_t _13, uint8_t _14, uint8_t _15, uint8_t _16, uint8_t _17, uint8_t _18, uint8_t _19, uint8_t _20, uint8_t _21, uint8_t _22, uint8_t _23, uint8_t _24, uint8_t _25, uint8_t _26, uint8_t _27, uint8_t _28, uint8_t _29, uint8_t _30, uint8_t _31>
static inline simd32uint8 create()

template<uint8_t _0, uint8_t _1, uint8_t _2, uint8_t _3, uint8_t _4, uint8_t _5, uint8_t _6, uint8_t _7, uint8_t _8, uint8_t _9, uint8_t _10, uint8_t _11, uint8_t _12, uint8_t _13, uint8_t _14, uint8_t _15, uint8_t _16, uint8_t _17, uint8_t _18, uint8_t _19, uint8_t _20, uint8_t _21, uint8_t _22, uint8_t _23, uint8_t _24, uint8_t _25, uint8_t _26, uint8_t _27, uint8_t _28, uint8_t _29, uint8_t _30, uint8_t _31>
static inline simd32uint8 create()

template<typename F>
static inline simd32uint8 binary_func(const simd32uint8 &a, const simd32uint8 &b, F &&f)

template<uint8_t _0, uint8_t _1, uint8_t _2, uint8_t _3, uint8_t _4, uint8_t _5, uint8_t _6, uint8_t _7, uint8_t _8, uint8_t _9, uint8_t _10, uint8_t _11, uint8_t _12, uint8_t _13, uint8_t _14, uint8_t _15, uint8_t _16, uint8_t _17, uint8_t _18, uint8_t _19, uint8_t _20, uint8_t _21, uint8_t _22, uint8_t _23, uint8_t _24, uint8_t _25, uint8_t _26, uint8_t _27, uint8_t _28, uint8_t _29, uint8_t _30, uint8_t _31>
static inline simd32uint8 create()

template<uint8_t _0, uint8_t _1, uint8_t _2, uint8_t _3, uint8_t _4, uint8_t _5, uint8_t _6, uint8_t _7, uint8_t _8, uint8_t _9, uint8_t _10, uint8_t _11, uint8_t _12, uint8_t _13, uint8_t _14, uint8_t _15, uint8_t _16, uint8_t _17, uint8_t _18, uint8_t _19, uint8_t _20, uint8_t _21, uint8_t _22, uint8_t _23, uint8_t _24, uint8_t _25, uint8_t _26, uint8_t _27, uint8_t _28, uint8_t _29, uint8_t _30, uint8_t _31>
static inline simd32uint8 create()

template<typename F>
static inline simd32uint8 binary_func(const simd32uint8 &a, const simd32uint8 &b, F &&f)

struct simd8uint32 : public faiss::simd256bit, public faiss::simd256bit, public faiss::simd256bit

#include <simdlib_avx2.h>

vector of 8 unsigned 32-bit integers

公共函数

inline simd8uint32()

inline explicit simd8uint32(__m256i i)

inline explicit simd8uint32(uint32_t x)

inline explicit simd8uint32(simd256bit x)

inline explicit simd8uint32(const uint8_t *x)

inline explicit simd8uint32(uint32_t u0, uint32_t u1, uint32_t u2, uint32_t u3, uint32_t u4, uint32_t u5, uint32_t u6, uint32_t u7)

inline simd8uint32 operator+(simd8uint32 other) const

inline simd8uint32 operator-(simd8uint32 other) const

inline simd8uint32 &operator+=(const simd8uint32 &other)

inline bool operator==(simd8uint32 other) const

inline bool operator!=(simd8uint32 other) const

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

inline std::string dec() const

inline void set1(uint32_t x)

inline simd8uint32 unzip() const

inline simd8uint32()

inline explicit simd8uint32(uint32_t x)

inline explicit simd8uint32(const simd256bit &x)

inline explicit simd8uint32(const uint32_t *x)

内联 显式 simd8uint32(uint32_t u0, uint32_t u1, uint32_t u2, uint32_t u3, uint32_t u4, uint32_t u5, uint32_t u6, uint32_t u7)

内联 simd8uint32 operator+(simd8uint32 other) const

内联 simd8uint32 operator-(simd8uint32 other) const

内联 simd8uint32 &operator+=(const simd8uint32 &other)

内联 bool operator==(simd8uint32 other) const

内联 bool operator!=(simd8uint32 other) const

内联 std::string elements_to_string(const char *fmt) const

内联 std::string hex() const

内联 std::string dec() const

内联 void set1(uint32_t x)

内联 simd8uint32 unzip() const

simd8uint32() = 默认

inline explicit simd8uint32(uint32_t x)

内联 显式 simd8uint32(const uint32x4x2_t &v)

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline explicit simd8uint32(const T &x)

inline explicit simd8uint32(const uint8_t *x)

内联 显式 simd8uint32(uint32_t u0, uint32_t u1, uint32_t u2, uint32_t u3, uint32_t u4, uint32_t u5, uint32_t u6, uint32_t u7)

内联 simd8uint32 operator+(simd8uint32 other) const

内联 simd8uint32 operator-(simd8uint32 other) const

内联 simd8uint32 &operator+=(const simd8uint32 &other)

inline simd8uint32 operator==(simd8uint32 other) const

inline simd8uint32 operator~() const

inline simd8uint32 operator!=(simd8uint32 other) const

template<typename T>
inline bool is_same_as(T other) const

inline void clear()

inline void storeu(uint32_t *ptr) const

inline void loadu(const uint32_t *ptr)

inline void store(uint32_t *ptr) const

inline void bin(char bits[257]) const

inline std::string bin() const

内联 std::string elements_to_string(const char *fmt) const

内联 std::string hex() const

内联 std::string dec() const

内联 void set1(uint32_t x)

内联 simd8uint32 unzip() const

inline simd8uint32()

inline explicit simd8uint32(uint32_t x)

inline explicit simd8uint32(const simd256bit &x)

inline explicit simd8uint32(const uint32_t *x)

内联 显式 simd8uint32(uint32_t u0, uint32_t u1, uint32_t u2, uint32_t u3, uint32_t u4, uint32_t u5, uint32_t u6, uint32_t u7)

内联 simd8uint32 operator+(simd8uint32 other) const

内联 simd8uint32 operator-(simd8uint32 other) const

内联 simd8uint32 &operator+=(const simd8uint32 &other)

内联 bool operator==(simd8uint32 other) const

内联 bool operator!=(simd8uint32 other) const

内联 std::string elements_to_string(const char *fmt) const

内联 std::string hex() const

内联 std::string dec() const

内联 void set1(uint32_t x)

内联 simd8uint32 unzip() const

inline void storeu(void *ptr) const

inline void loadu(const void *ptr)

inline void store(void *ptr) const

inline bool is_same_as(simd256bit other) const

公共成员

uint32x4x2_t data

__m256i i

__m256 f

union faiss::simd256bit::[anonymous] [anonymous]

uint8_t u8[32]

uint16_t u16[16]

uint32_t u32[8]

float f32[8]

union faiss::simd256bit::[anonymous] [anonymous]

union faiss::simd256bit::[anonymous] [anonymous]

struct simd8float32 : public faiss::simd256bit, public faiss::simd256bit, public faiss::simd256bit

公共函数

inline simd8float32()

inline explicit simd8float32(simd256bit x)

inline explicit simd8float32(__m256 x)

inline explicit simd8float32(float x)

inline explicit simd8float32(const float *x)

inline explicit simd8float32(float f0, float f1, float f2, float f3, float f4, float f5, float f6, float f7)

inline simd8float32 operator*(simd8float32 other) const

inline simd8float32 operator+(simd8float32 other) const

inline simd8float32 operator-(simd8float32 other) const

inline simd8float32 & operator+=(const simd8float32 &other)

inline bool operator==(simd8float32 other) const

inline bool operator!=(simd8float32 other) const

inline std::string tostring() const

inline simd8float32()

inline explicit simd8float32(const simd256bit &x)

inline explicit simd8float32(float x)

inline explicit simd8float32(const float *x)

inline void set1(float x)

inline explicit simd8float32(float f0, float f1, float f2, float f3, float f4, float f5, float f6, float f7)

inline simd8float32 operator*(const simd8float32 &other) const

inline simd8float32 operator+(const simd8float32 &other) const

inline simd8float32 operator-(const simd8float32 &other) const

inline simd8float32 &operator+=(const simd8float32 &other)

inline bool operator==(simd8float32 other) const

inline bool operator!=(simd8float32 other) const

inline std::string tostring() const

simd8float32() = default

inline explicit simd8float32(float x)

inline explicit simd8float32(const float32x4x2_t &v)

template<typename T, typename std::enable_if<detail::simdlib::is_simd256bit<T>::value, std::nullptr_t>::type = nullptr>
inline explicit simd8float32(const T &x)

inline explicit simd8float32(const float *x)

inline explicit simd8float32(float f0, float f1, float f2, float f3, float f4, float f5, float f6, float f7)

inline void clear()

inline void storeu(float *ptr) const

inline void loadu(const float *ptr)

inline void store(float *ptr) const

inline void bin(char bits[257]) const

inline std::string bin() const

inline simd8float32 operator*(const simd8float32 &other) const

inline simd8float32 operator+(const simd8float32 &other) const

inline simd8float32 operator-(const simd8float32 &other) const

inline simd8float32 &operator+=(const simd8float32 &other)

inline simd8uint32 operator==(simd8float32 other) const

inline simd8uint32 operator!=(simd8float32 other) const

template<typename T>
inline bool is_same_as(T other) const

inline std::string tostring() const

inline simd8float32()

inline explicit simd8float32(const simd256bit &x)

inline explicit simd8float32(float x)

inline explicit simd8float32(const float *x)

inline void set1(float x)

inline explicit simd8float32(float f0, float f1, float f2, float f3, float f4, float f5, float f6, float f7)

inline simd8float32 operator*(const simd8float32 &other) const

inline simd8float32 operator+(const simd8float32 &other) const

inline simd8float32 operator-(const simd8float32 &other) const

inline simd8float32 &operator+=(const simd8float32 &other)

inline bool operator==(simd8float32 other) const

inline bool operator!=(simd8float32 other) const

inline std::string tostring() const

inline void storeu(void *ptr) const

inline void loadu(const void *ptr)

inline void store(void *ptr) const

inline bool is_same_as(simd256bit other) const

公共成员

float32x4x2_t data

__m256i i

__m256 f

union faiss::simd256bit::[anonymous] [anonymous]

uint8_t u8[32]

uint16_t u16[16]

uint32_t u32[8]

float f32[8]

union faiss::simd256bit::[anonymous] [anonymous]

union faiss::simd256bit::[anonymous] [anonymous]

公共静态函数

template<typename F>
static inline simd8float32 binary_func(const simd8float32 &a, const simd8float32 &b, F &&f)

template<typename F>
static inline simd8float32 binary_func(const simd8float32 &a, const simd8float32 &b, F &&f)

struct simd512bit

#include <simdlib_avx512.h>

不解释为向量的512位表示

AVX 512位寄存器的简单包装器

目标是分离相同寄存器的不同解释（作为 uint8、uint16 或 uint32 的向量），提供打印函数，并为 AVX intrinsic 提供更易读的名称。 它并不试图详尽无遗，而是根据需要添加函数。

被 faiss::simd32uint16, faiss::simd64uint8 子类化

公共函数

inline simd512bit()

inline explicit simd512bit(__m512i i)

inline explicit simd512bit(__m512 f)

inline explicit simd512bit(const void *x)

inline explicit simd512bit(simd256bit lo)

inline explicit simd512bit(simd256bit lo, simd256bit hi)

inline void clear()

inline void storeu(void *ptr) const

内联函数，用于从内存中加载数据。

内联函数，用于将数据存储到内存中。

内联函数，将数据转换为二进制表示，并存储到字符数组中。

内联函数，将数据转换为二进制字符串表示。

公共成员

512位整数向量。

512位浮点数向量。

匿名联合体。

结构体 simd32uint16，继承自 faiss::simd512bit。

#include <simdlib_avx512.h>

包含 32 个 uint16 类型元素的向量。

公共函数

内联函数，simd32uint16 的默认构造函数。

内联显式构造函数，用 __m512i 初始化 simd32uint16。

内联显式构造函数，用 int 初始化 simd32uint16。

内联显式构造函数，用 uint16_t 初始化 simd32uint16。

内联显式构造函数，用 faiss::simd512bit 初始化 simd32uint16。

内联显式构造函数，用 uint16_t 指针初始化 simd32uint16。

内联显式构造函数，用 faiss::simd256bit 初始化 simd32uint16的低位部分。

内联显式构造函数，用两个 faiss::simd256bit 初始化 simd32uint16，一个用于低位部分，一个用于高位部分。

内联函数，将 simd32uint16 的元素转换为字符串，使用指定的格式。

内联函数，将 simd32uint16 的元素转换为十六进制字符串。

内联函数，将 simd32uint16 的元素转换为十进制字符串。

内联函数，将 simd32uint16 的所有元素设置为指定的值。

inline simd32uint16 operator*(const simd32uint16 &other) const

inline simd32uint16 operator>>(const int shift) const

inline simd32uint16 operator<<(const int shift) const

inline simd32uint16 operator+=(simd32uint16 other)

inline simd32uint16 operator-=(simd32uint16 other)

inline simd32uint16 operator+(simd32uint16 other) const

inline simd32uint16 operator-(simd32uint16 other) const

inline simd32uint16 operator&(simd512bit other) const

inline simd32uint16 operator|(simd512bit other) const

inline simd32uint16 operator^(simd512bit other) const

inline simd32uint16 operator~() const

inline simd16uint16 low() const

inline simd16uint16 high() const

inline uint16_t operator[](int i) const

inline void accu_min(simd32uint16 incoming)

inline void accu_max(simd32uint16 incoming)

inline void clear()

inline void storeu(void *ptr) const

inline void loadu(const void *ptr)

inline void store(void *ptr) const

inline void bin(char bits[513]) const

inline std::string bin() const

公共成员

__m512i i

__m512 f

union faiss::simd512bit::[anonymous] [anonymous]

struct simd64uint8 : public faiss::simd512bit

公共函数

inline simd64uint8()

inline explicit simd64uint8(__m512i i)

inline explicit simd64uint8(int x)

inline explicit simd64uint8(uint8_t x)

inline explicit simd64uint8(simd256bit lo)

inline explicit simd64uint8(simd256bit lo, simd256bit hi)

inline explicit simd64uint8(simd512bit x)

inline explicit simd64uint8(const uint8_t *x)

inline std::string elements_to_string(const char *fmt) const

inline std::string hex() const

inline std::string dec() const

inline void set1(uint8_t x)

inline simd64uint8 operator&(simd512bit other) const

inline simd64uint8 operator+(simd64uint8 other) const

inline simd64uint8 lookup_4_lanes(simd64uint8 idx) const

inline simd32uint16 lane0_as_uint16() const

inline simd32uint16 lane1_as_uint16() const

inline simd64uint8 operator+=(simd64uint8 other)

inline uint8_t operator[](int i) const

inline void clear()

inline void storeu(void *ptr) const

inline void loadu(const void *ptr)

inline void store(void *ptr) const

inline void bin(char bits[513]) const

inline std::string bin() const

公共成员

__m512i i

__m512 f

union faiss::simd512bit::[anonymous] [anonymous]

template<typename T>
struct CombinerRangeKNN

#include <utils.h>

此类用于在 contrib.exhaustive_search.range_search_gpu 中组合范围和 knn 搜索结果

公共函数

inline CombinerRangeKNN(int64_t nq, size_t k, T r2, bool keep_max)

是否保留最大值而不是最小值。

void compute_sizes(int64_t *L_res)

大小 nq + 1

void write_result(T *D_res, int64_t *I_res)

阶段 2：调用者分配 D_res 和 I_res（大小为 L_res[nq]） 阶段 3：填充 D_res 和 I_res

公共成员

int64_t nq

size_t k

查询数量

T r2

knn 搜索部分的邻居数量

bool keep_max

范围搜索半径

const int64_t *I = nullptr

Knn 搜索结果。

const T *D = nullptr

大小 nq * k

const bool *mask = nullptr

大小 nq * k

可选：范围搜索结果（如果 mask 为 NULL，则忽略）

const int64_t *lim_remain = nullptr

knn 结果有效的掩码，大小为 nq

const T *D_remain = nullptr

大小 nrange + 1

const int64_t *I_remain = nullptr

大小 lim_remain[nrange]

const int64_t *L_res = nullptr

大小 lim_remain[nrange]

struct CodeSet

公共函数

inline explicit CodeSet(size_t d)

void insert(size_t n, const uint8_t *codes, bool *inserted)

公共成员

size_t d

std::set<std::vector<uint8_t>> s

class WorkerThread

公共函数

WorkerThread()

~WorkerThread()

停止并等待工作线程退出，刷新所有待处理的 lambda

void stop()

请求工作线程自行停止。

void waitForThreadExit()

在当前线程中阻塞等待工作线程停止

std::future<bool> add(std::function<void()> f)

添加一个 lambda 函数到工作线程中运行；返回一个 future 对象，可用于阻塞直到该函数完成。如果 lambda 函数在工作线程中运行，future 对象的状态为 true；如果因为工作线程正在退出或已退出而未运行，则为 false。

私有函数

void startThread()

void threadMain()

void threadLoop()

私有成员

std::thread thread_

所有排队的 lambda 函数都在此线程上运行。

std::mutex mutex_

队列和退出状态的互斥锁。

std::condition_variable monitor_

退出状态和队列的监视器。

bool wantStop_

是否希望线程退出。

std::deque<std::pair<std::function<void()>, std::promise<bool>>> queue_

待调用的 lambda 函数的队列。

struct VectorTransform

#include <VectorTransform.h>

应用于向量集合的任何转换

子类包括 faiss::CenteringTransform, faiss::ITQTransform, faiss::LinearTransform, faiss::NormalizationTransform, faiss::RemapDimensionsTransform

公共函数

inline explicit VectorTransform(int d_in = 0, int d_out = 0)

! 输出维度

virtual void train(idx_t n, const float *x)

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const = 0

应用转换并在提供的矩阵中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

• xt – 输出向量，大小为 n * d_out

virtual void reverse_transform(idx_t n, const float *xt, float *x) const

反向变换。 可能未实现，或者可能返回近似结果。

virtual void check_identical(const VectorTransform &other) const = 0

inline virtual ~VectorTransform()

公共成员

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct LinearTransform : public faiss::VectorTransform

#include <VectorTransform.h>

通用线性变换，输出上应用偏置项 y = A * x + b

被faiss::ITQMatrix, faiss::OPQMatrix, faiss::PCAMatrix, faiss::RandomRotationMatrix继承

公共函数

explicit LinearTransform(int d_in = 0, int d_out = 0, bool have_bias = false)

支持 d_in > d_out 和 d_out < d_in

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

与 apply 相同，但结果是预先分配的

void transform_transpose(idx_t n, const float *y, float *x) const

计算 x = A^T * (x - b)，如果 A 具有正交的行，则是反向变换

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

仅在 is_orthonormal 时有效

void set_is_orthonormal()

计算 A^T * A 以设置 is_orthonormal 标志

void print_if_verbose(const char *name, const std::vector<double> &mat, int n, int d) const

virtual void check_identical(const VectorTransform &other) const override

inline ~LinearTransform() override

virtual void train(idx_t n, const float *x)

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

bool have_bias

bool is_orthonormal

! 是否使用偏差项

检查矩阵A是否是正交的 (启用 reverse_transform)

std::vector<float> A

变换矩阵，大小为 d_out * d_in。

std::vector<float> b

偏差向量，大小为 d_out

bool verbose

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct RandomRotationMatrix : public faiss::LinearTransform

#include <VectorTransform.h>

随机旋转一组向量。

公共函数

inline RandomRotationMatrix(int d_in, int d_out)

支持 d_in > d_out 和 d_out < d_in

void init(int seed)

必须在使用变换之前调用

virtual void train(idx_t n, const float *x) override

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

inline RandomRotationMatrix()

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

与 apply 相同，但结果是预先分配的

void transform_transpose(idx_t n, const float *y, float *x) const

计算 x = A^T * (x - b)，如果 A 具有正交的行，则是反向变换

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

仅在 is_orthonormal 时有效

void set_is_orthonormal()

计算 A^T * A 以设置 is_orthonormal 标志

void print_if_verbose(const char *name, const std::vector<double> &mat, int n, int d) const

virtual void check_identical(const VectorTransform &other) const override

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

bool have_bias

bool is_orthonormal

! 是否使用偏差项

检查矩阵A是否是正交的 (启用 reverse_transform)

std::vector<float> A

变换矩阵，大小为 d_out * d_in。

std::vector<float> b

偏差向量，大小为 d_out

bool verbose

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct PCAMatrix : public faiss::LinearTransform

#include <VectorTransform.h>

对一组向量应用主成分分析，可以选择进行白化和随机旋转。

公共函数

explicit PCAMatrix(int d_in = 0, int d_out = 0, float eigen_power = 0, bool random_rotation = false)

virtual void train(idx_t n, const float *x) override

在 n 个向量上进行训练。如果 n < d_in，则特征向量矩阵将用 0 补全

void copy_from(const PCAMatrix &other)

复制预训练的 PCA 矩阵

void prepare_Ab()

在计算均值、PCAMat 和特征值后调用

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

与 apply 相同，但结果是预先分配的

void transform_transpose(idx_t n, const float *y, float *x) const

计算 x = A^T * (x - b)，如果 A 具有正交的行，则是反向变换

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

仅在 is_orthonormal 时有效

void set_is_orthonormal()

计算 A^T * A 以设置 is_orthonormal 标志

void print_if_verbose(const char *name, const std::vector<double> &mat, int n, int d) const

virtual void check_identical(const VectorTransform &other) const override

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

float eigen_power

变换后，组件乘以特征值^eigen_power

=0：不进行白化处理 =-0.5：完全白化处理

float epsilon

添加到特征值的值，以避免白化时除以 0

bool random_rotation

PCA 之后的随机旋转

size_t max_points_per_d

训练向量数与维度之间的比率

int balanced_bins

尝试将输出特征向量分配到这么多 bin 中

std::vector<float> mean

均值，大小为 d_in。

std::vector<float> eigenvalues

协方差矩阵的特征值（= 平方奇异值）

std::vector<float> PCAMat

PCA 矩阵，大小为 d_in * d_in。

bool have_bias

bool is_orthonormal

! 是否使用偏差项

检查矩阵A是否是正交的 (启用 reverse_transform)

std::vector<float> A

变换矩阵，大小为 d_out * d_in。

std::vector<float> b

偏差向量，大小为 d_out

bool verbose

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct ITQMatrix : public faiss::LinearTransform

#include <VectorTransform.h>

ITQ的实现来自

迭代量化：一种用于学习大规模图像检索的二进制码的 Procrustean 方法，

Yunchao Gong, Svetlana Lazebnik, Albert Gordo, Florent Perronnin, PAMI’12.

公共函数

explicit ITQMatrix(int d = 0)

virtual void train(idx_t n, const float *x) override

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

与 apply 相同，但结果是预先分配的

void transform_transpose(idx_t n, const float *y, float *x) const

计算 x = A^T * (x - b)，如果 A 具有正交的行，则是反向变换

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

仅在 is_orthonormal 时有效

void set_is_orthonormal()

计算 A^T * A 以设置 is_orthonormal 标志

void print_if_verbose(const char *name, const std::vector<double> &mat, int n, int d) const

virtual void check_identical(const VectorTransform &other) const override

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

int max_iter

int seed

std::vector<double> init_rotation

bool have_bias

bool is_orthonormal

! 是否使用偏差项

检查矩阵A是否是正交的 (启用 reverse_transform)

std::vector<float> A

变换矩阵，大小为 d_out * d_in。

std::vector<float> b

偏差向量，大小为 d_out

bool verbose

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct ITQTransform : public faiss::VectorTransform

#include <VectorTransform.h>

完整的 ITQ 变换，包括归一化和 PCA 变换

公共函数

explicit ITQTransform(int d_in = 0, int d_out = 0, bool do_pca = false)

virtual void train(idx_t n, const float *x) override

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

应用转换并在提供的矩阵中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

• xt – 输出向量，大小为 n * d_out

virtual void check_identical(const VectorTransform &other) const override

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

virtual void reverse_transform(idx_t n, const float *xt, float *x) const

反向变换。 可能未实现，或者可能返回近似结果。

公共成员

std::vector<float> mean

bool do_pca

ITQMatrix itq

int max_train_per_dim

每个维度的最大训练点数

LinearTransform pca_then_itq

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct OPQMatrix : public faiss::LinearTransform

#include <VectorTransform.h>

应用旋转以使维度与 PQ 对齐，从而最大限度地减少重建误差。可以在 IndexPQ 或 IndexIVFPQ 之前使用。该方法是中描述的非参数版本

“用于近似最近邻搜索的优化乘积量化”，Tiezheng Ge, Kaiming He, Qifa Ke, Jian Sun, CVPR’13

公共函数

explicit OPQMatrix(int d = 0, int M = 1, int d2 = -1)

如果 d2 != -1，则输出此维度的向量

virtual void train(idx_t n, const float *x) override

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

与 apply 相同，但结果是预先分配的

void transform_transpose(idx_t n, const float *y, float *x) const

计算 x = A^T * (x - b)，如果 A 具有正交的行，则是反向变换

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

仅在 is_orthonormal 时有效

void set_is_orthonormal()

计算 A^T * A 以设置 is_orthonormal 标志

void print_if_verbose(const char *name, const std::vector<double> &mat, int n, int d) const

virtual void check_identical(const VectorTransform &other) const override

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

int M

子量化器的数量

int niter = 50

外部训练迭代次数。

int niter_pq = 4

PQ 的训练迭代次数。

int niter_pq_0 = 40

同上，对于第一次外部迭代

size_t max_train_points = 256 * 256

如果训练点过多，则重新采样

bool verbose = false

ProductQuantizer *pq = nullptr

如果非 NULL，则使用此乘积量化器进行训练，应使用 (d_out, M, _) 构造

bool have_bias

bool is_orthonormal

! 是否使用偏差项

检查矩阵A是否是正交的 (启用 reverse_transform)

std::vector<float> A

变换矩阵，大小为 d_out * d_in。

std::vector<float> b

偏差向量，大小为 d_out

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct RemapDimensionsTransform : public faiss::VectorTransform

#include <VectorTransform.h>

重新映射输入向量的维度，可能插入 0。严格来说，这也是一种线性变换，但我们不想用矩阵乘法来计算它。

公共函数

RemapDimensionsTransform(int d_in, int d_out, const int *map)

RemapDimensionsTransform(int d_in, int d_out, bool uniform = true)

将输入重新映射到输出，根据需要跳过或插入维度。 如果 uniform 为真：则均匀分布维度；否则，只取前 d_out 个维度。

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

应用转换并在提供的矩阵中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

• xt – 输出向量，大小为 n * d_out

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

仅当映射是排列时，逆变换才是正确的

inline RemapDimensionsTransform()

virtual void check_identical(const VectorTransform &other) const override

virtual void train(idx_t n, const float *x)

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

std::vector<int> map

从输出维度到输入的映射，大小为 d_out -1 -> 将输出设置为 0

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct NormalizationTransform : public faiss::VectorTransform

#include <VectorTransform.h>

每个向量的归一化

公共函数

explicit NormalizationTransform(int d, float norm = 2.0)

NormalizationTransform()

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

应用转换并在提供的矩阵中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

• xt – 输出向量，大小为 n * d_out

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

由于范数不可逆，因此为恒等变换。

virtual void check_identical(const VectorTransform &other) const override

virtual void train(idx_t n, const float *x)

在代表性向量集上执行训练。默认情况下不执行任何操作。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

float norm

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

struct CenteringTransform : public faiss::VectorTransform

#include <VectorTransform.h>

从向量中减去每个分量的均值。

公共函数

explicit CenteringTransform(int d = 0)

virtual void train(idx_t n, const float *x) override

在 n 个向量上进行训练。

virtual void apply_noalloc(idx_t n, const float *x, float *xt) const override

减去均值

virtual void reverse_transform(idx_t n, const float *xt, float *x) const override

加上均值

virtual void check_identical(const VectorTransform &other) const override

float *apply(idx_t n, const float *x) const

应用转换并在已分配的指针中返回结果

参数：

• n – 要转换的向量的数量

• x – 输入向量，大小为 n * d_in

返回值：

输出向量，大小为 n * d_out

公共成员

std::vector<float> mean

均值，大小为 d_in = d_out。

int d_in

int d_out

! 输入维度

bool is_trained

设置VectorTransform是否需要训练，或者是否已经完成训练

namespace cppcontrib

函数

bool isBigEndian()

template<intptr_t DIM, intptr_t COARSE_SIZE, intptr_t FINE_SIZE, intptr_t COARSE_BITS = 8, intptr_t FINE_BITS = 8>
struct Index2LevelDecoder

#include <Level2-inl.h>

Index2LevelDecoder.

公共类型

using coarse_storage_type = typename detail::CoarseBitType<COARSE_BITS>::bit_type

公共静态函数

static inline void store (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqCoarseCentroids2, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void store (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqCoarseCentroids2, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void store (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqCoarseCentroids2, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

公共静态属性

static constexpr intptr_t dim = DIM

static constexpr intptr_t coarseSize = COARSE_SIZE

static constexpr intptr_t fineSize = FINE_SIZE

static constexpr intptr_t coarseBits = COARSE_BITS

static constexpr intptr_t fineBits = FINE_BITS

static constexpr intptr_t COARSE_TABLE_BYTES = (1 << COARSE_BITS)

static constexpr intptr_t FINE_TABLE_BYTES = (1 << FINE_BITS)

template<typename SubIndexT>
struct IndexMinMaxDecoder

公共静态函数

static inline void store (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void store (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqCoarseCentroids2, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

公共静态属性

static constexpr intptr_t dim = SubIndexT::dim

template<typename SubIndexT>
struct IndexMinMaxFP16Decoder

公共静态函数

static inline void store (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void store (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids0, const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqCoarseCentroids1, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqCoarseCentroids2, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqCoarseCentroids, const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum, float &minvAccum)

公共静态属性

static constexpr intptr_t dim = SubIndexT::dim

template<intptr_t DIM, intptr_t FINE_SIZE, intptr_t FINE_BITS = 8>
struct IndexPQDecoder

#include <PQ-inl.h>

IndexPQDecoder.

公共静态函数

static inline void store (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void store (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void store (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, float *const __restrict outputStore)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code, const float weight, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids0, const uint8_t *const __restrict code0, const float weight0, const float *const __restrict pqFineCentroids1, const uint8_t *const __restrict code1, const float weight1, const float *const __restrict pqFineCentroids2, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

static inline void accum (const float *const __restrict pqFineCentroids, const uint8_t *const __restrict code0, const float weight0, const uint8_t *const __restrict code1, const float weight1, const uint8_t *const __restrict code2, const float weight2, float *const __restrict outputAccum)

公共静态属性

static constexpr intptr_t dim = DIM

static constexpr intptr_t fineSize = FINE_SIZE

static constexpr intptr_t fineBits = FINE_BITS

static constexpr intptr_t FINE_TABLE_BYTES = (1 << FINE_BITS)

namespace detail

类型定义

template<intptr_t DIM, intptr_t CODE_SIZE, intptr_t CODE_BITS, intptr_t CPOS>
using UintReader = typename UintReaderImplType<维度 / 代码大小, 代码位数, CPOS>::reader_type

template<intptr_t N_ELEMENTS, intptr_t CODE_BITS, intptr_t CPOS>
using UintReaderRaw = typename UintReaderImplType<N_ELEMENTS, CODE_BITS, CPOS>::reader_type

template<int COARSE_BITS>
struct CoarseBitType

template<>
struct CoarseBitType<8>

公共类型

using bit_type = uint8_t

template<>
struct CoarseBitType<16>

公共类型

using bit_type = uint16_t

namespace detail

namespace simdlib

类型定义

template<typename T>
using remove_cv_ref_t = typename std::remove_reference<typename std::remove_cv<T>::type>::type

函数

static inline uint8x16x2_t reinterpret_u8(const uint8x16x2_t &v)

static inline uint8x16x2_t reinterpret_u8(const uint16x8x2_t &v)

static inline uint8x16x2_t reinterpret_u8(const uint32x4x2_t &v)

static inline uint8x16x2_t reinterpret_u8(const float32x4x2_t &v)

static inline uint16x8x2_t reinterpret_u16(const uint8x16x2_t &v)

static inline uint16x8x2_t reinterpret_u16(const uint16x8x2_t &v)

static inline uint16x8x2_t reinterpret_u16(const uint32x4x2_t &v)

static inline uint16x8x2_t reinterpret_u16(const float32x4x2_t &v)

static inline uint32x4x2_t reinterpret_u32(const uint8x16x2_t &v)

静态 内联 uint32x4x2_t reinterpret_u32(const uint16x8x2_t &v)

静态 内联 uint32x4x2_t reinterpret_u32(const uint32x4x2_t &v)

静态 内联 uint32x4x2_t reinterpret_u32(const float32x4x2_t &v)

静态 内联 float32x4x2_t reinterpret_f32(const uint8x16x2_t &v)

静态 内联 float32x4x2_t reinterpret_f32(const uint16x8x2_t &v)

静态 内联 float32x4x2_t reinterpret_f32(const uint32x4x2_t &v)

静态 内联 float32x4x2_t reinterpret_f32(const float32x4x2_t &v)

静态 内联 ::uint16x8_t vdupq_n_u16(std::uint16_t v)

静态 内联 ::uint8x16_t vdupq_n_u8(std::uint8_t v)

静态 内联 void bin(const char (&bytes)[32], char bits[257])

模板<typename T, size_t N, typename S>
静态 内联 void bin(const S &simd, char bits[257])

模板<typename S>
静态 内联 std::string bin(const S &simd)

template<typename D, typename T>
static inline set1_impl<remove_cv_ref_t<D>, T> set1(D &d, T t)

template<typename T, size_t N, typename S>
static inline std::string elements_to_string(const char *fmt, const S &simd)

template<typename T>
static inline unary_func_impl<remove_cv_ref_t<T>, remove_cv_ref_t<T>> unary_func(const T &a)

template<typename T, typename U>
static inline unary_func_impl<remove_cv_ref_t<T>, remove_cv_ref_t<U>> unary_func(const U &a)

template<typename T>
static inline binary_func_impl<remove_cv_ref_t<T>, remove_cv_ref_t<T>> binary_func(const T &a, const T &b)

template<typename T, typename U>
静态 inline binary_func_impl<remove_cv_ref_t<T>, remove_cv_ref_t<U>> binary_func(const U &a, const U &b)

static inline uint16_t vmovmask_u8(const uint8x16_t &v)

template<uint16x8_t (*F)(uint16x8_t, uint16x8_t)>
static inline uint32_t cmp_xe32(const uint16x8x2_t &d0, const uint16x8x2_t &d1, const uint16x8x2_t &thr)

template<std::uint8_t Shift>
static inline uint16x8_t vshlq(uint16x8_t vec)

template<std::uint8_t Shift>
static inline uint16x8_t vshrq(uint16x8_t vec)

template<typename T, typename U = decltype(reinterpret_u8(std::declval<T>().data))>
struct is_simd256bit : public std::is_same<decltype(reinterpret_u8(std::declval<T>().data)), uint8x16x2_t>

template<typename D, typename T>
struct set1_impl

公共函数

template<remove_cv_ref_t<decltype(std::declval<D>().val[0])> (*F)(T)>
inline void call()

公共成员

D &d

T t

template<typename T, typename U>
struct unary_func_impl

公共类型

using Telem = remove_cv_ref_t<decltype(std::declval<T>().val[0])>

using Uelem = remove_cv_ref_t<decltype(std::declval<U>().val[0])>

公共函数

template<Telem (*F)(Uelem)>
inline T call()

公共成员

const U &a

template<typename T, typename U>
struct binary_func_impl

公共类型

using Telem = remove_cv_ref_t<decltype(std::declval<T>().val[0])>

using Uelem = remove_cv_ref_t<decltype(std::declval<U>().val[0])>

公共函数

template<Telem (*F)(Uelem, Uelem)>
inline T call()

公共成员

const U &a

const U &b

namespace gpu

枚举

enum class DistanceDataType

值

enumerator F32

enumerator F16

enumerator BF16

enum class IndicesDataType

值

enumerator I64

enumerator I32

enum class graph_build_algo

值

enumerator IVF_PQ

使用 IVF-PQ 构建所有邻居的 knn 图。

enumerator NN_DESCENT

使用 NN-Descent 构建所有邻居的 knn 图。

enum class codebook_gen

用于指定如何创建 PQ 码本的类型。

值

enumerator PER_SUBSPACE

enumerator PER_CLUSTER

enum class search_algo

值

enumerator SINGLE_CTA

适用于大批量大小。

enumerator MULTI_CTA

适用于小批量大小。

enumerator MULTI_KERNEL

enumerator AUTO

enum class hash_mode

值

enumerator HASH

enumerator SMALL

enumerator AUTO

enum IndicesOptions

用户向量索引数据在 GPU 上的存储方式。

值

enumerator INDICES_CPU

用户索引仅存储在 CPU 上；GPU 将（倒排列表，偏移量）返回给 CPU，然后将其转换为实际的用户索引。

enumerator INDICES_IVF

索引根本不存储，无论是在 CPU 还是 GPU 上。 仅将（倒排列表，偏移量）作为索引返回给用户。

enumerator INDICES_32_BIT

索引作为 32 位整数存储在 GPU 上，但作为 64 位整数返回

enumerator INDICES_64_BIT

索引作为 64 位整数存储在 GPU 上。

enum AllocType

值

enumerator Other

未知分配类型或杂项（当前未分类）

enumerator FlatData

GpuIndexFlat 的主数据存储（向量的原始矩阵和向量范数，如果需要）

enumerator IVFLists

GpuIndexIVF* 的主数据存储（每个单独的 IVF 列表的存储）

enumerator Quantizer

Quantizer (PQ, SQ) 字典信息。

enumerator QuantizerPrecomputedCodes

对于 GpuIndexIVFPQ，更高效的 PQ 查找的“预计算代码”需要使用可能很大的表。 这些与 Quantizer 分开标记，因为它们通常大小为 100s - 1000s MiB

enumerator TemporaryMemoryBuffer

当使用 StandardGpuResources 时，StandardGpuResources 实现特定类型。 临时内存分配 (MemorySpace::Temporary) 来自于预先为每个 GPU 分配的堆栈内存区域（例如，初始化时为 1.5 GiB）。StandardGpuResources 的这种分配使用此 AllocType 进行标记。

枚举器 TemporaryMemoryOverflow

当使用 StandardGpuResources 时，任何无法在 TemporaryMemoryBuffer 区域内满足的 MemorySpace::Temporary 分配都会退回到调用 cudaMalloc，cudaMalloc 的大小正好满足手头的请求。 这些“溢出”临时分配使用此 AllocType 进行标记。

枚举 MemorySpace

GPU 可访问的内存区域。

值

枚举器 Temporary

临时设备内存（保证在顶级索引调用退出时不再使用，并且使用它的流已完成 GPU 工作）。 通常由设备内存（cudaMalloc/cudaFree）支持。

枚举器 Device

使用 cudaMalloc/cudaFree 进行管理（典型的 GPU 设备内存）

枚举器 Unified

使用 cudaMallocManaged/cudaFree 进行管理（典型的统一 CPU/GPU 内存）

函数

faiss::Index *index_gpu_to_cpu(const faiss::Index *gpu_index)

将 gpu_index 中的任何 GPU 索引转换为 CPU 索引

faiss::Index *index_cpu_to_gpu(GpuResourcesProvider *provider, int device, const faiss::Index *index, const GpuClonerOptions *options = nullptr)

转换任何可以转换为 GPU 的 CPU 索引

faiss::Index *index_cpu_to_gpu_multiple(std::vector<GpuResourcesProvider*> &provider, std::vector<int> &devices, const faiss::Index *index, const GpuMultipleClonerOptions *options = nullptr)

faiss::IndexBinary *index_binary_gpu_to_cpu(const faiss::IndexBinary *gpu_index)

faiss::IndexBinary *index_binary_cpu_to_gpu(GpuResourcesProvider *provider, int device, const faiss::IndexBinary *index, const GpuClonerOptions *options = nullptr)

转换任何可以转换为 GPU 的 CPU 索引

faiss::IndexBinary *index_binary_cpu_to_gpu_multiple(std::vector<GpuResourcesProvider*> &provider, std::vector<int> &devices, const faiss::IndexBinary *index, const GpuMultipleClonerOptions *options = nullptr)

bool should_use_cuvs(GpuDistanceParams args)

一个函数，用于确定是否应基于各种条件（例如不支持的架构）使用 cuVS。

void bfKnn(GpuResourcesProvider *resources, const GpuDistanceParams &args)

gpu/impl/Distance.cuh 的一个封装器，用于公开在外部提供的内存区域（例如，来自 pytorch 张量）上直接进行暴力 k 近邻搜索。数据（向量、查询、outDistances、outIndices）可以驻留在 GPU 或 CPU 上，但所有计算都在 GPU 上执行。如果结果缓冲区位于 CPU 上，则完成后会将结果复制回来。

所有 GPU 计算都在当前的 CUDA 设备上执行，并且根据 resources->getDefaultStreamCurrentDevice() 排序。

对于 queries 中的每个向量，搜索所有 vectors 以找到其相对于给定度量的 k 个最近邻居

void bfKnn_tiling(GpuResourcesProvider *resources, const GpuDistanceParams &args, size_t vectorsMemoryLimit, size_t queriesMemoryLimit)

void bruteForceKnn(GpuResourcesProvider *resources, faiss::MetricType metric, const float *vectors, bool vectorsRowMajor, idx_t numVectors, const float *queries, bool queriesRowMajor, idx_t numQueries, int dims, int k, float *outDistances, idx_t *outIndices)

已弃用的旧实现。

bool should_use_cuvs(GpuIndexConfig config_)

一个集中式函数，用于根据各种条件（例如不支持的架构）确定是否应使用 cuVS

GpuIndex *tryCastGpuIndex(faiss::Index *index)

如果给定的索引是 GPU 索引，则此函数返回索引实例。

bool isGpuIndex(faiss::Index *index)

给定的索引实例是 GPU 索引吗？

bool isGpuIndexImplemented(faiss::Index *index)

给定的 CPU 索引实例是否具有对应的 GPU 实现？

std::string allocTypeToString(AllocType t)

将 AllocType 转换为字符串。

std::string memorySpaceToString(MemorySpace s)

将 MemorySpace 转换为字符串。

AllocInfo makeDevAlloc(AllocType at, cudaStream_t st)

使用 MemorySpace::Device 为当前设备创建 AllocInfo。

AllocInfo makeTempAlloc(AllocType at, cudaStream_t st)

使用 MemorySpace::Temporary 为当前设备创建 AllocInfo。

AllocInfo makeSpaceAlloc(AllocType at, MemorySpace sp, cudaStream_t st)

为当前设备创建 AllocInfo。

int getMaxKSelection()

索引实现的各种实用函数的集合。

返回基于我们编译时使用的 CUDA SDK 支持的最大 k 选择值。.cu 文件可以使用 DeviceDefs.cuh，但这适用于非 CUDA 文件

void validateKSelect(int k)

void validateNProbe(size_t nprobe)

std::vector<uint8_t> unpackNonInterleaved(std::vector<uint8_t> data, int numVecs, int dims, int bitsPerCode)

std::vector<uint8_t> unpackInterleaved(std::vector<uint8_t> data, int numVecs, int dims, int bitsPerCode)

std::vector<uint8_t> packNonInterleaved(std::vector<uint8_t> data, int numVecs, int dims, int bitsPerCode)

std::vector<uint8_t> packInterleaved(std::vector<uint8_t> data, int numVecs, int dims, int bitsPerCode)

void ivfOffsetToUserIndex(idx_t *indices, idx_t numLists, idx_t queries, int k, const std::vector<std::vector<idx_t>> &listOffsetToUserIndex)

Utility function to translate (list id, offset) to a user index on the CPU. In a cpp in order to use OpenMP.

void newTestSeed()

Generates and displays a new seed for the test.

void setTestSeed(long seed)

Uses an explicit seed for the test.

float relativeError(float a, float b)

Returns the relative error in difference between a and b (|a - b| / (0.5 * (|a| + |b|))

int randVal(int a, int b)

Generates a random integer in the range [a, b].

bool randBool()

Generates a random bool.

template<typename T>
T randSelect(std::initializer_list<T> vals)

Select a random value from the given list of values provided as an initializer_list

std::vector<float> randVecs(size_t num, size_t dim)

Generates a collection of random vectors in the range [0, 1].

std::vector<unsigned char> randBinaryVecs(size_t num, size_t dim)

Generates a collection of random bit vectors.

std::vector<float> roundToHalf(const std::vector<float> &v)

void compareIndices(const std::vector<float> &queryVecs, faiss::Index &refIndex, faiss::Index &testIndex, int numQuery, int dim, int k, const std::string &configMsg, float maxRelativeError = 6e-5f, float pctMaxDiff1 = 0.1f, float pctMaxDiffN = 0.005f)

通过查询比较两个索引的相似度，使用用户指定的一组查询向量

void compareIndices(faiss::Index &refIndex, faiss::Index &testIndex, int numQuery, int dim, int k, const std::string &configMsg, float maxRelativeError = 6e-5f, float pctMaxDiff1 = 0.1f, float pctMaxDiffN = 0.005f)

通过查询比较两个索引的相似度，生成随机查询向量

void compareLists(const float *refDist, const faiss::idx_t *refInd, const float *testDist, const faiss::idx_t *testInd, int dim1, int dim2, const std::string &configMsg, bool printBasicStats, bool printDiffs, bool assertOnErr, float maxRelativeError = 6e-5f, float pctMaxDiff1 = 0.1f, float pctMaxDiffN = 0.005f)

显示两个（距离，索引）列表中的具体差异。

template<typename A, typename B>
void testIVFEquality(A &cpuIndex, B &gpuIndex)

对比 CPU 索引和 GPU 索引之间的 IVF 列表。

inline cuvsDistanceType metricFaissToCuvs(MetricType metric, bool exactDistance)

void validRowIndices(GpuResources *res, Tensor<float, 2, true> &vecs, bool *validRows)

识别包含非 NaN 值的矩阵行。 如果第 i 行包含 NaN 值，则 validRows[i] 为 false，否则为 true。

idx_t inplaceGatherFilteredRows(GpuResources *res, Tensor<float, 2, true> &vecs, Tensor<idx_t, 1, true> &indices)

滤除包含 NaN 值的矩阵行。 向量和索引会原地更新。

int getCurrentDevice()

返回当前线程本地 GPU 设备。

void setCurrentDevice(int device)

设置当前线程本地 GPU 设备。

int getNumDevices()

返回可用的 GPU 设备数量。

void profilerStart()

启动 CUDA 分析器（通过 SWIG 公开）

void profilerStop()

停止 CUDA 分析器（通过 SWIG 公开）

void synchronizeAllDevices()

将 CPU 与所有设备同步（相当于每个设备的 cudaDeviceSynchronize）

const cudaDeviceProp &getDeviceProperties(int device)

返回给定设备的缓存 cudaDeviceProp。

const cudaDeviceProp &getCurrentDeviceProperties()

返回当前设备的缓存 cudaDeviceProp。

int getMaxThreads(int device)

返回给定 GPU 设备可用的最大线程数

int getMaxThreadsCurrentDevice()

等效于 getMaxThreads(getCurrentDevice())

dim3 getMaxGrid(int device)

返回给定 GPU 设备的最大网格大小。

dim3 getMaxGridCurrentDevice()

等效于 getMaxGrid(getCurrentDevice())

size_t getMaxSharedMemPerBlock(int device)

返回给定 GPU 设备可用的最大 smem。

size_t getMaxSharedMemPerBlockCurrentDevice()

等效于 getMaxSharedMemPerBlock(getCurrentDevice())

int getDeviceForAddress(const void *p)

对于给定的指针，返回它是否位于设备上（deviceId >= 0）或主机上（-1）。

bool getFullUnifiedMemSupport(int device)

给定设备是否支持完全统一内存共享主机内存？

bool getFullUnifiedMemSupportCurrentDevice()

等同于 getFullUnifiedMemSupport(getCurrentDevice())

bool getTensorCoreSupport(int device)

给定设备是否支持 Tensor Core 操作？

bool getTensorCoreSupportCurrentDevice()

等同于 getTensorCoreSupport(getCurrentDevice())

int getWarpSize(int device)

返回给定 GPU 设备的 warp 大小。

int getWarpSizeCurrentDevice()

等同于 getWarpSize(getCurrentDevice())

size_t getFreeMemory(int device)

返回给定设备上当前可用的内存量。

size_t getFreeMemoryCurrentDevice()

等同于 getFreeMemory(getCurrentDevice())

template<typename L1, typename L2>
void streamWaitBase(const L1 &listWaiting, const L2 &listWaitOn)

调用以使一组流等待。

template<typename L1>
void streamWait(const L1 &a, const std::initializer_list<cudaStream_t> &b)

这些版本允许使用 initializer_list 作为参数，因为否则 {…} 没有类型

template<typename L2>
void streamWait(const std::initializer_list<cudaStream_t> &a, const L2 &b)

inline void streamWait(const std::initializer_list<cudaStream_t> &a, const std::initializer_list<cudaStream_t> &b)

struct GpuParameterSpace : public faiss::ParameterSpace

#include <GpuAutoTune.h>

用于 GPU 索引的参数空间和设置器

公共函数

virtual void initialize(const faiss::Index *index) override

使用索引的合理参数进行初始化

virtual void set_index_parameter(faiss::Index *index, const std::string &name, double val) const override

在索引上设置参数组合

size_t n_combinations() const

组合数，= 值大小的乘积

bool combination_ge(size_t c1, size_t c2) const

返回元组意义上组合 c1 >= c2 是否成立

std::string combination_name(size_t cno) const

获取组合的字符串表示形式

void display() const

在 stdout 上打印描述

ParameterRange &add_range(const std::string &name)

添加新参数（如果存在，则返回它）

void set_index_parameters(Index *index, size_t cno) const

在索引上设置参数组合

void set_index_parameters(Index *index, const char *param_string) const

设置由字符串描述的参数组合

void update_bounds(size_t cno, const OperatingPoint &op, double *upper_bound_perf, double *lower_bound_t) const

对于给定的另一个操作点op，找到配置cno的性能上限和t的下限

void explore(Index *index, size_t nq, const float *xq, const AutoTuneCriterion &crit, OperatingPoints *ops) const

探索操作点

参数：

• index – 要运行的索引

• xq – 查询向量 (大小 nq * index.d)

• crit – 选择标准

• ops – 结果操作点

公共成员

std::vector<ParameterRange> parameter_ranges

所有可调参数

int verbose

探索期间的详细程度

int n_experiments

优化期间的实验次数 (0 = 尝试所有组合)

size_t batchsize

一次提交的最大查询数。

bool thread_over_batches

在批处理中使用多线程（用于基准测试独立的单次搜索很有用）

double min_test_duration

多次运行测试，直到它们至少达到此持续时间（以避免 MT 模式下的抖动）

struct ToCPUCloner : public faiss::Cloner

#include <GpuCloner.h>

为 GPU -> CPU 特制的Cloner。

公共函数

void merge_index(Index *dst, Index *src, bool successive_ids)

virtual Index *clone_Index(const Index *index) override

virtual VectorTransform *clone_VectorTransform(const VectorTransform*)

virtual IndexIVF *clone_IndexIVF(const IndexIVF*)

struct ToGpuCloner : public faiss::Cloner, public faiss::gpu::GpuClonerOptions

#include <GpuCloner.h>

Cloner 专门用于 CPU -> 1 GPU.

公共函数

ToGpuCloner(GpuResourcesProvider *prov, int device, const GpuClonerOptions &options)

virtual Index *clone_Index(const Index *index) override

virtual VectorTransform *clone_VectorTransform(const VectorTransform*)

virtual IndexIVF *clone_IndexIVF(const IndexIVF*)

公共成员

GpuResourcesProvider *provider

int device

IndicesOptions indicesOptions = INDICES_64_BIT

索引应该如何在支持索引的索引类型上存储（除了 GpuIndexFlat* 之外的任何东西）？

bool useFloat16CoarseQuantizer = false

粗量化器是否使用 float16？

bool useFloat16 = false

对于 GpuIndexIVFFlat, 存储是否使用 float16？ 对于 GpuIndexIVFPQ, 中间计算是否使用 float16？

bool usePrecomputed = false

使用预计算表？

long reserveVecs = 0

在 invfiles 中保留向量？

bool storeTransposed = false

对于 GpuIndexFlat, 以转置布局存储数据？

bool verbose = false

在索引上设置 verbose 选项。

bool use_cuvs = false

使用 cuVS 实现

bool allowCpuCoarseQuantizer = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

struct ToGpuClonerMultiple : public faiss::Cloner, public faiss::gpu::GpuMultipleClonerOptions

#include <GpuCloner.h>

专用于 CPU -> 多个 GPU 的 Cloner。

公共函数

ToGpuClonerMultiple(std::vector<GpuResourcesProvider*> &provider, std::vector<int> &devices, const GpuMultipleClonerOptions &options)

ToGpuClonerMultiple(const std::vector<ToGpuCloner> &sub_cloners, const GpuMultipleClonerOptions &options)

void copy_ivf_shard(const IndexIVF *index_ivf, IndexIVF *idx2, idx_t n, idx_t i)

Index *clone_Index_to_shards(const Index *index)

virtual Index *clone_Index(const Index *index) override

主要函数

virtual VectorTransform *clone_VectorTransform(const VectorTransform*)

virtual IndexIVF *clone_IndexIVF(const IndexIVF*)

公共成员

std::vector<ToGpuCloner> sub_cloners

bool shard = false

是否跨 GPU 分片索引，而不是跨 GPU 复制

int shard_type = 1

IndexIVF::copy_subset_to 子集类型。

bool common_ivf_quantizer = false

如果 IndexIVF 要分派到多个 GPU，且它们共享一个通用的 IVF 量化器（即，只有倒排列表在子索引上进行分片），则设置为 true（使用 IndexShardsIVF）。

IndicesOptions indicesOptions = INDICES_64_BIT

索引应该如何在支持索引的索引类型上存储（除了 GpuIndexFlat* 之外的任何东西）？

bool useFloat16CoarseQuantizer = false

粗量化器是否使用 float16？

bool useFloat16 = false

对于 GpuIndexIVFFlat, 存储是否使用 float16？ 对于 GpuIndexIVFPQ, 中间计算是否使用 float16？

bool usePrecomputed = false

使用预计算表？

long reserveVecs = 0

在 invfiles 中保留向量？

bool storeTransposed = false

对于 GpuIndexFlat, 以转置布局存储数据？

bool verbose = false

在索引上设置 verbose 选项。

bool use_cuvs = false

使用 cuVS 实现

bool allowCpuCoarseQuantizer = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

struct GpuProgressiveDimIndexFactory : public faiss::ProgressiveDimIndexFactory

#include <GpuCloner.h>

用于 ProgressiveDimClustering 对象的索引工厂。

公共函数

explicit GpuProgressiveDimIndexFactory(int ngpu)

virtual Index *operator()(int dim) override

所有权转移给调用者

virtual ~GpuProgressiveDimIndexFactory() override

公共成员

GpuMultipleClonerOptions options

std::vector<GpuResourcesProvider*> vres

std::vector<int> devices

int ncall

struct GpuClonerOptions

#include <GpuClonerOptions.h>

设置一些关于如何复制到 GPU 的选项

被 faiss::gpu::GpuMultipleClonerOptions, faiss::gpu::ToGpuCloner 继承

公共成员

索引选项 = INDICES_64_BIT

索引应该如何在支持索引的索引类型上存储（除了 GpuIndexFlat* 之外的任何东西）？

使用 Float16 粗量化器 = false

粗量化器是否使用 float16？

使用 Float16 = false

对于 GpuIndexIVFFlat, 存储是否使用 float16？ 对于 GpuIndexIVFPQ, 中间计算是否使用 float16？

使用预计算 = false

使用预计算表？

保留向量数 = 0

在 invfiles 中保留向量？

存储转置 = false

对于 GpuIndexFlat, 以转置布局存储数据？

详细模式 = false

在索引上设置 verbose 选项。

使用 cuvs = false

使用 cuVS 实现

允许 CPU 粗量化器 = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

GPU 多重克隆器选项

被 faiss::gpu::ToGpuClonerMultiple 继承

公共成员

分片 = false

是否跨 GPU 分片索引，而不是跨 GPU 复制

分片类型 = 1

IndexIVF::copy_subset_to 子集类型。

通用 IVF 量化器 = false

如果 IndexIVF 要分派到多个 GPU，且它们共享一个通用的 IVF 量化器（即，只有倒排列表在子索引上进行分片），则设置为 true（使用 IndexShardsIVF）。

索引选项 = INDICES_64_BIT

索引应该如何在支持索引的索引类型上存储（除了 GpuIndexFlat* 之外的任何东西）？

使用 Float16 粗量化器 = false

粗量化器是否使用 float16？

使用 Float16 = false

对于 GpuIndexIVFFlat, 存储是否使用 float16？ 对于 GpuIndexIVFPQ, 中间计算是否使用 float16？

使用预计算 = false

使用预计算表？

保留向量数 = 0

在 invfiles 中保留向量？

存储转置 = false

对于 GpuIndexFlat, 以转置布局存储数据？

详细模式 = false

在索引上设置 verbose 选项。

使用 cuvs = false

使用 cuVS 实现

允许 CPU 粗量化器 = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

GPU 距离参数

#include <GpuDistance.h>

用于暴力 GPU k 近邻搜索的参数。

公共成员

度量标准 = METRIC_L2

搜索参数：距离度量。

度量标准参数 = 0

搜索参数：距离度量参数（如果适用）。对于 metric == METRIC_Lp，这是 p 值

int k = 0

搜索参数：返回 k 个最近邻。如果提供的值为 -1，则报告所有成对距离，不进行 top-k 过滤。

int dims = 0

向量维度。

const void *vectors = nullptr

如果 vectorsRowMajor 为 true，则为 numVectors x dims，其中 dims 是最内层的；否则，为 dims x numVectors，其中 numVectors 是最内层的

DistanceDataType vectorType = DistanceDataType::F32

bool vectorsRowMajor = true

idx_t numVectors = 0

const float *vectorNorms = nullptr

向量 vectors 中每个向量的预计算 L2 范数，可以提前提供以加速 METRIC_L2 的计算

const void *queries = nullptr

如果 queriesRowMajor 为 true，则为 numQueries x dims，其中 dims 是最内层的；否则，为 dims x numQueries，其中 numQueries 是最内层的

DistanceDataType queryType = DistanceDataType::F32

bool queriesRowMajor = true

idx_t numQueries = 0

float *outDistances = nullptr

大小为 numQueries x k 的内存区域，其中 k 是最内层的（行优先），如果 k > 0，或者如果 k == -1，则为大小为 numQueries x numVectors 的内存区域

bool ignoreOutDistances = false

我们是否只关心报告的索引，而不是输出距离？如果 k == -1（所有成对距离）则不使用

IndicesDataType outIndicesType = IndicesDataType::I64

大小为 numQueries x k 的内存区域，其中 k 是最内层的（行优先）。如果 k == -1（所有成对距离）则不使用

void *outIndices = nullptr

int device = -1

搜索应该在哪个 GPU 设备上运行？ -1 表示使用当前的 CUDA 线程局部设备（通过 cudaGetDevice/cudaSetDevice）。否则，整数 0 <= device < numDevices 表示执行的设备

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIcmEncoder : public faiss::lsq::IcmEncoder

#include <GpuIcmEncoder.h>

在 GPU 上执行 LSQ 编码。

将输入向量拆分到不同的设备并调用 IcmEncoderImpl::encode 对其进行编码

公共函数

GpuIcmEncoder(const LocalSearchQuantizer *lsq, const std::vector<GpuResourcesProvider*> &provs, const std::vector<int> &devices)

~GpuIcmEncoder()

GpuIcmEncoder(const GpuIcmEncoder&) = delete

GpuIcmEncoder &operator=(const GpuIcmEncoder&) = delete

virtual void set_binary_term() override

virtual void encode(int32_t *codes, const float *x, std::mt19937 &gen, size_t n, size_t ils_iters) const override

使用给定的码本编码向量

参数：

• codes – 输出代码，大小为 n * M

• x – 要编码的向量，大小为 n * d

• gen – 随机生成器

• n – 向量的数量

• ils_iters – 迭代局部搜索的迭代次数

公共成员

std::vector<float> binaries

bool verbose

const LocalSearchQuantizer *lsq

私有成员

std::unique_ptr<IcmEncoderShards> shards

struct GpuIcmEncoderFactory : public faiss::lsq::IcmEncoderFactory

公共函数

explicit GpuIcmEncoderFactory(int ngpus = 1)

virtual lsq::IcmEncoder *get(const LocalSearchQuantizer *lsq) override

公共成员

std::vector<GpuResourcesProvider*> provs

std::vector<int> devices

struct GpuIndexConfig

继承自 faiss::gpu::GpuIndexBinaryFlatConfig, faiss::gpu::GpuIndexCagraConfig, faiss::gpu::GpuIndexFlatConfig, faiss::gpu::GpuIndexIVFConfig

公共成员

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIndex : public faiss::Index

继承自 faiss::gpu::GpuIndexCagra, faiss::gpu::GpuIndexFlat, faiss::gpu::GpuIndexIVF

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndex(std::shared_ptr<GpuResources> resources, int dims, faiss::MetricType metric, float metricArg, GpuIndexConfig config)

int getDevice() const

返回此索引所在的设备。

std::shared_ptr<GpuResources> getResources()

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

void setMinPagingSize(size_t size)

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

size_t getMinPagingSize() const

返回分页搜索的当前最小数据大小。

virtual void add(idx_t, const float *x) override

x 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void add_with_ids(idx_t n, const float *x, const idx_t *ids) override

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const override

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void compute_residual(const float *x, float *residual, idx_t key) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

计算 n 个向量的残差。

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

用给定的向量训练索引。

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reset() = 0

从数据库中删除所有元素。

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

受保护的函数

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

virtual bool addImplRequiresIDs_() const = 0

addImpl_ 是否需要 ID？如果是这样，并且未提供 ID，我们将根据添加 ID 的顺序按顺序生成它们

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) = 0

重写以实际执行添加 保证所有数据都驻留在我们的设备上

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const = 0

重写以实际执行搜索 保证所有数据都驻留在我们的设备上

受保护的属性

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_

我们的配置选项。

size_t minPagedSize_

从 CPU 到 GPU 的分页复制的大小阈值。

私有函数

void addPaged_(idx_t n, const float *x, const idx_t *ids)

如果添加集太大，则处理分页添加，传递给 addImpl_ 以实际执行当前页面的添加

void addPage_(idx_t n, const float *x, const idx_t *ids)

为 GPU 驻留数据的单个页面调用 addImpl_。

void searchNonPaged_(idx_t n, const float *x, int k, float *outDistancesData, idx_t *outIndicesData, const SearchParameters *params) const

为单个 GPU 常驻数据页调用 searchImpl_。

void searchFromCpuPaged_(idx_t n, const float *x, int k, float *outDistancesData, idx_t *outIndicesData, const SearchParameters *params) const

为单个 GPU 常驻数据页调用 searchImpl_，处理数据的分页和从 CPU 的复制

struct GpuIndexBinaryFlatConfig : public faiss::gpu::GpuIndexConfig

公共成员

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIndexBinaryFlat : public faiss::IndexBinary

#include <GpuIndexBinaryFlat.h>

一个 GPU 版本的 IndexBinaryFlat，用于通过汉明距离对位向量进行暴力比较

公共类型

using component_t = uint8_t

using distance_t = int32_t

公共函数

GpuIndexBinaryFlat(GpuResourcesProvider *resources, const faiss::IndexBinaryFlat *index, GpuIndexBinaryFlatConfig config = GpuIndexBinaryFlatConfig())

从预先存在的 faiss::IndexBinaryFlat 实例构建，将数据复制到给定的 GPU

GpuIndexBinaryFlat(GpuResourcesProvider *resources, int dims, GpuIndexBinaryFlatConfig config = GpuIndexBinaryFlatConfig())

构造一个可以添加的空实例。

~GpuIndexBinaryFlat() override

int getDevice() const

返回此索引所在的设备。

std::shared_ptr<GpuResources> getResources()

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

void copyFrom(const faiss::IndexBinaryFlat *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexBinaryFlat *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

virtual void add(faiss::idx_t n, const uint8_t *x) override

将维度为 d 的 n 个向量添加到索引。

向量被隐式地分配标签 ntotal .. ntotal + n - 1

参数：

x – 输入矩阵，大小为 n * d / 8

virtual void reset() override

从数据库中移除所有元素。

virtual void search(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, faiss::idx_t *labels, const faiss::SearchParameters *params = nullptr) const override

查询维度为 d 的 n 个向量到索引。

最多返回 k 个向量。 如果某个查询的结果不足，则结果数组将填充 -1。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

• distances – 输出成对距离，大小为 n*k

virtual void reconstruct(faiss::idx_t key, uint8_t *recons) const override

重建存储的向量。

对于某些索引，可能未定义此函数。

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小 d / 8）

virtual void train(idx_t n, const uint8_t *x)

对有代表性的向量集合执行训练。

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d / 8

virtual void add_with_ids(idx_t n, const uint8_t *x, const idx_t *xids)

与 add 相同，但存储 xids 而不是顺序 ids。

默认实现会因为断言而失败，因为它不被所有索引支持。

参数：

xids – 如果非空，则为向量存储的 ID (大小为 n)

virtual void range_search(idx_t n, const uint8_t *x, int radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询维度为 d 的 n 个向量到索引。

返回所有距离 < radius 的向量。请注意，许多索引不实现 range_search（只有 k-NN 搜索是强制性的）。距离被转换为 float 以重用 RangeSearchResult 结构，但它们是整数。按照惯例，只返回距离 < radius (严格比较) 的向量，即 radius = 0 不返回任何结果，1 只返回完全相同的向量。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• radius – 搜索半径

• result – 结果表

void assign(idx_t n, const uint8_t *x, idx_t *labels, idx_t k = 1) const

返回与查询向量 x 最接近的 k 个向量的索引。

此函数与 search 相同，但仅返回邻居的标签。

参数：

• x – 要搜索的输入向量，大小为 n * d / 8

• labels – 输出 NN 的标签，大小为 n*k

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。并非所有索引都支持。

virtual void reconstruct_n(idx_t i0, idx_t ni, uint8_t *recons) const

重建向量 i0 到 i0 + ni - 1。

对于某些索引，可能未定义此函数。

参数：

recons – 重建的向量（大小为 ni * d / 8）

virtual void search_and_reconstruct(idx_t n, const uint8_t *x, idx_t k, int32_t *distances, idx_t *labels, uint8_t *recons, const SearchParameters *params = nullptr) const

类似于搜索，但也重建了搜索结果的存储向量（或者是有损编码情况下的近似值）。

如果查询的结果不足，则生成的数组会用 -1 填充。

参数：

recons – 重建的向量大小 (n, k, d)

void display() const

显示实际的类名和更多信息。

virtual void merge_from(IndexBinary &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const IndexBinary &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

与IndexBinary的 add_with_ids 相同。

公共成员

int d = 0

向量维度

int code_size = 0

每个向量的字节数（= d / 8）

idx_t ntotal = 0

索引向量的总数

bool verbose = false

详细级别

bool is_trained = true

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type = METRIC_L2

此索引用于搜索的度量类型

受保护的函数

void searchFromCpuPaged_(idx_t n, const uint8_t *x, int k, int32_t *outDistancesData, idx_t *outIndicesData) const

从CPU上的输入数据进行搜索时调用；可能允许使用锁页内存

void searchNonPaged_(idx_t n, const uint8_t *x, int k, int32_t *outDistancesData, idx_t *outIndicesData) const

受保护的属性

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS句柄和暂存内存。

const GpuIndexBinaryFlatConfig binaryFlatConfig_

配置选项。

std::unique_ptr<BinaryFlatIndex> data_

保存包含向量列表的GPU数据。

struct IVFPQBuildCagraConfig

公共成员

uint32_t n_lists = 1024

倒排列表（簇）的数量

提示：每个簇的向量数（n_rows/n_lists）应大约为1,000到10,000。

uint32_t kmeans_n_iters = 20

搜索k-means中心（索引构建）的迭代次数。

double kmeans_trainset_fraction = 0.5

在迭代k-means构建期间使用的数据比例。

uint32_t pq_bits = 8

通过PQ压缩后，向量元素的位长度。

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

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

uint32_t pq_dim = 0

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

注意：pq_dim /// pq_bits 必须是 8 的倍数。

提示：较小的“pq_dim”会导致较小的索引大小和更好的搜索性能，但召回率较低。 如果“pq_bits”为 8，“pq_dim”可以设置为任何数字，但 8 的倍数对于良好的性能是可取的。 如果“pq_bits”不是 8，“pq_dim”应该是 8 的倍数。 为了获得良好的性能，“pq_dim”最好是 32 的倍数。 理想情况下，“pq_dim”也应该是数据集维度的除数。

codebook_gen codebook_kind = codebook_gen::PER_SUBSPACE

PQ码本的创建方式。

bool force_random_rotation = false

即使 dim % pq_dim == 0，也在输入数据和查询上应用随机旋转矩阵。

注意：如果 dim 不是 pq_dim 的倍数，则始终对输入数据和查询应用随机旋转，以将工作空间从 dim 转换为 rot_dim，后者可能略大于原始空间并且是 pq_dim 的倍数（rot_dim % pq_dim == 0）。 但是，当 dim 是 pq_dim 的倍数时，这种转换是不必要的（dim == rot_dim，因此不需要添加“额外的”数据列/特征）。

默认情况下，如果 dim == rot_dim，则使用单位矩阵初始化旋转变换。 当 force_random_rotation == true 时，无论 dim 和 pq_dim 的值如何，都会生成随机正交变换矩阵。

bool conservative_memory_allocation = false

默认情况下，该算法为各个集群（list_data）分配比必要更多的空间。 这样可以分摊内存分配的成本，并减少重复调用 extend（扩展数据库）期间的数据复制次数。

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

struct IVFPQSearchCagraConfig

公共成员

uint32_t n_probes = 20

要搜索的聚类数量。

cudaDataType_t lut_dtype = CUDA_R_32F

在搜索时动态创建的查找表的数据类型。

可能的值：[CUDA_R_32F, CUDA_R_16F, CUDA_R_8U]

使用低精度类型会减少搜索时所需的共享内存量，因此即使对于具有大维度的数据集，也可以使用快速共享内存内核。 请注意，选择低精度类型时，召回率会略有降低。

cudaDataType_t internal_distance_dtype = CUDA_R_32F

搜索时计算的距离/相似度的存储数据类型。

可能的值：[CUDA_R_16F, CUDA_R_32F]

如果搜索时的性能限制是设备内存访问，则选择 FP16 会略微提高性能。

double preferred_shmem_carveout = 1.0

要用作共享内存的 SM 统一内存/ L1 缓存的首选比例。

可能的值：[0.0 - 1.0]，作为 sharedMemPerMultiprocessor 的一部分。

人们希望增加 carveout 以确保主搜索内核具有良好的 GPU 占用率，但不要保持太高，以留下一些内存用作 L1 缓存。 请注意，此值仅被解释为提示。 此外，GPU 通常仅允许一组固定的缓存配置，因此提供的值将向上舍入到最接近的配置。 请参阅目标 GPU 架构的 NVIDIA 调整指南。

请注意，这是一个低级调整参数，如果调整不正确，可能会对搜索性能产生极大的负面影响。

struct GpuIndexCagraConfig : public faiss::gpu::GpuIndexConfig

公共成员

size_t intermediate_graph_degree = 128

用于修剪的输入图的度数。

size_t graph_degree = 64

输出图的度数。

graph_build_algo build_algo = graph_build_algo::IVF_PQ

用于构建 knn 图的 ANN 算法。

size_t nn_descent_niter = 20

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

IVFPQBuildCagraConfig *ivf_pq_params = nullptr

IVFPQSearchCagraConfig *ivf_pq_search_params = nullptr

float refine_rate = 2.0f

bool store_dataset = true

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

struct SearchParametersCagra : public faiss::SearchParameters

公共成员

size_t max_queries = 0

要同时搜索的最大查询数（批处理大小）。 0 时自动选择。

size_t itopk_size = 64

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

这是调整准确性和搜索速度之间权衡的主要旋钮。 较高的值可提高搜索准确性。

size_t max_iterations = 0

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

search_algo algo = search_algo::AUTO

要使用的搜索实现。

size_t team_size = 0

用于计算单个距离的线程数。 4、8、16 或 32。

size_t search_width = 1

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

size_t min_iterations = 0

搜索迭代次数的下限。

size_t thread_block_size = 0

线程块大小。 0、64、128、256、512、1024。 设为 0 时自动选择。

hash_mode hashmap_mode = hash_mode::AUTO

Hashmap 类型。 设置为 AUTO 时自动选择。

size_t hashmap_min_bitlen = 0

Hashmap 位长的下限。 大于 8。

float hashmap_max_fill_rate = 0.5

Hashmap 填充率的上限。 大于 0.1，小于 0.9。

uint32_t num_random_samplings = 1

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

uint64_t seed = 0x128394

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

IDSelector *sel = nullptr

如果非空，则仅在搜索期间考虑这些 ID。

struct GpuIndexCagra : public faiss::gpu::GpuIndex

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexCagra(GpuResourcesProvider *provider, int dims, faiss::MetricType metric = faiss::METRIC_L2, GpuIndexCagraConfig config = GpuIndexCagraConfig())

virtual void train(idx_t n, const float *x) override

根据给定的向量数据训练 CAGRA。

void copyFrom(const faiss::IndexHNSWCagra *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexHNSWCagra *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

virtual void reset() override

从数据库中删除所有元素。

std::vector<idx_t> get_knngraph() const

int getDevice() const

返回此索引所在的设备。

std::shared_ptr<GpuResources> getResources()

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

void setMinPagingSize(size_t size)

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

size_t getMinPagingSize() const

返回分页搜索的当前最小数据大小。

virtual void add(idx_t, const float *x) override

x 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void add_with_ids(idx_t n, const float *x, const idx_t *ids) override

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const override

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void compute_residual(const float *x, float *residual, idx_t key) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct( , )

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void ( , , )

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void ( , , )

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual ()

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual ()

生成的代码的大小（以字节为单位）

virtual void ( , , )

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void ( , , )

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void ( , )

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void ( )

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void ( , , )

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

受保护的函数

virtual bool addImplRequiresIDs_() const override

addImpl_ 是否需要 ID？如果是这样，并且未提供 ID，我们将根据添加 ID 的顺序按顺序生成它们

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) override

重写以实际执行添加 保证所有数据都驻留在我们的设备上

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *search_params) const override

从 GpuIndex 调用以进行搜索。

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

受保护的属性

const GpuIndexCagraConfig cagraConfig_

我们的配置选项。

std::shared_ptr<CuvsCagra> index_

我们拥有的实例；包含倒排列表。

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_

我们的配置选项。

size_t minPagedSize_

从 CPU 到 GPU 的分页复制的大小阈值。

struct GpuIndexFlatConfig : public faiss::gpu::GpuIndexConfig

公共函数

bool ALIGNED (8) useFloat16

数据是否以 float16 格式存储。

公共成员

bool storeTransposed = false

已弃用：不再使用。之前用于指示向量的内部存储是否已转置。

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIndexFlat : public faiss::gpu::GpuIndex

#include <GpuIndexFlat.h>

GPU 实现的包装器，外观类似于 faiss::IndexFlat；从给定的 faiss::IndexFlat 复制质心数据

由 faiss::gpu::GpuIndexFlatIP、faiss::gpu::GpuIndexFlatL2 继承

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexFlat(GpuResourcesProvider *provider, const faiss::IndexFlat *index, GpuIndexFlatConfig config = GpuIndexFlatConfig())

从预先存在的 faiss::IndexFlat 实例构造，将数据复制到给定的 GPU

GpuIndexFlat(std::shared_ptr<GpuResources> resources, const faiss::IndexFlat *index, GpuIndexFlatConfig config = GpuIndexFlatConfig())

GpuIndexFlat(GpuResourcesProvider *provider, int dims, faiss::MetricType metric, GpuIndexFlatConfig config = GpuIndexFlatConfig())

构造一个可以添加的空实例。

GpuIndexFlat(std::shared_ptr<GpuResources> resources, int dims, faiss::MetricType metric, GpuIndexFlatConfig config = GpuIndexFlatConfig())

~GpuIndexFlat() override

void copyFrom(const faiss::IndexFlat *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexFlat *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

size_t getNumVecs() const

返回我们包含的向量的数量。

virtual void reset() override

清除此索引中的所有向量。

virtual void train(idx_t n, const float *x) override

此索引未经训练，因此不执行任何操作。

virtual void add(idx_t, const float *x) override

重写以避免过度复制。

virtual void reconstruct(idx_t key, float *out) const override

重构方法; 优先使用批量重构，因为它会更有效

virtual void reconstruct_n(idx_t i0, idx_t num, float *out) const override

批量重构方法。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *out) const override

批量重构方法。

virtual void compute_residual(const float *x, float *residual, idx_t key) const override

计算残差。

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const override

计算残差（批量模式）

inline FlatIndex *getGpuData()

用于内部访问。

int getDevice() const

返回此索引所在的设备。

std::shared_ptr<GpuResources> getResources()

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

void setMinPagingSize(size_t size)

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

size_t getMinPagingSize() const

返回分页搜索的当前最小数据大小。

向索引添加向量，并提供对应的ID。

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

为每个查询向量分配k个最近的邻居。

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

搜索索引中的k个最近邻居。

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

搜索索引中的k个最近邻居，并返回重构向量。

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

搜索索引中位于指定半径内的所有邻居。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

从索引中移除具有指定ID的向量。

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

返回用于计算距离的距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

返回用于存储向量的编码大小（以字节为单位）。

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

受保护的函数

void resetIndex_(int dims)

virtual bool addImplRequiresIDs_() const override

Flat 索引不需要 ID，因为没有可用于存储它们的空间

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) override

从 GpuIndex 调用以进行添加。

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const override

从 GpuIndex 调用以进行搜索。

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

受保护的属性

const GpuIndexFlatConfig flatConfig_

我们的配置选项。

std::unique_ptr<FlatIndex> data_ 数据

保存包含向量列表的GPU数据。

std::shared_ptr<GpuResources> resources_ 资源

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_ 配置

我们的配置选项。

size_t minPagedSize_ 最小分页大小

从 CPU 到 GPU 的分页复制的大小阈值。

class GpuIndexFlatL2 : public faiss::gpu::GpuIndexFlat GpuIndexFlatL2 类：公共继承自 GpuIndexFlat。

#include <GpuIndexFlat.h>

围绕 GPU 实现的包装器，外观类似于 faiss::IndexFlatL2；从给定的 faiss::IndexFlat 复制质心数据。

公共类型

using component_t = float 组件类型 = float

using distance_t = float 距离类型 = float

公共函数

GpuIndexFlatL2(GpuResourcesProvider *provider, faiss::IndexFlatL2 *index, GpuIndexFlatConfig config = GpuIndexFlatConfig()) 从预先存在的 faiss::IndexFlatL2 实例构造，并将数据复制到给定的 GPU 上。

从预先存在的 faiss::IndexFlatL2 实例构造，并将数据复制到给定的 GPU 上

config: GpuIndexFlatConfig 对象，用于配置 GPU 索引的行为，默认为默认配置。

config: GpuIndexFlatConfig 对象，用于配置 GPU 索引的行为，默认为默认配置。

构造一个可以添加的空实例。

config: GpuIndexFlatConfig 对象，用于配置 GPU 索引的行为，默认为默认配置。

index: 指向 CPU IndexFlat 对象的指针。

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

index: 指向 CPU IndexFlat 对象的指针。

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

index: 指向 CPU IndexFlat 对象的常量指针。

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

index: 指向 CPU IndexFlat 对象的指针。

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

**返回值:** 索引中的向量数量。

返回我们包含的向量的数量。

**说明:** 重置索引，删除所有向量。

清除此索引中的所有向量。

x: 训练向量的指针。

此索引未经训练，因此不执行任何操作。

x: 要添加的向量的指针。

重写以避免过度复制。

out: 输出向量的指针。

重构方法; 优先使用批量重构，因为它会更有效

out: 输出向量的指针。

批量重构方法。

out: 输出向量的指针。

批量重构方法。

key: 索引中向量的键。

计算残差。

keys: 索引中向量的键的指针。

计算残差（批量模式）

指向 GPU 数据的指针。

用于内部访问。

设备 ID。

返回此索引所在的设备。

指向 GPU 资源的共享指针。

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

size: 最小分页大小。

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

获取最小分页大小

返回分页搜索的当前最小数据大小。

添加带有 ID 的向量。

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

将向量分配给最近的聚类中心。

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

搜索最近邻。

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

搜索最近邻并重构它们。

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

在指定半径内搜索近邻。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

移除符合 ID 选择器的向量。

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

获取快速近似（SA）编码的大小。

生成的代码的大小（以字节为单位）

使用快速近似（SA）编码对向量进行编码。

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

使用快速近似（SA）编码对向量进行解码。

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

合并索引。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查索引是否兼容以进行合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加 SA 代码。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

维度。

向量维度

向量的总数。

索引向量的总数

详细模式。

详细级别

是否已经训练过索引。

如果 Index 不需要训练，或者如果已经完成训练，则设置

度量类型。

此索引用于搜索的度量类型

度量参数。

度量类型的参数

受保护的函数

从另一个索引复制数据。

从 CPU 等效项复制我们需要的内容。

将数据复制到另一个索引。

将我们拥有的内容复制到 CPU 等效项。

重置索引，必要时重新分配内存。

addImpl 是否需要 ID。

Flat 索引不需要 ID，因为没有可用于存储它们的空间

添加向量到索引的实现。

从 GpuIndex 调用以进行添加。

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const override

从 GpuIndex 调用以进行搜索。

受保护的属性

const GpuIndexFlatConfig flatConfig_

我们的配置选项。

std::unique_ptr<FlatIndex> data_

保存包含向量列表的GPU数据。

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_

我们的配置选项。

size_t minPagedSize_

从 CPU 到 GPU 的分页复制的大小阈值。

class GpuIndexFlatIP : public faiss::gpu::GpuIndexFlat

#include <GpuIndexFlat.h>

GPU 实现的包装器，外观类似于 faiss::IndexFlatIP；从给定的 faiss::IndexFlat 复制质心数据

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexFlatIP(GpuResourcesProvider *provider, faiss::IndexFlatIP *index, GpuIndexFlatConfig config = GpuIndexFlatConfig())

从预先存在的 faiss::IndexFlatIP 实例构造，将数据复制到给定的 GPU

GpuIndexFlatIP(std::shared_ptr<GpuResources> resources, faiss::IndexFlatIP *index, GpuIndexFlatConfig config = GpuIndexFlatConfig())

GpuIndexFlatIP(GpuResourcesProvider *provider, int dims, GpuIndexFlatConfig config = GpuIndexFlatConfig())

构造一个可以添加的空实例。

GpuIndexFlatIP(std::shared_ptr<GpuResources> resources, int dims, GpuIndexFlatConfig config = GpuIndexFlatConfig())

void copyFrom(faiss::IndexFlat *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexFlat *index)

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

void copyFrom(const faiss::IndexFlat *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexFlat *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

size_t getNumVecs() const

返回我们包含的向量的数量。

virtual void reset() override

清除此索引中的所有向量。

virtual void train(idx_t n, const float *x) override

此索引未经训练，因此不执行任何操作。

virtual void add(idx_t, const float *x) override

重写以避免过度复制。

virtual void reconstruct(idx_t key, float *out) const override

重构方法; 优先使用批量重构，因为它会更有效

virtual void reconstruct_n(idx_t i0, idx_t num, float *out) const override

批量重构方法。

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *out) const override

批量重构方法。

virtual void compute_residual(const float *x, float *residual, idx_t key) const override

计算残差。

参数：

计算残差（批量模式）

返回：指向FlatIndex的指针。

用于内部访问。

返回：设备ID。

返回此索引所在的设备。

返回：指向GpuResources的共享指针。

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

参数：

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

返回：最小分页大小。

返回分页搜索的当前最小数据大小。

参数：

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

参数：

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

参数：

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

参数：

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

范围搜索（Range Search）。

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

移除 IDs。

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

获取 SA 码的大小。

生成的代码的大小（以字节为单位）

对 SA 码进行编码。

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

对 SA 码进行解码。

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

从另一个索引合并。

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查是否兼容以进行合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

添加 SA 码。

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

公共成员

维度。

向量维度

向量总数。

索引向量的总数

是否输出详细信息。

详细级别

是否已训练。

如果 Index 不需要训练，或者如果已经完成训练，则设置

度量类型。

此索引用于搜索的度量类型

度量参数。

度量类型的参数

受保护的函数

将索引复制到 GPU 索引。

从 CPU 等效项复制我们需要的内容。

将 GPU 索引复制到索引。

将我们拥有的内容复制到 CPU 等效项。

重置索引。

添加实现是否需要 ID。

Flat 索引不需要 ID，因为没有可用于存储它们的空间

添加实现。

从 GpuIndex 调用以进行添加。

搜索实现。

从 GpuIndex 调用以进行搜索。

受保护的属性

平面配置。

我们的配置选项。

数据。

保存包含向量列表的GPU数据。

资源。

管理设备的流、cuBLAS 句柄和暂存内存。

配置。

我们的配置选项。

最小分页大小。

从 CPU 到 GPU 的分页复制的大小阈值。

GPU IVF 索引配置。

被 faiss::gpu::GpuIndexIVFFlatConfig, faiss::gpu::GpuIndexIVFPQConfig, faiss::gpu::GpuIndexIVFScalarQuantizerConfig 继承

公共成员

GPU 的 Index 存储选项。

GPU 的 Index 存储选项。

粗量化器对象的配置。

粗量化器对象的配置。

是否允许 CPU 粗量化器。

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

设备 ID。

索引所在的 GPU 设备。

内存空间。

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

是否使用 cuvs。

索引是否应该分派到 cuVS？

class GpuIndexIVF : public faiss::gpu::GpuIndex, public faiss::IndexIVFInterface

#include <GpuIndexIVF.h>

所有 GPU IVF 索引类型的基类。目前，这故意不继承自 IndexIVF，因为 IndexIVF 中的许多公共数据成员和功能在 GPU 上不支持以相同的方式实现。

由 faiss::gpu::GpuIndexIVFFlat, faiss::gpu::GpuIndexIVFPQ, faiss::gpu::GpuIndexIVFScalarQuantizer 继承

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexIVF(GpuResourcesProvider *provider, int dims, faiss::MetricType metric, float metricArg, idx_t nlist, GpuIndexIVFConfig config = GpuIndexIVFConfig())

根据所需的指标自动构建一个平面粗量化器的版本

GpuIndexIVF(GpuResourcesProvider *provider, Index *coarseQuantizer, int dims, faiss::MetricType metric, float metricArg, idx_t nlist, GpuIndexIVFConfig config = GpuIndexIVFConfig())

获取粗量化器实例的版本。默认情况下，GpuIndexIVF 不拥有 coarseQuantizer 实例（例如 IndexIVF 这样的函数）。

~GpuIndexIVF() override

void copyFrom(const faiss::IndexIVF *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::IndexIVF *index) const

将我们拥有的内容复制到 CPU 等效项。

virtual void updateQuantizer() = 0

如果用户手动更改 IVF 粗量化器的状态（例如，替换一个新的实例或在训练范围之外更改粗量化器中的向量），则应调用此方法

virtual idx_t getNumLists() const

返回我们正在管理的倒排列表的数量。

virtual idx_t getListLength(idx_t listId) const

返回特定倒排列表中存在的向量数量。

virtual std::vector<uint8_t> getListVectorData(idx_t listId, bool gpuFormat = false) const

返回特定倒排列表中包含的编码向量数据，用于调试目的。如果gpuFormat为true，则数据以GPU端表示形式进行编码后返回。否则，将其转换为CPU格式。兼容格式，而原生GPU格式可能有所不同。

virtual std::vector<idx_t> getListIndices(idx_t listId) const

返回特定倒排列表中包含的向量索引，用于调试目的。

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const SearchParametersIVF *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

int getDevice() const

返回此索引所在的设备。

std::shared_ptr<GpuResources> getResources()

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

void setMinPagingSize(size_t size)

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

size_t getMinPagingSize() const

返回分页搜索的当前最小数据大小。

virtual void add(idx_t, const float *x) override

x 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void add_with_ids(idx_t n, const float *x, const idx_t *ids) override

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

将向量分配到倒排列表。

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

搜索最近邻。

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void compute_residual(const float *x, float *residual, idx_t key) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void train(idx_t n, const float *x)

在一组具有代表性的向量上执行训练

参数：

• n – 训练向量的数量

• x – 训练向量，大小为 n * d

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual void reset() = 0

从数据库中删除所有元素。

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

重建一批指定向量。

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

重建从 i0 开始的 ni 个向量。

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

获取距离计算器。

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

获取存储附加向量的代码的大小 (以字节为单位)。

生成的代码的大小（以字节为单位）

对存储的附加向量进行编码。

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

对存储的附加向量进行解码。

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

检查两个索引是否兼容以进行合并。

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

训练一级量化器。

训练量化器并调用 train_residual 来训练子量化器。

返回粗糙量化器的代码大小。

计算存储列表 ID 所需的字节数

对列表编号进行编码。

从代码中解码列表编号。

公共成员

向量维度。

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

受保护的函数

int getCurrentNProbe_(const SearchParameters *params) const

无论是从当前设置的 nprobe 还是从可用的 SearchParameters，都返回应该用于当前搜索的 nprobe。

void verifyIVFSettings_() const

virtual bool addImplRequiresIDs_() const override

addImpl_ 是否需要 ID？如果是这样，并且未提供 ID，我们将根据添加 ID 的顺序按顺序生成它们

virtual void trainQuantizer_(idx_t n, const float *x)

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) override

从 GpuIndex 调用，用于 add/add_with_ids。

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const override

从 GpuIndex 调用以进行搜索。

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

受保护的属性

const GpuIndexIVFConfig ivfConfig_

我们的配置选项。

std::shared_ptr<IVFBase> baseIndex_

对于已训练/初始化的索引，这是对基类的引用。

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_

我们的配置选项。

size_t minPagedSize_

从 CPU 到 GPU 的分页复制的大小阈值。

私有函数

void init_()

共享初始化函数。

struct GpuIndexIVFFlatConfig : public faiss::gpu::GpuIndexIVFConfig

公共成员

bool interleavedLayout = true

为IVF列表使用备用内存布局（目前是默认布局）

IndicesOptions indicesOptions = INDICES_64_BIT

GPU 的 Index 存储选项。

GpuIndexFlatConfig flatConfig

粗量化器对象的配置。

bool allowCpuCoarseQuantizer = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIndexIVFFlat : public faiss::gpu::GpuIndexIVF

#include <GpuIndexIVFFlat.h>

GPU实现的包装器，外观类似于 faiss::IndexIVFFlat

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexIVFFlat(GpuResourcesProvider *provider, const faiss::IndexIVFFlat *index, GpuIndexIVFFlatConfig config = GpuIndexIVFFlatConfig())

从预先存在的 faiss::IndexIVFFlat 实例构造，如果输入索引已训练，则将数据复制到给定的 GPU。

GpuIndexIVFFlat(GpuResourcesProvider *provider, int dims, idx_t nlist, faiss::MetricType metric = faiss::METRIC_L2, GpuIndexIVFFlatConfig config = GpuIndexIVFFlatConfig())

构造一个新的实例，带有一个空的flat量化器；用户提供所需的IVF列表数量。

GpuIndexIVFFlat(GpuResourcesProvider *provider, Index *coarseQuantizer, int dims, idx_t nlist, faiss::MetricType metric = faiss::METRIC_L2, GpuIndexIVFFlatConfig config = GpuIndexIVFFlatConfig())

构造一个新的实例，带有一个提供的CPU或GPU粗量化器；用户提供所需的IVF列表数量。

~GpuIndexIVFFlat() override

void reserveMemory(size_t numVecs)

在我们的倒排列表中为这个数量的向量预留GPU内存。

void copyFrom(const faiss::IndexIVFFlat *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexIVFFlat *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

size_t reclaimMemory()

添加向量后，可以调用此方法来回收设备内存，使其恰好为所需的数量。 返回以字节为单位回收的空间

virtual void reset() override

清除所有倒排列表，但保留粗糙的质心信息

virtual void updateQuantizer() override

如果用户手动更改 IVF 粗量化器的状态（例如，替换一个新的实例或在训练范围之外更改粗量化器中的向量），则应调用此方法

virtual void train(idx_t n, const float *x) override

基于给定的向量数据训练粗量化器。

virtual void reconstruct_n(idx_t i0, idx_t n, float *out) const override

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

void copyFrom(const faiss::IndexIVF *index)

从 CPU 等效项复制我们需要的内容。

将索引复制到 faiss::IndexIVF。

将我们拥有的内容复制到 CPU 等效项。

获取列表数量。

返回我们正在管理的倒排列表的数量。

获取指定列表的长度。

返回特定倒排列表中存在的向量数量。

获取指定列表的向量数据。

返回特定倒排列表中包含的编码向量数据，用于调试目的。如果gpuFormat为true，则数据以GPU端表示形式进行编码后返回。否则，将其转换为CPU格式。兼容格式，而原生GPU格式可能有所不同。

获取指定列表的索引。

返回特定倒排列表中包含的向量索引，用于调试目的。

预分配搜索。

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

预分配范围搜索。

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

获取设备 ID。

返回此索引所在的设备。

获取 GPU 资源。

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

设置最小分页大小。

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

获取最小分页大小() const

返回分页搜索的当前最小数据大小。

虚拟 void add(idx_t, const float * x) 重写

x 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

虚拟 void add_with_ids(idx_t n, const float * x, const idx_t * ids) 重写

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

虚拟 void assign(idx_t n, const float * x, idx_t * labels, idx_t k = 1) const 重写

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

虚拟 void search(idx_t n, const float * x, idx_t k, float * distances, idx_t * labels, const SearchParameters * params = nullptr) const 重写

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

虚拟 void search_and_reconstruct(idx_t n, const float * x, idx_t k, float * distances, idx_t * labels, float * recons, const SearchParameters * params = nullptr) const 重写

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

虚拟 void compute_residual(const float * x, float * residual, idx_t key) const 重写

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

虚拟 void compute_residual_n(idx_t n, const float * xs, float * residuals, const idx_t * keys) const 重写

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

受保护的函数

void setIndex_(GpuResources *resources, int dim, int nlist, faiss::MetricType metric, float metricArg, bool useResidual, faiss::ScalarQuantizer *scalarQ, bool interleavedLayout, IndicesOptions indicesOptions, MemorySpace space)

初始化合适的索引。

参数：

scalarQ – 可选的 ScalarQuantizer

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

int getCurrentNProbe_(const SearchParameters *params) const

无论是从当前设置的 nprobe 还是从可用的 SearchParameters，都返回应该用于当前搜索的 nprobe。

void verifyIVFSettings_() const

virtual bool addImplRequiresIDs_() const override

addImpl_ 是否需要 ID？如果是这样，并且未提供 ID，我们将根据添加 ID 的顺序按顺序生成它们

virtual void trainQuantizer_(idx_t n, const float *x)

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) override

从 GpuIndex 调用，用于 add/add_with_ids。

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const override

从 GpuIndex 调用以进行搜索。

受保护的属性

const GpuIndexIVFFlatConfig ivfFlatConfig_

我们的配置选项。

size_t reserveMemoryVecs_

期望的反向列表内存预留。

std::shared_ptr<IVFFlat> index_

我们拥有的实例；包含倒排列表。

const GpuIndexIVFConfig ivfConfig_

我们的配置选项。

std::shared_ptr<IVFBase> baseIndex_

对于已训练/初始化的索引，这是对基类的引用。

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_

我们的配置选项。

size_t minPagedSize_

从 CPU 到 GPU 的分页复制的大小阈值。

struct GpuIndexIVFPQConfig : public faiss::gpu::GpuIndexIVFConfig

公共成员

bool useFloat16LookupTables = false

是否在列表扫描内核中使用 float16 残差距离表。当 subQuantizers * 2^bitsPerCode > 16384 时，这是必需的。

bool usePrecomputedTables = false

是否启用搜索的预计算表选项，这可能会大大增加内存需求。

bool interleavedLayout = false

对 IVF 列表使用替代内存布局。警告：这是一项正在开发中的功能，仅在为索引启用 cuVS 时才受支持。如果未启用 cuVS，请勿使用。

bool useMMCodeDistance = false

对于 IVFPQ 的非预计算表版本，使用 GEMM 支持的 PQ 代码距离计算。 这用于调试目的，它不应以任何方式显着影响结果。

请注意，如果使用的每个子量化器的维度数量不是本机专门化的（奇数，例如 7 左右），则会自动启用 MM 代码距离。

IndicesOptions indicesOptions = INDICES_64_BIT

GPU 的 Index 存储选项。

GpuIndexFlatConfig flatConfig

粗量化器对象的配置。

bool allowCpuCoarseQuantizer = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIndexIVFPQ : public faiss::gpu::GpuIndexIVF

#include <GpuIndexIVFPQ.h>

用于 GPU 的 IVFPQ 索引。

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexIVFPQ(GpuResourcesProvider *provider, const faiss::IndexIVFPQ *index, GpuIndexIVFPQConfig config = GpuIndexIVFPQConfig())

从预先存在的 faiss::IndexIVFPQ 实例构造，如果输入索引已训练，则将数据复制到给定的 GPU。

GpuIndexIVFPQ(GpuResourcesProvider *provider, int dims, idx_t nlist, idx_t subQuantizers, idx_t bitsPerCode, faiss::MetricType metric = faiss::METRIC_L2, GpuIndexIVFPQConfig config = GpuIndexIVFPQConfig())

构造一个新的实例，带有一个空的flat量化器；用户提供所需的IVF列表数量。

GpuIndexIVFPQ(GpuResourcesProvider *provider, Index *coarseQuantizer, int dims, idx_t nlist, idx_t subQuantizers, idx_t bitsPerCode, faiss::MetricType metric = faiss::METRIC_L2, GpuIndexIVFPQConfig config = GpuIndexIVFPQConfig())

构造一个新的实例，带有一个提供的CPU或GPU粗量化器；用户提供所需的IVF列表数量。

~GpuIndexIVFPQ() override

void copyFrom(const faiss::IndexIVFPQ *index)

在 GPU 上为 num 向量的反向列表保留空间，假设它们在给定的 CPU 索引中均匀分布；将覆盖自身中的所有数据

void copyTo(faiss::IndexIVFPQ *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

void reserveMemory(size_t numVecs)

在我们的倒排列表中为这个数量的向量预留GPU内存。

void setPrecomputedCodes(bool enable)

启用或禁用预计算的代码。

bool getPrecomputedCodes() const

是否启用了预计算代码？

int getNumSubQuantizers() const

返回我们正在使用的子量化器的数量。

int getBitsPerCode() const

返回每个 PQ 代码的位数。

int getCentroidsPerSubQuantizer() const

返回每个 PQ 代码的质心数（每个代码 2^bits）

size_t reclaimMemory()

添加向量后，可以调用此方法来回收设备内存，使其恰好为所需的数量。 返回以字节为单位回收的空间

virtual void reset() override

清除所有倒排列表，但保留粗量化和乘积质心信息

virtual void updateQuantizer() override

如果用户手动更改 IVF 粗量化器的状态（例如，替换一个新的实例或在训练范围之外更改粗量化器中的向量），则应调用此方法

virtual void train(idx_t n, const float *x) override

基于给定的向量数据训练粗量化器和乘积量化器。

void copyFrom(const faiss::IndexIVF *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::IndexIVF *index) const

将我们拥有的内容复制到 CPU 等效项。

virtual idx_t getNumLists() const

返回我们正在管理的倒排列表的数量。

virtual idx_t getListLength(idx_t listId) const

返回特定倒排列表中存在的向量数量。

virtual std::vector<uint8_t> getListVectorData(idx_t listId, bool gpuFormat = false) const

返回特定倒排列表中包含的编码向量数据，用于调试目的。如果gpuFormat为true，则数据以GPU端表示形式进行编码后返回。否则，将其转换为CPU格式。兼容格式，而原生GPU格式可能有所不同。

virtual std::vector<idx_t> getListIndices(idx_t listId) const

返回特定倒排列表中包含的向量索引，用于调试目的。

virtual void search_preassigned(idx_t n, const float *x, idx_t k, const idx_t *assign, const float *centroid_dis, float *distances, idx_t *labels, bool store_pairs, const SearchParametersIVF *params = nullptr, IndexIVFStats *stats = nullptr) const override

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual void range_search_preassigned(idx_t nx, const float *x, float radius, const idx_t *keys, const float *coarse_dis, RangeSearchResult *result, bool store_pairs = false, const IVFSearchParameters *params = nullptr, IndexIVFStats *stats = nullptr) const override

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

获取设备 ID。

返回此索引所在的设备。

获取 GpuResources 对象。

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

设置最小分页大小。

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

获取最小分页大小。

返回分页搜索的当前最小数据大小。

添加单个向量到索引。

x 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

添加向量和对应的 ID 到索引。

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

将向量分配给聚类。

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

在索引中搜索最近邻。

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

在索引中搜索最近邻并重建它们。

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

计算向量相对于聚类中心的残差。

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

计算多个向量相对于聚类中心的残差。

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

ProductQuantizer pq

与CPU版本类似，我们公开一个公开可见的ProductQuantizer 以供操作

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

受保护的函数

void setIndex_(GpuResources *resources, int dim, idx_t nlist, faiss::MetricType metric, float metricArg, int numSubQuantizers, int bitsPerSubQuantizer, bool useFloat16LookupTables, bool useMMCodeDistance, bool interleavedLayout, float *pqCentroidData, IndicesOptions indicesOptions, MemorySpace space)

初始化合适的索引。

void verifyPQSettings_() const

如果配置设置不正确，则抛出错误。

void trainResidualQuantizer_(idx_t n, const float *x)

根据给定的向量数据训练 PQ 量化器。

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

int getCurrentNProbe_(const SearchParameters *params) const

无论是从当前设置的 nprobe 还是从可用的 SearchParameters，都返回应该用于当前搜索的 nprobe。

void verifyIVFSettings_() const

virtual bool addImplRequiresIDs_() const override

addImpl_ 是否需要 ID？如果是这样，并且未提供 ID，我们将根据添加 ID 的顺序按顺序生成它们

virtual void trainQuantizer_(idx_t n, const float *x)

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) override

从 GpuIndex 调用，用于 add/add_with_ids。

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const override

从 GpuIndex 调用以进行搜索。

受保护的属性

const GpuIndexIVFPQConfig ivfpqConfig_

我们的配置选项，我们在初始化时使用了这些选项。

bool usePrecomputedTables_

运行时覆盖：是否使用预计算表。

int subQuantizers_

每个编码向量的子量化器数量。

int bitsPerCode_

每个子量化器代码的位数。

size_t reserveMemoryVecs_

期望的反向列表内存预留。

std::shared_ptr<IVFPQ> index_

我们拥有的乘积量化器实例；包含倒排列表

const GpuIndexIVFConfig ivfConfig_

我们的配置选项。

std::shared_ptr<IVFBase> baseIndex_

对于已训练/初始化的索引，这是对基类的引用。

std::shared_ptr<GpuResources> resources_

管理设备的流、cuBLAS 句柄和暂存内存。

const GpuIndexConfig config_

我们的配置选项。

size_t minPagedSize_

从 CPU 到 GPU 的分页复制的大小阈值。

struct GpuIndexIVFScalarQuantizerConfig : public faiss::gpu::GpuIndexIVFConfig

公共成员

bool interleavedLayout = true

为IVF列表使用备用内存布局（目前是默认布局）

IndicesOptions indicesOptions = INDICES_64_BIT

GPU 的 Index 存储选项。

GpuIndexFlatConfig flatConfig

粗量化器对象的配置。

bool allowCpuCoarseQuantizer = false

此标志控制索引的粗量化器组件的 CPU 回退逻辑。 如果设置为 false（默认），则克隆器将针对 GPU 上未实现的索引抛出异常。 如果设置为 true，它将回退到 CPU 实现。

int device = 0

索引所在的 GPU 设备。

MemorySpace memorySpace = MemorySpace::Device

用于主存储的内存空间。在 Pascal 及以上（CC 6+）架构上，允许 GPU 使用比 GPU 上可用内存更多的内存。

bool use_cuvs = false

索引是否应该分派到 cuVS？

class GpuIndexIVFScalarQuantizer : public faiss::gpu::GpuIndexIVF

#include <GpuIndexIVFScalarQuantizer.h>

GPU 实现的包装器，其外观类似于 faiss::IndexIVFScalarQuantizer

公共类型

using component_t = float

using distance_t = float

公共函数

GpuIndexIVFScalarQuantizer(GpuResourcesProvider *provider, const faiss::IndexIVFScalarQuantizer *index, GpuIndexIVFScalarQuantizerConfig config = GpuIndexIVFScalarQuantizerConfig())

从预先存在的 faiss::IndexIVFScalarQuantizer 实例构造，将数据复制到给定的 GPU，如果输入索引已训练。

GpuIndexIVFScalarQuantizer(GpuResourcesProvider *provider, int dims, idx_t nlist, faiss::ScalarQuantizer::QuantizerType qtype, faiss::MetricType metric = MetricType::METRIC_L2, bool encodeResidual = true, GpuIndexIVFScalarQuantizerConfig config = GpuIndexIVFScalarQuantizerConfig())

构造一个新的实例，带有一个空的flat量化器；用户提供所需的IVF列表数量。

GpuIndexIVFScalarQuantizer(GpuResourcesProvider *provider, Index *coarseQuantizer, int dims, idx_t nlist, faiss::ScalarQuantizer::QuantizerType qtype, faiss::MetricType metric = MetricType::METRIC_L2, bool encodeResidual = true, GpuIndexIVFScalarQuantizerConfig config = GpuIndexIVFScalarQuantizerConfig())

构造一个新的实例，带有一个提供的CPU或GPU粗量化器；用户提供所需的IVF列表数量。

~GpuIndexIVFScalarQuantizer() override

void reserveMemory(size_t numVecs)

在我们的倒排列表中为这个数量的向量预留GPU内存。

void copyFrom(const faiss::IndexIVFScalarQuantizer *index)

从给定的 CPU 索引初始化自身; 将覆盖自身的所有数据

void copyTo(faiss::IndexIVFScalarQuantizer *index) const

将自身复制到给定的 CPU 索引；将覆盖索引实例中的所有数据

size_t reclaimMemory()

添加向量后，可以调用此方法来回收设备内存，使其恰好为所需的数量。 返回以字节为单位回收的空间

virtual void reset() override

清除所有倒排列表，但保留粗量化器和标量量化器信息。

virtual void updateQuantizer() override

如果用户手动更改 IVF 粗量化器的状态（例如，替换一个新的实例或在训练范围之外更改粗量化器中的向量），则应调用此方法

virtual void train(idx_t n, const float *x) override

基于给定的向量数据训练粗量化器和标量量化器。

void copyFrom(const faiss::IndexIVF *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::IndexIVF *index) const

将我们拥有的内容复制到 CPU 等效项。

virtual idx_t getNumLists() const

返回我们正在管理的倒排列表的数量。

virtual idx_t getListLength(idx_t listId) const

返回特定倒排列表中存在的向量数量。

virtual ::vector<> ( , = false)

返回特定倒排列表中包含的编码向量数据，用于调试目的。如果gpuFormat为true，则数据以GPU端表示形式进行编码后返回。否则，将其转换为CPU格式。兼容格式，而原生GPU格式可能有所不同。

virtual ::vector<> ( )

返回特定倒排列表中包含的向量索引，用于调试目的。

virtual ( , , , , , , , , = , = )

搜索一组向量，这些向量由 IVF 量化器预量化。 用查询结果填充相应的堆。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• distance – 输出距离，大小为n * k

• labels – 输出标签，大小为n * k

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

virtual ( , , , , , , = , = , = )

范围搜索一组向量，这些向量由 IVF 量化器预量化。 填写 RangeSearchResults 结果。 默认实现使用 InvertedListScanners 进行搜索。

参数：

• n – 要查询的向量数

• x – 查询向量，大小 nx * d

• assign – 粗量化索引，大小为nx * nprobe

• centroid_dis – 到粗质心的距离，大小为nx * nprobe

• result – 输出结果

• store_pairs – 在结果的上/下32位中存储倒排列表索引+倒排列表偏移量，而不是ID（用于重新排序）。

• params – 用于覆盖对象的搜索参数

• stats – 要更新的搜索统计信息（可以为空）

()

返回此索引所在的设备。

::shared_ptr<> ()

返回对我们的 GpuResources 对象的引用，该对象管理 GPU 上的内存、流和句柄资源

( )

设置使用 CPU -> GPU 分页进行搜索的最小数据大小 (单位：MiB)

()

返回分页搜索的当前最小数据大小。

virtual (, )

x 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void add_with_ids(idx_t n, const float *x, const idx_t *ids) override

x 和 ids 可以在 CPU 或任何 GPU 上；根据需要执行复制 如果添加集太大，则处理分页添加；调用 addInternal_

virtual void assign(idx_t n, const float *x, idx_t *labels, idx_t k = 1) const override

x 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const SearchParameters *params = nullptr) const override

x、distances 和 labels 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void search_and_reconstruct(idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, float *recons, const SearchParameters *params = nullptr) const override

x、distances 和 labels 以及 recons 可以在 CPU 或任何 GPU 上；根据需要执行复制

virtual void compute_residual(const float *x, float *residual, idx_t key) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void compute_residual_n(idx_t n, const float *xs, float *residuals, const idx_t *keys) const override

被重写以强制 GPU 索引提供其自己的 GPU 友好的实现

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const

查询 n 个维度为 d 的向量到索引。

返回所有距离 < 半径的向量。 请注意，许多索引未实现 range_search（只有 k-NN 搜索是强制性的）。

参数：

• n – 向量的数量

• x – 要搜索的输入向量，大小为 n * d

• radius – 搜索半径

• result – 结果表

virtual size_t remove_ids(const IDSelector &sel)

从索引中删除 ID。 并非所有索引都支持。 返回已删除元素的数量。

virtual void reconstruct(idx_t key, float *recons) const

重建存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• key – 要重建的向量的 id

• recons – 重建的向量（大小为 d）

virtual void reconstruct_batch(idx_t n, const idx_t *keys, float *recons) const

重建多个存储的向量（如果是有损编码，则重建近似值）

此函数可能未针对某些索引定义

参数：

• n – 要重建的向量数

• keys – 要重建的向量的 id（大小为 n）

• recons – 重建的向量（大小为 n * d）

virtual void reconstruct_n(idx_t i0, idx_t ni, float *recons) const

重建向量 i0 到 i0 + ni - 1

此函数可能未针对某些索引定义

参数：

• i0 – 序列中第一个向量的索引

• ni – 序列中的向量数

• recons – 重建的向量（大小为 ni * d）

virtual DistanceComputer *get_distance_computer() const

获取此索引类型的 DistanceComputer (在 AuxIndexStructures 中定义) 对象。

DistanceComputer 是为支持对其向量进行随机访问的索引实现的。

virtual size_t sa_code_size() const

生成的代码的大小（以字节为单位）

virtual void sa_encode(idx_t n, const float *x, uint8_t *bytes) const

编码一组向量

参数：

• n – 向量的数量

• x – 输入向量，大小为 n * d

• bytes – 输出编码后的向量，大小为 n * sa_code_size()

virtual void sa_decode(idx_t n, const uint8_t *bytes, float *x) const

解码一组向量

参数：

• n – 向量的数量

• bytes – 输入编码后的向量，大小为 n * sa_code_size()

• x – 输出向量，大小为 n * d

virtual void merge_from(Index &otherIndex, idx_t add_id = 0)

将条目从另一个数据集移动到自身。 在输出时，other 为空。 add_id 被添加到所有移动的 id（对于顺序 id，这将是 this->ntotal）

virtual void check_compatible_for_merge(const Index &otherIndex) const

检查两个索引是否兼容（即，它们以相同的方式训练并具有相同的参数）。 否则抛出异常。

virtual void add_sa_codes(idx_t n, const uint8_t *codes, const idx_t *xids)

添加使用独立编解码器计算的向量

参数：

• codes – 要添加的代码，大小为 n * sa_code_size()

• xids – 对应的 id，大小为 n

void train_q1(size_t n, const float *x, bool verbose, MetricType metric_type)

训练量化器并调用 train_residual 来训练子量化器。

size_t coarse_code_size() const

计算存储列表 ID 所需的字节数

void encode_listno(idx_t list_no, uint8_t *code) const

idx_t decode_listno(const uint8_t *code) const

公共成员

faiss::ScalarQuantizer sq

与CPU版本类似。

bool by_residual

与CPU版本类似。

int d

向量维度

idx_t ntotal

索引向量的总数

bool verbose

详细级别

bool is_trained

如果 Index 不需要训练，或者如果已经完成训练，则设置

MetricType metric_type

此索引用于搜索的度量类型

float metric_arg

度量类型的参数

size_t nprobe = 1

查询时的探针数量

size_t max_codes = 0

查询时要访问的最大代码数量

Index *quantizer = nullptr

quantizer that maps vectors to inverted lists

size_t nlist = 0

倒排列表的数量

char quantizer_trains_alone = 0

>= 0: 将量化器用作 kmeans 训练中的索引 = 1: 仅将训练集传递给量化器的 train() = 2: 在平面索引上进行 kmeans 训练 + 将质心添加到量化器

bool own_fields = false

whether object owns the quantizer

ClusteringParameters cp

to override default clustering params

Index *clustering_index = nullptr

to override index used during clustering

受保护的函数

void verifySQSettings_() const

验证索引 SQ 参数。

void trainResiduals_(idx_t n, const float *x)

从训练中调用以处理 SQ 残差训练。

void copyFrom(const faiss::Index *index)

从 CPU 等效项复制我们需要的内容。

void copyTo(faiss::Index *index) const

将我们拥有的内容复制到 CPU 等效项。

int getCurrentNProbe_(const SearchParameters *params) const

无论是从当前设置的 nprobe 还是从可用的 SearchParameters，都返回应该用于当前搜索的 nprobe。

void verifyIVFSettings_() const

virtual bool addImplRequiresIDs_() const override

addImpl_ 是否需要 ID？如果是这样，并且未提供 ID，我们将根据添加 ID 的顺序按顺序生成它们

virtual void trainQuantizer_(idx_t n, const float *x)

virtual void addImpl_(idx_t n, const float *x, const idx_t *ids) override

从 GpuIndex 调用，用于 add/add_with_ids。

virtual void searchImpl_(idx_t n, const float *x, int k, float *distances, idx_t *labels, const SearchParameters *params) const override

从 GpuIndex 调用以进行搜索。

受保护的属性

const GpuIndexIVFScalarQuantizerConfig ivfSQConfig_

我们的配置选项。

size_t reserveMemoryVecs_

期望的反向列表内存预留。

std::shared_ptr<IVFFlat> index_

我们拥有的实例; 包含倒排列表。

const GpuIndexIVFConfig ivfConfig_

我们的配置选项。

基索引，类型为 std::shared_ptr<IVFBase>

对于已训练/初始化的索引，这是对基类的引用。

GPU 资源，类型为 std::shared_ptr<GpuResources>

管理设备的流、cuBLAS 句柄和暂存内存。

GPU 索引配置，类型为 const GpuIndexConfig

我们的配置选项。

最小分页大小，类型为 size_t

从 CPU 到 GPU 的分页复制的大小阈值。

struct AllocInfo

#include <GpuResources.h>

关于分配是什么/在哪里的信息。

被 faiss::gpu::AllocRequest 继承

公共函数

inline AllocInfo()

inline AllocInfo(AllocType at, int dev, MemorySpace sp, cudaStream_t st)

std::string toString() const

返回此信息的字符串表示形式。

公共成员

AllocType type = AllocType::Other

分配的内部类别。

int device = 0

正在进行分配的设备。

MemorySpace space = MemorySpace::Device

分配的内存空间。

cudaStream_t stream = nullptr

将在其上对内存上的新工作进行排序的流（例如，如果缓存的一段内存要为此调用返回，上次在流 3 上使用，而新的内存请求是针对流 4，则内存管理器将同步流 4 以等待通过事件或其他流同步完成流 3）。

内存管理器保证返回的内存可以自由使用，而不会在此指定的流上发生数据争用。

struct AllocRequest : public faiss::gpu::AllocInfo

#include <GpuResources.h>

关于分配是什么/在哪里的信息，以及它应该有多大。

公共函数

inline AllocRequest()

inline AllocRequest(const AllocInfo &info, size_t sz)

inline AllocRequest(AllocType at, int dev, MemorySpace sp, cudaStream_t st, size_t sz)

std::string toString() const

返回此请求的字符串表示形式。

公共成员

size_t size = 0

分配的字节大小。

AllocType type = AllocType::Other

分配的内部类别。

int device = 0

正在进行分配的设备。

MemorySpace space = MemorySpace::Device

分配的内存空间。

cudaStream_t stream = nullptr

将在其上对内存上的新工作进行排序的流（例如，如果缓存的一段内存要为此调用返回，上次在流 3 上使用，而新的内存请求是针对流 4，则内存管理器将同步流 4 以等待通过事件或其他流同步完成流 3）。

内存管理器保证返回的内存可以自由使用，而不会在此指定的流上发生数据争用。

struct GpuMemoryReservation

#include <GpuResources.h>

管理临时内存请求的 RAII 对象。

公共函数

GpuMemoryReservation()

GpuMemoryReservation(GpuResources *r, int dev, cudaStream_t str, void *p, size_t sz)

GpuMemoryReservation(GpuMemoryReservation &&m) noexcept

~GpuMemoryReservation()

GpuMemoryReservation &operator=(GpuMemoryReservation &&m)

inline void *get()

void release()

公共成员

GpuResources *res

int device

cudaStream_t stream

void *data

size_t size

class GpuResources

#include <GpuResources.h>

GPU 端资源提供者的基类；隐藏 cuBLAS 句柄、CUDA 流以及执行的所有设备内存分配的供应

由 faiss::gpu::StandardGpuResourcesImpl 继承

公共函数

virtual ~GpuResources()

virtual void initializeForDevice(int device) = 0

调用此函数可为特定设备预分配资源。 如果未调用此函数，则会在首次需求时分配资源

virtual bool supportsBFloat16(int device) = 0

给定的GPU是否支持bfloat16？

virtual cublasHandle_t getBlasHandle(int device) = 0

返回我们用于给定设备的cuBLAS句柄。

virtual cudaStream_t getDefaultStream(int device) = 0

返回我们为给定设备上的所有计算排序的流。

virtual void setDefaultStream(int device, cudaStream_t stream) = 0

将设备的默认流覆盖为用户提供的流。资源对象不拥有此流（即，它不会销毁它）。

virtual std::vector<cudaStream_t> getAlternateStreams(int device) = 0

返回我们用于给定设备的备用流的集合。

virtual void *allocMemory(const AllocRequest &req) = 0

内存管理。返回来自给定内存空间的分配，相对于给定流排序（即，第一个用户将是此流中的内核）。 所有分配在内部调整大小为16字节的下一个最高倍数，并保证返回的所有分配都是16字节对齐的。

virtual void deallocMemory(int device, void *in) = 0

返回先前的分配。

virtual size_t getTempMemoryAvailable(int device) const = 0

对于MemorySpace::Temporary，无需cudaMalloc分配即可立即获得多少空间？

virtual std::pair<void*, size_t> getPinnedMemory() = 0

返回可用的CPU固定内存缓冲区。

virtual cudaStream_t getAsyncCopyStream(int device) = 0

返回我们执行异步CPU <-> GPU 复制的流。

bool supportsBFloat16CurrentDevice()

当前GPU是否支持bfloat16？

默认提供的函数

cublasHandle_t getBlasHandleCurrentDevice()

使用当前设备调用 getBlasHandle。

cudaStream_t getDefaultStreamCurrentDevice()

使用当前设备调用 getDefaultStream。

size_t getTempMemoryAvailableCurrentDevice() const

使用当前设备调用 getTempMemoryAvailable。

GpuMemoryReservation allocMemoryHandle(const AllocRequest &req)

通过 RAII 对象返回临时内存分配。

void syncDefaultStream(int device)

针对给定设备，使 CPU 与默认流同步

void syncDefaultStreamCurrentDevice()

为当前设备调用 syncDefaultStream。

std::vector<cudaStream_t> getAlternateStreamsCurrentDevice()

为当前设备调用 getAlternateStreams。

cudaStream_t getAsyncCopyStreamCurrentDevice()

为当前设备调用 getAsyncCopyStream。

class GpuResourcesProvider

#include <GpuResources.h>

共享资源对象提供程序的接口。 这是为了避免将 std::shared_ptr 连接到 Python

由 faiss::gpu::GpuResourcesProviderFromInstance、faiss::gpu::StandardGpuResources 继承

公共函数

virtual ~GpuResourcesProvider()

virtual std::shared_ptr<GpuResources> getResources() = 0

返回共享资源对象。

class GpuResourcesProviderFromInstance : public faiss::gpu::GpuResourcesProvider

#include <GpuResources.h>

一个简单的 GpuResources 对象包装器，用于再次创建一个 GpuResourcesProvider

公共函数

explicit GpuResourcesProviderFromInstance(std::shared_ptr<GpuResources> p)

~GpuResourcesProviderFromInstance() override

virtual std::shared_ptr<GpuResources> getResources() override

返回共享资源对象。

私有成员

std::shared_ptr<GpuResources> res_

template<typename GpuIndex>
struct IndexWrapper

公共函数

IndexWrapper(int numGpus, std::function<std::unique_ptr<GpuIndex>(GpuResourcesProvider*, int)> init)

faiss::Index *getIndex()

void runOnIndices(std::function<void(GpuIndex*)> f)

void setNumProbes(size_t nprobe)

公共成员

resources

subIndex

replicaIndex

class StandardGpuResourcesImpl : public GpuResources

#include <StandardGpuResources.h>

GpuResources 对象的标准实现，它提供了一个临时内存管理器

公共函数

StandardGpuResourcesImpl()

~StandardGpuResourcesImpl() override

virtual bool supportsBFloat16(int device) override

给定的GPU是否支持bfloat16？

noTempMemory()

禁用临时内存分配；所有临时内存请求将在使用时调用 cudaMalloc / cudaFree

setTempMemory(size_t size)

指定我们希望在所有设备上使用一定固定大小的内存作为临时内存。 这是我们将保留的 GPU 内存的上限。 我们永远不会超过任何 GPU 上的 1.5 GiB； 较小的 GPU（<= 4 GiB 或 <= 8 GiB）将使用比这更少的内存。 要避免任何临时内存分配，请传递 0。

setPinnedMemory(size_t size)

设置要分配的固定内存量，用于异步 GPU <-> CPU 传输

virtual void setDefaultStream(int device, cudaStream_t stream) override

调用以更改工作排序的流。 我们不拥有 stream； 也就是说，当 GpuResources 对象被清理时，它不会被销毁。 我们保证所有 Faiss GPU 工作都按照此流的顺序执行，并在退出索引或其他 Faiss GPU 调用时。

revertDefaultStream(int device)

如果有人调用了 setDefaultStream，则将默认流恢复为由此资源对象管理的原始流。

virtual cudaStream_t getDefaultStream(int device) override

返回给定设备上的流，所有 Faiss GPU 工作都按照该流的顺序执行。 我们保证所有 Faiss GPU 工作都按照此流的顺序执行，并在退出索引或其他 Faiss GPU 调用时。

setDefaultNullStreamAllDevices()

调用以将所有设备的工作排序流更改为空流

setLogMemoryAllocations(bool enable)

如果启用，将把每个 GPU 内存分配和释放打印到标准输出

virtual void initializeForDevice(int device) override

内部系统调用。

为此设备初始化资源

virtual cublasHandle_t getBlasHandle(int device) override

返回我们用于给定设备的cuBLAS句柄。

virtual std::vector<cudaStream_t> getAlternateStreams(int device) override

返回我们用于给定设备的备用流的集合。

virtual void *allocMemory(const AllocRequest &req) override

分配非临时GPU内存。

virtual void deallocMemory(int device, void *in) override

返回先前的分配。

virtual size_t getTempMemoryAvailable(int device) const override

对于MemorySpace::Temporary，无需cudaMalloc分配即可立即获得多少空间？

std::map<int, std::map<std::string, std::pair<int, size_t>>> getMemoryInfo() const

导出Python使用的内存描述。

virtual std::pair<void*, size_t> getPinnedMemory() override

返回可用的CPU固定内存缓冲区。

virtual cudaStream_t getAsyncCopyStream(int device) override

返回我们执行异步CPU <-> GPU 复制的流。

bool supportsBFloat16CurrentDevice()

当前GPU是否支持bfloat16？

默认提供的函数

cublasHandle_t getBlasHandleCurrentDevice()

使用当前设备调用 getBlasHandle。

cudaStream_t getDefaultStreamCurrentDevice()

使用当前设备调用 getDefaultStream。

size_t getTempMemoryAvailableCurrentDevice() const

使用当前设备调用 getTempMemoryAvailable。

GpuMemoryReservation allocMemoryHandle(const AllocRequest &req)

通过 RAII 对象返回临时内存分配。

void syncDefaultStream(int device)

针对给定设备，使 CPU 与默认流同步

void syncDefaultStreamCurrentDevice()

为当前设备调用 syncDefaultStream。

std::vector<cudaStream_t> getAlternateStreamsCurrentDevice()

为当前设备调用 getAlternateStreams。

cudaStream_t getAsyncCopyStreamCurrentDevice()

为当前设备调用 getAsyncCopyStream。

受保护的函数

bool isInitialized(int device) const

GPU资源是否已为此设备初始化？

受保护的属性

std::unordered_map<int, std::unordered_map<void*, AllocRequest>> allocs_

每个设备的当前未完成的内存分配集合 设备 -> (分配请求，已分配指针)

std::unordered_map<int, std::unique_ptr<StackDeviceMemory>> tempMemory_

每个设备的临时内存提供者。

std::unordered_map<int, cudaStream_t> defaultStreams_

我们的默认流，工作在其上排序，每个设备一个。

std::unordered_map<int, cudaStream_t> userDefaultStreams_

如果用户设置了特定的流用于排序，则包含在这里

std::unordered_map<int, std::vector<cudaStream_t>> alternateStreams_

我们可以使用的其他流，每个设备一个。

std::unordered_map<int, cudaStream_t> asyncCopyStreams_

用于 GPU <-> CPU 锁页内存复制的异步复制流。

std::unordered_map<int, cublasHandle_t> blasHandles_

每个设备的 cuBLAS 句柄

void *pinnedMemAlloc_

用于此 GPU 的锁页内存分配。

size_t pinnedMemAllocSize_

size_t tempMemSize_

另一种选择是在所有设备上使用指定数量的内存

size_t pinnedMemSize_

我们应该分配的锁页内存量。

bool allocLogging_

是否记录每次 GPU 内存分配和释放。

受保护的静态函数

static size_t getDefaultTempMemForGPU(int device, size_t requested)

根据 GPU 总内存大小调整默认临时内存分配

class StandardGpuResources : public faiss::gpu::GpuResourcesProvider

#include <StandardGpuResources.h>

GpuResources 的默认实现，它分配一个 cuBLAS 流和 2 个用于使用的流，以及临时内存。 在内部，Faiss GPU 代码使用由 getResources 管理的实例，但这是用户面向的对象，它在内部进行引用计数。

公共函数

StandardGpuResources()

~StandardGpuResources() override

virtual std::shared_ptr<GpuResources> getResources() override

返回共享资源对象。

bool supportsBFloat16(int device)

给定设备是否支持原生 bfloat16 算法。

bool supportsBFloat16CurrentDevice()

当前设备是否支持原生 bfloat16 算法。

void noTempMemory()

禁用临时内存分配；所有临时内存请求将在使用时调用 cudaMalloc / cudaFree

void setTempMemory(size_t size)

指定我们希望在所有设备上使用一定固定大小的内存作为临时内存。 这是我们将保留的 GPU 内存的上限。 我们永远不会超过任何 GPU 上的 1.5 GiB； 较小的 GPU（<= 4 GiB 或 <= 8 GiB）将使用比这更少的内存。 要避免任何临时内存分配，请传递 0。

void setPinnedMemory(size_t size)

设置要分配的固定内存量，用于异步 GPU <-> CPU 传输

void setDefaultStream(int device, cudaStream_t stream)

调用以更改工作排序的流。 我们不拥有 stream； 也就是说，当 GpuResources 对象被清理时，它不会被销毁。 我们保证所有 Faiss GPU 工作都按照此流的顺序执行，并在退出索引或其他 Faiss GPU 调用时。

void revertDefaultStream(int device)

如果有人调用了 setDefaultStream，则将默认流恢复为由此资源对象管理的原始流。

void setDefaultNullStreamAllDevices()

调用以将所有设备的工作排序流更改为空流

std::map<int, std::map<std::string, std::pair<int, size_t>>> getMemoryInfo() const

导出Python使用的内存描述。

cudaStream_t getDefaultStream(int device)

返回当前默认流。

size_t getTempMemoryAvailable(int device) const

返回当前可用临时内存量。

void syncDefaultStreamCurrentDevice()

将我们的默认流与CPU同步。

void setLogMemoryAllocations(bool enable)

如果启用，将把每个 GPU 内存分配和释放打印到标准输出

私有成员

std::shared_ptr<StandardGpuResourcesImpl> res_

class DeviceScope

#include <DeviceUtils.h>

RAII 对象，用于设置当前设备，并在销毁时恢复之前的设备

公共函数

explicit DeviceScope(int device)

~DeviceScope()

私有成员

int prevDevice_

class CublasHandleScope

#include <DeviceUtils.h>

RAII 对象，用于管理 cublasHandle_t。

公共函数

CublasHandleScope()

~CublasHandleScope()

inline cublasHandle_t get()

私有成员

cublasHandle_t blasHandle_

class CudaEvent

公共函数

explicit CudaEvent(cudaStream_t stream, bool timer = false)

创建一个事件并将其记录在此流中。

CudaEvent(const CudaEvent &event) = delete

CudaEvent(CudaEvent &&event) noexcept

~CudaEvent()

inline cudaEvent_t get()

void streamWaitOnEvent(cudaStream_t stream)

在此流中等待此事件。

void cpuWaitOnEvent()

让 CPU 等待此事件完成。

CudaEvent &operator=(CudaEvent &&event) noexcept

CudaEvent &operator=(CudaEvent &event) = delete

私有成员

cudaEvent_t event_

class StackDeviceMemory

#include <StackDeviceMemory.h>

设备内存管理器，用于从内存区域为单个设备提供临时内存分配

公共函数

StackDeviceMemory(GpuResources *res, int device, size_t allocPerDevice)

分配一个新的我们管理的内存区域。

StackDeviceMemory(int device, void *p, size_t size, bool isOwner)

管理特定设备的内存区域，有或没有所有权

~StackDeviceMemory()

int getDevice() const

void *allocMemory(cudaStream_t stream, size_t size)

所有请求的分配都应该是 16 字节的倍数。

void deallocMemory(int device, cudaStream_t, size_t size, void *p)

size_t getSizeAvailable() const

std::string toString() const

受保护的属性

int device_

我们的设备。

Stack stack_

内存堆栈。

struct Range

#include <StackDeviceMemory.h>

先前的分配范围和需要同步的流

公共函数

inline Range(char *s, char *e, cudaStream_t str)

公共成员

char *start_

char *end_

cudaStream_t stream_

struct Stack

公共函数

Stack(GpuResources *res, int device, size_t size)

通过 cudaMalloc 分配内存的构造函数。

~Stack()

size_t getSizeAvailable() const

返回在不调用 cudaMalloc 的情况下可用于分配的大小。

char *getAlloc(size_t size, cudaStream_t stream)

获取一个分配；保证所有分配都是 16 字节对齐的。

void returnAlloc(char *p, size_t size, cudaStream_t stream)

返回一个分配。

std::string toString() const

返回堆栈状态。

公共成员

GpuResources *res_

我们的 GpuResources 对象。

int device_

此分配所在的设备。

char *alloc_

我们的临时内存缓冲区分配在哪里；我们从该缓冲区开始分配 16 个字节。

size_t allocSize_

我们分配的总大小。

char *start_

我们的临时内存区域； [start_, end_) 是有效的。

char *end_

char *head_

Stack 在 [start, end) 中的头。

std::list<Range> lastUsers_

堆栈上先前最后分配用户的列表，用于可能的同步目的。

size_t highWaterMemoryUsed_

从临时缓冲区使用的内存方面来看，最高水位线是多少？

class KernelTimer

#include <Timer.h>

用于定时内核执行的实用程序类。

公共函数

KernelTimer(cudaStream_t stream = nullptr)

构造函数启动计时器并在当前设备流中添加事件

~KernelTimer()

析构函数释放事件资源。

float elapsedMilliseconds()

添加停止事件，然后同步停止事件，以获取当前流中启动的任何内核的实际 GPU 端内核计时。 返回经过的毫秒数。 只能调用一次。

私有成员

cudaEvent_t startEvent_

cudaEvent_t stopEvent_

cudaStream_t stream_

bool valid_

class CpuTimer

#include <Timer.h>

CPU 挂钟经过时间计时器。

公共函数

CpuTimer()

创建并启动一个新的计时器。

float elapsedMilliseconds()

返回以毫秒为单位的经过时间。

私有成员

std::chrono::time_point<std::chrono::steady_clock> start_

namespace utils

函数

template<typename U, typename V> constexpr __host__ __device__ auto divDown (U a, V b) -> decltype(a+b)

template<typename U, typename V> constexpr __host__ __device__ auto divUp (U a, V b) -> decltype(a+b)

template<typename U, typename V> constexpr __host__ __device__ auto roundDown (U a, V b) -> decltype(a+b)

template<typename U, typename V> constexpr __host__ __device__ auto roundUp (U a, V b) -> decltype(a+b)

template<class T> constexpr __host__ __device__ T pow (T n, T power)

template<class T> constexpr __host__ __device__ T pow2 (T n)

template<typename T> constexpr __host__ __device__ int log2 (T n, int p=0)

template<typename T> constexpr __host__ __device__ bool isPowerOf2 (T v)

template<typename T> constexpr __host__ __device__ T nextHighestPowerOf2 (T v)

namespace ivflib

函数

void check_compatible_for_merge(const Index *index1, const Index *index2)

检查两个索引是否具有相同的参数，并以相同的方式进行训练，否则抛出异常。

const IndexIVF *extract_index_ivf(const Index *index)

从索引中获取一个 IndexIVF。该索引可以是 IndexIVF 或包含 IndexIVF 的某些包装类

如果不是这种情况，则抛出异常。

IndexIVF *extract_index_ivf(Index *index)

const IndexIVF *try_extract_index_ivf(const Index *index)

与上面相同，但返回 nullptr 而不是在失败时抛出异常

IndexIVF *try_extract_index_ivf(Index *index)

void merge_into(Index *index0, Index *index1, bool shift_ids)

将 index1 合并到 index0 中。适用于嵌入在 IndexPreTransform 中的 IndexIVF 和 IndexIVF。在输出时，index1 为空。

参数：

shift_ids – 将 id 从 index1 转换为 index0->prev_ntotal

void search_centroid(Index *index, const float *x, int n, idx_t *centroid_ids)

void search_and_return_centroids(Index *index, size_t n, const float *xin, long k, float *distances, idx_t *labels, idx_t *query_centroid_ids, idx_t *result_centroid_ids)

ArrayInvertedLists *get_invlist_range(const Index *index, long i0, long i1)

获取倒排列表的子集 [i0, i1)

void set_invlist_range(Index *index, long i0, long i1, ArrayInvertedLists *src)

设置倒排列表的子集。

void search_with_parameters(const Index *index, idx_t n, const float *x, idx_t k, float *distances, idx_t *labels, const IVFSearchParameters *params, size_t *nb_dis = nullptr, double *ms_per_stage = nullptr)

使用给定的参数搜索 IndexIVF，可能嵌入在 IndexPreTransform 中。这是一种设置 nprobe 并以线程安全的方式获取统计信息的方法。

可选地返回（如果非空指针）

• nb_dis：计算的距离数

• ms_per_stage：[0]：预处理时间 [1]：粗量化，[2]：列表扫描

void range_search_with_parameters(const Index *index, idx_t n, const float *x, float radius, RangeSearchResult *result, const IVFSearchParameters *params, size_t *nb_dis = nullptr, double *ms_per_stage = nullptr)

与 search_with_parameters 相同，但用于范围搜索

IndexIVFResidualQuantizer *ivf_residual_from_quantizer(const ResidualQuantizer&, int nlevel)

从 ResidualQuantizer 构建一个 IndexIVFResidualQuantizer，使用前 nlevel 个组件作为粗量化器，其余的作为 invlist 中的代码

void ivf_residual_add_from_flat_codes(IndexIVFResidualQuantizer *ivfrq, size_t ncode, const uint8_t *codes, int64_t code_size = -1)

从代码添加。注意，未使用 norm 组件，因此可以提供 code_size。

参数：

• ivfrq – 使用代码填充的索引

• codes – 要添加的代码，大小 (ncode, code_size)

• code_size – 覆盖 ivfrq 的 code_size，如果 norm 编码不同，则很有用

struct SlidingIndexWindow

#include <IVFlib.h>

以 FIFO 方式连接在一起的一组 IndexIVF。在每个“step”中，最旧的索引切片被删除，并添加一个新索引。

公共函数

SlidingIndexWindow(Index *index)

索引最初应为空且经过训练

void step(const Index *sub_index, bool remove_oldest)

将一个索引添加到当前索引并删除最旧的索引。

参数：

• sub_index – 要换入的切片（可以为 NULL）

• remove_oldest – 如果为 true，则删除最旧的切片

公共成员

Index *index

包含滑动窗口的公共索引

ArrayInvertedLists *ils

索引的 InvertedLists。

int n_slice

当前索引中的切片数

size_t nlist

与 index->nlist 相同

std::vector<std::vector<size_t>> sizes

每个切片的累积列表大小

namespace lsq

struct IcmEncoder

由 faiss::gpu::GpuIcmEncoder 子类化

公共函数

explicit IcmEncoder(const LocalSearchQuantizer *lsq)

inline virtual ~IcmEncoder()

计算二元项

virtual void set_binary_term()

virtual void encode(int32_t *codes, const float *x, std::mt19937 &gen, size_t n, size_t ils_iters) const

使用给定的码本编码向量

参数：

• codes – 输出代码，大小为 n * M

• x – 要编码的向量，大小为 n * d

• gen – 随机生成器

• n – 向量的数量

• ils_iters – 迭代局部搜索的迭代次数

公共成员

std::vector<float> binaries

bool verbose

const LocalSearchQuantizer *lsq

struct IcmEncoderFactory

由 faiss::gpu::GpuIcmEncoderFactory 继承

公共函数

inline virtual IcmEncoder *get(const LocalSearchQuantizer *lsq)

inline virtual ~IcmEncoderFactory()

struct LSQTimer

#include <LocalSearchQuantizer.h>

一个用于在训练期间计算消耗时间的辅助结构体。它不是线程安全的。

公共函数

inline LSQTimer()

double get(const std::string &name)

void add(const std::string &name, double delta)

void reset()

公共成员

std::unordered_map<std::string, double> t

struct LSQTimerScope

公共函数

LSQTimerScope(LSQTimer *timer, std::string name)

void finish()

~LSQTimerScope()

公共成员

double t0

LSQTimer *timer

std::string name

bool finished

namespace nn

类型定义

using Tensor2D = Tensor2DTemplate<float>

using Int32Tensor2D = Tensor2DTemplate<int32_t>

template<typename T>
struct Tensor2DTemplate

公共函数

Tensor2DTemplate(size_t n0, size_t n1, const T *data = nullptr)

Tensor2DTemplate &operator+=(const Tensor2DTemplate&)

Tensor2DTemplate column(size_t j) const

获取第 j 列作为一个单列 Tensor2D

inline size_t numel() const

inline T *data()

inline const T *data() const

公共成员

size_t shape[2]

std::vector<T> v

struct Linear

#include <NeuralNet.h>

nn.Linear 的最小化翻译

公共函数

Linear(size_t in_features, size_t out_features, bool bias = true)

Tensor2D operator()(const Tensor2D &x) const

公共成员

size_t in_features

size_t out_features

std::vector<float> weight

std::vector<float> bias

struct Embedding

#include <NeuralNet.h>

nn.Embedding 的最小化翻译

公共函数

Embedding(size_t num_embeddings, size_t embedding_dim)

Tensor2D operator()(const Int32Tensor2D&) const

inline float *data()

inline const float *data() const

公共成员

size_t num_embeddings

size_t embedding_dim

std::vector<float> weight

struct FFN

#include <NeuralNet.h>

前馈层，扩展到隐藏维度，应用 ReLU 非线性，然后映射回原始维度

公共函数

FFN类的构造函数，内联函数。接受两个整数参数 d 和 h。

重载的函数调用运算符。它接受一个常量引用类型的 Tensor2D 对象 x 作为参数，并返回一个 Tensor2D 对象。该函数是常量成员函数。

公共成员

类型为 Linear 的成员变量 linear1。

类型为 Linear 的成员变量 linear2。

命名空间 nndescent。

结构体 Neighbor。

公共函数

Neighbor 结构体的默认构造函数。

Neighbor 结构体的内联构造函数，接受一个整数 id，一个浮点数 distance 和一个布尔值 f 作为参数。

重载的小于运算符。它接受一个常量引用类型的 Neighbor 对象 other 作为参数，并返回一个布尔值。该函数是常量成员函数。

公共成员

类型为 int 的成员变量 id。

类型为 float 的成员变量 distance。

类型为 bool 的成员变量 flag。

结构体 Nhood。

公共函数

Nhood 结构体的默认构造函数。

Nhood 结构体的构造函数，接受一个整数 l，一个整数 s，一个 std::mt19937 类型的引用 rng, 一个整数 N 作为参数。

重载的赋值运算符。它接受一个常量引用类型的 Nhood 对象 other 作为参数，并返回一个 Nhood 对象的引用。

Nhood 结构体的拷贝构造函数，它接受一个常量引用类型的 Nhood 对象 other 作为参数。

insert 函数，用于插入元素。接受一个整数 id 和一个浮点数 dist 作为参数。

模板函数 join 的模板参数定义。
join 函数是一个模板函数，它接受一个类型为 C 的参数 callback。该函数是常量成员函数。

公共成员

类型为 std::mutex 的成员变量 lock。

类型为 std::vector<Neighbor> 的成员变量 pool。

类型为 int 的成员变量 M。

类型为 std::vector<int> 的成员变量 nn_old。

类型为 std::vector<int> 的成员变量 nn_new。

类型为 std::vector<int> 的成员变量 rnn_old。

std::vector<int> rnn_new

namespace nsg

函数

DistanceComputer *storage_distance_computer(const Index *storage)

template<class node_t>
struct Graph

公共函数

inline Graph(node_t *data, int N, int K)

inline Graph(int N, int K)

inline Graph(const Graph &g)

inline virtual ~Graph()

inline node_t at(int i, int j) const

inline node_t &at(int i, int j)

inline virtual size_t get_neighbors(int i, node_t *neighbors) const

公共成员

node_t *data

扁平化的邻接矩阵，大小为 N-by-K

int K

每个节点的邻居数

int N

节点的总数

bool own_fields

底层数据是否由自身拥有

namespace quantize_lut

用于将 PQ 浮点查找表 (LUT) 量化为 uint8，并将偏差量化为 uint16 的函数。 累加应该在 uint16 中进行。 量化系数是 float (a, b)，使得

 original_value = quantized_value * a / b

量化中最难的部分是需要加在一起的多个 LUT。 在这种情况下，必须选择系数 a，以便总和适合 uint16 累加器。

函数

void round_uint8_per_column(float *tab, size_t n, size_t d, float *a_out = nullptr, float *b_out = nullptr)

void round_uint8_per_column_multi(float *tab, size_t m, size_t n, size_t d, float *a_out = nullptr, float *b_out = nullptr)

void quantize_LUT_and_bias(size_t nprobe, size_t M, size_t ksub, bool lut_is_3d, const float *LUT, const float *bias, uint8_t *LUTq, size_t M2, uint16_t *biasq, float *a_out = nullptr, float *b_out = nullptr)

将 LUT 量化为 uint8，并将 bias 量化为 uint16。

(nprobe, M, ksub, lut_is_3d) 决定 LUT 的大小

LUT 输入

• 2D 大小 (M, ksub)：每个探针一个矩阵 (lut_is_3d=false)

• 3D 大小 (nprobe, M, ksub)：每个探针一个单独的 LUT (lut_is_3d=true) bias 输入

• nullptr：bias 为 0

• 大小 (nprobe)：每个探针一个 bias 输出

• LUTq：LUT 的 uint8 版本（M 的大小向上舍入为 M2）

• biasq（或 nullptr）：LUT 的 uint16 版本

• a, b：用于近似真实距离的标量

void aq_quantize_LUT_and_bias(size_t nprobe, size_t M, size_t ksub, const float *LUT, const float *bias, size_t M_norm, int norm_scale, uint8_t *LUTq, size_t M2, uint16_t *biasq, float *a_out, float *b_out)

float aq_estimate_norm_scale(size_t M, size_t ksub, size_t M_norm, const float *LUT)

namespace rq_encode_steps

函数

void refine_beam_mp(const ResidualQuantizer &rq, size_t n, size_t beam_size, const float *x, int out_beam_size, int32_t *out_codes, float *out_residuals, float *out_distances, RefineBeamMemoryPool &pool)

void refine_beam_LUT_mp(const ResidualQuantizer &rq, size_t n, const float *query_norms, const float *query_cp, int out_beam_size, int32_t *out_codes, float *out_distances, RefineBeamLUTMemoryPool &pool)

void compute_codes_add_centroids_mp_lut0(const ResidualQuantizer &rq, const float *x, uint8_t *codes_out, size_t n, const float *centroids, ComputeCodesAddCentroidsLUT0MemoryPool &pool)

void compute_codes_add_centroids_mp_lut1(const ResidualQuantizer &rq, const float *x, uint8_t *codes_out, size_t n, const float *centroids, ComputeCodesAddCentroidsLUT1MemoryPool &pool)

struct RefineBeamMemoryPool

公共成员

std::vector<int32_t> new_codes

std::vector<float> new_residuals

std::vector<float> residuals

std::vector<int32_t> codes

std::vector<float> distances

struct RefineBeamLUTMemoryPool

公共成员

std::vector<int32_t> new_codes

std::vector<float> new_distances

std::vector<int32_t> codes

std::vector<float> distances

struct ComputeCodesAddCentroidsLUT0MemoryPool

公共成员

std::vector<int32_t> codes

std::vector<float> norms

std::vector<float> distances

std::vector<float> residuals

RefineBeamMemoryPool refine_beam_pool

struct ComputeCodesAddCentroidsLUT1MemoryPool

公共成员

std::vector<int32_t> codes

std::vector<float> distances

std::vector<float> query_norms

std::vector<float> query_cp

std::vector<float> residuals

RefineBeamLUTMemoryPool refine_beam_lut_pool

namespace simd_result_handlers

函数

template<class C, bool W, class Consumer, class ...Types>
void dispatch_SIMDResultHandler_fixedCW(SIMDResultHandler &res, Consumer &consumer, Types... args)

template<class C, class Consumer, class ...Types>
void dispatch_SIMDResultHandler_fixedC(SIMDResultHandler &res, Consumer &consumer, Types... args)

template<class Consumer, class ...Types>
void dispatch_SIMDResultHandler(SIMDResultHandler &res, Consumer &consumer, Types... args)

struct DummyResultHandler : public faiss::SIMDResultHandler

#include <simd_result_handlers.h>

只是计算结果校验和的虚拟结构（以避免计算被优化掉）

公共函数

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

inline virtual void set_block_origin(size_t, size_t) final

设置正在计算的子矩阵

inline ~DummyResultHandler()

公共成员

size_t cs = 0

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

struct StoreResultHandler : public faiss::SIMDResultHandler

#include <simd_result_handlers.h>

memorize results in a nq-by-nb matrix.

j0 is the current upper-left block of the matrix

公共函数

inline StoreResultHandler(uint16_t *data, size_t ld)

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

inline virtual void set_block_origin(size_t i0_in, size_t j0_in) final

设置正在计算的子矩阵

公共成员

uint16_t *data

size_t ld

size_t i0 = 0

size_t j0 = 0

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<int NQ, int BB>
struct FixedStorageHandler : public faiss::SIMDResultHandler

#include <simd_result_handlers.h>

在固定大小的矩阵中存储结果。

公共函数

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

inline virtual void set_block_origin(size_t i0_in, size_t j0_in) final

设置正在计算的子矩阵

template<class OtherResultHandler>
inline void to_other_handler(OtherResultHandler &other) const

inline virtual ~FixedStorageHandler()

公共成员

simd16uint16 dis[NQ][BB]

int i0 = 0

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<class C, bool with_id_map>
struct ResultHandlerCompare : public faiss::SIMDResultHandlerToFloat

#include <simd_result_handlers.h>

结果处理器，它比较距离以检查它们是否需要保留

被 faiss::simd_result_handlers::RangeHandler< C, false > 子类化

公共类型

using TI = typename C::TI

公共函数

inline ResultHandlerCompare(size_t nq, size_t ntotal, const IDSelector *sel_in)

设置块的起始位置

设置正在计算的子矩阵

根据起始位置调整。

根据起始位置调整ID。

inline uint32_t get_lt_mask(uint16_t thr, size_t b, simd16uint16 d0, simd16uint16 d1)

返回(d0, d1)中小于thr的元素的二进制掩码。inverse_test返回大于的元素。

析构函数

开始处理，传入范数。

结束处理。

处理SIMD结果的虚函数。

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

公共成员

是否禁用。

行起始索引。

列起始索引。

ID选择器。

查询向量的数量。

向量总数。

const idx_t *id_map = nullptr

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<class C, bool with_id_map = false>
struct SingleResultHandler : public faiss::simd_result_handlers::ResultHandlerCompare<C, false>

#include <simd_result_handlers.h>

k=1 的特殊版本

公共类型

using T = typename C::T

using TI = typename C::TI

using RHC = ResultHandlerCompare<C, with_id_map>

公共函数

inline SingleResultHandler(size_t nq, size_t ntotal, float *dis, int64_t *ids, const IDSelector *sel_in)

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

inline virtual void end()

inline virtual void set_block_origin(size_t i0_in, size_t j0_in) final

设置正在计算的子矩阵

inline void adjust_with_origin(size_t &q, simd16uint16 &d0, simd16uint16 &d1) // 使用原点调整

inline int64_t adjust_id(size_t b, size_t j) // 调整ID

inline uint32_t get_lt_mask(uint16_t thr, size_t b, simd16uint16 d0, simd16uint16 d1) // 获取小于阈值的掩码

返回(d0, d1)中小于thr的元素的二进制掩码。inverse_test返回大于的元素。

inline virtual void begin(const float *norms) // 开始处理，传入norms

公共成员

std::vector<int16_t> idis

float *dis

int64_t *ids

bool disable

int64_t i0

int64_t j0

const IDSelector *sel

size_t nq

size_t ntotal

const idx_t *id_map = nullptr

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<class C, bool with_id_map = false>
struct HeapHandler : public faiss::simd_result_handlers::ResultHandlerCompare<C, false>

#include <simd_result_handlers.h>

在最小或最大堆中收集结果的结构

公共类型

using T = typename C::T

using TI = typename C::TI

using RHC = ResultHandlerCompare<C, with_id_map>

公共函数

inline HeapHandler(size_t nq, size_t ntotal, int64_t k, float *dis, int64_t *ids, const IDSelector *sel_in)

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

inline virtual void end() override

inline virtual void set_block_origin(size_t i0_in, size_t j0_in) final

设置正在计算的子矩阵

inline void adjust_with_origin(size_t &q, simd16uint16 &d0, simd16uint16 &d1)

inline int64_t adjust_id(size_t b, size_t j)

inline uint32_t get_lt_mask(uint16_t thr, size_t b, simd16uint16 d0, simd16uint16 d1)

返回(d0, d1)中小于thr的元素的二进制掩码。inverse_test返回大于的元素。

inline virtual void begin(const float *norms)

公共成员

std::vector<uint16_t> idis

std::vector<TI> iids

float *dis

int64_t *ids

int64_t k

bool disable

int64_t i0

int64_t j0

const IDSelector *sel

size_t nq

size_t ntotal

const idx_t *id_map = nullptr

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<class C, bool with_id_map = false>
struct ReservoirHandler : public faiss::simd_result_handlers::ResultHandlerCompare<C, false>

#include <simd_result_handlers.h>

Simple top-N implementation using a reservoir.

Results are stored when they are below the threshold until the capacity is reached. Then a partition sort is used to update the threshold. Handler built from several ReservoirTopN (one per query)

公共类型

using T = typename C::T

using TI = typename C::TI

using RHC = ResultHandlerCompare<C, with_id_map>

公共函数

inline ReservoirHandler(size_t nq, size_t ntotal, size_t k, size_t cap, float *dis, int64_t *ids, const IDSelector *sel_in)

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

内联虚函数 void end() 重载

内联虚函数 void set_block_origin(size_t i0_in, size_t j0_in) 最终

设置正在计算的子矩阵

内联函数 void adjust_with_origin(size_t &q, simd16uint16 &d0, simd16uint16 &d1)

内联函数 int64_t adjust_id(size_t b, size_t j)

内联函数 uint32_t get_lt_mask(uint16_t thr, size_t b, simd16uint16 d0, simd16uint16 d1)

返回(d0, d1)中小于thr的元素的二进制掩码。inverse_test返回大于的元素。

内联虚函数 void begin(const float *norms)

公共成员

size_t capacity

float *dis

int64_t *ids

std::vector<TI> all_ids

AlignedTable<T> all_vals

std::vector<ReservoirTopN<C>> reservoirs

bool disable

int64_t i0

int64_t j0

const IDSelector *sel

size_t nq

size_t ntotal

const idx_t *id_map = nullptr

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

template<class C, bool with_id_map = false>
struct RangeHandler : public faiss::simd_result_handlers::ResultHandlerCompare<C, false>

#include <simd_result_handlers.h>

用于范围搜索的结果处理器。 难点在于范围距离必须使用缩放器进行缩放。

公共类型

using T = typename C::T

using TI = typename C::TI

using RHC = ResultHandlerCompare<C, with_id_map>

公共函数

inline RangeHandler(RangeSearchResult &rres, float radius, size_t ntotal, const IDSelector *sel_in)

inline virtual void begin(const float *norms) override

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出 32 个距离，并以两个 simd16uint16 提供时调用。(q, b) 指示它在块中的哪个条目。

inline virtual void end() override

inline virtual void set_block_origin(size_t i0_in, size_t j0_in) final

设置正在计算的子矩阵

inline void adjust_with_origin(size_t &q, simd16uint16 &d0, simd16uint16 &d1)

inline int64_t adjust_id(size_t b, size_t j)

inline uint32_t get_lt_mask(uint16_t thr, size_t b, simd16uint16 d0, simd16uint16 d1)

返回(d0, d1)中小于thr的元素的二进制掩码。inverse_test返回大于的元素。

公共成员

RangeSearchResult &rres

float radius

std::vector<uint16_t> thresholds

std::vector<size_t> n_per_query

size_t q0 = 0

std::vector<Triplet> triplets

bool disable

int64_t i0

int64_t j0

const IDSelector *sel

size_t nq

size_t ntotal

const idx_t *id_map = nullptr

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false

struct Triplet

公共成员

idx_t q

idx_t b

uint16_t dis

template<class C, bool with_id_map = false>
struct PartialRangeHandler : public faiss::simd_result_handlers::RangeHandler<C, false>

公共类型

using T = typename C::T

using TI = typename C::TI

using RHC = RangeHandler<C, with_id_map>

公共函数

inline PartialRangeHandler(RangeSearchPartialResult &pres, float radius, size_t ntotal, size_t q0, size_t q1, const IDSelector *sel_in)

inline void shift_n_per_query()

inline virtual void end() override

inline virtual void begin(const float *norms) override

inline virtual void handle(size_t q, size_t b, simd16uint16 d0, simd16uint16 d1) final

当计算出32个距离并以两个 simd16uint16 提供时调用。（q，b）指示它在块中的哪个条目。

inline virtual void set_block_origin(size_t i0_in, size_t j0_in) final

设置正在计算的子矩阵

inline void adjust_with_origin(size_t &q, simd16uint16 &d0, simd16uint16 &d1)

inline int64_t adjust_id(size_t b, size_t j)

inline uint32_t get_lt_mask(uint16_t thr, size_t b, simd16uint16 d0, simd16uint16 d1)

返回(d0, d1)中小于thr的元素的二进制掩码。inverse_test返回大于的元素。

公共成员

RangeSearchPartialResult &pres

size_t q0

std::vector<Triplet> triplets

std::vector<size_t> n_per_query

RangeSearchResult &rres

float radius

std::vector<uint16_t> thresholds

bool disable = false

int64_t i0 = 0

int64_t j0 = 0

const IDSelector *sel

size_t nq

size_t ntotal

const idx_t *id_map = nullptr

这些字段主要用于 IVF 变体（with_id_map=true）

const int *q_map = nullptr

const uint16_t *dbias = nullptr

const float *normalizers = nullptr

bool is_CMax = false

uint8_t sizeof_ids = 0

bool with_fields = false