Panduan Menggunakan Ekstensi pgvector PostgreSQL di ServBay

pgvector adalah ekstensi pihak ketiga yang sangat canggih untuk pangkalan data PostgreSQL, menambahkan tipe data vektor serta metode indeks vektor yang efisien seperti IVFFlat dan HNSW. Fitur ini memungkinkan PostgreSQL untuk mendukung penyimpanan vektor dan pencarian kemiripan vektor secara asli, menjadikannya pilihan ideal untuk membangun aplikasi AI, sistem rekomendasi, pengenalan gambar, dan pemrosesan bahasa alami yang membutuhkan pengolahan data vektor berdimensi tinggi.

Sebagai lingkungan pengembangan web lokal yang terintegrasi, ServBay telah memaketkan PostgreSQL beserta ekstensi pgvector, sehingga proses mengaktifkan dan menggunakan pangkalan data vektor di lingkungan lokal Anda menjadi sangat mudah. Artikel ini akan menjelaskan secara detail bagaimana memanfaatkan pgvector di ServBay.

Apa Itu pgvector dan Mengapa Penting?

Dalam banyak skenario aplikasi modern, data tidak lagi hanya berupa teks atau angka terstruktur. Khususnya seiring berkembangnya kecerdasan buatan dan pembelajaran mesin, data sering kali direpresentasikan sebagai vektor berdimensi tinggi, dikenal sebagai "embedding". Vektor-vektor ini mengandung informasi semantik atau fitur dari suatu data, seperti karakter visual dari gambar, makna dari teks, maupun preferensi pengguna.

Ekstensi pgvector memungkinkan PostgreSQL untuk menyimpan vektor-vektor tersebut secara langsung, serta melakukan pencarian kemiripan vektor (nearest neighbor search) dengan efisien. Ini berarti Anda dapat menggunakan bahasa SQL yang sudah Anda kenal untuk menemukan data yang mirip dengan vektor tertentu, tanpa perlu memisahkan data vektor ke pangkalan data khusus, sehingga tumpukan teknologi menjadi lebih sederhana.

Syarat Awal

Sebelum mulai menggunakan pgvector, pastikan Anda telah memenuhi persyaratan berikut:

1. ServBay telah diinstal dan dijalankan di macOS Anda.
2. Paket PostgreSQL pada daftar "Packages" ServBay sudah diaktifkan. Jika belum, temukan PostgreSQL pada antarmuka aplikasi ServBay dan ubah statusnya menjadi "Enabled".

Cara Mengaktifkan Ekstensi pgvector di PostgreSQL ServBay

ServBay sudah menyertakan file ekstensi pgvector di direktori instalasi PostgreSQL. Anda tidak perlu mengunduh atau melakukan kompilasi manual. Anda hanya perlu mengaktifkan ekstensi ini di basis data yang ingin Anda gunakan.

Langkah-langkah untuk mengaktifkan ekstensi pgvector di pangkalan data PostgreSQL ServBay:

1. Koneksi ke Basis Data PostgreSQL: Anda dapat menggunakan alat baris perintah psql untuk terhubung ke instance PostgreSQL yang tersedia di ServBay. Konfigurasi default biasanya mengizinkan koneksi lokal, dengan user bawaan seperti postgres atau servbay, serta port default 5432. Jika konfigurasi ServBay Anda berbeda, silakan cek panduan konfigurasi basis datanya.

   Buka terminal dan sambungkan dengan perintah berikut (sesuaikan nama user dan basis data sesuai konfigurasi):

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

   • -U servbay: menentukan username sebagai servbay (atau postgres).
   • -d your_database_name: menentukan nama basis data yang akan diakses. Jika basis data belum dibuat, Anda dapat membuatnya terlebih dahulu (misalnya dengan CREATE DATABASE servbay_demo_db;).
   • -h localhost: host adalah lokal.
   • -p 5432: port default PostgreSQL ServBay.

2. Buat Ekstensi vector: Setelah berhasil terhubung, di prompt psql jalankan perintah SQL berikut untuk mengaktifkan ekstensi pgvector:

   CREATE EXTENSION vector;

   Jika ekstensi sudah ada, Anda akan mendapat peringatan bahwa ekstensi telah tersedia.

3. Verifikasi Instalasi: Untuk memastikan pgvector sudah aktif, tampilkan daftar ekstensi yang terpasang dengan perintah berikut:

   \dx

   Di daftar keluaran, Anda seharusnya melihat ekstensi bernama vector beserta informasi versinya.

                              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)

   (Catatan: Versi mungkin berbeda bergantung pada versi pgvector yang dipaketkan ServBay)

Konfigurasi dan Penggunaan pgvector

Setelah ekstensi pgvector diaktifkan, Anda dapat mulai membuat dan mengelola data vektor di basis data Anda.

Membuat Tabel dengan Kolom Vektor

Pertama, buat tabel untuk menyimpan data vektor Anda. pgvector menyediakan tipe data baru bernama VECTOR(dimensions), di mana dimensions adalah banyaknya dimensi vektor.

