Windows 下 pgvector 快速安装完整指南：免编译与源码构建两条路都讲透

Windows 下 pgvector 快速安装完整指南：免编译与源码构建两条路都讲透

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

你的业务要接向量检索，又不想多养一套中间件？pgvector 是 PostgreSQL 的开源向量相似度搜索扩展，让向量数据和业务数据躺在同一张表里，用熟悉的 SQL 就能做近邻查询。本文带你用"免编译"或"源码构建"两种途径，在 Windows 上完成 PostgreSQL 向量扩展的安装，并跑通第一次近邻检索。

🎬 从一个具体痛点说起

想象一下：产品要做语义搜索，团队评审时有两个选项——引入一套独立的向量数据库，或者给现有 PostgreSQL 加个扩展。前者意味着多一个集群、多一套备份恢复流程、多一种连接方式；而 vector.control 描述的 pgvector 方案，只需要在现有库里执行一句CREATE EXTENSION vector;，向量列和关系型列就能写在同一个事务里。

这就是它的定位：向量能力长在你的数据库里，而不是数据库旁边。支持稠密向量、半精度向量、二进制向量和稀疏向量，覆盖 L2、内积、余弦、L1 等距离度量（对应 src/ 目录下的 vector.c、halfvec.c、bitvec.c、sparsevec.c 等实现）。

📋 开工前的环境清单

动手前对照下面这张表，缺什么补什么：

🛤️ 先花 10 秒选一条路

两条路殊途同归，最终都是让vector.dll、vector.control和升级脚本各就各位。下面分开讲。

📦 免编译通道：文件放对位置就成功

前提是你已经拿到了与本机 PostgreSQL 主版本匹配的 pgvector 预编译包。

1. 把vector.dll复制到 PostgreSQL 安装目录的lib子目录，例如C:\Program Files\PostgreSQL\16\lib\。
2. 把vector.control和所有vector--*.sql脚本复制到share\extension\目录。升级脚本的作用见仓库里的 sql/ 目录——每个vector--旧版--新版.sql负责一次版本迁移，vector--0.8.6.sql则对应全新安装。
3. 重启 PostgreSQL 服务（或至少确认服务账号有读取这些文件的权限）。

落位清单核对：

如果这一步卡住，多半是文件版本和你本地的 PostgreSQL 主版本不匹配——加载扩展时如果报version "0.8.6" not found之类的错，就是脚本没拷全。

🔨 源码构建通道：五条命令走完全程

用 Visual Studio 附带的x64 Native Tools Command Prompt for VS（右键选择"以管理员身份运行"），依次执行：

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

声明你的 PostgreSQL 安装根目录，Makefile.win 在没设置PGROOT时会直接!error拒绝编译。

cd %TEMP% git clone --branch v0.8.6 https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector

拉取指定 tag 的源码到临时目录，避免污染其他工作区。

nmake /F Makefile.win

编译vector.dll并生成带版本号的安装脚本。注意这里显式指定Makefile.win——误用 Linux 用的Makefile会立刻撞上process_begin: CreateProcess(NULL, uname -s, ...) failed这类错误，因为普通 nmake 不认识其中的 POSIX 命令。

nmake /F Makefile.win install

这一步对应 Makefile.win 第 61~66 行的 install 目标：把 DLL 拷进lib\，把.control和 SQL 脚本拷进share\extension\，同时把vector.h等头文件放到服务器扩展头目录。

编译慢或想加优化参数时，可以看 Makefile.win 中PG_CFLAGS的注释，它已经内置了/O2 /fp:fast的自动向量化配置。

🩺 报错定位速查

✅ 冒烟验证：三条 SQL 定生死

打开 psql，连上任意业务库：

CREATE EXTENSION vector; SELECT '[1,2,3]'::vector; SELECT * FROM pg_extension WHERE extname = 'vector';

判定标准一句话：三条全部无报错执行、第二条返回[1,2,3]，就说明扩展链路（DLL → control → SQL 脚本）全部就位。

🔎 首批查询体验：建表、插数、找近邻

接下来用三段最小 SQL 感受下向量距离算子。

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

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

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

<->是 L2 距离算子，距离越小排得越前——[1,2,3]会排在第一位。换算子就能换度量：<#>内积、<=>余弦、<+>L1（对应 src/vector.c 中注册的距离函数）。

🏭 上生产前的备忘

• 版本兼容：pgvector 的 DLL 与 PostgreSQL 主版本绑定，PG 升级后要重新编译或更换匹配产物；扩展自身的版本升级由share\extension\下的升级脚本链驱动（sql/ 目录从 0.1.0 一直排到 0.8.6）。
• 索引选型：数据量大时别裸扫，建hnsw或ivfflat索引。HNSW 召回稳定、写入代价略高（实现见 src/hnsw.c），IVFFlat 建索引快、适合批量入库场景（实现见 src/ivfflat.c），可按查询延迟目标先小数据压测再定。
• 备份：扩展随数据库一起被 pg_dump/pg_basebackup 覆盖，无需单独处理；但记得把vector(n)列的维度变更纳入变更流程，因为维度变化不兼容旧数据。

🧭 接下来可以摸什么

• 距离函数扩展：把test/sql/下的用例当教材，跑通 test/t/ 中的回归脚本（039_hnsw_cost.pl、040_ivfflat_cost.pl等），体会索引代价估算逻辑。
• 稀疏向量与半精度：用sparsevec、halfvec类型重做一遍近邻查询，对比存储占用与召回差异。
• 过滤召回调优：参考 test/t/017_hnsw_filtering.pl 的写法，验证WHERE条件叠加下 HNSW 的召回表现。
• 迭代扫描：了解ivfflat.iterative_scan/hnsw.iterative_scanGUC（对应 test/t/041_ivfflat_iterative_scan.pl 的验证用例），在多跳召回场景下多扫几批候选。

挑其中一项，在你的测试库上建一张 10 万行的向量表跑通它——这比读十篇博客更能确认你的环境真的准备好了。

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