ServBay'de pgvector PostgreSQL Eklentisi Kullanım Rehberi

pgvector, PostgreSQL için geliştirilmiş güçlü bir üçüncü taraf uzantıdır ve veritabanına vektör veri tipi ile IVFFlat ve HNSW gibi yüksek performanslı vektör indeksleme yöntemleri ekler. Böylece PostgreSQL, vektör depolama ve benzerlik aramasını yerel şekilde destekleyebilir. Bu sayede yüksek boyutlu vektör verisinin işlendiği AI uygulamaları, öneri sistemleri, görüntü tanıma ve doğal dil işleme gibi alanlar için ideal bir çözüm sunar.

ServBay, tümleşik bir yerel web geliştirme ortamı olarak, PostgreSQL ve pgvector eklentilerini önceden içermektedir. Böylece yerel bir geliştirme ortamında bir vektör veritabanı kurmak ve kullanmak son derece kolaylaşır. Bu rehberde, ServBay üzerinde pgvector’ün nasıl kullanılacağını adım adım bulabilirsiniz.

pgvector nedir? Neden önemlidir?

Günümüzün pek çok modern uygulamasında veri yalnızca metin ve sayılardan ibaret değildir. Özellikle yapay zeka ve makine öğreniminin gelişimiyle, veri çoğunlukla yüksek boyutlu vektörler ile (embedding olarak da bilinir) temsil edilmeye başlanmıştır. Bu vektörler, veri öğelerinin anlamını veya özelliklerini yakalar; örneğin, bir görselin özelliklerini, bir metnin anlamını veya bir kullanıcının tercihlerini.

pgvector uzantısı, PostgreSQL’in bu tür vektörleri doğrudan depolayıp aralarında benzerlik araması (yakın komşu arama) yapmasına olanak tanır. Böylece, ayrı bir vektör veritabanı kurmaya gerek kalmadan doğrudan tanıdık SQL diliyle verilerinizi sorgulayabilir ve teknolojik altyapınızı sadeleştirebilirsiniz.

Gereksinimler

pgvector’ü kullanmaya başlamadan önce aşağıdaki ön koşulların sağlandığından emin olun:

1. ServBay’in macOS üzerinde kurulmuş ve çalışıyor olması gerekir.
2. ServBay’in "Paketler" listesinden PostgreSQL paketi etkinleştirilmiş olmalıdır. Eğer etkin değilse, ServBay uygulama arayüzünden PostgreSQL’i bulup durumunu "Etkin" yapın.

ServBay PostgreSQL’de pgvector Uzantısını Etkinleştirme

ServBay, PostgreSQL’in kurulum dizinine pgvector uzantısı dosyalarını önceden ekler. Dosyaları manuel olarak indirmenize veya derlemenize gerek yoktur; yalnızca kullanmak istediğiniz veritabanında etkinleştirmeniz yeterlidir.

ServBay PostgreSQL veritabanında pgvector’ü etkinleştirme adımları şunlardır:

