pgvector 安装教程：在 Windows 上给 PostgreSQL 加上向量搜索能力

pgvector 安装教程：在 Windows 上给 PostgreSQL 加上向量搜索能力

【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector

在 Windows 上给 PostgreSQL 装向量搜索能力，最容易卡住的不是数据库本身，而是源码编译这一步：找不到头文件、nmake 报错、装完却CREATE EXTENSION失败。下面把整条链路拆成"检查—编译—验证—排错"四段，照着走就能把 pgvector 跑起来。

pgvector 是一个 PostgreSQL 扩展，让你在现有数据库里直接存向量、建向量索引、做最近邻搜索，不用另外搭一套向量数据库。它支持vector、halfvec、sparsevec、bit四种类型，提供 HNSW 和 IVFFlat 两类近似索引，距离度量覆盖 L2、内积、余弦、L1。

安装前先核对这份环境清单

这一步完成后，你能确认编译环境没问题，避免 90% 的"找不到头文件 / 链接失败"报错。

1. PostgreSQL 13+：pgvector 当前版本兼容 13 到 18。打开命令行执行psql --version确认版本。
2. Visual Studio 含 C++ 工作负载：编译走 MSVC，必须装"C++ 桌面开发"组件，而不是只装基础 IDE。
3. Git 命令行：用于拉取源码。

关键一点：编译和安装都要在x64 Native Tools Command Prompt for VS里进行，并且以管理员身份打开它。普通 cmd 没有 MSVC 的 PATH 和宏环境，nmake会直接报"不是内部或外部命令"。

三步完成 pgvector 源码编译安装

这一步完成后，vector.dll会被拷进 PostgreSQL 的lib目录，扩展文件进入share/extension，数据库就能识别它了。

1. 以管理员身份打开x64 Native Tools Command Prompt for VS。
2. 设置 PGROOT 指向你的 PostgreSQL 安装根目录（注意是含bin、include、lib的那一层）：

set "PGROOT=C:\Program Files\PostgreSQL\18"

3. 拉取源码并进入目录：

cd %TEMP% git clone https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector

4. 编译并安装：

nmake /F Makefile.win nmake /F Makefile.win install

成功的标志：第二条命令跑完后，$(PGROOT)\lib下出现vector.dll，$(PGROOT)\share\extension下出现vector.control和一批vector--*.sql文件。Makefile.win 会检查 PGROOT，未设置时直接报错退出，所以第 2 步不能省。

五分钟验证 pgvector 是否装好

这一步完成后，你能用一段最小 SQL 证明"类型可用、索引可建、查询可跑"，把安装问题和使用问题彻底分开。

1. 用psql连进你要用的那个库（扩展按库启用，每个库都要单独执行一次）：

CREATE EXTENSION vector;

成功的标志：无报错。若提示"could not open extension control file"，说明上一步安装没成功或连错了库的实例。

2. 建一张 3 维测试表并插入数据：

CREATE TABLE test_items ( id bigserial PRIMARY KEY, embedding vector(3) ); INSERT INTO test_items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

3. 按 L2 距离做最近邻查询：

SELECT * FROM test_items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

成功的标志：能按距离升序返回结果。<->是 L2 距离，另外还有内积<#>、余弦<=>、L1<+>。

两种向量索引怎么选

这一步完成后，你能按数据规模和写入频率选对索引类型，避免"建了索引却没被查询用上"的浪费。

建索引示例（二选一）：

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

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

两个实用调优点：建 IVFFlat / 大表 HNSW 前调大maintenance_work_mem（如SET maintenance_work_mem = '2GB';）能明显加速；带WHERE过滤的近似查询可能少返回结果，pgvector 0.8.0 起支持迭代式索引扫描，会自动多扫索引直到凑够条数。

一张表看懂 pgvector 常见报错

下一步建议

• 先在你的真实表上把 HNSW 索引建起来，用EXPLAIN (ANALYZE, BUFFERS)观察索引是否真的被命中。
• 维度较高或数据量大时，对比 HNSW 与 IVFFlat 的召回率和延迟，再定参数。
• 关注 CHANGELOG 跟进版本更新，升级用ALTER EXTENSION vector UPDATE;。

【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector