Panduan Penggunaan Ekstensi pgvector PostgreSQL di ServBay

pgvector adalah ekstensi pihak ketiga yang kuat untuk basis data PostgreSQL. Ekstensi ini menambahkan tipe data vektor serta metode indeks vektor yang efisien, seperti IVFFlat dan HNSW. Dengan fitur ini, PostgreSQL dapat mendukung penyimpanan vektor dan pencarian kesamaan vektor secara native, sehingga ideal untuk membangun aplikasi AI, sistem rekomendasi, pengenalan gambar, dan pemrosesan bahasa alami yang membutuhkan penanganan data vektor berdimensi tinggi.

Sebagai lingkungan pengembangan web lokal terintegrasi, ServBay telah menyediakan PostgreSQL dan ekstensi pgvector secara built-in. Hal ini sangat mempermudah proses mengaktifkan dan menggunakan database vektor di lingkungan pengembangan lokal Anda. Artikel ini akan menjelaskan secara detail cara memanfaatkan pgvector di ServBay.

Apa Itu pgvector? Mengapa Penting?

Pada banyak skenario aplikasi modern, data tidak lagi hanya berupa teks terstruktur dan angka. Dengan kemajuan AI dan machine learning, data sering direpresentasikan sebagai vektor berdimensi tinggi, dikenal juga sebagai "embedding". Vektor-vektor ini menangkap informasi semantik atau fitur suatu data—seperti ciri visual gambar, makna teks, atau preferensi pengguna.

Ekstensi pgvector memungkinkan PostgreSQL menyimpan vektor-vektor ini secara langsung dan melakukan pencarian kemiripan vektor (nearest neighbor search) yang efisien. Itu artinya, Anda dapat menggunakan SQL yang sudah familiar untuk mencari data yang paling mirip dengan vektor tertentu, tanpa harus menggunakan database vektor terpisah—menyederhanakan tumpukan teknologi Anda.

Prasyarat

Sebelum menggunakan pgvector, pastikan Anda telah memenuhi persyaratan berikut:

1. ServBay telah terinstal dan berjalan di macOS.
2. Paket PostgreSQL sudah diaktifkan di laman “Packages” ServBay. Jika belum, buka aplikasi ServBay, cari PostgreSQL, dan pastikan statusnya "Enabled".

Mengaktifkan Ekstensi pgvector di PostgreSQL ServBay

ServBay telah menyertakan file ekstensi pgvector di direktori instalasi PostgreSQL. Anda tidak perlu mengunduh atau meng-compile secara manual. Anda hanya perlu mengaktifkannya pada database tertentu yang ingin digunakan bersama pgvector.

Langkah-langkah untuk mengaktifkan pgvector di database PostgreSQL ServBay:

1. Terhubung ke Basis Data PostgreSQL: Anda bisa menggunakan alat baris perintah psql untuk terhubung ke PostgreSQL instance dari ServBay. Pengaturan default ServBay biasanya mengizinkan koneksi lokal dengan user postgres atau servbay dan port default 5432. Jika konfigurasi berbeda, silakan cek dokumentasi konfigurasi database ServBay Anda.

   Buka Terminal dan jalankan perintah berikut (silakan sesuaikan user/database sesuai konfigurasi Anda):

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

   • -U servbay: Menentukan user sebagai servbay (atau postgres).
   • -d your_database_name: Nama database yang akan dikoneksikan. Jika database belum ada, buat dulu (mis. CREATE DATABASE servbay_demo_db;).
   • -h localhost: Host lokal.
   • -p 5432: Port 5432 adalah default PostgreSQL di ServBay.

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

   CREATE EXTENSION vector;

   Jika ekstensi sudah ada, Anda akan mendapat notifikasi bahwa ekstensi sudah tersedia.

3. Verifikasi Instalasi: Untuk memverifikasi bahwa pgvector sudah aktif, tampilkan daftar ekstensi terpasang:

   \dx

   Pada output, cari ekstensi bernama vector beserta info 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 tergantung paket pgvector di ServBay.)

Konfigurasi & Penggunaan pgvector

Setelah ekstensi pgvector aktif, Anda bisa mulai membuat dan mengelola data vektor di database.

Membuat Tabel dengan Kolom Vektor

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

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

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Mendefinisikan kolom vektor berdimensi 3
    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 agar contoh query berikut lebih bervariasi

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

