Panduan Penggunaan Ekstensi pgvector PostgreSQL di ServBay

pgvector adalah ekstensi pihak ketiga yang powerful untuk database PostgreSQL, menghadirkan tipe data vektor beserta metode indeks vektor yang efisien seperti IVFFlat dan HNSW. Hal ini memungkinkan PostgreSQL mendukung penyimpanan dan pencarian vektor secara native, menjadikannya solusi sempurna untuk membangun aplikasi AI, sistem rekomendasi, pengenalan gambar, dan pemrosesan bahasa alami yang membutuhkan pengolahan data vektor berdimensi tinggi.

ServBay adalah lingkungan pengembangan web lokal yang terintegrasi dan telah menyediakan PostgreSQL serta ekstensi pgvector secara langsung, sehingga memudahkan proses aktivasi serta penggunaan database vektor di lingkungan pengembangan lokal Anda. Panduan ini membahas langkah-langkah praktis memakai pgvector di ServBay.

Apa Itu pgvector dan Kenapa Penting?

Pada banyak kasus aplikasi modern, data tidak lagi sebatas teks atau angka terstruktur. Berkat kemajuan kecerdasan buatan dan machine learning, data kini sering direpresentasikan sebagai vektor berdimensi tinggi—disebut juga "embeddings". Vektor ini menangkap informasi semantik atau fitur data, misalnya karakteristik visual gambar, makna teks, maupun preferensi pengguna.

Ekstensi pgvector memungkinkan PostgreSQL menyimpan vektor tersebut secara langsung dan menjalankan pencarian kemiripan vektor (nearest neighbor search) secara efisien. Artinya, Anda bisa memakai SQL yang telah familiar untuk menemukan data yang paling mirip dengan vektor tertentu, tanpa perlu database vektor terpisah—menyederhanakan stack teknologi Anda.

Prasyarat

Sebelum mulai menggunakan pgvector, pastikan Anda sudah memenuhi syarat berikut:

1. ServBay telah terinstal dan berjalan di macOS.
2. Paket PostgreSQL telah diaktifkan di daftar “Packages” ServBay. Jika belum, temukan PostgreSQL di antarmuka aplikasi ServBay dan ubah statusnya menjadi “Enabled”.

Mengaktifkan Ekstensi pgvector di PostgreSQL ServBay

ServBay sudah menyediakan file ekstensi pgvector di folder instalasi PostgreSQL. Anda tidak perlu mengunduh atau melakukan kompilasi manual. Anda cukup mengaktifkan ekstensi ini di database yang ingin digunakan.

Berikut langkah untuk mengaktifkan pgvector di PostgreSQL ServBay:

1. Koneksi ke Database PostgreSQL: Anda dapat terhubung ke instance PostgreSQL ServBay menggunakan tool command line psql. Pengaturan default ServBay biasanya memungkinkan koneksi lokal, dengan user default seperti postgres atau servbay. Port default adalah 5432. Jika konfigurasi ServBay Anda berbeda, cek dokumentasi konfigurasi database ServBay.

   Buka terminal dan jalankan perintah berikut (ubah nama user/database sesuai konfigurasi Anda):

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

   • -U servbay: Menspesifikasikan user sebagai servbay (atau postgres).
   • -d your_database_name: Nama database tujuan. Jika belum ada, Anda bisa membuatnya terlebih dahulu (misal dengan CREATE DATABASE servbay_demo_db;).
   • -h localhost: Host lokal.
   • -p 5432: Port 5432 (default PostgreSQL ServBay).

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

   CREATE EXTENSION vector;

   Jika ekstensi sudah ada, akan muncul notifikasi bahwa ekstensi sudah tersedia.

3. Verifikasi Instalasi: Anda dapat mengecek ekstensi yang sudah terinstal dengan perintah berikut:

   \dx

   Pada hasil output, Anda akan melihat ekstensi bernama vector beserta versi detailnya.

                              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 tergantung versi pgvector yang terintegrasi di ServBay)

Konfigurasi & Penggunaan pgvector

Setelah aktif, Anda bisa membuat serta mengolah data vektor di PostgreSQL.

Membuat Tabel dengan Kolom Vektor

Mulailah dengan membuat sebuah tabel untuk menyimpan data vektor. pgvector menyediakan tipe data baru VECTOR(dimensi), di mana dimensi adalah jumlah dimensi vektornya.

