HNSW-index in Postgres: indexbron voor zoeken naar vectoren

HNSW staat voor Hiërarchisch Navigeerbare Kleine Wereld. Het is een grafiekindex: elke vector wordt een knooppunt dat is verbonden met zijn dichtstbijzijnde buren, georganiseerd in verschillende over elkaar heen liggende lagen. Een zoekopdracht begint bovenaan de grafiek, op de dunste laag, en gaat vervolgens laag voor laag naar de meest relevante buren. De zoektijd wordt dus bijna logaritmisch en niet lineair over het aantal regels.

IVFFlat, de andere index van pgvector, werkt anders: het verdeelt de vectorruimte in lijsten die worden bepaald door een trainingspas op een bestaand monster, voordat het iets kan indexeren. HNSW heeft deze beperking niet; elke invoeging verrijkt de grafiek direct, waardoor het eenvoudiger wordt om te werken op een tafel die voortdurend groeit. Aan de andere kant verbruikt een HNSW-index meer geheugen en kost het meer tijd om te bouwen dan een gelijkwaardige IVFFlat op hetzelfde volume.

pgvector introduceert HNSW-ondersteuning in versie 0.5.0. Latere versies voegen nuttige mogelijkheden toe aan deze handleiding: het type halfvec (0.7.0) om verder dan 2000 dimensies te indexeren, en de parameter hnsw.iterative_scan (0.8.0) om het terugroepen van gefilterde query's te verbeteren. Als u pgvector vergelijkt met een speciale vectorbasis voordat u een beslissing neemt, beschrijft onze vergelijking pgvector versus Pinecone, Weaviate en Qdrant de afwegingen.

Bevestig eerst welke versie van pgvector is geïnstalleerd. Een extensie die te oud is, zorgt ervoor dat sommige functies in deze handleiding stilzwijgend mislukken, met name halfvec en hnsw.iterative_scan.

SELECT extversion FROM pg_extension WHERE extname = 'vector';

HNSW bestaat sinds pgvector 0.5.0. Voor het type halfvec, nodig om inbeddingsvormen groter dan 2000 dimensies te indexeren, is minimaal versie 0.7.0 vereist. De parameter hnsw.iterative_scan vraagt ​​om versie 0.8.0.

Bij Aurabase-projecten doet de vraag zich niet voor: de Postgres-image sluit pgvector 0.8.6 in, zowel op het gedeelde Postgres-cluster (docker/Postgres.Dockerfile, rechtstreeks gebouwd op pgvector/pgvector:0.8.6-pg16-bookworm) als op de Postgres 16 CNPG-instanties die per project zijn toegewezen (docker/Postgres.CNPG.Dockerfile, die pgvector 0.8.6 overneemt van de officiële CloudNativePG-image). Geverifieerd in beide Dockerfiles op 24 augustus 2026.

Het kolomtype is afhankelijk van de grootte van uw insluitingen, en niet alleen van het model dat ze genereert. pgvector slaat een klassieke vector op in het type vector, met een maximum van 16.000 dimensies in opslag. Maar HNSW-indexering op dit type is beperkt tot 2000 dimensies: daarbuiten mislukt CREATE INDEX.

Veelgebruikte insluitingsmodellen overschrijden deze drempel vaak: text-embedding-3-large van OpenAI of gemini-embedding-2 van Google produceren native maximaal 3072 dimensies. Om deze vectoren met HNSW te indexeren, cast u de kolom naar halfvec (opslagprecisie gehalveerd), waardoor de indexeringslimiet ruim boven de 2000 dimensies ligt.

De Aurabase RAG-engine illustreert dit compromis in de productie: er worden drie dimensieklassen ondersteund (768, 1536, 3072), opgeslagen in drie afzonderlijke kolommen van dezelfde embeddings-tabel. Kolommen 768 en 1536 worden rechtstreeks in HNSW geïndexeerd op het type vector. Kolom 3072 wordt geïndexeerd via een ::halfvec(3072)-cast, precies om de dimensielimiet van 2000 te omzeilen.

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;

Voor details over opname (chunking, aanroep van de insluitingsprovider, invoeging), zie de RAG-pijplijntutorial op pgvector.

De minimale syntaxis is voldoende voor een eerste index, met de standaardwaarden van pgvector.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops);

pgvector past vervolgens m = 16 en ef_construction = 64toe. Om deze waarden expliciet aan te passen, gebruik je de WITH-clausule:

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

