结构体 faiss::ResidualQuantizer

struct ResidualQuantizer : public faiss::AdditiveQuantizer

具有每个子量化器可变位数的残差量化器

残差质心存储在一个大的累积质心表中。 代码可以表示为大小为 (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，并存储 8 位量化范数

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 作为范数量化器（用于快速扫描）

公共函数

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 – 输入 beam 大小

• new_beam_size – 输出 beam 大小 (应 <= 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 搜索会消耗大量内存。此函数估计 refine_beam 使用的内存量以调整批量大小

参数:

beam_size – 如果 != -1，则覆盖 beam 大小

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 – 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 搜索，带有预计算的范数

公共成员

train_type_t train_type = Train_progressive_dim

下面 Train_* 标志的二进制或。

int niter_codebook_refine = 5

码本优化的迭代次数。

int max_beam_size = 5

用于训练和编码的 beam 大小

int use_beam_LUT = 0

使用 LUT 进行 beam 搜索

ApproxTopK_mode_t approx_topk_mode = ApproxTopK_mode_t::EXACT_TOPK

当前使用的近似 min-k 计算模式。默认值为 EXACT_TOPK。

ProgressiveDimClusteringParameters cp

聚类参数

ProgressiveDimIndexFactory *assign_index_factory = nullptr

如果非 NULL，则使用此索引进行分配

size_t M

码本数量

std::vector<size_t> nbits

每一步的比特数

std::vector<float> codebooks

码本

std::vector<uint64_t> codebook_offsets

码本 #1 存储在码本表 codebooks 中的行 codebook_offsets[i]:codebook_offsets[i+1] 中，大小为 total_codebook_size by 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 位快速扫描

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

每个索引向量的字节数

公共静态属性

static const int Train_default = 0

常规k-means（最少量的计算）

static const int Train_progressive_dim = 1

渐进维度聚类（默认设置）

static const int Train_refine_codebook = 2

在第一级估计后进行几次码本细化迭代

static const int Train_top_beam = 1024

如果在train_type上设置此位，则仅在beam的第一个元素上训练beam（更快但不太准确）

static const int Skip_codebook_tables = 2048

设置此位以不在训练后自动计算码本表