文件 Index.h
定义
-
FAISS_VERSION_MAJOR
-
FAISS_VERSION_MINOR
-
FAISS_VERSION_PATCH
-
FAISS_STRINGIFY(ARG)
-
FAISS_TOSTRING(ARG)
-
VERSION_STRING
-
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
定义一些将变换应用于一组向量的对象 通常这些是预处理步骤。
-
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。
-
inline virtual ~SearchParameters()
-
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
公共函数
-
inline explicit Index(idx_t d = 0, MetricType metric = METRIC_L2)
-
virtual ~Index()
-
virtual void add(idx_t n, const float *x) = 0
将 n 个维度为 d 的向量添加到索引。
向量被隐式分配标签 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 而不是顺序 id。
默认实现会因断言而失败，因为它不是所有索引都支持。
- 参数:
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
查询索引中维度为 d 的 n 个向量。
最多返回 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
查询索引中维度为 d 的 n 个向量。
返回距离 < radius 的所有向量。 请注意，许多索引未实现 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 个向量的索引。
此函数与 search 相同，但仅返回邻居的标签。
- 参数:
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
与 search 类似，但也重建搜索结果的存储向量（或者在有损编码的情况下，重建近似向量）。
如果查询的结果不足，则结果数组将填充 -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 – 编码后的索引，由 search 和 assign 返回
-
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 – 编码后的索引，由 search 和 assign 返回
-
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
-
inline explicit Index(idx_t d = 0, MetricType metric = METRIC_L2)
-
struct SearchParameters