pgvector: устанавливаем векторный поиск прямо в PostgreSQL

Pgvector — это расширение PostgreSQL, которое добавляет тип данных vector и операторы поиска ближайших соседей прямо в обычную реляционную базу. Отдельный векторный сервис для этого не нужен. Если ваш стек уже стоит на PostgreSQL или Supabase, это самый короткий путь к семантическому поиску и RAG.

Pgvector решает задачу без нового элемента в архитектуре: ставите расширение туда, где база уже стоит. В статье: установка через Docker и на Windows, команда CREATE EXTENSION, разница между IVFFlat и HNSW, и честный ответ, когда вместо pgvector нужна отдельная векторная база вроде Qdrant.

Что такое pgvector и зачем он вайбкодеру

Pgvector добавляет в PostgreSQL тип vector и три оператора расстояния для поиска похожих записей. Работает как обычное расширение SQL, без отдельного сервиса.

Pgvector — это расширение Postgres, а не отдельная база данных. Именно поэтому его ставят на уже существующий сервер одной командой SQL, без миграции данных куда-то ещё. Проект pgvector с открытым исходным кодом, актуальная стабильная версия на GitHub — 0.8.2.

Для вайбкодера это выглядит так: у вас уже есть Supabase под приложением, а значит база на PostgreSQL уже есть. Добавить туда семантический поиск, RAG для чат-бота или рекомендации по товарам можно без нового сервиса, без отдельного биллинга и без второй системы, за которой нужно следить. Поиск похожих объектов работает через операторы <-> (Евклидово расстояние), <#> (скалярное произведение) и <=> (косинусное расстояние) прямо в SELECT-запросе.

Обратная сторона: pgvector не создаёт для вас новую базу с нуля. Он подключается поверх существующей PostgreSQL, а значит нагрузка на векторный поиск ложится на тот же сервер, что обслуживает остальное приложение.

Как установить pgvector через Docker

Быстрее всего поставить pgvector локально через официальный Docker-образ pgvector/pgvector — Postgres и расширение приходят уже собранными вместе, без компиляции.

Официальный образ pgvector/pgvector разворачивает PostgreSQL с уже вкомпилированным расширением одной командой docker run. Это самый быстрый способ протестировать векторный поиск локально, без установки postgres на хост-машину и без сборки из исходников.

Команда для теста выглядит так:

docker run -d --name pg-vector -e POSTGRES_PASSWORD=pass -p 5432:5432 pgvector/pgvector:pg17

После старта контейнера подключаетесь любым клиентом (psql, DBeaver, TablePlus) на порт 5432 и внутри базы выполняете CREATE EXTENSION vector. Если у вас уже есть база PostgreSQL, а не свежий контейнер, ставить весь образ заново не нужно. Расширение либо уже есть в вашем дистрибутиве Postgres (так у Supabase, Railway, Neon), либо доустанавливается пакетом для вашей ОС, и дальше применяется тот же CREATE EXTENSION.

Для Supabase процесс ещё короче: в дашборде заходите в Database → Extensions, ищете vector и включаете тумблером. Ни докера, ни терминала.

Как установить pgvector на Windows

На Windows придётся ставить PostgreSQL, скачивать Visual Studio C++ Build Tools и собирать расширение из исходников через nmake — процесс на порядок сложнее, чем на Linux или Mac.

Компиляция C-расширения на голом Windows — источник большинства ошибок у новичков. На Linux и Mac установка через Homebrew или apt занимает одну команду. На Windows придётся собирать pgvector руками, и это реальная боль, судя по объёму запросов именно про эту платформу.

Порядок такой:

1. Ставите PostgreSQL с postgresql.org. Берите стабильную версию — часть свежих сборок (18.x, 15.15) у пользователей не собиралась, а 13.x и 16.x заходили без проблем.
2. Запоминаете пароль, который задаёте при установке. Он понадобится при каждом подключении.
3. Ставите Visual Studio Build Tools и в компонентах выбираете именно "Desktop development with C++" — без этого пункта сборка расширения не пойдёт.
4. Открываете x64 Native Tools Command Prompt for VS 2022 от имени администратора. Обычная командная строка тут не подойдёт: нужна консоль с настроенным окружением компилятора.
5. Прописываете переменную окружения на директорию Postgres командой set PGROOT=C:\Program Files\PostgreSQL\16, скачиваете исходники pgvector с GitHub и собираете через make -f win32/Makefile.win, затем make /f win32/Makefile.win install.

