Postgres'te HNSW dizini: vektör araması için dizin kuyusu

HNSW, Hiyerarşik Gezinilebilir Küçük Dünya anlamına gelir. Bu bir grafik indeksidir: her vektör, üst üste bindirilmiş birkaç katman halinde organize edilmiş, en yakın komşularına bağlı bir düğüm haline gelir. Grafiğin en üstünde, en seyrek katmanda bir arama başlar ve ardından katman katman en alakalı komşulara doğru iner. Böylece arama süresi satır sayısı üzerinden doğrusal değil, neredeyse logaritmik hale gelir.

Pgvector'un diğer dizini IVFFlat farklı çalışır: herhangi bir şeyi dizine eklemeden önce vektör uzayını mevcut bir örnek üzerinde eğitim geçişi tarafından belirlenen listelere böler. HNSW'de bu kısıtlama yoktur, her ekleme doğrudan grafiği zenginleştirir, bu da sürekli büyüyen bir tablo üzerinde çalışmayı kolaylaştırır. Öte yandan, bir HNSW dizini, aynı birimdeki eşdeğer bir IVFFlat'a göre daha fazla bellek tüketir ve oluşturulması daha fazla zaman alır.

pgvector, 0.5.0 sürümünde HNSW desteğini sunuyor. Daha sonraki sürümler, bu kılavuza yararlı özellikler ekler: 2000'den fazla boyutu dizine eklemek için halfvec türü (0.7.0) ve filtrelenmiş sorguların hatırlanmasını iyileştirmek için hnsw.iterative_scan parametresi (0.8.0). Karar vermeden önce pgvector'ü özel bir vektör tabanıyla karşılaştırırsanız, pgvector karşılaştırmamız Pinecone, Weaviate ve Qdrant ile karşılaştırmaları ayrıntılarıyla anlatır.

İlk önce yüklenen pgvector sürümünü onaylayın. Çok eski bir uzantı, bu kılavuzdaki bazı özelliklerin (özellikle halfvec ve hnsw.iterative_scan) sessizce başarısız olmasına neden olur.

SELECT extversion FROM pg_extension WHERE extname = 'vector';

HNSW, pgvector 0.5.0'dan beri mevcuttur. 2000 boyutun ötesindeki yerleştirmeleri indekslemek için gerekli olan halfvectürü en az 0.7.0 sürümünü gerektirir. hnsw.iterative_scan parametresi 0.8.0 sürümünü ister.

