Przewodnik: Używanie rozszerzenia pgvector PostgreSQL w ServBay

pgvector to potężne, zewnętrzne rozszerzenie dla bazy danych PostgreSQL, które dodaje typ danych wektorowych oraz wydajne metody indeksowania wektorów, takie jak IVFFlat i HNSW. Dzięki temu PostgreSQL natywnie obsługuje przechowywanie wektorów oraz wyszukiwanie podobieństwa, co sprawia, że jest idealnym rozwiązaniem do budowy aplikacji AI, systemów rekomendacyjnych, rozpoznawania obrazów czy analizy języka naturalnego, które wymagają przetwarzania danych o dużej liczbie wymiarów.

ServBay, jako zintegrowane lokalne środowisko do rozwoju aplikacji webowych, dostarcza już gotowe do użycia paczki PostgreSQL oraz rozszerzenie pgvector, znacznie upraszczając pracę z bazą wektorową lokalnie. W tym przewodniku znajdziesz krok po kroku instrukcję korzystania z pgvector w ServBay.

Co to jest pgvector i dlaczego jest ważny?

W nowoczesnych zastosowaniach dane to nie tylko tekst czy liczby w ustrukturyzowanych tabelach. W szczególności w obszarach AI oraz uczenia maszynowego, dane reprezentowane są często jako wielowymiarowe wektory, tzw. „embeddings”. Wektory te opisują semantykę lub cechy, np. wizualne właściwości obrazów, znaczenie tekstów lub preferencje użytkowników.

Rozszerzenie pgvector pozwala PostgreSQL bezpośrednio przechowywać takie wektory i efektywnie prowadzić wyszukiwanie zbliżonych (najbliższych) sąsiadów. Dzięki temu możesz korzystać z SQL do wyszukiwania rekordów najbardziej podobnych do danego wektora, bez potrzeby używania odrębnej bazy wektorowej — co upraszcza cały stos technologiczny.

Wymagania wstępne

Przed rozpoczęciem pracy z pgvector upewnij się, że spełniasz następujące warunki:

1. ServBay jest zainstalowany i uruchomiony na macOS.
2. Pakiet PostgreSQL jest aktywowany w liście „Pakiety” ServBay. Jeśli nie jest, znajdź PostgreSQL w interfejsie ServBay i ustaw jego status na „Włączony”.

Aktywacja rozszerzenia pgvector w PostgreSQL ServBay

ServBay dostarcza pliki rozszerzenia pgvector w katalogu instalacyjnym PostgreSQL. Nie musisz ich pobierać ani kompilować samodzielnie — wystarczy aktywować rozszerzenie w wybranej bazie danych.

Oto kroki, jak aktywować pgvector w PostgreSQL w ServBay:

1. Połącz się z bazą PostgreSQL:

   Do połączenia z bazą PostgreSQL dostarczaną przez ServBay możesz użyć narzędzia wiersza poleceń psql. Domyślna konfiguracja zezwala zwykle na lokalne połączenia, domyślny użytkownik to często postgres lub servbay, domyślny port to 5432. Jeśli masz inną konfigurację — sprawdź dokumentację ServBay.

   Otwórz terminal i wpisz (w razie potrzeby dostosuj nazwę użytkownika i bazy):

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

   • -U servbay: nazwa użytkownika (servbay lub postgres).
   • -d your_database_name: nazwa bazy danych, do której się łączysz. Jeśli baza nie istnieje, utwórz ją poleceniem np. CREATE DATABASE servbay_demo_db;.
   • -h localhost: połączenie lokalne.
   • -p 5432: domyślny port PostgreSQL w ServBay.

2. Utwórz rozszerzenie vector:

   Po połączeniu się, w poleceniu psql wykonaj:

   CREATE EXTENSION vector;

   Jeśli rozszerzenie już istnieje, pojawi się odpowiednia informacja.

3. Sprawdź instalację:

   Listę rozszerzeń wywołasz poleceniem:

   \dx

   W wynikach powinno pojawić się rozszerzenie vector wraz z wersją.

                             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)

   (Uwaga: numer wersji zależy od wersji pgvector w ServBay)

Konfiguracja i użycie pgvector

Po aktywacji rozszerzenia możesz tworzyć i zarządzać danymi wektorowymi w bazie.

Tworzenie tabeli z danymi wektorowymi

Najpierw utwórz tabelę do przechowywania wektorów. pgvector wprowadza typ danych VECTOR(dimensions), gdzie dimensions to liczba wymiarów.

Przykład — tabela embeddings dla wektorów 3-wymiarowych:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Definicja kolumny z wektorem 3-wymiarowym
    vector VECTOR(3)
);

