Что такое pgvector и когда он нужен
pgvector — расширение PostgreSQL, которое добавляет тип данных для векторов и операторы поиска ближайших соседей прямо в обычную базу. Не нужно поднимать отдельный сервис: векторы хранятся в той же таблице, что и остальные данные, а поиск делается стандартным SQL-запросом.
Расширение хорошо подходит проектам, где PostgreSQL уже используется как основная база: интернет-магазину, базе знаний, CRM. Для каталогов на десятки миллионов записей с высокой нагрузкой на поиск стоит сравнить pgvector со специализированными базами — см. статью сравнение векторных баз данных.
Установка расширения на VDS
pgvector ставится как обычное расширение PostgreSQL — из пакетов дистрибутива или сборкой из исходников.
sudo apt update
sudo apt install -y postgresql-16-pgvector
sudo -u postgres psql -d mydb -c "CREATE EXTENSION IF NOT EXISTS vector;"Если пакета нет в репозитории дистрибутива, расширение собирается из исходников: клонируйте репозиторий проекта, выполните make и make install с установленными заголовками PostgreSQL.
Создание таблицы с векторной колонкой
Колонка типа vector требует указать размерность — она должна совпадать с моделью эмбеддингов, которая генерирует векторы.
CREATE TABLE articles (
id serial PRIMARY KEY,
title text,
embedding vector(768)
);Размерность 768 подходит для модели multilingual-e5-base — подробнее о выборе модели и генерации векторов рассказано в статье семантический поиск на эмбеддингах.
Индекс для быстрого поиска ближайших соседей
Без индекса PostgreSQL сравнивает запрос с каждой строкой таблицы — это работает, но медленно растёт с объёмом данных. Индекс HNSW ускоряет поиск на больших таблицах ценой небольшой погрешности.
| Индекс | Точность | Скорость на 1 млн строк | Когда использовать |
|---|---|---|---|
| Без индекса | 100 % | медленно | таблицы до 10 тысяч строк |
| IVFFlat | высокая | быстро | средние таблицы, редкие вставки |
| HNSW | высокая | очень быстро | крупные таблицы, частые вставки |
CREATE INDEX ON articles USING hnsw (embedding vector_cosine_ops);Оператор vector_cosine_ops задаёт метрику сходства — для нормализованных эмбеддингов косинусное расстояние обычно даёт лучший результат, чем евклидово.
Поиск ближайших статей по запросу
После построения индекса поиск ближайших записей выполняется обычным SELECT с оператором расстояния <=>.
SELECT id, title, embedding <=> '[0.12, 0.05, ...]' AS distance
FROM articles
ORDER BY distance
LIMIT 5;Вектор запроса подставляется приложением после расчёта той же моделью, что использовалась при индексации. Результат сортируется по возрастанию расстояния — чем меньше значение, тем ближе статья по смыслу к запросу.
Типичные ошибки настройки pgvector
Большинство проблем связаны с несоответствием параметров, а не с самим расширением:
- Размерность колонки не совпадает с размерностью модели — PostgreSQL вернёт ошибку при вставке, проверьте вывод модели заранее.
- Индекс построен под евклидово расстояние, а запросы используют косинусное — результаты поиска окажутся случайными.
- HNSW создан до массовой загрузки данных — индекс лучше строить после первичного импорта, иначе вставка станет заметно медленнее.
- Векторы не нормализованы перед сохранением, хотя модель этого требует — сравните флаг normalize_embeddings в коде генерации.
После настройки pgvector даёт полноценный семантический поиск без дополнительного сервиса. Для нагруженных проектов имеет смысл замерить скорость на реальных данных и сравнить с отдельной векторной базой вроде Qdrant.