PostgreSQL 向量检索配置：pgvector 扩展安装与相似度查询

PostgreSQL 原生并不具备向量检索能力，需要借助 pgvector 扩展来实现。
pgvector 为 PostgreSQL 增加了 vector 数据类型、距离操作符以及 ivfflat 和 hnsw 索引，安装后即可在普通 SQL 中完成最近邻查询。
下面从编译安装到查询验证逐步说明，适用于 PostgreSQL 12 及以上版本、Linux 环境。

安装前确认编译环境

pgvector 需要从源码编译，先确认 PostgreSQL 服务端开发包和编译工具已就绪。
以 Ubuntu/Debian 为例：

sudo apt update
sudo apt install -y postgresql-server-dev-all build-essential git

CentOS/RHEL 则安装 postgresql-devel 和 gcc。
如果数据库是通过宝塔面板安装的，需要找到对应的 PostgreSQL 安装目录，通常位于 /www/server/pgsql，编译时通过 PG_CONFIG 指定路径。

编译并启用 pgvector

拉取 pgvector 源码并编译安装：

git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

版本号可按需选择，建议使用官方仓库当前稳定分支。
安装完成后，连接到目标数据库并创建扩展：

CREATE EXTENSION vector;

执行 \dx 能看到 vector 扩展即表示启用成功。
如果提示 could not open extension control file，说明编译时 pg_config 指向了错误的 PostgreSQL 版本，需要重新用正确的 PG_CONFIG 路径编译。

建表并写入向量数据

创建一个带 3 维向量字段的示例表：

CREATE TABLE items (
    id bigserial PRIMARY KEY,
    embedding vector(3)
);

插入几条测试数据：

INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');

向量维度必须与字段定义一致，否则会报 expected 3 dimensions, not 4 之类的错误。
实际业务中维度通常是 768、1024 或 1536，建表时按模型输出维度填写。

执行相似度查询

pgvector 提供多种距离操作符，最常用的是 L2 距离 <-> 和余弦距离 <=>。
查询与 [1,2,3] 最接近的记录：

SELECT id, embedding <-> '[1,2,3]' AS distance
FROM items
ORDER BY embedding <-> '[1,2,3]'
LIMIT 5;

余弦距离适用于文本嵌入向量，查询时改用 <=> 即可。
如果数据量较大，可以创建索引加速：

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

HNSW 索引对查询性能提升明显，但会增加写入开销和内存占用；
IVFFlat 索引则需要先用 CREATE INDEX ... USING ivfflat 并配合 lists 参数调整。
小数据量下不建索引也能正常查询。

常见问题与避坑

• 扩展创建失败：确认 pg_config 路径与正在运行的 PostgreSQL 版本一致，重启数据库不是必须的，但需要重新执行 CREATE EXTENSION。
• 向量维度不匹配：建表时 vector(n) 的 n 必须与写入数据长度一致，修改维度需要重建字段或表。
• 索引未生效：HNSW 索引要求向量维度不超过 2000，超过时需改用其他方案或降维。
• 权限问题：编译安装和 CREATE EXTENSION 通常需要超级用户权限，生产环境建议由 DBA 操作。

验证配置结果

完成以上步骤后，执行 SELECT * FROM items ORDER BY embedding <-> '[1,2,3]' LIMIT 1;，应返回 id 为 1 的记录且距离为 0。
再用 \d+ items 查看表结构，确认 embedding 字段类型为 vector(3)，索引列表中包含 hnsw 索引，即表示 PostgreSQL 向量检索配置已生效。