Membuat Indeks Vektor untuk Performa Query

Untuk tabel dengan data vektor berjumlah besar, penggunaan indeks sangat penting agar pencarian kemiripan vektor lebih cepat. pgvector mendukung dua tipe indeks utama: IVFFlat dan HNSW. Pilihan tipe bergantung pada kebutuhan Anda (kecepatan, waktu pembuatan indeks, penggunaan memori, recall rate, dsb).

• IVFFlat (Inverted File Index dengan kompresi Flat): Cocok untuk dataset besar dengan kebutuhan recall sedikit lebih rendah. Proses pembuatannya lebih cepat.
• HNSW (Hierarchical Navigable Small World): Biasanya recall lebih tinggi dan pencarian lebih cepat, tetapi membutuhkan waktu pembuatan indeks dan memori lebih banyak.

Contoh membuat indeks IVFFlat dan HNSW pada kolom vector di tabel embeddings:

1. Membuat Indeks IVFFlat:

   -- Menjalankan ANALYZE sebelum membuat IVFFlat untuk mengumpulkan statistik
   ANALYZE embeddings;
   
   -- Membuat indeks IVFFlat
   -- WITH (lists = 100): Jumlah inverted list. Nilai ini perlu disesuaikan dengan ukuran data.
   -- lists semakin besar, pembuatan indeks makin lama, query bisa lebih lambat, tetapi recall makin baik.
   -- Rekomendasi dari dokumen resmi: lists = sqrt(jumlah_row).
   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 untuk HNSW.
   -- m: jumlah maksimum koneksi per node. Berpengaruh pada performa query dan penggunaan memori.
   -- ef_construction: cakupan pencarian saat membangun indeks. Berpengaruh pada kualitas indeks dan waktu pembuatannya.
   -- Sesuaikan parameter sesuai kebutuhan dan karakter data.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Catatan: Parameter indeks seperti lists, m, ef_construction secara signifikan memengaruhi performa dan recall pencarian. Pilih nilai yang sesuai dengan memahami data dan pola query Anda, serta lakukan pengujian. Lihat dokumentasi pgvector untuk detail dan tips tuning.

Query Vektor dengan pgvector

pgvector menyediakan sejumlah operator untuk menghitung jarak antar vektor, memungkinkan pencarian kemiripan secara efisien. Operator yang sering digunakan:

• <->: Jarak L2 (Euclidean Distance), mengukur “jarak garis lurus” antar vektor.
• <#>: Inner Product. Terkait dengan cosine similarity, berguna untuk kemiripan arah.
• <=>: Cosine Distance. Sama dengan 1 - cosine similarity. Mengukur kemiripan arah, tanpa memperhatikan panjang vektor.

Beberapa contoh query untuk pencarian vektor:

Query Nearest Neighbor (Tetangga Terdekat)

Mencari vektor yang paling mirip (berjarak paling kecil) dengan vektor tertentu. Biasanya menggunakan ORDER BY dan operator jarak, lalu LIMIT.

1. Mencari 5 vektor terdekat (L2) dengan [0.2, 0.3, 0.4]:

   SELECT
       id,
       vector,
       -- Menghitung jarak L2 ke vektor query
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Urut naik, semakin kecil semakin mirip
   LIMIT 5;

Query Kemiripan Vektor (Similarity Search)

Serupa dengan query nearest neighbor, namun lebih menonjolkan skor kemiripan.

1. Mencari 5 vektor dengan cosine distance terdekat ke [0.2, 0.3, 0.4], tampilkan jaraknya:

   SELECT
       id,
       vector,
       -- Menghitung cosine distance ke vektor query
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Urut naik, semakin kecil semakin mirip
   LIMIT 5;

Visualisasi Data Vektor (Opsional)

Visualisasi data vektor berdimensi tinggi membantu memahami distribusi dan kluster data. Untuk vektor 2D/3D dapat langsung di-plot; untuk dimensi lebih tinggi, gunakan metode reduksi dimensi (seperti PCA atau t-SNE) sebelum divisualisasikan.

Berikut contoh sederhana visualisasi vektor 3D menggunakan Python dan Matplotlib.

