HNSW-Index in Postgres: Indexbrunnen für die Vektorsuche

HNSW steht für Hierarchical Navigable Small World. Es handelt sich um einen Diagrammindex: Jeder Vektor wird zu einem Knoten, der mit seinen nächsten Nachbarn verbunden ist und in mehreren übereinander liegenden Schichten organisiert ist. Eine Suche beginnt oben im Diagramm auf der dünnsten Ebene und geht dann Schicht für Schicht nach unten zu den relevantesten Nachbarn. Die Suchzeit wird somit nahezu logarithmisch und nicht linear über die Anzahl der Zeilen.

IVFFlat, der andere Index von pgvector, funktioniert anders: Er unterteilt den Vektorraum in Listen, die durch einen Trainingsdurchlauf an einer vorhandenen Stichprobe bestimmt werden, bevor er irgendetwas indizieren kann. Bei HNSW gibt es diese Einschränkung nicht. Jede Einfügung bereichert das Diagramm direkt, was die Arbeit an einer kontinuierlich wachsenden Tabelle vereinfacht. Andererseits verbraucht ein HNSW-Index mehr Speicher und benötigt mehr Zeit für die Erstellung als ein gleichwertiger IVFFlat auf demselben Volume.

pgvector führt HNSW-Unterstützung in Version 0.5.0 ein. Spätere Versionen fügen diesem Handbuch nützliche Funktionen hinzu: den Typ halfvec (0.7.0) zur Indizierung über 2000 Dimensionen hinaus und den Parameter hnsw.iterative_scan (0.8.0) zur Verbesserung des Abrufs bei gefilterten Abfragen. Wenn Sie pgvector mit einer dedizierten Vektorbasis vergleichen, bevor Sie sich entscheiden, finden Sie in unserem -Vergleich pgvector vs. Pinecone, Weaviate und Qdrant Einzelheiten zu den Kompromissen.

Bestätigen Sie zuerst die installierte Version von pgvector. Eine zu alte Erweiterung führt dazu, dass einige Funktionen in diesem Handbuch stillschweigend fehlschlagen, insbesondere halfvec und hnsw.iterative_scan.

SELECT extversion FROM pg_extension WHERE extname = 'vector';

HNSW existiert seit pgvector 0.5.0. Der Typ halfvec, der zum Indizieren von Einbettungen über 2000 Dimensionen hinaus erforderlich ist, erfordert mindestens Version 0.7.0. Der Parameter hnsw.iterative_scan fordert Version 0.8.0 an.

Bei Aurabase-Projekten stellt sich die Frage nicht: Das Postgres-Image bettet pgvector 0.8.6 ein, sowohl im gemeinsam genutzten Postgres-Cluster (docker/Postgres.Dockerfile, direkt auf pgvector/pgvector:0.8.6-pg16-bookwormaufgebaut) als auch auf den 16 CNPG-Instanzen von Postgres, die pro Projekt dediziert sind (docker/Postgres.CNPG.Dockerfile, das pgvector 0.8.6 vom offiziellen CloudNativePG-Image erbt). Verifiziert in beiden Docker-Dateien am 24. August 2026.

Der Spaltentyp hängt von der Größe Ihrer Einbettungen ab, nicht nur vom Modell, das sie generiert. pgvector speichert einen klassischen Vektor im Typ vectormit einer Speicherkapazität von maximal 16.000 Dimensionen. Die HNSW-Indizierung für diesen Typ ist jedoch auf 2000 Dimensionen beschränkt: Darüber hinaus schlägt CREATE INDEX fehl.

Gängige Einbettungsmodelle überschreiten diesen Schwellenwert häufig: text-embedding-3-large von OpenAI oder gemini-embedding-2 von Google erzeugen nativ bis zu 3072 Dimensionen. Um diese Vektoren mit HNSW zu indizieren, wandeln Sie die Spalte in halfvec um (Speichergenauigkeit halbiert), wodurch die Indizierungsgrenze weit über 2000 Dimensionen hinausgeht.

Die Aurabase RAG-Engine veranschaulicht diesen Kompromiss in der Produktion: Drei Dimensionsklassen werden unterstützt (768, 1536, 3072), gespeichert in drei unterschiedlichen Spalten derselben embeddings-Tabelle. Die Spalten 768 und 1536 werden direkt in HNSW auf den Typ vectorindiziert. Spalte 3072 wird über eine ::halfvec(3072)-Umwandlung indiziert, genau um die 2000-Dimensionsbeschränkung zu umgehen.

CREATE INDEX idx_embeddings_vec_768 ON embeddings
  USING hnsw (embedding_768 vector_cosine_ops)
  WHERE embedding_768 IS NOT NULL;

CREATE INDEX idx_embeddings_vec_1536 ON embeddings
  USING hnsw (embedding_1536 vector_cosine_ops)
  WHERE embedding_1536 IS NOT NULL;

CREATE INDEX idx_embeddings_vec_3072 ON embeddings
  USING hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  WHERE embedding_3072 IS NOT NULL;

Einzelheiten zur Aufnahme (Chunking, Aufruf des Einbettungsanbieters, Einfügen) finden Sie im RAG-Pipeline-Tutorial zu pgvector.

