首页 / 文章

使用 pgvector 和 .NET 在 PostgreSQL 中实现语义搜索:实用配置指南

将嵌入向量存储在关系数据旁边,构建HNSW或IVFFlat索引,对混合排名进行过滤与融合,从而判断pgvector是否足以满足您的应用需求。

发布者:REACTAPP.TOP阅读约 9 分钟2030 词

来源: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time

在应用中加入语义搜索时,通常会遇到相同的几款候选方案:Pinecone、Weaviate、Qdrant、Milvus或其他专门的向量数据库。这些方案中的任何一种都可能成为合适的选择。不过,许多应用已经运行了 PostgreSQL 实例,对于很多语义搜索需求而言,该数据库本身就能完成处理。

让这一切得以实现的正是 pgvector,这是一个开源扩展,为 Postgres 添加了向量类型和相似度搜索功能。嵌入向量数据会与关系型数据并存,可通过普通 SQL 进行查询。除了需要运行的组件更少之外,这种方式在结构上也更具优势——无需同步任何内容,所有数据都存储在同一个地方,而且只有在负载需求增加时才需要额外添加基础设施。

一句话概括语义搜索

传统搜索匹配的是文字,而语义搜索匹配的是含义。像“我该如何翻越这座山口?”这样的查询能够找到关于山口的文本,而非学校走廊的描述,这是因为查询内容和文档都会被转换成称为嵌入的数值向量。

整个流程包含四个步骤:

  1. 将文本转换为嵌入向量。
  2. 将该向量存储在 PostgreSQL 中。
  3. 将搜索查询也转换到同一个向量空间中。
  4. 检索与查询向量最接近的已存储向量。

“同一个向量空间”这一表述非常重要——不同模型生成的嵌入无法随意混合使用。

首先选择嵌入模型

模型先于模式存在,因为它决定了向量维度、每次请求的成本、支持的语言范围以及是否可在本地运行。使用 OpenAI 的 text-embedding-3-small 时,通常对应的向量维度为 vector(1536)。而其他模型,包括通过 Ollama 提供的本地模型,可能会生成不同的维度。

这并非无关紧要的细节——PostgreSQL 会拒绝维度不正确的向量。

日后更换模型意味着需要进行数据迁移,具体操作包括:

  • 添加新的向量列或表格;
  • 重新为每份文档生成向量;
  • 重新构建向量索引;
  • 绝不能直接比较旧版本和新版本的向量。

安装 pgvector

需为每个数据库单独启用该扩展:

CREATE EXTENSION IF NOT EXISTS vector;

在托管的 PostgreSQL 服务中,需确认您的套餐及 Postgres 版本是否支持 pgvector。虽然很多版本都支持它,但在基于其功能进行设计之前仍需核实。

模式设计:分块存储

对于短记录,每行一个向量即可。而对于实际文档而言,通常最好将内容分块存储,因为长文档可能涉及多个主题,若用一个向量表示整个文档,容易使这些主题相互混淆。一种可行的结构如下:

CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    source      TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE document_chunks (
    id           BIGSERIAL PRIMARY KEY,
    document_id  BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
    chunk_index  INTEGER NOT NULL,
    content      TEXT NOT NULL,
    embedding    vector(1536) NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (document_id, chunk_index)
);

只有当您的模型确实返回1536个数值时才保留vector(1536),否则请更改其值以匹配实际数量。

在.NET环境中使用Npgsql调用它

需添加以下包:

dotnet add package Npgsql
dotnet add package Pgvector

Dapper 用户还需要一个:

dotnet add package Pgvector.Dapper

使用普通的 Npgsql,可在数据源构建器上调用 UseVector() 方法:

using Npgsql;
using Pgvector;

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();

await using var dataSource = dataSourceBuilder.Build();

在生产环境中,可通过迁移或配置方式创建扩展和表结构。如果扩展是在运行时创建的,则需在使用新类型之前重新加载连接对应的 PostgreSQL 类型。

从 OpenAI 获取嵌入向量

OpenAI .NET SDK 提供了一个嵌入向量客户端:

using OpenAI.Embeddings;

var embeddingClient = new EmbeddingClient("text-embedding-3-small", apiKey);

async Task<float[]> GetEmbeddingAsync(string text)
{
    var result = await embeddingClient.GenerateEmbeddingAsync(text);
    return result.Value.ToFloats().ToArray();
}

对于本地嵌入,可通过您选择的任意服务提供商使用本地模型。规则依然不变:用于索引文档的模型与用于嵌入查询的模型必须一致,或至少要确保二者具有兼容性。绝不能使用一个模型进行索引,再用另一个模型进行搜索。

保存数据块