Contoh berikut membuat tabel bernama embeddings untuk menyimpan vektor 3 dimensi:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Definisi kolom vektor 3 dimensi
    vector VECTOR(3)
);

Selanjutnya, masukkan beberapa data vektor contoh:

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]'); -- Tambah data lebih banyak agar contoh query lebih jelas

Catatan: Nilai vektor harus ditempatkan dalam tanda kurung [ ], dengan elemen dipisahkan oleh koma.

Membuat Indeks Vektor untuk Kinerja Query Lebih Cepat

Untuk tabel dengan jumlah data vektor yang besar, membuat indeks sangat penting untuk mempercepat pencarian kemiripan vektor. pgvector mendukung dua tipe indeks utama: IVFFlat dan HNSW. Pilih tipe indeks sesuai kebutuhan Anda (kecepatan query, waktu pembuatan indeks, penggunaan memori, recall, dan lain-lain).

• IVFFlat (Indeks File Terbalik dengan Kompresi Flat): Cocok untuk dataset besar dengan kebutuhan recall yang tidak terlalu tinggi. Waktu pembuatan indeks relatif cepat.
• HNSW (Hierarchical Navigable Small World): Umumnya memberikan recall yang lebih tinggi dan kecepatan query yang lebih baik, namun waktu pembuatan indeks lebih lama dan memori yang dibutuhkan lebih besar.

Berikut contoh pembuatan indeks IVFFlat dan HNSW pada kolom vector tabel embeddings:

1. Membuat Indeks IVFFlat:

   -- Sebelum membuat indeks IVFFlat, jalankan ANALYZE untuk mengumpulkan statistik
   ANALYZE embeddings;
   
   -- Membuat indeks IVFFlat
   -- WITH (lists = 100): menentukan jumlah daftar inverted. Sesuaikan nilai berdasarkan ukuran dataset.
   -- Semakin banyak lists, indeks lebih lama dibuat dan query lebih banyak daftar yang dipindai (dapat lebih lambat), namun recall lebih tinggi.
   -- Saran resmi: lists = sqrt(jumlah baris).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. Membuat Indeks HNSW:

   -- Membuat indeks HNSW
   -- WITH (m = 16, ef_construction = 200): parameter indeks HNSW.
   -- m: Jumlah koneksi maksimum per node. Mempengaruhi konektivitas, efisiensi query, dan memori.
   -- ef_construction: Ruang lingkup pencarian saat membangun indeks. Mempengaruhi waktu, memori, dan kualitas indeks (recall).
   -- Sesuaikan parameter dengan kebutuhan data dan performa Anda.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Catatan: Parameter indeks seperti lists, m, dan ef_construction akan berpengaruh signifikan pada performa dan recall. Pilihan terbaik tergantung data dan pola query Anda—eksperimen sangat disarankan. Silakan konsultasikan dokumentasi resmi pgvector untuk penjelasan dan rekomendasi parameter lebih detail.

Melakukan Kueri Vektor dengan pgvector

pgvector menyediakan operator jarak untuk menghitung kemiripan antara vektor, sehingga dapat melakukan pencarian data serupa secara efisien. Operator jarak yang umum:

• <->: Jarak L2 (Euclidean). Mengukur jarak lurus antar vektor.
• <#>: Inner Product (Perkalian Dalam). Berkaitan dengan kemiripan cosinus, mengukur arah kemiripan.
• <=>: Jarak Cosinus (Cosine Distance). Nilai dari 1 - kemiripan cosinus. Cocok untuk data dengan vektor berdimensi sama tanpa memperhatikan besaran vektor.

Berikut contoh umum kueri vektor:

Pencarian Tetangga Terdekat (Nearest Neighbor Search)

Mencari vektor yang jaraknya paling dekat dengan vektor yang Anda tentukan. Biasanya menggunakan ORDER BY dengan operator jarak, serta LIMIT untuk membatasi jumlah hasil.

1. Mencari 5 vektor dengan L2 jarak terdekat ke [0.2, 0.3, 0.4]:

   SELECT
       id,
       vector,
       -- Hitung jarak L2 ke vektor query
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Urutkan naik (jarak kecil lebih mirip)
   LIMIT 5;

Pencarian Kemiripan Vektor (Similarity Search)

Mirip dengan pencarian tetangga terdekat, namun menonjolkan skor kemiripan.

1. Mencari 5 vektor dengan jarak cosinus terdekat ke [0.2, 0.3, 0.4], tampilkan nilai jarak:

   SELECT
       id,
       vector,
       -- Hitung jarak cosinus ke vektor query
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Urutkan naik (semakin mirip)
   LIMIT 5;

Visualisasi Data Vektor (Opsional)

Visualisasi data vektor berdimensi tinggi dapat membantu memahami pola dan cluster dalam data. Untuk vektor 2D atau 3D, Anda bisa langsung membuat scatter plot. Untuk vektor berdimensi lebih tinggi, biasanya diperlukan teknik reduksi dimensi (seperti PCA atau t-SNE) sebelum visualisasi ke 2D/3D.

