pgvector 安装与部署完全指南

目录

• 为什么 pgvector 这么好装
• 方式一：Docker（推荐新手首选）
• 方式二：在现有 PostgreSQL 上安装
• 方式三：云托管方案对比
• 验证安装是否成功
• 常见问题与排错
• 生产环境部署建议

为什么 pgvector 这么好装

在向量数据库的世界里，Milvus 需要你折腾一堆组件（etcd、MinIO、Pulsar……），Qdrant 虽然简单但也是个独立进程，Weaviate 更是得配齐一套生态。

pgvector 的安装是这个领域里最短的故事。

它是 PostgreSQL 的一个扩展（extension），就像给手机装个 App 一样。PostgreSQL 的扩展机制非常成熟——Oracle 有它的插件，MySQL 有 UDF，PostgreSQL 有 extension，这是数据库世界里扩展能力最优雅的机制之一。

所以：

• 已有 PostgreSQL：两条命令，五分钟搞定
• 没有 PostgreSQL：一个 Docker 镜像，三分钟搞定
• 不想自己运维：Supabase、AWS RDS、Azure 都内置支持，点几下鼠标

这就是 pgvector 相对于独立向量数据库的核心优势之一——可复用现有 PostgreSQL 基础设施，但仍需评估新增存储、索引和计算成本。

方式一：Docker（推荐新手首选）

Docker 是最简单、最干净的方式。你不需要关心操作系统差异，不需要编译，不需要配置系统依赖——镜像里全包了。

1.1 最快的一行命令

如果你只是想试试效果，一行命令就够：

docker run -d \
  --name pgvector-dev \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=vectordb \
  -p 5432:5432 \
  pgvector/pgvector:pg17

等容器启动后，连接进去：

docker exec -it pgvector-dev psql -U postgres -d vectordb

然后启用扩展：

CREATE EXTENSION IF NOT EXISTS vector;
-- CREATE EXTENSION
-- 就这一句，搞定了

验证一下：

SELECT extversion FROM pg_extension WHERE extname = 'vector';
--  extversion
-- ------------
--  0.8.0
-- (1 row)

看到版本号，说明安装成功。

1.2 Docker Compose 部署配置示例

实际项目里，你不会只跑一个裸容器。你需要数据持久化、健康检查、初始化脚本、资源限制。下面是一份部署配置示例；其生产适用性取决于网络隔离、权限、资源预算、备份恢复及实际负载测试：

项目目录结构（根目录：my-pgvector-project/）：

.env 文件（存放敏感配置）：

# 此用户是镜像初始化时创建的数据库管理角色，不是受限应用账号；生产应用应另建最小权限角色
POSTGRES_USER=appuser
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=vectordb
POSTGRES_PORT=5432

init/01-init.sql（初始化脚本，容器首次启动时自动执行）：

-- 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

-- 启用 pg_trgm（用于文本模糊搜索，混合检索时很有用）
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- 创建一个示例 schema（可选，用于组织表结构）
CREATE SCHEMA IF NOT EXISTS app;

-- 验证安装
DO $$
BEGIN
  IF EXISTS (
    SELECT 1 FROM pg_extension WHERE extname = 'vector'
  ) THEN
    RAISE NOTICE 'pgvector 安装成功，版本: %',
      (SELECT extversion FROM pg_extension WHERE extname = 'vector');
  ELSE
    RAISE EXCEPTION 'pgvector 安装失败！';
  END IF;
END;
$$;

docker-compose.yml（部署配置示例，不构成完整生产方案）：

version: "3.8"

services:
  pgvector:
    image: pgvector/pgvector:pg17
    container_name: pgvector-app
    restart: unless-stopped

    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
      # 性能调优参数（通过环境变量传给 PostgreSQL）
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"

    ports:
      - "${POSTGRES_PORT:-5432}:5432"

    volumes:
      # 数据持久化：容器删了数据还在
      - pgvector_data:/var/lib/postgresql/data
      # 初始化脚本：首次启动时按文件名顺序执行
      - ./init:/docker-entrypoint-initdb.d:ro

    # PostgreSQL 性能调优参数
    command: >
      postgres
      -c shared_buffers=256MB
      -c effective_cache_size=1GB
      -c maintenance_work_mem=128MB
      -c work_mem=16MB
      -c max_connections=100
      -c checkpoint_completion_target=0.9
      -c wal_buffers=16MB
      -c random_page_cost=1.1

    # 健康检查
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

    # 资源限制（根据实际服务器调整）
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

    # 日志配置
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"