После установки заходите в SQL Shell и проверяете командой CREATE EXTENSION vector. Если ошибок нет, расширение подключилось.

Если возни с компилятором совсем не хочется — вариант с Docker выше решает задачу за одну команду и без Visual Studio вообще.

Как включить pgvector командой CREATE EXTENSION

Расширение включается одной SQL-командой в каждой базе, где оно нужно, дальше создаётся таблица с колонкой типа vector и заполняется эмбеддингами.

CREATE EXTENSION vector активирует расширение один раз для конкретной базы данных. Дальше можно создавать таблицы с колонкой-вектором и хранить эмбеддинги рядом с обычными данными: заголовком, описанием, ценой, датой.

CREATE EXTENSION vector;

CREATE TABLE items (
  id bigserial PRIMARY KEY,
  title text,
  embedding vector(384)
);

INSERT INTO items (title, embedding) VALUES ('Пример', '[0.1, 0.2, 0.3]');

SELECT * FROM items ORDER BY embedding <=> '[0.1, 0.2, 0.29]' LIMIT 5;

Число в vector(384) — размерность эмбеддинга, она зависит от модели: у all-MiniLM это 384, у моделей OpenAI text-embedding обычно 1536. Размерность фиксируется на уровне таблицы при её создании, менять её потом без пересоздания колонки нельзя.

Без индекса такой запрос работает точным полным перебором. На небольших таблицах, до сотни тысяч записей, этого достаточно и без индекса. На миллионе записей полный перебор уже занимает больше двух секунд на запрос, и тут в игру вступают индексы.

IVFFlat или HNSW что выбрать

IVFFlat быстрее строится и экономит память, HNSW точнее и быстрее отвечает на запрос, но дольше строится и требует больше памяти. Для датасетов больше миллиона записей чаще берут IVFFlat.

На тесте с миллионом векторов IVFFlat построился за минуту и отвечал на запрос за 0.0365 секунды, HNSW строился 25 минут и отвечал за 0.0795 секунды. Без индекса тот же запрос занимал 2.12 секунды. Разница на порядки, и выбор индекса реально влияет на то, будет ли приложение отзывчивым.

IVFFlat работает через кластеризацию: делит все векторы на группы (lists), а при поиске проверяет не все группы, а только ближайшие (probes). Это компромисс между точностью и скоростью, но компромисс управляемый: можно увеличить число probes и получить точность выше ценой скорости.

HNSW строит графовую структуру, где каждый вектор связан с соседями на нескольких уровнях. Это даёт стабильно высокую точность поиска и хорошую скорость самого запроса, но построение такого графа медленнее и прожорливее по памяти, особенно на больших объёмах.

После создания IVFFlat-индекса обязательно выполните ANALYZE items — без этого индекс существует, но Postgres может его не использовать при построении плана запроса.

Pgvector или Qdrant когда что выбрать

Pgvector выигрывает, если проект уже на PostgreSQL и объём векторов до нескольких миллионов. Qdrant и другие специализированные базы выигрывают на масштабе, гибридном поиске и тонком контроле индексации.

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

Если стек уже стоит на Postgres или Supabase, а объём эмбеддингов не превышает нескольких миллионов, pgvector закрывает задачу без нового элемента в инфраструктуре, почти бесплатно и без отдельного DevOps. Qdrant написан на Rust, работает быстрее на больших объёмах и даёт тонкий контроль над квантованием индекса, но это отдельный сервис, который нужно поднимать и поддерживать. Pinecone — полностью управляемый serverless-вариант, вообще без инфраструктуры на вашей стороне, но за это платите долларами, а не временем инженера. Weaviate добавляет гибридный поиск: объединяет векторный поиск с обычным поиском по ключевым словам (BM25) в одном запросе, это удобно, когда точное совпадение термина важно так же, как смысл.

Практический совет: оборачивайте вызовы векторной базы тонким интерфейсом в коде, с одними и теми же методами upsert и search. Тогда переход с pgvector на Qdrant, если проект вырастет, займёт день, а не переписывание половины бэкенда.

Максим: «Я уверен полностью, что языки программирования вообще не нужно изучать. Нейросети обучены на 80+ языках. Нужно погружаться в архитектуру: фронт, бэк, база данных.»

Сколько стоит pgvector и когда его уже мало

