pgvector 文档 on Vchord

安装与快速上手

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 为 Debian、Ubuntu 以及 RHEL/Rocky/AlmaLinux（x86_64 与 ARM64 架构）提供了针对 PostgreSQL 14–18 预编译的原生 pgvector（v0.8.2）软件包：

Mon, 01 Jan 0001 00:00:00 +0000

pgvector 提供六种距离操作符，可用于排序（ORDER BY）与阈值过滤：

操作符	距离度量	支持的数据类型	说明
`<->`	欧氏距离（L2）	`vector`, `halfvec`, `sparsevec`	$\sqrt{\sum (a_i - b_i)^2}$
`<#>`	负内积（Negative Inner Product）	`vector`, `halfvec`, `sparsevec`	返回 $-\sum a_i b_i$ （因为 PostgreSQL 索引扫描仅支持升序 `ASC` 排序）
`<=>`	余弦距离（Cosine Distance）	`vector`, `halfvec`, `sparsevec`	$1 - \frac{a \cdot b}{\\|a\\|\\|b\\|}$ （取值范围 `[0, 2]`）
`<+>`	曼哈顿距离（L1）	`vector`, `halfvec`, `sparsevec`	(\sum
`<~>`	汉明距离（Hamming Distance）	`bit`	两个位向量中不同比特位的数量（`XOR` 置位计数）
`<%>`	杰卡德距离（Jaccard Distance）	`bit`	(1 - \frac{

归一化向量建议

如果您的嵌入向量已经归一化为单位长度（例如 OpenAI text-embedding-3-* 或 BGE 模型输出），建议优先使用内积（<#>）而非余弦距离（<=>），以获得更高的 CPU 计算吞吐量。

Mon, 01 Jan 0001 00:00:00 +0000

默认情况下，pgvector 执行精确最近邻搜索（全表顺序扫描），具有 100% 的召回率。当表数据量增长至数万行以上时，可以通过创建近似最近邻（ANN）索引，以极小的召回率折中换取几个数量级的查询加速。

Mon, 01 Jan 0001 00:00:00 +0000

pgvector 支持四种向量数据类型，方便您在内存占用、维度上限与检索召回率之间灵活权衡：

数据类型	元素精度	索引最大维度上限	存储空间占用
`vector(n)`	32 位浮点（`float32`）	2,000 维	$4n + 8$ 字节
`halfvec(n)`	16 位半精度浮点（`float16`）	4,000 维	$2n + 8$ 字节
`bit(n)`	1 位二值比特（`0` / `1`）	64,000 维	$\lceil n / 8 \rceil + 8$ 字节
`sparsevec(n)`	非零 `下标:float32` 键值对	最多 1,000 个非零元素（总维度可达 100 万）	$8 \times \text{nnz} + 16$ 字节

vchord 中的 RaBitQ 量化

除了 pgvector 内置的量化类型外，vchord 还提供 rabitq8（8-bit）与 rabitq4（4-bit）专用量化向量类型，并在 vchordrq 索引中支持高达 60,000 维的超长向量。详见 vchord 量化类型。

Mon, 01 Jan 0001 00:00:00 +0000

函数	返回类型	说明
`l2_distance(a, b)`	`float8`	计算 `a` 与 `b` 之间的欧氏（L2）距离（支持 `vector`, `halfvec`, `sparsevec`）
`inner_product(a, b)`	`float8`	计算内积 $\sum a_i b_i$ （支持 `vector`, `halfvec`, `sparsevec`）
`cosine_distance(a, b)`	`float8`	计算余弦距离 $1 - \frac{a \cdot b}{\\|a\\|\\|b\\|}$ （支持 `vector`, `halfvec`, `sparsevec`）
`l1_distance(a, b)`	`float8`	计算曼哈顿（L1）距离 (\sum
`hamming_distance(a, b)`	`float8`	计算两个 `bit` 位向量之间的汉明距离
`jaccard_distance(a, b)`	`float8`	计算两个 `bit` 位向量之间的杰卡德距离
`vector_dims(a)`	`integer`	返回向量的维度数（支持 `vector`, `halfvec`, `sparsevec`）
`vector_norm(a)`	`float8`	返回向量的欧氏范数 $\\|a\\|_2$ （支持 `vector`, `halfvec`, `sparsevec`）
`l2_normalize(a)`	与输入相同	将向量归一化为单位 L2 长度（支持 `vector`, `halfvec`, `sparsevec`）
`binary_quantize(a)`	`bit`	将 `vector` 或 `halfvec` 的每个元素二值化为 `1`（ $> 0$ ）或 `0`（ $\le 0$ ）
`subvector(a, start, count)`	与输入相同	从 1 起始下标 `start` 处截取长度为 `count` 的子向量（支持 `vector`, `halfvec`）

参数名称	类型 / 允许取值	默认值	说明
`hnsw.ef_search`	`integer`（`1`–`1000`）	`40`	HNSW 查询时的动态候选列表大小
`hnsw.iterative_scan`	`off`, `relaxed_order`, `strict_order`	`off`	当 `WHERE` 条件过滤导致结果少于 `LIMIT` 时，自动继续扫描 HNSW 索引
`hnsw.max_scan_tuples`	`integer`	`20000`	HNSW 迭代扫描期间最多访问的元组数量
`hnsw.scan_mem_multiplier`	`real`	`1`	HNSW 迭代扫描维护访问状态可使用的 `work_mem` 倍数
`ivfflat.probes`	`integer`（`1`–`lists`）	`1`	IVFFlat 查询时探测的倒排列表数量
`ivfflat.iterative_scan`	`off`, `relaxed_order`	`off`	当 `WHERE` 条件过滤导致结果少于 `LIMIT` 时，自动探测更多 IVFFlat 分桶
`ivfflat.max_probes`	`integer`	`32768`	IVFFlat 迭代扫描期间最多探测的倒排列表数量

SELECT pg_size_pretty(pg_relation_size('items_embedding_idx'));

使用 EXPLAIN ANALYZE 确认查询是否命中向量索引并查看缓冲区命中与耗时：