volumes:
  pgvector_data:
    driver: local

启动命令：

# 启动（后台运行）
docker compose up -d

# 查看日志
docker compose logs -f pgvector

# 等待健康检查通过后，验证安装
docker compose exec pgvector psql -U appuser -d vectordb -c "SELECT extversion FROM pg_extension WHERE extname = 'vector';"

1.3 多版本 PostgreSQL 的 Docker 镜像

pgvector 官方为每个主流 PostgreSQL 版本提供了对应镜像：

选版本的原则：新项目用最新稳定版（17），老项目保持现有版本。

方式二：在现有 PostgreSQL 上安装

如果你的服务器上已经有 PostgreSQL，不需要 Docker，直接装扩展就行。

2.1 Ubuntu / Debian 系统

这是最常见的 Linux 生产环境。PostgreSQL 官方提供了 apt 仓库，强烈建议用官方源而不是系统自带的老版本。

Step 1：确认你的 PostgreSQL 版本

psql --version
# psql (PostgreSQL) 16.4

Step 2：安装 pgvector

# 安装构建依赖
sudo apt-get update
sudo apt-get install -y \
  postgresql-server-dev-16 \
  build-essential \
  git

# 克隆 pgvector 源码（推荐指定版本）
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector

# 编译并安装
make
sudo make install

# 清理（可选）
cd ..
rm -rf pgvector

Step 3：在数据库中启用扩展

# 连接到你的数据库
psql -U postgres -d your_database

# 启用 pgvector
CREATE EXTENSION IF NOT EXISTS vector;

# 验证
SELECT extversion FROM pg_extension WHERE extname = 'vector';

# 添加 PostgreSQL 官方 apt 源
sudo apt-get install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# 安装 pgvector（把 16 替换成你的版本）
sudo apt-get install -y postgresql-16-pgvector

# 然后在数据库里 CREATE EXTENSION IF NOT EXISTS vector; 就行了

2.2 macOS（本地开发环境）

macOS 上开发，有两种方式：Homebrew 或 Postgres.app。

方式 A：Homebrew（推荐）

# 如果你用 Homebrew 装的 PostgreSQL
brew install pgvector

# 连接数据库，启用扩展
psql -U $(whoami) -d your_database
CREATE EXTENSION IF NOT EXISTS vector;

就这一条，Homebrew 自动帮你处理了编译和安装的所有细节。

方式 B：从源码编译（适用于 Postgres.app 用户）

# 先找到 Postgres.app 的 pg_config 路径
# 一般在 /Applications/Postgres.app/Contents/Versions/latest/bin/
export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

# 克隆编译
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

# 连接数据库，启用扩展
psql your_database
CREATE EXTENSION IF NOT EXISTS vector;

验证 macOS 安装：

psql your_database -c "SELECT extversion FROM pg_extension WHERE extname = 'vector';"

2.3 CentOS / RHEL / Amazon Linux

企业环境里 CentOS/RHEL 还是很常见的。

# 安装依赖
sudo yum install -y \
  postgresql16-devel \
  gcc \
  make \
  git

# 设置 PATH（让 make install 找到正确的 pg_config）
export PATH=/usr/pgsql-16/bin:$PATH

# 克隆编译安装
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

对于 RHEL 系，也可以用 PGDG（PostgreSQL Global Development Group）的 yum 仓库安装预编译包：

# 以 PostgreSQL 16 为例
sudo yum install -y pgvector_16

# 然后连接数据库启用
psql -U postgres -d your_db -c "CREATE EXTENSION IF NOT EXISTS vector;"

2.4 Windows（不推荐生产，但本地开发可用）

Windows 下最省事的方式还是 Docker，但如果你坚持原生安装：

1. 从 pgvector Releases 下载对应 Windows 的预编译包
2. 解压到 PostgreSQL 的安装目录（通常是 C:\Program Files\PostgreSQL\16\）
   • 把 vector.dll 复制到 lib/ 目录
   • 把 vector.control、vector--*.sql 复制到 share/extension/ 目录
3. 在数据库里 CREATE EXTENSION IF NOT EXISTS vector;

方式三：云托管方案对比

如果你不想管服务器，直接用云托管的 PostgreSQL。主流云厂商的支持情况：

3.1 各平台对比总览

3.2 Supabase：最简单的选择

