PostgreSQL pgvector 向量数据库实战：从零搭建 AI 语义搜索系统

2026 年，几乎所有涉及 AI 的应用都需要向量检索能力——从 RAG（检索增强生成）到语义搜索，再到推荐系统。根据 Stack Overflow 2026 年开发者调查，超过 67% 的 AI 应用开发者在生产环境中使用向量数据库，而其中增长最快的方案不是 Pinecone 或 Milvus，而是 PostgreSQL 的 pgvector 扩展。原因很简单：大多数团队已经有了 PostgreSQL，加一个扩展就能获得向量检索能力，何乐而不为？

但 pgvector 真的能替代专用向量数据库吗？答案取决于你是否理解它的索引机制、性能边界和调优策略。本文将从实战角度出发，带你深入掌握 pgvector 的每一个关键细节。

🔧 一、pgvector 基础：安装、数据建模与基本操作

1.1 安装与启用

pgvector 作为 PostgreSQL 扩展安装，支持 PostgreSQL 12 及以上版本。在生产环境中，推荐使用最新稳定版（0.7+），因为它引入了 halfvec 类型和稀疏向量支持，显著降低了内存占用。

# Ubuntu/Debian 安装（以 PostgreSQL 16 为例）
sudo apt install postgresql-16-pgvector

# 或从源码编译
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

-- 在目标数据库中启用扩展
CREATE EXTENSION IF NOT EXISTS vector;

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

1.2 数据建模实战

向量检索的核心是选择合适的维度（Dimension）。不同 Embedding 模型输出的维度差异很大，选错维度会直接影响存储成本和检索性能。

⚠️ **警告：**维度一旦确定就很难更改。如果你的表有 1000 万条数据，修改维度意味着重新生成所有 Embedding 并全量更新。务必在项目初期就确定模型选择。

-- 创建文档向量表（以 1536 维为例）
CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    content     TEXT NOT NULL,
    metadata    JSONB DEFAULT '{}',
    embedding   vector(1536) NOT NULL,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    updated_at  TIMESTAMPTZ DEFAULT NOW()
);

-- 添加注释便于团队协作
COMMENT ON COLUMN documents.embedding IS 'text-embedding-3-small 模型生成的向量';
COMMENT ON COLUMN documents.metadata IS '自定义元数据，支持 JSONB 查询';

1.3 向量插入与基本查询

-- 插入向量数据（实际项目中向量由应用层生成）
INSERT INTO documents (title, content, embedding) VALUES
('PostgreSQL 入门指南', 'PostgreSQL 是世界上最先进的开源关系型数据库...', '[0.1, -0.3, 0.5, ...]'),
('pgvector 性能优化', '向量索引的选择直接影响查询性能...', '[0.2, -0.1, 0.8, ...]');

-- 余弦相似度查询（最常用）
SELECT id, title, 1 - (embedding <=> query_vec) AS similarity
FROM documents, (SELECT '[0.15, -0.25, 0.6, ...]'::vector AS query_vec) q
ORDER BY embedding <=> query_vec
LIMIT 10;

-- L2 距离查询（欧氏距离）
SELECT id, title, embedding <-> query_vec AS distance
FROM documents, (SELECT '[0.15, -0.25, 0.6, ...]'::vector AS query_vec) q
ORDER BY embedding <-> query_vec
LIMIT 10;

💡 **提示：**pgvector 提供三种距离运算符：<=>（余弦距离）、<->（L2 距离）、<#>（内积）。对于文本语义搜索，余弦距离是最常用的选择，因为它只关注方向而非大小。

🚀 二、索引策略：HNSW vs IVFFlat 深度对比

pgvector 的性能瓶颈在于索引选择。错误的索引配置可以让查询速度从毫秒级退化到秒级。2026 年的最佳实践已经非常明确：新项目首选 HNSW，IVFFlat 仅用于特殊场景。

2.1 HNSW 索引：生产环境首选

HNSW（Hierarchical Navigable Small World）是一种基于图的近似最近邻（ANN）算法。它构建一个多层图结构，从顶层的稀疏连接逐层向下搜索到密集连接的底层，实现对数级别的查询复杂度。

-- 创建 HNSW 索引（余弦距离）
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- 创建 HNSW 索引（L2 距离）
CREATE INDEX ON documents USING hnsw (embedding vector_l2_ops)
WITH (m = 16, ef_construction = 200);

m 和 ef_construction 两个参数直接影响索引质量：

📌 记住：ef_search 是运行时参数，不需要重建索引。你可以根据场景动态调整：对精度要求高的场景调大，对延迟敏感的场景调小。

-- 运行时调整搜索精度（当前会话生效）
SET hnsw.ef_search = 100;

-- 验证索引使用情况（EXPLAIN ANALYZE）
EXPLAIN ANALYZE
SELECT id, title
FROM documents
ORDER BY embedding <=> '[0.15, -0.25, 0.6, ...]'::vector
LIMIT 10;

