Индекс HNSW в Postgres: индекс для векторного поиска

HNSW означает «Иерархический навигационный малый мир». Это индекс графа: каждый вектор становится узлом, соединенным со своими ближайшими соседями, организованным в несколько наложенных друг на друга слоев. Поиск начинается в верхней части графа, на самом разреженном слое, а затем идет вниз слой за слоем к наиболее релевантным соседям. Таким образом, время поиска становится почти логарифмическим, а не линейным по количеству строк.

IVFFlat, другой индекс pgvector, работает по-другому: он делит векторное пространство на списки, определяемые проходом обучения на существующей выборке, прежде чем иметь возможность что-либо индексировать. HNSW не имеет этого ограничения: каждая вставка напрямую обогащает граф, что упрощает работу с постоянно растущей таблицей. С другой стороны, индекс HNSW потребляет больше памяти и требует больше времени для построения, чем эквивалентный индекс IVFFlat на том же томе.

pgvector представляет поддержку HNSW в версии 0.5.0. В более поздних версиях этого руководства добавлены полезные возможности: тип halfvec (0.7.0) для индексации за пределами 2000 измерений и параметр hnsw.iterative_scan (0.8.0) для улучшения отзыва по отфильтрованным запросам. Если вы сравните pgvector со специальной базой векторов, прежде чем принять решение, в нашем сравнении pgvector с Pinecone, Weaviate и Qdrant подробно описаны компромиссы.

Подтвердите версию pgvector, установленную первой. Слишком старое расширение приводит к автоматическому сбою некоторых функций в этом руководстве, особенно halfvec и hnsw.iterative_scan.

SELECT extversion FROM pg_extension WHERE extname = 'vector';

HNSW существует с версии pgvector 0.5.0. Тип halfvec, необходимый для индексации вложений размером более 2000, требует версии не ниже 0.7.0. Параметр hnsw.iterative_scan запрашивает версию 0.8.0.

В проектах Aurabase вопрос не возникает: образ Postgres встраивает pgvector 0.8.6 как в общий кластер Postgres (docker/Postgres.Dockerfile, построенный непосредственно на pgvector/pgvector:0.8.6-pg16-bookworm), так и в экземплярах Postgres 16 CNPG, выделенных для каждого проекта (docker/Postgres.CNPG.Dockerfile, который наследует pgvector 0.8.6 из официального образа CloudNativePG). Проверено в обоих файлах Dockerfile 24 августа 2026 г.

Тип столбца зависит от размера ваших внедрений, а не только от модели, которая их генерирует. pgvector хранит классический вектор типа vectorс ограничением в 16 000 измерений. Но индексация HNSW для этого типа ограничена 2000 измерениями: кроме этого CREATE INDEX не работает.

Распространенные модели внедрения часто превышают этот порог: text-embedding-3-large от OpenAI или Gemini-embedding-2 от Google изначально создают до 3072 измерений. Чтобы проиндексировать эти векторы с помощью HNSW, приведите столбец к halfvec (точность хранения уменьшится вдвое), что значительно выдвинет предел индексации за пределы 2000 измерений.

Механизм Aurabase RAG иллюстрирует этот компромисс в производстве: поддерживаются три класса измерений (768, 1536, 3072), хранящиеся в трех отдельных столбцах одной и той же таблицы embeddings. Столбцы 768 и 1536 индексируются непосредственно в HNSW по типу vector. Столбец 3072 индексируется посредством приведения ::halfvec(3072)именно для того, чтобы обойти ограничение размера 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;

Подробные сведения о приеме (фрагментировании, вызове поставщика внедрения, вставке) см. в руководстве по конвейеру RAG на pgvector.

Минимального синтаксиса достаточно для первого индекса со значениями по умолчанию для pgvector.

CREATE INDEX ON items
  USING hnsw (embedding vector_cosine_ops);

Затем pgvector применяет m = 16 и ef_construction = 64. Чтобы явно настроить эти значения, используйте предложение WITH:

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

Что меняет параметр m?

m устанавливает максимальное количество соединений, которые поддерживает каждый узел графа на каждом уровне. Более высокое значение уплотняет график: отзыв увеличивается, но потребление памяти и время построения также увеличиваются, примерно линейно. Значение по умолчанию (16) подходит для большинства случаев. Увеличение числа до 24 или 32 особенно оправдано при больших вложениях, где различие между близкими и дальними соседями становится более тонким.

Что меняет ef_construction?

ef_construction устанавливает размер списка кандидатов, исследуемого во время построения индекса, для каждого вставленного узла. Более высокое значение улучшает качество окончательного графика, а значит и потенциальный отзыв, за счет увеличения времени построения. В отличие от m, этот параметр не требует затрат во время запроса: это единовременная инвестиция, выплачиваемая только один раз при создании индекса.

Частичные индексы для нескольких классов измерений в одной таблице

Если в таблице хранится несколько векторных столбцов (по одному на каждый класс измерений, как это делает Aurabase), индексируйте каждый столбец отдельно с помощью предложения WHERE colonne IS NOT NULL. Этот частичный индекс позволяет избежать индексации пустых строк для классов, не используемых в данной строке, что уменьшает размер индекса и ускоряет его построение без каких-либо затрат на вызов.

Выбор класса оператора (vector_cosine_ops, vector_l2_ops или vector_ip_ops) должен соответствовать метрике, на которой обучалась модель внедрения. Самые последние модели внедрения текста обучены на косинусное сходство: поэтому vector_cosine_ops (или halfvec_cosine_ops в столбце приведения) является самым безопасным выбором по умолчанию.

ef_search устанавливается при каждом запросе, а не при построении индекса. Он устанавливает размер списка кандидатов, исследуемых во время поиска: чем он выше, тем лучше отзыв, но за счет увеличения задержки. pgvector устанавливает значение по умолчанию 40.

SET LOCAL hnsw.ef_search = 100;

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

40 редко бывает достаточно, поскольку запрос сочетает векторный поиск с фильтром WHERE, применяемым после сканирования индекса (по пространству имен, арендатору или любому другому критерию метаданных). Сканирование HNSW возвращает необработанные кандидаты ef_search, затем фильтр отбрасывает часть из них. Если выживет слишком мало кандидатов, финальный LIMIT окажется недополненным.

Таким образом, механизм Aurabase RAG динамически расширяет ef_search в соответствии с запрошенным top_kвместо сохранения фиксированного значения 40: ef = max(top_k × 4, 64). Для поиска 5 ближайших результатов используется ef_search = 64; поиск 50 лучших использует ef_search = 200. Эта формула остается настраиваемой для каждой переменной среды для развертываний, которым требуется другой компромисс между отзывом и задержкой.

В pgvector 0.8 добавлен второй рычаг для решения той же проблемы: hnsw.iterative_scan. В режиме strict_order или relaxed_orderпоиск постепенно расширяется до тех пор, пока после фильтрации не будет собрано достаточно результатов, а не останавливается на фиксированном списке кандидатов. Aurabase активирует его по умолчанию в strict_order, но защищает вызов в точке сохранения. В версии pgvector до 0.8, где этот параметр не существует, запрос продолжается в ухудшенном режиме, а не завершается сбоем.

Этот индекс HNSW — это всего лишь часть полного конвейера RAG: разбиение на фрагменты, генерация внедрения, прием и затем поиск. Наше пошаговое руководство строит этот конвейер сквозным образом на pgvector, от первой вставки до запроса на сходство. В технической документации также подробно описаны все собственные возможности искусственного интеллекта Aurabase, созданные на базе Postgres.