Przechowywanie i wyszukiwanie embeddingów Ollamy w PostgreSQL z pgvector

README pgvector opisuje go jako open source'owe wyszukiwanie wektorów według podobieństwa dla Postgresa. Obsługuje dokładne i przybliżone wyszukiwanie najbliższych sąsiadów; wektory o pojedynczej precyzji, o połowicznej precyzji, binarne i rzadkie; oraz odległość L2, iloczyn skalarny, odległość cosinusową, odległość L1, odległość Hamminga i odległość Jaccarda. Ponieważ wektory są zwykłymi kolumnami PostgreSQL, zyskują też zgodność z ACID, odzyskiwanie do punktu w czasie (point-in-time recovery) i JOIN-y.

Aby przeszukiwać dokumenty, zapisujesz po jednym wierszu na fragment, z jego tekstem i wektorem, tworzysz embedding pytania tym samym modelem i sortujesz wiersze według odległości od wektora pytania.

pgvector obsługuje PostgreSQL 13 i nowszy. README podaje kilka sposobów instalacji, między innymi te:

Kolumna typu vector(n) przechowuje wektory o dokładnie n wymiarach, a n musi być równe długości wektorów z Twojego modelu embeddingów. Wektor o innej długości zostaje odrzucony: gdy wstawiliśmy wektor o 2 wymiarach do kolumny vector(3), PostgreSQL zwrócił "expected 3 dimensions, not 2". all-minilm zwraca 384 wymiary, więc jego kolumna to vector(384).

README podaje, że każdy wektor zajmuje 4 × wymiary + 8 bajtów, przy czym każdy element jest liczbą zmiennoprzecinkową o pojedynczej precyzji, i dopuszcza do 16,000 wymiarów w kolumnie. Indeks obsługuje mniej wymiarów, jak pokazano niżej. Typ halfvec przechowuje wartości o połowicznej precyzji w 2 × wymiary + 8 bajtów.

pgvector odczytuje wektor jako tekst w nawiasach kwadratowych, na przykład '[1,2,3]', a README mówi, że wszystkie elementy muszą być skończone (bez NaN, Infinity ani -Infinity). Każda tablica w polu embeddings odpowiedzi /api/embed ma już taką postać, a odpowiedź zachowuje kolejność danych wejściowych, więc pierwszy tekst odpowiada pierwszemu wektorowi.

README pokazuje INSERT dla kilku wierszy, INSERT … ON CONFLICT dla upsertów i COPY dla ładowania zbiorczego. Konwerter poniżej łączy Twoje teksty z odpowiedzią i pisze polecenia INSERT z poprawnie zapisanymi cudzysłowami. Uruchomiliśmy jego wynik z tekstami zawierającymi cudzysłowy, ukośniki wsteczne, podziały wierszy i emoji, a wróciły one bez zmian.

Dokumentacja Ollamy zaleca podobieństwo cosinusowe w większości zastosowań wyszukiwania semantycznego i mówi, że /api/embed zwraca wektory o długości 1. Dla takich wektorów odległość cosinusowa, odległość L2 i iloczyn skalarny ustawiają wiersze w tej samej kolejności, ponieważ kwadrat odległości L2 to 2 minus 2 razy podobieństwo cosinusowe. W naszym teście z all-minilm trzy pierwsze wiersze były takie same dla wszystkich trzech, a odległość L2 równa 0.931 odpowiadała podobieństwu cosinusowemu 0.566.

Każda odległość ma własny operator. Wyszukiwanie sortuje według operatora i bierze pierwsze wiersze za pomocą LIMIT, a indeks jest budowany dla jednej klasy operatorów.

Bez indeksu pgvector wykonuje dokładne wyszukiwanie najbliższych sąsiadów, które według README zapewnia doskonały recall. Przybliżony indeks wymienia część recallu na szybkość, a README ostrzega, że po dodaniu indeksu zapytania mogą zwracać inne wyniki.

Indeks jest używany tylko wtedy, gdy zapytanie ma ORDER BY i LIMIT, a ORDER BY jest samym operatorem odległości w kolejności rosnącej. ORDER BY embedding <=> $1 LIMIT 5 może użyć indeksu; ORDER BY 1 - (embedding <=> $1) DESC nie może. README zaznacza też, że skan całej tabeli może być szybszy, gdy tabela jest mała.

W HNSW wyniki są ograniczone przez hnsw.ef_search, domyślnie 40. Na tabeli testowej z 200 wierszami i indeksem HNSW LIMIT 100 zwrócił 40 wierszy; po SET hnsw.ef_search = 100 zwrócił 100. Ustaw hnsw.ef_search na co najmniej tyle, ile wierszy potrzebujesz. SET LOCAL wewnątrz transakcji zmienia go tylko dla jednego zapytania.

Filtrowanie również zmniejsza wyniki. Przy indeksach przybliżonych, jak mówi README, warunek WHERE jest stosowany po przeskanowaniu indeksu: jeśli warunek pasuje do 10% wierszy, HNSW z domyślnym hnsw.ef_search równym 40 zwraca średnio tylko 4 wiersze. Od wersji 0.8.0 iteracyjne skanowanie indeksu (SET hnsw.iterative_scan = strict_order lub relaxed_order) przeszukuje większą część indeksu, aż znajdzie się dość wierszy, do hnsw.max_scan_tuples (domyślnie 20,000).