-- 正确输出应包含 "Index Scan using documents_embedding_idx"
-- 如果是 "Seq Scan"，说明索引未被使用

2.2 IVFFlat 索引：特定场景下的选择

IVFFlat（Inverted File with Flat Compression）将向量空间划分为若干聚类（Voronoi cells），查询时只搜索最近的几个聚类。它的优势是索引构建速度快，适合数据频繁批量更新的场景。

-- 创建 IVFFlat 索引
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

⚠️ **警告：**IVFFlat 有一个致命限制——必须在有数据之后才能创建索引。如果表是空的，索引不会被使用。建议至少插入 1000 条数据后再创建索引。

下面是两种索引的全面对比：

2.3 跳过索引：暴力搜索的适用场景

对于小数据集（<10 万条），直接使用顺序扫描反而更快，因为省去了索引的开销。

-- 不创建任何索引，pgvector 自动使用顺序扫描
-- 10 万条 1536 维向量，查询延迟通常 < 50ms

-- 使用 matryoshka 维度截断降低计算量（pgvector 0.7+）
-- 先用低维度粗筛，再用全维度精排
SELECT id, title
FROM documents
ORDER BY embedding::halfvec(256) <=> '[...]'::halfvec(256)
LIMIT 100;

-- 在候选集中用全维度重排
SELECT id, title, 1 - (embedding <=> '[...]'::vector) AS similarity
FROM documents
WHERE id IN (候选 ID 列表)
ORDER BY embedding <=> '[...]'::vector
LIMIT 10;

💡 **提示：**pgvector 0.7+ 引入的 halfvec 类型使用 16 位浮点数代替 32 位，内存占用直接减半，精度损失几乎可以忽略。对于大多数文本检索场景，强烈推荐使用 halfvec。

🎯 三、生产级实战：混合检索与 RAG 集成

3.1 混合检索：向量 + 全文搜索

纯向量检索有一个明显短板：它不擅长精确匹配关键词。比如用户搜索 “pgvector 0.7 版本”，向量检索可能会返回关于 “数据库版本管理” 的结果。解决方案是混合检索——同时使用向量相似度和全文搜索，用 RRF（Reciprocal Rank Fusion）融合排序。

-- 创建全文搜索索引
ALTER TABLE documents ADD COLUMN fts tsvector
    GENERATED ALWAYS AS (to_tsvector('chinese', title || ' ' || content)) STORED;
CREATE INDEX ON documents USING gin(fts);

-- 混合检索函数（RRF 融合排序）
CREATE OR REPLACE FUNCTION hybrid_search(
    query_text TEXT,
    query_embedding VECTOR(1536),
    match_count INT DEFAULT 20,
    rrf_k INT DEFAULT 60
)
RETURNS TABLE(id BIGINT, title TEXT, score NUMERIC)
LANGUAGE plpgsql AS $$
BEGIN
    RETURN QUERY
    WITH vector_results AS (
        SELECT d.id, d.title,
               ROW_NUMBER() OVER (ORDER BY d.embedding <=> query_embedding) AS rank
        FROM documents d
        ORDER BY d.embedding <=> query_embedding
        LIMIT match_count * 3
    ),
    fts_results AS (
        SELECT d.id, d.title,
               ROW_NUMBER() OVER (ORDER BY ts_rank(d.fts, plainto_tsquery('chinese', query_text)) DESC) AS rank
        FROM documents d
        WHERE d.fts @@ plainto_tsquery('chinese', query_text)
        LIMIT match_count * 3
    ),
    combined AS (
        SELECT COALESCE(v.id, f.id) AS result_id,
               COALESCE(v.title, f.title) AS result_title,
               COALESCE(1.0 / (rrf_k + v.rank), 0.0) +
               COALESCE(1.0 / (rrf_k + f.rank), 0.0) AS rrf_score
        FROM vector_results v
        FULL OUTER JOIN fts_results f ON v.id = f.id
    )
    SELECT result_id, result_title, rrf_score
    FROM combined
    ORDER BY rrf_score DESC
    LIMIT match_count;
END;
$$;

-- 调用混合检索
SELECT * FROM hybrid_search(
    'pgvector 性能优化',
    '[0.15, -0.25, 0.6, ...]'::vector,
    10
);

⚡ **关键结论：**混合检索在 RAG 场景中的召回准确率通常比纯向量检索高 15-30%。特别是当用户查询包含专有名词、版本号、代码片段等精确信息时，全文搜索的补充至关重要。

3.2 Node.js + pgvector RAG 集成

以下是一个完整的 RAG 检索流程示例，使用 Node.js + OpenAI Embedding API + pgvector：

