Точный и приближённый векторный поиск

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

Точный векторный поиск вычисляет расстояние между заданной точкой и всеми точками в векторном пространстве. Это обеспечивает максимально возможную точность, то есть возвращаемые точки гарантированно являются фактическими ближайшими соседями. Поскольку векторное пространство просматривается полностью, точный векторный поиск может быть слишком медленным для практического использования.
Приближённый векторный поиск относится к группе методов (например, специальные структуры данных, такие как графы и случайные леса), которые вычисляют результаты намного быстрее, чем точный векторный поиск. Точность результата, как правило, «достаточно хороша» для практического применения. Многие приближённые методы предоставляют параметры для настройки компромисса между точностью результата и временем поиска.

Векторный поиск (точный или приближённый) может быть записан на SQL следующим образом:

WITH [...] AS reference_vector
SELECT [...]
FROM table
WHERE [...] -- условие WHERE необязательно
ORDER BY <DistanceFunction>(vectors, reference_vector)
LIMIT <N>

Точки в векторном пространстве хранятся в столбце vectors типа массива, например Array(Float64), Array(Float32) или Array(BFloat16). Эталонный вектор — это константный массив, задаваемый в виде общего табличного выражения. <DistanceFunction> вычисляет расстояние между эталонной точкой и всеми сохранёнными точками. Для этого может быть использована любая из доступных функций расстояния. <N> задаёт, сколько соседей нужно вернуть.

Точный поиск по векторам

Точный поиск по векторам можно выполнить с использованием приведённого выше запроса SELECT без изменений. Время выполнения таких запросов, как правило, пропорционально количеству сохранённых векторов и их размерности, то есть количеству элементов массива. Кроме того, поскольку ClickHouse выполняет полный перебор всех векторов, время выполнения таких запросов также зависит от количества потоков, используемых запросом (см. настройку max_threads).

Пример

CREATE TABLE tab(id Int32, vec Array(Float32)) ENGINE = MergeTree ORDER BY id;

INSERT INTO tab VALUES (0, [1.0, 0.0]), (1, [1.1, 0.0]), (2, [1.2, 0.0]), (3, [1.3, 0.0]), (4, [1.4, 0.0]), (5, [1.5, 0.0]), (6, [0.0, 2.0]), (7, [0.0, 2.1]), (8, [0.0, 2.2]), (9, [0.0, 2.3]), (10, [0.0, 2.4]), (11, [0.0, 2.5]);

WITH [0., 2.] AS reference_vec
SELECT id, vec
FROM tab
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3;

возвращает

   ┌─id─┬─vec─────┐
1. │  6 │ [0,2]   │
2. │  7 │ [0,2.1] │
3. │  8 │ [0,2.2] │
   └────┴─────────┘

Приблизительный векторный поиск

Индексы сходства векторов

ClickHouse предоставляет специальный индекс сходства векторов («vector similarity») для выполнения приблизительного векторного поиска.

Примечание

Индексы сходства векторов доступны в ClickHouse версиях 25.8 и новее. Если вы столкнётесь с проблемами, пожалуйста, создайте issue в репозитории ClickHouse.

Создание индекса сходства векторов

Индекс сходства векторов можно создать на новой таблице следующим образом:

CREATE TABLE table
(
  [...],
  vectors Array(Float*),
  INDEX <index_name> vectors TYPE vector_similarity(<type>, <distance_function>, <dimensions>) [GRANULARITY <N>]
)
ENGINE = MergeTree
ORDER BY [...]

В качестве альтернативы можно добавить индекс векторного сходства к уже существующей таблице:

ALTER TABLE table ADD INDEX <index_name> vectors TYPE vector_similarity(<type>, <distance_function>, <dimensions>) [GRANULARITY <N>];

Индексы векторного сходства — это особый вид пропускающих индексов (см. здесь и здесь). Соответственно, приведенный выше оператор ALTER TABLE приводит к тому, что индекс строится только для новых данных, которые будут вставляться в таблицу. Чтобы построить индекс и для уже существующих данных, его необходимо материализовать:

ALTER TABLE table MATERIALIZE INDEX <index_name> SETTINGS mutations_sync = 2;

Функция <distance_function> должна быть

L2Distance, евклидовым расстоянием, представляющим длину отрезка между двумя точками в евклидовом пространстве, или
cosineDistance, косинусным расстоянием, представляющим угол между двумя ненулевыми векторами.

Для нормализованных данных обычно лучше всего подходит L2Distance, в противном случае рекомендуется cosineDistance, чтобы компенсировать масштаб.

<dimensions> задаёт размер массива (количество элементов) в базовом столбце. Если при создании индекса ClickHouse обнаружит массив с другим размером, индекс не будет создан, а будет возвращена ошибка.

Необязательный параметр GRANULARITY <N> относится к размеру гранул индекса (см. здесь). Значение по умолчанию — 100 миллионов — должно хорошо подходить для большинства вариантов использования, но его также можно настроить. Мы рекомендуем выполнять настройку только продвинутым пользователям, которые понимают последствия своих действий (см. ниже).