Następnie możesz wstawić przykładowe dane:

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]'); -- Dodaj więcej danych, by przykłady zapytań były wyraźniejsze

Uwaga: wartości wektorów muszą być w nawiasach kwadratowych [], rozdzielone przecinkami.

Tworzenie indeksów wektorowych dla lepszej wydajności zapytań

Dla tabel z dużą liczbą wektorów, indeksy znacznie poprawiają szybkość zapytań o podobieństwo. pgvector obsługuje dwa główne typy indeksów — IVFFlat i HNSW. Wybór zależy od wymagań (szybkość, czas budowy, zużycie RAM, skuteczność/recall).

• IVFFlat (Inverted File Index z płaską kompresją): Dobry dla większych zbiorów, kiedy recall może być trochę niższy. Indeks powstaje szybko.
• HNSW (Hierarchical Navigable Small World): Zazwyczaj zapewnia wyższy recall i szybsze zapytania, ale indeks buduje się wolniej i wymaga więcej pamięci.

Przykład tworzenia indeksów IVFFlat oraz HNSW na kolumnie vector w tabeli embeddings:

1. Tworzenie indeksu IVFFlat:

   -- Przed utworzeniem indeksu zaleca się użyć ANALYZE
   ANALYZE embeddings;
   
   -- Tworzenie indeksu IVFFlat
   -- WITH (lists = 100): liczba list indeksu — dostosuj do rozmiaru zbioru.
   -- Więcej list = wolniejsze tworzenie indeksu, więcej skanowanych list przy zapytaniu (może być wolniej), ale wyższy recall.
   -- Zwykle lists = sqrt(liczba wierszy).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. Tworzenie indeksu HNSW:

   -- Tworzenie indeksu HNSW
   -- WITH (m = 16, ef_construction = 200): parametry HNSW.
   -- m: maksymalna liczba połączeń dla węzła.
   -- ef_construction: zakres wyszukiwania przy budowie indeksu.
   -- Parametry dobierz do własnych danych i wymagań wydajności/recallu.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Uwaga: Parametry indeksów (lists, m, ef_construction) znacząco wpływają na wydajność i recall. Warto dobrze zrozumieć dane i profil zapytań oraz eksperymentować z ew. innymi wartościami. Zajrzyj do dokumentacji pgvector po szczegóły i porady dotyczące strojenia.

Wyszukiwanie wektorów z pgvector

pgvector oferuje różne operatory do obliczania odległości między wektorami dla wyszukiwania podobieństwa. Najważniejsze z nich to:

• <->: Odległość L2 (Euklidesowa) — mierzy dystans prostoliniowy między wektorami.
• <#>: Iloczyn skalarny (Inner Product) — powiązany z cosinusową miarą podobieństwa.
• <=>: Odległość cosinusowa (Cosine Distance) — 1 - podobieństwo cosinusowe; mierzy zgodność kierunków, ignorując długość wektora.

Przykłady typowych zapytań:

Zapytanie o najbliższych sąsiadów (Nearest Neighbor Search)

Znajdź wektory najbardziej podobne do danego (najmniejsza odległość). Użyj ORDER BY z operatorem odległości i ogranicz ilość wyników przez LIMIT.

1. Szukaj 5 wektorów najbliższych [0.2, 0.3, 0.4] wg L2:

   SELECT
       id,
       vector,
       -- Obliczenie odległości L2 od podanego wektora
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- rosnąco, by najbliższe były pierwsze
   LIMIT 5;

Wyszukiwanie podobieństwa (Similarity Search)

Jak wyżej, ale zwraca także score podobieństwa.

1. Szukaj 5 wektorów najbliższych dla [0.2, 0.3, 0.4] wg odległości cosinusowej:

   SELECT
       id,
       vector,
       -- Odległość cosinusowa od wektora zapytania
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- rosnąco, najbardziej podobne na górze
   LIMIT 5;

Wizualizacja danych wektorowych (opcjonalnie)

Wizualizacja wielowymiarowych danych pozwala zrozumieć ich rozkład oraz klastry. Dla wektorów 2D/3D możesz łatwo narysować wykres punktowy. Przy większej liczbie wymiarów należy skorzystać z redukcji wymiarów (PCA, t-SNE itd.), by uzyskać 2D lub 3D.

Przykład wizualizacji wektorów 3D w Pythonie z użyciem Matplotlib.