Supabase 是对开发者最友好的选项——它本质上就是托管的 PostgreSQL + 一堆开发工具，而且 pgvector 是默认内置、默认启用的。

-- 在 Supabase SQL Editor 里，直接用
-- 不需要 CREATE EXTENSION，已经装好了

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

-- 建个向量表试试
CREATE TABLE documents (
  id BIGSERIAL PRIMARY KEY,
  content TEXT,
  embedding VECTOR(1536)
);

免费套餐有 500MB 数据库空间，够玩一阵子。生产项目按 Pro 套餐计费（25 美元/月起）。

Supabase 的特别优势：

• 自动生成 REST API
• 内置认证和 RLS（Row Level Security）
• Dashboard 可以直接查询和管理数据
• pgvector 和业务数据在同一个库，JOIN 查询无缝衔接

3.3 AWS RDS：企业首选

如果你的团队已经在 AWS 上，RDS for PostgreSQL 是最自然的选择。

启用步骤：

1. 确认目标实例提供 vector 扩展，且连接角色具有启用权限：

   SELECT * FROM pg_available_extensions WHERE name = 'vector';
   

2. 无需仅为 pgvector 添加 shared_preload_libraries 或重启实例。

3. 连接目标数据库，启用扩展：

   CREATE EXTENSION IF NOT EXISTS vector;
   

RDS 的 terraform 配置示例（基础设施即代码）：

resource "aws_db_parameter_group" "pgvector" {
  name   = "pgvector-params"
  family = "postgres16"

  # pgvector 不需要 shared_preload_libraries，
  # 它是纯 extension，不是后台进程
  # 直接 CREATE EXTENSION 即可
}

resource "aws_db_instance" "main" {
  identifier     = "my-pgvector-db"
  engine         = "postgres"
  engine_version = "16.4"
  instance_class = "db.t3.medium"

  # ... 其他配置
  parameter_group_name = aws_db_parameter_group.pgvector.name

  # 实例可连接后，另行通过 SQL 客户端或部署流程执行 CREATE EXTENSION；此配置未实现数据库初始化
}

3.4 Azure Database for PostgreSQL

Azure 的启用方式稍有不同，需要在"扩展白名单"里先添加 vector：

1. 在 Azure 门户 → PostgreSQL 服务器 → 服务器参数
2. 搜索 azure.extensions
3. 在值里添加 VECTOR（大写）
4. 保存，等待生效（不需要重启）
5. 连接数据库：CREATE EXTENSION IF NOT EXISTS vector;

-- Azure 上启用 pgvector
CREATE EXTENSION IF NOT EXISTS vector;

-- 验证
SELECT * FROM pg_available_extensions WHERE name = 'vector';

3.5 Neon：Serverless PostgreSQL

Neon 是近年来很受关注的 Serverless PostgreSQL 服务，特别适合用量不稳定的场景（比如个人项目、低频访问）。

• 冷启动时间：约 0.5-2 秒（不活跃时会自动暂停）
• pgvector 支持：内置，直接用
• 计费：按计算时间和存储计费，空闲时不收费

-- Neon 上同样直接使用
CREATE EXTENSION IF NOT EXISTS vector;

验证安装是否成功

不管用哪种方式安装，最终都需要验证。下面是一套完整的验证脚本：

4.1 基础验证

-- 1. 确认扩展已安装
SELECT
  name,
  default_version,
  installed_version,
  comment
FROM pg_available_extensions
WHERE name = 'vector';

-- 期望输出：
--  name  | default_version | installed_version |         comment
-- -------+-----------------+-------------------+-------------------------
--  vector | 0.8.0           | 0.8.0             | vector data type and ivfflat and hnsw access methods

-- 2. 确认当前数据库已启用
SELECT extversion FROM pg_extension WHERE extname = 'vector';
-- 输出版本号即为成功

4.2 功能验证（确认向量运算正常）

-- 创建测试表
CREATE TABLE IF NOT EXISTS _pgvector_test (
  id SERIAL PRIMARY KEY,
  embedding vector(3)
);

-- 插入测试数据
INSERT INTO _pgvector_test (embedding) VALUES
  ('[1.0, 0.0, 0.0]'),
  ('[0.0, 1.0, 0.0]'),
  ('[0.0, 0.0, 1.0]'),
  ('[0.5, 0.5, 0.0]');

-- 测试向量相似度搜索（L2 距离）
SELECT
  id,
  embedding,
  embedding <-> '[1.0, 0.0, 0.0]' AS l2_distance