Индексы векторного сходства являются обобщёнными в том смысле, что могут использовать различные методы приблизительного поиска. Фактически используемый метод задаётся параметром <type>. На данный момент доступен только метод HNSW (академическая статья) — популярная и современная техника приблизительного поиска по векторам на основе иерархических графов близости. Если в качестве типа используется HNSW, пользователи могут дополнительно указать специфичные для HNSW параметры:

CREATE TABLE table
(
  [...],
  vectors Array(Float*),
  INDEX index_name vectors TYPE vector_similarity('hnsw', <distance_function>, <dimensions>[, <quantization>, <hnsw_max_connections_per_layer>, <hnsw_candidate_list_size_for_construction>]) [GRANULARITY N]
)
ENGINE = MergeTree
ORDER BY [...]

Доступны следующие параметры, специфичные для HNSW:

<quantization> управляет квантизацией векторов в графе близости. Возможные значения: f64, f32, f16, bf16, i8 или b1. Значение по умолчанию — bf16. Обратите внимание, что этот параметр не влияет на представление векторов во внутреннем столбце.
<hnsw_max_connections_per_layer> управляет количеством соседей у каждой вершины графа, также известным как гиперпараметр HNSW M. Значение по умолчанию — 32. Значение 0 означает использование значения по умолчанию.
<hnsw_candidate_list_size_for_construction> управляет размером динамического списка кандидатов во время построения графа HNSW, также известным как гиперпараметр HNSW ef_construction. Значение по умолчанию — 128. Значение 0 означает использование значения по умолчанию.

Значения по умолчанию всех параметров, специфичных для HNSW, достаточно хорошо подходят для большинства сценариев использования. Поэтому мы не рекомендуем изменять эти параметры.

Дополнительно действуют следующие ограничения:

Индексы векторного сходства могут быть построены только по столбцам типов Array(Float32), Array(Float64) или Array(BFloat16). Массивы допускающих NULL и чисел с плавающей запятой с низкой кардинальностью, такие как Array(Nullable(Float32)) и Array(LowCardinality(Float32)), не поддерживаются.
Индексы векторного сходства должны строиться по отдельным столбцам.
Индексы векторного сходства могут быть построены по вычисляемым выражениям (например, INDEX index_name arraySort(vectors) TYPE vector_similarity([...])), но такие индексы не могут быть использованы для последующего приближённого поиска ближайших соседей.
Для индексов векторного сходства требуется, чтобы все массивы в базовом столбце содержали <dimension> элементов — это проверяется при создании индекса. Чтобы как можно раньше обнаружить нарушения этого требования, пользователи могут добавить ограничение для векторного столбца, например, CONSTRAINT same_length CHECK length(vectors) = 256.
Аналогично, значения массивов в базовом столбце не должны быть пустыми ([]) и не должны иметь пустое значение по умолчанию (также []).

Оценка потребления хранилища и памяти

Вектор, сгенерированный для использования с типичной моделью ИИ (например, большой языковой моделью, LLMs), состоит из сотен или тысяч значений с плавающей запятой. Таким образом, одно векторное значение может потреблять несколько килобайт памяти. Пользователи, которые хотят оценить объём хранилища, необходимый для базового векторного столбца в таблице, а также объём оперативной памяти, необходимый для индекса векторного сходства, могут использовать две приведённые ниже формулы:

Потребление хранилища векторным столбцом в таблице (без сжатия):

Потребление хранилища = Количество векторов × Размерность × Размер типа данных столбца

Пример для датасета DBpedia:

Потребление хранилища = 1 миллион * 1536 * 4 (для Float32) = 6,1 ГБ

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

Объём памяти, необходимый для загрузки векторного индекса:

Память для векторов в индексе (mv) = Количество векторов * Размерность * Размер квантованного типа данных
Память для графа в оперативной памяти (mg) = Количество векторов * hnsw_max_connections_per_layer * Байт_на_идентификатор_узла (= 4) * Коэффициент_повторения_узлов_по_слоям (= 2)

Потребление памяти: mv + mg

Пример для набора данных DBpedia:

Память для векторов в индексе (mv) = 1 млн * 1536 * 2 (для BFloat16) = 3072 МБ
Память для графа в памяти (mg) = 1 млн * 64 * 2 * 4 = 512 МБ

Потребление памяти = 3072 + 512 = 3584 МБ

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

Использование индекса векторного сходства

Примечание

Чтобы использовать индексы векторного сходства, настройка compatibility должна быть равна '' (значение по умолчанию) или '25.1' либо новее.

Индексы векторного сходства поддерживают запросы SELECT следующего вида:

WITH [...] AS reference_vector
SELECT [...]
FROM table
WHERE [...] -- предложение WHERE необязательно
ORDER BY <DistanceFunction>(vectors, reference_vector)
LIMIT <N>

