Szukanie semantyczne w PostgreSQL przy użyciu pgvector i .NET: praktyczne ustawienie
Przechowuj embeddy obok danych relacyjnych, twórz indeksy HNSW lub IVFFlat, filtrowaj i łącz hybrydowe ranki, a także oceniaj, czy pgvector wystarcza do twojej aplikacji.
Źródła: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time
Dodawanie wyszukiwania semantycznego do aplikacji zazwyczaj prowadzi do tej samej listy możliwości: Pinecone, Weaviate, Qdrant, Milvus lub inne dedykowane bazy danych wektorowych. Każda z nich może być odpowiedzią. Mimo to wiele aplikacji już korzysta z instancji PostgreSQL, a w przypadku wielu zadań związanych z wyszukiwaniem semantycznym ta baza danych może sama sobie z nimi poradzić.
Kluczowym elementem umożliwiającym to działanie jest pgvector – rozszerzenie otwartego oprogramowania, które dodaje do Postgres typ wektorowy oraz funkcje wyszukiwania podobieństwa. Embeddingi znajdują się obok danych relacyjnych i można do nich uzyskiwać dostęp za pomocą zwykłego SQL. Oprócz mniejszej liczby komponentów do uruchomienia, korzyść ta ma również charakter strukturalny: nie trzeba niczego synchronizować, prawda znajduje się w jednym miejscu, a infrastrukturę dodaje się tylko wtedy, gdy wymaga tego obciążenie.
Wyszukiwanie semantyczne w jednym zdaniu
Klasyczne wyszukiwanie dopasowuje słowa, natomiast wyszukiwanie semantyczne dopasowuje znaczenia. Zapytanie takie jak „Jak przejść przez przechodzącą górę?” może znaleźć tekst o przechodzącej górze zamiast o korytarzu szkolnym, ponieważ zarówno zapytanie, jak i dokumenty są przekształcane w wektory liczbowe zwane embeddingami.
Proces składa się z czterech kroków:
- Przekształcenie tekstu w wektor embeddingu.
- Zapisanie wektora w PostgreSQL.
- Przekształcenie zapytania wyszukiwania do tego samego przestrzeni wektorowej.
- Pobranie zapisanych wektorów najbliższych wektorowi zapytania.
Wyrażenie „ta sama przestrzeń wektorowa” ma duże znaczenie – embeddingi z różnych modeli nie mogą być swobodnie łączone.
Najpierw wybierz model embeddingu
Model przychodzi przed schematem, ponieważ określa on wymiar wektora, koszt na zapytanie, języki, które są dobrze obsługiwane, oraz to, czy można go uruchomić lokalnie. W przypadku modelu text-embedding-3-small od OpenAI zwykle używa się kolumny vector(1536). Inny model, w tym ten lokalny dostarczany przez Ollamę, może mieć inny wymiar.
To nie jest błaha kwestia. PostgreSQL odrzuca wektory o niewłaściwej liczbie wymiarów.
Zmiana modelu później oznacza migrację danych. Będziesz musiał:
- dodać nową kolumnę lub tabelę wektorową;
- ponownie utworzyć wektory dla każdego dokumentu;
- ponownie zbudować indeks wektorowy;
- nigdy bezpośrednio nie porównywać starych i nowych wektorów.
Instalacja pgvector
Włącz rozszerzenie raz na każdą bazę danych:
CREATE EXTENSION IF NOT EXISTS vector;
W zarządzanych usługach PostgreSQL sprawdź, czy pgvector jest dostępny w Twoim planie i wersji Postgresa. Wiele z nich go obsługuje, ale warto to sprawdzić przed jego wykorzystaniem.
Schemat: przechowywanie fragmentów
Dla krótkich rekordów wystarczy jeden wektor na wiersz. W przypadku rzeczywistych dokumentów zazwyczaj lepiej jest umieszczać w nich fragmenty, ponieważ długi dokument może dotyczyć kilku tematów, a jeden wektor dla całego dokumentu może sprawić, że te tematy staną się nierozróżnialne. Praktyczny układ:
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)
);
Zachowaj vector(1536) tylko wtedy, gdy twój model rzeczywiście zwraca 1536 liczb, w przeciwnym razie zmień go odpowiednio.
Użycie w .NET z Npgsql
Dodaj pakiety:
dotnet add package Npgsql
dotnet add package Pgvector
Użytkownicy Dapper potrzebują jeszcze jednego:
dotnet add package Pgvector.Dapper
Używając zwykłego Npgsql, wywołaj UseVector() w konstruktorze źródła danych:
using Npgsql;
using Pgvector;
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();
await using var dataSource = dataSourceBuilder.Build();
W środowisku produkcyjnym twórz rozszerzenia oraz tabele za pomocą migracji lub procesu konfiguracji. Jeśli rozszerzenie zostanie utworzone w czasie wykonywania aplikacji, załaduj ponownie typy PostgreSQL z połączenia przed użyciem nowego typu.
Pobieranie embeddingów z OpenAI
SDK OpenAI .NET udostępnia klienta do pobierania embeddingów:
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();
}
Dla lokalnych embeddingów użyj modelu lokalnego poprzez dowolnego dostawcę, którego preferujesz. Zasada pozostaje ta sama: model, który indeksuje dokumenty, oraz model, który tworzy embeddingi z zapytań, muszą być identyczne lub przynajmniej celowo kompatybilne. Nigdy nie indeksuj za pomocą jednego modelu, a nie szukaj za pomocą innego.
Zapisywanie fragmentu
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);
}
Ścieżka aktualizacji jest kluczowym elementem. Jeśli zmieni się tekst fragmentu, musi ulec zmianie również jego embedding, dlatego operacja upsert łączy je razem.
Przeprowadzanie wyszukiwania
Operator <=> oblicza odległość kosinową, przy czym mniejsza wartość oznacza bliższe dopasowanie. Sortowanie w porządku rosnącym pokazuje najbliższe wektory na początku.
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;
}
Należy pamiętać, że zapytanie sortuje się bezpośrednio na podstawie wyrażenia odległości. Dzięki indeksom pgvector to wyrażenie ORDER BY embedding <=> @query LIMIT n umożliwia planerowi wykorzystanie indeksu.
Operatory odległości
pgvector oferuje kilka operatorów:
| Operator | Mierzy |
|---|---|
<-> | Odległość euklidesowa (L2) |
<=> | Odległość kosinowa |
<#> | Ujemny iloczyn skalarny |
<+> | Odległość taxicab (L1) |
Dla embeddingów tekstowych odległość kosinowa stanowi rozsądny standard.
Indeksy HNSW
Bez indeksu PostgreSQL przeszukuje całą tabelę przy każdym zapytaniu wektorowym. Jest to metoda dokładna i prosta, ale jej wydajność spada wraz ze wzrostem liczby wektorów. HNSW jest często najlepszym pierwszym indeksem do wyszukiwania w aplikacjach:
CREATE INDEX document_chunks_embedding_hnsw_idx
ON document_chunks
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
Dwa parametry to:
m– maksymalna liczba połączeń na warstwę, której domyślna wartość to 16;ef_construction– rozmiar listy kandydatów podczas budowania, której domyślna wartość to 64.
Większe wartości mogą poprawić dokładność, ale wymagają więcej pamięci i czasu na budowanie.
Dokładność można również dostosować w momencie wyszukiwania w ramach danej sesji:
SET hnsw.ef_search = 100;
lub tylko w ramach jednej transakcji:
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;
Pamiętaj, że HNSW jest metodą przybliżoną. Rezygnuje ona z doskonałej dokładności w zamian za szybkość.
IVFFlat jako alternatywa
IVFFlat może wymagać mniej pamięci i być szybciej budowany niż HNSW, chociaż jego kompromis pomiędzy szybkością a dokładnością jest zazwyczaj gorszy.
CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
Nie twórz indeksu IVFFlat na pustej tabeli, ponieważ potrzebuje on istniejących wierszy do utworzenia swoich list. Jako przybliżony początek dla lists, tabela zawierająca 10 000 wektorów nadaje się mniej więcej do 10 list, a nie do 100.
Podczas wyszukiwania dostosuj sondy:
SET ivfflat.probes = 10;
Liczniejsze sondy poprawiają dokładność wyników, ale spowalniają zapytania.
Filtrowanie i wyszukiwanie hybrydowe
Głównym powodem wyboru pgvector jest to, że wektory znajdują się obok danych relacyjnych. Można najpierw zafiltrować, a następnie sklasyfikować wyniki:
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;
Dla prawdziwego wyszukiwania hybrydowego nie obliczaj rankingu słowa kluczowego, a następnie go ignoruj. Połącz ranki semantyczne z rankami słów kluczowych. Jednym praktycznym podejściem jest ocenianie w stylu 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;
To nie jest jedyny sposób na połączenie tych dwóch rozwiązań, ale sprawia, że logika rankingu staje się widoczna.
Kiedy pgvector jest odpowiedni
Jest dobrym wyborem wtedy, gdy:
- PostgreSQL jest już główną bazą danych;
- wektory muszą być naturalnie łączone z tabelami relacyjnymi;
- ważna jest spójność transakcyjna;
- zespół już wie, jak obsługiwać Postgres;
- zbiór danych ma małą lub średnią wielkość;
- chcesz uniknąć dodatkowej usługi i zadania synchronizacji.
Typowymi zastosowaniami są wyszukiwarki wewnętrzne, wyszukiwarki produktów, narzędzia wsparcia oraz wyszukiwanie w dokumentacji, a także konfiguracje RAG, których dane pochodzą już z bazy danych relacyjnej.
Kiedy lepszy może być dedykowany magazyn wektorów
Rozważ specjalnie zaprojektowaną bazę danych wektorów wtedy, gdy:
- liczba wektorów osiąga dziesiątki milionów lub więcej;
- objętość zapytań jest bardzo duża, a limity opóźnień są niskie;
- chcesz usługi zarządzanej z specjalistycznymi operacjami wyszukiwania wektorowego;
- potrzebujesz bardziej zaawansowanych wbudowanych funkcji hybrydowego wyszukiwania, ponownego rankowania lub filtrowania niż oferuje Postgres;
- twoz zespół nie ma głębokiej wiedzy na temat PostgreSQL;
- izolacja wielu użytkowników i skalowalność są kluczowymi wymaganiami.
To nie jest kwestia ideologii. Chodzi o dopasowanie operacyjne.
Pełny punkt końcowy 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);
});
Jakie to ma dla ciebie konsekwencje
Wyszukiwanie semantyczne nie zawsze wymaga oddzielnego bazę danych wektorowej. Gdy PostgreSQL już zawiera twoje źródło prawdy, pgvector pozwala przechowywać embeddingi obok danych relacyjnych, przeszukiwać je za pomocą SQL, filtrować je za pomocą zwykłych warunków oraz utrzymywać transakcje w jednym systemie.
Kilka zasad pomaga utrzymać uporządkowanie konfiguracji:
- wybierz model embeddingu przed określeniem wymiaru wektorowego;
- nigdy nie łącz embeddingi z różnych modeli;
- dziel na fragmenty dokumenty długie lub dotyczące kilku tematów;
- dodawaj indeks tylko wtedy, gdy tabela jest na tyle duża, by był on potrzebny;
- pamiętaj, że HNSW i IVFFlat są aproksymacyjne;
- traktuj zmianę modelu jako migrację danych.
Dla wielu zastosowań produkcyjnych pgvector wystarcza przez długi czas. To nie oznacza, że dedykowane bazy danych wektorowych są niepotrzebne. Po prostu najprostsza i najbardziej niezawodna architektura często pozostawia dane tam, gdzie już się znajdują.
Aby dowiedzieć się więcej, zapoznaj się z dokumentacją pgvector README oraz jego pakietem .NET, dokumentacją OpenAI .NET SDK i przewodnikiem dotyczącym embeddingów, a także z dokumentacją Microsoft.Extensions.AI.