Aurabase's native vector search (RAG, pgvector, embeddings) relies on this same indexing mechanism, described in detail on the Native AI on Postgrespage. This guide assumes a Postgres table with pgvector already installed, a column of type vector, and at least a few thousand rows. Below, a simple sequential scan is often faster than an approximate index.
Temeller
- HNSW, IVFFlat'tan farklı olarak herhangi bir eğitim aşaması gerektirmez: dizin eklemeler üzerine oluşturulmuştur ve pgvector sürümü 0.5.0'dan beri mevcuttur.
- İki parametre, yapım aşamasında endeksin kalitesini belirler:
m(düğüm başına bağlantı, varsayılan 16) veef_construction(yapım aşamasında arama genişliği, varsayılan 64). - Üçüncü bir parametre olan
hnsw.ef_search(pgvector varsayılan: 40), geri çağırma ve gecikmeyi dengelemek için dizini yeniden oluşturmadan her istek için ayarlanır. - pgvector,
vectortipindeki HNSW indekslemeyi 2000 boyuta kadar sınırlar. Bunun ötesinde (örneğin 3072 boyuta sahip bir yerleştirme), indekslemek içinhalfvec'ye bir dönüşüm gereklidir. - pgvector 0.8.6, Aurabase Postgres kiracı görüntüsüne katıştırılmış sürümdür ve 24 Ağustos 2026'da doğrudan Dockerfile'da doğrulanmıştır.
pgvector içindeki HNSW dizini nedir?
HNSW Hiyerarşik Gezinilebilir Küçük Dünya anlamına gelir. Bu bir grafik indeksidir: her vektör, üst üste bindirilmiş birkaç katman halinde düzenlenmiş, 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 öğesinin diğer dizini olan IVFFlat farklı şekilde çalışır: herhangi bir şeyi dizine eklemeden önce vektör uzayını mevcut bir örnek üzerindeki eğitim geçişi tarafından belirlenen listelere böler. HNSW bu kısıtlamaya sahip değildir, 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'yi özel bir vektör tabanıyla karşılaştırırsanız, karşılaştırmamız pgvector ile Pinecone, Weaviate ve Qdrant takasların ayrıntılarını verir.
Dizini oluşturmadan önce pgvector sürümünüzü kontrol edin
Önce yüklü olan pgvector sürümünü doğrulayı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ümesinde (docker/Postgres.Dockerfile, doğrudan pgvector/pgvector:pg18 üzerine kuruludur) hem de Postgres 18 üzerinde pgvector 0.8.6 gömer. Proje başına ayrılmış CNPG örnekler (docker/Postgres.CNPG.Dockerfile, pgvector 0.8.6'yı resmi CloudNativePG görüntüsünden devralır). 24 Ağustos 2026'da her iki Docker dosyasında da doğrulandı.
Gömmelerinizin boyutuna göre doğru sütun türünü seçin
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 indeksleme 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.
| Boyutlar | Sütun | HNSW vektör üzerinde | Döküm gerektirir |
|---|---|---|---|
| 768 | yerleştirme_768 | Evet | Hayır |
| 1536 | yerleştirme_1536 | Evet | Hayır |
| 3072 | yerleştirme_3072 | Hayır (> 2000 loş) | Evet, cast::halfvec(3072) |
Aurabase RAG motoru, üretimdeki bu uzlaşmayı göstermektedir: aynı embeddingstablosunun üç farklı sütununda depolanan üç boyut sınıfı (768, 1536, 3072) desteklenir. 768 ve 1536 numaralı sütunlar doğrudan HNSW türünde 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.
Dizini m ve ef_construction parametreleriyle oluşturun
Minimum sözdizimi, varsayılan değerler olan pgvector ile ilk dizin için yeterlidir.
CREATE INDEX ON items
USING hnsw (embedding vector_cosine_ops);
pgvector daha sonra m = 16 ve ef_construction = 64 uygular. 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);
Büyük bir tabloda HNSW dizini oluşturmadan önce, oturum için maintenance_work_mem değerini geçici olarak artırın: bu, pgvector belgelerine göre, inşaat süresini kısaltmanın en doğrudan aracıdır.
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 bir kez ödenir.
Aynı tablodaki çeşitli boyut sınıfları için kısmi dizinler
Bir tablo birden fazla vektör sütununu (Aurabase'nin yaptığı gibi boyut sınıfı başına bir tane) depoladığında, her sütunu bir WHERE colonne IS NOT NULLcümlesiyle ayrı ayrı dizinleyin. 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'ü sorgu zamanında ayarlayın
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ını 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_k değerine göre dinamik olarak genişletir: ef = max(top_k × 4, 64). En yakın 5 sonucun aranması için ef_search = 64 kullanılır; ilk 50 için yapılan aramada ef_search = 200 kullanı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 listesinde durmak yerine, filtrelemeden sonra yeterli sonuç toplayana kadar aramasını kademeli olarak genişletir. Aurabase bunu varsayılan olarak strict_order içinde etkinleştirir, ancak çağrıyı bir kayıt noktasında korur. Bu parametrenin mevcut olmadığı pgvector 0.8'den önceki bir sürümde, sorgu başarısız olmak yerine azaltılmış modda devam eder.
RAG boru hattının tamamını oluşturun
Bu HNSW dizini, 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'nin Postgres üzerine kurulu tüm yerel AI yeteneklerinin ayrıntılarını verir.