1. Przygotuj środowisko Pythona:

   Możesz pracować zarówno poza ServBay, jak i w jego środowisku Python. Jeśli używasz pythona z ServBay, aktywuj odpowiedni pakiet. Zainstaluj psycopg2 (połączenie z PostgreSQL) oraz matplotlib (wizualizacja):

   # Dla systemowego Pythona lub własnej instalacji
   pip install psycopg2 matplotlib
   
   # Dla Pythona z ServBay — ewentualnie przez ServBay CLI lub bezpośrednio z bin
   # /Applications/ServBay/Pakiety/python/bin/pip install psycopg2 matplotlib

   Dostosuj ścieżkę pip w zależności od konfiguracji środowiska.

2. Utwórz skrypt Pythona:

   Utwórz plik np. visualize_vectors.py i skopiuj poniższy kod. Zmodyfikuj parametry połączenia (dbname, user, password, host, port) zgodnie z Twoją konfiguracją PostgreSQL w ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Import do tworzenia wykresów 3D
   
   # Parametry połączenia z bazą — dostosuj do swojej konfiguracji
   db_params = {
       "dbname": "your_database_name", # Podaj nazwę swojej bazy
       "user": "servbay",              # Użytkownik PostgreSQL w ServBay (servbay lub postgres)
       "password": "",                 # Hasło do bazy (dla lokalnego może być puste)
       "host": "localhost",            # Zazwyczaj localhost
       "port": "5432"                  # Domyślny port ServBay PostgreSQL
   }
   
   conn = None
   cur = None
   
   try:
       # Połączenie z bazą PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Pobieranie wektorów
       # Uwaga: psycopg2 domyślnie odczytuje typ vector jako string '[x, y, z]'.
       # Trzeba to sparsować ręcznie lub z wykorzystaniem nowszego pgvector/psycopg2.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parsuj stringi do list liczb
       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("Nie znaleziono danych wektorowych.")
           exit()
   
       # Sprawdź, czy wszystkie wektory są 3-wymiarowe
       if any(len(v) != 3 for v in vectors):
            print("Uwaga: Wektory mają niezgodne wymiary — nie można wyrysować 3D.")
            # Możesz tu dodać kod do wykresu 2D lub zakończyć
            exit()
   
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # Tworzenie wykresu 3D
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Wymiar 1')
       ax.set_ylabel('Wymiar 2')
       ax.set_zlabel('Wymiar 3')
       ax.set_title('Wizualizacja wektorów 3D')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Błąd bazy danych: {e}")
   except Exception as e:
       print(f"Wystąpił błąd: {e}")
   finally:
       # Zamknij połączenie z bazą
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Uruchom skrypt:

   Odpal go w terminalu:

   python visualize_vectors.py

   Skrypt połączy się z bazą PostgreSQL, pobierze wektory i pokaże okno z wykresem 3D.

Najczęstsze pytania (FAQ)

• P: Nie widzę rozszerzenia vector w wyniku \dx. Co robić? O: Upewnij się, że polecenie CREATE EXTENSION vector; zostało wykonane poprawnie i bez błędów. Jeśli nadal brakuje rozszerzenia, sprawdź, czy pakiet PostgreSQL w ServBay jest zainstalowany i aktywowany, a pliki pgvector są w podkatalogu share/extension PostgreSQL. Brak plików może wymagać ponownej instalacji lub aktualizacji pakietu.
• P: Błąd autoryzacji przy połączeniu z bazą. Co robić? O: Zweryfikuj użyte nazwy użytkownika, hasła, hosta i portu (w psql oraz skrypcie Python) — muszą być zgodne z konfiguracją PostgreSQL w ServBay. Domyślnie użytkownik to servbay lub postgres, hasło bywa nieustawione dla lokalnych połączeń.
• P: Jak wybrać parametry indeksu (lists, m, ef_construction)? O: Parametry wpływają na szybkość i recall, nie istnieje uniwersalna wartość. Testuj z różnymi konfiguracjami, uwzględnij rozmiar i wymiary danych, wymagania względem wydajności i skuteczności. W dokumentacji pgvector znajdziesz szczegółowe zalecenia.

Podsumowanie

pgvector wnosi zaawansowane możliwości przechowywania i wyszukiwania wektorów do dojrzałego i stabilnego PostgreSQL, dając deweloperom świetne narzędzie do lokalnych projektów AI i analizy danych wektorowych. ServBay, dzięki gotowym rozszerzeniom, upraszcza całą konfigurację.

Korzystając z kroków opisanych w przewodniku, łatwo aktywujesz pgvector, utworzysz tabele dla wektorów, zbudujesz szybkie indeksy i przeprowadzisz zapytania o podobieństwo. Integracja z narzędziami ServBay pozwala sprawnie rozwijać nowoczesne aplikacje webowe i projekty danych na własnym komputerze.