其他功能

IReduction *CreateReduction(std::string typeName, const ReductionConfig &config);

创建具体的降维算法。

std::string typeName：降维算法参数，可选{"NN", "PCAR"}。

ReductionConfig &config：降维参数。

无

IReduction *CreateReduction：创建的具体的降维实例。

目前仅支持使用NN、PCAR两种降维参数，使用其他参数降维会抛异常。

使用完毕该实例后请注意delete此指针，释放对应的空间。

virtual void reduce(idx_t n, const float *x, float *res) const = 0;

降维接口，本函数中不提供具体实现。

idx_t n：待执行推理的输入数量。

const float *x：待执行推理的特征向量。

float* res：执行推理得到的特征向量结果。

无

• 此处“n”的取值范围：0 < n < 1e9。
• 此处指针“x”需要为非空指针，且长度应该为dimIn * n，“res”需要为非空指针，且长度应该为dimOut * n，否则可能出现越界读写错误并引起程序崩溃。

inline ReductionConfig(int dimIn, int dimOut, float eigenPower, bool randomRotation);

ReductionConfig的构造函数，当用户使用“PCAR”降维时，使用该函数。

int dimIn：输入特征维度，即降维前的维度，PCAR需要配置此参数。

int dimOut：输出特征维度，即降维后的维度，PCAR需要配置此参数。

float eigenPower：奇异值的power数，PCAR需要配置此参数。

bool randomRotation：是否进行随机旋转，PCAR需要配置此参数。

无

无

• 使用不同的降维算法，需要配置对应的参数并且降维后的维度需要满足后续使用降维数据Index的维度限制。
• 使用PCAR降维时，需要保证dimOut>0，dimIn ≥ dimOut。eigenPower的范围为[-0.5, 0]。

inline ReductionConfig(std::vector<int> deviceList, const char *model, uint64_t modelSize);

ReductionConfig的构造函数，当用户使用“NN”降维时，使用该函数。

std::vector<int> deviceList：Device侧资源配置。

const char *model：神经网络降维模型。

uint64_t modelSize：模型的大小。

无

无

• deviceList取值范围(0, 32]。
• 使用不同的降维算法，需要配置对应的参数并且降维后的维度需要满足后续使用降维数据Index的维度限制。
• “model”需要为合法有效的深度神经网络推理模型的内存指针，大小为“modelSize”，modelSize取值范围为(0, 128MB]，参数不匹配可能造成模型实例化或推理失败。非法的模型可能会对系统造成危害，请确保模型的来源合法有效。
  • dimsIn ∈ {64, 128, 256, 384, 512, 768, 1024}。
  • dimsOut ∈ {32, 64, 96, 128, 256}。
  • batches ∈ {1, 2, 4, 8, 16, 32, 64, 128}

virtual ~IReduction() = default;

IReduction的析构函数，销毁IReduction对象，释放资源。

无

无

无

无

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

训练的抽象接口，本函数中不提供具体实现。

idx_t n：训练集中特征向量的条数。

const float *x：特征向量数据。

无

无

• 此处“n”的取值范围：0 < n < 1e9。
• 此处指针“x”需要为非空指针，且长度应该为dimIn * n，否则可能出现越界读写错误并引起程序崩溃。

AscendNNInference(std::vector<int> deviceList, const char* model, uint64_t modelSize);

AscendNNInference的构造函数，生成AscendNNInference，此时根据“deviceList”中配置的值设置Device侧昇腾AI处理器资源以及模型路径等。

std::vector<int> deviceList：Device侧设备ID。

const char* model：深度神经网络推理模型。

uint64_t modelSize：深度神经网络推理模型的大小。

无

无

• deviceList取值范围(0, 32]。
• “model”需要为合法有效的深度神经网络推理模型的内存指针，大小为“modelSize”，modelSize取值范围为(0, 128MB]，参数不匹配可能造成模型实例化或推理失败。非法的模型可能会对系统造成危害，请确保模型的来源合法有效。
  • dimsIn ∈ {64, 128, 256, 384, 512, 768, 1024}。
  • dimsOut ∈ {32, 64, 96, 128, 256}。
  • batches ∈ {1, 2, 4, 8, 16, 32, 64, 128}

AscendNNInference(const AscendNNInference&) = delete;

声明此AscendNNInference拷贝构造函数为空，即不可拷贝类型。

const AscendNNInference&：常量AscendNNInference。

无

无

无

~AscendNNInference();

AscendNNInference的析构函数，销毁AscendNNInference对象，释放资源。

无

无

无

无

int getDimBatch() const;

获取模型的单次推理的样本或查询向量的数量。