async Task InsertChunkAsync(
    long documentId,
    int chunkIndex,
    string content,
    CancellationToken cancellationToken = default)
{
    var embedding = await GetEmbeddingAsync(content);
    var vector = new Vector(embedding);

    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        INSERT INTO document_chunks (document_id, chunk_index, content, embedding)
        VALUES (@documentId, @chunkIndex, @content, @embedding)
        ON CONFLICT (document_id, chunk_index)
        DO UPDATE SET
            content = EXCLUDED.content,
            embedding = EXCLUDED.embedding
        """, conn);

    cmd.Parameters.AddWithValue("documentId", documentId);
    cmd.Parameters.AddWithValue("chunkIndex", chunkIndex);
    cmd.Parameters.AddWithValue("content", content);
    cmd.Parameters.AddWithValue("embedding", vector);

    await cmd.ExecuteNonQueryAsync(cancellationToken);
}

更新路径是关键细节。如果某个数据块的文本发生变化,其嵌入向量也必须随之改变,这就是为什么该语句会同时更新两者。

执行搜索

<=>运算符用于计算余弦距离,数值越小表示匹配度越高。按升序排序可以首先得到最接近的向量。

public sealed record SearchResult(
    long DocumentId,
    long ChunkId,
    string Title,
    string Content,
    double Distance);

async Task<List<SearchResult>> SearchAsync(
    string query,
    int limit = 5,
    CancellationToken cancellationToken = default)
{
    var queryEmbedding = await GetEmbeddingAsync(query);
    var queryVector = new Vector(queryEmbedding);

    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        SELECT d.id,
               c.id,
               d.title,
               c.content,
               c.embedding <=> @queryVector AS distance
        FROM document_chunks c
        JOIN documents d ON d.id = c.document_id
        ORDER BY c.embedding <=> @queryVector
        LIMIT @limit
        """, conn);

    cmd.Parameters.AddWithValue("queryVector", queryVector);
    cmd.Parameters.AddWithValue("limit", limit);

    var results = new List<SearchResult>();

    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
    while (await reader.ReadAsync(cancellationToken))
    {
        results.Add(new SearchResult(
            DocumentId: reader.GetInt64(0),
            ChunkId: reader.GetInt64(1),
            Title: reader.GetString(2),
            Content: reader.GetString(3),
            Distance: reader.GetDouble(4)));
    }

    return results;
}

请注意,查询会直接根据距离表达式进行排序。借助 pgvector 索引,ORDER BY embedding <= @query LIMIT n 这种写法才能让查询规划器使用该索引。

距离运算符

pgvector 提供了多种运算符:

运算符 所测量的距离
欧几里得(L2)距离
余弦距离
负内积
出租车距离(L1)

对于文本嵌入向量,余弦距离是合适的默认选择。

HNSW 索引

由于没有索引,PostgreSQL在每次向量搜索时都需要扫描整个表。这种方式虽然准确且简单,但随着向量数量的增加,查询速度会变慢。HNSW通常是应用程序搜索中最理想的初始索引选择:

CREATE INDEX document_chunks_embedding_hnsw_idx
ON document_chunks
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

这两个参数为:

  • m,表示每层的最大连接数,默认值为16;
  • ef_construction,表示构建时的候选列表大小,默认值为64。

数值越大,召回率越高,但会消耗更多内存并增加构建时间。

在会话的查询阶段也可以调整召回率:

SET hnsw.ef_search = 100;

或者仅在单个事务中:

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;

请记住,HNSW是一种近似算法。它为了提升速度而放弃了完美的召回率。

IVFFlat作为替代方案

IVFFlat比HNSW占用更少内存,构建速度也更快,但其速度与召回率之间的权衡通常更差。

CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

不要在空表上构建IVFFlat索引,因为它需要现有的行来形成其列表。作为lists的初步方案,10,000个向量的表大约只能生成10个列表,而无法生成100个。

在查询时,需调整探针设置:

SET ivfflat.probes = 10;

更多的探针可以提高召回率,但会降低查询速度。

过滤与混合搜索

选择 pgvector 的一个重要原因在于向量数据可以与关系型数据并存。你可以先进行过滤,然后再进行排序:

SELECT d.id, d.title, c.content, c.embedding <=> @queryVector AS distance
FROM document_chunks c
JOIN documents d ON d.id = c.document_id
WHERE d.created_at > NOW() - INTERVAL '30 days'
  AND d.source = 'documentation'
ORDER BY c.embedding <=> @queryVector
LIMIT 10;

对于真正的混合搜索,不要先计算关键词排名后再忽略它,而应将语义排名与关键词排名合并。一种实用的方法是采用互反排名融合的方式来进行评分:

