Ollama embedding'lerini pgvector ile PostgreSQL'de saklama ve arama

pgvector README'si onu Postgres için açık kaynaklı vektör benzerliği araması olarak tanımlar. Kesin ve yaklaşık en yakın komşu aramasını; tek duyarlıklı, yarım duyarlıklı, ikili ve seyrek vektörleri; ayrıca L2 uzaklığını, nokta çarpımını (inner product), kosinüs uzaklığını, L1 uzaklığını, Hamming uzaklığını ve Jaccard uzaklığını destekler. Vektörler sıradan PostgreSQL sütunları olduğu için ACID uyumluluğundan, belirli bir ana geri dönüşten (point-in-time recovery) ve JOIN'lerden de yararlanırlar.

Belgeleriniz üzerinde arama yapmak için her parça için metnini ve vektörünü içeren bir satır saklarsınız, soruyu aynı modelle embedding'e çevirirsiniz ve satırları sorunun vektörüne olan uzaklıklarına göre sıralarsınız.

pgvector, PostgreSQL 13 ve üstünü destekler. README, aralarında şunların da bulunduğu birkaç kurulum yolu sıralar:

vector(n) türündeki bir sütun tam olarak n boyutlu vektörler tutar ve n, embedding modelinizin verdiği vektörlerin uzunluğu olmalıdır. Farklı uzunlukta bir vektör reddedilir: vector(3) sütununa 2 boyutlu bir vektör eklediğimizde PostgreSQL "expected 3 dimensions, not 2" hatasını verdi. all-minilm 384 boyut döndürür, bu yüzden sütunu vector(384) olur.

README, her vektörün depolama boyutunu 4 × boyut + 8 bayt olarak verir; her öğe tek duyarlıklı bir kayan noktalı sayıdır ve bir sütunda 16,000 boyuta kadar izin verir. Bir indeks, aşağıda gösterildiği gibi daha az boyutu destekler. halfvec türü, yarım duyarlıklı değerleri 2 × boyut + 8 bayt içinde saklar.

pgvector bir vektörü köşeli parantezli metin olarak okur, örneğin '[1,2,3]'; README tüm öğelerin sonlu olması gerektiğini söyler (NaN, Infinity veya -Infinity olmaz). Bir /api/embed yanıtının embeddings alanındaki her dizi zaten bu biçimdedir ve yanıt girdinin sırasını korur; yani ilk metin ilk vektörle eşleşir.

README, birkaç satır için INSERT'i, upsert için INSERT … ON CONFLICT'i ve toplu yükleme için COPY'yi gösterir. Aşağıdaki dönüştürücü metinlerinizi yanıtla eşleştirir ve tırnakları kaçışlanmış INSERT ifadeleri yazar. Çıktısını tırnak, ters eğik çizgi, satır sonu ve emoji içeren metinlerle çalıştırdık ve metinler değişmeden geri geldi.

Ollama'nın belgeleri, anlamsal aramanın çoğu kullanım senaryosu için kosinüs benzerliğini önerir ve /api/embed'in uzunluğu 1 olan vektörler döndürdüğünü söyler. Bu tür vektörlerde kosinüs uzaklığı, L2 uzaklığı ve nokta çarpımı satırları aynı sıraya koyar; çünkü L2 uzaklığının karesi, 2 eksi 2 çarpı kosinüs benzerliğidir. all-minilm ile yaptığımız testte ilk üç satır üçünde de aynıydı ve 0.931 olan L2 uzaklığı, 0.566 olan kosinüs benzerliğiyle uyuşuyordu.

Her uzaklığın kendi operatörü vardır. Bir arama operatöre göre sıralar ve LIMIT ile ilk satırları alır; bir indeks de tek bir operatör sınıfı için oluşturulur.

İndeks olmadan pgvector kesin en yakın komşu araması yapar; README bunun mükemmel recall sağladığını söyler. Yaklaşık bir indeks, biraz recall'u hız karşılığında verir ve README, bir indeks ekledikten sonra sorguların farklı sonuçlar döndürebileceği konusunda uyarır.

Bir indeks yalnızca sorguda ORDER BY ve LIMIT varsa ve ORDER BY artan sırada uzaklık operatörünün kendisiyse kullanılır. ORDER BY embedding <=> $1 LIMIT 5 indeksi kullanabilir; ORDER BY 1 - (embedding <=> $1) DESC kullanamaz. README ayrıca tablo küçükken tablo taramasının daha hızlı olabileceğini belirtir.

HNSW'de sonuçlar, varsayılanı 40 olan hnsw.ef_search ile sınırlıdır. HNSW indeksli 200 satırlık bir test tablosunda LIMIT 100 yalnızca 40 satır döndürdü; SET hnsw.ef_search = 100 sonrasında 100 satır döndürdü. hnsw.ef_search değerini en az ihtiyaç duyduğunuz satır sayısı kadar yapın. Bir işlem (transaction) içindeki SET LOCAL, değeri yalnızca tek bir sorgu için değiştirir.

Filtreleme de sonuçları azaltır. Yaklaşık indekslerde README'ye göre WHERE koşulu, indeks tarandıktan sonra uygulanır: bir koşul satırların %10'una uyuyorsa, hnsw.ef_search varsayılan değeri 40 olan HNSW ortalama olarak yalnızca 4 satır döndürür. 0.8.0 sürümünden beri yinelemeli indeks taramaları (SET hnsw.iterative_scan = strict_order veya relaxed_order), yeterli satır bulunana kadar indeksin daha fazlasını tarar; üst sınır hnsw.max_scan_tuples'tır (varsayılan 20,000).