Оптимизатор запросов ClickHouse пытается сопоставить запрос с приведённым выше шаблоном и использовать доступные индексы векторного сходства. Запрос может использовать индекс векторного сходства только в том случае, если функция расстояния в запросе SELECT совпадает с функцией расстояния в определении индекса.

Продвинутые пользователи могут задать собственное значение настройки hnsw_candidate_list_size_for_search (также известной как гиперпараметр HNSW «ef_search»), чтобы настраивать размер списка кандидатов при выполнении поиска (например, SELECT [...] SETTINGS hnsw_candidate_list_size_for_search = <value>). Значение настройки по умолчанию, равное 256, хорошо работает в большинстве сценариев использования. Более высокие значения настройки обеспечивают лучшую точность ценой более низкой производительности.

Если запрос может использовать индекс векторного сходства, ClickHouse проверяет, что значение LIMIT <N>, указанное в запросах SELECT, находится в разумных пределах. Более точно, будет возвращена ошибка, если <N> больше значения настройки max_limit_for_vector_search_queries, по умолчанию равного 100. Слишком большие значения LIMIT могут замедлять поиск и обычно указывают на ошибку в использовании.

Чтобы проверить, использует ли запрос SELECT индекс векторного сходства, вы можете добавить к запросу префикс EXPLAIN indexes = 1.

В качестве примера, запрос

EXPLAIN indexes = 1
WITH [0.462, 0.084, ..., -0.110] AS reference_vec
SELECT id, vec
FROM tab
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 10;

может вернуть

    ┌─explain─────────────────────────────────────────────────────────────────────────────────────────┐
 1. │ Expression (Проекция имён)                                                                      │
 2. │   Limit (предварительный LIMIT (без OFFSET))                                                    │
 3. │     Sorting (Сортировка для ORDER BY)                                                              │
 4. │       Expression ((Перед ORDER BY + (Проекция + Преобразование имён столбцов в идентификаторы))) │
 5. │         ReadFromMergeTree (default.tab)                                                         │
 6. │         Индексы:                                                                                │
 7. │           PrimaryKey                                                                            │
 8. │             Условие: true                                                                     │
 9. │             Части: 1/1                                                                          │
10. │             Гранулы: 575/575                                                                   │
11. │           Skip                                                                                  │
12. │             Имя: idx                                                                           │
13. │             Описание: vector_similarity GRANULARITY 100000000                                │
14. │             Части: 1/1                                                                          │
15. │             Гранулы: 10/575                                                                    │
    └─────────────────────────────────────────────────────────────────────────────────────────────────┘

В этом примере 1 миллион векторов из набора данных dbpedia, каждый размерностью 1536, хранятся в 575 гранулах, т.е. примерно по 1,7 тыс. строк на гранулу. В запросе запрашиваются 10 соседей, и индекс векторного сходства находит этих 10 соседей в 10 отдельных гранулах. Эти 10 гранул будут прочитаны во время выполнения запроса.

Индексы векторного сходства используются, если вывод содержит Skip, а также имя и тип векторного индекса (в примере idx и vector_similarity). В этом случае индекс векторного сходства отбросил две из четырёх гранул, т.е. 50% данных. Чем больше гранул может быть отброшено, тем эффективнее используется индекс.

Совет

Чтобы принудительно использовать индекс, вы можете выполнить запрос SELECT с параметром force_data_skipping_indexes (укажите имя индекса в качестве значения параметра).

Постфильтрация и префильтрация

Пользователи могут дополнительно указать предложение WHERE с дополнительными условиями фильтрации для запроса SELECT. ClickHouse будет применять эти условия фильтрации, используя стратегию постфильтрации или префильтрации. Кратко, обе стратегии определяют порядок, в котором применяются фильтры:

Постфильтрация означает, что индекс векторного сходства применяется первым, после чего ClickHouse применяет дополнительные фильтры, указанные в предложении WHERE.
Префильтрация означает, что порядок применения фильтров будет обратным.

У стратегий разные компромиссы:

У постфильтрации есть типичная проблема: она может вернуть меньше строк, чем запрошено в предложении LIMIT <N>. Такая ситуация возникает, когда одна или несколько строк результата, возвращённых индексом векторного сходства, не удовлетворяют дополнительным фильтрам.
Префильтрация в целом остаётся нерешённой задачей. Некоторые специализированные векторные базы данных предоставляют алгоритмы префильтрации, но большинство реляционных баз данных (включая ClickHouse) будут переходить к точному поиску соседей, т.е. к полному перебору без индекса.

Используемая стратегия зависит от условия фильтрации.

Дополнительные фильтры являются частью ключа партиционирования

Если дополнительное условие фильтрации является частью ключа партиционирования, то ClickHouse применит отсечение партиций. В качестве примера, таблица разбита на диапазонные партиции по столбцу year, и выполняется следующий запрос:

WITH [0., 2.] AS reference_vec
SELECT id, vec
FROM tab
WHERE year = 2025
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3;

ClickHouse отбросит все партиции, кроме партиции за 2025 год.

Дополнительные фильтры, которые не могут быть выполнены по индексам

