📦 一、pgvector 简介

• **定位：**PostgreSQL 的官方向量扩展（由 Andrew Kane 开发，已合并入 PG 官方生态）
• 核心能力：
  • 支持 稠密向量存储（vector(n) 类型）
  • 提供 相似度运算符：<->（L2）、<#>（内积）、<=>（余弦）
  • 支持 IVFFlat（v0.4+） 和 HNSW（PostgreSQL 16+ 原生支持）
  • 与 SQL 生态无缝融合（JOIN、事务、RBAC、JSONB、全文检索）
• 适用场景：
  • 已使用 PostgreSQL 的团队想低成本引入 RAG
  • 中小规模向量搜索（≤ 5000 万向量）
  • 需要 ACID 事务保障的 AI 应用

✅ 优势：零新系统引入、复用现有 DBA 技能、SQL 灵活查询
⚠️ 局限：超大规模（>1 亿）性能不如专用向量库（如 Qdrant/Milvus）

🚀 二、部署与安装

方式 1：Docker（开发/测试推荐）

# 使用预装 pgvector 的镜像（推荐 ankane/pgvector）
docker run -d \
  --name pgvector-db \
  -p 5432:5432 \
  -e POSTGRES_DB=rag_db \
  -e POSTGRES_USER=rag_user \
  -e POSTGRES_PASSWORD=secure_password_123 \
  -v $(pwd)/pgdata:/var/lib/postgresql/data \
  ankane/pgvector:0.7.4  # 包含 pgvector + pg_bm25（可选）

✅ 镜像已内置：

• PostgreSQL 16
• pgvector 0.7.4（支持 HNSW）
• 可选：pg_bm25（关键词检索）

方式 2：云托管（生产推荐）

云厂商	支持情况
AWS RDS	PostgreSQL 16+，需手动 CREATE EXTENSION vector;
Google Cloud SQL	支持（需启用 vector 扩展）
Supabase	默认启用 pgvector，开箱即用
Neon	Serverless PG，原生支持 pgvector
Azure Database for PostgreSQL	支持（Flexible Server）

💡 Supabase 示例：注册后直接在 SQL Editor 执行 CREATE EXTENSION vector;

方式 3：源码编译（高级用户）

适用于自建 PostgreSQL 服务器：

# 安装依赖（Ubuntu）
sudo apt-get install postgresql-server-dev-16 build-essential

# 下载 pgvector
git clone https://github.com/pgvector/pgvector.git
cd pgvector

# 编译安装
make
sudo make install

# 登录 PostgreSQL 启用扩展
psql -U postgres -d rag_db -c "CREATE EXTENSION vector;"

🔒 确保 postgresql.conf 中 shared_preload_libraries 不冲突

🔧 三、验证安装

连接数据库并测试：

-- 启用扩展（首次）
CREATE EXTENSION IF NOT EXISTS vector;

-- 创建测试表
CREATE TABLE items (
  id BIGSERIAL PRIMARY KEY,
  content TEXT,
  embedding VECTOR(1536)  -- OpenAI text-embedding-3-small 维度
);

-- 插入示例向量
INSERT INTO items (content, embedding)
VALUES ('Hello world', '[0.1, 0.2, 0.3, ..., 0.5]');

-- 相似度搜索（余弦距离）
SELECT id, content, embedding <=> '[0.1, 0.2, 0.3, ..., 0.6]' AS distance
FROM items
ORDER BY distance
LIMIT 5;

✅ 若无报错，说明 pgvector 已成功启用。

🌟 四、高性能索引（关键！）

1. IVFFlat 索引（兼容所有 PG 版本）

适合中小数据集（< 1000 万）：

-- 创建 IVFFlat 索引（余弦距离）
CREATE INDEX ON items 
USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 100);  -- 建议 lists = sqrt(总行数)

⚠️ IVFFlat 是近似索引，lists 越大精度越高、构建越慢

2. HNSW 索引（PostgreSQL 16+ 推荐）

更高精度 & 更低延迟：

-- 创建 HNSW 索引（PG 16+ 原生支持）
CREATE INDEX ON items 
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

参数说明：

• m：每个节点的连接数（默认 16，范围 2~100）
• ef_construction：构建时的候选集大小（默认 64，越大越准）

📌 生产建议：

• 数据量 < 100 万：m=16, ef_construction=64
• 数据量 > 100 万：m=24, ef_construction=128

💻 五、Python 应用集成

1. 原生 psycopg（推荐）

import psycopg
from pgvector.psycopg import register_vector

# 连接数据库
conn = psycopg.connect(
    dbname="rag_db",
    user="rag_user",
    password="secure_password_123",
    host="localhost"
)

# 注册 vector 类型
register_vector(conn)

