## 关于 pgvector pgvector 是一款对高维度向量提供高效相似度搜索能力的插件，该插件具备以下功能： * 支持向量数据类型，能够存储和查询向量数据。 * 支持精确和近似最近邻搜索（Approximate Nearest Neighbor，简称 ANN），支持的距离或相似度度量方法包括欧氏距离（L2 正则化欧氏距离，L2 norm Euclidean Distance）、曼哈顿距离（L1 Manhattan Distance）、余弦相似度（Cosine Similarity）以及内积运算（Inner Product）。 * 最大支持创建 64000 维度的向量，最大支持对 64000 维度的向量建立索引。 * 支持量化索引（Scalar Quantization 和 RaBitQ），通过降低向量存储精度实现更低的内存占用和更快的检索速度，同时保持较高的召回率。 > **说明** > 量化索引能力仅在 0.8.2 版本中提供。 ## 使用插件 ### 创建插件 > **说明** > 需使用高权限账号创建插件。 ```sql create extension vector; ``` ### 查询插件版本 ```sql select * from pg_available_extensions where name='vector'; ``` ### 版本发布记录关于 pgvector 在不同版本中提供的功能，请参见[插件发布记录](https://docs.volcengine.com/docs/87275/2662815#tLivqMBu)。 ### 升级插件可使用以下命令升级 pgvector 插件至最新版本。 ```SQL ALTER EXTENSION vector UPDATE; ``` > **说明** > 如您的 Workspace 是在 2026.07.17 及之后创建，则默认使用 0.8.2 版本的 vector 插件，无需手动升级。 > 如您的 Workspace 是在 2026.07.17 之前创建，只能使用 0.8.0 版本的插件。如您需要在这些 Workspace 中使用 0.8.2 版本的 vector 插件，请[提交工单](https://console.volcengine.com/workorder/create)联系我们升级 Workspace，升级后再执行上述命令升级 vector 插件。 ### 删除插件 ```sql drop extension vector; ``` ## 数据类型 pgvector 提供了 3 种向量数据类型（以下示例基于 vector 类型）。 |类型 |注释 |最大支持维度 |最大构建索引维度 |支持的索引 | |---|---|---|---|---| |vector |表示 32 位浮点型向量 |* 0.8.2_20260615 以及更早版本的插件：16000。

* 0.8.2_20260715 及更新版本的插件：64000。

|* 0.8.2_20260615 及更早版本的插件：2000。

* 0.8.2_20260715 及更新版本的插件：

* RaBitQ none/fp32：64000

* RaBitQ ex4：12000

* RaBitQ ex8 ：7000

* SQ8：8000