无

无

模型单次推理的样本或查询向量的数量。

无

int getInputType() const;

获取模型的输入数据类型。

无

无

模型的输入数据类型。

无

int getOutputType() const;

获取模型的输出数据类型。

无

无

模型的输出数据类型。

无

int getDimIn() const;

获取模型的输入数据维度。

无

无

输入数据维度。

无

int getDimOut() const;

获取模型的输出数据维度。

无

无

模型的输出数据维度。

无

void infer(size_t n, const char* inputData, char* outputData) const;

根据网络模型执行推理。

size_t n：待执行推理的输入数量。

const char* inputData：待执行推理的特征向量。

char* outputData：执行推理得到的特征向量结果。

无

• 此处“n”的取值范围：0 < n < 1e9。
• 此处指针“inputData”需要为非空指针，且长度应该为dimIn * n，“outputData”需要为非空指针，且长度应该为dimOut * n，否则可能出现越界读写错误并引起程序崩溃。

AscendNNInference& operator=(const AscendNNInference&) = delete;

声明此Index赋值构造函数为空，即不可拷贝类型。

const AscendNNInference&：常量AscendNNInference。

无

无

无

AscendClonerOptions()

AscendClonerOptions的构造函数。

无

无

无

无

faiss::Index *index_ascend_to_cpu(const faiss::Index *ascend_index);

根据Ascend上的检索index资源，拷贝生成一个CPU上的检索Index。

const faiss::Index *ascend_index：Ascend上的Index资源。

无

生成一个CPU上的检索Index。

使用完毕该接口返回的Index指针后请注意delete掉此指针，释放对应的空间。

faiss::Index *index_cpu_to_ascend(std::initializer_list<int> devices, const faiss::Index *index, const AscendClonerOptions *options = nullptr);

根据CPU上的检索Index资源，拷贝生成一个Ascend上的检索Index。

std::initializer_list<int> devices：NPU上待配置的设备ID。

const faiss::Index *index：CPU上的检索Index资源。

const AscendClonerOptions *options = nullptr：待配置的AscendClonerOptions资源。

无

生成一个Ascend上的检索Index。

• 使用完毕该接口返回的Index指针后请注意delete掉此指针，释放对应的空间。
• “devices”需要为合法有效不重复的设备ID，最大数量为64。
• “index”需要为合法有效的CPU Index指针。

faiss::Index *index_cpu_to_ascend(std::vector<int> devices, const faiss::Index *index, const AscendClonerOptions *options = nullptr);

根据CPU上的检索Index资源，拷贝生成一个Ascend上的检索Index。

std::vector<int> devices：NPU上待配置的设备ID。

const faiss::Index *index：CPU上的检索Index资源。

const AscendClonerOptions *options = nullptr：待配置的AscendClonerOptions资源。

无

生成一个Ascend上的检索Index。

• 使用完毕该接口返回的Index指针后请注意delete掉此指针，释放对应的空间。
• “devices”需要为合法有效不重复的设备ID，最大数量为64。
• “index”需要为合法有效的CPU Index指针。

faiss::Index *index_int8_ascend_to_cpu(const AscendIndexInt8 *index);

根据Ascend上的INT8的检索Index资源，拷贝生成一个CPU上的检索Index。

const AscendIndexInt8 *index：Ascend上的Index资源。

无

生成一个CPU上的检索Index。

• 使用完毕该接口返回的Index指针后请注意delete此指针，释放对应的空间。
• “index”需要为合法有效的AscendIndexInt8指针。

AscendIndexInt8 *index_int8_cpu_to_ascend(std::initializer_list<int> devices, const faiss::Index *index, const AscendClonerOptions *options = nullptr);

根据CPU上的检索Index资源，拷贝生成一个Ascend上的INT8的检索Index。

std::initializer_list<int> devices：NPU上待配置的设备ID。

const faiss::Index *index：CPU上的检索Index资源。

const AscendClonerOptions *options = nullptr：待配置的AscendClonerOptions资源。

无

生成一个Ascend上的INT8的检索Index。

• 使用完毕该接口返回的Index指针后请注意delete此指针，释放对应的空间。
• “devices”需要为合法有效不重复的设备ID，最大数量为64。
• “index”需要为合法有效的CPU Index指针。

AscendIndexInt8 *index_int8_cpu_to_ascend(std::vector<int> devices, const faiss::Index *index, const AscendClonerOptions *options = nullptr);

根据CPU上的检索Index资源，拷贝生成一个Ascend上的INT8的检索Index。

std::vector<int> devices：NPU上待配置的设备ID。

