Vector нагрузка

Позволяет тестировать производительность и полноту векторного поиска YDB с помощью точного и приближённого поиска. Поддерживается тестирование обычных векторных индексов и векторных индексов с фильтрацией.

Нагрузка позволяет загружать векторы из реального датасета (например, Wikipedia embeddings) или генерировать случайные синтетические векторы. После загрузки данных можно построить векторный индекс, запустить поисковые запросы для измерения полноты и производительности и очистить таблицы нагрузки.

Структура команды

ydb [global options...] workload vector [options...] <subcommand>

Подкоманды:

vector                YDB vector workload.
├─ init                 Инициализация таблиц для нагрузки
├─ import               Загрузка данных в таблицы нагрузки
│   ├─ files              Импорт векторов из файлов
│   └─ generator          Генерация случайных векторов
├─ build-index          Создание и инициализация векторного индекса
├─ drop-index           Удаление векторного индекса
├─ run                  Запуск нагрузки
│   ├─ select            Поиск векторов и измерение производительности/полноты
│   └─ upsert            Вставка или обновление строк с векторами
└─ clean                Удаление таблиц, созданных для нагрузочного тестирования

Инициализация нагрузки

Создайте таблицу для нагрузочного тестирования:

ydb workload vector init

Доступные параметры

Создаваемая таблица имеет следующую схему:

• id Uint64 NOT NULL — первичный ключ;
• embedding String — сериализованный вектор-эмбеддинг;
• prefix Uint64 NOT NULL (только при указании --prefixed) — столбец фильтра для prefixed-индексов.

Загрузка данных

После инициализации загрузите данные в таблицу. Доступны две подкоманды: files — для импорта векторов из готового датасета, и generator — для генерации синтетических случайных векторов.

После завершения импорта автоматически строится векторный индекс с именем index по столбцу embedding (если не указано --index-type None).

Импорт из файлов

Импорт векторов из файлов (CSV, TSV или Parquet, возможно в сжатом формате gzip). Датасет должен содержать столбцы id и embedding. Дополнительные столбцы игнорируются.

В файлах CSV/TSV эмбеддинги должны быть представлены в виде списка чисел с плавающей точкой, например "[ 1.0, 2.0, 3.0 ]". В файлах Parquet эмбеддинги могут быть как списком float32, так и уже сериализованными бинарными эмбеддингами YDB.

Пример запуска:

ydb workload vector import files

Доступные параметры

Общие параметры команды import

Генерация синтетических данных

Генерация случайных векторов и загрузка их в таблицу. Компоненты векторов выбираются из равномерного распределения и сериализуются в бинарный формат эмбеддингов YDB.

ydb workload vector import generator

Доступные параметры

Общие параметры команды import

Построение векторного индекса

Если данные загружались с параметром --index-type None, или если нужно построить дополнительный индекс с другими параметрами, векторный индекс можно построить на существующей таблице командой build-index.

ydb workload vector build-index --distance cosine

Доступные параметры

Удаление векторного индекса

Удаление ранее созданного векторного индекса.

ydb workload vector drop-index

Доступные параметры

Запуск нагрузки

Запустите нагрузочное тестирование в одном из двух режимов: select (векторный поиск) или upsert (вставка новых векторов).

Нагрузочное тестирование поисковых запросов

Выполняет запросы векторного поиска к индексированной таблице. Опционально измеряет полноту, сравнивая результаты приближённого поиска с точным (полным перебором), затем выполняет замер производительности.

ydb workload vector run select --recall

Доступные параметры

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

Нагрузочное тестирование на запись

Непрерывно вставляет новые строки с векторами в таблицу, генерируя случайные эмбеддинги «на лету».

ydb workload vector run upsert

Доступные параметры

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

Очистка данных

Удаление таблиц, созданных для нагрузочного тестирования:

ydb workload vector clean

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

Режим run select выполняет следующие шаги:

1. Формируется тестовая выборка:
   • Если задана таблица с тестовой выборкой (--query-table), из неё выбираются первые --targets записей по порядку первичного ключа.
   • В противном случае выбираются случайные --targets записей из основной таблицы.
2. Производится оценка полноты (если указан --recall):
   • Для каждого элемента тестовой выборки запускается по два запроса.
   • Первый запрос — точный векторный поиск (полный перебор) по близости к векторной колонке, формируя эталонное множество результатов R_exact.
   • Второй запрос — приближённый векторный поиск на основе векторного индекса, получая множество результатов R_approx.
   • Если выбран индекс с фильтрацией, то оба поиска проводятся только среди записей с соответствующими значениями колонок фильтров.
   • Вычисляется полнота приближённого поиска по формуле $\frac{|R_{approx} \bigcap R_{exact}|}{|R_{exact}|}$ (здесь |A| — число элементов в множестве A, а A ∩ B — пересечение множеств A и B).
