Panduan Penggunaan Ekstensi pgvector PostgreSQL di ServBay

pgvector adalah sebuah ekstensi pihak ketiga yang kuat untuk pangkalan data PostgreSQL, yang menambahkan tipe data vektor beserta metode indeks vektor yang efisien seperti IVFFlat dan HNSW. Hal ini memungkinkan PostgreSQL secara native mendukung penyimpanan vektor dan pencarian kemiripan vektor—menjadikannya pilihan ideal untuk membangun aplikasi AI, sistem rekomendasi, pengenalan gambar, dan pemrosesan bahasa alami yang membutuhkan pengelolaan data vektor berdimensi tinggi.

Sebagai lingkungan pengembangan web lokal terintegrasi, ServBay telah membundel PostgreSQL dan ekstensi pgvector secara default, sehingga proses mengaktifkan dan menggunakan database vektor di lingkungan lokal Anda menjadi sangat sederhana. Artikel ini akan memandu Anda langkah demi langkah cara memakai pgvector di ServBay.

Apa Itu pgvector dan Kenapa Penting?

Di banyak skenario aplikasi modern, data kini tidak lagi sekadar teks terstruktur atau angka. Khususnya dengan berkembangnya kecerdasan buatan dan pembelajaran mesin, data sering kali direpresentasi sebagai vektor berdimensi tinggi, juga dikenal sebagai “embeddings”. Vektor-vektor ini menangkap makna atau fitur semantis dari data, misalnya karakteristik visual gambar, makna teks, atau preferensi pengguna.

Ekstensi pgvector membuat PostgreSQL mampu menyimpan vektor-vektor ini secara langsung dan menjalankan pencarian kemiripan vektor secara efisien (dikenal juga sebagai “Nearest Neighbor Search”). Ini berarti Anda dapat menggunakan sintaks SQL yang telah Anda kuasai untuk menemukan data yang paling mirip dengan sebuah vektor query, tanpa perlu menyimpan data vektor di database terpisah—sehingga menambah kesederhanaan pada teknologi stack Anda.

Prasyarat

Sebelum mulai menggunakan pgvector, pastikan Anda memenuhi prasyarat berikut:

1. ServBay telah terinstal dan berjalan di macOS Anda.
2. Paket PostgreSQL telah diaktifkan di daftar “Packages” ServBay. Jika belum, silakan buka aplikasi ServBay dan aktifkan PostgreSQL dengan mengubah statusnya menjadi “Enabled”.

Mengaktifkan Ekstensi pgvector di PostgreSQL ServBay

ServBay telah mem-bundle file ekstensi pgvector langsung di direktori instalasi PostgreSQL-nya. Anda tidak perlu mengunduh atau mengompilasi secara manual. Cukup aktifkan ekstensi di database yang ingin digunakan.

Berikut langkah-langkah mengaktifkan pgvector pada database PostgreSQL Anda di ServBay:

1. Terhubung ke Database PostgreSQL: Anda dapat menggunakan tool baris perintah psql untuk menyambung ke instance PostgreSQL yang disediakan oleh ServBay. Secara default, ServBay mengizinkan koneksi lokal; user biasanya postgres atau servbay, dan port default 5432. Jika konfigurasi ServBay Anda berbeda, silakan cek dokumentasi konfigurasi database ServBay.

   Buka terminal dan gunakan perintah berikut untuk koneksi (sesuaikan nama database & user sesuai pengaturan Anda):

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

   • -U servbay: Set user sebagai servbay (atau postgres).
   • -d your_database_name: Nama database yang ingin dihubungkan. Jika belum ada, buat terlebih dahulu (seperti CREATE DATABASE servbay_demo_db;).
   • -h localhost: Menghubungkan ke host lokal.
   • -p 5432: Port default PostgreSQL ServBay adalah 5432.

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

   CREATE EXTENSION vector;

   Jika ekstensi sudah pernah dibuat, Anda akan mendapat pesan bahwa ekstensi sudah ada.

3. Verifikasi Instalasi: Untuk memastikan pgvector telah aktif, Anda bisa menampilkan daftar ekstensi yang terpasang:

   \dx

   Di daftar output, Anda harus menemui ekstensi bernama vector beserta versi dan keterangannya.

                              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 ekstensi tergantung pada versi pgvector yang dibundle ServBay)