Aurabase projelerinde şu soru ortaya çıkmaz: Postgres görüntüsü, hem paylaşılan Postgres kümesine (docker/Postgres.Dockerfile, doğrudan pgvector/pgvector:0.8.6-pg16-bookwormüzerine inşa edilmiştir) hem de proje başına ayrılmış Postgres 16 CNPG örneklerine (docker/Postgres.CNPG.Dockerfile, resmi CloudNativePG görüntüsünden pgvector 0.8.6'yı devralır) pgvector 0.8.6'yı yerleştirir. 24 Ağustos 2026'da her iki Docker dosyasında da doğrulandı.

Sütun türü yalnızca onları oluşturan modele değil, yerleştirmelerinizin boyutuna da bağlıdır. pgvector, depolamada 16.000 boyut sınırıyla vectortüründe klasik bir vektör saklar. Ancak bu türde HNSW dizini oluşturma 2000 boyutla sınırlıdır: bunun ötesinde CREATE INDEX başarısız olur.

Yaygın yerleştirme modelleri genellikle bu eşiği aşar: OpenAI'den text-embedding-3-large veya Google'dan gemini-embedding-2, yerel olarak 3072'ye kadar boyut üretir. Bu vektörleri HNSW ile indekslemek için sütunu halfvec (depolama hassasiyeti yarıya indirildi) değerine dönüştürün; bu da indeksleme sınırını 2000 boyutun çok ötesine taşır.

Aurabase RAG motoru, üretimdeki bu uzlaşmayı göstermektedir: aynı embeddingstablosunun üç ayrı sütununda depolanan üç boyut sınıfı (768, 1536, 3072) desteklenir. 768 ve 1536 numaralı sütunlar doğrudan HNSW'de vectortüründe indekslenir. Sütun 3072, tam olarak 2000 boyut sınırını aşmak için ::halfvec(3072)dönüşümü yoluyla indekslenmiştir.

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;

For details of ingestion (chunking, call to the embedding provider, insertion), see the RAG pipeline tutorial on pgvector.

Minimum sözdizimi, pgvector'un varsayılan değerleriyle birlikte ilk dizin için yeterlidir.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops);

pgvector daha sonra m = 16 ve ef_construction = 64uygular. Bu değerleri açıkça ayarlamak için WITH yan tümcesini kullanın:

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

m parametresi neyi değiştirir?

m grafikteki her düğümün katman başına sağladığı maksimum bağlantı sayısını ayarlar. Daha yüksek bir değer grafiği yoğunlaştırır: hatırlama artar, ancak tüketilen bellek ve yapım süresi de yaklaşık olarak doğrusal olarak artar. Varsayılan (16) çoğu durum için uygundur. Yakın ve uzak komşular arasındaki ayrımın daha ince hale geldiği büyük yerleşimlerde 24 veya 32'ye çıkmak özellikle mantıklıdır.

Ef_construction neyi değiştirir?

ef_construction eklenen her düğüm için dizin oluşturma sırasında keşfedilen aday listesinin boyutunu ayarlar. Daha yüksek bir değer, daha uzun inşaat süresi pahasına nihai grafiğin kalitesini, dolayısıyla potansiyel geri çağırmayı artırır. m'den farklı olarak bu parametrenin sorgu zamanında maliyeti yoktur: tek seferlik bir yatırımdır ve yalnızca dizin oluşturulduğunda ödenir.

Aynı tablodaki çeşitli boyut sınıfları için kısmi dizinler

Bir tablo birden fazla vektör sütununu (Aurabase'in yaptığı gibi boyut sınıfı başına bir tane) depoladığında, her sütunu bir WHERE colonne IS NOT NULLcümlesiyle ayrı ayrı indeksleyin. Bu kısmi indeks, belirli bir hat tarafından kullanılmayan sınıflar için boş satırların indekslenmesini önler, bu da indeksin boyutunu azaltır ve geri çağırmada herhangi bir maliyete yol açmadan inşasını hızlandırır.

Operatör sınıfı seçimi (vector_cosine_ops, vector_l2_ops veya vector_ip_ops), yerleştirme modelinin eğitildiği metriğe karşılık gelmelidir. En yeni metin gömme modelleri kosinüs benzerliği için eğitilmiştir: vector_cosine_ops (veya bir dönüşüm sütununda halfvec_cosine_ops) bu nedenle en güvenli varsayılan seçimdir.

ef_search dizin oluşturulduğunda değil, her sorguda ayarlanır. Arama sırasında keşfedilen adayların listesinin boyutunu belirler: ne kadar yüksek olursa, daha uzun gecikme pahasına geri çağırma da o kadar iyi olur. pgvector varsayılan değerini 40 olarak ayarlar.

SET LOCAL hnsw.ef_search = 100;

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

Bir sorgu, vektör aramasını dizini taradıktan sonra uygulanan bir WHERE filtresiyle (bir ad alanı, kiracı veya başka herhangi bir meta veri kriteri üzerinde) birleştirdiğinde 40 nadiren yeterlidir. HNSW taraması ef_search ham adayları geri getirir, ardından filtre bunların bir kısmını atar. Çok az sayıda aday hayatta kalırsa, son LIMIT yetersiz doldurulmuş olur.

Bu nedenle Aurabase RAG motoru, sabit 40 değerini korumak yerine ef_search öğesini istenen top_kdeğerine göre dinamik olarak genişletir: ef = max(top_k × 4, 64). En yakın 5 sonucun aranması için ef_search = 64kullanılır; ilk 50 için yapılan aramada ef_search = 200kullanılır. Bu formül, başka bir geri çağırma/gecikme dengelemesi gerektiren dağıtımlar için ortam değişkenine göre ayarlanabilir olmaya devam eder.

pgvector 0.8 aynı problem için ikinci bir kaldıraç ekler: hnsw.iterative_scan. strict_order veya relaxed_ordermodunda, arama, sabit bir aday listesi üzerinde durmak yerine, filtrelemeden sonra yeterli sonuç toplayana kadar aramasını kademeli olarak genişletir. Aurabase bunu varsayılan olarak strict_order'de etkinleştirir ancak çağrıyı bir kayıt noktasında korur. Bu parametrenin mevcut olmadığı pgvector'un 0.8'den önceki bir sürümünde sorgu başarısız olmak yerine azaltılmış modda devam eder.

Bu HNSW dizini, tüm RAG ardışık düzeninin yalnızca bir parçasıdır: parçalama, yerleştirme oluşturma, alma ve ardından arama. adım adım öğreticimiz bu hattı ilk eklemeden benzerlik sorgusuna kadar pgvector üzerinde uçtan uca oluşturur. teknik belgeleri ayrıca Aurabase'in Postgres üzerine kurulu tüm yerel yapay zeka yeteneklerinin ayrıntılarını verir.