第一次在 Windows 上给 PostgreSQL 编译扩展十有八九会卡在nmake那一行。我前后在三台配置不同的机器上把 pgvector 从克隆源码到跑通第一条相似度查询走了一遍从 PostgreSQL 13 一路跟到 17踩的坑高度雷同postgres.h找不到、vector.dll被服务进程占用、编出来的库和运行的服务端版本对不上、建完 HNSW 索引却发现查询走了全表扫描。这篇就把整个流程摊开讲从环境怎么对齐、Makefile.win里那几个变量是什么意思、装完之后怎么确认扩展真的挂上了一直到造测试数据、写ORDER BY embedding - [...]、给查询加上近似索引并验证召回率。内容偏向实操适合已经会用 psql、想在 Windows 本机跑通向量检索的开发者也适合被编译报错磨掉耐心、想找一份完整对照表的人。1. 先搞清楚 Windows 上编译 pgvector 到底难在哪1.1 pgvector 是什么它给你的数据库补了哪块能力pgvector 是 PostgreSQL 的一个扩展核心就干三件事提供一个vector数据类型用来存定长浮点数组提供一组距离操作符用来做相似度比较提供两种近似最近邻索引IVFFlat 和 HNSW用来把暴力比较压到可接受的时间。它不是一个独立服务不占端口不额外起进程装好之后就是数据库里多了一个类型加几个函数跟你平时用jsonb、uuid没有任何使用习惯上的差别。它解决的问题很具体。假设你有一张商品表每条记录有一个 768 维的文本嵌入向量用户输入一句话你要找语义最接近的 20 个商品。没有 pgvector 的时候你得把向量搬到专门的向量数据库里然后面对数据同步、事务一致性、双写失败补偿这一堆破事。有了 pgvector向量就是表里的一列跟价格、标题放在同一行WHERE条件能和向量排序写在同一条 SQL 里事务、备份、权限体系全部复用。适合谁用我的判断标准是数据量在一千万行以内、对召回延迟要求在几十毫秒量级、团队不想再维护一套异构存储的pgvector 基本是首选。数据量再往上、或者需要多副本分片检索的才需要考虑专用方案。这个边界先划清楚后面折腾编译才有意义。1.2 三条路可选预编译包、容器镜像、源码编译在 Windows 上拿到能用的 pgvector实际有三条路各有各的适用场景我先把取舍摆出来你再决定要不要跟着后面折腾源码。方式上手成本版本匹配风险适合场景官方 Releases 里的 Windows 二进制包最低解压复制即可中包只覆盖特定 PG 大版本版本正好对得上只想快速验证容器镜像含 pgvector 的 PostgreSQL 镜像低一条命令起服务低本地开发、CI、不依赖本机 PostgreSQL克隆源码 MSVC 编译高要配工具链最低头文件和运行库都自己控本机已有 PostgreSQL 实例、需要特定小版本、或要改源码我之所以坚持走第三条是因为前两条在真实工作里经常被卡住预编译包不是每个小版本、每个 PG 大版本都齐碰上公司内网镜像没有你需要的 tag就只能回到源码容器方案在本地开发很爽但如果你要连接的是本机已经跑了两年、装着其他扩展、配置改过十几处的那个 PostgreSQL 实例把数据迁到容器里往往比编译一次扩展麻烦得多。还有一类更隐蔽的情况你需要对着某个特定 commit 编译因为上游刚合入的补丁正好修了你遇到的问题而正式版还没发。这种时候只有源码编译这条路。所以哪怕你这次用预编译包搞定了把这套编译流程走通一遍也不亏它决定了你以后遇到版本问题时是束手无策还是能自己动手。1.3 为什么 Windows 上特别容易出问题Linux 上编译 PostgreSQL 扩展基本是make make install两条命令因为 PostgreSQL 用 autoconf 那套构建系统扩展跟着 PGXS 走就行。Windows 上 PostgreSQL 是用 MSVC 构建的没有 autoconf也就没有 PGXS扩展必须自己写一份nmake的 makefilepgvector 仓库里那个Makefile.win就是干这个的。这就带来三个连锁问题。第一编译器必须是 MSVC 的cl.exeMinGW 那一套在链接postgres.lib时会出现符号修饰和 C 运行时库不匹配的问题能编过也可能在加载时崩。第二C 运行时库的版本必须和 PostgreSQL 服务端一致PG 16 之后官方包基本用 VS2022 的 v143 工具集你拿 VS2019 编出来的 DLL 加载时可能报找不到入口点。第三Windows 的文件锁机制会让nmake install在服务运行期间失败这个坑我下面会单独讲。把这三条记住后面遇到的大部分报错你都能对上号。2. 动手之前把环境变量和版本号对齐2.1 PostgreSQL 安装包里到底有没有编译需要的头文件这一步是整条链路里最容易想当然的地方。很多人以为装了 PostgreSQL 就有开发头文件实际上安装程序给的组件是有区别的。pgvector 编译需要的是postgres.h位置在%PGROOT%\include\server\postgres.h还需要%PGROOT%\lib\postgres.lib这个导入库用于链接。先做一次存在性检查比什么都可靠。打开命令行把PGROOT换成你实际的安装路径dir C:\Program Files\PostgreSQL\17\include\server\postgres.h dir C:\Program Files\PostgreSQL\17\lib\postgres.lib dir C:\Program Files\PostgreSQL\17\bin\pg_config.exe三个文件都在说明这套安装包含服务端开发组件可以直接往下走。如果include\server目录整个不存在说明安装时只装了客户端或者精简组件这时候别硬扛重新跑一遍安装程序把 PostgreSQL Server 相关的组件补上比在网上找零散头文件靠谱得多。顺带确认一下架构。现在基本没人装 32 位 PostgreSQL 了但老机器上确实见过。用pg_config看一眼C:\Program Files\PostgreSQL\17\bin\pg_config.exe --version输出的版本号要和你实际连的服务端版本一致。我遇到过装了 PG 16 和 PG 17 两个实例、PATH 里排在前面的是 16 的情况结果对着 16 的头文件编译装到了 17 的目录里CREATE EXTENSION直接报The specified procedure could not be found。这种错误信息完全不指向真正的原因非常耗时间。2.2 MSVC 工具链版本和 PostgreSQL 要对得上PostgreSQL 官方 Windows 包从 16 开始基本是 VS2022 构建的所以最稳的是装 Visual Studio 2022 的生成工具。不需要完整的 IDE装 Build Tools 版本就够关键是在安装向导里勾上「使用 C 的桌面开发」这个工作负载它会带上cl.exe、link.exe和nmake.exe。装完之后不要直接开普通命令行cl.exe不在 PATH 里。要用开发者命令提示符或者手动调vcvars64.bat。我习惯写一个批处理文件放在项目目录下免得每次找路径echo off call C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat if errorlevel 1 ( echo vcvars64 调用失败检查 VS 安装路径 exit /b 1 ) set PGROOTC:\Program Files\PostgreSQL\17 echo 环境就绪PGROOT%PGROOT%vcvars64.bat的具体路径和你的 VS 版本、安装位置有关Build Tools 一般在上面这个位置Community 版在C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\下。这个脚本干的事就是把cl.exe的目录、Windows SDK 的目录、库目录一股脑塞进环境变量跑完之后where cl应该能定位到编译器。验证一下架构对不对cl直接执行会输出版本横幅里面会写明是 x64 还是 x86。必须是 x64和 PostgreSQL 的位数一致。混着来的话链接阶段会报一堆看起来莫名其妙的符号错误。2.3 目录约定和路径里的空格Windows 上有一个反复坑人的点C:\Program Files中间带空格。nmake对带空格的变量处理得很别扭Makefile.win里给PGINC、PGLIB加引号但你自己传的变量如果忘了引号展开之后就是断开的两个参数。我的做法是统一用带引号的set形式set PGROOTC:\Program Files\PostgreSQL\17而不是set PGROOTC:\Program Files\PostgreSQL\17。后者在set命令本身是没问题的但如果你把它拼到别的命令里行尾的空格会被一起吃进变量值导致路径末尾多一个空格报错信息里又看不出来非常难受。源码目录反而不要带空格、不要带中文。我吃过一次亏把源码放在D:\我的项目\pgvector下面编译到一半时报找不到中间文件排查了半天才发现是路径编码问题。现在统一放C:\dev\pgvector这种结构短、纯 ASCII、无空格。还有一个准备动作确认你要装扩展的那个 PostgreSQL 服务是不是在跑。跑着也没关系但记住我们在第 3 章装 DLL 的时候需要停一下原因后面讲。3. 从克隆到编译把 vector.dll 造出来3.1 克隆源码并且把版本钉死不要直接 clone 默认分支就编。默认分支是开发中的代码可能引用了尚未发布的 API编出来的版本号和vector.control里声明的对不上CREATE EXTENSION会报找不到对应的 SQL 脚本。正确的做法是按 tag 拉git clone --branch v0.8.0 --depth 1 https://github.com/pgvector/pgvector.git C:\dev\pgvector--depth 1只拉最新一次提交仓库不大但能省一点时间。tag 名字去 Releases 页面查写这篇文章时较新的稳定版是 0.8.x 系列它带的vector--0.8.0.sql会跟着vector.control里的default_version一起被安装。拉下来之后先看目录结构理解每个文件的作用出问题时才知道该查哪儿pgvector/ ├── Makefile # Linux/macOS 用Windows 不走这条 ├── Makefile.win # 我们真正要执行的 ├── vector.control # 扩展元信息安装时复制到 share\extension ├── sql/ │ ├── vector--0.8.0.sql # 建类型、建函数、建操作符的脚本 │ └── vector--0.7.4--0.8.0.sql └── src/ ├── vector.c ├── hnsw.c ├── ivfflat.c └── ...vector.control的内容值得看一眼它决定了 PostgreSQL 怎么认识这个扩展comment vector data type and ivfflat and hnsw access methods default_version 0.8.0 module_pathname $libdir/vector relocatable truemodule_pathname里的$libdir会在运行时展开成 PostgreSQL 的 lib 目录也就是C:\Program Files\PostgreSQL\17\lib。这就是为什么 DLL 必须放到那个位置也是为什么装错版本目录会直接导致加载失败。3.2 读懂 Makefile.win 里的关键变量Makefile.win不长但几个变量决定了成败。默认它里面写死了一个PGROOT比如C:\Program Files\PostgreSQL\17如果你装的不是这个版本两条路改文件或者用命令行覆盖。我选后者因为改文件之后git status永远是脏的下次 pull 还容易冲突。覆盖方式就是在nmake命令里传参nmake /F Makefile.win PGROOTC:\Program Files\PostgreSQL\17它有这几个变量值得知道PGROOTPostgreSQL 安装根目录PGINC和PGLIB都从它派生。PGINC头文件目录实际编译时会加/I$(PGINC)\server因为postgres.h在server子目录里。PGLIB库目录链接时用postgres.lib。OPTFLAGS优化选项默认/O2。如果定义DEBUG会变成/Od /Zi调试崩溃时有用。编译产出的目标文件在src目录下最终链接成vector.dll。链接那一行大概是这个形状link /DLL /OUT:vector.dll src\vector.obj src\hnsw.obj ... C:\Program Files\PostgreSQL\17\lib\postgres.lib看到LNK1104: 无法打开文件 postgres.lib就知道是PGLIB不对或者路径带空格没处理好。这类错误信息其实很直白怕的是不看错误码直接上网搜。3.3 执行编译和安装的完整命令序列把前面几步串起来一次完整的编译安装是这样的。建议存成一个.bat文件以后换机器直接改两行路径就能复用echo off call C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat set PGROOTC:\Program Files\PostgreSQL\17 cd /d C:\dev\pgvector echo [1/3] 清理上次产物 nmake /F Makefile.win clean PGROOT%PGROOT% echo [2/3] 编译 nmake /F Makefile.win PGROOT%PGROOT% if errorlevel 1 ( echo 编译失败检查上面的报错 exit /b 1 ) echo [3/3] 安装 nmake /F Makefile.win install PGROOT%PGROOT% if errorlevel 1 ( echo 安装失败通常是权限或文件占用 exit /b 1 ) echo 完成有一个细节必须提醒install这一步在写C:\Program Files下面的目录普通权限会失败。解决办法是用管理员身份打开命令行再跑。我见过有人用普通终端跑报拒绝访问以为是编译问题折腾半天。另一个更隐蔽的失败是 DLL 被占用。如果你的 PostgreSQL 服务正在运行并且之前已经加载过vector.dll比如你之前装过旧版本或者这是第二次编译复制会被拒绝提示文件正在被另一个程序使用。这时候有两个选择停服务再装或者直接重启服务。我的习惯是先停net stop postgresql-x64-17 nmake /F Makefile.win install PGROOTC:\Program Files\PostgreSQL\17 net start postgresql-x64-17服务名不一定叫这个用sc query type service state all | findstr /i postgres查一下实际名字。第一次安装的时候因为服务还没加载过这个 DLL通常不会被占用所以「第一次顺利、第二次报错」是很常见的现象别怀疑自己。3.4 确认扩展真的装进去了编译装完先看文件系统层面是否到位这是最快的验证dir C:\Program Files\PostgreSQL\17\lib\vector.dll dir C:\Program Files\PostgreSQL\17\share\extension\vector*lib下应该有vector.dllshare\extension下应该有vector.control和若干个vector--*.sql。如果 SQL 脚本没复制过去CREATE EXTENSION会报extension vector has no update path或者干脆说找不到脚本。然后进数据库CREATE EXTENSION vector; \dx vector\dx会列出扩展名、版本、schema。版本号要和你编译的 tag 一致。如果这一步报could not open extension control file说明share\extension里没有vector.control回到上一步检查 install 是不是失败了。最后做一个类型层面的冒烟测试这一步能同时验证 DLL 加载和 SQL 脚本注册SELECT [1,2,3]::vector AS v, vector_dims([1,2,3]::vector) AS dims;能返回[1,2,3]和3说明类型系统、输入函数、DLL 全部正常工作。到这儿编译环节就算彻底打通了后面全是 SQL 的事。注意如果CREATE EXTENSION报could not load library ... The specified procedure could not be found九成是编译用的头文件版本和运行的服务端版本不一致。用pg_config --version和SELECT version();对一遍不要在这个错误上做无用功。4. 跑通第一条相似度查询建表、造数、排序4.1 vector 类型、维度约束和三种常用距离vector(n)里的n是维度必须固定。建表时写vector(768)之后插入的每一行都必须是 768 维多一维少一维都会报错。这个约束看着烦实际是好事它保证同一个列里的向量可以互相比较距离函数不会在运行期才发现维度不匹配。维度上限也要心里有数vector类型本身最多支持 16000 维但一旦要建 HNSW 或 IVFFlat 索引上限降到 2000 维。超过 2000 维的列可以存、可以算距离但建不了索引查询只能全表扫。如果你的嵌入模型输出是 3072 维要么降维要么用halfvec类型半精度索引上限 4000 维这是后话第一次跑通先用低维数据。距离操作符有三个必须记住操作符含义配合的索引操作符类数值特性-欧氏距离L2vector_l2_ops越小越相似无上界#负内积vector_ip_ops越小越相似注意是负的余弦距离vector_cosine_ops范围 0 到 2越小越相似#这个负号坑过不少人。内积本身是越大越相似但 PostgreSQL 的索引框架统一按「距离升序」来组织所以 pgvector 返回的是内积的相反数你ORDER BY embedding # [...]拿到的第一行就是内积最大的那行。逻辑上没问题但你如果自己拿内积值做阈值判断符号要记得反过来。选哪个文本嵌入一般用余弦距离因为它对向量长度不敏感图像检索里 L2 用得更多推荐系统里内积常见。关键原则是查询用的操作符必须和建索引时指定的操作符类对应否则索引不会被使用。这一点在第 5 章还会展开。4.2 造一批测试数据两种方式的取舍建表很简单CREATE TABLE items ( id bigserial PRIMARY KEY, category text, embedding vector(3) );3 维是为了让结果肉眼可验证。先插几条手工数据确认基本行为INSERT INTO items (category, embedding) VALUES (a, [1,1,1]), (b, [2,2,2]), (c, [1,1,2]), (d, [10,10,10]); SELECT id, category, embedding - [1,1,1] AS dist FROM items ORDER BY embedding - [1,1,1] LIMIT 3;第一行应该是自己距离 0。这种小数据量的验证很有必要它把「扩展装错了」和「查询写错了」两类问题彻底分开。数据量上去之后手工 INSERT 就不现实了。用generate_series造随机数据pgvector 提供了数组到 vector 的隐式转换可以直接把float8[]转过来INSERT INTO items (category, embedding) SELECT cat_ || (i % 5), ARRAY[random(), random(), random()]::vector FROM generate_series(1, 20000) AS i;两万行三維数据一两秒就完事。真实场景维度高得多768 维的写法是这样CREATE TABLE docs ( id bigserial PRIMARY KEY, content text, embedding vector(768) ); INSERT INTO docs (content, embedding) SELECT doc_ || i, (SELECT array_agg(random()::real) FROM generate_series(1, 768))::vector FROM generate_series(1, 5000) AS i;这个会慢一些因为每一行都要跑一次子查询生成 768 个随机数五千行大概几秒到十几秒。数据量再大的话不要用 INSERT ... SELECT 硬灌走COPY快一个数量级先用脚本生成 CSV向量列写成[0.1,0.2,...]的文本形式然后\copy docs FROM data.csv WITH (FORMAT csv)。我做过对比同样一百万行 768 维数据逐行 INSERT 要跑接近一小时COPY 只要几分钟差距全在解析和 WAL 上。4.3 写出第一条查询并读懂执行计划有了数据第一条真正的相似度查询就一行SELECT id, category, embedding - [0.5,0.5,0.5] AS distance FROM items ORDER BY embedding - [0.5,0.5,0.5] LIMIT 5;这里有个写法上的讲究SELECT列表里的距离表达式和ORDER BY里的表达式必须完全一致包括操作符。写成SELECT embedding [...]但ORDER BY embedding - [...]PostgreSQL 不会认为是同一个表达式索引也用不上。想让两边同步可以起个别名再按别名排序但用别名排序在某些版本上会影响索引匹配我一般老老实实写两遍或者用子查询包一层。看执行计划确认它是怎么跑的EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding - [0.5,0.5,0.5] LIMIT 5;两万行没有索引的情况下你会看到Seq Scan加SortSort Method: top-N heapsort。这是因为LIMIT 5让 PostgreSQL 只需要维护一个大小为 5 的堆。这个细节值得理解没有索引时带 LIMIT 的向量查询并不是把所有行排序一遍它是 top-N实际耗时和 LIMIT 大小关系不大主要跟行数成正比。两万行三維大概几毫秒一百万行 768 维就会到秒级这才是需要索引的原因。结果怎么解读距离是数值不是百分比。余弦距离 0 表示方向完全一致1 表示正交2 表示完全相反。欧氏距离则依赖向量的绝对长度同一个语义在不同长度的向量上 L2 距离可能差很多。验证结果合不合理最好的办法是拿一条已知记录当查询向量看它自己是不是排第一SELECT id, embedding - (SELECT embedding FROM items WHERE id 42) AS d FROM items ORDER BY embedding - (SELECT embedding FROM items WHERE id 42) LIMIT 3;第一行的d必须是 0浮点误差下可能是极小的数id 是 42。如果不是说明你的数据写入或者类型转换环节有问题先别往下走。5. 加上索引从全表扫到近似检索5.1 HNSW 和 IVFFlat 该怎么选两种索引的实现思路完全不同选择逻辑也不一样。IVFFlat 是「聚类 倒排」建索引时把所有向量聚成lists个簇查询时只扫距离查询向量最近的probes个簇。它的特点是建索引快、内存占用小但必须在有数据之后建因为聚类需要样本空表建出来的索引是空的后续插入的数据分布会很差。另一个坑是数据分布变化大的时候要重建索引否则簇的划分会失真。HNSW 是「分层小世界图」每个向量是图上的一个节点查询时从稀疏的顶层往下走逐层收敛。它的特点是查询快、召回高、支持增量插入新数据直接插进图里代价是建索引慢、内存占用大。一百万行 768 维数据HNSW 建索引可能要几十分钟maintenance_work_mem给不够还会退化成磁盘排序慢得离谱。我的选择逻辑很直接场景推荐理由数据基本一次性导入、很少更新IVFFlat建得快内存省数据持续增量写入HNSW支持增量不用重建召回率要求高95%HNSW同等参数下召回更好内存紧张、数据量大IVFFlat索引体积小很多第一次跑通建议先用 HNSW因为它的参数更少、不用等数据齐、行为更符合直觉出问题也容易判断。5.2 建索引、调参数、验证召回给三維的测试表建 HNSW 索引CREATE INDEX items_embedding_hnsw_idx ON items USING hnsw (embedding vector_l2_ops);注意vector_l2_ops对应的是-操作符。如果你的查询要按余弦距离排序索引就得建成vector_cosine_ops否则查询时用不上索引。这个对应关系是死规则没有自动适配。数据量大的时候建索引前把内存参数调上去能省几倍时间SET maintenance_work_mem 2GB; SET max_parallel_maintenance_workers 4; CREATE INDEX docs_embedding_hnsw_idx ON docs USING hnsw (embedding vector_cosine_ops) WITH (m 16, ef_construction 64);m是每个节点的最大连接数默认 16调大能提高召回但增加内存和建索引时间一般 16 到 32 之间够用。ef_construction是建索引时的候选队列大小默认 64数据分布复杂时调到 128 或 200 能明显改善图的质量代价是建索引更慢。查询侧还有一个参数hnsw.ef_search默认 40它控制搜索时候选队列的大小。这是运行时可调的也是最实用的调优点SET hnsw.ef_search 100; SELECT id FROM docs ORDER BY embedding [...] LIMIT 10;ef_search必须大于等于LIMIT的值否则拿不到足够的候选。这个参数和召回率、延迟是三角关系调大召回高但慢调小快但可能漏。工程上的做法是先离线测一组召回数据选一个满足业务要求的点固定下来。怎么测召回思路是拿索引结果和精确结果做交集。用临时表把两次查询的结果存下来对比-- 精确结果强制走顺序扫描 SET enable_indexscan off; CREATE TEMP TABLE exact_res AS SELECT id FROM docs ORDER BY embedding (SELECT embedding FROM docs WHERE id 1) LIMIT 20; -- 近似结果强制走索引 SET enable_seqscan off; SET hnsw.ef_search 40; CREATE TEMP TABLE ann_res AS SELECT id FROM docs ORDER BY embedding (SELECT embedding FROM docs WHERE id 1) LIMIT 20; SELECT count(*)::float / 20 AS recall FROM exact_res e JOIN ann_res a USING (id);recall就是召回率。五千行 768 维随机数据、ef_search 40的情况下召回通常在 0.9 以上如果明显偏低把ef_search往上调或者重建索引时提高ef_construction。要注意随机数据本身没有聚类结构真实嵌入数据的召回一般比随机数据更好所以这个测试是偏保守的。5.3 索引明明建了却不生效的四种情况这是实战里最高频的问题我按遇到频率排个序。第一种操作符和操作符类不匹配。索引建的是vector_l2_ops查询写的是规划器不会用这个索引。反过来的情况也一样。判断方法很简单看EXPLAIN输出里有没有Index Scan using ...出现Seq Scan就是没用上。第二种距离表达式被包了一层。比如ORDER BY (embedding - [...])::float8加了个类型转换表达式就变了索引匹配不上。或者写成ORDER BY 1 - (embedding [...])想转成相似度同样会破坏匹配。相似度转换放到外层做别动ORDER BY里的表达式。第三种表太小规划器认为全表扫更便宜。几千行的表走索引的随机 IO 可能比顺序扫描还慢规划器选Seq Scan是理性的。测试索引效果时用SET enable_seqscan off强制走索引但不要在生产上留这个设置。第四种索引建在错误的列或者错误的表上。多实例环境下尤其容易连到了 A 库却在 B 库建索引然后对着 A 库查。我现在的习惯是建完索引立刻在同一会话里跑一次EXPLAIN确认索引名出现在计划里再干别的。还有一个小细节LIMIT的值如果大于索引能提供的候选数规划器可能放弃索引。比如ef_search 40而LIMIT 100理论上拿不到 100 个有质量的候选某些情况下规划器会保守地选择全表扫。6. 踩坑实录一份按现象查的排查表6.1 编译阶段的典型报错nmake找不到。现象是命令行提示nmake 不是内部或外部命令。原因只有一个没有在vcvars64.bat初始化过的环境里执行。注意nmake.exe是随 VS 的 C 组件装的只装 VS 的 .NET 或者 Python 工作负载是不带的。fatal error C1083: 无法打开包括文件: postgres.h。这是PGROOT不对或者路径带空格被截断了。检查%PGROOT%\include\server\postgres.h是否存在再检查nmake命令里PGROOT有没有加引号。还有一个少见情况PostgreSQL 装在 D 盘但你set PGROOT的时候写的是 C 盘路径。LNK1104: 无法打开文件 postgres.lib。链接器找不到导入库。确认%PGROOT%\lib\postgres.lib存在。有些精简安装包不带这个文件需要重装并勾选服务端组件。LNK2001: 无法解析的外部符号 _pg_detoast_datum_packed之类的符号错误。基本是架构不匹配用 x86 的cl对着 x64 的postgres.lib链接。重新开一个 x64 开发者命令行cl版本横幅里应该写 x64。NMAKE : fatal error U1077: cl.exe : 返回代码0x2。这只是一个包装错误真正的原因在上面几行。往上翻找第一个error C开头的行。6.2 运行阶段的典型报错could not open extension control file .../vector.control: No such file or directory。install没执行或者装到了另一个 PostgreSQL 实例的目录。用pg_config --sharedir查一下服务端认识的那个目录和你实际复制的位置对一下。extension vector is not available。vector.control在但对应的vector--x.y.z.sql不在或者default_version写的版本号没有对应的脚本文件。检查share\extension下的文件名。could not load library .../vector.dll: The specified procedure could not be found。编译时的 PostgreSQL 版本和运行的服务端版本不一致。这是最坑的一类因为文件名、路径都正确只是二进制接口对不上。用SELECT version();确认服务端版本然后对着对应版本的头文件重编。ERROR: column cannot have more than 2000 dimensions for hnsw index。维度超了索引上限。要么降维要么换halfvec上限 4000 维要么放弃索引接受全表扫。这个限制是硬编码的不是配置问题。ERROR: operator class vector_l2_ops does not exist for access method hnsw。扩展没装成功或者装在了别的 schema、当前search_path找不到。先\dx确认再\dn看 schema。6.3 一张可以直接对照的速查表现象大概率原因处理动作nmake不是命令未初始化 MSVC 环境跑vcvars64.bat找不到postgres.hPGROOT错误或路径带空格检查路径加引号install报拒绝访问权限不足管理员身份运行install报文件被占用服务已加载旧 DLL停服务再装或重启服务CREATE EXTENSION找不到 controlinstall 未执行或目录不对用pg_config --sharedir核对加载 DLL 报找不到过程头文件版本与服务端不一致对齐版本重编建索引报维度超限超过 2000 维降维或改halfvec建了索引仍全表扫操作符与操作符类不匹配改查询或重建索引查询结果第一条不是自己维度或数据写入有问题检查插入的向量长度召回率偏低ef_search太小调大参数或重建索引这张表我在三台机器上迭代出来的基本上遇到问题往里一套就能定位。真正花时间的从来不是解决问题而是从报错信息定位到是哪一环出的错所以我把「现象」这一列写得尽量贴近你屏幕上看到的原文。还有一个跨阶段的坑值得单独说不要在同一个终端里混用多个 PostgreSQL 版本的pg_config。PATH 里排前面的那个决定了pg_config指向谁而psql可能连的是另一个实例。我现在的做法是在项目目录下放一个.bat开头就把PGROOT和PATH显式设死不依赖系统环境换机器只需要改这一处。7. 我自己的几点实操体会这套流程我前后走过五六遍最大的感受是Windows 上编译扩展的难点不在技术本身而在「版本对齐」这四个字。编译器版本、C 运行时版本、PostgreSQL 头文件版本、服务端版本、扩展版本五个东西必须拧成一股绳任何一个错位都会以一个完全不相关的错误信息呈现出来。所以我现在养成一个习惯动手之前先把这五个版本号抄在一张纸上编完对照一遍比事后排查省太多时间。另一个体会是不要跳过小数据验证。我见过太多人一上来就灌一百万行然后查询结果不对根本分不清是数据问题、索引问题还是安装问题。先用四行三維数据把CREATE EXTENSION、插入、排序、EXPLAIN全部走一遍二十分钟的事能把后面几小时的排查挡掉。这个习惯我建议每个刚开始用 pgvector 的人都养成向量检索的问题有一半出在「以为装好了其实没装好」上。最后说个容易被忽略的维护细节vector.dll是可以在服务运行期间被替换的但替换之后已经在跑的连接仍然用旧版本只有新建连接才会加载新的 DLL。所以如果你改源码重新编译装完记得确认一下是不是所有应用连接都重连过最简单的办法就是重启一次服务。这个细节在本地开发时无关痛痒但在多实例、连接池的环境下会表现成「有的进程正常、有的报错」这种非常难查的现象。 
长河君 · 2026/11/2 8:34:51 · 阅读 1.2k Windows下源码编译pgvector并跑通HNSW向量检索
第一次在 Windows 上给 PostgreSQL 编译扩展十有八九会卡在nmake那一行。我前后在三台配置不同的机器上把 pgvector 从克隆源码到跑通第一条相似度查询走了一遍从 PostgreSQL 13 一路跟到 17踩的坑高度雷同postgres.h找不到、vector.dll被服务进程占用、编出来的库和运行的服务端版本对不上、建完 HNSW 索引却发现查询走了全表扫描。这篇就把整个流程摊开讲从环境怎么对齐、Makefile.win里那几个变量是什么意思、装完之后怎么确认扩展真的挂上了一直到造测试数据、写ORDER BY embedding - [...]、给查询加上近似索引并验证召回率。内容偏向实操适合已经会用 psql、想在 Windows 本机跑通向量检索的开发者也适合被编译报错磨掉耐心、想找一份完整对照表的人。1. 先搞清楚 Windows 上编译 pgvector 到底难在哪1.1 pgvector 是什么它给你的数据库补了哪块能力pgvector 是 PostgreSQL 的一个扩展核心就干三件事提供一个vector数据类型用来存定长浮点数组提供一组距离操作符用来做相似度比较提供两种近似最近邻索引IVFFlat 和 HNSW用来把暴力比较压到可接受的时间。它不是一个独立服务不占端口不额外起进程装好之后就是数据库里多了一个类型加几个函数跟你平时用jsonb、uuid没有任何使用习惯上的差别。它解决的问题很具体。假设你有一张商品表每条记录有一个 768 维的文本嵌入向量用户输入一句话你要找语义最接近的 20 个商品。没有 pgvector 的时候你得把向量搬到专门的向量数据库里然后面对数据同步、事务一致性、双写失败补偿这一堆破事。有了 pgvector向量就是表里的一列跟价格、标题放在同一行WHERE条件能和向量排序写在同一条 SQL 里事务、备份、权限体系全部复用。适合谁用我的判断标准是数据量在一千万行以内、对召回延迟要求在几十毫秒量级、团队不想再维护一套异构存储的pgvector 基本是首选。数据量再往上、或者需要多副本分片检索的才需要考虑专用方案。这个边界先划清楚后面折腾编译才有意义。1.2 三条路可选预编译包、容器镜像、源码编译在 Windows 上拿到能用的 pgvector实际有三条路各有各的适用场景我先把取舍摆出来你再决定要不要跟着后面折腾源码。方式上手成本版本匹配风险适合场景官方 Releases 里的 Windows 二进制包最低解压复制即可中包只覆盖特定 PG 大版本版本正好对得上只想快速验证容器镜像含 pgvector 的 PostgreSQL 镜像低一条命令起服务低本地开发、CI、不依赖本机 PostgreSQL克隆源码 MSVC 编译高要配工具链最低头文件和运行库都自己控本机已有 PostgreSQL 实例、需要特定小版本、或要改源码我之所以坚持走第三条是因为前两条在真实工作里经常被卡住预编译包不是每个小版本、每个 PG 大版本都齐碰上公司内网镜像没有你需要的 tag就只能回到源码容器方案在本地开发很爽但如果你要连接的是本机已经跑了两年、装着其他扩展、配置改过十几处的那个 PostgreSQL 实例把数据迁到容器里往往比编译一次扩展麻烦得多。还有一类更隐蔽的情况你需要对着某个特定 commit 编译因为上游刚合入的补丁正好修了你遇到的问题而正式版还没发。这种时候只有源码编译这条路。所以哪怕你这次用预编译包搞定了把这套编译流程走通一遍也不亏它决定了你以后遇到版本问题时是束手无策还是能自己动手。1.3 为什么 Windows 上特别容易出问题Linux 上编译 PostgreSQL 扩展基本是make make install两条命令因为 PostgreSQL 用 autoconf 那套构建系统扩展跟着 PGXS 走就行。Windows 上 PostgreSQL 是用 MSVC 构建的没有 autoconf也就没有 PGXS扩展必须自己写一份nmake的 makefilepgvector 仓库里那个Makefile.win就是干这个的。这就带来三个连锁问题。第一编译器必须是 MSVC 的cl.exeMinGW 那一套在链接postgres.lib时会出现符号修饰和 C 运行时库不匹配的问题能编过也可能在加载时崩。第二C 运行时库的版本必须和 PostgreSQL 服务端一致PG 16 之后官方包基本用 VS2022 的 v143 工具集你拿 VS2019 编出来的 DLL 加载时可能报找不到入口点。第三Windows 的文件锁机制会让nmake install在服务运行期间失败这个坑我下面会单独讲。把这三条记住后面遇到的大部分报错你都能对上号。2. 动手之前把环境变量和版本号对齐2.1 PostgreSQL 安装包里到底有没有编译需要的头文件这一步是整条链路里最容易想当然的地方。很多人以为装了 PostgreSQL 就有开发头文件实际上安装程序给的组件是有区别的。pgvector 编译需要的是postgres.h位置在%PGROOT%\include\server\postgres.h还需要%PGROOT%\lib\postgres.lib这个导入库用于链接。先做一次存在性检查比什么都可靠。打开命令行把PGROOT换成你实际的安装路径dir C:\Program Files\PostgreSQL\17\include\server\postgres.h dir C:\Program Files\PostgreSQL\17\lib\postgres.lib dir C:\Program Files\PostgreSQL\17\bin\pg_config.exe三个文件都在说明这套安装包含服务端开发组件可以直接往下走。如果include\server目录整个不存在说明安装时只装了客户端或者精简组件这时候别硬扛重新跑一遍安装程序把 PostgreSQL Server 相关的组件补上比在网上找零散头文件靠谱得多。顺带确认一下架构。现在基本没人装 32 位 PostgreSQL 了但老机器上确实见过。用pg_config看一眼C:\Program Files\PostgreSQL\17\bin\pg_config.exe --version输出的版本号要和你实际连的服务端版本一致。我遇到过装了 PG 16 和 PG 17 两个实例、PATH 里排在前面的是 16 的情况结果对着 16 的头文件编译装到了 17 的目录里CREATE EXTENSION直接报The specified procedure could not be found。这种错误信息完全不指向真正的原因非常耗时间。2.2 MSVC 工具链版本和 PostgreSQL 要对得上PostgreSQL 官方 Windows 包从 16 开始基本是 VS2022 构建的所以最稳的是装 Visual Studio 2022 的生成工具。不需要完整的 IDE装 Build Tools 版本就够关键是在安装向导里勾上「使用 C 的桌面开发」这个工作负载它会带上cl.exe、link.exe和nmake.exe。装完之后不要直接开普通命令行cl.exe不在 PATH 里。要用开发者命令提示符或者手动调vcvars64.bat。我习惯写一个批处理文件放在项目目录下免得每次找路径echo off call C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat if errorlevel 1 ( echo vcvars64 调用失败检查 VS 安装路径 exit /b 1 ) set PGROOTC:\Program Files\PostgreSQL\17 echo 环境就绪PGROOT%PGROOT%vcvars64.bat的具体路径和你的 VS 版本、安装位置有关Build Tools 一般在上面这个位置Community 版在C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\下。这个脚本干的事就是把cl.exe的目录、Windows SDK 的目录、库目录一股脑塞进环境变量跑完之后where cl应该能定位到编译器。验证一下架构对不对cl直接执行会输出版本横幅里面会写明是 x64 还是 x86。必须是 x64和 PostgreSQL 的位数一致。混着来的话链接阶段会报一堆看起来莫名其妙的符号错误。2.3 目录约定和路径里的空格Windows 上有一个反复坑人的点C:\Program Files中间带空格。nmake对带空格的变量处理得很别扭Makefile.win里给PGINC、PGLIB加引号但你自己传的变量如果忘了引号展开之后就是断开的两个参数。我的做法是统一用带引号的set形式set PGROOTC:\Program Files\PostgreSQL\17而不是set PGROOTC:\Program Files\PostgreSQL\17。后者在set命令本身是没问题的但如果你把它拼到别的命令里行尾的空格会被一起吃进变量值导致路径末尾多一个空格报错信息里又看不出来非常难受。源码目录反而不要带空格、不要带中文。我吃过一次亏把源码放在D:\我的项目\pgvector下面编译到一半时报找不到中间文件排查了半天才发现是路径编码问题。现在统一放C:\dev\pgvector这种结构短、纯 ASCII、无空格。还有一个准备动作确认你要装扩展的那个 PostgreSQL 服务是不是在跑。跑着也没关系但记住我们在第 3 章装 DLL 的时候需要停一下原因后面讲。3. 从克隆到编译把 vector.dll 造出来3.1 克隆源码并且把版本钉死不要直接 clone 默认分支就编。默认分支是开发中的代码可能引用了尚未发布的 API编出来的版本号和vector.control里声明的对不上CREATE EXTENSION会报找不到对应的 SQL 脚本。正确的做法是按 tag 拉git clone --branch v0.8.0 --depth 1 https://github.com/pgvector/pgvector.git C:\dev\pgvector--depth 1只拉最新一次提交仓库不大但能省一点时间。tag 名字去 Releases 页面查写这篇文章时较新的稳定版是 0.8.x 系列它带的vector--0.8.0.sql会跟着vector.control里的default_version一起被安装。拉下来之后先看目录结构理解每个文件的作用出问题时才知道该查哪儿pgvector/ ├── Makefile # Linux/macOS 用Windows 不走这条 ├── Makefile.win # 我们真正要执行的 ├── vector.control # 扩展元信息安装时复制到 share\extension ├── sql/ │ ├── vector--0.8.0.sql # 建类型、建函数、建操作符的脚本 │ └── vector--0.7.4--0.8.0.sql └── src/ ├── vector.c ├── hnsw.c ├── ivfflat.c └── ...vector.control的内容值得看一眼它决定了 PostgreSQL 怎么认识这个扩展comment vector data type and ivfflat and hnsw access methods default_version 0.8.0 module_pathname $libdir/vector relocatable truemodule_pathname里的$libdir会在运行时展开成 PostgreSQL 的 lib 目录也就是C:\Program Files\PostgreSQL\17\lib。这就是为什么 DLL 必须放到那个位置也是为什么装错版本目录会直接导致加载失败。3.2 读懂 Makefile.win 里的关键变量Makefile.win不长但几个变量决定了成败。默认它里面写死了一个PGROOT比如C:\Program Files\PostgreSQL\17如果你装的不是这个版本两条路改文件或者用命令行覆盖。我选后者因为改文件之后git status永远是脏的下次 pull 还容易冲突。覆盖方式就是在nmake命令里传参nmake /F Makefile.win PGROOTC:\Program Files\PostgreSQL\17它有这几个变量值得知道PGROOTPostgreSQL 安装根目录PGINC和PGLIB都从它派生。PGINC头文件目录实际编译时会加/I$(PGINC)\server因为postgres.h在server子目录里。PGLIB库目录链接时用postgres.lib。OPTFLAGS优化选项默认/O2。如果定义DEBUG会变成/Od /Zi调试崩溃时有用。编译产出的目标文件在src目录下最终链接成vector.dll。链接那一行大概是这个形状link /DLL /OUT:vector.dll src\vector.obj src\hnsw.obj ... C:\Program Files\PostgreSQL\17\lib\postgres.lib看到LNK1104: 无法打开文件 postgres.lib就知道是PGLIB不对或者路径带空格没处理好。这类错误信息其实很直白怕的是不看错误码直接上网搜。3.3 执行编译和安装的完整命令序列把前面几步串起来一次完整的编译安装是这样的。建议存成一个.bat文件以后换机器直接改两行路径就能复用echo off call C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat set PGROOTC:\Program Files\PostgreSQL\17 cd /d C:\dev\pgvector echo [1/3] 清理上次产物 nmake /F Makefile.win clean PGROOT%PGROOT% echo [2/3] 编译 nmake /F Makefile.win PGROOT%PGROOT% if errorlevel 1 ( echo 编译失败检查上面的报错 exit /b 1 ) echo [3/3] 安装 nmake /F Makefile.win install PGROOT%PGROOT% if errorlevel 1 ( echo 安装失败通常是权限或文件占用 exit /b 1 ) echo 完成有一个细节必须提醒install这一步在写C:\Program Files下面的目录普通权限会失败。解决办法是用管理员身份打开命令行再跑。我见过有人用普通终端跑报拒绝访问以为是编译问题折腾半天。另一个更隐蔽的失败是 DLL 被占用。如果你的 PostgreSQL 服务正在运行并且之前已经加载过vector.dll比如你之前装过旧版本或者这是第二次编译复制会被拒绝提示文件正在被另一个程序使用。这时候有两个选择停服务再装或者直接重启服务。我的习惯是先停net stop postgresql-x64-17 nmake /F Makefile.win install PGROOTC:\Program Files\PostgreSQL\17 net start postgresql-x64-17服务名不一定叫这个用sc query type service state all | findstr /i postgres查一下实际名字。第一次安装的时候因为服务还没加载过这个 DLL通常不会被占用所以「第一次顺利、第二次报错」是很常见的现象别怀疑自己。3.4 确认扩展真的装进去了编译装完先看文件系统层面是否到位这是最快的验证dir C:\Program Files\PostgreSQL\17\lib\vector.dll dir C:\Program Files\PostgreSQL\17\share\extension\vector*lib下应该有vector.dllshare\extension下应该有vector.control和若干个vector--*.sql。如果 SQL 脚本没复制过去CREATE EXTENSION会报extension vector has no update path或者干脆说找不到脚本。然后进数据库CREATE EXTENSION vector; \dx vector\dx会列出扩展名、版本、schema。版本号要和你编译的 tag 一致。如果这一步报could not open extension control file说明share\extension里没有vector.control回到上一步检查 install 是不是失败了。最后做一个类型层面的冒烟测试这一步能同时验证 DLL 加载和 SQL 脚本注册SELECT [1,2,3]::vector AS v, vector_dims([1,2,3]::vector) AS dims;能返回[1,2,3]和3说明类型系统、输入函数、DLL 全部正常工作。到这儿编译环节就算彻底打通了后面全是 SQL 的事。注意如果CREATE EXTENSION报could not load library ... The specified procedure could not be found九成是编译用的头文件版本和运行的服务端版本不一致。用pg_config --version和SELECT version();对一遍不要在这个错误上做无用功。4. 跑通第一条相似度查询建表、造数、排序4.1 vector 类型、维度约束和三种常用距离vector(n)里的n是维度必须固定。建表时写vector(768)之后插入的每一行都必须是 768 维多一维少一维都会报错。这个约束看着烦实际是好事它保证同一个列里的向量可以互相比较距离函数不会在运行期才发现维度不匹配。维度上限也要心里有数vector类型本身最多支持 16000 维但一旦要建 HNSW 或 IVFFlat 索引上限降到 2000 维。超过 2000 维的列可以存、可以算距离但建不了索引查询只能全表扫。如果你的嵌入模型输出是 3072 维要么降维要么用halfvec类型半精度索引上限 4000 维这是后话第一次跑通先用低维数据。距离操作符有三个必须记住操作符含义配合的索引操作符类数值特性-欧氏距离L2vector_l2_ops越小越相似无上界#负内积vector_ip_ops越小越相似注意是负的余弦距离vector_cosine_ops范围 0 到 2越小越相似#这个负号坑过不少人。内积本身是越大越相似但 PostgreSQL 的索引框架统一按「距离升序」来组织所以 pgvector 返回的是内积的相反数你ORDER BY embedding # [...]拿到的第一行就是内积最大的那行。逻辑上没问题但你如果自己拿内积值做阈值判断符号要记得反过来。选哪个文本嵌入一般用余弦距离因为它对向量长度不敏感图像检索里 L2 用得更多推荐系统里内积常见。关键原则是查询用的操作符必须和建索引时指定的操作符类对应否则索引不会被使用。这一点在第 5 章还会展开。4.2 造一批测试数据两种方式的取舍建表很简单CREATE TABLE items ( id bigserial PRIMARY KEY, category text, embedding vector(3) );3 维是为了让结果肉眼可验证。先插几条手工数据确认基本行为INSERT INTO items (category, embedding) VALUES (a, [1,1,1]), (b, [2,2,2]), (c, [1,1,2]), (d, [10,10,10]); SELECT id, category, embedding - [1,1,1] AS dist FROM items ORDER BY embedding - [1,1,1] LIMIT 3;第一行应该是自己距离 0。这种小数据量的验证很有必要它把「扩展装错了」和「查询写错了」两类问题彻底分开。数据量上去之后手工 INSERT 就不现实了。用generate_series造随机数据pgvector 提供了数组到 vector 的隐式转换可以直接把float8[]转过来INSERT INTO items (category, embedding) SELECT cat_ || (i % 5), ARRAY[random(), random(), random()]::vector FROM generate_series(1, 20000) AS i;两万行三維数据一两秒就完事。真实场景维度高得多768 维的写法是这样CREATE TABLE docs ( id bigserial PRIMARY KEY, content text, embedding vector(768) ); INSERT INTO docs (content, embedding) SELECT doc_ || i, (SELECT array_agg(random()::real) FROM generate_series(1, 768))::vector FROM generate_series(1, 5000) AS i;这个会慢一些因为每一行都要跑一次子查询生成 768 个随机数五千行大概几秒到十几秒。数据量再大的话不要用 INSERT ... SELECT 硬灌走COPY快一个数量级先用脚本生成 CSV向量列写成[0.1,0.2,...]的文本形式然后\copy docs FROM data.csv WITH (FORMAT csv)。我做过对比同样一百万行 768 维数据逐行 INSERT 要跑接近一小时COPY 只要几分钟差距全在解析和 WAL 上。4.3 写出第一条查询并读懂执行计划有了数据第一条真正的相似度查询就一行SELECT id, category, embedding - [0.5,0.5,0.5] AS distance FROM items ORDER BY embedding - [0.5,0.5,0.5] LIMIT 5;这里有个写法上的讲究SELECT列表里的距离表达式和ORDER BY里的表达式必须完全一致包括操作符。写成SELECT embedding [...]但ORDER BY embedding - [...]PostgreSQL 不会认为是同一个表达式索引也用不上。想让两边同步可以起个别名再按别名排序但用别名排序在某些版本上会影响索引匹配我一般老老实实写两遍或者用子查询包一层。看执行计划确认它是怎么跑的EXPLAIN (ANALYZE, BUFFERS) SELECT id FROM items ORDER BY embedding - [0.5,0.5,0.5] LIMIT 5;两万行没有索引的情况下你会看到Seq Scan加SortSort Method: top-N heapsort。这是因为LIMIT 5让 PostgreSQL 只需要维护一个大小为 5 的堆。这个细节值得理解没有索引时带 LIMIT 的向量查询并不是把所有行排序一遍它是 top-N实际耗时和 LIMIT 大小关系不大主要跟行数成正比。两万行三維大概几毫秒一百万行 768 维就会到秒级这才是需要索引的原因。结果怎么解读距离是数值不是百分比。余弦距离 0 表示方向完全一致1 表示正交2 表示完全相反。欧氏距离则依赖向量的绝对长度同一个语义在不同长度的向量上 L2 距离可能差很多。验证结果合不合理最好的办法是拿一条已知记录当查询向量看它自己是不是排第一SELECT id, embedding - (SELECT embedding FROM items WHERE id 42) AS d FROM items ORDER BY embedding - (SELECT embedding FROM items WHERE id 42) LIMIT 3;第一行的d必须是 0浮点误差下可能是极小的数id 是 42。如果不是说明你的数据写入或者类型转换环节有问题先别往下走。5. 加上索引从全表扫到近似检索5.1 HNSW 和 IVFFlat 该怎么选两种索引的实现思路完全不同选择逻辑也不一样。IVFFlat 是「聚类 倒排」建索引时把所有向量聚成lists个簇查询时只扫距离查询向量最近的probes个簇。它的特点是建索引快、内存占用小但必须在有数据之后建因为聚类需要样本空表建出来的索引是空的后续插入的数据分布会很差。另一个坑是数据分布变化大的时候要重建索引否则簇的划分会失真。HNSW 是「分层小世界图」每个向量是图上的一个节点查询时从稀疏的顶层往下走逐层收敛。它的特点是查询快、召回高、支持增量插入新数据直接插进图里代价是建索引慢、内存占用大。一百万行 768 维数据HNSW 建索引可能要几十分钟maintenance_work_mem给不够还会退化成磁盘排序慢得离谱。我的选择逻辑很直接场景推荐理由数据基本一次性导入、很少更新IVFFlat建得快内存省数据持续增量写入HNSW支持增量不用重建召回率要求高95%HNSW同等参数下召回更好内存紧张、数据量大IVFFlat索引体积小很多第一次跑通建议先用 HNSW因为它的参数更少、不用等数据齐、行为更符合直觉出问题也容易判断。5.2 建索引、调参数、验证召回给三維的测试表建 HNSW 索引CREATE INDEX items_embedding_hnsw_idx ON items USING hnsw (embedding vector_l2_ops);注意vector_l2_ops对应的是-操作符。如果你的查询要按余弦距离排序索引就得建成vector_cosine_ops否则查询时用不上索引。这个对应关系是死规则没有自动适配。数据量大的时候建索引前把内存参数调上去能省几倍时间SET maintenance_work_mem 2GB; SET max_parallel_maintenance_workers 4; CREATE INDEX docs_embedding_hnsw_idx ON docs USING hnsw (embedding vector_cosine_ops) WITH (m 16, ef_construction 64);m是每个节点的最大连接数默认 16调大能提高召回但增加内存和建索引时间一般 16 到 32 之间够用。ef_construction是建索引时的候选队列大小默认 64数据分布复杂时调到 128 或 200 能明显改善图的质量代价是建索引更慢。查询侧还有一个参数hnsw.ef_search默认 40它控制搜索时候选队列的大小。这是运行时可调的也是最实用的调优点SET hnsw.ef_search 100; SELECT id FROM docs ORDER BY embedding [...] LIMIT 10;ef_search必须大于等于LIMIT的值否则拿不到足够的候选。这个参数和召回率、延迟是三角关系调大召回高但慢调小快但可能漏。工程上的做法是先离线测一组召回数据选一个满足业务要求的点固定下来。怎么测召回思路是拿索引结果和精确结果做交集。用临时表把两次查询的结果存下来对比-- 精确结果强制走顺序扫描 SET enable_indexscan off; CREATE TEMP TABLE exact_res AS SELECT id FROM docs ORDER BY embedding (SELECT embedding FROM docs WHERE id 1) LIMIT 20; -- 近似结果强制走索引 SET enable_seqscan off; SET hnsw.ef_search 40; CREATE TEMP TABLE ann_res AS SELECT id FROM docs ORDER BY embedding (SELECT embedding FROM docs WHERE id 1) LIMIT 20; SELECT count(*)::float / 20 AS recall FROM exact_res e JOIN ann_res a USING (id);recall就是召回率。五千行 768 维随机数据、ef_search 40的情况下召回通常在 0.9 以上如果明显偏低把ef_search往上调或者重建索引时提高ef_construction。要注意随机数据本身没有聚类结构真实嵌入数据的召回一般比随机数据更好所以这个测试是偏保守的。5.3 索引明明建了却不生效的四种情况这是实战里最高频的问题我按遇到频率排个序。第一种操作符和操作符类不匹配。索引建的是vector_l2_ops查询写的是规划器不会用这个索引。反过来的情况也一样。判断方法很简单看EXPLAIN输出里有没有Index Scan using ...出现Seq Scan就是没用上。第二种距离表达式被包了一层。比如ORDER BY (embedding - [...])::float8加了个类型转换表达式就变了索引匹配不上。或者写成ORDER BY 1 - (embedding [...])想转成相似度同样会破坏匹配。相似度转换放到外层做别动ORDER BY里的表达式。第三种表太小规划器认为全表扫更便宜。几千行的表走索引的随机 IO 可能比顺序扫描还慢规划器选Seq Scan是理性的。测试索引效果时用SET enable_seqscan off强制走索引但不要在生产上留这个设置。第四种索引建在错误的列或者错误的表上。多实例环境下尤其容易连到了 A 库却在 B 库建索引然后对着 A 库查。我现在的习惯是建完索引立刻在同一会话里跑一次EXPLAIN确认索引名出现在计划里再干别的。还有一个小细节LIMIT的值如果大于索引能提供的候选数规划器可能放弃索引。比如ef_search 40而LIMIT 100理论上拿不到 100 个有质量的候选某些情况下规划器会保守地选择全表扫。6. 踩坑实录一份按现象查的排查表6.1 编译阶段的典型报错nmake找不到。现象是命令行提示nmake 不是内部或外部命令。原因只有一个没有在vcvars64.bat初始化过的环境里执行。注意nmake.exe是随 VS 的 C 组件装的只装 VS 的 .NET 或者 Python 工作负载是不带的。fatal error C1083: 无法打开包括文件: postgres.h。这是PGROOT不对或者路径带空格被截断了。检查%PGROOT%\include\server\postgres.h是否存在再检查nmake命令里PGROOT有没有加引号。还有一个少见情况PostgreSQL 装在 D 盘但你set PGROOT的时候写的是 C 盘路径。LNK1104: 无法打开文件 postgres.lib。链接器找不到导入库。确认%PGROOT%\lib\postgres.lib存在。有些精简安装包不带这个文件需要重装并勾选服务端组件。LNK2001: 无法解析的外部符号 _pg_detoast_datum_packed之类的符号错误。基本是架构不匹配用 x86 的cl对着 x64 的postgres.lib链接。重新开一个 x64 开发者命令行cl版本横幅里应该写 x64。NMAKE : fatal error U1077: cl.exe : 返回代码0x2。这只是一个包装错误真正的原因在上面几行。往上翻找第一个error C开头的行。6.2 运行阶段的典型报错could not open extension control file .../vector.control: No such file or directory。install没执行或者装到了另一个 PostgreSQL 实例的目录。用pg_config --sharedir查一下服务端认识的那个目录和你实际复制的位置对一下。extension vector is not available。vector.control在但对应的vector--x.y.z.sql不在或者default_version写的版本号没有对应的脚本文件。检查share\extension下的文件名。could not load library .../vector.dll: The specified procedure could not be found。编译时的 PostgreSQL 版本和运行的服务端版本不一致。这是最坑的一类因为文件名、路径都正确只是二进制接口对不上。用SELECT version();确认服务端版本然后对着对应版本的头文件重编。ERROR: column cannot have more than 2000 dimensions for hnsw index。维度超了索引上限。要么降维要么换halfvec上限 4000 维要么放弃索引接受全表扫。这个限制是硬编码的不是配置问题。ERROR: operator class vector_l2_ops does not exist for access method hnsw。扩展没装成功或者装在了别的 schema、当前search_path找不到。先\dx确认再\dn看 schema。6.3 一张可以直接对照的速查表现象大概率原因处理动作nmake不是命令未初始化 MSVC 环境跑vcvars64.bat找不到postgres.hPGROOT错误或路径带空格检查路径加引号install报拒绝访问权限不足管理员身份运行install报文件被占用服务已加载旧 DLL停服务再装或重启服务CREATE EXTENSION找不到 controlinstall 未执行或目录不对用pg_config --sharedir核对加载 DLL 报找不到过程头文件版本与服务端不一致对齐版本重编建索引报维度超限超过 2000 维降维或改halfvec建了索引仍全表扫操作符与操作符类不匹配改查询或重建索引查询结果第一条不是自己维度或数据写入有问题检查插入的向量长度召回率偏低ef_search太小调大参数或重建索引这张表我在三台机器上迭代出来的基本上遇到问题往里一套就能定位。真正花时间的从来不是解决问题而是从报错信息定位到是哪一环出的错所以我把「现象」这一列写得尽量贴近你屏幕上看到的原文。还有一个跨阶段的坑值得单独说不要在同一个终端里混用多个 PostgreSQL 版本的pg_config。PATH 里排前面的那个决定了pg_config指向谁而psql可能连的是另一个实例。我现在的做法是在项目目录下放一个.bat开头就把PGROOT和PATH显式设死不依赖系统环境换机器只需要改这一处。7. 我自己的几点实操体会这套流程我前后走过五六遍最大的感受是Windows 上编译扩展的难点不在技术本身而在「版本对齐」这四个字。编译器版本、C 运行时版本、PostgreSQL 头文件版本、服务端版本、扩展版本五个东西必须拧成一股绳任何一个错位都会以一个完全不相关的错误信息呈现出来。所以我现在养成一个习惯动手之前先把这五个版本号抄在一张纸上编完对照一遍比事后排查省太多时间。另一个体会是不要跳过小数据验证。我见过太多人一上来就灌一百万行然后查询结果不对根本分不清是数据问题、索引问题还是安装问题。先用四行三維数据把CREATE EXTENSION、插入、排序、EXPLAIN全部走一遍二十分钟的事能把后面几小时的排查挡掉。这个习惯我建议每个刚开始用 pgvector 的人都养成向量检索的问题有一半出在「以为装好了其实没装好」上。最后说个容易被忽略的维护细节vector.dll是可以在服务运行期间被替换的但替换之后已经在跑的连接仍然用旧版本只有新建连接才会加载新的 DLL。所以如果你改源码重新编译装完记得确认一下是不是所有应用连接都重连过最简单的办法就是重启一次服务。这个细节在本地开发时无关痛痒但在多实例、连接池的环境下会表现成「有的进程正常、有的报错」这种非常难查的现象。