pgvector 安装与使用指南

目标：在 PostgreSQL 上安装并启用 pgvector 扩展，实现向量类型存储、三种距离度量与 HNSW/IVFFlat 相似度索引，覆盖源码编译（在线）与离线 tar.gz 两种部署方式。pgvector 本身是 PostgreSQL 扩展，没有独立的守护进程、端口与配置文件，随 PostgreSQL 服务生命周期运行。本文已在 Ubuntu 22.04.5 LTS + PostgreSQL 14.24 + pgvector 0.8.1 实测通过。

一、pgvector 简介

pgvector 是 PostgreSQL 官方生态中最流行的向量检索扩展，将「向量存储 + 相似度检索」能力直接嵌入关系数据库：

新增 vector 数据类型，支持 2~2000 维浮点向量。
提供三种距离算子：<->（L2 欧氏距离）、<#>（内积）、<=>（余弦距离）。
提供 HNSW（分层可导航小世界图）与 IVFFlat（倒排文件）两种 ANN 索引。
支持精确 KNN 检索（ORDER BY embedding <-> $1 LIMIT k）与近似检索（走索引）。

二、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64/amd64）
PostgreSQL	14.24（`PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)`）
pgvector	0.8.1
编译工具	build-essential 12.9ubuntu3、git 1:2.34.1
开发头文件	postgresql-server-dev-14 14.24
pg_config 路径	`/usr/bin/pg_config`

pg_config --version
# PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)
pg_config --pkglibdir
# /usr/lib/postgresql/14/lib
pg_config --sharedir
# /usr/share/postgresql/14

三、前置条件

3.1 安装 PostgreSQL

apt-get update
apt-get install -y postgresql-14 postgresql-client-14
systemctl enable --now postgresql
systemctl is-active postgresql
# active

3.2 安装编译工具链与 PG 开发头文件

apt-get install -y build-essential git postgresql-server-dev-14

说明：build-essential 提供 gcc/make，git 用于拉取源码，postgresql-server-dev-14 提供编译扩展所需的 pg_config 头文件与 pgxs 构建框架。

四、在线部署：源码编译安装

4.1 克隆源码并切到发布 tag

git clone --branch v0.8.1 https://github.com/pgvector/pgvector.git
cd pgvector
git checkout v0.8.1

4.2 编译并安装

make
# gcc -O3 -fPIC ... vector.c ...
# gcc -O3 -fPIC ... -shared -o vector.so
make install
# /usr/bin/mkdir -p '/usr/lib/postgresql/14/lib'
# /usr/bin/mkdir -p '/usr/share/postgresql/14/extension'
# /usr/bin/install -c -m 755 vector.so '/usr/lib/postgresql/14/lib/'
# /usr/bin/install -c -m 644 vector.control ... '/usr/share/postgresql/14/extension/'
# /usr/bin/install -c -m 644 vector--0.8.1.sql ... '/usr/share/postgresql/14/extension/'

4.3 确认安装产物

ls -l $(pg_config --pkglibdir)/vector.so
# -rwxr-xr-x ... /usr/lib/postgresql/14/lib/vector.so
ls $(pg_config --sharedir)/extension/vector*
# vector--0.8.1.sql  vector.control  以及全套 0.x → 0.8.1 升级脚本

五、离线部署：tar.gz 拷贝方式

pgvector 的安装产物只有两类文件：vector.so（共享库）与 extension/ 下的控制/脚本文件。在任意一台与目标版本号一致的机器上执行 make install 后，将产物打包拷入目标机即可完成离线部署。

5.1 在编译机打包产物

cd /tmp
tar czf pgvector-0.8.1-pg14.tar.gz \
  /usr/lib/postgresql/14/lib/vector.so \
  /usr/share/postgresql/14/extension/vector.control \
  /usr/share/postgresql/14/extension/vector--*.sql

5.2 在目标机解包到对应目录

# 目标机需已安装相同版本（14.x）的 PostgreSQL 与 postgresql-server-dev-14（或仅提供目录权限）
tar xzf pgvector-0.8.1-pg14.tar.gz -C /
ls -l /usr/lib/postgresql/14/lib/vector.so
# -rwxr-xr-x ... /usr/lib/postgresql/14/lib/vector.so

