Хранение и поиск эмбеддингов Ollama в PostgreSQL с помощью pgvector

README pgvector описывает его как поиск векторов по сходству с открытым исходным кодом для Postgres. Он поддерживает точный и приближённый поиск ближайших соседей; векторы с одинарной точностью, половинной точностью, бинарные и разреженные; а также расстояние L2, скалярное произведение, косинусное расстояние, расстояние L1, расстояние Хэмминга и расстояние Жаккара. Поскольку векторы — обычные столбцы PostgreSQL, на них распространяются и соответствие ACID, восстановление на момент времени (point-in-time recovery) и JOIN.

Чтобы искать по документам, вы сохраняете по одной строке на фрагмент — с его текстом и вектором, создаёте эмбеддинг вопроса той же моделью и сортируете строки по расстоянию до вектора вопроса.

pgvector поддерживает PostgreSQL 13 и новее. README перечисляет несколько способов установки, в том числе такие:

Столбец типа vector(n) хранит векторы ровно с n измерениями, и n должно совпадать с длиной векторов вашей модели эмбеддингов. Вектор другой длины отклоняется: когда мы вставили вектор с 2 измерениями в столбец vector(3), PostgreSQL вернул "expected 3 dimensions, not 2". all-minilm возвращает 384 измерения, поэтому его столбец — vector(384).

README указывает, что каждый вектор занимает 4 × измерения + 8 байт, причём каждый элемент — число с плавающей запятой одинарной точности, и допускает до 16,000 измерений в столбце. Индекс поддерживает меньше измерений, как показано ниже. Тип halfvec хранит значения половинной точности в 2 × измерения + 8 байт.

pgvector читает вектор как текст в квадратных скобках, например '[1,2,3]', а README говорит, что все элементы должны быть конечными (без NaN, Infinity и -Infinity). Каждый массив в поле embeddings ответа /api/embed уже имеет такой вид, а ответ сохраняет порядок входных данных, поэтому первому тексту соответствует первый вектор.

README показывает INSERT для нескольких строк, INSERT … ON CONFLICT для upsert и COPY для массовой загрузки. Конвертер ниже сопоставляет ваши тексты с ответом и пишет операторы INSERT с экранированными кавычками. Мы выполнили его результат с текстами, в которых были кавычки, обратные косые черты, переводы строк и эмодзи, и они вернулись без изменений.

Документация Ollama рекомендует косинусное сходство для большинства случаев семантического поиска и говорит, что /api/embed возвращает векторы длиной 1. Для таких векторов косинусное расстояние, расстояние L2 и скалярное произведение упорядочивают строки одинаково, потому что квадрат расстояния L2 равен 2 минус 2, умноженное на косинусное сходство. В нашем тесте с all-minilm первые три строки были одинаковыми для всех трёх мер, а расстояние L2 0.931 соответствовало косинусному сходству 0.566.

У каждого расстояния свой оператор. Поиск сортирует по оператору и берёт первые строки с помощью LIMIT, а индекс строится для одного класса операторов.

Без индекса pgvector выполняет точный поиск ближайших соседей, который, по словам README, обеспечивает идеальную полноту (recall). Приближённый индекс обменивает часть полноты на скорость, и README предупреждает, что после добавления индекса запросы могут возвращать другие результаты.

Индекс используется только тогда, когда в запросе есть ORDER BY и LIMIT, а ORDER BY — это сам оператор расстояния по возрастанию. ORDER BY embedding <=> $1 LIMIT 5 может использовать индекс; ORDER BY 1 - (embedding <=> $1) DESC — не может. README также отмечает, что полное сканирование таблицы может быть быстрее, если таблица небольшая.

В HNSW результаты ограничены параметром hnsw.ef_search, по умолчанию 40. На тестовой таблице из 200 строк с индексом HNSW запрос с LIMIT 100 вернул 40 строк; после SET hnsw.ef_search = 100 он вернул 100. Задайте hnsw.ef_search не меньше числа нужных вам строк. SET LOCAL внутри транзакции меняет значение только для одного запроса.

Фильтрация тоже уменьшает результаты. При приближённых индексах, по словам README, условие WHERE применяется после сканирования индекса: если условию соответствует 10% строк, HNSW со значением hnsw.ef_search по умолчанию 40 в среднем вернёт только 4 строки. Начиная с версии 0.8.0 итеративное сканирование индекса (SET hnsw.iterative_scan = strict_order или relaxed_order) просматривает индекс дальше, пока не найдётся достаточно строк, но не больше hnsw.max_scan_tuples (по умолчанию 20,000).

