ServBay'de pgvector PostgreSQL Eklentisi Kullanım Rehberi

pgvector, PostgreSQL veritabanları için güçlü bir üçüncü parti eklentidir. Bu eklenti, PostgreSQL'e vektör veri tipi ve IVFFlat ile HNSW gibi etkili vektör indeksleme yöntemleri sunar. Böylece PostgreSQL, vektör depolama ve benzerlik aramasını yerel olarak destekler ve yüksek boyutlu vektör verileriyle çalışan AI uygulamaları, tavsiye sistemleri, görüntü tanıma, doğal dil işleme gibi senaryolar için ideal hâle gelir.

ServBay, entegre bir yerel web geliştirme ortamı olarak, PostgreSQL ile pgvector eklentisini önyüklü şekilde sunar. Böylece yerel ortamınızda vektör veritabanlarını etkinleştirmek ve kullanmak son derece kolaydır. Bu makalede, ServBay üzerinde pgvector'ün nasıl kullanılacağını adım adım açıklayacağız.

pgvector Nedir ve Neden Önemlidir?

Modern uygulama senaryolarında veriler yalnızca yapılandırılmış metin ve sayılardan ibaret değildir. Özellikle yapay zeka ve makine öğreniminin yaygınlaştığı günümüzde, veriler genellikle yüksek boyutlu vektörler, yani "embedding"ler şeklinde temsil edilir. Bu vektörler; nesnelerin görsel özellikleri, metinlerin anlamı ya da kullanıcı tercihleri gibi semantik bilgileri ya da özellikleri yakalar.

pgvector eklentisi, PostgreSQL'in bu vektörleri doğrudan depolamasını ve etkili vektör benzerliği araması (ya da "en yakın komşu arama") yapmasını sağlar. Böylece tanıdık SQL sözdizimiyle, ayrı bir vektör veritabanına gerek kalmadan benzer ögeleri arayabilir ve teknoloji yığınınızı sadeleştirebilirsiniz.

Ön Koşullar

pgvector'ü kullanmaya başlamadan önce aşağıdaki ön koşulları sağlamalısınız:

1. ServBay'i macOS üzerinde kurmuş ve çalıştırıyor olmalısınız.
2. ServBay'in "Paketler" ("Packages") listesinden PostgreSQL paketini etkinleştirmiş olmalısınız. Henüz etkinleştirmediyseniz ServBay arayüzünde PostgreSQL'i bulup "Etkin" pozisyonuna getirebilirsiniz.

ServBay PostgreSQL'de pgvector Eklentisini Etkinleştirmek

ServBay, PostgreSQL kurulumunun içine pgvector eklenti dosyalarını önyüklü olarak getirir. Elinizle indirme veya derleme yapmanıza gerek yoktur. Yalnızca vektör fonksiyonlarını kullanmak istediğiniz veritabanında eklentiyi etkinleştirmeniz yeterlidir.

ServBay PostgreSQL veritabanında pgvector'ü etkinleştirmek için:

1. PostgreSQL Veritabanına Bağlanın:psql komut satırı aracını kullanarak ServBay PostgreSQL örneğine bağlanabilirsiniz. ServBay genellikle varsayılan olarak yerel bağlantıya (localhost) izin verir, kullanıcı adı sıklıkla postgres veya servbay olur, port ise 5432'dir. Farklı bir konfigürasyon kullanıyorsanız, ServBay veritabanı yapılandırmasını inceleyin.

   Terminali açıp aşağıdaki komutu girin (gerçek kullanıcı adınızı ve veritabanınızı uyarlayın):

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

   • -U servbay: Kullanıcı adı olarak servbay (veya postgres) kullanır.
   • -d your_database_name: Bağlanmak istediğiniz veritabanının adını belirtir. Eğer veritabanı yoksa önce oluşturmanız gerekebilir (CREATE DATABASE servbay_demo_db; gibi).
   • -h localhost: Sunucu yerel makinedir.
   • -p 5432: 5432 portunu kullanır (ServBay PostgreSQL varsayılan portu).