1. PostgreSQL Veritabanına Bağlanma: ServBay’in sunduğu PostgreSQL örneğine psql komut satırı aracı ile bağlanabilirsiniz. ServBay’in PostgreSQL’i, varsayılan olarak yerel bağlantıları kabul eder ve varsayılan kullanıcı genellikle postgres veya servbay’dir; varsayılan port ise 5432. Farklı bir yapılandırmanız varsa ServBay’in veritabanı ayarlarını kontrol edin.

   Terminalde aşağıdaki komutu girerek bağlanabilirsiniz (kendi kullanıcı adınızı ve veritabanı adınızı ayarlayın):

   psql -U servbay -d your_database_name -h localhost -p 5432

   • -U servbay: Kullanıcı adını servbay (veya postgres) olarak belirler.
   • -d your_database_name: Bağlanacağınız veritabanının adı. Yoksa, öncelikle oluşturmanız gerekebilir (örneğin CREATE DATABASE servbay_demo_db;).
   • -h localhost: Yerel ana bilgisayara bağlanır.
   • -p 5432: Portu 5432 olarak seçer (ServBay'in varsayılan PostgreSQL portu).

2. vector Uzantısını Oluşturma: Başarılı şekilde bağlandıktan sonra, psql ekranında aşağıdaki SQL komutunu girerek pgvector uzantısını etkinleştirin:

   CREATE EXTENSION vector;

   Eğer uzantı önceden mevcutsa, komut bir bilgilendirme mesajı verebilir.

3. Kurulumu Doğrulama: Yüklü uzantıları listeleyerek kurulumun başarılı olup olmadığını kontrol edebilirsiniz:

   \dx

   Komut çıktısında, vector adlı bir uzantı ve sürüm bilgisi görünmelidir.

                              List of installed extensions
      Name   | Version |   Schema   |                         Description
   ----------+---------+------------+--------------------------------------------------------------
    plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
    vector   | 0.7.0   | public     | vector data type and ivfflat and hnsw access methods
   (2 rows)

   (Not: Sürüm numarası ServBay’in pgvector sürümüne göre değişebilir.)

pgvector’un Yapılandırılması ve Kullanımı

Uzantı etkinleştirildiğinde artık veritabanında vektör veri depolayabilir ve yönetebilirsiniz.

Vektör Veri Tutan Tablo Oluşturma

Öncelikle, vektör verinizi saklamak için bir tablo oluşturmalısınız. pgvector, yeni bir veri türü sağlar: VECTOR(boyut), burada boyut vektörün boyutunu belirtir.

Aşağıda, 3 boyutlu vektörleri tutacak embeddings adlı bir tablo oluşturma örneği verilmiştir:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- 3 boyutlu vektör kolonunu tanımlayın
    vector VECTOR(3)
);

Ardından, örnek vektör verilerini ekleyebilirsiniz:

INSERT INTO embeddings (vector) VALUES
('[0.1, 0.2, 0.3]'),
('[0.4, 0.5, 0.6]'),
('[0.7, 0.8, 0.9]'),
('[0.15, 0.25, 0.35]'),
('[0.6, 0.5, 0.4]'); -- Sonraki sorgu örnekleri için daha fazla veri ekleyin

Dikkat: Vektör değerleri köşeli parantez [] içinde yazılmalı ve öğeler virgülle ayrılmalıdır.

Sorgu Performansını Artırmak için Vektör İndeksi Oluşturma

Büyük miktarda vektör verisi içeren tablolar için indeksleme, benzerlik aramalarının hızını artırmak açısından çok önemlidir. pgvector, IVFFlat ve HNSW olmak üzere iki temel indeks türünü destekler. Hangi indeksi seçeceğiniz veri setinizin büyüklüğüne, sorgu hızına, oluşturma süresine, bellek kullanımına ve geri çağırma oranına bağlıdır.

• IVFFlat (Ters Dosya İndeksi ve Düz Sıkıştırma): Büyük veri setleri ve nispeten düşük geri çağırma oranı ihtiyacında uygundur. Oluşturması hızlıdır.
• HNSW (Hiyerarşik Gezinilebilir Küçük Dünya): Genellikle daha yüksek geri çağırma ve daha hızlı sorgu sunar; fakat oluşturması daha yavaş ve bellek tüketimi daha fazladır.

Aşağıda, embeddings tablosundaki vector kolonu için IVFFlat ve HNSW indekslerinin nasıl oluşturulacağı gösterilmiştir:

1. IVFFlat İndeksi Oluşturma:

   -- IVFFlat indeksi oluşturmadan önce genellikle ANALYZE komutunu çalıştırarak istatistik toplayın
   ANALYZE embeddings;
   
   -- IVFFlat indeksi oluştur
   -- WITH (lists = 100): Ters dosya listesinin sayısı. Veri setinizin büyüklüğüne göre ayarlanmalıdır.
   -- List sayısı arttıkça indeks oluşturma süresi ve sorgularda taranacak liste sayısı artar (daha yavaş olabilir), ancak geri çağırma oranı yükselir.
   -- Resmi öneri: lists = sqrt(satır sayısı).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. HNSW İndeksi Oluşturma:

   -- HNSW indeksi oluştur
   -- WITH (m = 16, ef_construction = 200): HNSW parametreleri.
   -- m: Her düğümün maksimum bağlantı sayısı. İndeksin bağlantılılığı ve sorgu hızı/bellek üzerinde etkili.
   -- ef_construction: İndeksi oluştururken kullanılan arama kapsamı. Zaman/bellek ve indeksin kalitesini (geri çağırma oranı) etkiler.
   -- Bu değerler verinize ve gereksinimlerinize göre ayarlanmalıdır.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Not: İndeks parametreleri (lists, m, ef_construction) indeks performansını ve geri çağırma oranını önemli derecede etkiler. En uygun değerlerin seçimi, veri ve sorgu tipinizi analiz etmeyi ve test etmeyi gerektirir. pgvector resmi belgelerine başvurarak ayrıntılı bilgi ve ayar önerileri alabilirsiniz.