Когда поиск вернул ближайшие строки, модели нужно передать их в промпте. /api/chat в Ollama принимает список сообщений, у каждого есть роль (system, user, assistant или tool) и содержимое. Простая схема — системное сообщение с правилами и сообщение пользователя, в котором перечислены строки, каждая со своим номером, например [1] и [2], а за ними вопрос. С номерами ответ может указать, какими строками он воспользовался, а каждый номер можно сопоставить обратно со строкой.

Чтобы ссылки на источники имели постоянную форму, передайте в поле format схему JSON Schema с ответом и списком ссылок, у каждой из которых есть номер источника и короткая цитата. Страница Ollama о структурированном выводе рекомендует также записать схему в промпте и снизить температуру (temperature), например до 0, чтобы вывод был более детерминированным. В psql функция json_agg собирает строки запроса в массив JSON, который инструмент ниже читает напрямую.

Правила, строки и вопрос должны поместиться в длину контекста. Страница Ollama о длине контекста указывает по умолчанию 4k токенов при менее чем 24 GiB VRAM, а FAQ — 4096 токенов; ollama ps на нашей тестовой машине показала 4096. Изменить её можно через num_ctx в options или через переменную окружения OLLAMA_CONTEXT_LENGTH.

Если промпт длиннее, /api/chat по умолчанию не возвращает ошибку. В исходном коде Ollama (0.40.11) сервер сначала отбрасывает целиком более ранние сообщения, сохраняя системные сообщения и последнее сообщение. Если оставшийся промпт всё равно слишком длинный, он сохраняет несколько первых токенов (num_keep, по умолчанию 4) и конец промпта, а середину отбрасывает. В нашем тесте с qwen2.5:7b и num_ctx 1024 промпт из 2,068 токенов был обрезан до 514. Системное сообщение и первые источники были потеряны: когда ответ был в источнике [1], модель ответила кодовым словом, которого не было ни в одном источнике, а когда ответ был в последнем источнике, она ответила верно, но без номера источника, который требовало системное сообщение. В ответе не было ошибки; в журнале сервера было предупреждение "truncating input prompt".

В исходном коде Ollama у запросов к чату есть и поле truncate, которого нет на странице /api/chat. С "truncate": false тот же запрос вернул HTTP 400 с ошибкой "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". Поле prompt_eval_count в ответе — это число токенов в промпте; в тесте с обрезкой оно равнялось 514, а не 2,068.

Ссылку на источник можно проверить механически: номер должен указывать на отправленный источник, а цитата должна встречаться в этом источнике. В нашем тесте с четырьмя источниками и qwen2.5:7b цитаты в ответах JSON совпадали с источниками слово в слово. Это не доказывает, что ответ верен: на вопрос о размере вектора с 384 измерениями модель процитировала верное правило (4 умножить на число измерений плюс 8 байт) и всё равно ответила 1552 байта вместо 1,544.

Смотрите и на ответы без ссылок. Когда в источниках ответа не было, модель один раз ответила из собственных знаний без ссылок, а один раз сказала, что не знает, но всё равно сослалась на посторонний источник. Если done_reason в ответе равен "length", ответ был обрезан из-за num_predict, и в нём могут отсутствовать ссылки.

README говорит, что индекс HNSW строится заметно быстрее, когда граф помещается в maintenance_work_mem, выводит уведомление, когда он перестаёт помещаться, и предупреждает, что не следует задавать maintenance_work_mem настолько большим, чтобы исчерпать память сервера. Как и в случае других индексов, быстрее создавать индекс после загрузки начальных данных. Индексы не обязаны помещаться в память, но, скорее всего, будут работать лучше, если помещаются; SELECT pg_size_pretty(pg_relation_size('index_name')) показывает размер индекса.

Для меньшего рабочего набора и меньших индексов README предлагает halfvec, индексирование с половинной точностью или бинарное квантование. Если Ollama работает на том же сервере, PostgreSQL и модели делят одну и ту же память; наша статья о наблюдении за памятью Ollama объясняет, от чего зависит, сколько её используют модели.