pgvector 扩展怎么装：在 PostgreSQL 里完成向量存储与相似度查询

知识分享

2026-10-30 21:00

25 阅读

先判断你的使用场景

pgvector 是 PostgreSQL 的一个扩展，不是独立数据库。
它让 PostgreSQL 表可以存储向量字段，并用距离运算符做最近邻查询。
如果你的项目已经用 PostgreSQL，又不想额外维护一套向量数据库，pgvector 是最省事的路径；
如果数据量极大或需要分布式检索，再考虑专用向量库。

本文假设你已有一台能运行 PostgreSQL 的 Linux 服务器，并具备 sudo 权限。
下面分别给出 Docker 和 apt 两种安装方式，选其中一种执行即可。

安装 PostgreSQL 与 pgvector 扩展

方式一：Docker 快速启动

官方 pgvector/pgvector 镜像已经内置扩展，适合本地验证或临时环境。

docker run -d --name pgvector-demo \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  pgvector/pgvector:pg16

启动后进入容器执行 psql：

docker exec -it pgvector-demo psql -U postgres

方式二：apt 安装到已有 PostgreSQL

如果服务器上已经装了 PostgreSQL，先确认大版本，再安装对应的扩展包。
以 Debian/Ubuntu 和 PostgreSQL 16 为例：

sudo apt update
sudo apt install postgresql-16-pgvector

把 16 换成你的 psql --version 显示的大版本号。
安装完成后重启 PostgreSQL 服务让扩展文件就绪：

sudo systemctl restart postgresql

启用扩展并验证

无论用哪种方式安装，都要在目标数据库中执行一次启用命令。
连接数据库：

sudo -u postgres psql -d postgres

在 psql 提示符下执行：

CREATE EXTENSION IF NOT EXISTS vector;
\dx

\dx 会列出已安装扩展，看到 vector 一行即表示启用成功。
如果报错 extension "vector" is not available，说明扩展包没有装到当前 PostgreSQL 版本对应的目录，回到上一步检查版本号是否匹配。

建表、写入与相似度查询

下面用三维向量做最小示例，便于理解。
真实场景中维度通常是 768、1024 或 1536，建表时按模型输出维度填写。

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

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

pgvector 提供三个常用距离运算符：<-> 欧氏距离、<#> 负内积、<=> 余弦距离。
查询与 [1,2,3] 最接近的记录：

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

预期结果是 id=1 的距离为 0，id=3 的距离最小且非零。
如果查询报错 operator does not exist: vector <=> unknown，检查向量字面量是否用单引号包裹，以及列类型是否为 vector。

建索引与验证检索效果

数据量超过几千行后，全表扫描会变慢，需要为向量列建索引。
pgvector 支持 IVFFlat 和 HNSW 两类索引。
以 HNSW 为例：

CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

索引运算符类要和查询距离保持一致：余弦距离用 vector_cosine_ops，欧氏距离用 vector_l2_ops，内积用 vector_ip_ops。
建完后用 EXPLAIN 检查是否走索引：

EXPLAIN SELECT id FROM items ORDER BY embedding <=> '[1,2,3]' LIMIT 2;

输出中出现 Index Scan using items_embedding_idx 即表示索引生效。
如果仍是 Seq Scan，先确认表里有足够数据，因为数据量太小时优化器可能主动选择全表扫描。

容易踩的几个坑

维度必须一致：vector(3) 的列不能插入四维向量，否则直接报错。换嵌入模型时要么重建表，要么用新列迁移。
索引不会自动更新：IVFFlat 索引需要 ANALYZE 后建立，且数据增长后要重建才能保持召回率；HNSW 写入开销更大，但查询通常更稳。
距离方向别搞反：ORDER BY ... LIMIT 默认取最小距离，余弦距离下数值越小越相似，不要误加 DESC。
扩展按数据库启用：CREATE EXTENSION 只对当前数据库生效，换库要重新执行。

常见疑问

pgvector 和专用向量数据库怎么选？ 已有 PostgreSQL 且数据量在百万级以内，优先用 pgvector，省去同步和运维成本；
需要水平扩展或超低延迟检索时再评估专用向量库。

索引应该选 HNSW 还是 IVFFlat？ HNSW 查询快、召回稳，但建索引慢、占内存；
IVFFlat 建索引快、内存占用低，适合数据量大且能接受一定召回损失的场景。
可以先从 HNSW 开始，压测后再调整。

查询结果为空或距离异常怎么办？ 先确认插入的向量维度与列定义一致，再检查查询向量是否用了相同的距离运算符。
必要时用 SELECT count(*) FROM items 确认数据确实写入了当前数据库。

Faiss 向量检索怎么上手：Python 建索引与相似度查询

LanceDB 怎么用：Python 本地向量库写入与相似度检索