概述pgvector 是 PostgreSQL 官方生态中推荐的向量相似性搜索扩展支持高维向量的存储、相似度计算以及向量索引结构。在使用 pgvector 之前需要完成扩展的安装与基本配置。本文基于 PostgreSQL 17 环境pgvector 支持 PostgreSQL 13 及以上版本系统介绍三种主流的 pgvector 安装方式pgenv一键安装、源码编译安装以及 RPM 包安装并重点剖析源码安装过程中常见的pg_config路径问题和权限问题。纲要pgvector扩展概述功能特性适用版本安装方式对比pgenv一键安装源码编译安装RPM 包安装pg_config与PGXS构建基础设施pg_config的作用PGXS构建系统多 PostgreSQL 版本环境下的路径指定权限问题与解决方案扩展启用与验证vector数据类型基础使用pgvector 扩展概述pgvector 是 PostgreSQL 的向量相似性搜索扩展由 pgvector/pgvector 开源项目维护。其核心能力包括精确与近似最近邻搜索支持精确搜索和基于索引的近似搜索多精度向量类型单精度 (vector)、半精度 (halfvec)、二进制 (bit)、稀疏向量 (sparsevec)多种距离函数L2 距离 (-)、内积 (#)、余弦距离 ()、L1 距离 ()、汉明距离 (~)、Jaccard 距离 (%)ACID 兼容与 PostgreSQL 事务机制完全兼容pgvector 支持 PostgreSQL 13 及以上版本。安装方式对比安装 pgvector 主要有三种方式适用不同场景安装方式适用场景优点缺点pgenv一键安装快速部署、开发测试自动处理依赖命令简洁需要网络版本可能滞后源码编译安装生产环境、指定版本最灵活可指定任意版本需手动处理依赖和路径RPM 包安装企业生产、离线环境符合企业运维规范依赖处理较繁琐pgenv 一键安装pgenv是一个 PostgreSQL 二进制版本管理工具由社区开发者维护旨在帮助用户快速安装和管理 PostgreSQL 及其扩展。适用版本pgenv 已适配 PostgreSQL 13 至 17。安装步骤# 1. 添加 pgenv 仓库sudopgenv repoaddPGDG# 2. 安装 pgvector 扩展pgenv extinstallpgvectorpgenv会自动处理所有依赖项如 LLVM、Python 开发包等无需手动解决依赖关系。这对于新手用户或不希望折腾依赖环境的场景尤为推荐。源码编译安装源码编译安装是最通用、最灵活的方式适用于需要安装特定版本或无法使用包管理器的场景。标准编译步骤参照 pgvector 官方文档# 1. 获取源码cd/tmpgitclone--branchv0.8.6 https://github.com/pgvector/pgvector.gitcdpgvector# 2. 编译make# 3. 安装可能需要 sudomakeinstallpg_config 的作用源码编译过程中make命令需要知道 PostgreSQL 的安装位置、头文件路径、库文件路径等信息。pg_config是 PostgreSQL 提供的配置信息查询工具它打印当前安装的 PostgreSQL 版本的配置参数。pg_config的核心输出包括--bindir用户可执行文件位置--includedir头文件位置--libdir库文件位置--pgxs扩展 makefile 位置在扩展的Makefile中通过PGXSPostgreSQL Extension Build Infrastructure机制调用pg_config来获取这些信息PG_CONFIG pg_config PGXS : $(shell $(PG_CONFIG) --pgxs) include $(PGXS)常见问题pg_config not found当执行make install时如果系统提示pg_config: command not found说明当前环境找不到pg_config命令。原因分析PostgreSQL 的开发包postgresql-server-dev未安装pg_config不在PATH环境变量中使用sudo时超级用户环境与普通用户环境不同解决方案一安装开发包对于 Debian/Ubuntusudoaptinstallpostgresql-server-dev-17对于 RHEL/Rocky Linuxsudoyuminstallpostgresql17-devel解决方案二指定 PG_CONFIG 路径如果系统中有多个 PostgreSQL 版本或pg_config不在PATH中可以在make命令中直接指定makePG_CONFIG/usr/pgsql-17/bin/pg_configsudomakeinstallPG_CONFIG/usr/pgsql-17/bin/pg_config解决方案三使用 sudo 时保留环境变量当需要使用sudo执行make install时sudo默认会重置环境变量导致pg_config不可用。解决方案sudo--preserve-envPG_CONFIGmakeinstall安装验证源码编译安装完成后pgvector 的动态库文件.so会安装到 PostgreSQL 的lib目录控制文件.control和 SQL 脚本会安装到share/extension目录。# 查看动态库ls$PGHOME/lib/vector.so# 查看控制文件ls$PGHOME/share/extension/vector.controlRPM 包安装RPM 包安装适用于企业生产环境特别是无法联网或需要严格版本管控的场景。从 PostgreSQL Yum 仓库安装# RHEL/Rocky Linuxsudoyuminstallpgvector_17# 或sudodnfinstallpgvector_17RPM 安装方式的挑战在于需要提前解决所有依赖项包括 LLVM、Git 以及 PostgreSQL 开发包等。扩展启用与验证无论采用哪种安装方式最后都需要在数据库中启用扩展。连接到目标数据库后执行-- 创建 pgvector 扩展CREATEEXTENSIONIFNOTEXISTSvector;-- 验证安装SELECTextname,extversionFROMpg_extensionWHEREextnamevector;执行结果示例extname | extversion --------------------- vector | 0.8.6 (1 row)注意CREATE EXTENSION命令需要在每个需要使用 pgvector 的数据库中分别执行。vector 数据类型基础使用安装并启用扩展后即可使用vector数据类型-- 创建包含向量列的表3 维向量CREATETABLEitems(id BIGSERIALPRIMARYKEY,embedding vector(3));-- 插入向量数据INSERTINTOitems(embedding)VALUES([1,2,3]),([4,5,6]);-- L2 距离最近邻查询SELECT*FROMitemsORDERBYembedding-[3,1,2]LIMIT5;API 速览本节梳理 pgvector 安装与使用过程中涉及的核心 API 与命令。pg_config所属PostgreSQL 核心工具方法签名pg_config[option...]常用选项选项说明--bindir用户可执行文件位置--includedirC 头文件位置--libdir库文件位置--pgxs扩展 makefile 位置--configure构建时的 configure 选项示例# 查看所有配置pg_config# 查看 pgxs 路径pg_config--pgxs# 输出示例: /usr/pgsql-17/lib/pgxs/src/makefiles/pgxs.mkCREATE EXTENSION所属PostgreSQL SQL 命令方法签名CREATEEXTENSION[IFNOTEXISTS]extension_name[WITH][SCHEMAschema_name][VERSION version][FROMold_version][CASCADE]参数说明IF NOT EXISTS如果扩展已存在则不报错SCHEMA指定扩展安装的目标 schemaVERSION指定要安装的版本CASCADE自动安装依赖扩展示例-- 基本创建CREATEEXTENSION vector;-- 安全创建避免重复执行报错CREATEEXTENSIONIFNOTEXISTSvector;-- 删除扩展DROPEXTENSION vector;make 与 PG_CONFIG所属GNU make PostgreSQL 扩展构建系统方法签名make[target][PG_CONFIG/path/to/pg_config]常用 targettarget说明all默认编译扩展install安装扩展到 PostgreSQL 目录clean清理编译产物installcheck运行回归测试示例# 指定 PostgreSQL 安装路径编译makePG_CONFIG/usr/pgsql-17/bin/pg_config# 指定路径安装使用 sudo 时保留环境变量sudo--preserve-envPG_CONFIGmakeinstall项目难点与解决方案核心难点多版本 PostgreSQL 环境下的扩展编译路径问题。当系统中同时安装多个 PostgreSQL 版本时默认的pg_config可能指向错误的版本导致扩展安装到非预期的 PostgreSQL 实例中。解决方案通过PG_CONFIG环境变量或make命令行参数显式指定目标 PostgreSQL 的pg_config路径exportPG_CONFIG/usr/pgsql-17/bin/pg_configmakesudo--preserve-envPG_CONFIGmakeinstall广度该问题不仅存在于 pgvector而是所有需要编译的 PostgreSQL 扩展如 PostGIS、pg_stat_statements 等的共性问题。深度pg_config与PGXS是 PostgreSQL 扩展构建基础设施的核心组件。理解其工作机制——pg_config提供路径信息PGXS提供构建规则——是掌握所有 PostgreSQL 扩展编译的基础。复杂度源码编译安装涉及依赖包安装LLVM、Python 开发包、Git 等、环境变量配置、权限管理等多个环节对新手有一定门槛。pgenv等工具的出现正是为了降低这一复杂度。官方文档PostgreSQL pg_config 官方文档https://www.postgresql.org/docs/current/app-pgconfig.htmlPostgreSQL PGXS 扩展构建基础设施https://www.postgresql.org/docs/current/extend-pgxs.htmlpgvector GitHub 仓库https://github.com/pgvector/pgvectorpgvector PGXN 页面https://pgxn.org/dist/vector/参考链接pgvector 安装说明Linux/macOShttps://github.com/pgvector/pgvector#installationpgenv GitHub 仓库https://github.com/theory/pgenvPostgreSQL Yum 仓库https://yum.postgresql.org/PostgreSQL APT 仓库https://apt.postgresql.org/总结本文系统介绍了 pgvector 扩展的三种安装方式pgenv一键安装适用于快速部署和开发测试源码编译安装最为灵活通用适合生产环境和指定版本需求RPM 包安装适用于企业级离线部署场景。源码编译安装的核心在于正确配置pg_config路径——pg_config是 PostgreSQL 提供的配置信息查询工具扩展的Makefile通过PGXS机制调用它来获取头文件、库文件路径等编译参数。当系统存在多个 PostgreSQL 版本或使用sudo导致环境变量丢失时需通过PG_CONFIG变量显式指定路径。无论采用哪种安装方式最后都需在目标数据库中执行CREATE EXTENSION vector来启用扩展。掌握pg_config与PGXS的工作原理是理解和解决所有 PostgreSQL 扩展编译问题的基础。
PostgreSQL笔记42: pgvector扩展安装与配置完全指南
概述pgvector 是 PostgreSQL 官方生态中推荐的向量相似性搜索扩展支持高维向量的存储、相似度计算以及向量索引结构。在使用 pgvector 之前需要完成扩展的安装与基本配置。本文基于 PostgreSQL 17 环境pgvector 支持 PostgreSQL 13 及以上版本系统介绍三种主流的 pgvector 安装方式pgenv一键安装、源码编译安装以及 RPM 包安装并重点剖析源码安装过程中常见的pg_config路径问题和权限问题。纲要pgvector扩展概述功能特性适用版本安装方式对比pgenv一键安装源码编译安装RPM 包安装pg_config与PGXS构建基础设施pg_config的作用PGXS构建系统多 PostgreSQL 版本环境下的路径指定权限问题与解决方案扩展启用与验证vector数据类型基础使用pgvector 扩展概述pgvector 是 PostgreSQL 的向量相似性搜索扩展由 pgvector/pgvector 开源项目维护。其核心能力包括精确与近似最近邻搜索支持精确搜索和基于索引的近似搜索多精度向量类型单精度 (vector)、半精度 (halfvec)、二进制 (bit)、稀疏向量 (sparsevec)多种距离函数L2 距离 (-)、内积 (#)、余弦距离 ()、L1 距离 ()、汉明距离 (~)、Jaccard 距离 (%)ACID 兼容与 PostgreSQL 事务机制完全兼容pgvector 支持 PostgreSQL 13 及以上版本。安装方式对比安装 pgvector 主要有三种方式适用不同场景安装方式适用场景优点缺点pgenv一键安装快速部署、开发测试自动处理依赖命令简洁需要网络版本可能滞后源码编译安装生产环境、指定版本最灵活可指定任意版本需手动处理依赖和路径RPM 包安装企业生产、离线环境符合企业运维规范依赖处理较繁琐pgenv 一键安装pgenv是一个 PostgreSQL 二进制版本管理工具由社区开发者维护旨在帮助用户快速安装和管理 PostgreSQL 及其扩展。适用版本pgenv 已适配 PostgreSQL 13 至 17。安装步骤# 1. 添加 pgenv 仓库sudopgenv repoaddPGDG# 2. 安装 pgvector 扩展pgenv extinstallpgvectorpgenv会自动处理所有依赖项如 LLVM、Python 开发包等无需手动解决依赖关系。这对于新手用户或不希望折腾依赖环境的场景尤为推荐。源码编译安装源码编译安装是最通用、最灵活的方式适用于需要安装特定版本或无法使用包管理器的场景。标准编译步骤参照 pgvector 官方文档# 1. 获取源码cd/tmpgitclone--branchv0.8.6 https://github.com/pgvector/pgvector.gitcdpgvector# 2. 编译make# 3. 安装可能需要 sudomakeinstallpg_config 的作用源码编译过程中make命令需要知道 PostgreSQL 的安装位置、头文件路径、库文件路径等信息。pg_config是 PostgreSQL 提供的配置信息查询工具它打印当前安装的 PostgreSQL 版本的配置参数。pg_config的核心输出包括--bindir用户可执行文件位置--includedir头文件位置--libdir库文件位置--pgxs扩展 makefile 位置在扩展的Makefile中通过PGXSPostgreSQL Extension Build Infrastructure机制调用pg_config来获取这些信息PG_CONFIG pg_config PGXS : $(shell $(PG_CONFIG) --pgxs) include $(PGXS)常见问题pg_config not found当执行make install时如果系统提示pg_config: command not found说明当前环境找不到pg_config命令。原因分析PostgreSQL 的开发包postgresql-server-dev未安装pg_config不在PATH环境变量中使用sudo时超级用户环境与普通用户环境不同解决方案一安装开发包对于 Debian/Ubuntusudoaptinstallpostgresql-server-dev-17对于 RHEL/Rocky Linuxsudoyuminstallpostgresql17-devel解决方案二指定 PG_CONFIG 路径如果系统中有多个 PostgreSQL 版本或pg_config不在PATH中可以在make命令中直接指定makePG_CONFIG/usr/pgsql-17/bin/pg_configsudomakeinstallPG_CONFIG/usr/pgsql-17/bin/pg_config解决方案三使用 sudo 时保留环境变量当需要使用sudo执行make install时sudo默认会重置环境变量导致pg_config不可用。解决方案sudo--preserve-envPG_CONFIGmakeinstall安装验证源码编译安装完成后pgvector 的动态库文件.so会安装到 PostgreSQL 的lib目录控制文件.control和 SQL 脚本会安装到share/extension目录。# 查看动态库ls$PGHOME/lib/vector.so# 查看控制文件ls$PGHOME/share/extension/vector.controlRPM 包安装RPM 包安装适用于企业生产环境特别是无法联网或需要严格版本管控的场景。从 PostgreSQL Yum 仓库安装# RHEL/Rocky Linuxsudoyuminstallpgvector_17# 或sudodnfinstallpgvector_17RPM 安装方式的挑战在于需要提前解决所有依赖项包括 LLVM、Git 以及 PostgreSQL 开发包等。扩展启用与验证无论采用哪种安装方式最后都需要在数据库中启用扩展。连接到目标数据库后执行-- 创建 pgvector 扩展CREATEEXTENSIONIFNOTEXISTSvector;-- 验证安装SELECTextname,extversionFROMpg_extensionWHEREextnamevector;执行结果示例extname | extversion --------------------- vector | 0.8.6 (1 row)注意CREATE EXTENSION命令需要在每个需要使用 pgvector 的数据库中分别执行。vector 数据类型基础使用安装并启用扩展后即可使用vector数据类型-- 创建包含向量列的表3 维向量CREATETABLEitems(id BIGSERIALPRIMARYKEY,embedding vector(3));-- 插入向量数据INSERTINTOitems(embedding)VALUES([1,2,3]),([4,5,6]);-- L2 距离最近邻查询SELECT*FROMitemsORDERBYembedding-[3,1,2]LIMIT5;API 速览本节梳理 pgvector 安装与使用过程中涉及的核心 API 与命令。pg_config所属PostgreSQL 核心工具方法签名pg_config[option...]常用选项选项说明--bindir用户可执行文件位置--includedirC 头文件位置--libdir库文件位置--pgxs扩展 makefile 位置--configure构建时的 configure 选项示例# 查看所有配置pg_config# 查看 pgxs 路径pg_config--pgxs# 输出示例: /usr/pgsql-17/lib/pgxs/src/makefiles/pgxs.mkCREATE EXTENSION所属PostgreSQL SQL 命令方法签名CREATEEXTENSION[IFNOTEXISTS]extension_name[WITH][SCHEMAschema_name][VERSION version][FROMold_version][CASCADE]参数说明IF NOT EXISTS如果扩展已存在则不报错SCHEMA指定扩展安装的目标 schemaVERSION指定要安装的版本CASCADE自动安装依赖扩展示例-- 基本创建CREATEEXTENSION vector;-- 安全创建避免重复执行报错CREATEEXTENSIONIFNOTEXISTSvector;-- 删除扩展DROPEXTENSION vector;make 与 PG_CONFIG所属GNU make PostgreSQL 扩展构建系统方法签名make[target][PG_CONFIG/path/to/pg_config]常用 targettarget说明all默认编译扩展install安装扩展到 PostgreSQL 目录clean清理编译产物installcheck运行回归测试示例# 指定 PostgreSQL 安装路径编译makePG_CONFIG/usr/pgsql-17/bin/pg_config# 指定路径安装使用 sudo 时保留环境变量sudo--preserve-envPG_CONFIGmakeinstall项目难点与解决方案核心难点多版本 PostgreSQL 环境下的扩展编译路径问题。当系统中同时安装多个 PostgreSQL 版本时默认的pg_config可能指向错误的版本导致扩展安装到非预期的 PostgreSQL 实例中。解决方案通过PG_CONFIG环境变量或make命令行参数显式指定目标 PostgreSQL 的pg_config路径exportPG_CONFIG/usr/pgsql-17/bin/pg_configmakesudo--preserve-envPG_CONFIGmakeinstall广度该问题不仅存在于 pgvector而是所有需要编译的 PostgreSQL 扩展如 PostGIS、pg_stat_statements 等的共性问题。深度pg_config与PGXS是 PostgreSQL 扩展构建基础设施的核心组件。理解其工作机制——pg_config提供路径信息PGXS提供构建规则——是掌握所有 PostgreSQL 扩展编译的基础。复杂度源码编译安装涉及依赖包安装LLVM、Python 开发包、Git 等、环境变量配置、权限管理等多个环节对新手有一定门槛。pgenv等工具的出现正是为了降低这一复杂度。官方文档PostgreSQL pg_config 官方文档https://www.postgresql.org/docs/current/app-pgconfig.htmlPostgreSQL PGXS 扩展构建基础设施https://www.postgresql.org/docs/current/extend-pgxs.htmlpgvector GitHub 仓库https://github.com/pgvector/pgvectorpgvector PGXN 页面https://pgxn.org/dist/vector/参考链接pgvector 安装说明Linux/macOShttps://github.com/pgvector/pgvector#installationpgenv GitHub 仓库https://github.com/theory/pgenvPostgreSQL Yum 仓库https://yum.postgresql.org/PostgreSQL APT 仓库https://apt.postgresql.org/总结本文系统介绍了 pgvector 扩展的三种安装方式pgenv一键安装适用于快速部署和开发测试源码编译安装最为灵活通用适合生产环境和指定版本需求RPM 包安装适用于企业级离线部署场景。源码编译安装的核心在于正确配置pg_config路径——pg_config是 PostgreSQL 提供的配置信息查询工具扩展的Makefile通过PGXS机制调用它来获取头文件、库文件路径等编译参数。当系统存在多个 PostgreSQL 版本或使用sudo导致环境变量丢失时需通过PG_CONFIG变量显式指定路径。无论采用哪种安装方式最后都需在目标数据库中执行CREATE EXTENSION vector来启用扩展。掌握pg_config与PGXS的工作原理是理解和解决所有 PostgreSQL 扩展编译问题的基础。