Für einen ersten Index reicht die minimale Syntax mit den Standardwerten von pgvector aus.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops);

pgvector wendet dann m = 16 und ef_construction = 64an. Um diese Werte explizit anzupassen, verwenden Sie die WITH-Klausel:

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 24, ef_construction = 100);

Was ändert sich durch den Parameter m?

m legt die maximale Anzahl von Verbindungen fest, die jeder Knoten im Diagramm pro Schicht verwaltet. Ein höherer Wert verdichtet das Diagramm: Der Rückruf nimmt zu, aber auch der Speicherverbrauch und die Erstellungszeit nehmen annähernd linear zu. Der Standardwert (16) ist für die meisten Fälle geeignet. Eine Erhöhung auf 24 oder 32 ist insbesondere bei großen Einbettungen gerechtfertigt, wo die Unterscheidung zwischen nahen und entfernten Nachbarn feiner wird.

Was ändert sich durch ef_construction?

ef_construction legt die Größe der Kandidatenliste fest, die während der Indexerstellung für jeden eingefügten Knoten untersucht wird. Ein höherer Wert verbessert die Qualität des endgültigen Diagramms und damit den potenziellen Rückruf, allerdings auf Kosten einer längeren Erstellungszeit. Im Gegensatz zu mfallen für diesen Parameter zum Zeitpunkt der Abfrage keine Kosten an: Es handelt sich um eine einmalige Investition, die nur einmal bei der Indexerstellung bezahlt wird.

Teilindizes für mehrere Dimensionsklassen in derselben Tabelle

Wenn eine Tabelle mehrere Vektorspalten speichert (eine pro Dimensionsklasse, wie dies bei Aurabase der Fall ist), indizieren Sie jede Spalte separat mit einer WHERE colonne IS NOT NULL-Klausel. Dieser Teilindex vermeidet die Indizierung leerer Zeilen für Klassen, die nicht von einer bestimmten Zeile verwendet werden, wodurch die Größe des Index reduziert und seine Erstellung beschleunigt wird, ohne dass beim Abruf Kosten entstehen.

Die Auswahl der Operatorklasse (vector_cosine_ops, vector_l2_ops oder vector_ip_ops) muss der Metrik entsprechen, auf der das Einbettungsmodell trainiert wurde. Die meisten neueren Texteinbettungsmodelle sind auf Kosinusähnlichkeit trainiert: vector_cosine_ops (oder halfvec_cosine_ops in einer umgewandelten Spalte) ist daher die sicherste Standardwahl.

ef_search wird bei jeder Abfrage festgelegt, nicht beim Erstellen des Index. Es legt die Größe der Kandidatenliste fest, die während der Suche untersucht wird: Je höher sie ist, desto besser ist der Rückruf, allerdings auf Kosten einer längeren Latenz. pgvector setzt seinen Standardwert auf 40.

SET LOCAL hnsw.ef_search = 100;

SELECT id, content
FROM embeddings
ORDER BY embedding <=> '[...]'::vector
LIMIT 10;

40 reicht selten aus, sobald eine Abfrage die Vektorsuche mit einem WHERE-Filter kombiniert, der nach dem Scannen des Index angewendet wird (auf einen Namespace, einen Mandanten oder ein anderes Metadatenkriterium). Der HNSW-Scan bringt ef_search Rohkandidaten zurück, dann verwirft der Filter einen Teil davon. Wenn zu wenige Kandidaten überleben, ist das endgültige LIMIT am Ende unterfüllt.

Die Aurabase RAG-Engine erweitert daher ef_search dynamisch entsprechend dem angeforderten top_k, anstatt den festen Wert von 40 beizubehalten: ef = max(top_k × 4, 64). Eine Suche nach den 5 nächstgelegenen Ergebnissen verwendet ef_search = 64; Eine Suche nach den Top 50 verwendet ef_search = 200. Diese Formel bleibt pro Umgebungsvariable für Bereitstellungen anpassbar, die einen anderen Kompromiss zwischen Rückruf und Latenz erfordern.

pgvector 0.8 fügt einen zweiten Hebel für dasselbe Problem hinzu: hnsw.iterative_scan. Im strict_order- oder relaxed_order-Modus erweitert die Suche ihre Suche schrittweise, bis nach dem Filtern genügend Ergebnisse gesammelt werden, anstatt bei einer festen Kandidatenliste anzuhalten. Aurabase aktiviert es standardmäßig in strict_order, schützt den Aufruf jedoch in einem Sicherungspunkt. Bei einer Version von pgvector vor 0.8, bei der dieser Parameter nicht vorhanden ist, wird die Abfrage im herabgesetzten Modus fortgesetzt und schlägt nicht fehl.

Dieser HNSW-Index ist nur ein Teil der gesamten RAG-Pipeline: Chunking, Einbettungsgenerierung, Aufnahme und dann Suche. Unser Schritt-für-Schritt-Tutorial baut diese Pipeline durchgängig auf pgvector auf, von der ersten Einfügung bis zur Ähnlichkeitsabfrage. Die technische Dokumentation beschreibt außerdem alle nativen KI-Funktionen von Aurabase, die auf Postgres basieren.