Berikut contoh sederhana menggunakan Python dan Matplotlib untuk memvisualisasikan vektor 3 dimensi.

1. Siapkan Lingkungan Python: Anda bisa menjalankan Python di dalam atau di luar ServBay. Jika menggunakan Python dari ServBay, pastikan paketnya diaktifkan. Instal juga library koneksi PostgreSQL (psycopg2) dan plotting (matplotlib):

   # Jika menggunakan Python sistem atau instalasi sendiri
   pip install psycopg2 matplotlib
   
   # Jika memakai Python dari ServBay, gunakan pip di path ServBay atau perintah CLI ServBay
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Pastikan menyesuaikan lokasi pip sesuai environment Python Anda.

2. Buat Skrip Python: Buat file Python (misal visualize_vectors.py), lalu salin kode berikut. Jangan lupa sesuaikan parameter koneksi (dbname, user, password, host, port) dengan konfigurasi PostgreSQL ServBay Anda.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Modul untuk scatter plot 3D
   
   # Parameter koneksi database - Sesuaikan dengan konfigurasi ServBay Anda
   db_params = {
       "dbname": "your_database_name", # Ganti dengan nama basis data Anda
       "user": "servbay",              # Ganti sesuai user PostgreSQL ServBay (biasanya servbay atau postgres)
       "password": "",                 # Ganti dengan password database Anda (untuk lokal bisa kosong)
       "host": "localhost",            # PostgreSQL ServBay biasanya di localhost
       "port": "5432"                  # Port default PostgreSQL ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Hubungkan ke basis data PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Query data vektor
       # Catatan: psycopg2 biasanya membaca tipe vector sebagai string seperti '[x, y, z]'
       # Lakukan parsing manual untuk mengubah ke list angka float
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parsing vektor string ke list angka
       vectors = []
       for row in vectors_raw:
           # Hapus kurung, split koma, konversi ke float
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("Tidak ditemukan data vektor.")
           exit()
   
       # Pastikan semua vektor berdimensi sama (contoh: 3D)
       if any(len(v) != 3 for v in vectors):
            print("Peringatan: Vektor tidak konsisten atau bukan 3D, tidak dapat membuat plot 3D.")
            # Bisa pilih buat plot 2D atau exit
            exit()
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # Buat scatter plot 3D
       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('3D Vector Visualization')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Error koneksi atau query database: {e}")
   except Exception as e:
       print(f"Terjadi error: {e}")
   finally:
       # Tutup koneksi database
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Jalankan Skripnya: Di terminal, jalankan skrip Python tersebut:

   python visualize_vectors.py

   Skrip akan terhubung ke pangkalan data PostgreSQL Anda, membaca data vektor, lalu menampilkan scatter plot 3D menggunakan Matplotlib.

FAQ (Pertanyaan Umum)

• Tanya: Saya tidak menemukan ekstensi vector pada output \dx, apa solusinya? Jawab: Pastikan Anda sudah menjalankan perintah CREATE EXTENSION vector; tanpa error. Jika tetap tidak muncul, cek apakah paket PostgreSQL ServBay sudah terinstal dan aktif. File ekstensi pgvector harus berada dalam subdirektori share/extension di folder PostgreSQL. Jika file hilang, Anda bisa mencoba install atau update ulang paket PostgreSQL ServBay.
• Tanya: Gagal otentikasi saat koneksi database, solusinya? Jawab: Pastikan username, password, host, dan port di perintah psql atau pada skrip Python sudah cocok dengan konfigurasi PostgreSQL ServBay Anda. Untuk akses lokal, user default biasanya servbay atau postgres, mungkin tanpa password.
• Tanya: Bagaimana memilih parameter indeks vektor seperti lists, m, ef_construction? Jawab: Parameter tersebut sangat berpengaruh pada performa dan recall, tidak ada nilai baku yang terbaik. Anda perlu bereksperimen dan sesuaikan dengan ukuran, dimensi dataset, kebutuhan latensi query, dan target recall. Lihat dokumentasi resmi pgvector untuk panduan dan rekomendasi detail.

Kesimpulan

pgvector membawa kapabilitas database vektor yang hebat ke ekosistem PostgreSQL yang sudah matang dan stabil, memudahkan pengembang membangun aplikasi AI dan pencarian vektor di lingkungan lokal. ServBay, dengan pgvector yang sudah dipaketkan, semakin menyederhanakan proses setup lingkungan.

Dengan mengikuti panduan ini, Anda bisa dengan mudah mengaktifkan pgvector di PostgreSQL ServBay, membuat tabel vektor, mempercepat query menggunakan indeks efisien, serta melakukan pencarian kemiripan vektor. Bila digabungkan dengan tool dan lingkungan lain yang tersedia di ServBay, Anda dapat membangun dan menguji aplikasi web modern atau proyek data intensif lebih cepat dan fleksibel.