Contoh membuat tabel bernama embeddings untuk menyimpan vektor berdimensi 3:

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

Selanjutnya, Anda dapat memasukkan 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]'); -- Tambahkan data lain agar contoh query lebih jelas

Catatan: Nilai vektor harus menggunakan tanda kurung siku [] dan elemen dipisahkan dengan koma.

Membuat Indeks Vektor untuk Performa Query

Untuk tabel dengan banyak data vektor, pembuatan indeks sangat penting guna mempercepat pencarian kemiripan vektor. pgvector mendukung dua jenis indeks utama: IVFFlat dan HNSW. Pilih jenis indeks sesuai kebutuhan Anda (misal kecepatan query, waktu membangun indeks, penggunaan memori, recall, dll).

• IVFFlat (Inverted File Index with Flat compression): Cocok untuk dataset besar, dengan kebutuhan recall yang tidak terlalu tinggi. Proses pembangunan indeks relatif cepat.
• HNSW (Hierarchical Navigable Small World): Biasanya memberi recall tinggi dan query lebih cepat, tapi pembangunan indeks lebih lama serta penggunaan memori lebih besar.

Contoh pembuatan indeks IVFFlat dan HNSW pada kolom vektor di tabel embeddings:

1. Indeks IVFFlat:

   -- Sebelum membuat indeks IVFFlat, jalankan ANALYZE untuk mengumpulkan statistik
   ANALYZE embeddings;
   
   -- Membuat indeks IVFFlat
   -- WITH (lists = 100): Menentukan jumlah inverted list. Sesuaikan nilai ini dengan ukuran data Anda.
   -- Semakin banyak lists, semakin lama membangun indeks dan membutuhkan lebih banyak waktu query, tapi recall meningkat.
   -- Saran: lists = sqrt(jumlah baris data).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. Indeks HNSW:

   -- Membuat indeks HNSW
   -- WITH (m = 16, ef_construction = 200): Parameter spesifik HNSW.
   -- m: Maksimal jumlah koneksi antar node (pengaruh ke performa/memori).
   -- ef_construction: Jumlah pencarian saat membangun indeks (pengaruh ke waktu/memori dan kualitas indeks/recall).
   -- Tuning diperlukan sesuai kebutuhan erformance dan data.
   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 sangat menentukan performa dan recall. Pilih nilai dengan memahami data dan pola query Anda, serta lakukan eksperimen jika perlu. Lihat dokumentasi resmi pgvector untuk detail dan tips tuning.

Query Data Vektor menggunakan pgvector

pgvector menyediakan beberapa operator untuk menghitung jarak antar vektor, mendukung pencarian kemiripan secara efisien. Operator umum meliputi:

• <->: Jarak L2 (Euclidean Distance; jarak garis lurus antar vektor).
• <#>: Inner Product (berkorelasi dengan cosine similarity, cocok untuk ngecek kemiripan arah vektor).
• <=>: Jarak Cosine (Cosine Distance = 1 - cosine similarity), beda arah tanpa pengaruh ukuran vektor.

Contoh query vektor di PostgreSQL:

Pencarian Terdekat (Nearest Neighbor Search)

Menemukan vektor yang paling mirip dengan sebuah vektor query (jaraknya paling kecil). Biasanya menggunakan ORDER BY dan operator jarak, plus LIMIT jumlah hasil.

1. Mencari 5 vektor dengan L2 Distance 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 dari jarak terkecil (paling mirip)
   LIMIT 5;

Query Kemiripan Vektor (Similarity Search)

Mirip nearest neighbor, namun lebih fokus ke nilai skor kemiripan.

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

   SELECT
       id,
       vector,
       -- Hitung jarak cosine ke vektor query
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Urut dari yang paling mirip
   LIMIT 5;

Visualisasi Data Vektor (Opsional)

Visualisasi vektor berdimensi tinggi berguna untuk memahami distribusi dan klaster data. Untuk vektor 2D atau 3D, Anda bisa langsung buat scatter plot. Untuk vektor lebih tinggi, gunakan teknik reduksi dimensi seperti PCA atau t-SNE agar bisa divisualisasi di 2D/3D.

Contoh sederhana berikut menunjukkan cara visualisasi vektor 3D pakai Python dan Matplotlib.

