Ana içeriğe geç

Zaten çalıştırdığınız Postgres'te vektör araması

· 8 dakikalık okuma

Bir RAG prototipi in-memory listesine sığmaz hale geldiğinde, genelde bir sonraki adım yeni bir altyapı parçası oluyor: kendi deployment'ı, kendi backup'ları ve içine veri kopyalayan bir senkronizasyon job'ı olan ayrı bir vector database. Zaten Postgres çalıştırıyorsanız daha kısa bir yol var. pgvector, elinizdeki veritabanına bir vektör tipi, mesafe operatörleri ve approximate index'ler ekliyor; vektörler de tarif ettikleri metinle aynı satırlarda duruyor.

Bu yazı, production'a almadan önce bilmek isteyeceğim şeyler: kolon, operatörler, index'ler ve ayarları, filtreleme tuzağı ve bunların .NET'ten nasıl göründüğü.

Neden buradan başlamalı?​

pgvector'ün lehine olan argüman aslında pek vektörlerle ilgili değil; Postgres'in zaten yaptığı diğer her şeyle ilgili. Bir chunk ve embedding'i aynı transaction'da yazılıyor; geri alınmış bir metnin vektörü diye bir şey olmuyor. Bir dokümanı silmek vektörlerini de siliyor, unutulacak ikinci bir sistem yok. Vektörler aynı backup'larda, aynı replica'larda ve aynı point-in-time recovery'de. Sorgu anında ihtiyaç duyduğunuz filtreler de, yani tenant, dil, doküman tipi ya da yetkiler, WHERE'e yazabileceğiniz ya da join yapabileceğiniz sıradan kolonlar.

Çok büyük ölçekte ayrı bir vector database yine de öne geçebilir. Ben bir ölçüm bunu söylediğinde geçerim, ilk gün değil.

Kolon​

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
id bigserial PRIMARY KEY,
tenant_id int NOT NULL,
source text NOT NULL,
content text NOT NULL,
embedding vector(1536) NOT NULL
);

vector(1536) içindeki sayı boyut sayısı ve embedding modeliyle birebir eşleşmesi gerekiyor: başka uzunluktaki bir vektör reddediliyor. 1536, OpenAI'ın text-embedding-3-small modelinin varsayılan olarak döndürdüğü boyut. Her eleman 4 byte'lık bir float, her değerin de 8 byte overhead'i var; yani yalnızca bu kolon satır başına yaklaşık 6 KB.

Baştan bilinmesi gereken bir limit var. Bir vector kolonu 16.000 boyuta kadar saklayabiliyor ama iki index tipi de en fazla 2.000 boyutu index'leyebiliyor. 3072 boyutlu bir model vector olarak doğrudan index'lenemiyor. Çıkış yolları: 2 byte'lık float saklayan ve 4.000 boyuta kadar index'lenebilen halfvec, model destekliyorsa ondan daha az boyut istemek ya da binary quantization. pgvector README'si üçünü de anlatıyor.

Üç operatör​

pgvector'de mesafe bir operatör ve sorguya hangi index'in hizmet edebileceğine operatör karar veriyor:

  • <-> L2, yani Euclidean mesafe.
  • <=> cosine mesafe; 1 eksi cosine similarity.
  • <#> inner product'ın negatifi. Negatif, çünkü Postgres bu operatörlerde index'leri yalnızca artan sırada tarayabiliyor; "en büyük inner product önce" ifadesinin "en küçük negatif önce" olması gerekiyor.

Normalize edilmiş embedding'lerde, ki OpenAI'ınkiler öyle, cosine ve inner product sonuçları aynı şekilde sıralıyor ve README inner product'ın daha hızlı olduğunu belirtiyor. Ben yine de varsayılan olarak cosine kullanıyorum, çünkü modelin çıktısını normalize etmesine bağlı değil. Değiştirirseniz index'i de değiştirin.

Üçü de mesafe: küçük olan daha yakın demek. Ekranda göstermek için bir similarity puanı istiyorsanız SELECT listesinde 1 - (embedding <=> $1) hesaplayın ama ona göre sıralamayın. Index yalnızca ORDER BY artan sırada çıplak mesafe operatörü olduğunda ve bir LIMIT olduğunda kullanılıyor.

İki index tipi​

Index yoksa pgvector exact search yapıyor: her satıra olan mesafeyi hesaplıyor. Recall mükemmel ve birkaç bin satır için yeterince hızlı. Index aramayı approximate yapıyor; biraz recall'dan vazgeçip hız kazandırıyor, yani bir index eklemek sonuçlarınızı değiştirebilir.