* SQ16：4000 |btree、ivfflat、hnsw | |halfvec |表示 16 位浮点型向量 |16000 |4000 |btree、ivfflat、hnsw | |sparsevec |表示稀疏向量，输入格式为`{index1:value1,index2:value2}/dimensions` |1000000000（非零维数16000） |非零维数1000 |btree、hnsw | > **说明** > 最大构建索引维度与量化类型有关。64000 维索引能力仅适用于 vector + RaBitQ none/fp32。普通 HNSW/IVFFlat 为 2000 维，RaBitQ ex4 为 12000 维，RaBitQ ex8 为 7000 维，SQ8 为 8000 维，SQ16 为 4000 维。 ### insert&select ```sql create table tbl_vector (tc1 vector(3), tc2 halfvec(3), tc3 sparsevec(3)); insert into tbl_vector values ('[1,2,3]', '[1,2,3]', '{2:1}/3'); select * from tbl_vector; ``` ## 向量操作符 pgvector 插件为向量类型实现了 14 种操作符。 > **注意** * > 使用操作符计算的两个向量需要有相同的维度。 * > 为方便使用，pgvector 对欧氏距离运算、曼哈顿距离运算、余弦相似度运算、内积运算的结果进行了统一化处理：运算结果越小，表示参与运算的两个向量相似度越高。 * > 曼哈顿距离运算(L1) ANN 仅原生 HNSW 索引支持；IVFFlat、SQ8/SQ16 和 RaBitQ 的 ANN 不支持 L1。 |操作符 |说明 |使用示例 | |---|---|---| |<\-\> |L2 欧氏距离运算 |select tc1 <\-\> '[1,1,1]' as euclidean_distance from tbl_vector order by euclidean_distance ; | |<#\> |负内积运算 |SELECT tc1 <#\> '[1,1,1]' AS nagative_inner_product FROM tbl_vector ORDER BY nagative_inner_product; | |<=\> |余弦距离运算 |SELECT tc1 <=\> '[1,1,1]' AS cosine_distance FROM tbl_vector ORDER BY cosine_distance; | |+ |加 |select tc1 + '[1,1,1]' from tbl_vector; | |\- |减 |select tc1 \- '[1,1,1]' from tbl_vector; | |< |小于 |select \* from tbl_vector where tc1 < '[1,1,1]' ; | |<= |小于等于 |select \* from tbl_vector where tc1 <= '[1,1,1]' ; | |= |等于 |select \* from tbl_vector where tc1 = '[1,1,1]' ; | |<\> |不等于 |select \* from tbl_vector where tc1 <\> '[1,1,1]' ; | |\>= |大于等于 |select \* from tbl_vector where tc1 \>= '[1,1,1]' ; | |\> |大于 |select \* from tbl_vector where tc1 \> '[1,1,1]' ; | |\* |逐元素乘法 |select tc1 \* '[2,2,2]' from tbl_vector; | |<+\> |L1 曼哈顿距离计算 |select tc1 <+\> '[1,1,1]' from tbl_vector; | |\|\| |向量拼接 |select tc1 \|\| '[1,1,1]' from tbl_vector; | ## 索引通常，单表中存储的向量条目（行数）会有上亿之多，为了加速 vector 类型数据的访问和相似度计算，pgvector 提供了三种索引类型：btree 索引、ivfflat 索引和 hnsw 索引。自 0.8.2 版本起，pgvector 新增对量化索引的支持，包括标量量化（SQ8、SQ16）和二进制量化（RaBitQ）。量化索引通过降低向量存储精度来减少内存占用和加速检索，适用于对召回精度有一定容忍度的大规模向量检索场景。 ### 创建索引 * 创建 ivfflat 索引 ```sql drop table tbl_vector ; create table tbl_vector(id serial, tc1 vector(5)); create index tbl_vector_tc1_idx on tbl_vector using ivfflat (tc1) with (lists = 4); ``` > **说明** * > 创建 ivfflat 索引时如不指定 opclass ，默认使用 `vector_l2_ops`。 * > ivfflat 索引要求被索引的 vector 列维度必须小于等于 2000。 * > ivfflat 不支持多列索引。 * > ivfflat 索引核心用于 KNN ORDER BY。查询可以同时带普通 WHERE 过滤；距离表达式也可以写成布尔条件，但 ivfflat opclass 本身不作为普通 WHERE 谓词索引。 * > ivfflat 索引仅仅适用于 order by，不适用于 where 过滤。因为 where 条件只能用于 bool 类型或者 bool 表达式，而 ivfflat 的操作符（<\-\>、<=\>、<#\>）的返回值不是 bool 类型。 * > 索引扫描时，召回率取决于 ivfflat.probes 和创建索引时指定的 lists 值。ivfflat.probes 值越高，召回率越高，索引扫描性能越低，ivfflat.probes 越低，召回率越低，索引扫描性能越高。召回率最高的是顺序扫描。 * 创建 hnsw 索引 ```sql drop table tbl_vector; create table tbl_vector(id serial, tc1 vector(5)); create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_l2_ops) with (m = 5, ef_construction = 10); ``` > **说明** * > hnsw 索引要求被索引的 vector 列维度必须小于等于 2000。 * > hnsw 不支持多列索引。 * > hnsw 索引核心用于 KNN ORDER BY。查询可以同时带普通 WHERE 过滤；距离表达式也可以写成布尔条件，但 hnsw opclass 本身不作为普通 WHERE 谓词索引。 * 创建 btree 索引 ```sql drop table tbl_vector; create table tbl_vector(id serial, tc1 vector(100)); insert into tbl_vector (tc1) select array_agg(random())::vector(100) from generate_series(1.0,100.0) ; create index on tbl_vector (tc1); ``` > **说明** * > 使用 vector 类型的 btree 索引不用于 ANN/KNN 相似度搜索。 * > 创建 btree 索引时，当前 8KB page 配置下 vector 维度小于等于 672 维可建；673 维及以上会超过 btree 单条索引记录大小上限。 * > 实际使用中，建议将需要创建 btree 索引的向量维度控制在 500 维以内，防止因为 toast 访问引起索引扫描效率下降等问题。 * 查询索引当前的构建进度 > **说明** > 该功能仅在 pgvector 0.6.2 及更高版本实例中提供。 ```sql vtest=# SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index; phase | % --------------------------------+----- building index: loading tuples | 8.6 (1 row) ``` ## 使用量化索引 pgvector 0.8.2 版本新增的量化索引能力，支持以下两种量化方式： * **标量量化（Scalar Quantization）** ：将原始 32 位浮点向量压缩为 8 位（SQ8）或 16 位（SQ16）整数表示，在保持较高召回率的前提下，显著降低索引的内存占用和提升检索速度。 * **二进制量化（RaBitQ）** ：将向量二值化为二进制表示，通过极致压缩实现最低的内存占用和最快的检索速度。RaBitQ 还支持 IVFFlat in\-filter 模式，可在索引扫描时进行条件过滤。量化索引适用于以下场景： * 向量数据量大，内存资源有限，需要降低索引的内存占用。 * 对检索延迟敏感，愿意用少量召回精度换取更快的检索速度。 * 需要在大规模数据集上实现高吞吐量的 ANN 检索。 ### 前提条件使用量化索引前，请确认以下条件： |**条件** |**说明** | |---|---| |Workspace 版本 |2026.07.17 及之后创建的 Workspace，或 2026.07.17 之前创建但提交工单升级了的 Workspace。 | |插件版本 |需升级插件至 0.8.2 版本。 | |账号权限 |需使用高权限账号执行插件升级和索引创建操作。 | ### 使用标量量化（SQ8/SQ16）标量量化通过将 32 位浮点向量压缩为低精度整数（8 位或 16 位），减少索引的内存占用。SQ8/SQ16 均支持 L2 欧氏距离、内积和余弦相似度三种距离计算方式。 #### 创建 SQ8 量化索引使用 HNSW 索引配合 SQ8 量化： ```SQL -- 创建测试表 CREATE TABLE tbl_sq_test(id serial, embedding vector(1536)); -- 插入测试数据 INSERT INTO tbl_sq_test (embedding) SELECT array_agg(random())::vector(1536) FROM generate_series(1, 1536) AS g1, generate_series(1, 10000) AS g2 GROUP BY g2; -- 创建 SQ8 量化的 HNSW 索引（L2 距离） CREATE INDEX idx_sq8_l2 ON tbl_sq_test USING hnsw (embedding sq8_vector_l2_ops); -- 创建 SQ8 量化的 HNSW 索引（余弦距离） CREATE INDEX idx_sq8_cosine ON tbl_sq_test USING hnsw (embedding sq8_vector_cosine_ops); -- 创建 SQ8 量化的 HNSW 索引（内积） CREATE INDEX idx_sq8_ip ON tbl_sq_test USING hnsw (embedding sq8_vector_ip_ops); ``` 使用 SQ8 量化索引进行查询： > 示例中查询的向量为伪代码，实际查询时请替换为完整的 1536 维向量。 ```SQL -- L2 距离查询 SELECT id FROM tbl_sq_test ORDER BY embedding <->'[1,2,3,...,1536]' LIMIT 10; -- 余弦距离查询 SELECT id FROM tbl_sq_test ORDER BY embedding <=> '[1,2,3,...,1536]' LIMIT 10; -- 负内积查询 SELECT id FROM tbl_sq_test ORDER BY embedding <#> '[1,2,3,...,1536]' LIMIT 10; ``` #### 创建 SQ16 量化索引 SQ16 量化的使用方式与 SQ8 类似，精度介于 SQ8 和原始 32 位浮点之间： ```SQL -- 创建 SQ16 量化的 HNSW 索引（余弦距离） CREATE INDEX ON tbl_sq_test USING hnsw (embedding sq16_vector_cosine_ops); -- 创建 SQ16 量化的 IVF 索引（内积） CREATE INDEX ON tbl_sq_test USING ivfflat (embedding sq16_vector_ip_ops) WITH (lists = 1000); ``` 使用 SQ16 量化索引进行查询： > 示例中查询的向量为伪代码，实际查询时请替换为完整的 1536 维向量。 ```SQL -- L2 距离查询 SELECT id FROM tbl_sq_test ORDER BY embedding <-> '[0.1, 0.2, ...]' LIMIT 10; -- 余弦距离查询 SELECT id FROM tbl_sq_test ORDER BY embedding <=> '[0.1, 0.2, ...]' LIMIT 10; -- 负内积查询 SELECT id FROM tbl_sq_test ORDER BY embedding <#> '[0.1, 0.2, ...]' LIMIT 10; ``` ### 使用二进制量化（RaBitQ） RaBitQ 是一种高效的二进制量化方法，通过将向量二值化为紧凑的二进制表示实现极致的压缩比。RaBitQ 支持 L2 欧氏距离、内积和余弦相似度三种距离计算方式。通过索引参数 `rabitq_enable=true` 开启。 #### 精排 (refine) RabitQ 量化的搜索流程为 1\-bit 粗排+ 精排以达到较高的召回率。目前支持 4 种精排 (refine) 类型：`none`, `fp32`, `ex4`, `ex8`。下面是详细说明： |**精排类型** |**描述** |**索引大小** |**索引参数** | |---|---|---|---| |none |仅粗排，无精排，召回率较低但是速度最快 |小 |`rabitq_refine_type = 'none'` | |fp32 |粗排后通过回表查询原向量（fp32) 进行精排。优点是节省空间，缺点是会有额外的回表开销。 |小 |`rabitq_refine_type = 'fp32'`

