Семантический поиск в PostgreSQL с pgvector и .NET: практическая настройка
Храните эмбеддинги рядом с реляционными данными, создавайте индексы HNSW или IVFFlat, фильтруйте и смешивайте гибридные рейтинги, а также определяйте, достаточен ли pgvector для вашего приложения.
Источники: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time
Для добавления семантического поиска в приложение обычно рассматриваются одни и те же варианты: Pinecone, Weaviate, Qdrant, Milvus или другие специализированные векторные базы данных. Любой из них может стать подходящим решением. Однако многие приложения уже используют инстанс PostgreSQL, и для многих задач семантического поиска эта база данных может справиться с ними сама.
Ключевым элементом здесь является pgvector — open-source расширение, которое добавляет в Postgres векторный тип и возможности поиска по сходству. Эмбеддинги хранятся рядом с реляционными данными и могут запрашиваться с помощью обычного SQL. Помимо уменьшения количества компонентов, это также имеет структурные преимущества: не нужно синхронизировать что-либо, информация хранится в одном месте, а инфраструктуру добавляют только тогда, когда это требуется нагрузкой.
Семантический поиск в одном предложении
Классический поиск ищет слова, а семантический поиск — смысл. Запрос вроде «Как преодолеть горный перевал?» может найти текст о горном перевале, а не о школьном коридоре, поскольку как запрос, так и документы преобразуются в числовые векторы, называемые эмбеддингами.
Процесс состоит из четырех шагов:
- Преобразовать текст в вектор эмбеддинга.
- Сохранить вектор в PostgreSQL.
- Преобразовать запрос на поиск в тот же векторный пространство.
- Получить сохраненные векторы, наиболее близкие к вектору запроса.
Фраза «тот же векторный пространство» имеет важное значение: эмбеддинги от разных моделей нельзя свободно смешивать.
Сначала выберите модель эмбеддингов
Модель определяется раньше схемы, поскольку она фиксирует размерность вектора, стоимость обработки каждого запроса, список поддерживаемых языков и возможность его запуска локально. Для модели OpenAI text-embedding-3-small обычно используется столбец vector(1536). Другие модели, включая локальные, предоставляемые через Ollama, могут иметь другую размерность.
Это не тривиальная деталь — PostgreSQL отклоняет векторы с неверным количеством измерений.
Замена модели позже требует миграции данных. Вам придётся:
- добавить новый столбец или таблицу для векторов;
- переобразовать каждый документ в вектор;
- пересоздать индекс векторов;
- никогда не сравнивать старые и новые векторы напрямую.
Установка pgvector
Активируйте расширение один раз для каждой базы данных:
CREATE EXTENSION IF NOT EXISTS vector;
В управляемых сервисах PostgreSQL убедитесь, что pgvector поддерживается для вашего тарифа и версии Postgres. Многие из них его поддерживают, но перед тем, как планировать использование, обязательно проверьте это.
Схема: хранение фрагментов
Для коротких записей достаточно одного вектора на строку. Для настоящих документов обычно лучше встраивать фрагменты, поскольку длинный документ может охватывать несколько тем, а один вектор для всего объема информации склонен смешивать их между собой. Рабочая структура:
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)
);
Сохраняйте vector(1536) только в том случае, если ваша модель действительно возвращает 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
SDK OpenAI для .NET предоставляет клиент для работы с эмбеддингами:
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);
}
Путь обновления — это ключевой момент. Если меняется текст блока, должно измениться и его вхождение, поэтому операция upsert обновляет их вместе.
Проведение поиска
Оператор <=> вычисляет косинусовое расстояние, причем чем меньше значение, тем ближе совпадение. Сортировка в порядке возрастания возвращает сначала наиболее близкие векторы.
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;
Для настоящего гибридного поиска не следует вычислять ранг ключевого слова, а затем игнорировать его. Необходимо объединить семантический и ключевой ранги. Один из практических подходов — оценка в стиле метода Reciprocal Rank Fusion:
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.