1. Menyiapkan Lingkungan Python: Buatlah environment Python baik di luar maupun di dalam ServBay. Jika pakai paket Python dari ServBay, pastikan sudah diaktifkan. Install library konektor PostgreSQL psycopg2 dan plotting matplotlib:

   # Jika pakai Python sistem ataupun instalasi sendiri
   pip install psycopg2 matplotlib
   
   # Jika pakai Python dari ServBay, kemungkinan via terminal atau akses bin directorynya
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Sesuaikan path pip dengan environment Python Anda.

2. Membuat Script Python: Buat file Python misal visualize_vectors.py dan copy kode di bawah ini. Ubah parameter koneksi sesuai konfigurasi PostgreSQL ServBay Anda (dbname, user, password, host, port).

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Import modul untuk plot 3D
   
   # Parameter koneksi database - sesuaikan dengan konfigurasi Anda
   db_params = {
       "dbname": "your_database_name", # Ganti dengan nama database Anda
       "user": "servbay",              # Ganti dengan user PostgreSQL ServBay (servbay atau postgres)
       "password": "",                 # Ganti dengan password database Anda (untuk lokal bisa dikosongkan)
       "host": "localhost",            # ServBay PostgreSQL biasanya di localhost
       "port": "5432"                  # Port default PostgreSQL ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Koneksi ke PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Mengambil data vektor
       # Catatan: psycopg2 akan membaca tipe vector PostgreSQL sebagai string '[x, y, z]'
       # Butuh parsing manual atau driver khusus pgvector & psycopg2 versi terbaru.
       # Contoh di bawah mengasumsikan hasil berupa string.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parse string vektor ke list angka
       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("Tidak ditemukan data vektor.")
           exit()
   
       # Ambil koordinat vektor
       # Pastikan semua berdimensi 3
       if any(len(v) != 3 for v in vectors):
            print("Peringatan: Dimensi vektor tidak konsisten atau bukan 3D, tidak bisa plot 3D.")
            exit()
   
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # Buat plot 3D
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Dimensi 1')
       ax.set_ylabel('Dimensi 2')
       ax.set_zlabel('Dimensi 3')
       ax.set_title('Visualisasi Vektor 3D')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Koneksi atau query database error: {e}")
   except Exception as e:
       print(f"Terjadi kesalahan: {e}")
   finally:
       # Tutup koneksi database
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Jalankan Script: Di terminal, eksekusi script Python tadi:

   python visualize_vectors.py

   Script ini akan terhubung ke database PostgreSQL Anda, mengambil data vektor, dan menampilkan jendela scatter plot 3D via Matplotlib.

FAQ (Pertanyaan Umum)

• T: Saya tidak menemukan ekstensi vector pada hasil \dx. Apa solusinya? J: Pastikan Anda telah menjalankan CREATE EXTENSION vector; tanpa error. Jika tetap tidak muncul, cek apakah paket PostgreSQL ServBay sudah terinstal dan diaktifkan. File ekstensi pgvector umumnya berada di subdirektori PostgreSQL share/extension. Jika filenya tidak ada, coba reinstall atau update paket PostgreSQL ServBay.
• T: Error autentikasi saat koneksi database? J: Pastikan username, password, host, dan port di psql atau script Python sama dengan konfigurasi ServBay. Di lokal, user default biasanya servbay atau postgres, dan password bisa kosong.
• T: Cara memilih parameter lists, m, ef_construction untuk indeks vektor? J: Parameter tersebut sangat berpengaruh pada performa dan recall, tidak ada nilai universal terbaik. Lakukan eksperimen sesuai jumlah data, dimensi, latency query, dan target recall Anda. Cek dokumentasi pgvector untuk panduan dan rekomendasi lebih detail.

Kesimpulan

pgvector menghadirkan fitur database vektor yang powerful ke ekosistem PostgreSQL yang sudah matang, memudahkan pengembang membangun aplikasi AI dan vektor secara lokal. Dengan pgvector yang sudah ter-preset oleh ServBay, proses setup lingkungan jadi sangat sederhana.

Berdasarkan panduan ini, Anda bisa dengan mudah mengaktifkan pgvector di PostgreSQL ServBay, membuat tabel untuk penyimpanan vektor, memanfaatkan indeks canggih untuk akselerasi query, dan menjalankan berbagai pencarian kemiripan vektor. Digabungkan dengan tool serta environment ServBay lainnya, Anda dapat membangun dan menguji aplikasi web modern dan proyek data-intensive secara optimal.