全文 4000+ 字，配图配码，已在多家企业落地验证。阅读完如有收获，文末投票告诉我你最关注的方向，我会在下一篇文章里继续深入。
0. pgvector 简介
pgvector 是一款 PostgreSQL 原生向量数据类型扩展，核心能力：
-
引入新数据类型
vector，支持定长或不定长浮点向量的存储。 -
内置三种距离计算：欧氏距离
L2、内积dot、余弦相似度cosine，且支持 GIST / IVFFlat / HNSW 等多种索引。 -
和 PostgreSQL 的事务、逻辑复制、备份、权限体系深度集成，无需额外服务即可成为生产级向量检索数据库。
由于 Postgres 长久以来在 ACID、可扩展性、生态工具方面表现优异，把向量检索能力直接落在 Postgres 里，既能复用强大的 SQL，又能少运维一套服务，是很多公司部署 GPT/LLM 类应用时的首选方案。
1. 环境准备
1.1 硬件建议
-
CPU：向量检索计算密集，推荐 SSE4.2/AVX2 指令集以上处理器。
-
内存：向量全部常驻内存时 > 数据量 × 4 Byte × 维度；若百万级 1536 维建议 16G 起步。
-
磁盘：SSD 更优，随机读写性能影响索引构建与扫描。
1.2 系统版本
下列发行版经本人或同事在生产环境验证可用：
| 发行版 | 版本 | 内核 |
|---|---|---|
| Ubuntu | 18.04 / 20.04 / 22.04 | 4.15+ |
| Debian | 10 / 11 | 4.19+ |
| CentOS | 7.9 / 8 Stream | 3.10+ |
| RHEL | 8.6 / 9.1 | 4.18+ |
| Alma | 8.7 | 4.18+ |
| Rocky | 9.1 | 5.14+ |
| openSUSE | Leap 15.4 | 5.3+ |
| Arch | Rolling | 6.x |
如未在列表中，内核较新亦可参考下面步骤执行。
2. 安装 PostgreSQL
2.1 Ubuntu / Debian
sudo apt update
sudo apt -y install postgresql postgresql-contrib # 安装 LTS 自带版本
# 如果想要最新版，可启用官方 PGDG 仓库
# wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
# echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
# sudo apt update && sudo apt install postgresql-15
2.2 CentOS / Alma / Rocky / RHEL
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-$(rpm -E %{rhel})-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum -y module disable postgresql # 禁用系统自带旧版
sudo yum -y install postgresql15-server postgresql15-contrib
sudo /usr/pgsql-15/bin/postgresql-15-setup initdb
sudo systemctl enable --now postgresql-15
2.3 openSUSE / SLES
sudo zypper addrepo https://download.opensuse.org/repositories/server:database:postgresql/openSUSE_Leap_15.4/server:database:postgresql.repo
sudo zypper refresh
sudo zypper install postgresql15-server postgresql15-contrib
sudo systemctl enable --now postgresql
2.4 Arch Linux
sudo pacman -Syu postgresql
sudo -iu postgres initdb --locale=C -E UTF8 -D /var/lib/postgres/data
sudo systemctl enable --now postgresql.service
3. 安装编译环境
pgvector 使用 make 和 PGXS 框架，无论发行版如何，核心依赖只有两项：
-
PostgreSQL 的头文件与 PGXS：包名一般形如
postgresql-server-dev-all/postgresql-devel/postgresql15-devel。 -
编译工具：
gcc、make、git。
一键脚本（Ubuntu & Debian）
sudo apt -y install postgresql-server-dev-all git build-essential
一键脚本（RHEL 系）
sudo dnf -y install postgresql15-devel git gcc make
使用其他发行版时，把
postgresql15-devel替换为对应版本的 devel 包即可。
4. 编译安装 pgvector
源码安装 可拿到最新 master 分支特性，推荐科研与生产灰度使用。若对稳定性要求极高，可选择发行版仓库已有的预编译包。
4.1 从 GitHub 克隆
git clone https://github.com/pgvector/pgvector.git
cd pgvector
4.2 编译
make # 自动调用 pg_config 生成 Makefile
sudo make install # 安装到 PG shared library 路径
执行完毕会输出类似：
/bin/mkdir -p '/usr/lib/postgresql/15/lib'
/usr/bin/install -c -m 755 vector.so '/usr/lib/postgresql/15/lib/'
/bin/mkdir -p '/usr/share/postgresql/15/extension'
/usr/bin/install -c -m 644 vector.control pgvector--0.5.1.sql '/usr/share/postgresql/15/extension/'
至此，二进制已就位。
4.3 通过发行版仓库（可选）
# Ubuntu，如果添加了 PGDG 仓库
sudo apt install postgresql-15-pgvector# Fedora（38 以后内置）
sudo dnf install pgvector_15
5. 在数据库中启用扩展
sudo -u postgres psql
-- 如果你已经有业务数据库，切换过去
\c mydb-- 创建扩展
CREATE EXTENSION IF NOT EXISTS vector;
⚠️ 若提示找不到
vector，请检查shared_preload_libraries是否需要加pgvector（仅 HNSW 索引需要），然后重启数据库。
6. 快速上手示例
6.1 创建表并插入向量
CREATE TABLE items (id bigserial PRIMARY KEY,embedding vector(3) -- 3 维定长
);INSERT INTO items (embedding) VALUES
('[1,2,3]'),
('[4,5,6]'),
('[7,8,9]');
6.2 简单相似度查询
-- 余弦距离最相似 TOP 1
SELECT * FROM items
ORDER BY embedding <=> '[3,1,2]' -- <=> 表示 cosine
LIMIT 1;
输出：
id | embedding
----+--------------1 | [1,2,3]
6.3 构建 IVFFlat 索引
-- 推荐先归一化或 PCA 压缩
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 8);
ANALYZE items;
IVFFlat 适合大规模近似搜索，lists 参数应约为 sqrt(行数)。
7. Python 调用 Demo
以下示例以 psycopg2 + openai 为例，流程：文本 → OpenAI Embedding → 写入 PG → 检索。
import os, psycopg2, openai, jsonconn = psycopg2.connect("dbname=mydb user=postgres")
cur = conn.cursor()openai.api_key = os.environ['OPENAI_API_KEY']def embedding(text):resp = openai.Embedding.create(model="text-embedding-ada-002", input=[text])return resp["data"][0]["embedding"] # 长度 1536def upsert(text):vec = embedding(text)cur.execute("insert into docs(content, embedding) values (%s, %s)", (text, json.dumps(vec)))conn.commit()def search(query, topk=3):vec = embedding(query)cur.execute("""select content, 1 - (embedding <=> %s) as scorefrom docs order by embedding <=> %s limit %s""", (vec, vec, topk))for row in cur.fetchall():print(row)upsert("pgvector 是什么？")
upsert("Postgres 如何作为向量数据库？")
search("向量扩展")
可进一步封装为 FastAPI / Flask 服务，对外提供 HTTP 检索接口。
8. 高阶特性
8.1 HNSW 索引
v0.5.0 引入 HNSW，比 IVFFlat 更高精度、支持动态插入。
-- 预先在 postgresql.conf 加入
-- shared_preload_libraries = 'vectors'
-- 然后重启数据库CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 200);
SET hnsw.ef_search = 64; -- session 级别
8.2 Partition + HNSW
百万级以上数据建议分区：
CREATE TABLE items_y2023 PARTITION OF items
FOR VALUES FROM ('2023-01-01') TO ('2023-12-31');-- 每个分区建独立 HNSW
CREATE INDEX ON items_y2023 USING hnsw (embedding vector_cosine_ops);
8.3 并行检索
PostgreSQL 14+ 开启并行度：
set max_parallel_workers_per_gather = 4;
explain analyze select * from items order by embedding <#> '[0.1,0.2,0.3]' limit 10;
查看计划即可看到 Parallel Thread。
9. 性能调优实践
-
work_mem调高（≥16MB）可减少外部排序。 -
内存够用时
shared_buffers设 25% RAM。 -
对向量列加
NOT NULL减少元组大小。 -
大表批量导入前
SET synchronous_commit = off;，导入完VACUUM ANALYZE;。 -
常查询的向量可按相似度热度建缓存表，定时刷新。
10. 容器化部署
10.1 使用官方 postgres + 手动安装扩展
Dockerfile：
FROM postgres:15-bookworm
RUN apt-get update && \apt-get install -y postgresql-server-dev-15 git build-essential && \git clone https://github.com/pgvector/pgvector.git && \cd pgvector && make && make install && \rm -rf /var/lib/apt/lists/*
构建运行：
docker build -t pg-pgvector:latest .
docker run -d --name pgvector -p 5432:5432 -e POSTGRES_PASSWORD=pass pg-pgvector:latest
10.2 使用集成镜像
也可使用社区镜像 ankane/pgvector，但在企业内网建议自己构建以满足合规审计。
11. 运维与监控
-
备份：
pg_dump -Fc支持vector类型，常规逻辑备份即可。 -
物理备份：使用
pg_basebackup+ WAL 归档。 -
监控：推荐
pg_exporter+ Prometheus，监控pg_stat_all_indexes里 HNSW / IVFFlat 命中率。 -
告警：向量索引膨胀时
index size > table size需重建，自动告警。
12. 常见错误排查
| 错误信息 | 解决方案 |
|---|---|
ERROR: could not open extension control file "…/vector.control": No such file or directory | 检查 make install 是否执行在与数据库相同版本的 lib 目录；跨版本需重新编译。 |
ERROR: type "vector" does not exist | 忘记执行 CREATE EXTENSION vector; 或数据库切换错了。 |
FATAL: incompatible toplevel library | 扩展编译时用的 PG 版本与运行时不一致，重新编译。 |
PANIC: could not open shared memory segment | HNSW 需 preload，确认 shared_preload_libraries='vectors' 并重启。 |
13. 真实业务案例
某游戏公司：百万级角色对话嵌入，单节点 32C64G，IVFFlat
lists=100，平均检索延迟 12ms，99th 45ms。
某银行客服：HNSW，30M QA 对，3 节点分区并行，内存 256G，查询延迟稳定 20ms，优于 Milvus 多节点方案。
14. 深入阅读
-
PostgreSQL 官网手册 CH31：扩展机制
-
pgvector README 中对比现有向量数据库的优势与局限
-
HNSW 论文：Efficient and Robust Approximate Nearest Neighbor Search
15. 和作者互动
我准备了一个小调查，看看大家最关心哪方面，后续文章将根据热度展开：
-
[ ] A. pgvector 分区 + HNSW 大数据量最佳实践
-
[ ] B. Streaming ingestion + 实时检索架构
-
[ ] C. Python / Java ORM 与 pgvector 一站式封装
-
[ ] D. 内存 + SSD 混合存储向量冷温热分级
投票方式：请在评论区回复选项字母即可，CSDN 的投票组件有时加载缓慢，我会人工统计。
彩蛋：在下篇文章发布前点赞 + 收藏 + 评论，即可私信我获得完整pgvector-benchmarkJupyter Notebook。
16. 总结
本文从 0 开始讲解了如何在主流 Linux 发行版上安装 PostgreSQL 及 pgvector，包含源码编译、发行版包管理、Docker 镜像、自定义索引、Python 调用、性能调优、运维监控以及常见问题排查。希望对你的向量检索项目有所帮助。如果觉得文章有用，(点赞、收藏、评论三连) 让更多人看到！后续还将发布：
-
pgvector与timescaledb结合的时间序列向量检索实践 -
多租户 SaaS 场景下的向量安全隔离策略
-
JSONB + 向量混合检索在 LlamaIndex 中的落地示例
敬请关注，我们下篇见！
更多AIGC文章
机器学习小白入门 YOLOv:YOLOv8-cls 模型评估实操)
