Indeks HNSW w Postgres: dobrze indeksuj do wyszukiwania wektorowego

HNSW oznacza Hierarchiczny Żeglowny Mały Świat. Jest to indeks grafowy: każdy wektor staje się węzłem połączonym z najbliższymi sąsiadami, zorganizowanymi w kilku nałożonych na siebie warstwach. Wyszukiwanie rozpoczyna się od góry wykresu, w najrzadszej warstwie, a następnie przechodzi w dół, warstwa po warstwie, do najbardziej odpowiednich sąsiadów. Czas wyszukiwania staje się zatem prawie logarytmiczny, a nie liniowy w zależności od liczby linii.

IVFFlat, drugi indeks pgvector, działa inaczej: dzieli przestrzeń wektorową na listy określone w trakcie szkolenia na istniejącej próbce, zanim będzie można cokolwiek zaindeksować. HNSW nie ma tego ograniczenia, każde wstawienie bezpośrednio wzbogaca wykres, co ułatwia operowanie na tabeli, która stale rośnie. Z drugiej strony indeks HNSW zużywa więcej pamięci i jego zbudowanie zajmuje więcej czasu niż równoważny indeks IVFFlat na tym samym woluminie.

pgvector wprowadza obsługę HNSW w wersji 0.5.0. Późniejsze wersje dodają przydatne funkcje do tego przewodnika: typ halfvec (0.7.0) do indeksowania ponad 2000 wymiarów oraz parametr hnsw.iterative_scan (0.8.0) do poprawy przypominania filtrowanych zapytań. Jeśli przed podjęciem decyzji porównasz pgvector z dedykowaną bazą wektorów, nasze porównanie pgvector z Pinecone, Weaviate i Qdrant szczegółowo opisuje kompromisy.

Najpierw potwierdź zainstalowaną wersję pgvector. Rozszerzenie, które jest zbyt stare, powoduje, że niektóre funkcje tego przewodnika po cichu nie działają, szczególnie halfvec i hnsw.iterative_scan.

SELECT extversion FROM pg_extension WHERE extname = 'vector';

HNSW istnieje od wersji pgvector 0.5.0. Typ halfvecniezbędny do indeksowania osadzania powyżej 2000 wymiarów wymaga wersji co najmniej 0.7.0. Parametr hnsw.iterative_scan żąda wersji 0.8.0.

W projektach Aurabase pytanie nie pojawia się: obraz Postgres osadza pgvector 0.8.6, zarówno we współdzielonym klastrze Postgres (docker/Postgres.Dockerfile, zbudowany bezpośrednio na pgvector/pgvector:0.8.6-pg16-bookworm), jak i w 16 instancjach CNPG Postgres dedykowanych dla każdego projektu (docker/Postgres.CNPG.Dockerfile, który dziedziczy pgvector 0.8.6 z oficjalny obraz CloudNativePG). Zweryfikowano w obu plikach Dockerfile 24 sierpnia 2026 r.

Typ kolumny zależy od rozmiaru osadzonych elementów, a nie tylko od modelu, który je generuje. pgvector przechowuje w pamięci klasyczny wektor typu vectorz ograniczeniem do 16 000 wymiarów. Ale indeksowanie HNSW tego typu jest ograniczone do 2000 wymiarów: poza tym CREATE INDEX kończy się niepowodzeniem.

Typowe modele osadzania często przekraczają ten próg: text-embedding-3-large z OpenAI lub gemini-embedding-2 z Google natywnie generują do 3072 wymiarów. Aby zindeksować te wektory za pomocą HNSW, rzuć kolumnę na halfvec (precyzja przechowywania zmniejszona o połowę), co przesuwa limit indeksowania znacznie poza 2000 wymiarów.

Silnik Aurabase RAG ilustruje ten kompromis w produkcji: obsługiwane są trzy klasy wymiarów (768, 1536, 3072), przechowywane w trzech odrębnych kolumnach tej samej tabeli embeddings. Kolumny 768 i 1536 są indeksowane bezpośrednio w HNSW na typie vector. Kolumna 3072 jest indeksowana za pomocą rzutowania ::halfvec(3072), dokładnie w celu obejścia ograniczenia wymiaru 2000.

CREATE INDEX idx_embeddings_vec_768 ON embeddings
  USING hnsw (embedding_768 vector_cosine_ops)
  WHERE embedding_768 IS NOT NULL;

CREATE INDEX idx_embeddings_vec_1536 ON embeddings
  USING hnsw (embedding_1536 vector_cosine_ops)
  WHERE embedding_1536 IS NOT NULL;

CREATE INDEX idx_embeddings_vec_3072 ON embeddings
  USING hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  WHERE embedding_3072 IS NOT NULL;

Aby uzyskać szczegółowe informacje na temat pozyskiwania (porcjowanie, wywoływanie dostawcy osadzania, wstawianie), zobacz samouczek potoku RAG na pgvector.