2. vector Eklentisini Oluşturun: Bağlantı sağladığınızda, aşağıdaki SQL komutuyla pgvector eklentisini etkinleştirin:

   CREATE EXTENSION vector;

   Eğer eklenti zaten varsa, bir uyarı görebilirsiniz, bu normaldir.

3. Kurulumu Doğrulayın: Kurulumun başarılı olduğunu görmek için yüklenmiş eklentileri listeleyin:

   \dx

   Çıktıdaki listede vector isminde bir eklenti ve sürüm bilgisi görmelisiniz.

                              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'e dahil edilen pgvector versiyonuna göre değişebilir.)

pgvector'ü Yapılandırma ve Kullanma

pgvector etkinleştirildikten sonra artık veritabanınızda vektör verileri oluşturabilir, saklayabilir ve yönetebilirsiniz.

Vektör Verisi İçeren Tablo Oluşturma

İlk adımda, vektörlerinizi depolayacağınız bir tablo oluşturmanız gerekir. pgvector ile birlikte gelen yeni veri tipi VECTOR(dimension_count) kullanılır; dimension_count, vektörün boyutunu belirtir.

Aşağıda, 3 boyutlu vektörler tutan bir embeddings tablosunun örneğini görebilirsiniz:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- 3 boyutlu bir vektör sütunu tanımlanıyor
    vector VECTOR(3)
);

Sonrasında örnek vektör verileri 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]'); -- Daha net arama örnekleri için daha fazla veri ekleyin

Not: Vektör değerleri köşeli parantez [] ile çevrili, öğeler ise virgül ile ayrılmış olmalıdır.

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

Çok sayıda vektör içeren tablolarda, benzerlik sorgularını hızlandırmak için indeks oluşturmak şarttır. pgvector, IVFFlat ve HNSW olmak üzere iki ana indeks tipini destekler. Hangi indeksi seçeceğiniz, veri büyüklüğü, hız, bellek kullanımı, geri çağırma oranı ve benzeri gereksinimlerinize göre değişir.

• IVFFlat (Ters Dosya İndeksi): Büyük veri kümelerinin hızla indekslenmesi ve orta seviyede isabet oranı için idealdir. Kurulması hızlıdır.
• HNSW (Hierarchical Navigable Small World): Genellikle daha yüksek geri çağırma oranı ve hızlı sorgu sağlar, fakat indeksleme yavaştır ve daha fazla bellek gerektirebilir.

Aşağıda, embeddings tablosundaki vector sütununa hem IVFFlat hem de HNSW için indeks oluşturma örnekleri yer alıyor:

1. IVFFlat İndeksi Oluşturma:

   -- IVFFlat kurulmadan önce ANALYZE komutuyla istatistik toplanması genellikle tavsiye edilir
   ANALYZE embeddings;
   
   -- IVFFlat indeksi oluşturuluyor
   -- WITH (lists = 100): Ters dosya listesinin sayısı belirtildi. Kümelerin büyüklüğüne göre değiştirilmeli.
   -- Daha fazla liste, daha yavaş indeksleme ve sorgulama, ama muhtemelen daha yüksek geri çağırma oranı demektir.
   -- Öneri: list sayısı ≈ satır sayısının karekökü.
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. HNSW İndeksi Oluşturma:

   -- HNSW İndeksi kur
   -- WITH (m = 16, ef_construction = 200): HNSW parametreleridir.
   -- m: Her nodun maksimum bağlantı sayısı (bağlantı yoğunluğu ve sorgu hızını etkiler).
   -- ef_construction: İndeks kurulurken kullanılacak arama genişliği.
   -- Parametreler veri ve performans gereksinimlerinize göre uyarlanmalı.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Not: İndeks parametreleri (lists, m, ef_construction) indeksin performansı ve geri çağırma oranını ciddi şekilde etkiler. Uygun değer seçimi için verinizi, sorgu yapılarını iyi analiz etmeli ve gerekirse denemeler yapmalısınız. Daha fazla bilgi ve optimizasyon önerisi için pgvector resmi belgelerine göz atabilirsiniz.

