AI Engineering Academy · Pelajaran

pgvector: Penyematan dalam PostgreSQL

Aktifkan ekstensi pgvector di PostgreSQL, buat tabel dengan kolom vektor, masukkan penyematan, dan jalankan kueri tetangga terdekat menggunakan operator jarak kosinus .

Pelajaran 3 dari 413 langkah

pgvector: Penyematan dalam PostgreSQL adalah pelajaran AI Engineering Academy gratis di CoddyKit. Ini adalah pelajaran 3 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar AI Engineering Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus AI Engineering Academy mencakup 4 pelajaran total.

pgvector: Pencarian Vektor di PostgreSQL

pgvector adalah ekstensi PostgreSQL sumber terbuka yang menambahkan tipe data vector dan operator pencarian kemiripan. Ekstensi ini memungkinkan Anda menyimpan embedding bersama data aplikasi biasa dalam basis data yang sudah Anda operasikan, sehingga tidak memerlukan penyimpanan vektor terpisah.

Ini ideal untuk tim yang sudah menggunakan PostgreSQL dan ingin menambahkan pencarian semantik tanpa memperkenalkan dependensi infrastruktur baru.

Mengaktifkan Ekstensi pgvector

Instal pgvector dari repositori resmi atau gunakan penyedia PostgreSQL terkelola yang sudah memasangnya (Supabase, Neon, AWS RDS, Render). Lalu aktifkan di basis data Anda dengan satu perintah SQL — tidak perlu memulai ulang.

-- Run this once per database to enable the extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Verify it's installed
SELECT extname, extversion
FROM pg_extension
WHERE extname = 'vector';
-- Returns: vector | 0.7.0 (or similar)

Membuat Tabel dengan Kolom Vektor

Tambahkan kolom vektor dengan menetapkan vector(n), dengan n sebagai dimensi embedding. Anda dapat menggabungkannya dengan kolom PostgreSQL biasa untuk metadata — sehingga Anda dapat memfilter berdasarkan user_id, created_at, atau field lainnya menggunakan klausa SQL WHERE standar.

CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    content     TEXT NOT NULL,
    category    TEXT,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    embedding   vector(1536)   -- must match your model dimension
);

-- Index on category for fast metadata filtering
CREATE INDEX ON documents (category);

SELECT column_name, data_type
FROM information_schema.columns
WHERE table_name = 'documents';

Menyisipkan Embedding dari Python

Gunakan driver psycopg2 atau asyncpg untuk menyisipkan baris yang berisi embedding. Ubah daftar float Python menjadi string dalam format '[0.1, 0.2, ...]' yang dapat diuraikan pgvector dengan benar. Paket Python pgvector menyediakan pembantu register_vector untuk menanganinya secara otomatis.

import psycopg2
from pgvector.psycopg2 import register_vector
from openai import OpenAI

conn = psycopg2.connect('postgresql://user:pass@localhost/mydb')
register_vector(conn)
cur = conn.cursor()

client = OpenAI()

document = 'pgvector adds vector search to PostgreSQL.'
resp = client.embeddings.create(model='text-embedding-3-small', input=document)
embedding = resp.data[0].embedding

cur.execute(
    'INSERT INTO documents (content, category, embedding) VALUES (%s, %s, %s)',
    (document, 'database', embedding)
)
conn.commit()
print('Inserted document with embedding')

Kemiripan Kosinus dengan Operator <=>

pgvector menambahkan tiga operator jarak:

<=> — jarak kosinus (1 - cosine_similarity)
<-> — jarak Euclidean (L2)
<#> — hasil kali dalam negatif (gunakan untuk kemiripan hasil kali titik)

Untuk embedding teks, gunakan <=> (jarak kosinus). ORDER BY distance ASC mengembalikan dokumen yang paling mirip terlebih dahulu.

-- Find top 5 documents most similar to a query embedding
-- Replace '[0.1, 0.2, ...]' with the actual query vector
SELECT
    id,
    content,
    category,
    1 - (embedding <=> '[0.1, 0.2, 0.3]'::vector) AS cosine_similarity
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, 0.3]'::vector
LIMIT 5;

Menggabungkan Pencarian Vektor dengan Filter SQL

Salah satu keunggulan terbesar pgvector adalah kemampuannya menggabungkan pencarian ANN dengan klausa SQL WHERE standar. Hal ini memungkinkan pemfilteran metadata secara bawaan tanpa sintaks khusus apa pun — Anda cukup menulis SQL.

-- Semantic search filtered to the 'database' category
-- and only recent documents
SELECT
    id,
    content,
    1 - (embedding <=> %s::vector) AS similarity
FROM documents
WHERE
    category = 'database'
    AND created_at > NOW() - INTERVAL '30 days'
ORDER BY embedding <=> %s::vector
LIMIT 5;

-- In Python with psycopg2:
# cur.execute(sql, (query_embedding, query_embedding))

Membuat Indeks HNSW untuk Kecepatan

Tanpa indeks, pgvector melakukan pemindaian tepat pada setiap baris — cukup baik untuk kurang dari 10.000 baris, tetapi lambat saat skala membesar. Buat indeks HNSW untuk pencarian tetangga terdekat aproksimatif. Parameter m (koneksi per simpul) dan ef_construction (lebar pencarian saat pembangunan) menukar ukuran indeks dan waktu pembangunan dengan akurasi recall.

-- Create an HNSW index for cosine distance queries
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- At query time, control recall vs speed:
SET hnsw.ef_search = 40;  -- higher = better recall, slower

-- Verify the index is being used:
EXPLAIN SELECT * FROM documents
ORDER BY embedding <=> '[0.1]'::vector(1)
LIMIT 5;

Indeks IVFFlat: Alternatif untuk HNSW