Если дополнительные условия фильтрации не могут быть выполнены по индексам (индекс по первичному ключу, пропускающий индекс), ClickHouse применит последующую фильтрацию.

Дополнительные фильтры могут оцениваться с использованием индекса первичного ключа

Если дополнительные условия фильтрации могут быть оценены с использованием первичного ключа (т. е. они образуют префикс первичного ключа) и

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

На практике второй вариант встречается довольно редко.

Дополнительные фильтры могут оцениваться с использованием skipping index

Если дополнительные условия фильтрации могут быть оценены с использованием skipping indexes (minmax index, set index и т. д.), ClickHouse выполняет постфильтрацию. В таких случаях индекс векторного сходства вычисляется первым, так как ожидается, что он отбросит наибольшее количество строк по сравнению с другими skipping indexes.

Для более тонкого управления постфильтрацией и предварительной фильтрацией можно использовать два параметра:

Параметр vector_search_filter_strategy (по умолчанию: auto, который реализует приведённые выше эвристики) может быть установлен в значение prefilter. Это полезно для принудительной предварительной фильтрации в случаях, когда дополнительные условия фильтрации обладают крайне высокой селективностью. Например, следующий запрос может выиграть от предварительной фильтрации:

SELECT bookid, author, title
FROM books
WHERE price < 2.00
ORDER BY cosineDistance(book_vector, getEmbedding('Книги о древних азиатских империях'))
LIMIT 10

Предположим, что только очень небольшое количество книг стоит меньше 2 долларов. В этом случае постфильтрация может вернуть ноль строк, потому что все 10 лучших совпадений, возвращённых векторным индексом, могут иметь цену выше 2 долларов. Принудительно включив префильтрацию (добавьте SETTINGS vector_search_filter_strategy = 'prefilter' к запросу), ClickHouse сначала находит все книги с ценой менее 2 долларов, а затем выполняет переборный (brute-force) векторный поиск по найденным книгам.

В качестве альтернативного подхода к решению указанной выше проблемы можно задать настройку vector_search_index_fetch_multiplier (по умолчанию: 1.0, максимум: 1000.0) значением > 1.0 (например, 2.0). Количество ближайших соседей, выбираемых из векторного индекса, умножается на значение этой настройки, после чего к этим строкам применяется дополнительный фильтр, чтобы вернуть количество строк, не превышающее значение LIMIT. Например, мы можем выполнить запрос ещё раз, но уже с множителем 3.0:

SELECT bookid, author, title
FROM books
WHERE price < 2.00
ORDER BY cosineDistance(book_vector, getEmbedding('Books on ancient Asian empires'))
LIMIT 10
SETTING vector_search_index_fetch_multiplier = 3.0;

ClickHouse извлечёт 3,0 x 10 = 30 ближайших соседей из векторного индекса в каждой части и затем применит дополнительные фильтры. Будут возвращены только десять ближайших соседей. Отметим, что настройка vector_search_index_fetch_multiplier может смягчить проблему, но в крайних случаях (при очень селективном условии WHERE) всё ещё возможно, что будет возвращено меньше N запрошенных строк.

Пересчёт оценок (rescoring)

Skip-индексы в ClickHouse обычно фильтруют данные на уровне гранул, то есть запрос к skip-индексу (внутренне) возвращает список потенциально подходящих гранул, что сокращает объём читаемых данных при последующем сканировании. Это хорошо работает для skip-индексов в целом, но в случае индексов векторного сходства создаётся «несоответствие гранулярности». Подробнее: индекс векторного сходства определяет номера строк N наиболее похожих векторов для заданного опорного вектора, но затем ему нужно сопоставить эти номера строк с номерами гранул. ClickHouse затем загрузит эти гранулы с диска и повторит вычисление расстояний для всех векторов в этих гранулах. Этот шаг называется пересчётом оценок (rescoring), и хотя теоретически он может повысить точность — помните, что индекс векторного сходства возвращает только приближённый результат, — очевидно, что с точки зрения производительности он не оптимален.

Поэтому ClickHouse предоставляет оптимизацию, которая отключает пересчёт оценок и возвращает наиболее похожие векторы и их расстояния напрямую из индекса. Эта оптимизация включена по умолчанию, см. настройку vector_search_with_rescoring. В общих чертах она работает так: ClickHouse делает доступными наиболее похожие векторы и их расстояния в виде виртуального столбца _distances. Чтобы увидеть это, выполните запрос векторного поиска с EXPLAIN header = 1:

EXPLAIN header = 1
WITH [0., 2.] AS reference_vec
SELECT id
FROM tab
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3
SETTINGS vector_search_with_rescoring = 0