💡 离线部署前提：目标机 PostgreSQL 主版本与编译机一致（本示例为 14），否则共享库无法加载。如需在 15/16/17 上部署，须在对应版本的编译机上重新 make install。

六、启用扩展

6.1 创建扩展

su - postgres -c "psql -d postgres -c 'CREATE EXTENSION vector;'"
# CREATE EXTENSION

6.2 确认版本

SELECT extname, extversion FROM pg_extension WHERE extname='vector';

#  extname | extversion
# ---------+------------
#  vector  | 0.8.1
# (1 row)

七、向量类型与检索（实测回显）

7.1 建表并插入向量

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

INSERT INTO items (embedding) VALUES ('[1,1,1]'), ('[2,2,2]'), ('[1,1,2]');

# INSERT 0 3
SELECT id, embedding FROM items ORDER BY id;
#  id | embedding
# ----+-----------
#   1 | [1,1,1]
#   2 | [2,2,2]
#   3 | [1,1,2]
# (3 rows)

7.2 三种距离算子

算子	度量	越小越相似	说明
`<->`	L2 欧氏距离	✅	最常用，配合 `l2_ops`
`<#>`	内积（点积）	❌（越大越相似）	配合 `ip_ops`
`<=>`	余弦距离	✅	对向量长度不敏感，配合 `cosine_ops`

SELECT id,
       embedding <-> '[1,1,1]' AS l2_dist,
       embedding <#> '[1,1,1]' AS inner_prod,
       embedding <=> '[1,1,1]' AS cosine_dist
FROM items ORDER BY id;

#  id |      l2_dist       | inner_prod |     cosine_dist
# ----+--------------------+------------+---------------------
#   1 |                  0 |         -3 |                   0
#   2 | 1.7320508075688772 |         -6 |                   0
#   3 |                  1 |         -4 | 0.05719095841793653
# (3 rows)

说明：[1,1,1] 与自身 L2/余弦距离均为 0；[2,2,2] 与 [1,1,1] 方向相同故余弦距离为 0、仅长度不同（余弦对长度不敏感）；[1,1,2] 方向偏离，余弦距离 0.057。

7.3 KNN 精确检索

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

#  id |      dist
# ----+-------------------
#   1 |                 0
#   3 | 0.05719095841793653
# (2 rows)

八、ANN 索引：HNSW 与 IVFFlat（实测回显）

8.1 HNSW 索引

CREATE INDEX items_hnsw_idx ON items USING hnsw (embedding vector_cosine_ops);

# CREATE INDEX

HNSW 参数	默认值	说明
`m`	16	每层最大连接数，越大召回越高、内存越多
`ef_construction`	64	构建期动态列表大小，越大构建越慢但图质量越高

CREATE INDEX items_hnsw_idx_m ON items USING hnsw (embedding vector_cosine_ops) WITH (m = 24, ef_construction = 128);

8.2 IVFFlat 索引

CREATE INDEX items_ivf_idx ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

# NOTICE:  ivfflat index created with little data
# DETAIL:  This will cause low recall.
# HINT:  Drop the index until the table has more data.
# CREATE INDEX

⚠️ 该 NOTICE 为正常现象：IVFFlat 用 K-Means 把向量聚类到 lists 个列表，数据量太少时聚类无意义、召回率会很低。生产建议：建 IVFFlat 索引前至少插入 100 万行并 ANALYZE，lists 经验值 = 行数 / 1000（上限约 4000）。HNSW 无此限制、对中小数据集更友好，因此更常用。

IVFFlat 参数	默认值	说明
`lists`	100	聚类中心数量
`probes`（查询参数）	1	查询时扫描的列表数，越大召回越高、越慢

8.3 索引视图确认

\d items

#                Table "public.items"
#   Column   |    Type    | Collation | Nullable |              Default
# -----------+------------+-----------+----------+-----------------------------------
#  id        | bigint     |           | not null | nextval('items_id_seq'::regclass)
#  embedding | vector(3)  |           |          |
# Indexes:
#     "items_pkey" PRIMARY KEY, btree (id)
#     "items_hnsw_idx" hnsw (embedding vector_cosine_ops)
#     "items_ivf_idx" ivfflat (embedding vector_cosine_ops) WITH (lists='100')