const faiss::Index *index：CPU上的检索Index资源。

const AscendClonerOptions *options = nullptr：待配置的AscendClonerOptions资源。

无

生成一个Ascend上的INT8的检索Index。

• 使用完毕该接口返回的Index指针后请注意delete此指针，释放对应的空间。
• “devices”需要为合法有效不重复的设备ID，最大数量为64。
• “index”需要为合法有效的CPU Index指针。

DiskPQParams {

int pqChunks = 512;

int funcType = 1;

int dim = 1;

char *pqTable = nullptr;

uint32_t *offsets = nullptr;

char *tablesTransposed = nullptr;

char *centroids = nullptr;

}

PQ量化结构体。

无

无

int pqChunks：表示将原始向量维度dim切分为pqChunks块。

int funcType：表示进行PQ查表距离计算时使用的计算标准。

int dim：表示原始数据维度。

char *pqTable：表示存储码本数据的指针。默认值为nullptr。

uint32_t *offsets：表示存储每个chunk在原始维度上起始和截止的维度。默认值为nullptr。

char *tablesTransposed：表示存储码本数据的转置形态指针。默认值为nullptr。

char *centroids：表示存储每个维度的平均值，用于对数据进行中心化处理。默认值为nullptr。

• 1 <= pqChunks <= dim。使用较小pqChunks将使用更少内存，但会带来相应的精度损失。一般情况下，推荐使用pqChunks为dim / 8或者dim / 16（均向上取整）。默认值为512。
• funcType取值范围为1~3。1表示使用L2距离；2表示使用IP距离；3表示使用cosine距离。默认值为1。
• 1 <= dim <= 2000。默认值为1。
• pqTable目前仅支持float数据类型，即OpenGauss数据类型中的Vector数据类型。
• tablesTransposed目前仅支持float数据类型，即OpenGauss数据类型中的Vector数据类型。

VectorArrayData {

int length;

int maxlen;

int dim;

size_t itemsize;

char *items;

}

数据封装结构体。

无

无

int length：表示结构体中存储的向量条数。

int maxlen：表示结构体中存储的最大向量条数。

int dim：表示结构体中存储的向量维度。

size_t itemsize：保留字段，用户可以选择不设置。

char *items：表示存储VectorArrayData中数据的指针。默认值为nullptr。

• 1 <= length <= 100000000。
• maxlen是OpenGauss侧保留字段，非OpenGauss用户设置该值等于length值即可。
• 1 <= dim <= 2000。
• 对于不同接口，用户需要确保items指向不同大小的数据。

int ComputePQTable(VectorArrayData *sample, DiskPQParams *params);

使用sample中存储的采样底库数据计算PQ码本，并将码本相关的数据存储在参数params中的对应参数里。

VectorArrayData *sample：指向填充好采样底库数据的VectorArrayData实例的指针。不能为空指针。

DiskPQParams *params：指向仅包含PQ参数，未填充训练好的PQ数据的DiskPQParams实例的指针。不能为空指针。

无

int：返回值为0时表示流程正常；返回值为-1时表示流程异常，且会将异常日志信息打印到cerr中。

• sample数据填充要求如下：

  items指向的数据大小为(8 + dim) * length * sizeof(float)字节，即每条向量前有8字节的metadata。非OpenGauss用户使用时，需在每条向量数据添加8字节的任意数据。

• params成员变量填充要求如下：
  • dim除满足上述的范围限制要求之外，还需确保与sample中对应的dim字段保持一致。
  • pqTable必须为nullptr，在动态库内部将使用new []关键字进行内存申请，需要使用者在外部对申请的内存进行释放（使用delete []）。内部申请的内存大小确保等于dim * 256 （256为每个chunk内的聚类数）* sizeof(float)字节。
  • offsets必须为nullptr，在动态库内部将使用new []关键字进行内存申请，需要使用者在外部对申请的内存进行释放（使用delete []）。内部申请的内存大小确保等于(pqChunks + 1) * sizeof(uint32_t)字节。
  • tablesTransposed必须为nullptr，在动态库内部将使用new []关键字进行内存申请，需要使用者在外部对申请的内存进行释放（使用delete []）。内部申请的内存大小确保等于dim * 256 * sizeof(float)字节。
  • centroids必须为nullptr，在动态库内部将使用new []关键字进行内存申请，需要使用者在外部对申请的内存进行释放（使用delete []）。内部申请的内存大小确保等于dim * sizeof(float)字节。

int ComputeVectorPQCode(VectorArrayData *baseData, const DiskPQParams *params, uint8_t *pqCode);

