Version: 0.8.0

GitHub

Включите расширение (сделайте это один раз в каждой базе данных, где вы хотите его использовать)

CREATE EXTENSION vector;

Создайте векторный столбец с 3 измерениями

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));

Вставить векторы

INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

Получить ближайших соседей по L2 расстоянию

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Также поддерживает скалярное произведение (<#>), косинусное расстояние (<=>) и L1 расстояние (<+>)

Note: <#> возвращает отрицательное внутреннее произведение, так как Postgres поддерживает только ASC порядок индексных сканирований для операторов

Создать новую таблицу с векторной колонкой

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));

Или добавьте векторный столбец в существующую таблицу

ALTER TABLE items ADD COLUMN embedding vector(3);

Также поддерживает половинной точности, бинарные и разреженные векторы

Вставить векторы

INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

Или загрузите векторы оптом, используя COPY (пример)

COPY items (embedding) FROM STDIN WITH (FORMAT BINARY);

Обновление или вставка векторов

INSERT INTO items (id, embedding) VALUES (1, '[1,2,3]'), (2, '[4,5,6]')
    ON CONFLICT (id) DO UPDATE SET embedding = EXCLUDED.embedding;

Обновить векторы

UPDATE items SET embedding = '[1,2,3]' WHERE id = 1;

Удалить векторы

DELETE FROM items WHERE id = 1;

Получить ближайших соседей к вектору

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Поддерживаемые функции расстояния:

Получить ближайших соседей для строки

SELECT * FROM items WHERE id != 1 ORDER BY embedding <-> (SELECT embedding FROM items WHERE id = 1) LIMIT 5;

Получить строки в пределах определенного расстояния

SELECT * FROM items WHERE embedding <-> '[3,1,2]' < 5;

Note: Используйте вместе с ORDER BY и LIMIT, чтобы использовать индекс

SELECT embedding <-> '[3,1,2]' AS distance FROM items;

SELECT (embedding <#> '[3,1,2]') * -1 AS inner_product FROM items;

SELECT 1 - (embedding <=> '[3,1,2]') AS cosine_similarity FROM items;

SELECT AVG(embedding) FROM items;

SELECT category_id, AVG(embedding) FROM items GROUP BY category_id;

По умолчанию pgvector выполняет точный поиск ближайших соседей, который обеспечивает идеальную полноту.

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

Поддерживаемые типы индексов:

Индекс HNSW создает многослойный граф. Он обеспечивает лучшую производительность запросов, чем IVFFlat (в терминах компромисса между скоростью и точностью), но имеет более медленное время построения и использует больше памяти. Также индекс может быть создан без каких-либо данных в таблице, так как отсутствует этап обучения, как в IVFFlat.

Добавьте индекс для каждой функции расстояния, которую вы хотите использовать.

Расстояние L2

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

Note: Используйте halfvec_l2_ops для halfvec и sparsevec_l2_ops для sparsevec (и аналогично с другими функциями расстояния)

Внутреннее произведение

CREATE INDEX ON items USING hnsw (embedding vector_ip_ops);

Косинусное расстояние

CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

Расстояние L1

CREATE INDEX ON items USING hnsw (embedding vector_l1_ops);

Хэммингово расстояние

CREATE INDEX ON items USING hnsw (embedding bit_hamming_ops);

Расстояние Жаккара

CREATE INDEX ON items USING hnsw (embedding bit_jaccard_ops);

Поддерживаемые типы:

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);

SET hnsw.ef_search = 100;

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;

SET maintenance_work_mem = '8GB';

NOTICE:  hnsw graph no longer fits into maintenance_work_mem after 100000 tuples
DETAIL:  Building will take significantly more time.
HINT:  Increase maintenance_work_mem to speed up builds.

SET max_parallel_maintenance_workers = 7; -- plus leader

SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;

Индекс IVFFlat делит векторы на списки, а затем ищет подмножество этих списков, которые находятся ближе всего к вектору запроса. Он имеет более быстрое время построения и использует меньше памяти, чем HNSW, но имеет более низкую производительность запросов (в терминах компромисса между скоростью и полнотой).

Три ключа к достижению хорошего запоминания:

Добавьте индекс для каждой функции расстояния, которую вы хотите использовать.

Расстояние L2

CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);

Note: Используйте halfvec_l2_ops для halfvec (и аналогично с другими функциями расстояния)

Внутреннее произведение

CREATE INDEX ON items USING ivfflat (embedding vector_ip_ops) WITH (lists = 100);

Косинусное расстояние

CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

Хэммингово расстояние

CREATE INDEX ON items USING ivfflat (embedding bit_hamming_ops) WITH (lists = 100);