Wat verandert de parameter m?

m stelt het maximale aantal verbindingen in dat elk knooppunt in de grafiek per laag onderhoudt. Een hogere waarde verdicht de grafiek: de herinnering neemt toe, maar het verbruikte geheugen en de bouwtijd nemen ook toe, ongeveer lineair. De standaardinstelling (16) is geschikt voor de meeste gevallen. Een stijging naar 24 of 32 is vooral gerechtvaardigd bij grote inbedding, waar het onderscheid tussen nabije en verre buren kleiner wordt.

Wat verandert ef_construction?

ef_construction stelt de grootte in van de kandidatenlijst die wordt onderzocht tijdens de indexconstructie, voor elk ingevoegd knooppunt. Een hogere waarde verbetert de kwaliteit van de uiteindelijke grafiek, en dus de potentiële terugroepactie, ten koste van een langere bouwtijd. In tegenstelling tot mbrengt deze parameter geen kosten met zich mee op het moment van de query: het is een eenmalige investering, die slechts één keer wordt betaald wanneer de index wordt gemaakt.

Gedeeltelijke indexen voor verschillende dimensieklassen in dezelfde tabel

Wanneer een tabel meerdere vectorkolommen opslaat (één per dimensieklasse, zoals Aurabase doet), indexeer dan elke kolom afzonderlijk met een WHERE colonne IS NOT NULL-clausule. Deze gedeeltelijke index vermijdt het indexeren van lege regels voor klassen die niet door een bepaalde regel worden gebruikt, waardoor de omvang van de index wordt verkleind en de constructie ervan wordt versneld zonder dat dit iets kost bij het terugroepen.

De keuze van de operatorklasse (vector_cosine_ops, vector_l2_ops of vector_ip_ops) moet overeenkomen met de metriek waarop het insluitingsmodel is getraind. De meest recente modellen voor het insluiten van tekst zijn getraind op cosinusovereenkomst: vector_cosine_ops (of halfvec_cosine_ops op een cast-kolom) is daarom de veiligste standaardkeuze.

ef_search wordt ingesteld voor elke query, niet wanneer de index wordt gebouwd. Het bepaalt de omvang van de lijst met kandidaten die tijdens de zoekopdracht worden onderzocht: hoe hoger deze is, hoe beter de terugroepactie, ten koste van een langere latentie. pgvector stelt de standaardwaarde in op 40.

SET LOCAL hnsw.ef_search = 100;

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

40 is zelden genoeg zodra een zoekopdracht vectorzoekopdrachten combineert met een WHERE-filter dat wordt toegepast na het scannen van de index (op een naamruimte, een tenant of een ander metadatacriterium). De HNSW-scan brengt ef_search onbewerkte kandidaten terug, waarna het filter een deel ervan verwijdert. Als er te weinig kandidaten overleven, wordt de laatste LIMIT onderbezet.

De Aurabase RAG-engine breidt daarom ef_search dynamisch uit volgens de gevraagde top_k, in plaats van de vaste waarde van 40 te behouden: ef = max(top_k × 4, 64). Een zoekopdracht naar de 5 dichtstbijzijnde resultaten gebruikt ef_search = 64; een zoekopdracht naar de top 50 gebruikt ef_search = 200. Deze formule blijft per omgevingsvariabele aanpasbaar voor implementaties waarvoor een andere afweging tussen terugroeping en latentie nodig is.

pgvector 0.8 voegt een tweede hefboom toe voor hetzelfde probleem: hnsw.iterative_scan. In de modus strict_order of relaxed_orderbreidt de zoekopdracht de zoekopdracht geleidelijk uit totdat na het filteren voldoende resultaten worden verzameld, in plaats van te stoppen bij een vaste lijst met kandidaten. Aurabase activeert het standaard in strict_order, maar beschermt de oproep in een savepoint. Op een versie van pgvector vóór 0.8, waar deze parameter niet bestaat, wordt de query voortgezet in een gedegradeerde modus in plaats van te mislukken.

Deze HNSW-index is slechts een onderdeel van de volledige RAG-pijplijn: chunking, genereren van inbedden, opname en vervolgens zoeken. Onze stapsgewijze zelfstudie bouwt deze pijplijn end-to-end op pgvector, vanaf de eerste invoeging tot aan de gelijkenisquery. De technische documentatie beschrijft ook alle native AI-mogelijkheden van Aurabase, gebouwd op Postgres.