pgvector ile Vektör Sorguları

pgvector, vektörler arası mesafeleri hesaplayarak benzerlik araması yapmanızı sağlayan bir dizi operatör sunar. Yaygın olanlar:

• <->: L2 mesafesi (Öklidyen mesafe). Vektörler arası doğrusal mesafeyi ölçer.
• <#>: İç çarpım (Inner Product). Kosinüs benzerliğine yakındır; yönsel benzerlik ölçer.
• <=>: Kosinüs mesafesi (Cosine Distance). 1 - Cosine Similarity; yalnızca yönü dikkate alır, büyüklüğü etkilemez.

Aşağıda en yaygın vektör sorgularının SQL örneklerini bulabilirsiniz.

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

Verilen bir sorgu vektörüne en yakın (yani mesafesi en kısa olan) vektörleri bulur. Genellikle mesafeye göre ORDER BY ile sıralanır ve LIMIT ile sonucu sınırlandırılır.

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

   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 şekilde sıralanır (mesafe düşükse daha benzer)
   LIMIT 5;

Vektör Benzerlik Sorgusu (Similarity Search)

En yakın komşuya benzer şekilde, fakat daha çok benzerlik skorlarını göstermeye odaklıdır.

1. Vektör [0.2, 0.3, 0.4] ile kosinüs mesafesi en düşük 5 vektörü ve mesafelerini göster:

   SELECT
       id,
       vector,
       -- Kosinüs mesafesini hesapla
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Mesafe küçükse daha benzer kabul edilir
   LIMIT 5;

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

Yüksek boyutlu vektörlerde veri dağılımını ve kümelenmeleri anlamak için görselleştirme yapılabilir. 2B veya 3B vektörler doğrudan dağılım grafiğiyle görselleştirilebilir; daha yüksek boyutlular, PCA veya t-SNE gibi boyut indirgeme teknikleriyle iki ya da üç boyuta indirgenerek çizilebilir.

Aşağıda, Python ve Matplotlib ile 3 boyutlu vektör verinizin nasıl görselleştirileceğini anlatan örnek bir rehber bulacaksınız.

1. Python Ortamını Hazırlayın: ServBay içinde ya da dışında bir Python ortamı oluşturmalısınız. Eğer ServBay'in Python paketini etkinleştirdiyseniz onu da kullanabilirsiniz. Ek olarak, PostgreSQL ile bağlantı için psycopg2, görselleştirme için matplotlib kurmanız gerekir:

   # Sisteminizdeki veya kendi oluşturduğunuz Python için
   pip install psycopg2 matplotlib
   
   # ServBay Python'u kullanıyorsanız, kendi pip yolundan kurulum:
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Lütfen ortamınıza uygun pip/iç yolu kullanın.

