Семантичний пошук у PostgreSQL за допомогою pgvector та .NET: практична налаштування
Зберігайте ембеддинги поруч із реляційними даними, створюйте індекси 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 з керуванням переконайтеся, що 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 протягом тривалого часу є достатнім. Це не означає, що спеціалізовані векторні бази даних є зайвими. Просто найпростіша надійна архітектура часто залишає дані там, де вони вже знаходяться.
Для подальшого ознайомлення перегляньте README до pgvector та його .NET-пакет, OpenAI .NET SDK та посібник з векторними представленнями, а також документацію Microsoft.Extensions.AI.