Pgvector сам по себе бесплатен: платите только за сервер PostgreSQL, который у вас, скорее всего, уже есть. Специализированная база начинает окупаться на масштабе от десятков миллионов векторов или при потребности в hybrid search и сложной фильтрации из коробки.

Self-hosted Qdrant или Weaviate требуют отдельного сервера и времени на его обслуживание. Managed-варианты вроде Pinecone стоят дороже в деньгах, но экономят время инженера на операциях. Pgvector в этом сравнении почти бесплатен: цена — это цена вашего уже существующего Postgres-сервера, без дополнительной подписки.

Проблема с наивной фильтрацией касается всех вариантов одинаково. Наивные системы сначала находят ближайших соседей, а потом отбрасывают те, что не прошли фильтр по метаданным, из-за чего результатов может не хватить. Qdrant и Pinecone умеют делать поиск с учётом фильтра сразу, без постобработки. У pgvector это тоже решается через комбинацию WHERE и оператора расстояния в одном запросе, но нужно проверять план запроса вручную.

Итог когда pgvector решает, а когда нет

Для большинства проектов на этапе MVP и раннего роста pgvector закрывает задачу семантического поиска полностью. Не нужно поднимать новый сервис, разбираться с ещё одним биллингом, тащить в стек Rust-based базу ради проекта на 50 тысяч записей.

Переходить на специализированную базу стоит, когда объём переваливает за десятки миллионов векторов, когда нужен hybrid search из коробки, или когда задержка на индексации HNSW в pgvector начинает мешать продакшену. До этого момента расширение справляется, и справляется дёшево.

Глоссарий

• Эмбеддинг (embedding) — числовое векторное представление текста, изображения или другого объекта, где похожие по смыслу объекты имеют близкие координаты.
• Косинусное расстояние — метрика похожести двух векторов по углу между ними, оператор <=> в pgvector.
• IVFFlat — тип индекса на основе кластеризации векторов, быстрее строится, чуть менее точен.
• HNSW — тип индекса на графовой структуре, точнее, но дольше строится и требует больше памяти.
• RAG (Retrieval-Augmented Generation) — подход, при котором нейросеть перед ответом ищет релевантные фрагменты в базе знаний через векторный поиск.
• Recall — доля реально релевантных результатов, которые индекс находит, ключевая метрика точности при выборе между IVFFlat и HNSW.

Частые вопросы про pgvector

Нужен ли отдельный сервер для pgvector?
Нет, это расширение существующего PostgreSQL. Если у вас уже есть база на Supabase, Railway или своём сервере, отдельный сервис не нужен.

Какую версию PostgreSQL ставить для pgvector?
Расширение поддерживает Postgres 11 и новее. По опыту пользователей на Windows стабильнее заходят версии 13.x и 16.x, а не самые свежие мажорные релизы.

Что делать, если CREATE EXTENSION vector выдаёт ошибку?
Чаще всего расширение просто не установлено в системе. Через Docker-образ pgvector/pgvector оно уже вкомпилировано, через обычный Postgres на Windows его нужно собрать вручную через Visual Studio Build Tools.

IVFFlat или HNSW для проекта на 50 тысяч записей?
На таком объёме разница в скорости почти не заметна, а точность у HNSW выше. Для маленьких и средних датасетов HNSW обычно удобнее.

Можно ли использовать pgvector вместе с Supabase бесплатно?
Да, расширение включается тумблером в дашборде Database → Extensions и не требует отдельной оплаты сверх обычного тарифа Supabase.

Когда pgvector точно не хватит?
На объёмах от десятков миллионов векторов, при потребности в продвинутом hybrid search или когда задержка индексации HNSW становится проблемой для продакшена.

Чем отличается pgvector от pgvector-python?
Pgvector — это расширение SQL для самого PostgreSQL. Pgvector-python — отдельная библиотека-клиент для работы с этим расширением из Python.

Если стек портала или бота уже собран на Supabase или другой PostgreSQL-базе, разобраться с выбором между pgvector и специализированной векторной базой для конкретного проекта можно на консультации с Максимом. Подробнее про сами векторные базы данных и их устройство — в статье «Векторная база данных — что это», а сравнение Pinecone, Qdrant и pgvector детально — в материале «Векторные базы: Pinecone vs Qdrant vs pgvector». Про сборку SaaS на Supabase за выходные — в гайде «SaaS за выходные: Supabase + Lovable».

Обновлено: сентябрь 2026