2. Python Script'i Oluşturun: Bir Python dosyası oluşturun (örneğin visualize_vectors.py) ve aşağıdaki kodu kopyalayın. Aşağıdaki bağlantı ayarlarını ServBay PostgreSQL yapılandırmanıza göre düzenleyin (dbname, user, password, host, port).

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # 3B dağılım grafiği için gerekli modül
   
   # Veritabanı bağlantı ayarları - Kendi ServBay kurulumunuza göre düzenleyin
   db_params = {
       "dbname": "your_database_name", # Veritabanı adınızı girin
       "user": "servbay",              # Kullanıcı adınız (genellikle servbay veya postgres)
       "password": "",                 # Varsayılan olarak boş olabilir
       "host": "localhost",            # ServBay PostgreSQL genelde localhost'tadır
       "port": "5432"                  # Varsayılan port
   }
   
   conn = None
   cur = None
   
   try:
       # Veritabanına bağlan
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Vektör verilerini sorgula
       # Not: psycopg2 varsayılan olarak vector tiplerini '[x, y, z]' şeklinde string olarak getirir.
       # Manuel parse gerekebilir veya pgvector ile entegre bir sürümle daha kolay olabilir.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Stringi parçalara bölüp listeye çevir
       vectors = []
       for row in vectors_raw:
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("Vektör verisi bulunamadı.")
           exit()
   
       # Boyutların tutarlı olduğunu doğrulayın (örnek 3 boyut için yapılmıştır)
       if any(len(v) != 3 for v in vectors):
            print("Uyarı: Vektörlerin boyutları tutarsız veya 3 boyutlu değil; 3B çizim yapılamaz.")
            exit()
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # 3D scatter plot (dağılım grafiği)
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Dimension 1')
       ax.set_ylabel('Dimension 2')
       ax.set_zlabel('Dimension 3')
       ax.set_title('3 Boyutlu Vektör Görselleştirmesi')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Veritabanı bağlantısı veya sorgu hatası: {e}")
   except Exception as e:
       print(f"Bir hata oluştu: {e}")
   finally:
       # Bağlantıyı kapat
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Script'i Çalıştırın: Terminalde dosyanızı çalıştırın:

   python visualize_vectors.py

   Script, PostgreSQL veritabanına bağlanacak, vektör verilerini okuyacak ve Matplotlib ile bir 3B dağılım grafiği penceresi oluşturacaktır.

Sıkça Sorulan Sorular (SSS)

• S: \dx çıktısında vector eklentisi yoksa ne yapmalıyım? C: Öncelikle CREATE EXTENSION vector; komutunu başarıyla çalıştırdığınızdan emin olun. Eğer hâlâ görünmüyorsa, ServBay PostgreSQL paketinizin doğru yüklendiğinden ve etkinleştirildiğinden emin olun. pgvector dosyaları PostgreSQL'in share/extension klasöründe yer almalı. Eksikse, PostgreSQL paketini yeniden yüklemeyi veya güncellemeyi deneyin.
• S: Veritabanına bağlanırken kimlik doğrulama hatası alıyorum; çözümü nedir? C: psql veya Python scriptinizde kullandığınız kullanıcı adı/parola, host ve port bilgilerinin ServBay PostgreSQL ayarlarıyla tutarlı olduğundan emin olun. Yerel bağlanmalarda genellikle kullanıcı adı olarak servbay veya postgres kullanılır, parola boş bırakılmış olabilir.
• S: Vektör indeks parametreleri (lists, m, ef_construction) nasıl seçilmeli? C: Bu parametreler performans ve başarı oranı üzerinde ciddi etkiye sahiptir, "en iyi" değerler duruma göre değişir. Veri kümenizin boyutu, boyut sayısı, sorgu gecikmesi/kesin doğruluk gereksinimlerinize göre deney yapmanız önerilir. Ayrıntılı tavsiyeler için pgvector resmi dökümantasyonuna göz atabilirsiniz.

Sonuç

pgvector, güçlü vektör veritabanı yeteneklerini olgun ve stabil PostgreSQL sistemine kazandırır; böylece geliştiricilere yerel olarak AI ve vektör tabanlı uygulamalar geliştirme kolaylığı sunar. ServBay'in önyüklü pgvector desteği, ortam kurulumunu neredeyse zahmetsiz hâle getirir.

Bu rehberdeki adımları takip ederek ServBay PostgreSQL ortamında kolaylıkla pgvector'ü etkinleştirebilir, vektör tabloları oluşturabilir, sorguları hızlandırmak için indeksler ayarlayabilir ve çeşitli benzerlik araması işlemleri yapabilirsiniz. ServBay’in sunduğu diğer araç ve ortam olanaklarıyla birleştirerek, modern web uygulamalarınızı ve veri yoğun projelerinizi daha hızlı ve verimli şekilde inşa edebilirsiniz.