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

> Установка pgvector для PostgreSQL: создание векторной колонки, индекс HNSW, поиск ближайших соседей и типичные ошибки настройки на VDS.

## Что такое pgvector и когда он нужен

pgvector — расширение PostgreSQL, которое добавляет тип данных для векторов и операторы поиска ближайших соседей прямо в обычную базу. Не нужно поднимать отдельный сервис: векторы хранятся в той же таблице, что и остальные данные, а поиск делается стандартным SQL-запросом.

Расширение хорошо подходит проектам, где PostgreSQL уже используется как основная база: интернет-магазину, базе знаний, CRM. Для каталогов на десятки миллионов записей с высокой нагрузкой на поиск стоит сравнить pgvector со специализированными базами — см. статью [сравнение векторных баз данных](https://www.zevshost.net/ru/kb/vektornye-bd-sravnenie/).

## Установка расширения на 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 — подробнее о выборе модели и генерации векторов рассказано в статье [семантический поиск на эмбеддингах](https://www.zevshost.net/ru/kb/semanticheskiy-poisk-embeddings/).

## Индекс для быстрого поиска ближайших соседей

Без индекса 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.

---

Источник: https://www.zevshost.net/ru/kb/pgvector-postgresql/