| |ex4

> **说明**

> 仅 0.8.2_20260715 及更新版本的插件支持。
|索引中额外存储 4\-bit ex_code，粗排后通过 ex_code 进行精排。速度比 fp32 快但是会使用额外的索引空间。 |中 |`rabitq_refine_type = 'ex4'` | |ex8

> **说明**

> 仅 0.8.2_20260715 及更新版本的插件支持。
|索引中额外存储 8\-bit ex_code，粗排后通过 ex_code 进行精排。速度比 fp32 快但是会使用更多额外的的索引空间 |大 |`rabitq_refine_type = 'ex8'`

| #### 创建 RaBitQ 量化索引 > **注意** > 使用 RaBitQ HNSW 量化算法需要表中有数据，RaBitQ IVFFlat 可以在空表构建，但会使用随机中心导致召回下降。RaBitQ 量化索引适合较大数据量，建议表中数据大于 1 万条后创建 RabitQ 索引。 **准备测试表和数据**： ```SQL DROP TABLE IF EXISTS items CASCADE; CREATE TABLE items ( id serial, embedding vector(1536) ); INSERT INTO items (embedding) SELECT array_agg(random() ORDER BY d)::vector(1536) FROM generate_series(1, 1536) AS d CROSS JOIN generate_series(1, 10000) AS g GROUP BY g; ``` **创建 RabitQ 量化索引**： ```SQL -- HNSW + RaBitQ，默认 fp32 精排（推荐起步配置） CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (rabitq_enable = true); -- 创建无精排索引，召回率一般为 80% 以上 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (rabitq_enable = true, rabitq_refine_type = 'none'); -- 创建fp32 精排索引，召回率可达90% 以上 CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 128, rabitq_enable = true, rabitq_refine_type = 'fp32', rabitq_nc = 16); -- 创建 ex4 精排索引，召回率可达90% 以上 CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 128, rabitq_enable = true, rabitq_refine_type = 'ex4', rabitq_nc = 16); -- 创建 ex8 精排索引，召回率可达90% 以上 CREATE INDEX items_embedding_ivf_ex_idx ON items USING ivfflat (embedding vector_l2_ops) WITH ( lists = 1000, rabitq_enable = true, rabitq_refine_type = 'ex8' ); -- IVFFlat + RaBitQ，l2 距离 CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 1000, rabitq_enable = true, rabitq_refine_type = 'fp32'); -- IVFFlat + RaBitQ，余弦距离 CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 1000, rabitq_enable = true); ``` **使用 RaBitQ 量化索引进行查询**： > 示例中查询的向量为伪代码，实际查询时请替换为完整的 1536 维向量。 ```SQL -- 查询：操作符要与操作符类匹配（l2 用 <->，余弦用 <=>，负内积用 <#>） SET hnsw.ef_search = 170; SELECT id FROM items ORDER BY embedding <-> '[0.1, 0.2, ...]' LIMIT 10; ``` #### 使用 IVFFlat in\-filter IVFFlat in\-filter 功能仅限 RaBitQ 量化使用。该功能允许在 IVFFlat RabitQ 索引扫描过程中进行条件过滤，优化高过滤率条件下的近似最近邻搜索性能。 **创建 IVFFlat + RaBitQ 索引** ```SQL -- 创建带有标量过滤列的测试表 CREATE TABLE tbl_rabitq_filter ( id serial, category int, embedding vector(1536) ); -- 插入测试数据 INSERT INTO tbl_rabitq_filter (category, embedding) SELECT (random() * 10)::int, array_agg(random() ORDER BY d)::vector(1536) FROM generate_series(1, 100000) AS g CROSS JOIN generate_series(1, 1536) AS d GROUP BY g; -- 创建 IVFFlat + RaBitQ 索引（L2 距离） CREATE INDEX idx_rabitq_ivfflat ON tbl_rabitq_filter USING ivfflat (embedding vector_l2_ops) WITH (lists = 100, rabitq_enable = true); ``` **使用 in\-filter 优化带条件的近似最近邻查询** > 示例中查询的向量为伪代码，实际查询时请替换为完整的 1536 维向量。 ```SQL -- 设置 IVFFlat in-filter 参数 SET ivfflat.probes = 10; SET ivfflat.rabitq_infilter = on; -- 带过滤条件的 ANN 查询 SELECT id, category FROM tbl_rabitq_filter WHERE category = 5 ORDER BY embedding <-> '[1,2,3,...,1536]'::vector LIMIT 10; ``` #### 使用 IVFFlat pre\-filter IVFFlat pre\-filter 功能支持 RaBitQ 量化 / 原生 IVF 索引使用（0.8.2_20260715 及更新版本）。该功能允许在 IVFFlat KNN 搜索前进行条件过滤，优化高过滤率条件下的近似最近邻搜索性能。 **使用 pre\-filter 优化带条件的近似最近邻查询** > **说明** * > 示例中查询的向量为伪代码，实际查询时请替换为完整的 1536 维向量。 * > 使用 pre\-filter 时，过滤条件需要有可用的标量索引，以生成 Bitmap Index Scan。 ```SQL -- 设置 IVFFlat pre-filter 参数 SET ivfflat.probes = 10; SET ivfflat.prefilter = on; -- 带过滤条件的 ANN 查询 SELECT id, category FROM tbl_rabitq_filter WHERE category = 5 ORDER BY embedding <-> '[1,2,3,...,1536]'::vector LIMIT 10; ``` **Explain 示例** ```SQL Custom Scan (VectorPrefilterScan) on tbl_rabitq_filter -> Index Scan using idx_rabitq_ivfflat -> Bitmap Index Scan using idx_rabitq_category ``` ### 量化索引参数说明以下为量化索引相关的函数和参数汇总。 |**参数** |**何时使用** |**默认** |**范围 / 取值** |**作用域** |**说明** | |---|---|---|---|---|---| |`rabitq_enable` |创建索引时指定。 |false |true / false |hnsw, ivfflat |是否开启 RaBitQ 二进制量化。