pgvector ile Vektör Sorguları

pgvector, vektörler arasındaki mesafeleri hesaplayabileceğiniz çeşitli operatörler sunar; böylece benzerlik aramaları yapabilirsiniz. En çok kullanılan operatörler şunlardır:

• <->: L2 mesafesi (Öklid mesafesi). Vektörler arası doğrudan mesafeyi ölçer.
• <#>: İç çarpım (Inner Product). Kosinüs benzerliğiyle ilgilidir, yön benzerliğinde kullanılır.
• <=>: Kosinüs mesafesi (Cosine Distance). Sonuç: 1 - kosinüs benzerliği. Vektör yönlerini karşılaştırırken kullanılır (vektör uzunluğundan etkilenmez).

Aşağıda sık kullanılan örnek vektör sorguları görebilirsiniz:

En Yakın Komşu Araması (Nearest Neighbor Search)

Verilen sorgu vektörüne en benzer (yani mesafesi en kısa olan) vektörleri aramak için kullanılır. ORDER BY ile mesafe operatörünü ve LIMIT ile sonuç sayısını belirtin.

1. Vektör [0.2, 0.3, 0.4] ile L2 mesafesi en kısa olan 5 vektörü bulma:

   SELECT
       id,
       vector,
       -- Sorgu vektörü ile L2 mesafesini hesapla
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Artan mesafeye göre sırala (mesafe küçükse daha benzer)
   LIMIT 5;

Vektör Benzerliği Arama (Similarity Search)

En yakın komşu aramaya benzer şekilde çalışır fakat daha fazla benzerlik skoru odaklıdır.

1. Vektör [0.2, 0.3, 0.4] ile kosinüs mesafesi en kısa olan 5 vektörü ve mesafelerini getir:

   SELECT
       id,
       vector,
       -- Sorgu vektörü ile kosinüs mesafesini hesapla
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Artan mesafeye göre sırala (mesafe küçükse daha benzer)
   LIMIT 5;

Vektör Verisinin Görselleştirilmesi (Opsiyonel)

Yüksek boyutlu vektör verisini görselleştirmek, veri kümesinin dağılımı ve kümelenmesini anlamada yardımcı olur. 2D veya 3D vektörler doğrudan dağılım grafikleriyle gösterilebilir. Daha yüksek boyutlu verilerde ise önce boyut indirgeme teknikleri (PCA, t-SNE vb.) kullanılır ve ardından görselleştirilir.

Aşağıda, Python ve Matplotlib kullanarak 3 boyutlu vektörlerin nasıl görselleştirileceğine dair örnek verilmiştir.

1. Python Ortamını Hazırlayın: ServBay dışında veya ServBay’in sunduğu Python paketini etkinleştirerek bir Python ortamı kurun. PostgreSQL bağlantısı için psycopg2, görselleştirme için ise matplotlib yükleyin:

   # Sistem varsayılan veya kendi kurduğunuz Python ile
   pip install psycopg2 matplotlib
   
   # ServBay Python'u kullanıyorsanız, ServBay’in pip konumunu kullanın
   # /Applications/ServBay/paketler/python/bin/pip install psycopg2 matplotlib

   pip komutunu kendi Python ortamınızın yoluna göre uyarlayın.