HNSW katmanlı bir graph kuruyor. Hız-recall dengesi daha iyi ve bir eğitim adımına ihtiyaç duymuyor; boş bir tabloda bile oluşturabiliyorsunuz. Bedeli bellek ve build süresi.

CREATE INDEX ON chunks USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

m node başına maksimum bağlantı sayısı, varsayılanı 16; ef_construction build sırasındaki aday listesinin boyutu, varsayılanı 64. Daha yüksek değerler build süresi ve insert hızı karşılığında recall kazandırıyor. README recall düşük değilse varsayılanlarda kalmayı söylüyor, ben de katılıyorum. Gerçekte çevireceğiniz ayar sorgu anında: hnsw.ef_search, arama sırasındaki aday listesinin boyutu, varsayılanı 40.

IVFFlat vektörleri lists kadar kümeye ayırıyor ve sorgu anında yalnızca sorguya en yakın probes kadar listeyi tarıyor. Daha hızlı build ediliyor ve daha az bellek kullanıyor ama aynı hızda recall'u daha kötü; kümeler de index oluşturulduğu anda tabloda hangi veri varsa ondan öğreniliyor. Bu yüzden onu veriyi yükledikten sonra oluşturun. README'nin başlangıç önerileri: bir milyon satıra kadar rows / 1000 liste, üzerinde sqrt(rows), probes için de sqrt(lists). ivfflat.probes varsayılan olarak 1, bu da düşük.

Operator class operatörle eşleşmeli: <=> için vector_cosine_ops, <-> için vector_l2_ops, <#> için vector_ip_ops. Biri için kurulmuş bir index diğerlerine hizmet etmiyor. Ben HNSW ile başlıyorum ve IVFFlat'i yalnızca build süresi ya da bellek gerçek bir kısıt olduğunda düşünüyorum.

Filtreleme: satırların kaybolduğu yer​

İnsanları şaşırtan kısım bu. Bir RAG sorgusunun neredeyse her zaman bir filtresi oluyor:

SELECT id, source, embedding <=> $1 AS distance
FROM chunks
WHERE tenant_id = $2
ORDER BY embedding <=> $1
LIMIT 5;

Approximate bir index'te filtre, index taramasından sonra uygulanıyor. HNSW ef_search kadar aday topluyor, sonra Postgres başka tenant'lara ait satırları atıyor. Tenant 7 satırların %10'una sahipse, o 40 adaydan ortalama 4 tanesi hayatta kalıyor. 5 istediniz, 4 aldınız, ya da 2, ya da hiç; ve hiçbir şey sizi uyarmadı.

Aynı tavan filtre olmadan da geçerli: varsayılan ef_search ile LIMIT 100 en fazla 40 satır döndürüyor.

pgvector 0.8.0 bunun için iterative index scan'leri ekledi. Açık olduklarında tarama, filtreden yeterince satır geçene kadar ya da hnsw.max_scan_tuples (varsayılanı 20.000) veya ivfflat.max_probes sınırına ulaşana kadar devam ediyor.

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SET LOCAL hnsw.iterative_scan = relaxed_order; -- or strict_order
-- the SELECT above
COMMIT;

strict_order sonuçları mesafeye göre tam sırada tutuyor. relaxed_order daha iyi recall karşılığında küçük sıra kaymalarına izin veriyor; sıra önemliyse materialized bir CTE içinde yeniden sıralayabilirsiniz. Managed Postgres servisleri her zaman en yeni extension'ı sunmuyor; güvenmeden önce SELECT extversion FROM pg_extension WHERE extname = 'vector'; ile kontrol edin.

Diğer araçlar düz Postgres. tenant_id üzerindeki bir B-tree index, filtre seçici olduğunda planner'ın tek bir tenant'ın satırları üzerinde exact search seçmesini sağlıyor ve bu çoğu zaman en iyi plan oluyor. Yalnızca birkaç filtre değeri varsa partial bir HNSW index işe yarıyor. Gerçek tenant izolasyonu için README list partitioning ya da ayrı tablolar öneriyor, çünkü paylaşılan bir index'te bir tenant'ın vektörleri diğer bütün tenant'ların recall'unu ve hızını etkiliyor.

SET LOCAL .NET'te önemli: transaction'la birlikte bitiyor, böylece bir ayar aynı pooled connection'ı ödünç alan bir sonraki isteğe sızamıyor.

.NET'ten Npgsql ile​

