PQ

介绍

本章节主要介绍openGauss数据库DataVec向量引擎PQ（Product Quantization）特性的安装使用步骤，以指导用户顺利完成操作。本特性将DataVec向量引擎和自研PQ算法相结合，以提高向量检索的查询性能。

限制：
PQ特性暂时只支持ARM架构环境。
PQ特性暂时只支持HNSW和IVF索引。
PQ特性暂时只支持vector数据类型，在其他向量数据类型构建HNSW-PQ以及IVF-PQ索引会导致执行失败。
在创建PQ索引前需要先插入数据，无数据情况下会创建失败。
创建PQ索引时表中的数据量小于pq_ksub可以正常创建索引，但会提示参与训练码本的数据量较少，召回率可能会偏低。
创建IVF-PQ索引时，如果表数据量小于索引选项lists，会提示召回率低。
PQ不支持ustore表建立索引。

安装准备

环境要求

PQ特性只支持ARM架构环境。

1. 容器化部署openGauss

详见容器镜像安装。

2. 获取PQ检索加速安装包

加速包默认安装路径为/usr/local/sra_recall。

wget https://kunpeng-repo.obs.cn-north-4.myhuaweicloud.com/Kunpeng%20BoostKit/Kunpeng%20BoostKit%2025.0.RC1/BoostKit-SRA_Recall-1.1.0.zip
unzip BoostKit-SRA_Recall-1.1.0.zip

3. 拷贝检索加速包至openGauss容器内安装

执行语句中的CONTAINER_ID为openGauss Docker容器ID，请根据实际情况进行替换。

docker cp  boostkit-sra_recall-1.1.0-1.aarch64.rpm CONTAINER_ID:/home/omm
docker exec -it CONTAINER_ID bash
cd /home/omm
rpm -ivf boostkit-sra_recall-1.1.0-1.aarch64.rpm

4. 容器内变量配置

在容器内修改环境配置

cd /
vi entrypoint.sh
export DATAVEC_PQ_LIB_PATH=/usr/local/sra_recall/lib

修改数据库参数配置，添加enable_pq=on

vi /var/lib/opengauss/data/postgresql.conf

重启Docker容器。

docker restart CONTAINER_ID

启用PQ特性

设置GUC参数enable_pq = on启用PQ特性，详情请参考DataVec向量引擎参数。

关闭PQ特性

设置GUC参数enable_pq = off关闭PQ特性，详情请参考DataVec向量引擎参数。

使用PQ

HNSW-PQ

openGauss=# CREATE INDEX [INDEX_NAME] 
ON [TABLE_NAME] 
USING hnsw (COLUMN_NAME [TYPE]_[DISTANCE_FUN]_ops) 
with (m=<M>, ef_construction=<EF_CONSTRUCTION>, enable_pq = on, pq_m = <PQ_M>, pq_ksub = <PQ_KSUB>);

INDEX_NAME - 索引名称
TABLE_NAME - 表名
COLUMN_NAME - 向量数据列名

HNSW-PQ索引操作符

HNSW索引操作符[TYPE]_[DISTANCE_FUN]_ops 格式：

TYPE - 向量类型
- vector

HNSW-PQ索引支持向量数据维度：

名称	维度限制
vector	2,000

DISTANCE_FUN - 距离函数
- l2
- ip
- cosine

vector 索引操作符

索引操作符	描述
vector_l2_ops	L2距离
vector_ip_ops	内积
vector_cosine_ops	余弦距离

索引选项

m - 每个图层最大连接数 2~100（默认为16）
ef_construction - 用于图形构造的动态候选集大小 4~1000，必须大于等于2*m（默认为64）
enable_pq - 开启pq量化压缩（默认off）
pq_m - 切分的子空间数量 1~2000（默认为8）。对于高维向量，pq_m的上限受页面大小限制，可能会在创建索引时报错，并给出当前向量维度对应pq_m的上限，还需结合pq_m的其他限制确定最终值。
示例： 使用L2距离创建HNSW-PQ索引，其中表items中向量为2000维。
```
openGauss=# CREATE INDEX ON items USING hnsw (embedding 	vector_l2_ops) WITH (enable_pq=on, pq_m=2000);
ERROR: vector and pqcode must on the same page, max pq_m is 72
```
对于HNSW-PQ索引，2000维的vector pq_m的最大值是72，由于维度%pq_m=0的限制，pq_m的最大值是50。
pq_ksub - 每个子空间的聚类中心数量 1~256（默认为256）

