pgvector 在 Windows 下从克隆源码到跑通第一条相似度查询这件事看起来像十分钟就能收工真动起手来的人都知道卡点几乎从不在 SQL 那一侧而是在 nmake 第一行输出里。官方的预编译二进制包里没有 Windows 版本Docker 镜像虽然省事但很多内网机器、交付现场根本不让装容器运行时而你手上偏偏有一个已经跑着业务数据的 PostgreSQL 实例想给它加一个向量列。这时候唯一的活路就是拿 MSVC 编译源码产出一个 vector.dll 塞进现有安装目录。这篇内容就是把我自己这台 Windows 机器上从零到第一条ORDER BY embedding - [...]返回结果的完整过程拆开写包括环境怎么对齐、Makefile.win 到底做了什么、install 为什么必须管理员权限、以及那些报错日志里一句话都看不出来的坑。适合两类人看一类是完全没编过 PostgreSQL 扩展、但需要在 Windows 上把向量检索跑起来的开发者另一类是已经装上了但查询结果不对劲、想知道索引和距离操作符怎么选的人。基础概念我会顺手带一句不会假设你懂 C 构建链。1. 先想清楚为什么要自己编三条路的取舍1.1 摆在面前的三条路各自的代价在 Windows 上给 PostgreSQL 装 pgvector实际上只有三条路能走每条路的代价完全不同选之前得先看清自己受什么约束。第一条是找现成的二进制包。这是最理想的但 pgvector 官方并不发布 Windows 预编译产物社区里偶尔有人打包版本、编译选项、对应的 PostgreSQL 主版本全对不上装上去能不能加载全靠运气。我试过一次别人打的包CREATE EXTENSION成功了但一建 HNSW 索引就崩最后发现是对面用的编译器和官方安装包的运行库不匹配。这条路只在“验证概念、不接生产”的场景下可以考虑。第二条是容器化。拉一个带 pgvector 的镜像起来端口映射出去五分钟就能写查询。问题是它给了你一个全新的数据库实例而你原本那套连接串、备份策略、权限体系、已经灌进去的数据全在宿主机上的老实例里。迁移的隐性成本远比编译一个 dll 高而且不少交付环境连容器的安装权限都收走了。第三条就是源码编译。它的好处是“就地升级”——扩展装进你现有的那个 PostgreSQL 目录服务不用换数据不用迁连接串一个字都不用改。坏处是需要一套完整的 C 构建链而且要处理 Windows 上特有的路径、权限、环境变量问题。我最终选第三条理由很朴素我要的是给一个已有的库加能力不是再建一个新库。这个判断决定了后面所有操作的方向。1.2 为什么是 MSVC 而不是 MinGW确定了要编译下一个问题是拿什么编。Windows 上能编 C 扩展的工具链主要有两套微软的 MSVCcl.exe link.exe nmake和 MSYS2 提供的 MinGW-w64gcc make。很多人下意识会选后者因为 pgvector 在 Linux 上的构建体验就是make make install看起来很眼熟。但这里有个隐性的坑PostgreSQL 官方 Windows 安装包是用 MSVC 编译的它依赖的是微软的运行库体系。你用 MinGW 编出来的 dll在导出符号、结构体对齐、运行库初始化上跟宿主进程是两套东西加载时不一定立刻报错可能在某个特定函数调用时才炸排查成本极高。pgvector 源码里同时提供了Makefile和Makefile.win两个构建脚本后者就是专门给 nmake 用的。官方在文档里提 Windows 构建时给的命令也是 nmake 那一套。顺着官方铺好的路走出问题的概率最低。所以我直接把 MinGW 那条路排除了哪怕它对熟悉 Unix 的人更顺手。1.3 动手前的环境清单与版本对齐环境清单这块我建议先列一张表把每个组件的版本和用途钉死再开始装。因为这套东西最容易出问题的地方就是版本错位——编译时找的头文件是 16 的服务跑的是 15 的或者 pg_config 指向了一个早就卸载的旧目录。组件建议版本作用容易踩的点PostgreSQL13 及以上本文以 16 为例宿主数据库提供头文件、库目录、pg_config必须装完整版不能只装客户端Visual Studio Build Tools2019 或 2022提供 cl.exe、link.exe、nmake.exe必须勾选 C 桌面开发工作负载Git for Windows任意较新版本克隆源码注意换行符配置命令行cmd管理员执行构建和安装PowerShell 下调用 vcvars 脚本要绕一层版本对齐有一条硬性检查编译时pg_config --version输出的版本号必须和服务端SELECT version();的结果主版本一致。听起来是废话但实际环境里同时存在两个 PostgreSQL 安装的情况非常普遍——比如以前装过一个 12 用来做实验没卸干净PATH 里排在前面nmake 就会按 12 的头文件编译然后 install 到 12 的目录去而你的服务跑在 16 上。表现就是CREATE EXTENSION报找不到控制文件你检查了半天 16 的目录什么都没发现。还有一个容易被忽略的点Windows 安装包里必须包含 server 端的头文件。判断方法很简单打开安装根目录看有没有include\server\postgres.h这个文件。有说明具备编译扩展的条件没有说明你装的是精简版得重装。这个检查花十秒钟能省掉后面半小时的困惑。2. 环境准备把编译器和服务端接上2.1 装 PostgreSQL 时的两个决定安装 PostgreSQL 本身没什么难度但有两个决定会影响后面一整条链路值得单独说一下。第一个是安装路径。默认路径是C:\Program Files\PostgreSQL\16里面带空格。这个空格在 cmake 之外的世界里是个持续的麻烦源尤其在 cmd 批处理里任何一个忘记加引号的地方都会变成“系统找不到指定的路径”。我自己的做法是装到C:\pg\16这种短且无空格的路径下。代价是安装时多改一个输入框收益是后面所有脚本、环境变量、命令行参数都不用处理引号和转义。如果你已经装在了默认路径也不用重装只是记得凡是拼路径的地方都加双引号包括set PGROOTC:\Program Files\PostgreSQL\16这种写法——注意引号是把整个赋值包起来不是只包值。第二个是组件的勾选。官方安装包里有 PostgreSQL Server、pgAdmin、Stack Builder、Command Line Tools 这几项。对我们来说 Server 和 Command Line Tools 是必需的后者提供了 psql 和 pg_config。pgAdmin 装不装无所谓Stack Builder 在这个流程里用不上可以取消省点安装时间。安装过程中会让你设超级用户密码和端口。端口默认 5432如果你机器上已经有别的服务占了改成 5433 也行但后面所有 psql 命令都要带上-p 5433别忘了。装完之后先做一次验证打开一个新的 cmd 窗口pg_config --version pg_config --includedir-server pg_config --libdir第一条应该输出类似PostgreSQL 16.x第二条指向...\include\server第三条指向...\lib。这三行输出就是你后面构建的全部坐标把它们记下来出问题时第一件事就是回来重新确认这三行。注意如果你在 cmd 里敲pg_config提示“不是内部或外部命令”说明安装目录下的 bin 没进 PATH。别急着重装手动加一下系统环境变量就行。加完之后必须关掉所有已经打开的 cmd 窗口重开因为 PATH 是在进程启动时读取的老窗口读不到新值。2.2 构建工具只装需要的那部分Visual Studio 的安装器现在做得很“大方”默认勾一堆东西装完十几个 G。我们其实只需要一小块C 的编译器、链接器和 nmake。打开安装器选择“使用 C 的桌面开发”这个工作负载右侧的安装详细信息里会默认勾上一堆可选项包括 Windows SDK、CMake、测试工具等等。C 核心的 MSVC 编译器组件和 Windows SDK 是必须留的其余的可以取消。如果只是编译一个扩展装 Build Tools 版本就够了不需要完整的 IDE——Build Tools 是独立安装包体积小很多。装完之后关键文件在这样一个位置C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat如果你是完整版 IDE把中间的BuildTools换成Community或Professional。不确定装在哪用官方提供的定位工具查一下C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe -latest -property installationPath它会吐出安装根目录拼上\VC\Auxiliary\Build\vcvars64.bat就是你要的路径。这个脚本的作用是往当前命令行进程里注入一堆环境变量让cl、link、nmake这些命令能被找到同时把 Windows SDK 的路径也配好。它只对当前这个 cmd 窗口生效关掉就没了——这一点决定了后面的操作顺序。2.3 环境变量的加载顺序顺序这件事我踩过一次坑之后才真正当回事。正确的流程是这样的先开一个普通 cmd然后call C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat执行完会看到一段输出最后一行类似[vcvarsall.bat] Environment initialized for: x64。这时候窗口里就有了编译器环境。接着再设 PGROOTset PGROOTC:\pg\16然后 cd 到源码目录执行 nmake。这个顺序是对的因为 vcvars 脚本内部会重写 PATH如果你先设了 PGROOT 但没设进 PATHPGROOT 只是个普通变量不是 PATH 的一部分其实也不受影响。真正会出问题的是另一种情况在 PowerShell 里直接跑。PowerShell 执行 bat 文件不能直接.\vcvars64.bat因为 bat 是 cmd 的脚本PowerShell 会把它当外部命令开一个新进程跑跑完进程退出环境变量全部丢失你的 PowerShell 窗口里依然没有 cl。要么用cmd /c vcvars64.bat nmake /F Makefile.win这种方式把两步塞进同一个 cmd 进程要么干脆老老实实开 cmd。我后来一律用 cmd因为这个流程里最怕的就是“看起来成功了但环境没生效”。还有一个细节如果你所在的目录路径很长或者带中文nmake 有时候会报奇怪的错。构建目录尽量放在盘的浅层比如C:\build\pgvector。3. 编译把源码变成 vector.dll3.1 克隆时选标签而不是主干克隆这一步只需要一条命令但选哪个分支值得说一句cd C:\build git clone --branch v0.7.4 --depth 1 https://github.com/pgvector/pgvector.git--depth 1是浅克隆只拉这一个提交速度快很多因为我们不需要历史记录。--branch v0.7.4指定标签这是关键。为什么不直接用默认的主干因为扩展的版本号是硬编码在几个地方的vector.control文件里的default_version、vector--x.y.z.sql这个脚本的文件名、以及编译进 dll 的PG_MODULE_MAGIC相关定义。主干分支上这些值可能是开发态版本和你照着文档写的 SQL 对不上甚至可能出现脚本文件名和 control 里声明的版本不一致导致CREATE EXTENSION时找不到对应的 SQL 文件。用发布标签这三处一定是一致的。至于选哪个标签取决于你要的功能。0.7.0 之后引入了halfvec、sparsevec、bit三种新类型以及 L1 距离操作符如果你只是做常规的文本向量检索0.5.x 以上就够用。这块按需选择但不要用主干这个原则是不变的。克隆完成后进目录看一眼你应该能看到这些文件Makefile Makefile.win vector.control sql\vector.sql sql\upgrade.sql src\vector.c src\hnsw.c src\ivfflat.c ...Makefile.win的存在是 Windows 能编的前提如果这个文件不在说明你拉的分支太老。3.2 Makefile.win 里到底写了什么花两分钟看一下这个文件能省掉后面很多“为什么报这个错”的困惑。它的结构和 Unix 的 Makefile 不一样不是基于 pgxs 那套机制而是自己手写了编译和链接规则。核心逻辑大概是这样几块先确定PGROOT如果这个变量没设置就退化成直接用 PATH 里的pg_config然后通过pg_config --includedir-server和--libdir拿到头文件和库目录接着列出所有要编译的 .c 文件对应的 .obj最后用cl编译、用link /DLL链接成vector.dll。这里面几个关键点值得留意。第一它同时需要 PostgreSQL 的服务端头文件postgres.h、fmgr.h这些和客户端库目录前者用于编译后者用于链接。第二链接方式是/DLL产出的就是一个动态链接库PostgreSQL 在CREATE EXTENSION时会把这个 dll 加载进服务进程。第三扩展的入口符号通过PG_MODULE_MAGIC宏声明这是 PostgreSQL 校验扩展和宿主版本兼容性的机制——如果编译时的头文件版本和服务端版本差太多加载时就会报incompatible library之类的错。PGROOT这个变量的作用就是告诉 Makefile.win 去哪里找 pg_config。如果你设了它脚本会用$(PGROOT)\bin\pg_config如果没设就用 PATH 里的。这两种情况在机器上装了多个 PostgreSQL 时会给出完全不同的结果所以我的建议是永远显式设置 PGROOT别依赖 PATH把不确定性降到最低。3.3 执行构建与安装的权限坑真正的构建就两行命令在已经 call 过 vcvars64.bat 的 cmd 里nmake /F Makefile.win nmake /F Makefile.win install第一条命令会编译所有源文件并链接。正常情况下输出会刷一屏每个 .c 文件一行cl /c ...最后一行是link /DLL ...结束时在仓库根目录出现一个vector.dll。中间如果出现warning C4996之类的警告通常可以忽略那是微软对某些 C 标准库函数的弃用提醒。第二条命令是安装它做的事情是把三个东西复制到 PostgreSQL 目录vector.dll→$(libdir)也就是C:\pg\16\libvector.control→$(datadir)\extension也就是C:\pg\16\share\extensionvector--*.sql一系列脚本 → 同一个 extension 目录这里就是权限坑的所在。如果你把 PostgreSQL 装在Program Files下那个目录的写权限默认只给 Administrators 组普通用户跑 install 会报拒绝访问。表现出来的错误大概是这样copy vector.dll C:\Program Files\PostgreSQL\16\lib 拒绝访问。 0 个文件已复制。 NMAKE : fatal error U1077: copy : 返回代码 0x1 停止。新手的第一个反应往往是“命令写错了”然后开始翻 Makefile。其实关键在于看错误的前一行——是“拒绝访问”不是“找不到路径”。解决办法很简单用管理员身份重新打开 cmd把 vcvars、PGROOT、cd 这几步重来一遍再执行 install。注意install 失败的时候编译产物vector.dll是已经在的但可能只有它被复制成功control 和 sql 文件没复制过去。这种半吊子状态最坑CREATE EXTENSION会报could not open extension control file。发现这个错别怀疑源码先去看 extension 目录里到底有几个 vector 开头的文件。安装完成后做个核对这一步别省dir C:\pg\16\lib\vector.dll dir C:\pg\16\share\extension\vector*第一条应该看到一个非零大小的 dll第二条应该看到vector.control加若干个vector--x.y.z.sql。三个东西都在扩展的物理安装才算完成。4. 装载扩展并跑通第一条相似度查询4.1 CREATE EXTENSION 与验证文件到位之后用 psql 连上目标库执行CREATE EXTENSION vector;如果这一步成功说明 dll 能被正常加载头文件版本和服务端也匹配。紧接着做两件事验证SELECT extversion FROM pg_extension WHERE extname vector; SELECT default_version, installed_version FROM pg_available_extensions WHERE name vector;第一条查的是当前库里已装的版本第二条查的是磁盘上有哪些版本可用。两个结果应该一致。如果第一条没返回行说明扩展没建在当前库如果第二条installed_version是空的但default_version有值说明文件在但没装到这个库。一个常见的误会是“装完扩展要重启 PostgreSQL 服务”。其实不需要。PostgreSQL 的扩展是运行时按需加载 dll 的CREATE EXTENSION那一刻才去lib目录找文件。只有一种情况需要重启你替换了一个已经加载过的 dll比如先装了 0.5 版又覆盖成 0.7 版这时候老版本的 dll 还在服务进程内存里得重启才能换掉。4.2 建表、灌数据、看清类型先建一张最小的表把流程跑通三条数据的规模足够验证CREATE TABLE items ( id bigserial PRIMARY KEY, embedding vector(3) ); INSERT INTO items (embedding) VALUES ([1,2,3]), ([4,5,6]), ([7,8,9]);这里有两个点值得展开。第一vector(3)里的 3 是维度约束声明之后这一列只接受三维向量插入四维会直接报错。如果你不确定维度可以写成不带宽度的vector它接受任意维度但建索引时就必须统一维度混着维度存的数据在建索引阶段会失败。实际项目里我强烈建议带上维度它是一道免费的防线——模型换版本导致维度变了插入时立刻报错比事后查出一堆脏数据强。第二输入格式是字符串字面量[1,2,3]这是 PostgreSQL 的数组语法。它跟 JSON 数组长得像但两者不一样别混。如果你从应用层传参一般是在驱动里把浮点数组拼成这个字符串形式或者用::vector做类型转换。维度上限也顺便说一下省得你后面撞墙vector类型本身最多支持 16000 维但建索引的时候只能到 2000 维。这个限制不是 pgvector 偷懒是 ANN 索引本身的内存和计算开销决定的。如果模型输出是 3072 维现在不少嵌入模型都是这个数你就得考虑降维或者改用halfvec——它用半精度浮点存索引支持到 4000 维。4.3 第一条相似度查询与距离操作符的选择数据进去了第一条查询长这样SELECT id, embedding FROM items ORDER BY embedding - [3,1,2] LIMIT 5;-是欧氏距离L2操作符ORDER BY ... LIMIT n就是 pgvector 里最经典的近邻检索写法。返回结果按距离升序排列第一行就是离查询向量最近的那条。默认排序方向是升序因为距离越小代表越像这个语义和常见的“按相似度降序”正好相反写业务代码时别搞反。pgvector 提供的操作符不止一个选错会直接影响检索质量操作符含义数值趋势适用场景-欧氏距离L2越小越近图像特征、坐标类向量#负内积越小越近已归一化的向量等价于余弦余弦距离越小越近文本嵌入未归一化也能用曼哈顿距离L1越小越近对异常值不敏感的场合~汉明距离越小越近二进制向量%Jaccard 距离越小越近二进制集合相似度这里有个容易被绕晕的地方#返回的是负内积。内积本身越大越相似取负之后越小越相似这样所有操作符的排序方向就统一了。如果你直接把#的结果当相似度展示给用户会得到一个负数看起来很怪。要转成 0 到 1 的相似度用1 - (embedding query)或者对内积结果取反。我选哪个取决于向量是怎么来的。文本嵌入模型如果输出已经归一化模长为 1L2 距离和余弦距离在排序上是等价的用哪个都行如果没有归一化余弦距离更稳因为它只关心方向不关心长度。这个判断不涉及任何玄学纯粹是数学性质。4.4 加索引参数怎么算才算合理三条数据的时候上面那条查询走的是全表扫描快得很。数据量上来了就必须建 ANN 索引pgvector 支持两种-- HNSW推荐查询快、召回高 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops); -- IVFFlat建索引快、内存占用低 CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists 100);索引的操作符类必须和查询用的操作符对应用-查询就建vector_l2_ops用就建vector_cosine_ops用#就建vector_ip_ops。建错了索引不是报错而是查询根本不走它EXPLAIN里看到的还是 Seq Scan白白占着空间。IVFFlat 的lists参数有个经验公式很多人抄了但不知道为什么行数在 100 万以内lists rows / 1000行数超过 100 万lists sqrt(rows)比如 50 万行数据lists 5001000 万行数据lists ≈ 3162。这个公式的背后逻辑是lists决定了把向量空间切成多少个簇每个簇的向量数应该和一次查询要扫的候选数量在同一量级。切太少每个簇太大扫描慢切太多簇太小聚类本身的质量下降召回率掉得厉害。查询时的probes参数控制扫几个簇默认是 1太小了。经验值是probes sqrt(lists)。500 个簇的话probes设 22 左右。可以在会话级别调SET ivfflat.probes 22;HNSW 那边对应的参数是ef_search默认 40可以往上调SET hnsw.ef_search 100;调大提高召回率、降低速度调小反过来。这个值没有绝对标准得拿你的数据集实测——准备一批查询用暴力搜索的结果当基准算召回率然后找那个召回率和耗时的平衡点。验证索引有没有生效用这个套路SET enable_seqscan off; EXPLAIN ANALYZE SELECT * FROM items ORDER BY embedding - [3,1,2] LIMIT 5;enable_seqscan off是强制优化器优先考虑索引它不是一个开关而是给顺序扫描加了一个巨大的代价惩罚。如果这样还是不出现Index Scan using ...那就是索引真的用不上常见原因是维度不匹配或者操作符类选错了。提示建 HNSW 索引是个内存大户尤其是数据量大的时候。如果maintenance_work_mem太小它会退化成磁盘排序建索引的时间能从几分钟变成几小时。建之前临时调大一点建完再调回来。5. 常见问题与排查技巧实录5.1 编译期报错速查编译这一步的错误信息大多很直白关键是知道去看哪一行。报错关键字真实原因处理方式nmake 不是内部或外部命令没 call vcvars64.bat或 call 了但换了窗口重开 cmd重新 call 脚本确认输出里有 x64Cannot open include file: postgres.hPGROOT 没设或指错或安装包不含 server 头文件检查include\server\postgres.h是否存在无法打开输入文件 vector.obj编译阶段失败但没注意直接跑了 install往上翻输出找第一个 errorLNK2019 无法解析的外部符号库目录不对链接不到 PostgreSQL 的导入库确认pg_config --libdir指向的目录有 libpostgres.lib拒绝访问/U1077没有管理员权限写不进安装目录管理员身份重开 cmd重跑 installNMAKE : fatal error U1086Makefile.win 的路径变量里有未转义的空格换安装路径或给所有路径加引号这里面最值得说的是第一个和第二个。nmake 不是内部命令这个错误新手容易误解成“nmake 没装”然后跑去装别的东西。实际上 Visual Studio 装完一定有 nmake只是它在一个很深的目录里要靠 vcvars 脚本注入 PATH 才能被找到。看到这个错先别装任何东西先检查你的窗口是不是 call 过那行脚本的同一个窗口。postgres.h找不到也是同理。这个文件不是 PostgreSQL 客户端库的一部分而是服务端头文件只有完整安装才带。有些人装了 psql 客户端就觉得环境齐了其实差得远。还有一个隐蔽的坑编译输出的 warning 里如果有C4819文件包含无法在当前代码页中表示的字符通常不影响结果但如果后面出现莫名其妙的链接错误可以试着把 cmd 的代码页切成 65001 再重来一遍。5.2 运行期报错速查装完之后的问题更分散因为错误信息往往只说“错了”不说“错在哪”。第一种could not open extension control file。这句话的字面意思是找不到vector.control。原因基本只有一个install 的时候文件没复制到当前服务实例的 extension 目录。可能是你机器上有两个 PostgreSQLnmake 装到了另一个也可能是 install 权限不够只复制了一半。排查方法是去pg_config --sharedir输出的目录下看有没有extension\vector.control。如果pg_config指向的目录和你服务的安装目录不是一个那就是版本错位得把 PGROOT 改成服务的那个路径重新编译安装。第二种ERROR: type vector does not exist。这说明扩展没装在你当前连的这个库上。PostgreSQL 的扩展是库级别的A 库装了不代表 B 库能用。用\dx看当前库装了哪些扩展或者CREATE EXTENSION vector;再执行一次。还有一种情况是你连的库装了但search_path被改过导致找不到类型用\dx确认后显式写public.vector试一下。第三种could not load library ...\vector.dll。这个最麻烦因为它可能有好几种不同的后缀。如果是The specified module could not be found通常是 dll 依赖的 VC 运行库没装齐装一个对应的运行库合集能解决。如果是incompatible library或者提到magic block那就是编译时的 PostgreSQL 主版本和服务端不一致必须重新对齐版本编译。如果是The specified procedure could not be found多半是你覆盖了一个旧版本 dll 但服务还在用内存里的旧版本重启服务。第四种ERROR: expected 3 dimensions, not 4。这是维度约束在起作用是好事。改数据的维度或者把列声明成不带长度的vector。但改之前想清楚混维度存储会让索引建不出来。第五种索引明明建了但查询不走。检查三件事操作符类对不对-配vector_l2_ops、EXPLAIN里有没有被enable_seqscan影响、以及矩阵是否真的够大。最后这条最容易被忽略——几十行的表优化器算下来全表扫描比走索引还快它当然不走索引。这不是 bug这是优化器在正常工作。5.3 我在这个流程里印象最深的几个坑第一个坑是路径里的空格。我第一次编译的时候把 PostgreSQL 装在默认的Program Files下面然后set PGROOTC:\Program Files\PostgreSQL\16这样写结果 Makefile 里所有拼出来的路径都被空格切断了报了一堆“找不到文件”但错误信息指向的是一个看起来完全不存在的路径。正确写法是把整个赋值用双引号包起来set PGROOTC:\Program Files\PostgreSQL\16。这个写法看着别扭但它是 cmd 里处理带空格路径的标准姿势。后来我干脆换了个无空格的安装目录一劳永逸。第二个坑是换版本时的 dll 缓存。有次我先把 0.5 版装好觉得功能不够又编了 0.7 版覆盖上去然后CREATE EXTENSION一直报函数不存在。折腾了半小时才发现服务进程里加载的还是老 dllCREATE EXTENSION走的还是老的 SQL 脚本。覆盖 dll 之后一定要重启一次服务这条我写在了自己的备忘里。判断方法也简单SELECT extversion FROM pg_extension如果显示的还是旧版本号那就是没换成功。第三个坑是把“能查到结果”当成“装好了”。前面跑通的那条ORDER BY - LIMIT 5在三条数据的表上走的是全表扫描它根本没用索引。真正要验证索引生效必须造一批有规模的数据再配合EXPLAIN ANALYZE看执行计划。我现在的习惯是装完扩展先建一张 10 万行的测试表建索引然后用SET enable_seqscan off加EXPLAIN确认走的是Index Scan这一步过了才算真的通了。这个检查多花十分钟能避免后面在业务数据量上来之后才发现索引压根没用上的尴尬。第四个坑说出来有点丢人有回我调hnsw.ef_search调完发现查询速度没变化一度以为参数没生效。后来才反应过来那条查询总共就几十行数据走的是顺序扫描ef_search只对 HNSW 索引扫描有意义。参数调优的前提是查询真的在用那个索引否则调什么都是在跟空气较劲。最后分享一个我自己常用的验证脚本装完任何一台机器都跑一遍五秒钟就能判断这套环境是不是真的可用SELECT extversion FROM pg_extension WHERE extname vector; DROP TABLE IF EXISTS _smoke_test; CREATE TABLE _smoke_test (id bigserial PRIMARY KEY, e vector(4)); INSERT INTO _smoke_test (e) VALUES ([1,0,0,0]), ([0,1,0,0]), ([0,0,1,0]); SELECT id, e - [1,0,0,0] AS dist FROM _smoke_test ORDER BY e - [1,0,0,0] LIMIT 3; DROP TABLE _smoke_test;预期结果是三条记录距离分别是 0、1.414、1.414第一行就是自己跟自己比。这个结果对上了说明类型、操作符、扩展加载三个环节全部正常剩下的才轮到索引和性能的调优。 
长河君 · 2026/11/2 8:34:51 · 阅读 1.2k Windows下用MSVC源码编译pgvector并跑通相似度查询
pgvector 在 Windows 下从克隆源码到跑通第一条相似度查询这件事看起来像十分钟就能收工真动起手来的人都知道卡点几乎从不在 SQL 那一侧而是在 nmake 第一行输出里。官方的预编译二进制包里没有 Windows 版本Docker 镜像虽然省事但很多内网机器、交付现场根本不让装容器运行时而你手上偏偏有一个已经跑着业务数据的 PostgreSQL 实例想给它加一个向量列。这时候唯一的活路就是拿 MSVC 编译源码产出一个 vector.dll 塞进现有安装目录。这篇内容就是把我自己这台 Windows 机器上从零到第一条ORDER BY embedding - [...]返回结果的完整过程拆开写包括环境怎么对齐、Makefile.win 到底做了什么、install 为什么必须管理员权限、以及那些报错日志里一句话都看不出来的坑。适合两类人看一类是完全没编过 PostgreSQL 扩展、但需要在 Windows 上把向量检索跑起来的开发者另一类是已经装上了但查询结果不对劲、想知道索引和距离操作符怎么选的人。基础概念我会顺手带一句不会假设你懂 C 构建链。1. 先想清楚为什么要自己编三条路的取舍1.1 摆在面前的三条路各自的代价在 Windows 上给 PostgreSQL 装 pgvector实际上只有三条路能走每条路的代价完全不同选之前得先看清自己受什么约束。第一条是找现成的二进制包。这是最理想的但 pgvector 官方并不发布 Windows 预编译产物社区里偶尔有人打包版本、编译选项、对应的 PostgreSQL 主版本全对不上装上去能不能加载全靠运气。我试过一次别人打的包CREATE EXTENSION成功了但一建 HNSW 索引就崩最后发现是对面用的编译器和官方安装包的运行库不匹配。这条路只在“验证概念、不接生产”的场景下可以考虑。第二条是容器化。拉一个带 pgvector 的镜像起来端口映射出去五分钟就能写查询。问题是它给了你一个全新的数据库实例而你原本那套连接串、备份策略、权限体系、已经灌进去的数据全在宿主机上的老实例里。迁移的隐性成本远比编译一个 dll 高而且不少交付环境连容器的安装权限都收走了。第三条就是源码编译。它的好处是“就地升级”——扩展装进你现有的那个 PostgreSQL 目录服务不用换数据不用迁连接串一个字都不用改。坏处是需要一套完整的 C 构建链而且要处理 Windows 上特有的路径、权限、环境变量问题。我最终选第三条理由很朴素我要的是给一个已有的库加能力不是再建一个新库。这个判断决定了后面所有操作的方向。1.2 为什么是 MSVC 而不是 MinGW确定了要编译下一个问题是拿什么编。Windows 上能编 C 扩展的工具链主要有两套微软的 MSVCcl.exe link.exe nmake和 MSYS2 提供的 MinGW-w64gcc make。很多人下意识会选后者因为 pgvector 在 Linux 上的构建体验就是make make install看起来很眼熟。但这里有个隐性的坑PostgreSQL 官方 Windows 安装包是用 MSVC 编译的它依赖的是微软的运行库体系。你用 MinGW 编出来的 dll在导出符号、结构体对齐、运行库初始化上跟宿主进程是两套东西加载时不一定立刻报错可能在某个特定函数调用时才炸排查成本极高。pgvector 源码里同时提供了Makefile和Makefile.win两个构建脚本后者就是专门给 nmake 用的。官方在文档里提 Windows 构建时给的命令也是 nmake 那一套。顺着官方铺好的路走出问题的概率最低。所以我直接把 MinGW 那条路排除了哪怕它对熟悉 Unix 的人更顺手。1.3 动手前的环境清单与版本对齐环境清单这块我建议先列一张表把每个组件的版本和用途钉死再开始装。因为这套东西最容易出问题的地方就是版本错位——编译时找的头文件是 16 的服务跑的是 15 的或者 pg_config 指向了一个早就卸载的旧目录。组件建议版本作用容易踩的点PostgreSQL13 及以上本文以 16 为例宿主数据库提供头文件、库目录、pg_config必须装完整版不能只装客户端Visual Studio Build Tools2019 或 2022提供 cl.exe、link.exe、nmake.exe必须勾选 C 桌面开发工作负载Git for Windows任意较新版本克隆源码注意换行符配置命令行cmd管理员执行构建和安装PowerShell 下调用 vcvars 脚本要绕一层版本对齐有一条硬性检查编译时pg_config --version输出的版本号必须和服务端SELECT version();的结果主版本一致。听起来是废话但实际环境里同时存在两个 PostgreSQL 安装的情况非常普遍——比如以前装过一个 12 用来做实验没卸干净PATH 里排在前面nmake 就会按 12 的头文件编译然后 install 到 12 的目录去而你的服务跑在 16 上。表现就是CREATE EXTENSION报找不到控制文件你检查了半天 16 的目录什么都没发现。还有一个容易被忽略的点Windows 安装包里必须包含 server 端的头文件。判断方法很简单打开安装根目录看有没有include\server\postgres.h这个文件。有说明具备编译扩展的条件没有说明你装的是精简版得重装。这个检查花十秒钟能省掉后面半小时的困惑。2. 环境准备把编译器和服务端接上2.1 装 PostgreSQL 时的两个决定安装 PostgreSQL 本身没什么难度但有两个决定会影响后面一整条链路值得单独说一下。第一个是安装路径。默认路径是C:\Program Files\PostgreSQL\16里面带空格。这个空格在 cmake 之外的世界里是个持续的麻烦源尤其在 cmd 批处理里任何一个忘记加引号的地方都会变成“系统找不到指定的路径”。我自己的做法是装到C:\pg\16这种短且无空格的路径下。代价是安装时多改一个输入框收益是后面所有脚本、环境变量、命令行参数都不用处理引号和转义。如果你已经装在了默认路径也不用重装只是记得凡是拼路径的地方都加双引号包括set PGROOTC:\Program Files\PostgreSQL\16这种写法——注意引号是把整个赋值包起来不是只包值。第二个是组件的勾选。官方安装包里有 PostgreSQL Server、pgAdmin、Stack Builder、Command Line Tools 这几项。对我们来说 Server 和 Command Line Tools 是必需的后者提供了 psql 和 pg_config。pgAdmin 装不装无所谓Stack Builder 在这个流程里用不上可以取消省点安装时间。安装过程中会让你设超级用户密码和端口。端口默认 5432如果你机器上已经有别的服务占了改成 5433 也行但后面所有 psql 命令都要带上-p 5433别忘了。装完之后先做一次验证打开一个新的 cmd 窗口pg_config --version pg_config --includedir-server pg_config --libdir第一条应该输出类似PostgreSQL 16.x第二条指向...\include\server第三条指向...\lib。这三行输出就是你后面构建的全部坐标把它们记下来出问题时第一件事就是回来重新确认这三行。注意如果你在 cmd 里敲pg_config提示“不是内部或外部命令”说明安装目录下的 bin 没进 PATH。别急着重装手动加一下系统环境变量就行。加完之后必须关掉所有已经打开的 cmd 窗口重开因为 PATH 是在进程启动时读取的老窗口读不到新值。2.2 构建工具只装需要的那部分Visual Studio 的安装器现在做得很“大方”默认勾一堆东西装完十几个 G。我们其实只需要一小块C 的编译器、链接器和 nmake。打开安装器选择“使用 C 的桌面开发”这个工作负载右侧的安装详细信息里会默认勾上一堆可选项包括 Windows SDK、CMake、测试工具等等。C 核心的 MSVC 编译器组件和 Windows SDK 是必须留的其余的可以取消。如果只是编译一个扩展装 Build Tools 版本就够了不需要完整的 IDE——Build Tools 是独立安装包体积小很多。装完之后关键文件在这样一个位置C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat如果你是完整版 IDE把中间的BuildTools换成Community或Professional。不确定装在哪用官方提供的定位工具查一下C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe -latest -property installationPath它会吐出安装根目录拼上\VC\Auxiliary\Build\vcvars64.bat就是你要的路径。这个脚本的作用是往当前命令行进程里注入一堆环境变量让cl、link、nmake这些命令能被找到同时把 Windows SDK 的路径也配好。它只对当前这个 cmd 窗口生效关掉就没了——这一点决定了后面的操作顺序。2.3 环境变量的加载顺序顺序这件事我踩过一次坑之后才真正当回事。正确的流程是这样的先开一个普通 cmd然后call C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat执行完会看到一段输出最后一行类似[vcvarsall.bat] Environment initialized for: x64。这时候窗口里就有了编译器环境。接着再设 PGROOTset PGROOTC:\pg\16然后 cd 到源码目录执行 nmake。这个顺序是对的因为 vcvars 脚本内部会重写 PATH如果你先设了 PGROOT 但没设进 PATHPGROOT 只是个普通变量不是 PATH 的一部分其实也不受影响。真正会出问题的是另一种情况在 PowerShell 里直接跑。PowerShell 执行 bat 文件不能直接.\vcvars64.bat因为 bat 是 cmd 的脚本PowerShell 会把它当外部命令开一个新进程跑跑完进程退出环境变量全部丢失你的 PowerShell 窗口里依然没有 cl。要么用cmd /c vcvars64.bat nmake /F Makefile.win这种方式把两步塞进同一个 cmd 进程要么干脆老老实实开 cmd。我后来一律用 cmd因为这个流程里最怕的就是“看起来成功了但环境没生效”。还有一个细节如果你所在的目录路径很长或者带中文nmake 有时候会报奇怪的错。构建目录尽量放在盘的浅层比如C:\build\pgvector。3. 编译把源码变成 vector.dll3.1 克隆时选标签而不是主干克隆这一步只需要一条命令但选哪个分支值得说一句cd C:\build git clone --branch v0.7.4 --depth 1 https://github.com/pgvector/pgvector.git--depth 1是浅克隆只拉这一个提交速度快很多因为我们不需要历史记录。--branch v0.7.4指定标签这是关键。为什么不直接用默认的主干因为扩展的版本号是硬编码在几个地方的vector.control文件里的default_version、vector--x.y.z.sql这个脚本的文件名、以及编译进 dll 的PG_MODULE_MAGIC相关定义。主干分支上这些值可能是开发态版本和你照着文档写的 SQL 对不上甚至可能出现脚本文件名和 control 里声明的版本不一致导致CREATE EXTENSION时找不到对应的 SQL 文件。用发布标签这三处一定是一致的。至于选哪个标签取决于你要的功能。0.7.0 之后引入了halfvec、sparsevec、bit三种新类型以及 L1 距离操作符如果你只是做常规的文本向量检索0.5.x 以上就够用。这块按需选择但不要用主干这个原则是不变的。克隆完成后进目录看一眼你应该能看到这些文件Makefile Makefile.win vector.control sql\vector.sql sql\upgrade.sql src\vector.c src\hnsw.c src\ivfflat.c ...Makefile.win的存在是 Windows 能编的前提如果这个文件不在说明你拉的分支太老。3.2 Makefile.win 里到底写了什么花两分钟看一下这个文件能省掉后面很多“为什么报这个错”的困惑。它的结构和 Unix 的 Makefile 不一样不是基于 pgxs 那套机制而是自己手写了编译和链接规则。核心逻辑大概是这样几块先确定PGROOT如果这个变量没设置就退化成直接用 PATH 里的pg_config然后通过pg_config --includedir-server和--libdir拿到头文件和库目录接着列出所有要编译的 .c 文件对应的 .obj最后用cl编译、用link /DLL链接成vector.dll。这里面几个关键点值得留意。第一它同时需要 PostgreSQL 的服务端头文件postgres.h、fmgr.h这些和客户端库目录前者用于编译后者用于链接。第二链接方式是/DLL产出的就是一个动态链接库PostgreSQL 在CREATE EXTENSION时会把这个 dll 加载进服务进程。第三扩展的入口符号通过PG_MODULE_MAGIC宏声明这是 PostgreSQL 校验扩展和宿主版本兼容性的机制——如果编译时的头文件版本和服务端版本差太多加载时就会报incompatible library之类的错。PGROOT这个变量的作用就是告诉 Makefile.win 去哪里找 pg_config。如果你设了它脚本会用$(PGROOT)\bin\pg_config如果没设就用 PATH 里的。这两种情况在机器上装了多个 PostgreSQL 时会给出完全不同的结果所以我的建议是永远显式设置 PGROOT别依赖 PATH把不确定性降到最低。3.3 执行构建与安装的权限坑真正的构建就两行命令在已经 call 过 vcvars64.bat 的 cmd 里nmake /F Makefile.win nmake /F Makefile.win install第一条命令会编译所有源文件并链接。正常情况下输出会刷一屏每个 .c 文件一行cl /c ...最后一行是link /DLL ...结束时在仓库根目录出现一个vector.dll。中间如果出现warning C4996之类的警告通常可以忽略那是微软对某些 C 标准库函数的弃用提醒。第二条命令是安装它做的事情是把三个东西复制到 PostgreSQL 目录vector.dll→$(libdir)也就是C:\pg\16\libvector.control→$(datadir)\extension也就是C:\pg\16\share\extensionvector--*.sql一系列脚本 → 同一个 extension 目录这里就是权限坑的所在。如果你把 PostgreSQL 装在Program Files下那个目录的写权限默认只给 Administrators 组普通用户跑 install 会报拒绝访问。表现出来的错误大概是这样copy vector.dll C:\Program Files\PostgreSQL\16\lib 拒绝访问。 0 个文件已复制。 NMAKE : fatal error U1077: copy : 返回代码 0x1 停止。新手的第一个反应往往是“命令写错了”然后开始翻 Makefile。其实关键在于看错误的前一行——是“拒绝访问”不是“找不到路径”。解决办法很简单用管理员身份重新打开 cmd把 vcvars、PGROOT、cd 这几步重来一遍再执行 install。注意install 失败的时候编译产物vector.dll是已经在的但可能只有它被复制成功control 和 sql 文件没复制过去。这种半吊子状态最坑CREATE EXTENSION会报could not open extension control file。发现这个错别怀疑源码先去看 extension 目录里到底有几个 vector 开头的文件。安装完成后做个核对这一步别省dir C:\pg\16\lib\vector.dll dir C:\pg\16\share\extension\vector*第一条应该看到一个非零大小的 dll第二条应该看到vector.control加若干个vector--x.y.z.sql。三个东西都在扩展的物理安装才算完成。4. 装载扩展并跑通第一条相似度查询4.1 CREATE EXTENSION 与验证文件到位之后用 psql 连上目标库执行CREATE EXTENSION vector;如果这一步成功说明 dll 能被正常加载头文件版本和服务端也匹配。紧接着做两件事验证SELECT extversion FROM pg_extension WHERE extname vector; SELECT default_version, installed_version FROM pg_available_extensions WHERE name vector;第一条查的是当前库里已装的版本第二条查的是磁盘上有哪些版本可用。两个结果应该一致。如果第一条没返回行说明扩展没建在当前库如果第二条installed_version是空的但default_version有值说明文件在但没装到这个库。一个常见的误会是“装完扩展要重启 PostgreSQL 服务”。其实不需要。PostgreSQL 的扩展是运行时按需加载 dll 的CREATE EXTENSION那一刻才去lib目录找文件。只有一种情况需要重启你替换了一个已经加载过的 dll比如先装了 0.5 版又覆盖成 0.7 版这时候老版本的 dll 还在服务进程内存里得重启才能换掉。4.2 建表、灌数据、看清类型先建一张最小的表把流程跑通三条数据的规模足够验证CREATE TABLE items ( id bigserial PRIMARY KEY, embedding vector(3) ); INSERT INTO items (embedding) VALUES ([1,2,3]), ([4,5,6]), ([7,8,9]);这里有两个点值得展开。第一vector(3)里的 3 是维度约束声明之后这一列只接受三维向量插入四维会直接报错。如果你不确定维度可以写成不带宽度的vector它接受任意维度但建索引时就必须统一维度混着维度存的数据在建索引阶段会失败。实际项目里我强烈建议带上维度它是一道免费的防线——模型换版本导致维度变了插入时立刻报错比事后查出一堆脏数据强。第二输入格式是字符串字面量[1,2,3]这是 PostgreSQL 的数组语法。它跟 JSON 数组长得像但两者不一样别混。如果你从应用层传参一般是在驱动里把浮点数组拼成这个字符串形式或者用::vector做类型转换。维度上限也顺便说一下省得你后面撞墙vector类型本身最多支持 16000 维但建索引的时候只能到 2000 维。这个限制不是 pgvector 偷懒是 ANN 索引本身的内存和计算开销决定的。如果模型输出是 3072 维现在不少嵌入模型都是这个数你就得考虑降维或者改用halfvec——它用半精度浮点存索引支持到 4000 维。4.3 第一条相似度查询与距离操作符的选择数据进去了第一条查询长这样SELECT id, embedding FROM items ORDER BY embedding - [3,1,2] LIMIT 5;-是欧氏距离L2操作符ORDER BY ... LIMIT n就是 pgvector 里最经典的近邻检索写法。返回结果按距离升序排列第一行就是离查询向量最近的那条。默认排序方向是升序因为距离越小代表越像这个语义和常见的“按相似度降序”正好相反写业务代码时别搞反。pgvector 提供的操作符不止一个选错会直接影响检索质量操作符含义数值趋势适用场景-欧氏距离L2越小越近图像特征、坐标类向量#负内积越小越近已归一化的向量等价于余弦余弦距离越小越近文本嵌入未归一化也能用曼哈顿距离L1越小越近对异常值不敏感的场合~汉明距离越小越近二进制向量%Jaccard 距离越小越近二进制集合相似度这里有个容易被绕晕的地方#返回的是负内积。内积本身越大越相似取负之后越小越相似这样所有操作符的排序方向就统一了。如果你直接把#的结果当相似度展示给用户会得到一个负数看起来很怪。要转成 0 到 1 的相似度用1 - (embedding query)或者对内积结果取反。我选哪个取决于向量是怎么来的。文本嵌入模型如果输出已经归一化模长为 1L2 距离和余弦距离在排序上是等价的用哪个都行如果没有归一化余弦距离更稳因为它只关心方向不关心长度。这个判断不涉及任何玄学纯粹是数学性质。4.4 加索引参数怎么算才算合理三条数据的时候上面那条查询走的是全表扫描快得很。数据量上来了就必须建 ANN 索引pgvector 支持两种-- HNSW推荐查询快、召回高 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops); -- IVFFlat建索引快、内存占用低 CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists 100);索引的操作符类必须和查询用的操作符对应用-查询就建vector_l2_ops用就建vector_cosine_ops用#就建vector_ip_ops。建错了索引不是报错而是查询根本不走它EXPLAIN里看到的还是 Seq Scan白白占着空间。IVFFlat 的lists参数有个经验公式很多人抄了但不知道为什么行数在 100 万以内lists rows / 1000行数超过 100 万lists sqrt(rows)比如 50 万行数据lists 5001000 万行数据lists ≈ 3162。这个公式的背后逻辑是lists决定了把向量空间切成多少个簇每个簇的向量数应该和一次查询要扫的候选数量在同一量级。切太少每个簇太大扫描慢切太多簇太小聚类本身的质量下降召回率掉得厉害。查询时的probes参数控制扫几个簇默认是 1太小了。经验值是probes sqrt(lists)。500 个簇的话probes设 22 左右。可以在会话级别调SET ivfflat.probes 22;HNSW 那边对应的参数是ef_search默认 40可以往上调SET hnsw.ef_search 100;调大提高召回率、降低速度调小反过来。这个值没有绝对标准得拿你的数据集实测——准备一批查询用暴力搜索的结果当基准算召回率然后找那个召回率和耗时的平衡点。验证索引有没有生效用这个套路SET enable_seqscan off; EXPLAIN ANALYZE SELECT * FROM items ORDER BY embedding - [3,1,2] LIMIT 5;enable_seqscan off是强制优化器优先考虑索引它不是一个开关而是给顺序扫描加了一个巨大的代价惩罚。如果这样还是不出现Index Scan using ...那就是索引真的用不上常见原因是维度不匹配或者操作符类选错了。提示建 HNSW 索引是个内存大户尤其是数据量大的时候。如果maintenance_work_mem太小它会退化成磁盘排序建索引的时间能从几分钟变成几小时。建之前临时调大一点建完再调回来。5. 常见问题与排查技巧实录5.1 编译期报错速查编译这一步的错误信息大多很直白关键是知道去看哪一行。报错关键字真实原因处理方式nmake 不是内部或外部命令没 call vcvars64.bat或 call 了但换了窗口重开 cmd重新 call 脚本确认输出里有 x64Cannot open include file: postgres.hPGROOT 没设或指错或安装包不含 server 头文件检查include\server\postgres.h是否存在无法打开输入文件 vector.obj编译阶段失败但没注意直接跑了 install往上翻输出找第一个 errorLNK2019 无法解析的外部符号库目录不对链接不到 PostgreSQL 的导入库确认pg_config --libdir指向的目录有 libpostgres.lib拒绝访问/U1077没有管理员权限写不进安装目录管理员身份重开 cmd重跑 installNMAKE : fatal error U1086Makefile.win 的路径变量里有未转义的空格换安装路径或给所有路径加引号这里面最值得说的是第一个和第二个。nmake 不是内部命令这个错误新手容易误解成“nmake 没装”然后跑去装别的东西。实际上 Visual Studio 装完一定有 nmake只是它在一个很深的目录里要靠 vcvars 脚本注入 PATH 才能被找到。看到这个错先别装任何东西先检查你的窗口是不是 call 过那行脚本的同一个窗口。postgres.h找不到也是同理。这个文件不是 PostgreSQL 客户端库的一部分而是服务端头文件只有完整安装才带。有些人装了 psql 客户端就觉得环境齐了其实差得远。还有一个隐蔽的坑编译输出的 warning 里如果有C4819文件包含无法在当前代码页中表示的字符通常不影响结果但如果后面出现莫名其妙的链接错误可以试着把 cmd 的代码页切成 65001 再重来一遍。5.2 运行期报错速查装完之后的问题更分散因为错误信息往往只说“错了”不说“错在哪”。第一种could not open extension control file。这句话的字面意思是找不到vector.control。原因基本只有一个install 的时候文件没复制到当前服务实例的 extension 目录。可能是你机器上有两个 PostgreSQLnmake 装到了另一个也可能是 install 权限不够只复制了一半。排查方法是去pg_config --sharedir输出的目录下看有没有extension\vector.control。如果pg_config指向的目录和你服务的安装目录不是一个那就是版本错位得把 PGROOT 改成服务的那个路径重新编译安装。第二种ERROR: type vector does not exist。这说明扩展没装在你当前连的这个库上。PostgreSQL 的扩展是库级别的A 库装了不代表 B 库能用。用\dx看当前库装了哪些扩展或者CREATE EXTENSION vector;再执行一次。还有一种情况是你连的库装了但search_path被改过导致找不到类型用\dx确认后显式写public.vector试一下。第三种could not load library ...\vector.dll。这个最麻烦因为它可能有好几种不同的后缀。如果是The specified module could not be found通常是 dll 依赖的 VC 运行库没装齐装一个对应的运行库合集能解决。如果是incompatible library或者提到magic block那就是编译时的 PostgreSQL 主版本和服务端不一致必须重新对齐版本编译。如果是The specified procedure could not be found多半是你覆盖了一个旧版本 dll 但服务还在用内存里的旧版本重启服务。第四种ERROR: expected 3 dimensions, not 4。这是维度约束在起作用是好事。改数据的维度或者把列声明成不带长度的vector。但改之前想清楚混维度存储会让索引建不出来。第五种索引明明建了但查询不走。检查三件事操作符类对不对-配vector_l2_ops、EXPLAIN里有没有被enable_seqscan影响、以及矩阵是否真的够大。最后这条最容易被忽略——几十行的表优化器算下来全表扫描比走索引还快它当然不走索引。这不是 bug这是优化器在正常工作。5.3 我在这个流程里印象最深的几个坑第一个坑是路径里的空格。我第一次编译的时候把 PostgreSQL 装在默认的Program Files下面然后set PGROOTC:\Program Files\PostgreSQL\16这样写结果 Makefile 里所有拼出来的路径都被空格切断了报了一堆“找不到文件”但错误信息指向的是一个看起来完全不存在的路径。正确写法是把整个赋值用双引号包起来set PGROOTC:\Program Files\PostgreSQL\16。这个写法看着别扭但它是 cmd 里处理带空格路径的标准姿势。后来我干脆换了个无空格的安装目录一劳永逸。第二个坑是换版本时的 dll 缓存。有次我先把 0.5 版装好觉得功能不够又编了 0.7 版覆盖上去然后CREATE EXTENSION一直报函数不存在。折腾了半小时才发现服务进程里加载的还是老 dllCREATE EXTENSION走的还是老的 SQL 脚本。覆盖 dll 之后一定要重启一次服务这条我写在了自己的备忘里。判断方法也简单SELECT extversion FROM pg_extension如果显示的还是旧版本号那就是没换成功。第三个坑是把“能查到结果”当成“装好了”。前面跑通的那条ORDER BY - LIMIT 5在三条数据的表上走的是全表扫描它根本没用索引。真正要验证索引生效必须造一批有规模的数据再配合EXPLAIN ANALYZE看执行计划。我现在的习惯是装完扩展先建一张 10 万行的测试表建索引然后用SET enable_seqscan off加EXPLAIN确认走的是Index Scan这一步过了才算真的通了。这个检查多花十分钟能避免后面在业务数据量上来之后才发现索引压根没用上的尴尬。第四个坑说出来有点丢人有回我调hnsw.ef_search调完发现查询速度没变化一度以为参数没生效。后来才反应过来那条查询总共就几十行数据走的是顺序扫描ef_search只对 HNSW 索引扫描有意义。参数调优的前提是查询真的在用那个索引否则调什么都是在跟空气较劲。最后分享一个我自己常用的验证脚本装完任何一台机器都跑一遍五秒钟就能判断这套环境是不是真的可用SELECT extversion FROM pg_extension WHERE extname vector; DROP TABLE IF EXISTS _smoke_test; CREATE TABLE _smoke_test (id bigserial PRIMARY KEY, e vector(4)); INSERT INTO _smoke_test (e) VALUES ([1,0,0,0]), ([0,1,0,0]), ([0,0,1,0]); SELECT id, e - [1,0,0,0] AS dist FROM _smoke_test ORDER BY e - [1,0,0,0] LIMIT 3; DROP TABLE _smoke_test;预期结果是三条记录距离分别是 0、1.414、1.414第一行就是自己跟自己比。这个结果对上了说明类型、操作符、扩展加载三个环节全部正常剩下的才轮到索引和性能的调优。