Поддерживаемые типы:

SET ivfflat.probes = 10;

BEGIN;
SET LOCAL ivfflat.probes = 10;
SELECT ...
COMMIT;

SET max_parallel_maintenance_workers = 7; -- plus leader

SELECT phase, round(100.0 * tuples_done / nullif(tuples_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;

Существует несколько способов индексировать запросы ближайших соседей с WHERE условием.

SELECT * FROM items WHERE category_id = 123 ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Хорошее место для начала - создание индекса на фильтрующем столбце. Это может обеспечить быстрый, точный поиск ближайших соседей во многих случаях. Postgres имеет ряд типов индексов для этого: B-tree (по умолчанию), hash, GiST, SP-GiST, GIN, и BRIN.

CREATE INDEX ON items (category_id);

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

CREATE INDEX ON items (location_id, category_id);

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

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

С приблизительными индексами фильтрация применяется после сканирования индекса. Если условие соответствует 10% строк, с HNSW и значением по умолчанию hnsw.ef_search равным 40, в среднем будет соответствовать только 4 строки. Для большего количества строк увеличьте hnsw.ef_search.

SET hnsw.ef_search = 200;

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

SET hnsw.iterative_scan = strict_order;

Если фильтрация осуществляется только по нескольким различным значениям, рассмотрите частичное индексирование.

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WHERE (category_id = 123);

Если фильтрация осуществляется по многим различным значениям, рассмотрите возможность разбиения на разделы.

CREATE TABLE items (embedding vector(3), category_id int) PARTITION BY LIST(category_id);

Добавлено в 0.8.0

С приблизительными индексами запросы с фильтрацией могут возвращать меньше результатов, так как фильтрация применяется после сканирования индекса. Начиная с версии 0.8.0, вы можете включить итеративные сканирования индекса, которые автоматически будут сканировать больше индекса, пока не будет найдено достаточно результатов (или пока не достигнет hnsw.max_scan_tuples или ivfflat.max_probes).

Итеративные сканирования могут использовать строгое или свободное упорядочение.

Strict гарантирует, что результаты будут в точном порядке по расстоянию

SET hnsw.iterative_scan = strict_order;

Relaxed позволяет результатам быть немного не в порядке по расстоянию, но обеспечивает лучшую полноту

SET hnsw.iterative_scan = relaxed_order;
# or
SET ivfflat.iterative_scan = relaxed_order;

С ослабленным упорядочиванием вы можете использовать материализованное CTE, чтобы получить строгое упорядочивание

WITH relaxed_results AS MATERIALIZED (
    SELECT id, embedding <-> '[1,2,3]' AS distance FROM items WHERE category_id = 123 ORDER BY distance LIMIT 5
) SELECT * FROM relaxed_results ORDER BY distance;

Для запросов, которые фильтруют по расстоянию, используйте материализованное CTE и размещайте фильтр расстояния за его пределами для достижения наилучшей производительности (из-за текущего поведения исполнителя Postgres)

WITH nearest_results AS MATERIALIZED (
    SELECT id, embedding <-> '[1,2,3]' AS distance FROM items ORDER BY distance LIMIT 5
) SELECT * FROM nearest_results WHERE distance < 5 ORDER BY distance;

Примечание: Разместите любые другие фильтры внутри CTE

SET hnsw.max_scan_tuples = 20000;

SET hnsw.scan_mem_multiplier = 2;

SET ivfflat.max_probes = 100;

Используйте тип halfvec для хранения векторов с половинной точностью

CREATE TABLE items (id bigserial PRIMARY KEY, embedding halfvec(3));

Индексы векторов с половинной точностью для меньших индексов

CREATE INDEX ON items USING hnsw ((embedding::halfvec(3)) halfvec_l2_ops);

Получить ближайших соседей

SELECT * FROM items ORDER BY embedding::halfvec(3) <-> '[1,2,3]' LIMIT 5;

Используйте тип bit для хранения бинарных векторов (пример)

CREATE TABLE items (id bigserial PRIMARY KEY, embedding bit(3));
INSERT INTO items (embedding) VALUES ('000'), ('111');

Получить ближайших соседей по расстоянию Хэмминга

SELECT * FROM items ORDER BY embedding <~> '101' LIMIT 5;

Также поддерживает расстояние Джаккара (<%>)

Используйте индексирование выражений для бинарной квантования

CREATE INDEX ON items USING hnsw ((binary_quantize(embedding)::bit(3)) bit_hamming_ops);

Получить ближайших соседей по расстоянию Хэмминга

SELECT * FROM items ORDER BY binary_quantize(embedding)::bit(3) <~> binary_quantize('[1,-2,3]') LIMIT 5;

Пересортировать по оригинальным векторам для лучшего восстановления

SELECT * FROM (
    SELECT * FROM items ORDER BY binary_quantize(embedding)::bit(3) <~> binary_quantize('[1,-2,3]') LIMIT 20
) ORDER BY embedding <=> '[1,-2,3]' LIMIT 5;

Используйте тип sparsevec для хранения разреженных векторов

CREATE TABLE items (id bigserial PRIMARY KEY, embedding sparsevec(5));

Вставить векторы

INSERT INTO items (embedding) VALUES ('{1:1,3:2,5:3}/5'), ('{1:4,3:5,5:6}/5');

Формат {индекс1:значение1,индекс2:значение2}/размерности и индексы начинаются с 1, как в SQL массивах

Получить ближайших соседей по L2 расстоянию

SELECT * FROM items ORDER BY embedding <-> '{1:3,3:1,5:2}/5' LIMIT 5;

Используйте вместе с Postgres полнотекстовым поиском для гибридного поиска.

SELECT id, content FROM items, plainto_tsquery('hello search') query
    WHERE textsearch @@ query ORDER BY ts_rank_cd(textsearch, query) DESC LIMIT 5;

Вы можете использовать Reciprocal Rank Fusion или кросс-энкодер, чтобы объединить результаты.

Используйте индексирование выражений для индексирования подвекторов

CREATE INDEX ON items USING hnsw ((subvector(embedding, 1, 3)::vector(3)) vector_cosine_ops);

Получить ближайших соседей по косинусному расстоянию

SELECT * FROM items ORDER BY subvector(embedding, 1, 3)::vector(3) <=> subvector('[1,2,3,4,5]'::vector, 1, 3) LIMIT 5;

Повторно ранжировать по полным векторам для лучшего восстановления

SELECT * FROM (
    SELECT * FROM items ORDER BY subvector(embedding, 1, 3)::vector(3) <=> subvector('[1,2,3,4,5]'::vector, 1, 3) LIMIT 20
) ORDER BY embedding <=> '[1,2,3,4,5]' LIMIT 5;

Отслеживайте производительность с помощью pg_stat_statements (не забудьте добавить его в shared_preload_libraries).

CREATE EXTENSION pg_stat_statements;

Получите наиболее времязатратные запросы с помощью:

SELECT query, calls, ROUND((total_plan_time + total_exec_time) / calls) AS avg_time_ms,
    ROUND((total_plan_time + total_exec_time) / 60000) AS total_time_min
    FROM pg_stat_statements ORDER BY total_plan_time + total_exec_time DESC LIMIT 20;

Note: Замените total_plan_time + total_exec_time на total_time для Postgres < 13

Контролируйте отзыв, сравнивая результаты приблизительного поиска с точным поиском.

BEGIN;
SET LOCAL enable_indexscan = off; -- use exact search
SELECT ...
COMMIT;

Масштабируйте pgvector так же, как вы масштабируете Postgres.

Масштабируйте вертикально, увеличивая память, ЦП и хранилище на одном экземпляре. Используйте существующие инструменты для настройки параметров и мониторинга производительности.

Масштабируйте горизонтально с репликами, или используйте Citus или другой подход для шардирования (пример).

Используйте pgvector из любого языка с клиентом Postgres. Вы можете даже генерировать и сохранять векторы на одном языке и выполнять запросы на другом.

pgvector доступен на этих провайдерах.

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

ALTER EXTENSION vector UPDATE;

Вы можете проверить версию в текущей базе данных с помощью:

SELECT extversion FROM pg_extension WHERE extname = 'vector';

Благодарности:

Просмотрите журнал изменений

Каждый может помочь улучшить этот проект. Вот несколько способов, как вы можете помочь:

Чтобы начать разработку:

git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

Чтобы запустить все тесты:

make installcheck        # regression tests
make prove_installcheck  # TAP tests

Чтобы запустить отдельные тесты:

make installcheck REGRESS=functions                            # regression test
make prove_installcheck PROVE_TESTS=test/t/001_ivfflat_wal.pl  # TAP test

Чтобы включить утверждения:

make clean && PG_CFLAGS="-DUSE_ASSERT_CHECKING" make && make install

Чтобы включить тестирование производительности:

make clean && PG_CFLAGS="-DIVFFLAT_BENCH" make && make install

Чтобы показать использование памяти:

make clean && PG_CFLAGS="-DHNSW_MEMORY -DIVFFLAT_MEMORY" make && make install

Чтобы получить метрики k-средних:

make clean && PG_CFLAGS="-DIVFFLAT_KMEANS_DEBUG" make && make install

Ресурсы для участников