Query id: a2a9d0c8-a525-45c1-96ca-c5a11fa66f47

    ┌─explain─────────────────────────────────────────────────────────────────────────────────────────────────┐
 1. │ Expression (Проекция имён)                                                                              │
 2. │ Header: id Int32                                                                                        │
 3. │   Limit (предварительный LIMIT (без OFFSET))                                                           │
 4. │   Header: L2Distance(__table1.vec, _CAST([0., 2.]_Array(Float64), 'Array(Float64)'_String)) Float64     │
 5. │           __table1.id Int32                                                                             │
 6. │     Sorting (Сортировка для ORDER BY)                                                                   │
 7. │     Header: L2Distance(__table1.vec, _CAST([0., 2.]_Array(Float64), 'Array(Float64)'_String)) Float64   │
 8. │             __table1.id Int32                                                                           │
 9. │       Expression ((До ORDER BY + (Проекция + Замена имён столбцов на идентификаторы столбцов)))        │
10. │       Header: L2Distance(__table1.vec, _CAST([0., 2.]_Array(Float64), 'Array(Float64)'_String)) Float64 │
11. │               __table1.id Int32                                                                         │
12. │         ReadFromMergeTree (default.tab)                                                                 │
13. │         Header: id Int32                                                                                │
14. │                 _distance Float32                                                                       │
    └─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Примечание

Запрос, выполняемый без повторной оценки (vector_search_with_rescoring = 0) и с включёнными параллельными репликами, может всё равно перейти к повторной оценке результатов.

Оптимизация производительности

Настройка сжатия

Практически во всех вариантах использования векторы в соответствующем столбце являются плотными и плохо сжимаются. В результате сжатие замедляет операции вставки данных во векторный столбец и чтения из него. Поэтому мы рекомендуем отключить сжатие. Для этого укажите CODEC(NONE) для векторного столбца следующим образом:

CREATE TABLE tab(id Int32, vec Array(Float32) CODEC(NONE), INDEX idx vec TYPE vector_similarity('hnsw', 'L2Distance', 2)) ENGINE = MergeTree ORDER BY id;

Настройка создания индексов

Жизненный цикл индексов векторного сходства привязан к жизненному циклу частей. Другими словами, всякий раз, когда создаётся новая часть с определённым индексом векторного сходства, создаётся и сам индекс. Обычно это происходит при вставке данных или во время слияний. К сожалению, HNSW известен длительным временем создания индексов, что может значительно замедлять вставки и слияния. Индексы векторного сходства оптимальны, когда данные неизменяемы или изменяются редко.

Для ускорения создания индексов можно использовать следующие приёмы:

Во-первых, создание индексов можно распараллелить. Максимальное количество потоков создания индексов настраивается с помощью серверного параметра max_build_vector_similarity_index_thread_pool_size. Для оптимальной производительности значение этого параметра следует устанавливать равным числу ядер CPU.

Во-вторых, для ускорения операторов INSERT пользователи могут отключить создание пропускающих индексов для вновь вставляемых частей при помощи параметра сессии materialize_skip_indexes_on_insert. SELECT-запросы к таким частям будут выполнять точный поиск. Поскольку вставляемые части, как правило, малы по сравнению с общим размером таблицы, ожидается, что влияние этого на производительность будет незначительным.

В-третьих, для ускорения слияний пользователи могут отключить создание пропускающих индексов на слитых частях с помощью параметра сессии materialize_skip_indexes_on_merge. В сочетании с оператором ALTER TABLE [...] MATERIALIZE INDEX [...] это обеспечивает явный контроль над жизненным циклом индексов векторного сходства. Например, создание индексов можно отложить до момента, когда весь объём данных уже принят, или до периода низкой нагрузки на систему, например на выходные.

Настройка использования индексов

Запросы SELECT должны загружать индексы векторного сходства в оперативную память, чтобы использовать их. Чтобы один и тот же индекс векторного сходства не загружался в оперативную память многократно, ClickHouse предоставляет специализированный кэш в оперативной памяти для таких индексов. Чем больше этот кэш, тем меньше будет лишних загрузок. Максимальный размер кэша можно настроить с помощью серверной настройки vector_similarity_index_cache_size. По умолчанию кэш может увеличиваться до 5 ГБ.

Примечание

Кэш индекса векторного сходства хранит гранулы векторного индекса. Если отдельные гранулы векторного индекса больше размера кэша, они не будут кэшироваться. Поэтому необходимо вычислить размер векторного индекса (на основе формулы из раздела «Оценка потребления хранилища и памяти» или system.data_skipping_indices) и задать размер кэша соответствующим образом.

Текущий размер кэша индекса векторного сходства отображается в system.metrics:

SELECT metric, value
FROM system.metrics
WHERE metric = 'VectorSimilarityIndexCacheBytes'

Информацию о попаданиях и промахах кэша для запроса с заданным идентификатором можно получить из system.query_log:

SYSTEM FLUSH LOGS query_log;

SELECT ProfileEvents['VectorSimilarityIndexCacheHits'], ProfileEvents['VectorSimilarityIndexCacheMisses']
FROM system.query_log
WHERE type = 'QueryFinish' AND query_id = '<...>'
ORDER BY event_time_microseconds;

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

Настройка квантования

