企业官网建设流程全解析

Windows 完整跑通 pgvector 向量搜索：编译安装到首次查询全指南

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

pgvector 是 PostgreSQL 的开源向量相似性搜索扩展。部署好之后，embedding 向量直接存在普通表里，建上 HNSW 或 IVFFlat 索引，一条 SQL 就能查出最相似的结果，不需要再单独维护一套向量数据库。本文覆盖 Windows 10/11 上 pgvector 部署的完整流程：环境准备、nmake 编译、验收与回归测试，照着敲一遍就能跑通。

先定验收标准：两行 SQL

动手前先明确目标。整个部署是否成功，只看两句话在 psql 里能否跑通、第二句能否返回版本号：

CREATE EXTENSION vector; SELECT vector_version();

下面所有内容都是围绕这两句倒推展开：需要什么环境、敲哪些命令、中途报错怎么处置。

从验收倒推：编译必须齐备的四样东西

pgvector 是 C 语言扩展，在 Windows 上构建依赖一套完整的 C++ 工具链加上 PostgreSQL 的开发文件。开工前逐项对一下：

• PostgreSQL 14 及以上：推荐 16 或 18。编译要读它的头文件（include 目录）和库文件（lib 目录），跑回归测试时还要用到它自带的 pg_regress
• Visual Studio 2019 及以上：安装时务必勾选"C++ 桌面开发"工作负载，漏勾是后面编译失败的头号原因
• Windows SDK 10.0.19041 及以上：通常随 VS 工具链一起装，别落下
• Git：较新版本即可，用于拉取源码

前 3 项属于硬依赖，缺一项 nmake 必然报错；Git 只在开头用一次。

Windows 编译 pgvector 的完整流程

第一步：拉取源码

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

源码放系统临时目录就够，编译安装完成后剩下的文件不再碍事。

第二步：把 PGROOT 指到 PostgreSQL 安装目录

构建脚本 Makefile.win 靠PGROOT这个环境变量定位头文件、库文件和安装目标，没设会直接以PGROOT is not set报错终止。顺手在同一会话里把 bin 加进 PATH，后面连库时能直接敲 psql：

set PGROOT=C:\Program Files\PostgreSQL\16 set PATH=%PGROOT%\bin;%PATH%

末尾的 16 按你实际安装的版本改。

第三步：编译并安装

终端要用 VS 的x64 Native Tools Command Prompt——只有这个 shell 里配好了 SDK 和 64 位编译器的环境变量，换别的 shell 大概率找不到头文件。

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

第一行把 src/ 下的源码编译成vector.dll；第二行负责落地：动态库拷进 PGROOT 的lib目录，vector.control 与 sql/ 下的扩展脚本放入share\extension。两行跑完，部署就算就位。

装完验证与完整回归

先回到开头那两句，在任意数据库执行：

CREATE EXTENSION vector; SELECT vector_version();

第二句返回你编译出来的版本号，主流程到此走通。

想更稳一点，再跑一遍完整回归。它会把 test/sql/ 下的 14 个用例全部过一遍，覆盖类型转换、索引构建、距离函数三大块：

nmake /F Makefile.win installcheck

输出很长，只看末尾汇总：没有 FAILED 就算通过。

编译报错的三类高发问题 ⚠️

报错信息像一张地址单，先读地址再动手，别盲敲命令。Windows 上的红屏九成落在下面三种：

1. 找不到crtdefs.h基本是工具链问题：用错了终端，或 VS 缺"C++ 生成工具"组件。先切到 x64 Native Tools Command Prompt 重编；仍不行就打开 VS Installer 修复对应组件。

2.PGROOT is not set环境变量没设，或设置后另开了新终端——set只在当前会话生效。在当前会话里重新执行一遍set PGROOT=...即可。

3.C2196 case value already used通常意味着编译环境不是 VS 原生环境，编译器对常量识别出了问题。切对命令行后，先清理再重编：

nmake /F Makefile.win clean nmake /F Makefile.win

pgvector 装好之后的能力速查

四种向量类型基本覆盖所有 embedding 输出：

• vector：单精度浮点，HNSW/IVFFlat 索引上限 2,000 维
• halfvec：半精度浮点，体积减半，索引上限 4,000 维
• bit：二进制向量，索引上限 64,000 维，适合二值量化场景
• sparsevec：稀疏向量，只存非零元素，专为高维稀疏数据设计

四个距离算子都能配合索引使用：

两类索引各有所长：HNSW基于图结构，查询速度快，多数场景默认选它；IVFFlat构建快、内存开销低，适合更看重构建时长的数据量。

索引构建与查询调优要点

几条经验能帮你避开大部分性能坑：

• 数据灌完再建索引：先建索引再插数据，速度会差很多
• 调大maintenance_work_mem：它直接决定索引构建可用的内存预算
• 大表开并行 worker建索引，把多核用起来
• 搜索参数二选一：HNSW 调ef_search，IVFFlat 调probes，调高换召回、调低换速度
• 小表别急着上索引：直接顺序扫描往往更快也更稳

pgvector 的 Windows 部署没有玄学——设一个变量、敲两行编译、用两行 SQL 验收，向量搜索就在手边了；下一步建一张表灌入 embedding，用ORDER BY embedding <-> '...'跑第一条查询试试手。

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