拓冰网站定制 
pgvector 30 分钟跑通指南PostgreSQL 向量相似搜索从环境自检到 HNSW 索引验证【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector当你的 Postgres 数据库需要承接语义检索或图片相似搜索不必再引入一套向量数据库装好 pgvector 扩展后向量存储与最近邻搜索直接在数据库内完成支持精确搜索和 HNSW、IVFFlat 近似索引。本文带你从源码编译 pgvector、装进已有的 PostgreSQL到跑通第一次向量相似搜索全程约 30 分钟。开工前自检环境检查清单动手前先确认四样东西都就位缺哪样先补哪样避免编译到一半再回退组件版本要求自检命令通过标准PostgreSQL 服务器13 及以上psql --version输出版本号 ≥ 13编译工具链gcc、make 任一可用版本gcc --version make --version均正常输出版本号PostgreSQL 开发文件与服务端主版本一致pg_config --pgxs无报错输出 pgxs 路径git任意可用版本git --version正常输出 机器上装了多个 PostgreSQL 版本时pg_config默认指向的可能不是你跑服务的那个。先执行pg_config --version确认对齐不一致时记下正确路径后文编译阶段会用PG_CONFIG指定。主流程编译安装并启用 pgvector装工具链与开发文件编译扩展需要 gcc、make 和 PostgreSQL 头文件一次装齐。# Ubuntu / Debian 示例16 换成你的服务端主版本RHEL 系用 dnf 安装对应包 sudo apt install -y build-essential postgresql-16 postgresql-server-dev-16你应该看到包列表中包含postgresql-server-dev-16对应版本Setting up或already the newest version字样且无E: Unable to locate package。获取 pgvector 源码把源码拉到工作目录固定到 v0.8.6 标签保证你装出来的版本与下文验证清单中的版本号一致。cd /tmp git clone --branch v0.8.6 https://gitcode.com/GitHub_Trending/pg/pgvector.git cd pgvector ls你应该看到目录里有 Makefile、src/、sql/、test/等条目clone过程无认证或网络报错。编译并安装扩展make产出vector.so和 SQL 脚本make install写入 PostgreSQL 的安装目录。# 若 pg_config 指向的服务器不是默认版本先执行export PG_CONFIG/path/to/pg_config make sudo make install你应该看到输出末尾出现若干installing ...行包含vector.control、vector--0.8.6.sql和vector.so路径形如/usr/share/postgresql/16/extension和/usr/lib/postgresql/16/lib以你的实际安装位置为准无Error字样。⚠️ 多版本环境下如果make报fatal error: postgres.h先make clean再设置PG_CONFIG后重新makesudo make install时如使用了PG_CONFIG记得写成sudo --preserve-envPG_CONFIG make install否则环境变量会被 sudo 丢弃。启用扩展并跑第一次相似搜索在服务端的某个数据库里启用扩展插入三条向量做第一次 L2 最近邻查询。psql -U postgresCREATE EXTENSION vector; 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 id, embedding FROM items ORDER BY embedding - [3,1,2] LIMIT 1;你应该看到查询返回一行id 1、embedding [1,2,3]说明最近邻搜索已生效。验证清单确认扩展真正生效按顺序执行以下 5 项全部通过才算跑通版本检查在 psql 执行SELECT extversion FROM pg_extension WHERE extname vector;。合格标准返回0.8.6与源码标签一致。L2 精确搜索SELECT id FROM items ORDER BY embedding - [1,2,3] LIMIT 1;。合格标准返回1最近的是自身。余弦距离SELECT 1 - (embedding [1,2,3]) AS cosine_similarity FROM items ORDER BY embedding [1,2,3];。合格标准返回 3 行首行为1。HNSW 索引生效CREATE INDEX ON items USING hnsw (embedding vector_l2_ops); BEGIN; SET LOCAL enable_seqscan off; EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM items ORDER BY embedding - [3,1,2] LIMIT 1; COMMIT;合格标准计划中出现Index Scan且索引名为items_embedding_hnsw_idx而非Seq Scan。文件对齐ls $(pg_config --pkglibdir)/vector.so ls $(pg_config --sharedir)/extension/vector.control。合格标准两个文件都存在。 技术细节第 4 项里小表加enable_seqscan off是为了强制规划器走索引验证可用性——表行数太少时顺序扫描本身更便宜出现Seq Scan不代表索引坏掉。排障速查高频报错对照表报错关键词常见原因处理动作pg_config: command not found未安装 PostgreSQL 开发包sudo apt install postgresql-server-dev-1616 换成你的版本fatal error: postgres.h: No such file or directory开发文件缺失或pg_config指向了与运行中服务不一致的版本安装对应版本的 server-dev 包多版本时export PG_CONFIG...后make clean makemake install报Permission denied/cannot create regular file当前用户无 PostgreSQL 安装目录写权限改用sudo make installERROR: extension vector is not available或could not open library ... vector.so扩展文件装到了错误版本目录或服务端未感知新库用ls $(pg_config --pkglibdir)/vector.so核对路径不一致则重装确认后用pg_ctl restart重启服务查询计划里看不到索引出现Seq Scan缺LIMIT或ORDER BY不是距离操作符的直接结果如写成ORDER BY 1 - (embedding ...) DESC改写成ORDER BY embedding - [3,1,2] LIMIT n再用第 4 项的方法强制验证再进一步调参与自测两个方向可以接着做一是调 HNSW 查询参数SET hnsw.ef_search 100提升召回率带WHERE过滤时开启SET hnsw.iterative_scan relaxed_order细节见 README.md 的 Query Options 一节二是跑项目自带的回归与 TAP 测试make installcheck验证 SQL 行为test/t/ 下还有 WAL、vacuum、召回率等专项测试可对照你环境的实际表现。到这里你的 PostgreSQL 已经能存向量并做最近邻搜索。下一步建议导入真实维度的 embedding对比 HNSW 与 IVFFlat 在你数据量下的召回率和延迟再决定索引参数。【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pgvector 30 分钟跑通指南：PostgreSQL 向量相似搜索从环境自检到 HNSW 索引验证
pgvector 30 分钟跑通指南PostgreSQL 向量相似搜索从环境自检到 HNSW 索引验证【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector当你的 Postgres 数据库需要承接语义检索或图片相似搜索不必再引入一套向量数据库装好 pgvector 扩展后向量存储与最近邻搜索直接在数据库内完成支持精确搜索和 HNSW、IVFFlat 近似索引。本文带你从源码编译 pgvector、装进已有的 PostgreSQL到跑通第一次向量相似搜索全程约 30 分钟。开工前自检环境检查清单动手前先确认四样东西都就位缺哪样先补哪样避免编译到一半再回退组件版本要求自检命令通过标准PostgreSQL 服务器13 及以上psql --version输出版本号 ≥ 13编译工具链gcc、make 任一可用版本gcc --version make --version均正常输出版本号PostgreSQL 开发文件与服务端主版本一致pg_config --pgxs无报错输出 pgxs 路径git任意可用版本git --version正常输出 机器上装了多个 PostgreSQL 版本时pg_config默认指向的可能不是你跑服务的那个。先执行pg_config --version确认对齐不一致时记下正确路径后文编译阶段会用PG_CONFIG指定。主流程编译安装并启用 pgvector装工具链与开发文件编译扩展需要 gcc、make 和 PostgreSQL 头文件一次装齐。# Ubuntu / Debian 示例16 换成你的服务端主版本RHEL 系用 dnf 安装对应包 sudo apt install -y build-essential postgresql-16 postgresql-server-dev-16你应该看到包列表中包含postgresql-server-dev-16对应版本Setting up或already the newest version字样且无E: Unable to locate package。获取 pgvector 源码把源码拉到工作目录固定到 v0.8.6 标签保证你装出来的版本与下文验证清单中的版本号一致。cd /tmp git clone --branch v0.8.6 https://gitcode.com/GitHub_Trending/pg/pgvector.git cd pgvector ls你应该看到目录里有 Makefile、src/、sql/、test/等条目clone过程无认证或网络报错。编译并安装扩展make产出vector.so和 SQL 脚本make install写入 PostgreSQL 的安装目录。# 若 pg_config 指向的服务器不是默认版本先执行export PG_CONFIG/path/to/pg_config make sudo make install你应该看到输出末尾出现若干installing ...行包含vector.control、vector--0.8.6.sql和vector.so路径形如/usr/share/postgresql/16/extension和/usr/lib/postgresql/16/lib以你的实际安装位置为准无Error字样。⚠️ 多版本环境下如果make报fatal error: postgres.h先make clean再设置PG_CONFIG后重新makesudo make install时如使用了PG_CONFIG记得写成sudo --preserve-envPG_CONFIG make install否则环境变量会被 sudo 丢弃。启用扩展并跑第一次相似搜索在服务端的某个数据库里启用扩展插入三条向量做第一次 L2 最近邻查询。psql -U postgresCREATE EXTENSION vector; 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 id, embedding FROM items ORDER BY embedding - [3,1,2] LIMIT 1;你应该看到查询返回一行id 1、embedding [1,2,3]说明最近邻搜索已生效。验证清单确认扩展真正生效按顺序执行以下 5 项全部通过才算跑通版本检查在 psql 执行SELECT extversion FROM pg_extension WHERE extname vector;。合格标准返回0.8.6与源码标签一致。L2 精确搜索SELECT id FROM items ORDER BY embedding - [1,2,3] LIMIT 1;。合格标准返回1最近的是自身。余弦距离SELECT 1 - (embedding [1,2,3]) AS cosine_similarity FROM items ORDER BY embedding [1,2,3];。合格标准返回 3 行首行为1。HNSW 索引生效CREATE INDEX ON items USING hnsw (embedding vector_l2_ops); BEGIN; SET LOCAL enable_seqscan off; EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM items ORDER BY embedding - [3,1,2] LIMIT 1; COMMIT;合格标准计划中出现Index Scan且索引名为items_embedding_hnsw_idx而非Seq Scan。文件对齐ls $(pg_config --pkglibdir)/vector.so ls $(pg_config --sharedir)/extension/vector.control。合格标准两个文件都存在。 技术细节第 4 项里小表加enable_seqscan off是为了强制规划器走索引验证可用性——表行数太少时顺序扫描本身更便宜出现Seq Scan不代表索引坏掉。排障速查高频报错对照表报错关键词常见原因处理动作pg_config: command not found未安装 PostgreSQL 开发包sudo apt install postgresql-server-dev-1616 换成你的版本fatal error: postgres.h: No such file or directory开发文件缺失或pg_config指向了与运行中服务不一致的版本安装对应版本的 server-dev 包多版本时export PG_CONFIG...后make clean makemake install报Permission denied/cannot create regular file当前用户无 PostgreSQL 安装目录写权限改用sudo make installERROR: extension vector is not available或could not open library ... vector.so扩展文件装到了错误版本目录或服务端未感知新库用ls $(pg_config --pkglibdir)/vector.so核对路径不一致则重装确认后用pg_ctl restart重启服务查询计划里看不到索引出现Seq Scan缺LIMIT或ORDER BY不是距离操作符的直接结果如写成ORDER BY 1 - (embedding ...) DESC改写成ORDER BY embedding - [3,1,2] LIMIT n再用第 4 项的方法强制验证再进一步调参与自测两个方向可以接着做一是调 HNSW 查询参数SET hnsw.ef_search 100提升召回率带WHERE过滤时开启SET hnsw.iterative_scan relaxed_order细节见 README.md 的 Query Options 一节二是跑项目自带的回归与 TAP 测试make installcheck验证 SQL 行为test/t/ 下还有 WAL、vacuum、召回率等专项测试可对照你环境的实际表现。到这里你的 PostgreSQL 已经能存向量并做最近邻搜索。下一步建议导入真实维度的 embedding对比 HNSW 与 IVFFlat 在你数据量下的召回率和延迟再决定索引参数。【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考