Pgvector paketi tip eşlemesini ekliyor. Data source üzerinde kaydedin, Vector sıradan bir parametre haline geliyor:

using Npgsql;
using Pgvector;

var builder = new NpgsqlDataSourceBuilder(connectionString);
builder.UseVector();
await using var dataSource = builder.Build();

await using var cmd = dataSource.CreateCommand("""
SELECT id, source, embedding <=> $1 AS distance
FROM chunks
WHERE tenant_id = $2
ORDER BY embedding <=> $1
LIMIT 5
""");
cmd.Parameters.AddWithValue(new Vector(queryEmbedding));
cmd.Parameters.AddWithValue(tenantId);

await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
Console.WriteLine($"{reader.GetInt64(0)} {reader.GetString(1)} {reader.GetDouble(2):F3}");

$1 iki kez geçiyor; positional parametreler buna izin veriyor. Vector'ün bir de ReadOnlyMemory<float> alan bir constructor'ı var; Microsoft.Extensions.AI'daki Embedding<float>.Vector size tam olarak bunu veriyor, yani embedding generator'ın çıktısı doğrudan içeri giriyor.

Bir de EF Core ile​

Pgvector.EntityFrameworkCore (güncel sürümler EF Core 9 ve 10'u destekliyor) tipi eşliyor ve mesafe metotlarını operatörlere çeviriyor:

using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;
using Pgvector;
using Pgvector.EntityFrameworkCore;

public sealed class Chunk
{
public long Id { get; set; }
public int TenantId { get; set; }
public string Source { get; set; } = "";
public string Content { get; set; } = "";

[Column(TypeName = "vector(1536)")]
public Vector Embedding { get; set; } = null!;
}

public sealed class AppDb(DbContextOptions<AppDb> options) : DbContext(options)
{
public DbSet<Chunk> Chunks => Set<Chunk>();

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.HasPostgresExtension("vector");
modelBuilder.Entity<Chunk>()
.HasIndex(c => c.Embedding)
.HasMethod("hnsw")
.HasOperators("vector_cosine_ops")
.HasStorageParameter("m", 16)
.HasStorageParameter("ef_construction", 64);
}
}

UseNpgsql(connectionString, o => o.UseVector()) ile kaydedin. Kendi NpgsqlDataSource'unuzu oluşturuyorsanız o builder üzerinde de UseVector() çağırın. Sonrasında sorgu sıradan bir LINQ gibi okunuyor:

var q = new Vector(queryEmbedding);

var hits = await db.Chunks
.Where(c => c.TenantId == tenantId)
.OrderBy(c => c.Embedding.CosineDistance(q))
.Take(5)
.Select(c => new { c.Id, c.Source, Distance = c.Embedding.CosineDistance(q) })
.ToListAsync();

ToQueryString() çıktısında ORDER BY c."Embedding" <=> @q LIMIT @p görünüyor, yani HNSW index devreye giriyor. L2Distance ve MaxInnerProduct diğer iki operatöre karşılık geliyor. Index modelin bir parçası ve diğer index'ler gibi migration'lardan çıkıyor. SET LOCAL için db.Database.BeginTransactionAsync() ile bir transaction açın ve sorgudan önce ExecuteSqlRawAsync("SET LOCAL hnsw.ef_search = 100") çalıştırın.

Güvenmeden önce neleri kontrol ederdim?​

  • Plan. EXPLAIN (ANALYZE, BUFFERS) index'in kullanılıp kullanılmadığını gösteriyor. Küçük bir tabloda sequential scan daha ucuz olabilir.
  • Recall. Gerçek sorgulardan bir seti exact sonuç almak için SET LOCAL enable_indexscan = off ile çalıştırın, sonra index'le tekrar çalıştırıp karşılaştırın. Approximation'ın size neye mal olduğunu bilmenin tek yolu bu. Prompt'u ayarlamadan önce retrieval'ı ölçün yazısı o seti kurmayı anlatıyor.
  • Eksik sonuçlar. Filtreli bir sorgu LIMIT'ten az satır döndürdüğünde loglayın. ef_search'ün ya da iterative scan'lerin ilgi beklediğine dair en ucuz sinyal bu.
  • Index boyutu. pg_size_pretty(pg_relation_size('index_name')). Belleğe sığması gerekmiyor ama sığdığında daha hızlı. Yeterli maintenance_work_mem ile build edin, production'da da write'lar bloklanmasın diye CONCURRENTLY kullanın.

Bir de bu Postgres olduğu için, hybrid search'ün keyword yarısı için gereken full-text search zaten aynı veritabanında, bir join uzağınızda.