Konfigurasi & Penggunaan pgvector

Setelah ekstensi pgvector diaktifkan, Anda siap membuat dan mengelola data vektor di database.

Membuat Tabel dengan Kolom Vektor

Langkah pertama, buat sebuah 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 berdimensi 3:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Definisikan 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]'); -- Tambahkan lebih banyak data agar contoh query berikut jadi lebih jelas

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

Membuat Indeks Vektor untuk Meningkatkan Kinerja Query

Untuk tabel dengan jumlah data vektor yang besar, membuat indeks sangat penting demi pencarian kemiripan vektor yang efisien. pgvector mendukung dua tipe indeks utama: IVFFlat dan HNSW. Pilih tipe indeks berdasarkan kebutuhan spesifik aplikasi Anda (contohnya: kecepatan query, waktu pembuatan indeks, pemakaian memori, atau target recall).

• IVFFlat (Inverted File Index with Flat compression): Cocok untuk dataset besar dengan toleransi recall sedikit lebih rendah. Pembangunan indeks cukup cepat.
• HNSW (Hierarchical Navigable Small World): Umumnya memberikan recall lebih tinggi dan pencarian lebih cepat, namun proses building lebih lama dan konsumsi memori lebih besar.

Contoh berikut memperlihatkan pembuatan indeks IVFFlat dan HNSW di kolom vector pada tabel embeddings:

1. Membuat Indeks IVFFlat:

   -- Sebelum membuat IVFFlat, disarankan untuk menjalankan ANALYZE agar mendapat statistik tabel
   ANALYZE embeddings;
   
   -- Membuat indeks IVFFlat
   -- WITH (lists = 100): Menentukan jumlah daftar inverted file. Nilai ini perlu disesuaikan dengan ukuran dataset.
   -- Semakin besar 'lists', waktu build makin lama, query juga mungkin butuh waktu sedikit lebih lama tetapi recall lebih tinggi.
   -- Rekomendasi resmi: lists = akar 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 HNSW.
   -- m: Maksimal koneksi tiap node—memengaruhi keterhubungan dan efisiensi query/memori.
   -- ef_construction: Rentang pencarian pada saat membangun indeks. Memengaruhi waktu/memori dan kualitas indeks (recall).
   -- Silakan sesuaikan parameter berdasarkan dataset dan kebutuhan performa aktual Anda.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Catatan: Parameter indeks (seperti lists, m, ef_construction) sangat berpengaruh terhadap performa dan recall. Pilih nilai optimal berdasarkan pemahaman data dan pola query Anda—disarankan untuk eksperimen. Kunjungi dokumentasi resmi pgvector untuk penjelasan detail parameter dan tips tuning.

Kuery Data Vektor dengan pgvector

pgvector menyediakan berbagai operator untuk menghitung jarak antar vektor, yang memungkinkan pencarian kemiripan. Operator jarak yang umum dipakai meliputi:

• <->: Jarak L2 (Euclidean). Umum untuk mengukur jarak garis lurus antar vektor.
• <#>: Inner Product. Berkaitan dengan cosine similarity, memandang kesamaan arah.
• <=>: Jarak Cosine (Cosine Distance). 1 - Cosine Similarity, mengukur kesamaan arah tanpa terpengaruh panjang vektor.

Berikut beberapa contoh query vektor:

Pencarian Nearest Neighbor

Cari vektor-vektor yang paling mirip (jarak terkecil) dengan vektor query. Biasanya memakai ORDER BY dengan operator jarak, dan LIMIT untuk membatasi hasil.

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

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

Pencarian Kemiripan Vektor (Similarity Search)

Serupa dengan nearest neighbor, tetapi menonjolkan tampilan skor kemiripan.

1. Cari 5 vektor dengan jarak cosine terdekat ke [0.2, 0.3, 0.4] dan tampilkan jaraknya:

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

Visualisasi Data Vektor (Opsional)

Visualisasi vektor berdimensi tinggi membantu memahami distribusi dan kluster data. Untuk vektor 2D/3D, Anda bisa gunakan scatter plot sederhana. Untuk dimensi lebih tinggi, biasanya perlu teknik reduksi dimensi (misal: PCA atau t-SNE) untuk proyeksi ke ruang 2D/3D.

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

