pgvector einrichten: Ähnlichkeitssuche für Firmendokumente

Wer PostgreSQL ohnehin betreibt, kann die Vektorsuche für Dokumente in derselben Datenbank einrichten. Dieser Leitfaden führt von der Installation von pgvector bis zur ersten Ähnlichkeitsabfrage.

Niklas Schult4 Min. Lesezeit

Illustration: Ein Aktenschrank mit offener Schublade, darüber ein Magnet an einer Schnur, der nahe beieinanderstehende Karten anzieht.

Was Sie am Ende haben und was Sie brauchen

Am Ende läuft in Ihrer bestehenden PostgreSQL-Datenbank die Erweiterung pgvector. Sie haben eine Tabelle für Dokumentabschnitte mit einer Vektorspalte, speichern darin Embeddings und fragen die ähnlichsten Abschnitte zu einem Suchvektor ab. Die Grundlage ist die README von pgvector, die Postgres ab Version 13 unterstützt.

Vorab benötigen Sie Zugriff auf den Datenbankserver, die Entwicklungsdateien Ihrer Postgres-Version und ein Embedding-Modell, das Ihre Texte in Zahlenvektoren umrechnet. Die README beschreibt nur die Datenbankseite und lässt offen, welches Modell Sie wählen. Für das Beispiel verwenden wir drei Dimensionen, damit die Abfragen lesbar bleiben. Echte Modelle liefern deutlich mehr Dimensionen, und die Spaltendefinition muss dazu passen.

Der Vorteil dieses Ansatzes liegt darin, dass die Vektoren neben den übrigen Daten liegen. Die README nennt unter anderem Transaktionssicherheit, Wiederherstellung zu einem beliebigen Zeitpunkt und Verknüpfungen mit anderen Tabellen als Eigenschaften, die Sie von Postgres weiterhin erhalten. Sie brauchen also keinen zusätzlichen Dienst, den Sie getrennt betreiben, sichern und überwachen müssten.

pgvector installieren und aktivieren

Unter Linux und Mac übersetzen Sie die Erweiterung aus dem Quellcode. Die folgenden Befehle laden die in der README genannte Version 0.8.7, bauen sie und installieren sie. Bei Bedarf braucht der letzte Schritt erhöhte Rechte.

Shell
cd /tmp
git clone --branch v0.8.7 https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

Wer Container einsetzt, kann stattdessen das fertige Image ziehen. Der Tag nennt die Postgres-Hauptversion, hier 18, und Sie starten das Image wie das normale Postgres-Image. Für Debian und Ubuntu gibt es außerdem Pakete aus dem PostgreSQL-APT-Repository.

Shell
docker pull pgvector/pgvector:pg18-trixie

Danach aktivieren Sie die Erweiterung. Das ist einmal je Datenbank nötig, in der Sie die Vektorsuche nutzen wollen.

Text
CREATE EXTENSION vector;

Tabelle anlegen und Embeddings speichern

Die Tabelle nimmt je Zeile einen Textabschnitt samt Vektor auf. Die Zahl in vector(3) legt die Dimensionen fest und muss der Ausgabe Ihres Embedding-Modells entsprechen. Spalten wie der Dateiname helfen später, einen Treffer dem passenden Dokument zuzuordnen.

Text
CREATE TABLE dokumente (
  id bigserial PRIMARY KEY,
  dateiname text,
  inhalt text,
  embedding vector(3)
);

Das Einfügen funktioniert mit gewöhnlichem INSERT, wobei Sie den Vektor als Text in eckigen Klammern übergeben. Für große Bestände nennt die README COPY mit binärem Format als schnelleren Weg. Bestehende Zeilen ändern Sie mit UPDATE, gelöscht wird mit DELETE.

Text
INSERT INTO dokumente (dateiname, inhalt, embedding) VALUES
  ('vertrag_a.pdf', 'Kündigungsfristen im Rahmenvertrag', '[1,2,3]'),
  ('handbuch.pdf', 'Wartung der Fräsmaschine', '[4,5,6]');

Die README zeigt auch, wie Sie eine Vektorspalte zu einer bestehenden Tabelle hinzufügen, mit ALTER TABLE und ADD COLUMN. Das hilft, wenn Ihre Dokumentabschnitte bereits in einer Tabelle liegen. Wer Zeilen je nach Stand neu anlegen oder aktualisieren will, kann einen Upsert mit ON CONFLICT verwenden. Laden Sie große Bestände vor dem Anlegen der Indizes, denn das beschleunigt laut README das Ganze.

Ähnlichkeitssuche abfragen und beschleunigen

Die Abfrage sortiert nach Abstand zum Suchvektor und begrenzt die Trefferzahl. Der Operator <=> steht für die Kosinusdistanz, die bei Textembeddings häufig gewählt wird. Daneben gibt es <-> für den euklidischen Abstand und <#> für das negative innere Produkt.