| |`rabitq_refine_type` |创建索引时指定。 |fp32 |none / fp32/ ex4 / ex8 |hnsw, ivfflat

|RabitQ 精排策略。none=无精排，fp32=真实距离精排，ex4/ex8= 4/8 bit extended RabitQ。 | |`rabitq_rerank_in_table`

|创建索引时指定。 |true

|true / false

|仅 ivfflat |rabitq_rerank_in_table = true 表示 fp32 rerank 从 heap 回表取原向量，索引更小但有回表开销。 | |`rabitq.enabled_by_default`

|查询前通过 SET 指定的 GUC；不是 CREATE INDEX reloption。 |off

|on / off |hnsw, ivfflat |打开后，用户在未指定量化类型时，默认创建 RabitQ 量化索引。

> **说明**

> 0.8.2_20260715 及更新版本支持。
| |`rabitq_nc` |创建索引时指定。 |16 |1 – 256 |仅 hnsw |全局质心数； | |`rabitq.query_bits` |查询时指定。 |8 |1 – 8 |hnsw, ivfflat |查询量化精度；越高召回率越高，吞吐会略微降低。 | |`rabitq.epsilon`

|查询时指定。 |1.9 |0.0 – 4.0 |hnsw, ivfflat |惰性精排误差界乘子；越大越宽松、收更多候选、召回更高 | 各量化方式支持的距离操作符（opclass）汇总： |**量化方式** |**L2 距离** |**余弦相似度** |**内积** | |---|---|---|---| |SQ8 |`sq8_vector_l2_ops` |`sq8_vector_cosine_ops` |`sq8_vector_ip_ops` | |SQ16 |`sq16_vector_l2_ops` |`sq16_vector_cosine_ops` |`sq16_vector_ip_ops` | |RaBitQ |`vector_l2_ops + rabitq_enable=true` |`vector_cosine_ops + rabitq_enable=true` |`vector_ip_ops + rabitq_enable=true` | > **说明** > 标量量化（SQ8/SQ16）和二进制量化（RaBitQ）不支持基于曼哈顿距离（L1 Manhattan Distance）的最近邻搜索（Approximate Nearest Neighbor）。 ### rabitq_last_scan_stats() 函数 `rabitq_last_scan_stats()` 函数用于查看最近一次 RaBitQ 索引扫描的统计信息，可帮助用户评估索引扫描的效率和召回质量。 > **说明** * > `rabitq.track_scan_stats` 默认关闭；关闭时不会展示统计结果。 * > 返回的是当前连接上一条 SQL 中最后一次完成的 RaBitQ scan；如果上一条 SQL 没有发生 RaBitQ scan，则返回空结果。 **返回字段说明** |**字段** |**类型** |**含义** | |---|---|---| |indexname |text |本次扫描使用的索引名，不包含 schema。 | |am |text |索引访问方法，取值为 `hnsw` 或 `ivfflat`。 | |mode |text |RaBitQ 扫描模式：