# 插入向量
embedding = [0.1] * 1536  # 示例向量
with conn.cursor() as cur:
    cur.execute(
        "INSERT INTO items (content, embedding) VALUES (%s, %s)",
        ("Sample document", embedding)
    )
    conn.commit()

# 相似度搜索
query_embedding = [0.11] * 1536
with conn.cursor() as cur:
    cur.execute("""
        SELECT id, content, embedding <=> %s AS distance
        FROM items
        ORDER BY distance
        LIMIT 5
    """, (query_embedding,))
    results = cur.fetchall()
    for row in results:
        print(row[1], "distance:", row[2])

✅ 安装依赖：

pip install psycopg[binary] pgvector

2. LangChain 集成（RAG 场景）

from langchain_postgres import PGVector
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document

# 连接字符串（psycopg 格式）
CONNECTION_STRING = "postgresql+psycopg://rag_user:secure_password_123@localhost:5432/rag_db"

# 初始化向量存储
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vector_store = PGVector(
    embeddings=embeddings,
    collection_name="langchain_docs",  # 自动创建表
    connection=CONNECTION_STRING,
    use_jsonb=True,  # 元数据存 JSONB 字段
    pre_delete_collection=False  # 是否清空旧数据
)

# 添加文档
docs = [
    Document(page_content="pgvector 让 PostgreSQL 支持向量搜索", metadata={"source": "blog"})
]
vector_store.add_documents(docs)

# 检索（支持距离阈值）
results = vector_store.similarity_search_with_score(
    "PostgreSQL 向量扩展",
    k=2,
    distance_threshold=0.5  # 余弦距离 < 0.5
)
for doc, score in results:
    print(f"Content: {doc.page_content}, Score: {score}")

✅ 安装：pip install langchain-postgres pgvector

3. 与 SQLAlchemy / Django 集成

• SQLAlchemy：使用 VECTOR 类型（via pgvector.sqlalchemy.Vector）
• Django：使用 django-pgvector 包

示例（Django）：

# models.py
from pgvector.django import VectorField

class Item(models.Model):
    content = models.TextField()
    embedding = VectorField(dimensions=1536)

⚙️ 六、性能调优（生产必备）

优化项	建议
work_mem	SET work_mem = ‘256MB’;（提升排序性能）
maintenance_work_mem	1GB（加速索引构建）
表分区	按租户/时间分区，避免单表过大
HNSW 参数	m=24, ef_construction=128（高精度）
并发控制	使用连接池（如 PgBouncer）
SSD 存储	必须使用 NVMe SSD

查看索引是否生效：

EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM items ORDER BY embedding <=> '[...]' LIMIT 5;

✅ 输出中应包含 Index Scan using …，而非 Seq Scan

🔒 七、安全、备份与监控

1. 安全

• 使用独立 DB 用户（最小权限原则）
• 启用 SSL 连接（云厂商默认开启）
• 向量列本身无敏感信息，但业务数据需加密（TDE 或应用层）
  2. 备份
• 使用 pg_dump / pg_basebackup（与普通 PG 表一致）
• 逻辑备份示例：

pg_dump -U rag_user -d rag_db -t items > items_backup.sql

3. 监控

• 指标：
  • 查询延迟（Prometheus + pg_exporter）
  • 索引大小：SELECT pg_size_pretty(pg_relation_size(‘items_embedding_idx’));
• 慢查询日志：开启 log_min_duration_statement = 1000

🛠 八、常见问题排查

❌ 问题1：type “vector” does not exist

• 未执行 CREATE EXTENSION vector;
• 扩展未正确安装（检查 pg_config --sharedir）

❌ 问题2：索引未生效（全表扫描）

• 未 ANALYZE 表：ANALYZE items;
• 向量维度不一致（必须固定维度）

❌ 问题3：插入慢

• 批量插入（executemany 或 COPY）
• 临时关闭索引 → 导入 → 重建索引

❌ 问题4：HNSW 报错（PG < 16）

• HNSW 仅 PostgreSQL 16+ 原生支持
• 降级使用 IVFFlat

📚 九、官方资源

GitHub：https://github.com/pgvector/pgvector
文档：https://github.com/pgvector/pgvector#readme
论文：pgvector: Efficient Vector Similarity Search in PostgreSQL（2023）

✅ 十、总结：何时选择 pgvector？

场景	是否推荐 pgvector
已有 PostgreSQL，不想引入新系统	✅ 强烈推荐
数据量 < 5000 万向量	✅
需要 SQL JOIN / 事务 / RBAC	✅
超大规模（>1 亿）或极致低延迟	❌ → 选 Qdrant / Milvus
需要混合搜索（关键词+向量）	⚠️ 需配合 tsvector 或 pg_bm25

💡 2025 年趋势：
pgvector 正成为“务实派”RAG 的默认选择——尤其在 SaaS、中小企业和快速迭代项目中。