2. Python Scripti Yazın: Bir Python dosyası oluşturun (örneğin visualize_vectors.py) ve aşağıdaki kodu yapıştırın. ServBay PostgreSQL ayarlarınıza göre bağlantı parametrelerini (dbname, user, password, host, port) düzenleyin.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # 3D dağılım grafiği modülünü ekleyin
   
   # Veritabanı bağlantı parametreleri - ServBay ayarınıza göre düzenleyin
   db_params = {
       "dbname": "your_database_name", # Veritabanını adınız
       "user": "servbay",              # Kullanıcı adınız (genellikle servbay veya postgres)
       "password": "",                 # Şifre (yerel bağlantıda genellikle boş bırakılır)
       "host": "localhost",            # ServBay genellikle localhost'ta çalışır
       "port": "5432"                  # ServBay’in varsayılan PostgreSQL portu
   }
   
   conn = None
   cur = None
   
   try:
       # PostgreSQL veritabanına bağlanın
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Vektör verisini sorgulayın
       # Not: psycopg2, vector tipini '[x, y, z]' olarak string okur.
       # El ile ayrıştırma gerekir veya pgvector+psycopg2’nin uyumlu yeni sürümleri otomatik dönüştürebilir.
       # Buradaki örnek, okunan değeri string varsayarak işliyor.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Vektör stringini ayrıştırıp rakam listesine dönüştürün
       vectors = []
       for row in vectors_raw:
           # Köşeli parantezleri ve aradaki virgülleri ayır, float’a çevir
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("Vektör verisi bulunmadı.")
           exit()
   
       # Vektör koordinatlarını ayıkla
       # Hepsi 3 boyutlu olmalı; aksi halinde grafik çizilemez!
       if any(len(v) != 3 for v in vectors):
            print("Uyarı: Vektör boyutları tutarlı değil ya da 3 değil, 3D grafik çizilemiyor.")
            exit()
   
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # 3D dağılım grafiği oluşturun
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Boyut 1')
       ax.set_ylabel('Boyut 2')
       ax.set_zlabel('Boyut 3')
       ax.set_title('3B Vektör Görselleştirmesi')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Veritabanı bağlantı veya sorgu hatası: {e}")
   except Exception as e:
       print(f"Bir hata oluştu: {e}")
   finally:
       # Veritabanı bağlantısını kapat
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Scripti çalıştırma: Terminalde ilgili Python dosyasını çalıştırın:

   python visualize_vectors.py

   Script, PostgreSQL veritabanına bağlanır, vektör verilerini çeker ve Matplotlib ile bir 3D dağılım grafik penceresi açar.

Sıkça Sorulan Sorular (SSS)

• S: \dx çıktısında vector uzantısını göremiyorum, ne yapmalıyım? C: Öncelikle, CREATE EXTENSION vector; komutunu doğru şekilde girdiğinizden ve hata almadığınızdan emin olun. Yine de uzantı bulunamıyorsa, ServBay PostgreSQL paketinin doğru kurulup etkinleştirildiğini kontrol edin. pgvector dosyaları PostgreSQL’in share/extension alt klasöründe bulunmalı. Dosyalar eksikse, paketi yeniden kurmanız veya güncellemeniz gerekebilir.
• S: Veritabanı bağlantısında kimlik doğrulama hatası alıyorum, ne yapmalıyım? C: psql komutunda veya Python scriptindeki kullanıcı adı, şifre, ana bilgisayar ve port bilgilerinin ServBay PostgreSQL ile uyumlu olduğundan emin olun. Yerel bağlantılarda varsayılan kullanıcı genellikle servbay veya postgres olur; şifre olmayan bir bağlantı da mümkün.
• S: Vektör indeks parametreleri lists, m, ef_construction nasıl seçilmeli? C: Bu parametrelerin performans ve geri çağırma oranı üzerinde büyük etkisi vardır—tek ideal değer yoktur. Veri seti boyutu, vektör boyutu, sorgu gecikmesi ve geri çağırma hedefiniz için farklı değerler deneyerek optimum ayarı bulmalısınız. pgvector resmi belgelerine göz atarak daha detaylı bilgi edinebilirsiniz.

Sonuç

pgvector, olgun ve istikrarlı PostgreSQL sistemine güçlü vektör veritabanı özellikleri ekler; böylece yerel ortamda AI ile vektör tabanlı uygulamalar geliştirirken oldukça kolaylık sağlar. ServBay’in pgvector eklentisini önceden sunması ise ortamı kurmayı daha da sadeleştirir.

Bu rehberdeki adımları takip ederek ServBay PostgreSQL üzerinde kolayca pgvector’ü etkinleştirebilir, vektör tablosu oluşturabilir, indekslerle sorgu hızını artırabilir ve çeşitli vektör benzerlik aramalarını gerçekleştirebilirsiniz. ServBay’in sunduğu diğer geliştirme araçları ile birlikte, modern web uygulamalarınızı ve veri ağırlıklı projelerinizi daha hızlı ve pratik şekilde geliştirebilirsiniz.