FROM _pgvector_test
ORDER BY l2_distance
LIMIT 3;

-- 期望输出（id=1 最近，距离为 0）：
--  id |  embedding   | l2_distance
-- ----+--------------+-------------
--   1 | [1,0,0]      | 0
--   4 | [0.5,0.5,0]  | 0.7071...
--   2 | [0,1,0]      | 1.4142...

-- 测试余弦距离（语义搜索常用）
SELECT
  id,
  embedding,
  1 - (embedding <=> '[1.0, 0.0, 0.0]') AS cosine_similarity
FROM _pgvector_test
ORDER BY cosine_similarity DESC
LIMIT 3;

-- 清理测试表
DROP TABLE _pgvector_test;

4.3 索引验证

-- 测试 HNSW 索引创建（pgvector 0.5.0+ 的核心功能）
CREATE TABLE IF NOT EXISTS _index_test (
  id SERIAL PRIMARY KEY,
  embedding vector(128)
);

-- 插入一些随机数据
INSERT INTO _index_test (embedding)
SELECT array_agg(random()::float4 ORDER BY dims.d)::vector(128)
FROM generate_series(1, 1000) AS samples(n)
CROSS JOIN generate_series(1, 128) AS dims(d)
GROUP BY samples.n;

-- 创建 HNSW 索引
CREATE INDEX ON _index_test
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

-- 确认索引创建成功
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = '_index_test';

-- 清理
DROP TABLE _index_test;

-- 如果以上都没报错，说明本次测试表与 HNSW 索引创建成功；不代表检索性能或生产可用性已验证
SELECT 'pgvector 安装验证通过！' AS status;

4.4 一键验证脚本

下面的脚本仅自动检查当前数据库中的 pgvector 扩展版本；向量运算和索引创建仍需执行前述功能验证：

#!/bin/bash
# verify-pgvector.sh
# 用法：./verify-pgvector.sh [host] [port] [user] [dbname]

HOST=${1:-localhost}
PORT=${2:-5432}
USER=${3:-postgres}
DB=${4:-postgres}

echo "正在验证 pgvector 安装..."
echo "连接：$USER@$HOST:$PORT/$DB"

RESULT=$(psql -h "$HOST" -p "$PORT" -U "$USER" -d "$DB" -t -c \
  "SELECT COALESCE((SELECT extversion FROM pg_extension WHERE extname = 'vector'), '未安装');" 2>&1)

if echo "$RESULT" | grep -q "未安装"; then
  echo "pgvector 未安装，请先执行：CREATE EXTENSION IF NOT EXISTS vector;"
  exit 1
elif echo "$RESULT" | grep -qE "^[[:space:]]*0\.[0-9]"; then
  VERSION=$(echo "$RESULT" | tr -d ' ')
  echo "pgvector 已安装，版本：$VERSION"
  echo "扩展版本检查通过；尚未验证向量运算和索引功能。"
  exit 0
else
  echo "无法确认安装状态，请手动检查"
  echo "输出：$RESULT"
  exit 2
fi

常见问题与排错

Q1：CREATE EXTENSION vector 报错 "could not open extension control file"

原因：pgvector 没有正确安装到 PostgreSQL 的 extension 目录。

排查步骤：

# 1. 找到 PostgreSQL 的 extension 目录
pg_config --sharedir
# 输出类似：/usr/share/postgresql/16

# 2. 检查 vector.control 是否存在
ls $(pg_config --sharedir)/extension/vector*
# 应该看到 vector.control、vector--0.8.0.sql 等文件

# 3. 如果没有，说明安装失败，重新执行安装步骤

Docker 场景下的排查：

# 确认镜像里包含 pgvector
docker exec pgvector-dev ls /usr/share/postgresql/17/extension/ | grep vector
# 应该看到 vector.control 等文件

Q2：Docker 容器启动后初始化脚本没有执行

原因：/docker-entrypoint-initdb.d/ 里的脚本只在数据卷为空时（即首次启动）执行。如果你的数据卷已经有数据，脚本不会重新执行。

解决方案：

# 方法 1：仅限可丢弃测试环境；删除数据卷会删除其中的数据库数据，保留数据时不要执行
docker compose down -v  # -v 参数会删除 volumes
docker compose up -d

# 方法 2：手动执行扩展创建
docker compose exec pgvector psql -U appuser -d vectordb -c "CREATE EXTENSION IF NOT EXISTS vector;"

Q3：vector 类型不认识，报 "type vector does not exist"