Arama en yakın satırları döndürdükten sonra modelin bunlara isteminde ihtiyacı vardır. Ollama'nın /api/chat uç noktası, her biri bir rol (system, user, assistant ya da tool) ve içerik taşıyan bir mesaj listesi alır. Basit bir düzen, kuralları içeren bir sistem mesajı ile satırları, her birine bir numara vererek, örneğin [1] ve [2], ardından da soruyu sıralayan bir kullanıcı mesajıdır. Numaralar sayesinde yanıt hangi satırları kullandığını söyleyebilir ve her numarayı satırına geri eşleyebilirsiniz.

Atıfları sabit bir biçimde almak için format alanına, yanıtı ve her biri kaynak numarası ile kısa bir alıntı içeren bir atıf listesini barındıran bir JSON Schema verin. Ollama'nın yapılandırılmış çıktılar sayfası, şemayı istemde de yazmayı ve daha deterministik çıktı için sıcaklığı (temperature) örneğin 0'a düşürmeyi önerir. psql'de json_agg işlevi bir sorgunun satırlarını bir JSON dizisinde toplar; aşağıdaki araç bunu doğrudan okur.

Kurallar, satırlar ve soru bağlam uzunluğuna sığmak zorundadır. Ollama'nın bağlam uzunluğu sayfası, 24 GiB'tan az VRAM olduğunda varsayılan olarak 4k token verir, SSS bölümü ise 4096 token verir; test makinemizde ollama ps 4096 gösterdi. options içindeki num_ctx ya da OLLAMA_CONTEXT_LENGTH ortam değişkeni bunu değiştirir.

İstem daha uzun olduğunda /api/chat varsayılan olarak hata döndürmez. Ollama'nın kaynak kodunda (0.40.11) sunucu önce daha önceki mesajları bütünüyle atar; sistem mesajlarını ve son mesajı korur. Kalan istem hâlâ çok uzunsa ilk birkaç token'ı (num_keep, varsayılan 4) ve istemin sonunu korur, aradaki kısmı atar. qwen2.5:7b ve num_ctx 1024 ile yaptığımız testte 2,068 token'lık bir istem 514'e kesildi. Sistem mesajı ve ilk kaynaklar kayboldu: yanıt [1] numaralı kaynaktayken model hiçbir kaynakta olmayan bir kod sözcüğüyle yanıt verdi; yanıt son kaynaktayken ise doğru yanıt verdi, ama sistem mesajının istediği kaynak numarası olmadan. Yanıtta hata yoktu; sunucu günlüğünde "truncating input prompt" uyarısı vardı.

Ollama'nın kaynak kodunda sohbet istekleri için /api/chat sayfasında listelenmeyen bir truncate alanı da vardır. "truncate": false ile aynı istek, "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it" hatasıyla HTTP 400 döndürdü. Bir yanıttaki prompt_eval_count alanı istemdeki token sayısıdır; kesilen testte 2,068 değil, 514 idi.

Bir atıf mekanik olarak denetlenebilir: numara gönderilmiş bir kaynağı göstermelidir ve alıntı o kaynakta geçmelidir. Dört kaynakla ve qwen2.5:7b ile yaptığımız testte JSON yanıtlarındaki alıntılar kaynaklarla kelimesi kelimesine eşleşti. Bu, yanıtın doğru olduğunu kanıtlamaz: 384 boyutlu bir vektörün boyutu sorulduğunda model doğru kuralı (boyut sayısının 4 katı artı 8 bayt) alıntıladı ve yine de 1,544 yerine 1552 bayt yanıtladı.

Atıfsız yanıtlara da bakın. Kaynaklarda yanıt yokken model bir keresinde kendi bilgisinden atıfsız yanıt verdi, bir keresinde de bilmediğini söyledi ama yine de ilgisiz bir kaynağa atıf yaptı. Yanıttaki done_reason "length" ise yanıt num_predict yüzünden kesilmiştir ve atıfları eksik olabilir.

README, çizge maintenance_work_mem içine sığdığında bir HNSW indeksinin belirgin biçimde daha hızlı oluştuğunu, artık sığmadığında bir bildirim gösterdiğini ve maintenance_work_mem değerini sunucunun belleğini tüketecek kadar yüksek ayarlamamanız gerektiğini söyler. Diğer indekslerde olduğu gibi, indeksi ilk veriler yüklendikten sonra oluşturmak daha hızlıdır. İndekslerin belleğe sığması gerekmez, ancak sığarlarsa büyük olasılıkla daha iyi performans görürsünüz; SELECT pg_size_pretty(pg_relation_size('index_name')) bir indeksin boyutunu gösterir.

Daha küçük bir çalışma kümesi ve daha küçük indeksler için README halfvec'i, yarım duyarlıklı indekslemeyi veya ikili nicemlemeyi önerir. Ollama aynı sunucuda çalışıyorsa PostgreSQL ve modeller aynı belleği paylaşır; Ollama'nın belleğini izleme üzerine yazdığımız makale, modellerin ne kadar bellek kullanacağını neyin belirlediğini açıklıyor.