File IndexPreTransform.h

namespace faiss

实现了具有多种变体的 k-means 聚类。

版权所有 (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 SearchParametersPreTransform : public faiss::SearchParameters

公共成员

SearchParameters *index_params = nullptr
struct IndexPreTransform : public faiss::Index
#include <IndexPreTransform.h>

Index 在将向量传递给子索引之前，应用 LinearTransform 变换。

公共函数

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 而不是顺序 id。

默认实现会因断言而失败，因为并非所有索引都支持它。

参数:

  • 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

查询索引中维度为 d 的 n 个向量。

最多返回 k 个向量。如果某个查询的结果不足，结果数组将用 -1 填充。

参数:

  • n – 向量的数量

  • x – 要搜索的输入向量，大小为 n * d

  • k – 提取的向量数

  • distances – 输出的成对距离，大小为 n*k

  • labels – NNs 的输出标签，大小为 n*k

virtual void range_search(idx_t n, const float *x, float radius, RangeSearchResult *result, const SearchParameters *params = nullptr) const override

查询索引中维度为 d 的 n 个向量。

返回所有距离 < radius 的向量。请注意，许多索引未实现 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

与 search 类似，但还会重建搜索结果的存储向量（如果是有损编码，则为近似值）。

如果某个查询的结果不足，则结果数组将用 -1 填充。

参数:

  • n – 向量的数量

  • x – 要搜索的输入向量，大小为 n * d

  • k – 提取的向量数

  • distances – 输出的成对距离，大小为 n*k

  • labels – NNs 的输出标签，大小为 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

公共成员

std::vector<VectorTransform*> chain
Index *index

! 变换链

bool own_fields

! 子索引