* `rabitq_approx` 表示仅使用近似距离。

* `rabitq_refined` 表示启用了 fp32、ex4 或 ex8 精排。 | |candidates_scanned |bigint |粗排阶段扫描并进入候选处理的数量。

* HNSW 中表示第 0 层访问的节点数。

* IVFFlat 中表示有效且通过前置过滤的候选数。 | |candidates_refined |bigint |从候选集合中取出并尝试进行精确距离计算的候选数。 | |heap_fetches |bigint |RaBitQ 精排或内置过滤过程中发起的 heap tuple 获取次数。 | |limit_hit |boolean |是否因为内部限制而停止继续扫描 topK 结果，等价于 `limit_cause <> 'none'`。 | |limit_cause |text |扫描停止原因：

* `none`：未出现内部限制导致的扫描停止。

* `scan_tuples`：第 0 层累计访问的 HNSW element 数达到 hnsw.max_scan_tuples。

* `mem`：HNSW 扫描临时内存超过允许值：work_mem × hnsw.scan_mem_multiplier。

* `probe_limit`：当前查询允许访问的倒排 lists（ivfflat.probes）已经全部扫描完。 | |nodes_visited |bigint |* HNSW 访问的节点总数，包含上层导航和第 0 层。

* IVFFlat 中为 `0`。 | |probes_visited |bigint |* IVFFlat 实际访问的 probe/list 次数。

* HNSW 中为 `0`。 | |bounded_pool_used |boolean |* IVFFlat 是否实际使用有容量上限的候选池。

* HNSW 中为 `false`。 | |pool_capacity |bigint |IVFFlat 有界候选池容量；多轮扫描时记录使用过的最大容量。未使用时为 `0`。 | |pool_replacements |bigint |IVFFlat 有界候选池已满后，新候选优于当前最差候选并将其替换的次数。 | |pool_rejections |bigint |IVFFlat 有界候选池已满后，新候选不够好而被拒绝的次数。 | |pool_shortfall_replay |boolean |IVFFlat 有界池候选耗尽但仍需更多结果时，是否以无界方式重新扫描了相同 probes。 | |work_mem_fallback |boolean |IVFFlat 是否因 work_mem 内存限制而切换到可 spill 的 tuplesort/无界存储路径（work_mem 内存不足导致使用临时文件，性能下降）。 | |adjacency_pool_used |boolean |HNSW RaBitQ shared\-cache adjacency pool 是否命中；非 HNSW shared\-cache adjacency 路径为 false。 | |adjacency_epoch_mismatch |boolean |HNSW adjacency pool epoch 不匹配后是否回退到普通邻接读取。 | |adjacency_fallbacks |bigint |HNSW adjacency pool 未命中或回退次数。 | **使用示例** > 示例中查询的向量为伪代码，实际查询时请替换为完整的 1536 维向量。 ```SQL SET rabitq.track_scan_stats = on; SELECT id FROM items ORDER BY embedding <-> $$[1,2,3]$$::vector LIMIT 10; SELECT * FROM rabitq_last_scan_stats(); ``` ## 索引参数 ### ivfflat 索引参数以下参数，分别用于 ivfflat 索引创建和索引扫描： |**参数** |**何时使用** |**默认** |**范围** |**说明** | |---|---|---|---|---| |`lists` |创建索引时指定。 |100

|1 – 32768 |表示往索引中的数据集分成的列表数。该值越大，查询效率就越快。lists 值不宜过大，千万级别向量建议设置在 2000 以内。 | |`ivfflat.probes` |查询时指定，索引扫描时使用。 |1 |1 – lists |在本次索引扫描过程中，搜索的列表数目。该值越大，召回率越高，但索引扫描效率有所降低。 | |`ivfflat.iterative_scan` |查询时指定，索引扫描时使用。 |off |off / relaxed_order |若设置为 "relaxed_order"，在查询时，会扩大索引扫描的范围，获得更高的召回率。 | |`ivfflat.max_probes` |查询时指定，索引扫描时使用。 |32768 |1 – 32768 |IVF 索引查询时最多扫描的列表数量。`ivfflat.iterative_scan` 设置为 "relaxed_order" 时生效。 | |`ivfflat.prefilter`

