企业官网建设流程全解析

5分钟装好pgvector：PostgreSQL向量搜索扩展的Linux新手安装指南

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

pgvector 是 PostgreSQL 的开源向量相似性搜索扩展，让你熟悉的数据库直接用 SQL 完成嵌入检索与语义搜索。需要搭建推荐或语义搜索应用、又不想多维护一套向量数据库时，pgvector 是成本最低的选择。这篇 pgvector 安装教程以 Ubuntu 为例，从环境检查到结果验证，全程约 5 分钟，每一步都可独立执行、独立验证。

环境检查：开始安装前备齐3样东西

本教程基于 Ubuntu 22.04 / 24.04，请先核对以下清单，任何一项缺失都会导致编译失败：

• 操作系统：Ubuntu 22.04 及以上，已安装 git 与基础 shell
• PostgreSQL：14 及以上（推荐 16 / 17），通过系统软件源 apt 安装即可，无需手动下载安装程序
• 服务器开发头文件：postgresql-server-dev，版本号须与当前 PostgreSQL 大版本一致
• 源码获取：pgvector 官方仓库，使用 git 克隆，地址见下文第一步

路径一：5分钟装好pgvector 🚀

这条路径是新手最快的路线，适合使用默认安装的 PostgreSQL，按编号顺序执行三步即可。

第1步，克隆 pgvector 源码到本地任意可写目录：

git clone https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector

克隆成功后目录下应能看到src/、sql/等子目录，说明源码已就位。

第2步，安装编译工具链和对应版本的服务器开发头文件（16 换成你的实际大版本）：

sudo apt update sudo apt install -y build-essential postgresql-server-dev-16

安装过程无报错即依赖就绪，可用pg_config --version确认编译器将识别到的版本。

第3步，编译并安装到默认 PostgreSQL 目录：

make sudo make install

make install正常结束即安装完成，此时向量库文件与控制文件已复制到 PostgreSQL 的 lib 与 share/extension 目录。

路径二：进阶自定义构建（适合开发者）

当同一台机器并存多个 PostgreSQL 大版本、需要指定版本构建时，通过显式指定PG_CONFIG控制编译目标：

make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config sudo make install

这样编译会严格对准指定版本头文件，需要切换版本时重新执行即可，适合 16、17 共存的开发机场景。

结果验证：2条SQL确认安装是否成功

重启 PostgreSQL 服务后用 psql 登录，执行下面两条语句验证扩展是否就绪：

CREATE EXTENSION vector; SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

预期输出为单行结果，extname 显示vector、extversion 为你刚构建的版本（如 0.8.6），两条语句均无报错即代表安装成功。

上手体验：4条SQL跑通向量相似度搜索

下面 4 条语句让你在 30 秒内体验 pgvector 的核心能力——按距离找最近的向量：

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 * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 3; DROP TABLE items;

查询会先返回[1,2,3]这一行，因为它的欧氏距离最小，这正是相似性搜索的核心行为。

常见报错与排查 🔧

报错1：make: pg_config: command not found

• 报错原文：make: pg_config: command not found
• 原因分析：未安装 PostgreSQL 服务器开发头文件，make 拿不到编译参数。
• 解决方法：执行sudo apt install postgresql-server-dev-16（版本对齐后重新make。

报错2：could not open extension control file

• 报错原文：ERROR: could not open extension control file ".../vector.control": No such file or directory
• 原因分析：控制文件未被复制到当前大版本的 extension 目录，通常发生在多版本共存时选错了构建目标。
• 解决方法：用pg_config --sharedir查看目标目录，确认vector.control是否存在；缺失时用路径二对正确版本重新make install。

报错3：extension "vector" is not available

• 报错原文：ERROR: extension "vector" is not available
• 原因分析：pgvector 编译时对准的 PostgreSQL 大版本与当前连接的服务不一致，动态库无法加载。
• 解决方法：用路径二显式指定目标版本的PG_CONFIG重新构建并安装，再重启服务。

4条实用技巧：让pgvector运行更稳

1. 版本兼容：pgvector 按 PostgreSQL 大版本编译，数据库升级大版本后需重新构建一次。
2. 按库创建：扩展是数据库级对象，每个新建数据库都要单独执行一次CREATE EXTENSION vector。
3. 索引选型：百万级数据建议建 HNSW 或 IVFFlat 索引加速检索；小表顺序扫描即可，不必建索引。
4. 维度一致：建表时声明的向量维度必须与实际数据一致，否则插入和查询都会报错。

安装完成之后：接下来可以做什么 💡

验证通过后，建议按以下路径继续深入：

• 接入真实业务数据，用现成嵌入模型的输出做第一版语义搜索
• 对比 HNSW 与 IVFFlat 的检索参数差异，在自己数据上调召回与速度
• 理解 L2、内积、余弦三种距离度量的适用场景，为不同业务选对度量
• 阅读源码中 test/ 目录的测试用例，学习索引构建与查询的更多写法

到这里，PostgreSQL 已能同时承担关系数据与向量检索，无需再引入额外组件。挑一个最小场景，把第一条相似性查询跑在你的真实数据上，就是最合适的起点。

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