使用 pgvector 和 .NET 在 PostgreSQL 中实现语义搜索:实用配置指南
将嵌入向量存储在关系数据旁边,构建HNSW或IVFFlat索引,对混合排名进行过滤与融合,从而判断pgvector是否足以满足您的应用需求。
来源: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time
在应用中加入语义搜索时,通常会遇到相同的几款候选方案:Pinecone、Weaviate、Qdrant、Milvus或其他专门的向量数据库。这些方案中的任何一种都可能成为合适的选择。不过,许多应用已经运行了 PostgreSQL 实例,对于很多语义搜索需求而言,该数据库本身就能完成处理。
让这一切得以实现的正是 pgvector,这是一个开源扩展,为 Postgres 添加了向量类型和相似度搜索功能。嵌入向量数据会与关系型数据并存,可通过普通 SQL 进行查询。除了需要运行的组件更少之外,这种方式在结构上也更具优势——无需同步任何内容,所有数据都存储在同一个地方,而且只有在负载需求增加时才需要额外添加基础设施。
一句话概括语义搜索
传统搜索匹配的是文字,而语义搜索匹配的是含义。像“我该如何翻越这座山口?”这样的查询能够找到关于山口的文本,而非学校走廊的描述,这是因为查询内容和文档都会被转换成称为嵌入的数值向量。
整个流程包含四个步骤:
- 将文本转换为嵌入向量。
- 将该向量存储在 PostgreSQL 中。
- 将搜索查询也转换到同一个向量空间中。
- 检索与查询向量最接近的已存储向量。
“同一个向量空间”这一表述非常重要——不同模型生成的嵌入无法随意混合使用。
首先选择嵌入模型
模型先于模式存在,因为它决定了向量维度、每次请求的成本、支持的语言范围以及是否可在本地运行。使用 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的文档。
相关阅读
- 可复用的语义搜索服务:MCP背后的Pinecone嵌入模型 —— 通过分块处理一次性索引PDF文件,利用批量多语言e5-large嵌入模型与Pinecone,随后让任何智能体通过带分数阈值的FastMCP服务器查询这些数据。