YENİPublication of @aurabase/aurabase-js v0.7.5 NPM Packages & Rust Crate v0.1.2Değişiklik günlüğüne bakın →

Yerel yapay zeka · 9 dk. okuma

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

Affane Daylami · Fondateur · 6 Nisan 2026

Bloga geri dön

HNSW, pgvector'nin Postgres üzerinde benzerlik vektörü araması için önerdiği indeksleme algoritmasıdır. Bu kılavuz, düzgün şekilde ayarlanmış bir HNSW dizininin nasıl oluşturulacağını gösterir. Üç seçenek önemlidir: yerleştirmelerinizin boyutuna göre sütun türü, oluşturma sırasında m ve ef_construction parametreleri ve geri çağırma ve gecikmeyi hakemleştirmek için her istekte ef_search.

Bu sayfa otomatik olarak çevrildi. İngilizce versiyonu yetkilidir.

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) ve ef_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, vector tipindeki HNSW indekslemeyi 2000 boyuta kadar sınırlar. Bunun ötesinde (örneğin 3072 boyuta sahip bir yerleştirme), indekslemek için halfvec'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.
#
Anla

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.

#
1. Adım

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.

psqlsql
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ı.

#
2. Adım

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.

BoyutlarSütunHNSW vektör üzerindeDöküm gerektirir
768yerleştirme_768EvetHayır
1536yerleştirme_1536EvetHayır
3072yerleştirme_3072Hayı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.

migration.sqlsql
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.

#
3. Adım

Dizini m ve ef_construction parametreleriyle oluşturun

Minimum sözdizimi, varsayılan değerler olan pgvector ile ilk dizin için yeterlidir.

psqlsql
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:

psqlsql
CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 24, ef_construction = 100);
Büyük bir inşaatı hızlandırın

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.

#
4. Adım

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.

psqlsql
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.

#
Daha ileri git

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.

#
Sıkça Sorulan Sorular

SSS

HNSW veya IVFFlat: pgvector ile hangisini seçmelisiniz?+
HNSW, üretimdeki vektör arama durumlarının büyük çoğunluğu için uygundur: eşit gecikme süresinde daha iyi hatırlama, önceden eğitim aşaması olmaması ve sürekli büyüyen tablolara karşı iyi tolerans. IVFFlat, mevcut hafıza çok kısıtlı olduğunda, genellikle daha düşük hatırlama ve veri dağılımının önemli ölçüde değişmesi durumunda gerekli yeniden eğitim pahasına, geçerliliğini korur.
HNSW dizini için ne kadar bellek planlanmalıdır?+
Büyüklük sırası doğrudan m'ye ve indekslenmiş vektörlerin sayısına bağlıdır: her düğüm, vektörün kendisine ek olarak katman başına m'ye kadar bağlantı depolar. Gerçek hacminize ilişkin güvenilir bir tahmin için dizini verilerinizin temsili bir alt kümesine göre oluşturun. Daha sonra ölçülmeyen bir genel kurala güvenmek yerine boyutunu pg_relation_size() ile ölçün.
2000'den fazla boyuttaki yerleştirmeleri HNSW ile indeksleyebilir miyiz?+
Doğrudan vektör türü üzerinde değil: pgvector, bu tür üzerinde 2000 boyutun ötesinde bir HNSW dizini oluşturmayı reddeder. Çözüm, dizin oluşturma sırasında sütunu halfvec'e dönüştürmektir; bu, depolama hassasiyetini yarıya indirerek dizin oluşturma sınırını zorlar. Bu tam olarak Aurabase'nin 3072 boyutlu gömme sınıfının üretiminde kullanılan yaklaşımdır.

DAĞITILMAYA HAZIR MISINIZ?

Beş dakika içinde arka ucunuz.

Kredi kartı gerekmez · 500 MB ücretsiz · 50.000 MAU