Semantische Suche in PostgreSQL mit pgvector und .NET: Eine praktische Einrichtung
Speichern Sie Embeddings neben den relationalen Daten, erstellen Sie HNSW- oder IVFFlat-Indizes, filtern und mischen Sie hybride Ranglisten sowie beurteilen Sie, ob pgvector für Ihre Anwendung ausreicht.
Quellen: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time
Die Einführung einer semantischen Suche in einer Anwendung führt in der Regel zu derselben Auswahl: Pinecone, Weaviate, Qdrant, Milvus oder einige andere spezialisierte Vektordatenbanken. Jede von ihnen kann die richtige Lösung sein. Dennoch laufen viele Anwendungen bereits mit einer PostgreSQL-Instanz, und für viele Anforderungen an semantische Suche kann diese Datenbank die Aufgabe allein bewältigen.
Der entscheidende Bestandteil hierfür ist pgvector, eine Open-Source-Erweiterung, die Postgres einen Vekortyp sowie eine Ähnlichkeitssuche bietet. Embeddings werden neben den relationalen Daten gespeichert und mit herkömmlichem SQL abgefragt. Neben der geringeren Anzahl an zu verwaltenden Komponenten gibt es auch strukturelle Vorteile: Es muss nichts synchronisiert werden, die Wahrheit befindet sich an nur einem Ort, und Infrastruktur wird nur hinzugefügt, wenn die Last es erfordert.
Semantische Suche in einem Satz
Klassische Suchfunktionen suchen nach Wörtern, während semantische Suchfunktionen nach Bedeutungen suchen. Eine Abfrage wie „Wie komme ich über den Gebirgspass?“ kann Texte über einen Gebirgspass statt über einen Schulflur finden, weil sowohl die Abfrage als auch die Dokumente in numerische Vektoren umgewandelt werden, die als Embeddings bezeichnet werden.
Der Ablauf umfasst vier Schritte:
- Den Text in einen Embedding-Vektor umwandeln.
- Den Vektor in PostgreSQL speichern.
- Die Suchabfrage in denselben Vektorraum umwandeln.
- Die gespeicherten Vektoren herausfiltern, die dem Abfragevektor am nächsten sind.
Der Ausdruck „derselbe Vektorraum“ ist von großer Bedeutung. Embeddings aus verschiedenen Modellen können nicht einfach miteinander vermischt werden.
Wählen Sie zunächst das Embedding-Modell aus
Das Modell kommt vor dem Schema, da es die Vektordimension, die Kosten pro Anfrage, die unterstützten Sprachen sowie die Möglichkeit einer lokalen Ausführung festlegt. Bei OpenAI’s text-embedding-3-small ist in der Regel eine vector(1536)-Spalte geeignet. Ein anderes Modell, einschließlich solcher, die über Ollama lokal bereitgestellt werden, kann eine andere Dimension haben.
Das ist kein unbedeutender Detail. PostgreSQL lehnt Vektoren mit der falschen Anzahl an Dimensionen ab.
Ein späterer Wechsel der Modelle erfordert eine Datenmigration. Dazu müssten Sie:
- eine neue Vektor-Spalte oder Tabelle hinzufügen;
- jedes Dokument erneut einbetten;
- den Vektorindex neu erstellen;
- alte und neue Einbettungen niemals direkt vergleichen.
Installation von pgvector
Die Erweiterung muss pro Datenbank einmal aktiviert werden:
CREATE EXTENSION IF NOT EXISTS vector;
In verwalteten PostgreSQL-Diensten sollten Sie überprüfen, ob pgvector für Ihr Abo sowie Ihre Postgres-Version angeboten wird. Viele unterstützen es zwar, aber prüfen Sie das vor der Planung unter Verwendung dieses Features.
Schema: Speicherung von Blöcken
Bei kurzen Datensätzen reicht ein Vector pro Zeile aus. Bei echten Dokumenten ist es in der Regel besser, Blöcke einzubetten, da ein langes Dokument mehrere Themen umfassen kann und ein einziger Vector für das gesamte Dokument dazu neigt, diese Themen miteinander zu vermischen. Ein praktikabler Aufbau:
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)
);
Behalten Sie vector(1536) nur bei, wenn Ihr Modell tatsächlich 1536 Zahlen zurückgibt; ansonsten ändern Sie es entsprechend.
Verwendung in .NET mit Npgsql
Fügen Sie die Pakete hinzu:
dotnet add package Npgsql
dotnet add package Pgvector
Dapper-Nutzer benötigen noch eines:
dotnet add package Pgvector.Dapper
Mit reinem Npgsql rufen Sie UseVector() beim Datenquellenersteller auf:
using Npgsql;
using Pgvector;
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();
await using var dataSource = dataSourceBuilder.Build();
In der Produktion werden die Erweiterung sowie die Tabellen über Migrationsprozesse oder Provisioning erstellt. Wenn die Erweiterung zur Laufzeit erstellt wird, müssen die PostgreSQL-Typen der Verbindung neu geladen werden, bevor der neue Typ verwendet wird.
Embeddings von OpenAI abrufen
Das OpenAI .NET SDK stellt einen Embedding-Client bereit:
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();
}
Für lokale Embeddings verwenden Sie ein lokales Modell über den von Ihnen gewählten Anbieter. Die Regel bleibt dieselbe: Das Modell, das die Dokumente indiziert, und das Modell, das Abfragen in Embeddings umwandelt, müssen übereinstimmen oder zumindest absichtlich kompatibel sein. Indizieren Sie niemals mit einem Modell und suchen Sie mit einem anderen.
Einen Datensatz speichern
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);
}
Der Aktualisierungsweg ist der entscheidende Aspekt. Wenn sich der Text eines Datensatzes ändert, muss sich auch seine Embedding-Struktur ändern – deshalb fügt die Anweisung beides gemeinsam hinzu.
Suche durchführen
Der Operator <=> berechnet die Kosinus-Distanz, wobei eine kleinere Zahl auf eine engere Übereinstimmung hindeutet. Eine Aufsteigende Sortierung gibt zunächst die nächsten Vektoren an.
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;
}
Beachten Sie, dass die Abfrage direkt nach der Entfernungsberechnung sortiert wird. Mit pgvector-Indizes ermöglicht die Formel ORDER BY embedding <=> @query LIMIT n es dem Planer, den Index zu nutzen.
Entfernungsoperatoren
pgvector bietet mehrere Operatoren:
| Operator | Messung |
|---|---|
<-> | Euklidische (L2)-Entfernung |
<=> | Kosinus-Entfernung |
<#> | Negatives Skalarprodukt |
<+> | Taxicab-(L1)-Entfernung |
Für Text-Embeddings ist die Kosinus-Entfernung eine sinnvolle Standardwahl.
HNSW-Indizes
Ohne Index durchsucht PostgreSQL bei jeder Vektorabfrage die gesamte Tabelle. Das ist präzise und einfach, wird aber langsamer, je mehr Vektoren vorhanden sind. HNSW ist oft der beste erste Index für Anwendungsabfragen:
CREATE INDEX document_chunks_embedding_hnsw_idx
ON document_chunks
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
Die beiden Parameter sind:
m, die maximale Anzahl an Verbindungen pro Schicht, standardmäßig 16;ef_construction, die Größe der Kandidatenliste während des Aufbaus, standardmäßig 64.
Höhere Werte können die Trefferquote erhöhen, erfordern aber mehr Speicher und längere Bereitstellungszeiten.
Die Trefferquote kann auch zur Laufzeit einer Sitzung bei Abfragen angepasst werden:
SET hnsw.ef_search = 100;
oder nur innerhalb einer einzigen Transaktion:
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;
Denken Sie daran, dass HNSW nur annähernd genau ist. Es verzichtet auf eine perfekte Trefferquote zugunsten von Geschwindigkeit.
IVFFlat als Alternative
IVFFlat verbraucht weniger Speicher und kann schneller aufgebaut werden als HNSW, doch sein Kompromiss zwischen Geschwindigkeit und Trefferquote ist in der Regel schlechter.
CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
Erstellen Sie keinen IVFFlat-Index auf einer leeren Tabelle, da er vorhandene Zeilen benötigt, um seine Listen zu bilden. Als grober Ausgangspunkt für lists eignet sich eine Tabelle mit 10.000 Vektoren für etwa 10 Listen, nicht für 100.
Zur Abfragezeit passen Sie die Proben an:
SET ivfflat.probes = 10;
Mehr Proben verbessern die Trefferquote, verlangsamen aber die Abfragen.
Filtern und hybrides Suchen
Ein wichtiger Grund, pgvector zu wählen, ist, dass Vektoren neben relationalen Daten gespeichert werden. Sie können zunächst filtern und anschließend ranken:
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;
Für eine echte hybride Suche sollte man nicht erst eine Schlüsselwort-Rangfolge berechnen und sie anschließend ignorieren. Man sollte die semantischen und die Schlüsselwort-Rangfolgen miteinander verbinden. Ein praktischer Ansatz ist die Bewertung im Stil der 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;
Es ist nicht die einzige Möglichkeit, beides zu kombinieren, aber es macht die Ranking-Logik sichtbar.
Wann pgvector geeignet ist
Es ist eine gute Wahl, wenn:
- PostgreSQL bereits die Hauptdatenbank ist;
- Vektoren nahtlos mit relationellen Tabellen verknüpft werden müssen;
- transaktionale Konsistenz wichtig ist;
- das Team bereits weiß, wie man Postgres betreibt;
- die Datensammlung klein oder mittelgroß ist;
- man einen weiteren Dienst sowie eine Synchronisierungsarbeit vermeiden möchte.
Typische Anwendungsbereiche sind interne Suchfunktionen, Produktsuche, Support-Tools sowie Dokumentensuche, ebenso wie RAG-Setups, deren Fakten bereits aus der relationellen Datenbank stammen.
Wann ein speziell entwickelter Vektordatenspeicher besser sein kann
Man sollte sich für einen speziell konzipierten Vektordatenspeicher entscheiden, wenn:
- die Anzahl der Vektoren in die Zehntausende oder darüber geht;
- die Anzahl der Abfragen sehr hoch ist und die Latenzvorgaben eng sind;
- Sie möchten einen verwalteten Service mit spezialisierten Vektor-Suchfunktionen;
- Sie benötigen eine umfangreichere integrierte hybride Such-, Neubewertungs- oder Filterfunktion als Postgres bietet;
- Ihr Team kennt PostgreSQL nicht ausführlich;
- Mehrfachnutzer-Isolation und Skalierbarkeit sind zentrale Anforderungen.
Es geht hier nicht um Ideologie, sondern um operative Passgenauigkeit.
Ein vollständiger ASP.NET Core-Endpunkt
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);
});
Was bleibt Ihnen übrig
Semantische Suche erfordert nicht immer eine separate Vektordatenbank. Wenn PostgreSQL bereits Ihre Quelle der Wahrheit enthält, ermöglicht pgvector es Ihnen, Embeddings neben relationalen Daten zu speichern, sie mit SQL abzufragen, mit gewöhnlichen Bedingungen zu filtern und Transaktionen in einem System zu verwalten.
Einige Regeln sorgen dafür, dass die Einrichtung übersichtlich bleibt:
- wählen Sie das Embedding-Modell vor der Vektordimension aus;
- mischen Sie niemals Embeddings aus verschiedenen Modellen;
- teilen Sie lange Dokumente oder solche auf mehrere Themen verteilte Dokumente in Abschnitte auf;
- fügen Sie einen Index nur dann hinzu, wenn die Tabelle groß genug ist, um einen zu benötigen;
- denken Sie daran, dass HNSW und IVFFlat nur annähernd funktionieren;
- betrachten Sie einen Modellwechsel als Datenmigration.
Für viele Produktionsanwendungen reicht pgvector über einen langen Zeitraum aus. Das bedeutet jedoch nicht, dass spezielle Vektordatenbanken unnötig sind. Es ist einfach so, dass die einfachste und zuverlässigste Architektur die Daten oft dort belässt, wo sie bereits vorhanden sind.
Zum Weiterlesen finden Sie die pgvector README sowie deren .NET-Paket, das OpenAI .NET SDK und die Anleitung zu Embeddings, außerdem die Dokumentation zu Microsoft.Extensions.AI.