pgvector Windows 编译安装指南：4 步出 vector.dll，附体检清单与报错对照

pgvector Windows 编译安装指南4 步出 vector.dll附体检清单与报错对照【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvectorpgvector 是给 Postgres 加的向量搜索扩展让它能直接存向量、查相似。这篇 Windows 编译安装教程面向第一次在 Windows 上动手的你全程跟着敲最后手里多一个能跑通的 vector.dll并装进数据库、用 SQL 查出最近邻。目标先行装完之后长什么样别急着敲命令先定下什么算装好。装好后你能直接做这三件事做到任意一条就说明成功在任意数据库里执行CREATE EXTENSION vector;不再报未找到扩展。建一张带vector(3)列的表能插进[1,2,3]这样的向量。用ORDER BY embedding - [3,1,2] LIMIT 5这种写法按距离排好序返回最近的行。把这三步记在脑子里后面每一步的自检都是朝着它走的。开工前体检清单Windows 上编译最容易翻车基本都栽在环境没配齐。开工前先把下面这张表过一遍比装到一半报错再回头查省事得多。检查项怎么确认通过标准C 编译器VS2022在 VS 命令提示符里敲cl.exe能看到编译器版本信息而不是不是内部或外部命令PostgreSQL 开发文件看%PGROOT%\include\server\postgres.h该文件存在PostgreSQL 库文件看%PGROOT%\lib\postgres.lib该文件存在PGROOT 路径变量echo %PGROOT%打印出你的 PostgreSQL 安装目录例如C:\Program Files\PostgreSQL\18管理员权限用管理员身份打开命令提示符窗口标题带管理员字样PGROOT是后面 Makefile.win 里所有路径的根它一旦指错编译会直接报PGROOT is not set或找不到postgres.h。按这个顺序动手整个流程就四步先备好工具再打通编译器和 PostgreSQL然后产出 dll最后装进库。每步都带一句白话和一个就地自检。第 1 步装工具装 Visual Studio 2022 时工作负载勾选使用 C 的桌面开发可选组件里带上 C 的 CMake 工具和对应版本的 Windows SDK。再装 PostgreSQL 13 及以上版本安装界面里勾上 Development Files开发文件把实际安装路径记下来。自检在以管理员身份打开的x64 Native Tools Command Prompt for VS 2022里敲cl.exe能看到版本信息就对了。第 2 步打通编译器与 PostgreSQL这一步就是告诉 nmakePostgreSQL 装在哪、编译器在哪。在 VS 命令提示符里先设好变量set PGROOTC:\Program Files\PostgreSQL\18这条命令的作用是把 PGROOT 指到你的 PostgreSQL 安装目录18换成你的实际版本号。接着验证目录里该有的文件都在dir %PGROOT%\include\server\postgres.h dir %PGROOT%\lib\postgres.lib第一条检查头文件第二条检查链接用的库文件两个都能列出文件说明 Makefile.win 里INCLUDEDIR_SERVER和LIBDIR引用的路径都有效。第 3 步产出 vector.dll拿到源码后开始编译。源码可以 clone 到临时目录git clone --branch v0.8.6 https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector然后编译nmake /F Makefile.win这条命令会按 Makefile.win 里的规则把 src/ 下的vector.c、hnsw.c、ivfflat.c等几十个 C 文件依次编译、链接成vector.dll。它默认带了/O2 /fp:fast优化见 Makefile.win 第 17 行。自检当前目录出现vector.dll编译过程没有停在报错上。第 4 步安装进库把刚产出的 dll 和 SQL 文件复制进 PostgreSQL 的 lib、share 目录nmake /F Makefile.win install这条命令把vector.dll拷到lib把vector.control和各版本升级脚本sql/vector--*.sql拷到share\extension。自检确认这两个文件就位——dir %PGROOT%\lib\vector.dll dir %PGROOT%\share\extension\vector.control跑通即验证重启一下 PostgreSQL或确认服务在跑连上库跑这段最小 SQL。能正常返回结果就真跑通了CREATE EXTENSION vector;打开扩展每个想用的库都要执行一次。CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3)); INSERT INTO items (embedding) VALUES ([1,2,3]), ([4,5,6]);建一张 3 维向量表塞进去两条数据。SELECT * FROM items ORDER BY embedding - [3,1,2] LIMIT 5;按 L2 距离排序返回离目标向量最近的行。想看余弦相似度可以换操作符内积用#L1 用这些都在 README.md 的 Querying 一节有说明。报错对照高频报错基本就这几类对症下药即可。症状原因一句话动作PGROOT is not set没设变量或没在同一窗口设在当前命令窗口重新set PGROOT...Cannot open include file: postgres.h开发文件没装或 PGROOT 指错重装时勾 Development Files并核对%PGROOT%cl.exe不是内部或外部命令没用 VS 命令提示符改用 x64 Native Tools Command Prompt 打开error C2196: case value 4 already used用了非 x64 的提示符换 x64 Native Tools 提示符nmake /F Makefile.win clean后重编Access is denied权限不够用管理员身份重跑 install⚠️ 最容易被忽略的是postgres.h那个它几乎总是 PGROOT 指错了目录而不是真的缺文件。先dir %PGROOT%\include\server\postgres.h确认路径再谈重装。另外一个容易踩的是 Postgres 17.0–17.2 链接时报unresolved external symbol float_to_shortest_decimal_bufn这是旧小版本的已知问题把 PostgreSQL 升到 17.3 及以上即可。让更快/更省想编译快一点、产物更省就两件事点到为止优化已默认开着。Makefile.win 默认就加了/O2 /fp:fast不用动。如果确认 CPU 支持可以往OPTFLAGS里加/arch:AVX2进一步提速见 Makefile.win 第 11–17 行不支持就留空别乱加。装完后的索引建得更快。数据先导入、后建索引用SET maintenance_work_mem和max_parallel_maintenance_workers提速HNSW 尤其吃这两项具体写法参考 README.md 的 Index Build Time。装完能干什么装上之后你在 Postgres 里就有了这几类能力四种向量类型vector单精度、halfvec半精度更省内存、bit二进制、sparsevec稀疏上限维度各不相同。六种距离度量L2-、内积#、余弦、L1、汉明~、Jaccard%。精确与近似搜索不加索引就是精确最近邻加 HNSW 或 IVFFlat 索引换速度用hnsw.ef_search、ivfflat.probes调召回。和 SQL 混着用WHERE过滤 距离排序、分区、混合全文检索都可以细节见 README.md。相关实现都能直接翻源码距离和 HNSW 逻辑在 src/hnsw.c、IVFFlat 在 src/ivfflat.c回归测试在 test/sql/。收尾与延伸到这儿Windows 下的 pgvector 就算落地了。接下来三步给真实数据建 HNSW 或 IVFFlat 索引用EXPLAIN (ANALYZE, BUFFERS)看查询是否走了索引。数据量大时换halfvec存、用二进制量化建索引把内存和工作集压下来。对照 test/ 里的回归用例把向量类型、距离、过滤各跑一遍确认和你的用法一致。把扩展装进 Postgres向量搜索和结构化查询就能待在同一个库里——后面再谈性能调优或索引选择都建立在这份能跑通的环境上。【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考