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:
- ServBay'i macOS üzerinde kurmuş ve çalıştırıyor olmalısınız.
- 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:
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ıklapostgres
veyaservbay
olur, port ise5432
'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):
bashpsql -U servbay -d your_database_name -h localhost -p 5432
1-U servbay
: Kullanıcı adı olarakservbay
(veyapostgres
) 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).
vector
Eklentisini Oluşturun: Bağlantı sağladığınızda, aşağıdaki SQL komutuylapgvector
eklentisini etkinleştirin:sqlCREATE EXTENSION vector;
1Eğer eklenti zaten varsa, bir uyarı görebilirsiniz, bu normaldir.
Kurulumu Doğrulayın: Kurulumun başarılı olduğunu görmek için yüklenmiş eklentileri listeleyin:
sql\dx
1Çı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)
1
2
3
4
5
6(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)
);
2
3
4
5
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
2
3
4
5
6
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:
IVFFlat İndeksi Oluşturma:
sql-- 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);
1
2
3
4
5
6
7
8HNSW İndeksi Oluşturma:
sql-- 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);
1
2
3
4
5
6Not: İ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.
- Vektör
[0.2, 0.3, 0.4]
ile L2 mesafesi en kısa olan 5 vektörü sorgulama:sqlSELECT 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;
1
2
3
4
5
6
7
8
9
10
Vektör Benzerlik Sorgusu (Similarity Search)
En yakın komşuya benzer şekilde, fakat daha çok benzerlik skorlarını göstermeye odaklıdır.
- Vektör
[0.2, 0.3, 0.4]
ile kosinüs mesafesi en düşük 5 vektörü ve mesafelerini göster:sqlSELECT 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;
1
2
3
4
5
6
7
8
9
10
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.
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çinmatplotlib
kurmanız gerekir:bash# 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
1
2
3
4
5Lütfen ortamınıza uygun pip/iç yolu kullanın.
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
).pythonimport 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()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69Script'i Çalıştırın: Terminalde dosyanızı çalıştırın:
bashpython visualize_vectors.py
1Script, 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ındavector
eklentisi yoksa ne yapmalıyım? C: ÖncelikleCREATE 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'inshare/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ı olarakservbay
veyapostgres
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çinpgvector
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.