1. Siapkan Environment Python: Anda bisa memakai Python di luar ServBay atau yang terintegrasi dalam ServBay bila tersedia. Pastikan pustaka psycopg2 untuk PostgreSQL dan matplotlib untuk plotting sudah terinstal:

   # Jika menggunakan Python sistem
   pip install psycopg2 matplotlib
   
   # Bila pakai Python dari ServBay, gunakan pip sesuai letak environment ServBay
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Sesuaikan path sesuai environment Python Anda.

2. Membuat Script Python: Buat file Python (misal visualize_vectors.py), lalu salin kode berikut. Pastikan sesuaikan parameter koneksi database (dbname, user, password, host, port) dengan pengaturan ServBay Anda.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Untuk membuat scatter plot 3D
   
   # Parameter koneksi database - ubah sesuai ServBay Anda
   db_params = {
       "dbname": "your_database_name", # Ganti dengan nama database Anda
       "user": "servbay",              # Biasanya servbay atau postgres
       "password": "",                 # Jika ada password, isi sesuai pengaturan (biasanya kosong untuk lokal)
       "host": "localhost",            # PostgreSQL ServBay berjalan di localhost
       "port": "5432"                  # Port default PostgreSQL ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Hubungkan ke database PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Ambil data vektor
       # Catatan: psycopg2 biasanya akan membacakan tipe vector sebagai string '[x, y, z]'
       # Perlu parsing manual jika belum didukung otomatis
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parsing 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 ada data vektor ditemukan.")
           exit()
   
       # Ekstrak koordinat vektor—pastikan semuanya berdimensi 3
       if any(len(v) != 3 for v in vectors):
            print("Peringatan: Dimensi vektor tidak konsisten atau bukan 3D, tidak bisa plot.")
            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 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 Script: Eksekusi script Python dari terminal:

   python visualize_vectors.py

   Script ini akan terhubung ke database PostgreSQL Anda, membaca data vektor, dan menampilkan scatter plot 3D menggunakan Matplotlib.

FAQ (Tanya Jawab Umum)

• Tanya: Kenapa ekstensi vector tidak muncul di hasil \dx? Jawab: Pastikan Anda telah menjalankan perintah CREATE EXTENSION vector; dan tidak terjadi error. Jika tetap tidak muncul, cek apakah paket PostgreSQL ServBay telah terinstal dan diaktifkan dengan benar. File ekstensi pgvector biasanya ada di subdirektori share/extension PostgreSQL. Jika file hilang, Anda mungkin perlu instal ulang atau update paket PostgreSQL ServBay Anda.
• Tanya: Koneksi database gagal autentikasi, solusinya? Jawab: Pastikan user, password, host, dan port yang Anda gunakan di perintah psql atau script Python sesuai dengan konfigurasi PostgreSQL ServBay. Untuk koneksi lokal, user default biasanya servbay atau postgres, dan sering kali tanpa password.
• Tanya: Bagaimana memilih parameter indeks lists, m, atau ef_construction? Jawab: Parameter ini sangat memengaruhi performa dan hasil recall—tidak ada satu nilai terbaik untuk semua kasus. Anda harus melakukan eksperimen untuk dataset, dimensi, kebutuhan recall, dan latency aplikasi Anda. Dokumentasi resmi pgvector menyediakan panduan lebih lengkap.

Ringkasan

pgvector membawa kekuatan database vektor ke dalam sistem PostgreSQL yang stabil dan matang, sehingga developer dapat dengan mudah membangun aplikasi AI dan pencarian vektor secara lokal. Dengan hadirnya pgvector secara default di ServBay, kebutuhan setup lingkungan jadi jauh lebih praktis.

Ikuti panduan di atas untuk mengaktifkan pgvector di PostgreSQL ServBay, membuat tabel untuk menyimpan vektor, membangun indeks demi query optimal, dan menjalankan pencarian kemiripan antar vektor. Dikombinasikan dengan alat pengembangan dan environment lain di ServBay, Anda bisa membangun serta menguji aplikasi web dan proyek data modern dengan lebih efisien.