原因：pgvector 没有在当前数据库里启用（CREATE EXTENSION 是 per-database 的操作）。

解决方案：

-- 确认当前连接的数据库
SELECT current_database();

-- 在正确的数据库里启用
\c your_target_database
CREATE EXTENSION IF NOT EXISTS vector;

Q4：安装了多个 PostgreSQL 版本，make install 安装到了错误的版本

原因：pg_config 指向了错误的 PostgreSQL 版本。

解决方案：

# 查看当前 pg_config 指向哪里
which pg_config
pg_config --version

# 如果不对，显式指定 pg_config 路径
make PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config

Q5：RDS 上无法启用 pgvector

排查方向：检查目标实例是否提供 vector 扩展、当前连接的数据库以及连接角色的权限；不要将 shared_preload_libraries 参数组配置作为 pgvector 的必要条件。

排查：

-- 检查 RDS 版本
SELECT version();

-- 检查 pgvector 是否可用
SELECT * FROM pg_available_extensions WHERE name = 'vector';
-- 如果没有结果，说明这个 RDS 版本/区域暂不支持

Q6：性能异常，向量搜索很慢

这通常不是安装问题，而是没有创建索引。参考 第一个 pgvector 应用 里的索引创建部分。

生产环境部署建议

安装完成后，还有一些生产环境的注意事项：

6.1 PostgreSQL 配置调优

pgvector 的向量运算是内存密集型操作。以下参数需要根据实际情况调整：

-- 查看当前配置
SHOW work_mem;
SHOW maintenance_work_mem;
SHOW shared_buffers;

-- 建议值（在 postgresql.conf 或启动参数里设置）
-- work_mem：影响向量搜索和排序，建议 64MB-256MB
-- maintenance_work_mem：影响索引构建，建议 512MB-2GB
-- shared_buffers：总内存的 25%

在 postgresql.conf 中：

# pgvector 相关调优
work_mem = 64MB                    # 向量搜索内存
maintenance_work_mem = 1GB         # 索引构建内存（IVFFlat/HNSW 都需要）
shared_buffers = 4GB               # 总内存的 25%
effective_cache_size = 12GB        # 总内存的 75%（给查询优化器的提示）

# 并行查询（pgvector 0.6.0+ 支持并行向量扫描）
max_parallel_workers_per_gather = 4

6.2 数据备份策略

pgvector 的数据就是普通的 PostgreSQL 数据，用标准的备份工具就行：

# pg_dump 备份（含向量数据）
pg_dump -h localhost -U postgres -d vectordb \
  --format=custom \
  --file=vectordb_backup_$(date +%Y%m%d).dump

# 恢复
pg_restore -h localhost -U postgres -d vectordb_restore \
  vectordb_backup_20260311.dump

6.3 监控指标

-- 查看向量索引大小
SELECT
  schemaname,
  tablename,
  indexname,
  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size
FROM pg_stat_user_indexes
JOIN pg_indexes USING (schemaname, tablename, indexname)
WHERE indexdef LIKE '%hnsw%' OR indexdef LIKE '%ivfflat%';

-- 查看表的总大小（含向量数据）
SELECT
  table_name,
  pg_size_pretty(pg_total_relation_size(table_name::text)) AS total_size,
  pg_size_pretty(pg_relation_size(table_name::text)) AS table_size
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY pg_total_relation_size(table_name::text) DESC;

6.4 升级 pgvector

当 pgvector 发布新版本时，升级流程：

# 1. 安装新版本（重复安装步骤）
cd pgvector
git fetch
git checkout v0.8.0  # 换成目标版本
make
sudo make install

# 2. 在数据库里升级扩展（不需要重建表）
psql -U postgres -d your_database -c "ALTER EXTENSION vector UPDATE;"

# 3. 验证新版本
psql -U postgres -d your_database -c "SELECT extversion FROM pg_extension WHERE extname = 'vector';"

小结

pgvector 最大的魅力就在于这种无缝融入——你不需要新增一套基础设施，不需要学习新的运维体系，就可以获得工程级的向量搜索能力。

安装完成后，下一步是写你的第一个向量搜索应用：第一个 pgvector 应用 — 从零构建语义搜索。

延伸阅读

• pgvector 核心概念
• 向量与 Embedding 基础
• pgvector 数据类型与操作符
• 第一个 pgvector 应用
• 向量数据库选型指南

#pgvector #PostgreSQL #向量数据库 #安装部署 #Docker #RAG