> **说明**

> 0.8.2_20260715 及更新版本支持。
|查询时指定，索引扫描时使用。 |off |on / off |开启 IVFFlat 索引的 pre\-filter 模式，允许在索引扫描前进行 WHERE 条件过滤。 | |`ivfflat.prefilter_max_candidate_ratio`

> **说明**

> 0.8.2_20260715 及更新版本支持。
|查询时指定，索引扫描时使用。 |0.30 |0.0 – 1.0 |pre\-filter 允许的标量候选比例上限。 | |`ivfflat.prefilter_max_membership_mem`

> **说明**

> 0.8.2_20260715 及更新版本支持。
|查询时指定，索引扫描时使用。 |0 KB（使用 work_mem） |0 – MAX_KILOBYTES |pre\-filter membership 内存预算，超过后禁用 pre\-filter。

| |`ivfflat.rabitq_infilter`

> **说明**

> 0.8.2_20260615 及更新版本支持。
|查询时指定，索引扫描时使用。 |off |on / off

|开启 IVFFlat 索引的 in\-filter 模式，允许在索引扫描时进行 WHERE 条件过滤。仅 RaBitQ 支持。 | |`ivfflat.rabitq_refine_ratio`

> **说明**

> 0.8.2_20260615 及更新版本支持。
|查询时指定，索引扫描时使用。 |3.0 |1.0 – 1000.0 |开启 `ivfflat.rabitq_bounded_pool` 时，IVF 纯向量 LIMIT 查询最多保留 ratio × LIMIT_K 个候选。 | |`ivfflat.rabitq_bounded_pool`

> **说明**

> 0.8.2_20260615 及更新版本支持。
|查询时指定，索引扫描时使用。 |on |on / off

|IVF 纯向量 LIMIT 查询是否使用有界候选池。打开会减小进入精排的候选个数，从而提高吞吐。 | ### hnsw 索引参数以下参数，分别用于 hnsw 索引的创建和扫描： |**参数** |**何时使用** |**默认** |**范围** |**含义** | |---|---|---|---|---| |`m` |创建索引时指定，insert 时使用。 |16 |2 \- 100 |表示每个点需要与图中其他的点建立的连接数。通常 m 越大召回率越高，同时内存消耗越大。 | |`ef_construction`查询时指定，索引扫描时使用。 |创建索引时指定，insert 时使用。 |64 |4 \- 1000 |表示构建索引时动态候选集合的大小。ef_construction 必须大于等于 2 \* m，通常设置为 m 值的 2 倍。 | |`hnsw.ef_search` |查询时指定，索引扫描时使用。 |40 |1 \- 1000 |通常 hnsw.ef_search 越大搜索准确度越高，同时消耗的时间越长。 | |`hnsw.iterative_scan` |查询时指定，索引扫描时使用。 |off |off / relaxed_order/ strict_order |若设置为 "relaxed_order" 或 "strict_order"，在查询时，会扩大索引扫描的范围。 | |`hnsw.max_scan_tuples` |查询时指定，索引扫描时使用。 |20000 |1\-INT_MAX |限制扩大索引扫描时访问的最大 tuple 数量。 | |`hnsw.scan_mem_multiplier` |查询时指定，索引扫描时使用。 |1 |1 \- 1000 |设置扩大索引扫描时使用的内存为 work_mem 的倍数。 | |`hnsw.prefetch_neighbors`