Text
SELECT dateiname, inhalt, 1 - (embedding <=> '[3,1,2]') AS aehnlichkeit
FROM dokumente
ORDER BY embedding <=> '[3,1,2]'
LIMIT 5;

Ohne Index sucht pgvector exakt und liefert vollständige Treffer. Bei vielen Abschnitten legen Sie einen HNSW-Index an, der ungefähr sucht und dafür schneller antwortet. Der Operatorsatz im Index muss zur Abstandsfunktion der Abfrage passen, hier vector_cosine_ops. Am besten legen Sie Indizes erst nach dem ersten Laden der Daten an.

Text
CREATE INDEX ON dokumente USING hnsw (embedding vector_cosine_ops);

Neben HNSW unterstützt pgvector den Indextyp IVFFlat. Laut README baut er schneller und braucht weniger Speicher, liefert aber bei Geschwindigkeit und Trefferqualität schlechtere Werte. Für den Einstieg genügt HNSW. Im Produktivbetrieb legen Sie Indizes mit CREATE INDEX CONCURRENTLY an, damit schreibende Zugriffe nicht blockiert werden.

Prüfen, Stolpersteine und Betrieb

Ob die Erweiterung installiert ist, zeigt die Versionsabfrage. Ob eine Suche den Index nutzt, sehen Sie im Plan. Ein Abgleich zwischen exakter und indizierter Suche zeigt außerdem, wie viele Treffer die Näherung verliert.

Text
SELECT extversion FROM pg_extension WHERE extname = 'vector';
EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM dokumente ORDER BY embedding <=> '[3,1,2]' LIMIT 5;

Die README nennt typische Stolpersteine. Eine Abfrage nutzt den Index nur mit ORDER BY und LIMIT, und die Sortierung muss direkt der Abstandsoperator in aufsteigender Reihenfolge sein. Ein Ausdruck wie 1 minus Distanz mit DESC verhindert den Indexeinsatz. Nach dem Anlegen eines HNSW-Index können weniger Treffer erscheinen, weil hnsw.ef_search standardmäßig 40 beträgt. Filter wie eine Abteilung wirken erst nach dem Indexscan, dagegen helfen iterative Scans über hnsw.iterative_scan. Ein HNSW-Index speichert zudem nur Vektoren bis 2.000 Dimensionen, und NULL-Vektoren werden nicht indiziert. Fehlt beim Kompilieren die Datei postgres.h, fehlen die Entwicklungsdateien Ihrer Postgres-Version.

Im Betrieb liegen die Vektoren in Ihrer Datenbank, also gelten Ihre bestehenden Sicherungen, die Replikation und Ihre Zugriffsrechte. Weil sich Vektoren aus Dokumenten ableiten, sollten Sie klären, wer diese Tabelle lesen darf, und das mit Ihrem Datenschutzkonzept abstimmen, siehe Sicherheit und Datenschutz. Updates der Erweiterung spielen Sie mit ALTER EXTENSION vector UPDATE je Datenbank ein.

Wer nicht selbst Embeddings erzeugen, Rechte abbilden und Quellen anbinden will, findet bei der Wissensmanagement-Software mit KI einen fertigen Weg. souveraen.ai nennt zu jeder Antwort die Fundstelle und läuft gehostet in Deutschland oder On-Premise. Für eigene Anwendungen gibt es die Entwickler-API, und zum Thema lokale KI finden Sie weitere Hinweise.

Quellen

Weitere Beiträge

Alle Beiträge

KI-API-Zugänge bei Resellern: Was die Dragos-Tests zeigen

Sicherheitsforscher von Dragos haben mit rund zwei Millionen Testanfragen gezeigt, dass Zwischenhändler und kompromittierte Anbieter Anfragen an KI-Modelle mitlesen. Wer KI per Schnittstelle nutzt, sollte daher klären, über wen die eigenen Daten tatsächlich laufen.

Datenschutz4 Min.

Text Generation Inference mit Docker selbst betreiben

Mit Text Generation Inference betreiben Sie ein offenes Sprachmodell als Container auf einem eigenen Server. Anfragen bleiben im Firmennetz, sodass keine Texte an einen Cloud-Anbieter gehen.

Anleitung4 Min.

Haftung bei Cloud-Ausfall: Wer trägt das Risiko?

Der Ausfall von Exchange Online und Outlook am 12. November 2026 dauerte etwa 36 Stunden und traf viele Betriebe. Wer dafür einstehen muss, betrifft jede Firma, die Cloud- und KI-Dienste nutzt.

Regulierung4 Min.

Testen Sie es mit Ihren eigenen Dokumenten.

3 Tage kostenlos, danach ab 24,90 € je Nutzer und Monat. Monatlich kündbar.

3 Tage kostenlos, danach ab 24,90 € je Nutzer und Monat.3 Tage kostenlos
3 Tage kostenlos testen