Gdy wyszukiwanie zwróci najbliższe wiersze, model potrzebuje ich w swoim prompcie. /api/chat Ollamy przyjmuje listę komunikatów, każdy z rolą (system, user, assistant lub tool) i treścią. Prosty układ to komunikat systemowy z zasadami oraz komunikat użytkownika, który wymienia wiersze, każdy z numerem, na przykład [1] i [2], a po nich pytanie. Dzięki numerom odpowiedź może wskazać, z których wierszy skorzystała, a każdy numer można odwzorować z powrotem na jego wiersz.

Aby cytowania miały stały kształt, nadaj polu format schemat JSON Schema z odpowiedzią i listą cytowań, każde z numerem źródła i krótkim cytatem. Strona Ollamy o ustrukturyzowanych wyjściach zaleca, by zapisać schemat także w prompcie i obniżyć temperaturę (temperature), na przykład do 0, aby wynik był bardziej deterministyczny. W psql funkcja json_agg zbiera wiersze zapytania w tablicę JSON, którą narzędzie poniżej odczytuje bezpośrednio.

Zasady, wiersze i pytanie muszą zmieścić się w długości kontekstu. Strona Ollamy o długości kontekstu podaje domyślnie 4k tokenów przy mniej niż 24 GiB VRAM, a jej FAQ podaje 4096 tokenów; ollama ps na naszej maszynie testowej pokazało 4096. Zmienia to num_ctx w options albo zmienna środowiskowa OLLAMA_CONTEXT_LENGTH.

Gdy prompt jest dłuższy, /api/chat domyślnie nie zwraca błędu. W kodzie źródłowym Ollamy (0.40.11) serwer najpierw odrzuca całe wcześniejsze komunikaty, zachowując komunikaty systemowe i ostatni komunikat. Jeśli pozostały prompt nadal jest za długi, zachowuje kilka pierwszych tokenów (num_keep, domyślnie 4) oraz koniec promptu, a środkową część odrzuca. W naszym teście z qwen2.5:7b i num_ctx 1024 prompt o 2,068 tokenach został obcięty do 514. Komunikat systemowy i pierwsze źródła zostały utracone: gdy odpowiedź była w źródle [1], model odpowiedział słowem kodowym, którego nie było w żadnym źródle, a gdy odpowiedź była w ostatnim źródle, odpowiedział poprawnie, ale bez numeru źródła, o który prosił komunikat systemowy. Odpowiedź nie zawierała błędu; w logu serwera było ostrzeżenie "truncating input prompt".

Kod źródłowy Ollamy ma też pole truncate dla żądań czatu, którego nie ma na stronie /api/chat. Z "truncate": false to samo żądanie zwróciło HTTP 400 z błędem "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". Pole prompt_eval_count w odpowiedzi to liczba tokenów promptu; w teście z obcięciem wynosiło 514, a nie 2,068.

Cytowanie można sprawdzić mechanicznie: numer musi wskazywać wysłane źródło, a cytat powinien występować w tym źródle. W naszym teście z czterema źródłami i qwen2.5:7b cytaty w odpowiedziach JSON zgadzały się ze źródłami słowo w słowo. To nie dowodzi, że odpowiedź jest poprawna: zapytany o rozmiar wektora o 384 wymiarach model zacytował właściwą regułę (4 razy liczba wymiarów plus 8 bajtów) i mimo to odpowiedział 1552 bajty zamiast 1,544.

Patrz też na odpowiedzi bez cytowań. Gdy źródła nie zawierały odpowiedzi, model raz odpowiedział z własnej wiedzy bez cytowań, a raz powiedział, że nie wie, ale i tak powołał się na niezwiązane źródło. Jeśli done_reason w odpowiedzi to "length", odpowiedź została ucięta przez num_predict i może jej brakować cytowań.

README mówi, że indeks HNSW buduje się znacznie szybciej, gdy graf mieści się w maintenance_work_mem, pokazuje komunikat, gdy już się nie mieści, i ostrzega, by nie ustawiać maintenance_work_mem tak wysoko, że wyczerpie pamięć serwera. Podobnie jak w przypadku innych indeksów, szybciej jest utworzyć indeks po wczytaniu początkowych danych. Indeksy nie muszą mieścić się w pamięci, ale prawdopodobnie osiągną lepszą wydajność, jeśli się mieszczą; SELECT pg_size_pretty(pg_relation_size('index_name')) pokazuje rozmiar indeksu.

Aby uzyskać mniejszy zbiór roboczy i mniejsze indeksy, README sugeruje halfvec, indeksowanie o połowicznej precyzji albo kwantyzację binarną. Jeśli Ollama działa na tym samym serwerze, PostgreSQL i modele dzielą tę samą pamięć; nasz artykuł o obserwowaniu pamięci Ollamy wyjaśnia, od czego zależy, ile pamięci zużywają modele.