使用填充好PQ数据的params，对baseData中的底库数据进行量化，并将量化数据写入pqCode指向的缓存区中。

VectorArrayData *baseData：指向填充好底库数据的VectorArrayData实例的指针。不能为空指针。用户可以根据自身内存的限制，在外层决定baseData中底库数据的大小。

const DiskPQParams *params：指向填充好PQ参数和训练好的PQ数据的DiskPQParams实例的指针。不能为空指针。

uint8_t *pqCode：接收返回的压缩好的底库向量的指针。不能为空指针。

int：返回值为0时表示流程正常；返回值为-1时表示流程异常，且会将异常日志信息打印到cerr中。

• baseData数据填充要求如下：

  items指向的数据大小为length * dim * sizeof(float)字节。注意此处与ComputePQTable接口不同， 无需在每条数据前填充代替metadata的数据。

• params成员变量填充要求如下：
  • dim除满足上述的范围限制要求之外，还需确保与sample中对应的dim字段保持一致。
  • pqTable必须指向内存大小为dim * 256 * sizeof(float)字节数的码本数据。用户需要保证指向的内存大小符合，否则有段错误风险。
  • offsets必须指向内存大小为(pqChunks + 1) * sizeof(uint32_t)字节数的offsets数据。用户需要保证指向的内存大小符合，否则有段错误风险。
  • 对tablesTransposed填充值无要求。
  • centroids必须指向内存大小为dim * sizeof(float)字节数的centroids数据。用户需要保证指向的内存大小符合，否则有段错误风险。
• 用户需保证pqCode指向的空间大小至少有length * pqChunks字节数。其中，length为VectorArrayData参数；pqChunks为DiskPQParams参数。

int GetPQDistanceTable(char *vec, const DiskPQParams *params, float *pqDistanceTable);

使用填充好PQ数据的params，对vec指向的query数据进行ADC PQ距离计算，并将PQ距离表写入pqDistanceTable指向的缓存区中。

char *vec：指向待计算的query数据的指针。

const DiskPQParams *params：指向填充好PQ参数和训练好的PQ数据的DiskPQParams实例的指针。不能为空指针。

float *pqDistanceTable：接收返回的query与每个chunk内每个centroid距离的指针。

int：返回值为0时表示流程正常；返回值为-1时表示流程异常，且会将异常日志信息打印到cerr中。

• 用户需保证vec指向的空间大小至少有dim * sizeof(float)字节数。目前仅支持float数据类型，即OpenGauss数据类型中的Vector数据类型。
• params成员变量填充要求如下：
  • pqTable指向值无要求。
  • offsets必须指向内存大小为(pqChunks + 1) * sizeof(uint32_t)字节数的offsets数据。用户需要保证指向的内存大小符合，否则有段错误风险。
  • tablesTransposed必须指向内存大小为dim * 256 * sizeof(float)字节数的码本数据。用户需要保证指向的内存大小符合，否则有段错误风险。
  • centroids必须指向内存大小为dim * sizeof(float)字节数的centroids数据。用户需要保证指向的内存大小符合，否则有段错误风险。
• 用户需保证pqDistanceTable指向的空间大小至少有pqChunks * 256 * sizeof(float)字节数。

int GetPQDistance(const uint8_t *basecode, const DiskPQParams *params, const float *pqDistanceTable, float &pqDistance);

使用basecode指向的底库向量对应的压缩码字数据和GetPQDistanceTable接口中获取的pqDistanceTable，计算query与该底库向量的PQ距离。

const uint8_t *basecode：指向一个底库向量对应的压缩码字数据的指针。

const DiskPQParams *params：指向填充好pqChunks数值的DiskPQParams实例的指针。不能为空指针。

const float *pqDistanceTable：指向query对应的ADC PQ距离表的指针。

float &pqDistance：接收最终输出的PQ距离的引用值。

int：返回值为0时表示流程正常；返回值为-1时表示流程异常，且会将异常日志信息打印到cerr中。

• 用户需保证basecode指向的数据大小至少有pqChunks个字节。
• 在params中，仅需填充pqChunks值，且与basecode中提到的pqChunks值对应。
• 用户需保证pqDistanceTable指向的数据大小至少有pqChunks * 256 * sizeof(float)字节数。
• 接口中不会在使用前对pqDistance置零，pqDistance最终结果为原pqDistance值 + 输出的query与basecode的PQ距离，因此推荐输入值为0。

std::string GetVersionInfo();

获取版本信息。会根据环境变量MX_INDEX_HOME来获取对应的版本信息，软件包安装时该环境变量会自动设置，无需修改。

无

无

版本信息。

无