PostgreSQL笔记42: pgvector扩展安装与配置完全指南

Wang's Blog

墨衍会员 · AI 创作全网分发码龄12年

关注

原创最新推荐文章于 2026-10-30 17:27:52 发布 695 阅读 AI 写同款· GEO 优化 ›

Pgvector的安装向量化数据的存储，可以为 PostgreSQL 安装 vector 扩展来存储向量化数据。阅读详情

概述

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 仓库
sudo pgenv repo add PGDG

# 2. 安装 pgvector 扩展
pgenv ext install pgvector

pgenv 会自动处理所有依赖项（如 LLVM、Python 开发包等），无需手动解决依赖关系。这对于新手用户或不希望折腾依赖环境的场景尤为推荐。

源码编译安装

源码编译安装是最通用、最灵活的方式，适用于需要安装特定版本或无法使用包管理器的场景。

标准编译步骤

参照 pgvector 官方文档：

# 1. 获取源码
cd /tmp
git clone --branch v0.8.6 https://github.com/pgvector/pgvector.git
cd pgvector

# 2. 编译
make

# 3. 安装（可能需要 sudo）
make install

pg_config 的作用

源码编译过程中，make 命令需要知道 PostgreSQL 的安装位置、头文件路径、库文件路径等信息。pg_config 是 PostgreSQL 提供的配置信息查询工具，它打印当前安装的 PostgreSQL 版本的配置参数。

pg_config 的核心输出包括：

--bindir：用户可执行文件位置
--includedir：头文件位置
--libdir：库文件位置
--pgxs：扩展 makefile 位置

在扩展的 Makefile 中，通过 PGXS（PostgreSQL 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/Ubuntu：

sudo apt install postgresql-server-dev-17

对于 RHEL/Rocky Linux：

sudo yum install postgresql17-devel

解决方案二：指定 PG_CONFIG 路径

如果系统中有多个 PostgreSQL 版本，或 pg_config 不在 PATH 中，可以在 make 命令中直接指定：

make PG_CONFIG=/usr/pgsql-17/bin/pg_config
sudo make install PG_CONFIG=/usr/pgsql-17/bin/pg_config

解决方案三：使用 sudo 时保留环境变量

当需要使用 sudo 执行 make install 时，sudo 默认会重置环境变量，导致 pg_config 不可用。解决方案：

sudo --preserve-env=PG_CONFIG make install

安装验证

源码编译安装完成后，pgvector 的动态库文件（.so）会安装到 PostgreSQL 的 lib 目录，控制文件（.control）和 SQL 脚本会安装到 share/extension 目录。

# 查看动态库
ls $PGHOME/lib/vector.so

# 查看控制文件
ls $PGHOME/share/extension/vector.control

RPM 包安装

RPM 包安装适用于企业生产环境，特别是无法联网或需要严格版本管控的场景。

从 PostgreSQL Yum 仓库安装：

# RHEL/Rocky Linux
sudo yum install pgvector_17
# 或
sudo dnf install pgvector_17

RPM 安装方式的挑战在于需要提前解决所有依赖项，包括 LLVM、Git 以及 PostgreSQL 开发包等。

扩展启用与验证

无论采用哪种安装方式，最后都需要在数据库中启用扩展。

连接到目标数据库后执行：

-- 创建 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

-- 验证安装
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

执行结果示例：

 extname | extversion
---------+------------
 vector  | 0.8.6
(1 row)

注意：CREATE EXTENSION 命令需要在每个需要使用 pgvector 的数据库中分别执行。

vector 数据类型基础使用

安装并启用扩展后，即可使用 vector 数据类型：

-- 创建包含向量列的表（3 维向量）
CREATE TABLE items (
    id BIGSERIAL PRIMARY KEY,
    embedding vector(3)
);

-- 插入向量数据
INSERT INTO items (embedding) VALUES
    ('[1,2,3]'),
    ('[4,5,6]');

-- L2 距离最近邻查询
SELECT * FROM items
ORDER BY embedding <-> '[3,1,2]'
LIMIT 5;

API 速览

本节梳理 pgvector 安装与使用过程中涉及的核心 API 与命令。

pg_config

所属：PostgreSQL 核心工具

方法签名：

pg_config [option...]

常用选项：

选项	说明
`--bindir`	用户可执行文件位置
`--includedir`	C 头文件位置
`--libdir`	库文件位置
`--pgxs`	扩展 makefile 位置
`--configure`	构建时的 configure 选项

示例：

# 查看所有配置
pg_config

# 查看 pgxs 路径
pg_config --pgxs
# 输出示例: /usr/pgsql-17/lib/pgxs/src/makefiles/pgxs.mk

CREATE EXTENSION

所属：PostgreSQL SQL 命令

方法签名：

CREATE EXTENSION [IF NOT EXISTS] extension_name
    [WITH] [SCHEMA schema_name]
    [VERSION version]
    [FROM old_version]
    [CASCADE]

参数说明：

IF NOT EXISTS：如果扩展已存在则不报错
SCHEMA：指定扩展安装的目标 schema
VERSION：指定要安装的版本
CASCADE：自动安装依赖扩展

示例：

-- 基本创建
CREATE EXTENSION vector;

-- 安全创建（避免重复执行报错）
CREATE EXTENSION IF NOT EXISTS vector;

-- 删除扩展
DROP EXTENSION vector;

make 与 PG_CONFIG

所属：GNU make + PostgreSQL 扩展构建系统

方法签名：

make [target] [PG_CONFIG=/path/to/pg_config]

常用 target：

target	说明
`all`（默认）	编译扩展
`install`	安装扩展到 PostgreSQL 目录
`clean`	清理编译产物
`installcheck`	运行回归测试

示例：

# 指定 PostgreSQL 安装路径编译
make PG_CONFIG=/usr/pgsql-17/bin/pg_config

# 指定路径安装（使用 sudo 时保留环境变量）
sudo --preserve-env=PG_CONFIG make install

项目难点与解决方案

核心难点

多版本 PostgreSQL 环境下的扩展编译路径问题。当系统中同时安装多个 PostgreSQL 版本时，默认的 pg_config 可能指向错误的版本，导致扩展安装到非预期的 PostgreSQL 实例中。

解决方案

通过 PG_CONFIG 环境变量或 make 命令行参数显式指定目标 PostgreSQL 的 pg_config 路径：

export PG_CONFIG=/usr/pgsql-17/bin/pg_config
make && sudo --preserve-env=PG_CONFIG make install

广度

该问题不仅存在于 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.html
PostgreSQL PGXS 扩展构建基础设施：https://www.postgresql.org/docs/current/extend-pgxs.html
pgvector GitHub 仓库：https://github.com/pgvector/pgvector
pgvector PGXN 页面：https://pgxn.org/dist/vector/

参考链接

pgvector 安装说明（Linux/macOS）：https://github.com/pgvector/pgvector#installation
pgenv GitHub 仓库：https://github.com/theory/pgenv
PostgreSQL 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 扩展编译问题的基础。