Квантование — это метод уменьшения объёма памяти, занимаемой векторами, и вычислительных затрат на построение и обход векторных индексов. Векторные индексы ClickHouse поддерживают следующие варианты квантования:

Quantization	Name	Storage per dimension
f32	Single precision	4 bytes
f16	Half precision	2 bytes
bf16 (default)	Half precision (brain float)	2 bytes
i8	Quarter precision	1 byte
b1	Binary	1 bit

Квантование снижает точность векторного поиска по сравнению с поиском по исходным значениям с полной точностью с плавающей запятой (f32). Однако на большинстве наборов данных квантование в формате half-precision brain float (bf16) приводит к пренебрежимо малой потере точности, поэтому векторные индексы похожести по умолчанию используют именно этот метод квантования. Квантование до четверной точности (i8) и бинарное квантование (b1) приводят к заметной потере точности в векторном поиске. Мы рекомендуем эти варианты квантования только в том случае, если размер векторного индекса похожести значительно превышает доступный объём DRAM. В этом случае мы также рекомендуем включить пересчёт скоринга (vector_search_index_fetch_multiplier, vector_search_with_rescoring) для повышения точности. Бинарное квантование рекомендуется только для 1) нормализованных эмбеддингов (т.е. длина вектора = 1, модели OpenAI обычно нормализованы) и 2) если в качестве функции расстояния используется косинусное расстояние. Бинарное квантование на внутреннем уровне использует расстояние Хэмминга для построения и обхода графа близости. На этапе пересчёта скоринга используются исходные векторы с полной точностью, хранящиеся в таблице, для определения ближайших соседей по косинусному расстоянию.

Настройка передачи данных

Опорный вектор в запросе векторного поиска предоставляется пользователем и, как правило, получается путём вызова большой языковой модели (LLM). Типичный Python-код, выполняющий векторный поиск в ClickHouse, может выглядеть так:

search_v = openai_client.embeddings.create(input = "[Good Books]", model='text-embedding-3-large', dimensions=1536).data[0].embedding

params = {'search_v': search_v}
result = chclient.query(
   "SELECT id FROM items
    ORDER BY cosineDistance(vector, %(search_v)s)
    LIMIT 10",
    parameters = params)

Векторы встраивания (search_v в приведённом выше фрагменте) могут иметь очень большую размерность. Например, OpenAI предоставляет модели, которые генерируют векторы встраивания с размерностью 1536 или даже 3072. В приведённом выше коде драйвер ClickHouse для Python подставляет вектор встраивания, преобразуя его в человекочитаемую строку, и затем целиком отправляет запрос SELECT в виде строки. Предположим, что вектор встраивания состоит из 1536 значений с плавающей запятой одинарной точности, тогда длина отправляемой строки достигает 20 кБ. Это приводит к высокому использованию CPU на токенизацию, разбор и выполнение тысяч преобразований строки в число с плавающей запятой. Кроме того, требуется значительный объём места в файле журнала сервера ClickHouse, что также вызывает разрастание system.query_log.

Обратите внимание, что большинство LLM‑моделей возвращают вектор встраивания в виде списка или массива NumPy из нативных чисел с плавающей запятой. Поэтому мы рекомендуем Python‑приложениям привязывать параметр опорного вектора в бинарной форме, используя следующий стиль:

search_v = openai_client.embeddings.create(input = "[Хорошие книги]", model='text-embedding-3-large', dimensions=1536).data[0].embedding

params = {'$search_v_binary$': np.array(search_v, dtype=np.float32).tobytes()}
result = chclient.query(
   "SELECT id FROM items
    ORDER BY cosineDistance(vector, (SELECT reinterpret($search_v_binary$, 'Array(Float32)')))
    LIMIT 10",
    parameters = params)

В этом примере опорный вектор отправляется как есть в бинарном виде и на сервере интерпретируется как массив чисел с плавающей запятой. Это экономит процессорное время на стороне сервера и предотвращает избыточный рост серверных логов и system.query_log.

Администрирование и мониторинг

Объём на диске индексов векторного сходства можно получить из system.data_skipping_indices:

SELECT database, table, name, formatReadableSize(data_compressed_bytes)
FROM system.data_skipping_indices
WHERE type = 'vector_similarity';

Пример результата:

┌─database─┬─table─┬─name─┬─formatReadab⋯ssed_bytes)─┐
│ default  │ tab   │ idx  │ 348.00 MB                │
└──────────┴───────┴──────┴──────────────────────────┘

Отличия от обычных пропускающих индексов

Как и все обычные пропускающие индексы, индексы векторного сходства строятся поверх гранул, и каждый индексируемый блок состоит из GRANULARITY = [N] гранул ([N] = 1 по умолчанию для обычных пропускающих индексов). Например, если гранулярность первичного индекса таблицы равна 8192 (параметр index_granularity = 8192) и GRANULARITY = 2, то каждый индексируемый блок будет содержать 16384 строки. Однако структуры данных и алгоритмы для поиска приблизительных соседей по своей природе ориентированы на строки. Они хранят компактное представление набора строк, а также возвращают строки в ответ на запросы векторного поиска. Это приводит к довольно неочевидным отличиям в поведении индексов векторного сходства по сравнению с обычными пропускающими индексами.