|查询时指定，索引扫描时使用。 |on |on / off |搜索时预取邻居页面。 | 以下三个参数，可以用于加快 hnsw 索引构建速度： |参数 |含义 | |---|---| |`max_parallel_workers` |设置系统的最大并行进程数量，默认值为 8。 | |`max_parallel_maintenance_workers` |设置单一工具性命令（例如 CREATE INDEX）的最大并行进程数。 | |`maintenance_work_mem` |指定在维护性操作（例如 VACUUM、CREATE INDEX）中使用的最大的内存量。 | ## 使用示例 * 创建并使用 btree 索引。 ```sql drop table tbl_vector ; create table tbl_vector (id serial, tc1 vector(5)); insert into tbl_vector (tc1) select array_agg(random())::vector(5) from generate_series(1.0,5.0) ; create index on tbl_vector (tc1); select * from tbl_vector order by tc1; ``` * 创建 ivfflat 索引，并使用 `vector_l2_ops`，进行欧式距离相似性搜索。 ```sql drop table tbl_vector ; create table tbl_vector(id serial, tc1 vector(5)); insert into tbl_vector (tc1) select array_agg(random())::vector(5) from generate_series(1.0,5.0) ; create index tbl_vector_tc1_idx on tbl_vector using ivfflat (tc1) with (lists = 4); -- 高召回率 set ivfflat.probes = 4; -- 将 ivfflat.probes 调整成和索引的 lists 值一样，表示扫描所有列表， select * from tbl_vector order by tc1 <-> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; -- 低召回率 set ivfflat.probes = 1; -- 将 ivfflat.probes 调整成小于索引的 lists 值，表示扫描部分列表 select * from tbl_vector order by tc1 <-> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; ``` * 创建 ivfflat 索引，并使用 `vector_cosine_ops`，进行余弦相似性搜索。 ```sql drop index tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using ivfflat (tc1 vector_cosine_ops) with (lists = 4); -- 高召回率 set ivfflat.probes = 4; -- 将 ivfflat.probes 调整成和索引的 lists 值一样，表示扫描所有列表， select * from tbl_vector order by tc1 <=> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; -- 低召回率 set ivfflat.probes = 1; -- 将 ivfflat.probes 调整成小于索引的 lists 值，表示扫描部分列表 select * from tbl_vector order by tc1 <=> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; ``` * 创建 ivfflat 索引，并使用 `vector_ip_ops`，进行内积相似性搜索。 ```sql drop index tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using ivfflat (tc1 vector_ip_ops) with (lists = 4); -- 高召回率 set ivfflat.probes = 4; -- 将 ivfflat.probes 调整成和索引的 lists 值一样，表示扫描所有列表， select * from tbl_vector order by tc1 <#> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; -- 低召回率 set ivfflat.probes = 1; -- 将 ivfflat.probes 调整成小于索引的 lists 值，表示扫描部分列表 select * from tbl_vector order by tc1 <#> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; ``` * 并行创建 hnsw 索引，并使用 `max_parallel_workers`、`max_parallel_maintenance_workers` 和 `maintenance_work_mem` 参数。 ```sql set maintenance_work_mem = '1GB'; set max_parallel_workers = 4; set max_parallel_maintenance_workers = 4; drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_l2_ops) with (m = 10, ef_construction = 20); ``` * 创建 hnsw 索引，并使用 `vector_l2_ops`，进行欧式距离相似性搜索。 ```sql -- 高召回率 drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_l2_ops) with (m = 10, ef_construction = 20); set hnsw.ef_search = 10; select * from tbl_vector order by tc1 <-> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; -- 低召回率 drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_l2_ops) with (m = 5 , ef_construction = 10); set hnsw.ef_search = 10; select * from tbl_vector order by tc1 <-> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; ``` * 创建 hnsw 索引，并使用 `vector_cosine_ops`，进行余弦相似性搜索。 ```sql -- 高召回率 drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_cosine_ops) with (m = 10, ef_construction = 20); set hnsw.ef_search = 10; select * from tbl_vector order by tc1 <=> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; -- 低召回率 drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_cosine_ops) with (m = 5 , ef_construction = 10); set hnsw.ef_search = 10; select * from tbl_vector order by tc1 <=> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; ``` * 创建 hnsw 索引，并使用`vector_ip_ops`，进行内积相似性搜索。 ```sql -- 高召回率 drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_ip_ops) with (m = 10, ef_construction = 20); set hnsw.ef_search = 10; select * from tbl_vector order by tc1 <#> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; -- 低召回率 drop index IF EXISTS tbl_vector_tc1_idx; create index tbl_vector_tc1_idx on tbl_vector using hnsw (tc1 vector_ip_ops) with (m = 5 , ef_construction = 10); set hnsw.ef_search = 10; select * from tbl_vector order by tc1 <#> '[0.559782,0.194308,0.454407,0.0176121,0.442676]'; ``` > **说明** > 以上示例代码中的高召回率和低召回率仅代表设定场景下的结果，实际情况下需要根据业务模型进行调整。 ## 聚合函数 pgvector 插件为向量类型提供了两个聚合函数 `avg()` 和 `sum()`。 * `avg()` 函数用于计算向量每一维度的平均值，使用方法如下示例所示： ```sql drop table tbl_vector ; create table tbl_vector(id serial, tc1 vector(5)); insert into tbl_vector (tc1) select array_agg(random())::vector(5) from generate_series(1.0,5.0) ; select avg(tc1) from tbl_vector; select id, avg(tc1) from tbl_vector group by id; ``` * `sum()` 函数用于对 vector 的每一维度进行求和，使用方法如下示例所示： ```sql insert into tbl_vector (tc1) select array_agg(random())::vector(5) from generate_series(1.0,5.0) ; select sum(tc1) from tbl_vector; select id, sum(tc1) from tbl_vector group by id; ``` ## 类型转换 pgvector 插件提供了向量类型和几种数组类型的转换。 |**转换类型** |**使用示例** | |---|---| |将 vector 转换为 vector |```sql```
```select '[0.802642,0.339995,0.440122,0.476725,0.449537]'::vector;```
| |将 vector 转换为 real[ ] |```sql```
```select vector('[0.802642,0.339995,0.440122,0.476725,0.449537]')::real[];```
| |将 real[ ] 转换为 vector |```sql```
```select '{0.802642,0.339995,0.440122,0.476725,0.449537}'::real[]::vector;```
| |将 int4[ ] 转换为 vector |```sql```
```select '{1,2,3,4,5}'::int4[]::vector;```
| |将 double precision[ ] 转换为 vector |```sql```
```select '{0.864488503430039,0.798674516845495,0.90717526525259,0.756084795109928,0.639521076343954}'::double precision[]::vector;```
| |将 numeric[ ] 转换为 vector |```sql```
```select '{0.864488503430039,0.798674516845495,0.90717526525259,0.756084795109928,0.639521076343954}'::numeric[]::vector;```
| ## pgvector 向量运算性能介绍在向量化场景中，典型场景是存储经过大语言模型（Large Language Model，简称 LLM）（比如：[text-embedding-ada-002](https://platform.openai.com/docs/guides/embeddings)）处理过后的 embeddings 向量（维度固定为 1536 维），并计算他们的相似度。本文以此场景为参考，验证不同数据量、不同线程数、不同并发数、不同索引和不同参数取值，对数据库 TPS 和时延的影响。 ### 测试参数 |测试参数 || |---|---| |测试并发数 |6/16 | |测试线程数 |1/4 | |测试时间 |60s | |PostgreSQL实例规格 |单 AZ 一主一备 32C64G | |客户端规格 |32vCPU128GiB 极速型 SSD PL0 40 GiB | ### 测试流程 |测试步骤 |语句 | |---|---| |创建插件 |```sql```
```create extension vector;```
| |创建表和索引 |```sql```
```create table tbl_embedding(id serial, embedding vector(1536));```
```-- 创建 l2 索引```
```create index on tbl_embedding using hnsw (embedding vector_l2_ops) with (m = 16, ef_construction = 64);```
| |创建函数，生成指定维度的 embedding 数据 |```sql```
```create or replace function gen_embeddings(dim int)```
``` returns vector```
```as $$```
``` select array_agg(random())::vector from generate_series(1, dim)```
```$$```
```language sql```
```volatile```
```cost 1;```
| |导入 10 万条数据 |```sql```
```-- 导入 10W 条数据```
```truncate tbl_embedding;```
```insert into tbl_embedding(embedding) select gen_embeddings(1536) from generate_series(1, 100000);```
```SELECT pg_relation_size('tbl_embedding_embedding_idx');```
| |pg_bench 压测 sql 语句：vtest.sql |```sql```
```with vtemp as (select gen_embeddings(1536) as ctemp)```
```select id from tbl_embedding order by embedding <-> (select ctemp from vtemp) limit 40;```
| |pgbench 执行 |```shell```
```PGPASSWORD= pgbench -c 16 -P 10 -T 60 -r -n -U suser -h postgres12fc1230****.rds-pg.ivolces.com -d testdb -p 5432 -f vtest.sql```
| |导入 20 万条数据 |```sql```
```-- 导入 20W 条数据```
```truncate tbl_embedding;```
```drop index tbl_embedding_embedding_idx;```
```insert into tbl_embedding(embedding)```
```select gen_embeddings(1536) from generate_series(1, 200000);```
| |导入 40 万条数据 |```sql```
```-- 导入 40W 条数据```
```truncate tbl_embedding;```
```drop index tbl_embedding_embedding_idx;```
```insert into tbl_embedding(embedding)```
```select gen_embeddings(1536) from generate_series(1, 400000);```
| |导入 60 万条数据 |```sql```
```-- 导入 60W 条数据```
```truncate tbl_embedding;```
```drop index tbl_embedding_embedding_idx;```
```insert into tbl_embedding(embedding)```
```select gen_embeddings(1536) from generate_series(1, 600000);```
| |导入 80 万条数据 |```sql```
```-- 导入 80W 条数据```
```truncate tbl_embedding;```
```drop index tbl_embedding_embedding_idx;```
```insert into tbl_embedding(embedding)```
```select gen_embeddings(1536) from generate_series(1, 800000);```
| |导入 100 万条数据 |```sql```
```-- 导入 100W 条数据```
```Truncate tbl_embedding;```
```drop index tbl_embedding_embedding_idx;```
```insert into tbl_embedding(embedding)```
```select gen_embeddings(1536) from generate_series(1, 1000000);```
| ### 测试结果 #### pgbench 性能 |测试数据量 |表数据大小 |索引数据大小 |TPS ||时延 || |---|---|---|---|---|---|---| ||||6 并发 1 线程 |16 并发 4 线程 |6 并发 1 线程 |16 并发 4 线程 | |10 万 |795 MB |781 MB |1838 |2299 |3.258 ms |6.871 ms | |20 万 |1590 MB |1562.5 MB |1683 |2503 |3.559 ms |6.329 ms | |40 万 |3180 MB |3125 MB |1588 |2487 |3.771 ms |6.368 ms | |60 万 |4770 MB |4687.5 MB |1564 |2538 |3.829 ms |6.254 ms | |80 万 |6360 MB |6250 MB |1508 |2537 |3.971 ms |6.256 ms | |100 万 |7950 MB |7812.5 MB |1434 |2533 |4.176 ms |6.275 ms | #### hnsw 索引与 ivfflat 索引对 TPS 和时延的影响在单 AZ 一主一备 32C64G 实例、 6 并发 1 线程、不同数据量场景下，使用 hnsw 索引与 ivfflat 索引时对 TPS 和时延的影响。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_905ac94b7bd33b0d07328e616dd04cc6.png) #### 超参数对于 TPS 和时延的影响在单 AZ 一主一备 32C64G 实例、 60 万数据量、 16 并发 4 线程场景下，固定 `m` 和 `ef_construction` 的值，设定不同的 `hnsw.ef_search` 值对于 TPS 和时延的影响。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_925b4a70436324815a667059cd0f92f0.png) ## pgvector 量化性能介绍 * 测试规格：Intel Xeon Platinum 8336C，16c64G 规格，32GB shared_buffers * 测试基准：VectorDBBench，50K \- 10M 数据集，TopK=100 ### 1536D / 50K / COSINE ![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0ed8f7a15bb2c38ad82aaef4b62fbc22.png) ### 768D / 1M / COSINE ![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_33081fc70dae72a4e3bf0891fcbbc2fa.png) ### 1536D / 5M / COSINE ![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ce99a6bb83cba2171737902fc36f7d92.png) ### 768D / 10M / COSINE ![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c5e8742d4d78584e8060ed74c9042d53.png)

AI 原生 BaaS 平台 Supabase 版