Minimalna składnia jest wystarczająca dla pierwszego indeksu, z domyślnymi wartościami pgvector.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops);

pgvector następnie stosuje m = 16 i ef_construction = 64. Aby jawnie dostosować te wartości, użyj klauzuli WITH:

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 24, ef_construction = 100);

Co zmienia parametr m?

m ustawia maksymalną liczbę połączeń utrzymywanych przez każdy węzeł na wykresie w każdej warstwie. Wyższa wartość zagęszcza wykres: wzrasta przywoływanie, ale zużycie pamięci i czas konstrukcji również rosną, w przybliżeniu liniowo. Wartość domyślna (16) jest odpowiednia w większości przypadków. Zwiększenie liczby do 24 lub 32 jest szczególnie uzasadnione w przypadku dużych osadów, gdzie rozróżnienie między bliskimi i odległymi sąsiadami staje się dokładniejsze.

Co zmienia ef_construction?

ef_construction ustawia rozmiar listy kandydatów badanej podczas konstruowania indeksu dla każdego wstawionego węzła. Wyższa wartość poprawia jakość końcowego wykresu, a tym samym potencjalne wycofanie, kosztem dłuższego czasu konstrukcji. W przeciwieństwie do m, ten parametr nie ma żadnych kosztów w momencie zapytania: jest to jednorazowa inwestycja, płacona tylko raz w momencie utworzenia indeksu.

Częściowe indeksy dla kilku klas wymiarów w tej samej tabeli

Gdy tabela przechowuje wiele kolumn wektorowych (po jednej na klasę wymiaru, tak jak robi to Aurabase), indeksuj każdą kolumnę osobno za pomocą klauzuli WHERE colonne IS NOT NULL. Ten częściowy indeks pozwala uniknąć indeksowania pustych linii dla klas, które nie są używane w danej linii, co zmniejsza rozmiar indeksu i przyspiesza jego budowę, nie ponosząc żadnych kosztów przywołania.

Wybór klasy operatora (vector_cosine_ops, vector_l2_ops lub vector_ip_ops) musi odpowiadać metryce, na podstawie której uczono modelu osadzania. Najnowsze modele osadzania tekstu są szkolone pod kątem podobieństwa cosinus: vector_cosine_ops (lub halfvec_cosine_ops w kolumnie rzutowanej) jest zatem najbezpieczniejszym wyborem domyślnym.

Wartość ef_search jest ustawiana przy każdym zapytaniu, a nie podczas budowania indeksu. Określa rozmiar listy kandydatów sprawdzanych podczas wyszukiwania: im jest ona większa, tym lepsze przypominanie, kosztem dłuższego opóźnienia. pgvector ustawia wartość domyślną na 40.

SET LOCAL hnsw.ef_search = 100;

SELECT id, content
FROM embeddings
ORDER BY embedding <=> '[...]'::vector
LIMIT 10;

Wartość 40 rzadko wystarcza, gdy tylko zapytanie łączy wyszukiwanie wektorowe z filtrem WHERE zastosowanym po przeskanowaniu indeksu (w przestrzeni nazw, dzierżawie lub innym kryterium metadanych). Skan HNSW przywraca surowych kandydatów ef_search, a następnie filtr odrzuca ich część. Jeśli zbyt mało kandydatów przeżyje, ostateczny LIMIT okaże się niedopełniony.

Dlatego silnik Aurabase RAG rozszerza ef_search dynamicznie zgodnie z żądanym top_k, zamiast utrzymywać stałą wartość 40: ef = max(top_k × 4, 64). Do wyszukiwania 5 najbliższych wyników używa się ef_search = 64; wyszukiwanie 50 najpopularniejszych zastosowań ef_search = 200. Tę formułę można dostosować do zmiennej środowiskowej w przypadku wdrożeń, które wymagają innego kompromisu w zakresie przypominania/opóźnienia.

pgvector 0.8 dodaje drugą dźwignię dla tego samego problemu: hnsw.iterative_scan. W trybie strict_order lub relaxed_orderwyszukiwanie stopniowo rozszerza swoje wyszukiwanie, aż po przefiltrowaniu zgromadzi wystarczającą liczbę wyników, zamiast zatrzymywać się na ustalonej liście kandydatów. Aurabase aktywuje go domyślnie w strict_order, ale chroni połączenie w punkcie zapisu. W wersji pgvector wcześniejszej niż 0.8, gdzie ten parametr nie istnieje, zapytanie jest kontynuowane w trybie pogorszonym, a nie kończy się niepowodzeniem.

Ten indeks HNSW to tylko jeden element kompletnego potoku RAG: fragmentacja, generowanie osadzania, przetwarzanie, a następnie wyszukiwanie. Nasz samouczek krok po kroku buduje ten potok od początku do końca na pgvector, od pierwszego wstawienia do zapytania o podobieństwo. Dokumentacja techniczna zawiera również szczegółowe informacje na temat wszystkich natywnych możliwości sztucznej inteligencji Aurabase zbudowanych na Postgres.