WITH semantic AS (
    SELECT c.id,
           row_number() OVER (ORDER BY c.embedding <=> @queryVector) AS semantic_rank
    FROM document_chunks c
    LIMIT 100
),
keyword AS (
    SELECT c.id,
           row_number() OVER (
               ORDER BY ts_rank_cd(
                   to_tsvector('english', c.content),
                   plainto_tsquery('english', @query)
               ) DESC
           ) AS keyword_rank
    FROM document_chunks c
    WHERE to_tsvector('english', c.content) @@ plainto_tsquery('english', @query)
    LIMIT 100
)
SELECT d.id AS document_id,
       c.id AS chunk_id,
       d.title,
       c.content,
       COALESCE(1.0 / (60 + semantic.semantic_rank), 0) +
       COALESCE(1.0 / (60 + keyword.keyword_rank), 0) AS score
FROM semantic
FULL OUTER JOIN keyword ON keyword.id = semantic.id
JOIN document_chunks c ON c.id = COALESCE(semantic.id, keyword.id)
JOIN documents d ON d.id = c.document_id
ORDER BY score DESC
LIMIT 10;

这并非融合两者的唯一方法,但它能让排序逻辑更加清晰可见。

何时适合使用 pgvector

在以下情况下它是不错的选择:

  • PostgreSQL 已经是主要的数据库;
  • 向量数据需要与关系型表自然关联;
  • 事务一致性非常重要;
  • 团队已经熟悉 Postgres 的使用方法;
  • 数据集规模较小或中等;
  • 希望避免使用额外的服务及同步任务。

它常见的应用场景包括内部搜索、产品搜索、支持工具以及文档搜索,还有那些事实数据源自关系型数据库的 RAG 系统。

何时专用向量存储可能更合适

在以下情况下可以考虑使用专为向量数据设计的数据库:

  • 向量数据量达到数千万甚至更多;
  • 查询量极大且对延迟要求极为严格;
  • 您需要具备专业向量搜索功能的管理型服务;
  • 您需要的内置混合检索、重排序或过滤功能比 Postgres 能提供的更为强大;
  • 您的团队对 PostgreSQL 并不十分熟悉;
  • 多租户隔离与扩展能力是您的核心需求。

这并非关乎理念问题,而是操作层面的适配性。

完整的 ASP.NET Core 接口

app.MapGet("/search", async (
    string q,
    NpgsqlDataSource db,
    CancellationToken cancellationToken) =>
{
    var queryEmbedding = await GetEmbeddingAsync(q);
    var queryVector = new Vector(queryEmbedding);

    await using var conn = await db.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        SELECT d.id,
               c.id,
               d.title,
               c.content,
               c.embedding <=> @v AS distance
        FROM document_chunks c
        JOIN documents d ON d.id = c.document_id
        ORDER BY c.embedding <=> @v
        LIMIT 5
        """, conn);

    cmd.Parameters.AddWithValue("v", queryVector);

    var results = new List<object>();

    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
    while (await reader.ReadAsync(cancellationToken))
    {
        results.Add(new
        {
            documentId = reader.GetInt64(0),
            chunkId = reader.GetInt64(1),
            title = reader.GetString(2),
            content = reader.GetString(3),
            distance = reader.GetDouble(4)
        });
    }

    return Results.Ok(results);
});

接下来的步骤

语义搜索并不总是需要单独的向量数据库。当 PostgreSQL 已经存储了真实数据时,pgvector 允许你在关系型数据旁保存嵌入向量,用 SQL 进行查询,用常规条件进行过滤,并将所有操作保留在同一个系统中。

以下几条规则有助于保持架构的整洁:

  • 先选择嵌入模型,再确定向量维度;
  • 切勿混用不同模型生成的嵌入向量;
  • 将过长或涉及多个主题的文档拆分;
  • 只有当表的数据量足够大时才添加索引;
  • 请记住 HNSW 和 IVFFlat 都属于近似算法;
  • 模型变更应视为数据迁移操作。

对于许多生产环境应用而言,pgvector在很长一段时间内就已足够使用。但这并不意味着专用向量数据库毫无必要,只是最简单可靠的架构通常会让数据保持在其原有的存储位置。

如需进一步了解,可参阅pgvector的README文件及其.NET版本包、OpenAI的.NET SDK与嵌入模型指南,以及Microsoft.Extensions.AI的文档。

相关阅读

  • 语义搜索与向量搜索的对比,以及RAG和Azure AI Search的适用场景——通过离职政策与事故案例解释关键词搜索、向量搜索、语义搜索及混合搜索,同时阐述Azure AI Search、Semantic Kernel与RAG之间的关联。
  • 结合互反排名融合的BM25与pgvector:Python环境下的RAG混合搜索方案——探讨为何密集检索会遗漏精确匹配项,BM25与余弦相似度搜索如何互补,以及基于Postgres和RRF实现两者融合的Python技术栈。