Когда пользователь определяет индекс векторного сходства по столбцу, ClickHouse внутренне создает для каждого индексного блока отдельный «подиндекс» векторного сходства. Подиндекс является «локальным» в том смысле, что он знает только о строках своего индексного блока. В предыдущем примере, при условии, что столбец содержит 65536 строк, мы получаем четыре индексных блока (охватывающих восемь гранул) и подиндекс векторного сходства для каждого индексного блока. Теоретически подиндекс может напрямую возвращать строки с N ближайшими точками в пределах своего индексного блока. Однако, поскольку ClickHouse загружает данные с диска в память на уровне гранул, подиндексы расширяют найденные строки до границ гранул. Это отличается от обычных пропускающих индексов, которые пропускают данные на уровне индексных блоков.

Параметр GRANULARITY определяет, сколько подиндексов векторного сходства создаётся. Большие значения GRANULARITY означают меньшее количество, но более крупные подиндексы векторного сходства, вплоть до ситуации, когда столбец (или часть данных столбца) имеет только один подиндекс. В этом случае подиндекс имеет «глобальное» представление обо всех строках столбца и может напрямую вернуть все гранулы столбца (части) с релевантными строками (таких гранул не более LIMIT [N]). На втором шаге ClickHouse загрузит эти гранулы и определит действительно лучшие строки, выполнив расчёт расстояний полным перебором (brute-force) по всем строкам гранул. При небольшом значении GRANULARITY каждый из подиндексов возвращает до LIMIT N гранул. В результате требуется загрузить и дополнительно отфильтровать больше гранул. Обратите внимание, что точность поиска в обоих случаях одинаково высока, различается только производительность обработки. Обычно рекомендуется использовать большое значение GRANULARITY для индексов векторного сходства и переходить к меньшим значениям GRANULARITY только в случае проблем, например чрезмерного потребления памяти структурами векторного сходства. Если GRANULARITY для индексов векторного сходства не задан, значение по умолчанию — 100 миллионов.

Пример

CREATE TABLE tab(id Int32, vec Array(Float32), INDEX idx vec TYPE vector_similarity('hnsw', 'L2Distance', 2)) ENGINE = MergeTree ORDER BY id;

INSERT INTO tab VALUES (0, [1.0, 0.0]), (1, [1.1, 0.0]), (2, [1.2, 0.0]), (3, [1.3, 0.0]), (4, [1.4, 0.0]), (5, [1.5, 0.0]), (6, [0.0, 2.0]), (7, [0.0, 2.1]), (8, [0.0, 2.2]), (9, [0.0, 2.3]), (10, [0.0, 2.4]), (11, [0.0, 2.5]);

WITH [0., 2.] AS reference_vec
SELECT id, vec
FROM tab
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3;

возвращает

   ┌─id─┬─vec─────┐
1. │  6 │ [0,2]   │
2. │  7 │ [0,2.1] │
3. │  8 │ [0,2.2] │
   └────┴─────────┘

Дополнительные наборы данных, использующие приблизительный векторный поиск:

Квантованный бит (QBit)

Experimental feature. Learn more.

Один из распространённых подходов к ускорению точного векторного поиска — использовать менее точный тип данных float. Например, если векторы хранятся как Array(BFloat16) вместо Array(Float32), размер данных уменьшается вдвое, и ожидается, что время выполнения запросов сократится пропорционально. Этот метод называется квантизацией. Хотя он ускоряет вычисления, точность результатов может снижаться, даже при полном переборе всех векторов.

При традиционной квантизации точность теряется как во время поиска, так и при хранении данных. В приведённом выше примере мы бы хранили BFloat16 вместо Float32, что означает невозможность выполнения более точного поиска в будущем, даже если это потребуется. Один из альтернативных подходов — хранить две копии данных: квантованную и с полной точностью. Хотя это работает, такой подход требует избыточного объёма хранилища. Рассмотрим сценарий, когда исходные данные имеют тип Float64, и нам нужно выполнять поиск с различной точностью (16-битной, 32-битной или полной 64-битной). В этом случае нам пришлось бы хранить три отдельные копии данных.

ClickHouse предлагает тип данных Quantized Bit (QBit), который устраняет эти ограничения за счёт:

Хранения исходных данных с полной точностью.
Возможности указания точности квантизации на этапе выполнения запроса.

Это достигается за счёт хранения данных в формате с побитовой группировкой (то есть все i-е биты всех векторов хранятся вместе), что позволяет выполнять чтение только с запрошенным уровнем точности. Вы получаете выигрыш в скорости за счёт сокращения объёма операций ввода-вывода и вычислений благодаря квантизации, при этом все исходные данные остаются доступными при необходимости. При выборе максимальной точности поиск становится точным.

Примечание