1. Siapkan Lingkungan Python: Anda bisa memakai Python di luar ServBay ataupun Python bawaan ServBay (pastikan sudah aktif). Instal library koneksi ke PostgreSQL (psycopg2) dan plotting (matplotlib):

   # Jika memakai Python sistem atau install sendiri
   pip install psycopg2 matplotlib
   
   # Jika memakai Python dari ServBay, gunakan pip di direktori bin ServBay
   # /Applications/ServBay/Packages/python/bin/pip install psycopg2 matplotlib

   Silakan sesuaikan path pip dengan lingkungan Python Anda.

2. Buat Skrip Python: Buat file Python (misal visualize_vectors.py), salin kode berikut. Silakan sesuaikan parameter koneksi (dbname, user, password, host, port) sesuai konfigurasi PostgreSQL ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Modul untuk scatter plot 3D
   
   # Parameter koneksi DB - sesuaikan dengan setting ServBay Anda
   db_params = {
       "dbname": "your_database_name", # Ubah ke nama database Anda
       "user": "servbay",              # Ubah ke user PostgreSQL ServBay (servbay atau postgres)
       "password": "",                 # Ubah jika ada password (localhost bisa kosong)
       "host": "localhost",            # PostgreSQL ServBay berjalan di localhost
       "port": "5432"                  # Port default PostgreSQL ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Koneksi ke database PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Query data vektor
       # Catatan: psycopg2 default akan menganggap tipe vector di PostgreSQL sebagai string '[x, y, z]'
       # Perlu parsing manual, atau jika driver terbaru mendukung pgvector, bisa otomatis.
       # Di sini diasumsikan hasilnya string.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parsing string vektor, diubah ke list float
       vectors = []
       for row in vectors_raw:
           # Hilangkan tanda kurung siku, split dengan koma, lalu float
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("Data vektor tidak ditemukan.")
           exit()
   
       # Ambil koordinat untuk plot
       # Pastikan semua vektor berdimensi sama (3D)
       if any(len(v) != 3 for v in vectors):
            print("Peringatan: Dimensi vektor tidak konsisten atau bukan 3D, tidak bisa plot 3D.")
            # Bisa buat plot 2D atau keluar
            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('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"Kesalahan koneksi/database: {e}")
   except Exception as e:
       print(f"Terjadi kesalahan: {e}")
   finally:
       # Tutup koneksi database
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Jalankan Skrip: Di terminal, jalankan skrip Python:

   python visualize_vectors.py

   Skrip ini akan menghubungkan ke database PostgreSQL Anda, mengambil data vektor, lalu menampilkan scatter plot 3D menggunakan Matplotlib.

FAQ (Pertanyaan yang Sering Diajukan)

• T: Mengapa ekstensi vector tidak muncul di hasil \dx? J: Pastikan Anda telah menjalankan perintah CREATE EXTENSION vector; tanpa error. Jika tetap tidak muncul, cek apakah paket PostgreSQL ServBay sudah benar-benar aktif. File ekstensi pgvector harus ada di direktori share/extension dalam instalasi PostgreSQL. Jika file hilang, cobalah reinstall atau update paket PostgreSQL di ServBay.
• T: Gagal otentikasi saat koneksi database, apa solusinya? J: Pastikan username, password, host, dan port yang digunakan di perintah psql atau skrip Python sudah sesuai dengan konfigurasi PostgreSQL di ServBay. Untuk localhost, user default umumnya servbay atau postgres, seringkali tanpa password.
• T: Bagaimana memilih nilai parameter indeks lists, m, ef_construction? J: Ketiga parameter ini sangat berpengaruh ke performa dan recall pencarian, sehingga tidak ada nilai universal terbaik. Cobalah tuning berdasarkan ukuran dataset, dimensi, kebutuhan latency, dan target recall. Lihat panduan dan rekomendasi lebih detail di dokumentasi pgvector.

Kesimpulan

pgvector membawa kemampuan database vektor yang kuat ke sistem PostgreSQL yang sudah matang dan stabil, sangat memudahkan pengembangan aplikasi AI dan vektor secara lokal. Dengan ekstensi pgvector yang sudah tersedia di ServBay, proses setup menjadi jauh lebih sederhana.

Ikuti panduan ini untuk mengaktifkan pgvector, membuat tabel vektor, mempercepat pencarian dengan indeks, dan menjalankan query kemiripan vektor di PostgreSQL pada ServBay dengan mudah. Dengan ekosistem tools lain dari ServBay, Anda akan bisa membangun dan menguji aplikasi web modern dan proyek data-intensif dengan lebih efisien.