AI Engineering Academy · Lekcja

pgvector: embeddingi w PostgreSQL

pgvector: embeddingi w PostgreSQL to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.

pgvector: wyszukiwanie wektorowe w PostgreSQL

pgvector to rozszerzenie PostgreSQL o otwartym kodzie źródłowym, które dodaje typ danych vector oraz operatory wyszukiwania podobieństwa. Umożliwia przechowywanie embeddingów obok zwykłych danych aplikacji w tej samej bazie danych, którą już Państwo obsługują, dzięki czemu nie jest potrzebny osobny magazyn wektorów.

To idealne rozwiązanie dla zespołów, które już korzystają z PostgreSQL i chcą dodać wyszukiwanie semantyczne bez wprowadzania nowej zależności infrastrukturalnej.

Włączanie rozszerzenia pgvector

Zainstaluj pgvector z oficjalnego repozytorium albo użyj zarządzanego dostawcy PostgreSQL, który ma je preinstalowane (Supabase, Neon, AWS RDS, Render). Następnie włącz je w bazie danych za pomocą pojedynczego polecenia SQL — nie jest wymagane ponowne uruchomienie.

-- 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)

Tworzenie tabeli z kolumną wektorową

Dodaj kolumnę wektorową, określając vector(n), gdzie n oznacza wymiar embeddingu. Możesz połączyć ją ze zwykłymi kolumnami PostgreSQL zawierającymi metadane — dzięki temu możesz filtrować dane według user_id, created_at lub dowolnego innego pola za pomocą standardowych klauzul SQL WHERE.

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';

Wstawianie embeddingów z języka Python

Użyj sterownika psycopg2 lub asyncpg, aby wstawiać wiersze zawierające embeddingi. Przekształć pythonową listę liczb zmiennoprzecinkowych w ciąg znaków w formacie '[0.1, 0.2, ...]', który pgvector poprawnie zinterpretuje. Pakiet pgvector dla języka Python udostępnia funkcję pomocniczą register_vector, która automatyzuje ten proces.

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')

Podobieństwo cosinusowe z operatorem <=>

pgvector dodaje trzy operatory odległości:

<=> — odległość cosinusowa (1 - cosine_similarity)
<-> — odległość euklidesowa (L2)
<#> — ujemny iloczyn skalarny (należy go używać do obliczania podobieństwa na podstawie iloczynu skalarnego)

W przypadku embeddingów tekstu użyj <=> (odległość cosinusowa). ORDER BY distance ASC zwraca najpierw najbardziej podobne dokumenty.

-- 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;

Łączenie wyszukiwania wektorowego z filtrami SQL

Jedną z największych zalet pgvector jest możliwość łączenia wyszukiwania ANN ze standardowymi klauzulami SQL WHERE. Umożliwia to natywne filtrowanie metadanych bez żadnej specjalnej składni — wystarczy napisać zapytanie 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))

Tworzenie indeksu HNSW w celu zwiększenia szybkości

Bez indeksu pgvector wykonuje dokładne skanowanie każdego wiersza — sprawdza się to w przypadku mniej niż 10 000 wierszy, ale przy większej skali działanie jest wolne. Utwórz indeks HNSW na potrzeby przybliżonego wyszukiwania najbliższych sąsiadów. Parametry m (liczba połączeń na węzeł) i ef_construction (szerokość wyszukiwania podczas budowania) stanowią kompromis między rozmiarem indeksu i czasem jego budowania a dokładnością odtwarzania wyników.

-- 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: alternatywa dla HNSW

Typ indeksu IVFFlat grupuje wektory w koszyki lists i podczas wykonywania zapytania przeszukuje tylko najbliższe koszyki probes. Buduje się szybciej niż HNSW i zużywa mniej pamięci, ale przy tej samej szybkości zapewnia nieco niższą skuteczność odtwarzania wyników.

Zasada praktyczna: użyj IVFFlat, gdy potrzebujesz szybszego budowania indeksu podczas częstego ponownego indeksowania; użyj HNSW w przypadku stabilnych korpusów, dla których najważniejsza jest maksymalna szybkość zapytań.

-- 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

Pełny przykład zapytania w języku Python

Oto kompletna funkcja w języku Python, która przyjmuje zapytanie użytkownika, tworzy dla niego embedding, wykonuje wyszukiwanie podobieństwa za pomocą pgvector z filtrowaniem metadanych i zwraca wyniki top-k jako listę słowników.

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()]

Kompromisy między pgvector a Pinecone

Porównanie pgvector i Pinecone:

pgvector: rozwiązanie samodzielnie hostowane, bez dodatkowych kosztów, doskonała integracja z SQL, dobrze skaluje się do około 5 mln wektorów, wymaga wiedzy administratora baz danych do dostrajania
Pinecone: w pełni zarządzane, obsługuje ogromną skalę (miliardy wektorów), oferuje wyspecjalizowane filtrowanie, jest droższe i wymaga obsługi oddzielnej usługi

Wybierz pgvector, jeśli już korzystasz z PostgreSQL, a Twój korpus obejmuje mniej niż kilka milionów dokumentów. Wybierz Pinecone w przypadku ogromnej skali albo gdy uniknięcie obciążenia operacyjnego jest warte dodatkowego kosztu.

Korzystanie z pgvector z Supabase

Supabase to hostowana usługa PostgreSQL z preinstalowanym pgvector. Udostępnia klienta w języku Python (supabase-py) oraz interfejs REST API do wykonywania zapytań wektorowych, dzięki czemu jest najprostszym sposobem na uzyskanie produkcyjnej konfiguracji pgvector bez samodzielnego zarządzania serwerem bazy danych.

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()

Szybki sprawdzian

Sprawdź swoją znajomość zagadnień z dziedziny inżynierii AI omówionych w tej lekcji.

Podsumowanie lekcji

W tej lekcji nauczył się Pan / nauczyła się Pani, że: pgvector dodaje do PostgreSQL typ kolumny wektorowej oraz operatory odległości cosinusowej i euklidesowej, indeksy HNSW umożliwiają szybkie przybliżone wyszukiwanie najbliższych sąsiadów przy dużej skali, a standardowe klauzule SQL WHERE zapewniają filtrowanie metadanych bez używania specjalnej składni. Następnie porównamy wszystkie najważniejsze opcje magazynów wektorowych, aby pomóc Panu / Pani wybrać właściwe rozwiązanie dla swojego projektu.

Często zadawane pytania

Czy lekcja „pgvector: embeddingi w PostgreSQL” jest bezpłatna?

Tak — pełny tekst „pgvector: embeddingi w PostgreSQL” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „pgvector: embeddingi w PostgreSQL”?

Uczestnicy włączą rozszerzenie pgvector w PostgreSQL, utworzą tabelę z kolumną wektorową, wstawią embeddingi oraz wykonają zapytania o najbliższych sąsiadów za pomocą operatora odległości cosinusowej… Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?

Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „pgvector: embeddingi w PostgreSQL”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?

Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Dlaczego potrzebują Państwo wektorowej bazy danych
Pierwsze kroki z Pinecone
pgvector: embeddingi w PostgreSQL
Wybór i benchmarkowanie magazynów wektorowych

← Powrót do AI Engineering Academy