// rag-search.mjs — 完整的 RAG 语义检索示例
import pg from 'pg';
import OpenAI from 'openai';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function semanticSearch(query, topK = 10) {
    // 1. 生成查询向量
    const embeddingResponse = await openai.embeddings.create({
        model: 'text-embedding-3-small',
        input: query,
    });
    const queryEmbedding = embeddingResponse.data[0].embedding;

    // 2. 向量检索（带元数据过滤）
    const vectorQuery = `
        SELECT id, title, content, metadata,
               1 - (embedding <=> $1::vector) AS similarity
        FROM documents
        WHERE metadata->>'status' = 'published'
        ORDER BY embedding <=> $1::vector
        LIMIT $2
    `;
    const result = await pool.query(vectorQuery, [
        `[${queryEmbedding.join(',')}]`,
        topK
    ]);

    // 3. 构建 RAG 上下文
    const context = result.rows
        .map((row, i) => `[${i + 1}] ${row.title}\n${row.content}`)
        .join('\n\n---\n\n');

    // 4. 调用 LLM 生成回答
    const completion = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [
            { role: 'system', content: `基于以下参考资料回答问题。如果参考资料中没有相关信息，请明确说明。\n\n${context}` },
            { role: 'user', content: query }
        ],
    });

    return {
        answer: completion.choices[0].message.content,
        sources: result.rows.map(r => ({ id: r.id, title: r.title, similarity: r.similarity })),
    };
}

// 使用示例
const result = await semanticSearch('pgvector 和 Pinecone 哪个更好？');
console.log(result.answer);
console.log('参考来源:', result.sources);

3.3 性能优化：连接池与批量操作

在高并发场景下，向量检索的性能瓶颈往往不在数据库，而在应用层的连接管理和批量操作策略。

// batch-insert.mjs — 高性能批量插入向量数据
import pg from 'pg';

const pool = new pg.Pool({
    connectionString: process.env.DATABASE_URL,
    max: 20,                    // 最大连接数
    idleTimeoutMillis: 30000,   // 空闲连接超时
    connectionTimeoutMillis: 5000,
});

async function batchInsert(documents, batchSize = 500) {
    const client = await pool.connect();
    try {
        for (let i = 0; i < documents.length; i += batchSize) {
            const batch = documents.slice(i, i + batchSize);
            const values = [];
            const params = [];
            let paramIndex = 1;

            for (const doc of batch) {
                values.push(`($${paramIndex}, $${paramIndex + 1}, $${paramIndex + 2}, $${paramIndex + 3}::vector)`);
                params.push(doc.title, doc.content, JSON.stringify(doc.metadata), `[${doc.embedding.join(',')}]`);
                paramIndex += 4;
            }

            const sql = `
                INSERT INTO documents (title, content, metadata, embedding)
                VALUES ${values.join(', ')}
                ON CONFLICT DO NOTHING
            `;
            await client.query(sql, params);
            console.log(`Inserted batch ${Math.floor(i / batchSize) + 1}/${Math.ceil(documents.length / batchSize)}`);
        }
    } finally {
        client.release();
    }
}

⚠️ **警告：**不要逐条插入向量数据。10 万条 1536 维向量逐条插入需要 30 分钟以上，批量插入（500 条/批）只需 2 分钟。同时，批量插入时临时禁用索引更新可以进一步提升性能。

⚠️ 四、避坑指南与生产注意事项

经过多个 pgvector 生产项目的实战，以下是最常见的坑点：

❌ 常见错误 1：索引创建时机不对

对于 HNSW 索引，虽然数据为空时也可以创建，但最佳实践是先批量导入数据，再创建索引。这比边插入边维护索引快 3-5 倍。

❌ 常见错误 2：没有设置合适的 maintenance_work_mem

索引构建是内存密集型操作。默认的 maintenance_work_mem（64MB）对于大数据集远远不够。

-- 索引构建前临时调大（构建完成后恢复）
SET maintenance_work_mem = '2GB';
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
RESET maintenance_work_mem;

❌ 常见错误 3：忽略 VACUUM 和 ANALYZE

向量表的膨胀问题比普通表更严重，因为每行携带大量向量数据。务必配置合理的 autovacuum 参数。

-- 为向量表配置更激进的 autovacuum
ALTER TABLE documents SET (
    autovacuum_vacuum_scale_factor = 0.05,
    autovacuum_analyze_scale_factor = 0.02
);

❌ 常见错误 4：在 pgvector 上期望专用向量数据库的性能

坦率地说，pgvector 在纯向量检索性能上无法与 Milvus 或 Pinecone 媲美。当数据量超过 1 亿条、QPS 超过 1000 时，专用向量数据库的优势会非常明显。pgvector 的核心价值在于统一技术栈和降低运维复杂度。

💡 五、总结与选型建议

⚡ **关键结论：**如果你的团队已经在使用 PostgreSQL，且数据量在千万级以内，pgvector 是 2026 年最务实的向量检索方案。它不需要引入新的基础设施，不需要学习新的查询语言，不需要处理数据同步问题。简单，就是最大的生产力。

相关工具推荐：

• 🔧 pgvector 官方仓库 — GitHub 上有详细文档
• 🔧 Drizzle ORM — 原生支持 pgvector 类型映射
• 🔧 LangChain pgvector 集成 — RAG 快速集成
• 🔧 jsjson.com JSON 格式化工具 — 处理 Embedding API 的 JSON 响应