8.4 查询强制走索引

SET enable_seqscan = off;
SELECT id, embedding <=> '[1,1,1]' AS dist FROM items ORDER BY embedding <=> '[1,1,1]' LIMIT 3;
EXPLAIN (COSTS OFF) SELECT id, embedding <=> '[1,1,1]' AS dist FROM items ORDER BY embedding <=> '[1,1,1]' LIMIT 3;

#                         QUERY PLAN
# ----------------------------------------------------------------
#  Limit
#    ->  Index Scan using items_hnsw_idx on items
#          Order By: (embedding <=> '[1,1,1]'::vector)
# (2 rows)

九、与 PostgreSQL 集成、调优与运维

9.1 无独立服务的说明

pgvector 没有独立守护进程、端口与配置文件，它是加载到 PostgreSQL 进程内的扩展库：

生命周期由 PostgreSQL 服务管理：systemctl enable --now postgresql、systemctl restart postgresql。
启动时无需单独拉起任何进程，CREATE EXTENSION 后立即可用。
升级 PostgreSQL 或 pgvector 后：make install 新版本 → 库内执行 ALTER EXTENSION vector UPDATE。

9.2 常用参数调优（postgresql.conf）

编辑 /etc/postgresql/14/main/postgresql.conf 后 systemctl restart postgresql：

# 向量批量导入时提高写入吞吐（导入后可恢复）
max_wal_size = 4GB
checkpoint_completion_target = 0.9

# 预留足够内存给 HNSW 图结构
shared_buffers = 4GB

9.3 常用运维命令

# 服务管理
systemctl restart postgresql
journalctl -u postgresql --no-pager -n 50

# 确认当前库已启用扩展
su - postgres -c "psql -d postgres -c '\dx'"
#                             List of installed extensions
#   Name   | Version |   Schema   |                     Description
# ---------+---------+------------+------------------------------------------------------
#  plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
#  vector  | 0.8.1   | public     | vector data type and ivfflat and hnsw access methods
# (2 rows)

# 删除扩展（连带删除依赖对象）
su - postgres -c "psql -d postgres -c 'DROP EXTENSION vector CASCADE;'"
# DROP EXTENSION

# 升级扩展（安装新版 .so/.sql 后执行）
su - postgres -c "psql -d postgres -c 'ALTER EXTENSION vector UPDATE;'"

# 索引维护：HNSW/IVFFlat 索引删除
su - postgres -c "psql -d postgres -c 'DROP INDEX items_hnsw_idx;'"

十、FAQ

pgvector 和 Milvus、Chroma 等向量数据库有什么区别？ pgvector 是 PostgreSQL 扩展，随数据库事务、SQL、备份体系一起工作，适合「向量+业务数据一体」的场景；Milvus 等独立向量数据库适合海量向量、高并发 ANN 检索场景。
vector 维度上限是多少？ 2~2000 维（vector(2000)）。存储按 4B/维 + 少量开销 计算。
HNSW 和 IVFFlat 怎么选？ 数据量小或要求即时写入即可检索 → HNSW（无需预热数据）；数据量百万级以上且能接受先批量导入再建索引 → IVFFlat（内存占用更低）。
离线部署需要注意什么？ vector.so 必须与目标机 PostgreSQL 主版本完全一致（14.x 的库不能用于 15.x），且目标机需安装对应 postgresql-server-dev-N 提供运行时依赖或至少保证目录可写。
插入报 invalid input syntax for type vector？ 向量字符串必须用方括号包裹、逗号分隔且不含空格，如 '[1,2,3]'；维度与列定义不一致也会报此错误。

十一、参考链接

pgvector 官方仓库：https://github.com/pgvector/pgvector
pgvector 官方文档：https://github.com/pgvector/pgvector/blob/master/README.md
PostgreSQL 扩展文档：https://www.postgresql.org/docs/14/extend-extensions.html