3. Производится оценка скорости:
   • В течение заданного времени и в заданное число параллельных потоков запускаются запросы поиска по индексу.
   • Каждый запрос запускается для случайного элемента тестовой выборки.
   • Вычисляется средняя производительность (RPS) и время ответа на разных квантилях.

Примеры использования

Пример с генерируемыми данными

1. Инициализируйте таблицу для нагрузочного тестирования:

   ydb workload vector init
   

2. Сгенерируйте и загрузите синтетические векторы:

   ydb workload vector import generator --rows 100000 --distance cosine
   

3. Запустите нагрузку на поиск:

   ydb workload vector run select --recall
   

   Пример вывода:

   Recall: 0.8950
   Window      Txs Txs/Sec Retries Errors  p50(ms) p95(ms) p99(ms) pMax(ms)
   1            100 100     0       0       5       8       12      15
   2             98 98      0       0       5       9       13      16
   ...
   
   Total       Txs Txs/Sec Retries Errors  p50(ms) p95(ms) p99(ms) pMax(ms)
   10          980 98.0    0       0       5       9       14      18
   

   Описание колонок:

   • Window — Порядковый номер временного окна (например, каждая секунда или фиксированный интервал).
   • Txs — Количество успешно выполненных транзакций в данном окне (или общее количество по всем окнам в итоговой строке).
   • Txs/Sec — Количество транзакций в секунду для данного окна (или среднее значение для итоговой строки).
   • Retries — Количество автоматических повторных попыток из-за временных ошибок (например, конфликтов или троттлинга).
   • Errors — Количество неисправимых ошибок.
   • p50(ms) — Медианная (50-й перцентиль) задержка выполнения транзакции в миллисекундах.
   • p95(ms) — Задержка на уровне 95-го перцентиля (миллисекунды).
   • p99(ms) — Задержка на уровне 99-го перцентиля (миллисекунды).
   • pMax(ms) — Максимальная наблюдаемая задержка в пределах окна (или глобальный максимум для итоговой строки).

4. Запустите нагрузку на запись:

   ydb workload vector run upsert
   

5. Удаление таблиц, созданных для нагрузочного тестирования:

   ydb workload vector clean
   

Пример с внешним датасетом

1. Подготовьте таблицы и загрузите данные. Пример создания таблицы и загрузки данных приведён в рецепте Векторный индекс с загрузкой внешнего набора данных.

   Примеры создания векторных индексов доступны на странице документации Векторные индексы.

2. Запустите нагрузку на поиск:

   ydb -e grpc://hostname:2135 -d /Root/testdb workload vector run select \
       --table wikipedia --index idx_vector \
       --query-table wikipedia_sample --recall
   

   Пример вывода:

   Recall: 0.8950
   Window      Txs Txs/Sec Retries Errors  p50(ms) p95(ms) p99(ms) pMax(ms)
   1            100 100     0       0       5       8       12      15
   2             98 98      0       0       5       9       13      16
   ...
   
   Total       Txs Txs/Sec Retries Errors  p50(ms) p95(ms) p99(ms) pMax(ms)
   10          980 98.0    0       0       5       9       14      18
   

Примечания

• Поисковая нагрузка генерирует SQL-запросы выборки ближайших строк по векторному расстоянию из таблицы --table по индексу --index.
• Указывать названия колонок (векторной, фильтра, первичного ключа) и функцию расстояния не нужно — они извлекаются автоматически из определения индекса.
• Случайный выбор тестовых векторов из таблицы --table работает только в том случае, если первичный ключ таблицы — целочисленный.
• Если используется --query-table, в обеих таблицах имена векторной колонки и колонки фильтра должны совпадать.
• Оценка полноты поиска (--recall) проводится отдельным этапом перед тестированием производительности и показывает среднюю долю совпадения результатов поиска по индексу и полным перебором (от 0 до 1).

Подготовка тестовой выборки из большой таблицы

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

CREATE TABLE vector_index_sample (
    id Uint64 NOT NULL,
    prefix Uint64 NOT NULL,
    embedding String NOT NULL,
    PRIMARY KEY (id)
);

Наполнение таблицы случайной выборкой приблизительно 1000 строк из большой таблицы:

INSERT INTO vector_index_sample
SELECT id, prefix, embedding FROM large_table
WHERE RandomNumber(id) < 0xFFFFFFFFFFFFFFFF / <число_строк_в_таблице> * 1000;