Jenis indeks IVFFlat mengelompokkan vektor ke dalam bucket lists dan saat kueri hanya mencari bucket probes terdekat. Indeks ini dibangun lebih cepat daripada HNSW dan menggunakan lebih sedikit memori, tetapi memiliki recall yang sedikit lebih rendah pada kecepatan yang sama.

Pedoman umum: gunakan IVFFlat jika Anda memerlukan pembangunan indeks yang lebih cepat selama pengindeksan ulang yang sering; gunakan HNSW untuk korpus yang stabil dan memerlukan kecepatan kueri maksimum.

-- IVFFlat index: good for large, infrequently updated corpora
-- lists ≈ sqrt(n) where n is the number of vectors
CREATE INDEX ON documents
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

-- At query time, probes controls recall vs speed:
SET ivfflat.probes = 10;  -- check 10 of 100 clusters

Contoh Kueri Python Lengkap

Berikut fungsi Python lengkap yang menerima kueri pengguna, membuat embedding, menjalankan pencarian kemiripan pgvector dengan pemfilteran metadata, lalu mengembalikan hasil teratas sebanyak k dalam bentuk daftar dict.

import psycopg2
from pgvector.psycopg2 import register_vector
from openai import OpenAI

conn = psycopg2.connect('postgresql://user:pass@localhost/mydb')
register_vector(conn)
client = OpenAI()

def semantic_search(query, category=None, top_k=5):
    resp = client.embeddings.create(model='text-embedding-3-small', input=query)
    q_vec = resp.data[0].embedding

    sql = '''
        SELECT content,
               1 - (embedding <=> %s::vector) AS similarity
        FROM documents
        {where}
        ORDER BY embedding <=> %s::vector
        LIMIT %s
    '''
    where = 'WHERE category = %s' if category else ''
    params = [q_vec, q_vec, top_k] if not category else [q_vec, category, q_vec, top_k]
    cur = conn.cursor()
    cur.execute(sql.format(where=where), params)
    return [{'text': r[0], 'score': r[1]} for r in cur.fetchall()]

Perbandingan Kelebihan dan Kekurangan pgvector serta Pinecone

Perbandingan pgvector dan Pinecone:

pgvector: dihosting sendiri, tanpa biaya tambahan, integrasi SQL yang sempurna, dapat diskalakan dengan baik hingga sekitar 5 juta vektor, memerlukan pengetahuan DBA untuk penyetelan
Pinecone: sepenuhnya terkelola, skala sangat besar (miliaran vektor), pemfilteran khusus, lebih mahal, berupa layanan terpisah yang harus dioperasikan

Pilih pgvector jika Anda sudah menjalankan PostgreSQL dan korpus Anda berisi kurang dari beberapa juta dokumen. Pilih Pinecone untuk skala sangat besar atau jika menghindari beban operasional sepadan dengan biayanya.

Menggunakan pgvector dengan Supabase

Supabase adalah layanan PostgreSQL terhosting yang sudah memasang pgvector. Layanan ini menyediakan klien Python (supabase-py) dan API REST untuk kueri vektor, sehingga menjadi cara termudah untuk menyiapkan pgvector produksi tanpa mengelola server basis data sendiri.

from supabase import create_client
import os

url = os.environ['SUPABASE_URL']
key = os.environ['SUPABASE_SERVICE_KEY']
supabase = create_client(url, key)

# Insert a document with embedding
supabase.table('documents').insert({
    'content': 'Supabase hosts PostgreSQL with pgvector.',
    'embedding': embedding   # list of 1536 floats
}).execute()

# Vector similarity search via RPC (Supabase edge function)
# result = supabase.rpc('match_documents', {'query_embedding': q_vec, 'match_count': 5}).execute()

Pemeriksaan Singkat

Uji pemahaman Anda tentang konsep Rekayasa AI dari pelajaran ini.

Jawab di pelajaran interaktif

Rangkuman Pelajaran

Dalam pelajaran ini Anda mempelajari bahwa: pgvector menambahkan jenis kolom vektor serta operator jarak kosinus/Euclidean ke PostgreSQL, indeks HNSW memungkinkan pencarian tetangga terdekat aproksimatif yang cepat pada skala besar, dan klausa SQL WHERE standar menyediakan pemfilteran metadata tanpa sintaks khusus. Selanjutnya, kita akan membandingkan semua opsi penyimpanan vektor utama untuk membantu Anda memilih yang tepat bagi proyek Anda.

Gratis untuk memulai

Belajar Python dengan tutor AI — gratis

Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.

Kursus: 30
Pelajaran: 120

Mulai belajar gratis Lihat kursus lengkapnya

Pertanyaan yang Sering Diajukan

Apakah pelajaran “pgvector: Penyematan dalam PostgreSQL” gratis?

Ya — teks lengkap “pgvector: Penyematan dalam PostgreSQL” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus AI Engineering Academy, upgrade ke CoddyKit PRO. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “pgvector: Penyematan dalam PostgreSQL”?

Aktifkan ekstensi pgvector di PostgreSQL, buat tabel dengan kolom vektor, masukkan penyematan, dan jalankan kueri tetangga terdekat menggunakan operator jarak kosinus . Kamu berlatih AI Engineering Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai AI Engineering Academy?

Tidak diperlukan pengalaman sebelumnya. AI Engineering Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 3 dari 4.

Berapa lama pelajaran “pgvector: Penyematan dalam PostgreSQL” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran AI Engineering Academy ini?

Ya. Setiap pelajaran AI Engineering Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Mengapa Anda Membutuhkan Basis Data Vektor
Memulai dengan Pinecone
pgvector: Penyematan dalam PostgreSQL
Memilih dan Mengukur Kinerja Penyimpanan Vektor

← Kembali ke AI Engineering Academy