设置建议：

pq_m：切分子空间越多，精度越高，同时性能越低。该值必须要能整除数据集维度，否则索引无法创建成功，推荐值为维度/4。
pq_ksub：聚类中心越多，精度越高，但同时性能越低。推荐值为256。
其余参数设置与向量索引中HNSW索引中相同。

GUC参数

hnsw_earlystop_threshold - 设置图搜索的最大连续迭代次数 160~INT32_MAX-1 (默认INT32_MAX)
示例： 使用L2距离计算创建HNSW-PQ索引并设置m = 16, ef_construction = 64, pq_m=32，并设置hnsw_earlystop_threshold为320。
```
openGauss=# CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64, enable_pq=on, 		pq_m=32);
openGauss=# SET hnsw_earlystop_threshold = 320;
```

IVF-PQ

openGauss=# CREATE INDEX [INDEX_NAME]
ON [TABLE_NAME]
USING ivfflat (COLUMN_NAME [TYPE]_[DISTANCE_FUN]_ops)
with (lists = <LISTS>, enable_pq = on, pq_m = <PQ_M>, pq_ksub = <PQ_KSUB>, by_residual = on);

INDEX_NAME - 索引名称
TABLE_NAME - 表名
COLUMN_NAME - 向量数据列名

IVF-PQ索引操作符

IVFFLAT索引操作符 [TYPE]_[DISTANCE_FUN]_ops 格式：

TYPE -向量类型
- vector

IVF-PQ索引执行向量数据维度：

名称	维度限制
vector	2,000

DISTANCE_FUN - 距离函数
- l2
- ip
- cosine

vector索引操作符

索引操作符	operator	描述
vector_l2_ops	<->	L2距离
vector_ip_ops	<#>	内积
vector_cosine_ops	<=>	余弦距离

索引选项

lists - 倒排表（单元格）聚类中心数量（默认为100）
enable_pq - 开启pq量化压缩（默认off）
pq_m - 仅在enable_pq开启时有效，切分的子空间数量 1~2000（默认为8）。对于高维向量，pq_m的上限受页面大小限制，可能会在创建索引时报错，并给出当前向量维度对应pq_m的上限，还需结合pq_m的其他限制确定最终值。
pq_ksub - 仅在enable_pq开启时有效，每个子空间的聚类中心数量 1~256 （默认256）
by_residual - 仅在enable_pq开启时有效，启用残差运算（默认off）
示例： 使用带残差的L2距离计算创建IVF-PQ索引并设置lists = 200, pq_m = 4, pq_ksub = 256。
```
openGauss=# CREATE INDEX ON items USING ivfflat (embedding 	vector_l2_ops) WITH (lists = 200,
enable_pq = on, pq_m = 4, pq_ksub = 256, by_residual = on);
```

设置建议：

pq_m：切分子空间越多，精度越高，同时性能越低。该值需要能整除数据集维度，推荐值为维度/4。
pq_ksub：聚类中心越多，精度越高，但同时性能越低。推荐值为256。
by_residual：启动残差计算可以提升精度，但是会增加构建索引的时间。推荐值off。
其余参数设置与向量索引中IVFFLAT索引相同。

查询选项

ivfflat_probe - 查询时候选集的大小，参见DataVec向量引擎参数。
示例：
```
openGauss=# SET ivfflat_probes = 10;
```
ivfpq_kreorder - 设置参与精排候选集的大小，参见DataVec向量引擎参数。
示例：
```
openGauss=# SET ivfpq_kreorder = 10;
```