Тип данных QBit и связанные с ним функции вычисления расстояния в настоящее время являются экспериментальными. Чтобы их включить, выполните SET allow_experimental_qbit_type = 1. Если вы столкнулись с проблемами, пожалуйста, создайте issue в репозитории ClickHouse.

Чтобы объявить столбец типа QBit, используйте следующий синтаксис:

column_name QBit(element_type, dimension)

Где:

element_type – тип каждого элемента вектора. Поддерживаемые типы: BFloat16, Float32 и Float64
dimension – количество элементов в каждом векторе

Создание таблицы `QBit` и добавление данных

CREATE TABLE fruit_animal (
    word String,
    vec QBit(Float64, 5)
) ENGINE = MergeTree
ORDER BY word;

INSERT INTO fruit_animal VALUES
    ('apple', [-0.99105519, 1.28887844, -0.43526649, -0.98520696, 0.66154391]),
    ('banana', [-0.69372815, 0.25587061, -0.88226235, -2.54593015, 0.05300475]),
    ('orange', [0.93338752, 2.06571317, -0.54612565, -1.51625717, 0.69775337]),
    ('dog', [0.72138876, 1.55757105, 2.10953259, -0.33961248, -0.62217325]),
    ('cat', [-0.56611276, 0.52267331, 1.27839863, -0.59809804, -1.26721048]),
    ('horse', [-0.61435682, 0.48542571, 1.21091247, -0.62530446, -1.33082533]);

Векторный поиск с `QBit`

Найдём ближайших соседей к вектору, соответствующему слову «lemon», используя L2-расстояние. Третий параметр в функции расстояния задаёт точность в битах: более высокие значения обеспечивают большую точность, но требуют больше вычислительных ресурсов.

Все доступные функции расстояния для QBit можно найти здесь.

Поиск с полной точностью (64-битной):

SELECT
    word,
    L2DistanceTransposed(vec, [-0.88693672, 1.31532824, -0.51182908, -0.99652702, 0.59907770], 64) AS distance
FROM fruit_animal
ORDER BY distance;

   ┌─word───┬────────────distance─┐
1. │ apple  │ 0.14639757188169716 │
2. │ banana │   1.998961369007679 │
3. │ orange │   2.039041552613732 │
4. │ cat    │   2.752802631487914 │
5. │ horse  │  2.7555776805484813 │
6. │ dog    │   3.382295083120104 │
   └────────┴─────────────────────┘

Поиск с уменьшенной точностью:

SELECT
    word,
    L2DistanceTransposed(vec, [-0.88693672, 1.31532824, -0.51182908, -0.99652702, 0.59907770], 12) AS distance
FROM fruit_animal
ORDER BY distance;

   ┌─word───┬───────────distance─┐
1. │ apple  │  0.757668703053566 │
2. │ orange │ 1.5499475034938677 │
3. │ banana │ 1.6168396735102937 │
4. │ cat    │  2.429752230904804 │
5. │ horse  │  2.524650475528617 │
6. │ dog    │   3.17766975527459 │
   └────────┴────────────────────┘

Обратите внимание, что с 12-битной квантизацией мы получаем хорошее приближение расстояний при более быстром выполнении запросов. Относительный порядок в целом сохраняется: 'apple' по‑прежнему является ближайшим совпадением.

Примечание

В текущей реализации ускорение достигается за счёт уменьшения I/O, так как мы читаем меньше данных. Если исходные данные были «широкими», например Float64, выбор меньшей точности всё равно приведёт к вычислению расстояния по данным той же ширины — только с меньшей точностью.

Соображения по производительности

Производительность QBit повышается за счёт сокращения операций I/O, поскольку при использовании меньшей точности из хранилища нужно читать меньше данных. Кроме того, когда QBit содержит данные типа Float32 и параметр точности равен 16 или меньше, появляется дополнительное преимущество за счёт уменьшения объёма вычислений. Параметр точности напрямую управляет компромиссом между точностью и скоростью:

Более высокая точность (ближе к исходной разрядности данных): более точные результаты, более медленные запросы
Низкая точность: более быстрые запросы с приближёнными результатами, уменьшенное использование памяти

Ссылки

Блоги:

Точный поиск по векторам​

Пример​

Приблизительный векторный поиск​

Индексы сходства векторов​

Создание индекса сходства векторов​

Использование индекса векторного сходства​

Оптимизация производительности​

Администрирование и мониторинг​

Отличия от обычных пропускающих индексов​

Пример​

Квантованный бит (QBit)​

Создание таблицы QBit и добавление данных​

Векторный поиск с QBit​

Соображения по производительности​

Ссылки​

Точный поиск по векторам

Пример

Приблизительный векторный поиск

Индексы сходства векторов

Создание индекса сходства векторов

Использование индекса векторного сходства

Оптимизация производительности

Администрирование и мониторинг

Отличия от обычных пропускающих индексов

Пример

Квантованный бит (QBit)

Создание таблицы `QBit` и добавление данных

Векторный поиск с `QBit`

Соображения по производительности

Ссылки