--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ydb.tech/docs/en/reference/ydb-cli/workload-fulltext.md?version=main - https://ydb.tech/docs/ru/reference/ydb-cli/workload-fulltext.md?version=main sourcePath: ru/core/reference/ydb-cli/workload-fulltext.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Fulltext нагрузка Позволяет тестировать производительность [полнотекстового поиска](https://ydb.tech/docs/ru/concepts/query_execution/fulltext_search.md?version=main) YDB на документных наборах данных. Поддерживает как реальные датасеты (например, [MS MARCO](https://microsoft.github.io/msmarco/TREC-Deep-Learning-2022)), так и синтетически сгенерированный текст при помощи [цепи Маркова](https://ru.wikipedia.org/wiki/Цепь_Маркова). Марковская модель считает, что каждое следующее слово зависит от одного или нескольких предыдущих. Количество предыдущих слов, на основании которых определяется следующее, называется порядком модели. Сначала мы используем обычный генератор случайных чисел с равномерным распределением, чтобы определить длину текста, который будем генерировать. Далее при помощи марковской модели генерируем слово за словом, пока не наберём нужное количество слов. Такое построение данных необходимо, чтобы текст был похож на какой-то реальный человеческий текст, а не представлял собой просто беспорядочный набор букв. Марковская модель может использоваться для: - [генерации текстов документов](#load-generator), которые хранятся в базе данных; - [генерации поисковых запросов (select)](#run-select); - [генерации запросов на запись (upsert)](#run-upsert). ## Структура команды {#structure} ```bash ydb [global options...] workload fulltext [options...] ``` Подкоманды: ```text fulltext YDB fulltext workload ├─ init Инициализация таблиц для нагрузки ├─ import Загрузка данных и построение полнотекстового индекса │ ├─ files Импорт данных из файлов │ └─ generator Генерация случайного текста с помощью модели цепи Маркова ├─ run Запуск нагрузки │ ├─ select Поиск документов с помощью полнотекстовых запросов │ └─ upsert Вставка или обновление документов в таблице ├─ clean Удаление таблиц, созданных для нагрузочного тестирования └─ model Построение модели цепи Маркова из текстового датасета ``` ## Общие параметры команд {#common-options} Все команды поддерживают следующий параметр: | Имя | Описание | Значение по умолчанию | |---|---|---| | `--path` или `-p` | Путь в базе данных, по которому будут созданы таблицы нагрузки. | `fulltext_workload` | ## Инициализация нагрузки {#init} Создайте таблицы для нагрузочного тестирования: ```bash ydb workload fulltext init ``` ### Доступные параметры {#init-options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--min-partitions <значение>` | Минимальное количество партиций таблицы. | `40` | | `--partition-size <значение>` | Целевой размер партиции, в МБ. | `2000` | | `--auto-partition <значение>` | Включить автопартицирование по нагрузке (`1` — включено, `0` — выключено). | `1` | | `--clear` | Удалить и пересоздать таблицу, если она уже существует. | | ## Загрузка данных {#load} После инициализации загрузите данные в таблицы и постройте полнотекстовый индекс. Доступны две подкоманды: `files` — для импорта из готового датасета, и `generator` — для генерации синтетических данных. После завершения импорта автоматически строится полнотекстовый индекс с именем `index` по столбцу `text`. ### Импорт из файлов {#load-files} Импорт документов из файлов (CSV, TSV или Parquet, возможно в сжатом формате gzip). Датасет должен содержать столбцы `id` и `text`. Для хранения колонки `id` внутри таблицы используется тип Uint64, для хранения колонки `text` используется тип String. Пример запуска: ```bash ydb workload fulltext import files ``` #### Доступные параметры {#load-files-options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--input <путь>` или `-i <путь>` | Путь к файлу или директории с датасетом. Поддерживаемые форматы: CSV/TSV (с опциональным gzip-сжатием), Parquet. Импортируются только столбцы `id` и `text`. | Обязательный | ### Общие параметры команды import {#load_options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--upload-threads <значение>` или `-t <значение>` | Количество потоков исполнения для подготовки данных. | Рассчитывается автоматически и равно числу доступных ядер на клиентской машине. | | `--bulk-size <значение>` | Размер порции для отправки данных в строках. | 10000 | | `--max-in-flight <значение>` | Максимальное количество порций данных, одновременно находящихся в обработке. | 128 | | `--file-output-path <значение>` или `-f <путь>` | Если эта опция установлена, данные не будут загружены в базу данных, а будут сохранены в каталоге <путь>. | | ### Генерация синтетических данных {#load-generator} Генерация случайного текста с помощью модели цепи Маркова и загрузка его в таблицу. Перед использованием необходимо [построить модель](#model) или загрузить готовую. - Чтобы загрузить уже готовую модель: ```bash wget https://storage.yandexcloud.net/ydb-public/markov_dict.tsv.gz ``` - Сделать свою модель из данных wikipedia: ```python from datasets import load_dataset ds = load_dataset( "rumbleFTW/wikipedia-20220301-en-raw", split="train[:1000000]", streaming=False, ) ds.to_csv('wikipedia_sample.csv.gz', compression='gzip', index=False) ``` Марковская модель считает что каждое следующее слово зависит от одного или нескольких предыдущих, количество предыдущих слов на основании которого определяется следующее, называется порядком модели. Сначала мы используем обычный случайный генератор с равномерным распределением, чтобы определить длину текста в диапазоне от `--min-sentence-len` до `--max-sentence-len`, который будем генерировать далее при помощью марковской модели слово за словом, пока не наберем нужное количество слов. Такое построение данных необходимо чтобы текст был похож на какой то реальный человеческий текст, а не был просто беспорядочным набором букв. ```bash ydb workload fulltext import generator ``` #### Доступные параметры {#load-generator-options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--model <путь>` или `-m <путь>` | Путь к файлу модели цепи Маркова (`.tsv.gz`). | Обязательный | | `--rows <значение>` | Количество строк для генерации. | `100000` | | `--min-sentence-len <значение>` | Минимальное количество слов в генерируемом документе. | `100` | | `--max-sentence-len <значение>` | Максимальное количество слов в генерируемом документе. | `1000` | При генерации текста параметры `--min-sentence-len` и `--max-sentence-len` используются для того чтобы случайно сгенерировать целевую длину текста, для генерации используется равномерное распределение. ### Общие параметры команды import {#load_options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--upload-threads <значение>` или `-t <значение>` | Количество потоков исполнения для подготовки данных. | Рассчитывается автоматически и равно числу доступных ядер на клиентской машине. | | `--bulk-size <значение>` | Размер порции для отправки данных в строках. | 10000 | | `--max-in-flight <значение>` | Максимальное количество порций данных, одновременно находящихся в обработке. | 128 | | `--file-output-path <значение>` или `-f <путь>` | Если эта опция установлена, данные не будут загружены в базу данных, а будут сохранены в каталоге <путь>. | | ## Запуск нагрузки {#run} Запустите нагрузочное тестирование в одном из двух режимов: `select` (полнотекстовый поиск) или `upsert` (вставка новых документов). ### Нагрузочное тестирование поисковых запросов {#run-select} Выполняет полнотекстовые поисковые запросы к индексированной таблице. Запросы могут генерироваться при помощи цепи Маркова или считываться из заранее загруженной таблицы запросов. ```bash ydb workload fulltext run select --model markov_dict.tsv.gz ``` #### Доступные параметры {#run-select-options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--model <путь>` или `-m <путь>` | Путь к файлу модели цепи Маркова (`.tsv.gz`) для генерации запросов. Необходимо указать либо `--model`, либо `--query-table`. | | | `--query-table <имя>` | Имя таблицы с заранее загруженными запросами. Таблица должна содержать столбец `query`. Необходимо указать либо `--model`, либо `--query-table`. | | | `--index-name <имя>` | Имя полнотекстового индекса для использования. | `index` | | `--min-query-len <значение>` | Минимальное количество слов в генерируемом запросе. | `1` | | `--max-query-len <значение>` | Максимальное количество слов в генерируемом запросе. | `5` | | `--top-size <значение>` | Количество строк для выборки из таблицы при формировании набора слов для запросов. | `1000` | | `--limit <значение>` | Ограничение количества результатов на запрос. `0` — без ограничения. | `0` | ### Общие параметры для всех видов нагрузки {#run_options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--dry-run` | Не выполнять инициализационные запросы, а только вывести их текст. | | | `--check-canonical` или `-c` | Использовать специальную версию запросов (они имеют детерминированные ответы) и сверять результаты с каноническими. | | | `--output <значение>` | Имя файла, в котором будут сохранены результаты выполнения запросов. | `results.out` | | `--iterations <значение>` | Количество выполнений каждого из запросов нагрузки. | `1` | | `--json <имя>` | Имя файла, в котором будет сохранена статистика выполнения запросов в формате `json`. | Файл не сохраняется | | `--ministat <имя>` | Имя файла, в котором будет сохранена статистика выполнения запросов в формате `ministat`. | Файл не сохраняется | | `--csv <имя>` | Имя файла для сохранения CSV-версии таблицы с результатами. | Файл не сохраняется | | `--plan <имя>` | Имя файла для сохранения плана запроса. Если задано, то сохраняются файлы `<имя>.<номер запроса>.explain` и `<имя>.<номер запроса>.<номер итерации>` с планами в нескольких форматах: `ast`, `json`, `svg` и `table`. | Планы не сохраняются. | | `--query-prefix <префикс>` | Префикс запроса. Каждый префикс будет добавлен отдельной строкой в начало каждого запроса. Если нужно указать несколько префиксов, используйте параметр несколько раз. | По умолчанию не задан | | `--retries` | Количество повторных попыток выполнения каждого запроса | `0` | | `--include` | Имена, номера или диапазоны номеров запросов, которые нужно выполнить в рамках нагрузки. Указываются через запятую, например: `1,2,4-6`. | Все запросы | | `--exclude` | Имена, номера или диапазоны номеров запросов, которые нужно исключить из нагрузки. Указываются через запятую, например: `1,2,4-6`. | | | `--verbose` или `-v` | Выводить больше информации на экран в процессе выполнения запросов. | | | `--global-timeout <значение>` | Общий таймаут на выполнение всех запросов. Задаётся в текстовом формате, например: `0.5s`, `1m`, `100us` и т.д. | Отсутствует. Время не ограничено. | | `--request-timeout <значение>` | Таймаут на выполнение каждой итерации каждого запроса. Задаётся в текстовом формате, например: `0.5s`, `1m`, `100us` и т.д. | Отсутствует. Время не ограничено. | | `--threads <значение>` или `-t <значение>` | Количество потоков, генерирующих нагрузку. Ноль означает, что запросы будут выполняться в основном потоке; при ином значении запросы будут перемешаны. | `0` | | `--stats <значение>` | Режим сбора расширенной статистики выполнения. Возможные значения: `full`, `profile`. | `full` | ### Нагрузочное тестирование на запись {#run-upsert} Непрерывно вставляет новые документы в таблицу, генерируя текст с помощью модели цепи Маркова. ```bash ydb workload fulltext run upsert --model markov_dict.tsv.gz ``` #### Доступные параметры {#run-upsert-options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--model <путь>` или `-m <путь>` | Путь к файлу модели цепи Маркова (`.tsv.gz`). | Обязательный | | `--index-name <имя>` | Имя полнотекстового индекса для использования. | `index` | | `--bulk-size <значение>` | Количество строк в одном пакете upsert. | `100` | | `--min-sentence-len <значение>` | Минимальное количество слов в генерируемом документе. | `100` | | `--max-sentence-len <значение>` | Максимальное количество слов в генерируемом документе. | `1000` | ### Общие параметры для всех видов нагрузки {#run_options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--dry-run` | Не выполнять инициализационные запросы, а только вывести их текст. | | | `--check-canonical` или `-c` | Использовать специальную версию запросов (они имеют детерминированные ответы) и сверять результаты с каноническими. | | | `--output <значение>` | Имя файла, в котором будут сохранены результаты выполнения запросов. | `results.out` | | `--iterations <значение>` | Количество выполнений каждого из запросов нагрузки. | `1` | | `--json <имя>` | Имя файла, в котором будет сохранена статистика выполнения запросов в формате `json`. | Файл не сохраняется | | `--ministat <имя>` | Имя файла, в котором будет сохранена статистика выполнения запросов в формате `ministat`. | Файл не сохраняется | | `--csv <имя>` | Имя файла для сохранения CSV-версии таблицы с результатами. | Файл не сохраняется | | `--plan <имя>` | Имя файла для сохранения плана запроса. Если задано, то сохраняются файлы `<имя>.<номер запроса>.explain` и `<имя>.<номер запроса>.<номер итерации>` с планами в нескольких форматах: `ast`, `json`, `svg` и `table`. | Планы не сохраняются. | | `--query-prefix <префикс>` | Префикс запроса. Каждый префикс будет добавлен отдельной строкой в начало каждого запроса. Если нужно указать несколько префиксов, используйте параметр несколько раз. | По умолчанию не задан | | `--retries` | Количество повторных попыток выполнения каждого запроса | `0` | | `--include` | Имена, номера или диапазоны номеров запросов, которые нужно выполнить в рамках нагрузки. Указываются через запятую, например: `1,2,4-6`. | Все запросы | | `--exclude` | Имена, номера или диапазоны номеров запросов, которые нужно исключить из нагрузки. Указываются через запятую, например: `1,2,4-6`. | | | `--verbose` или `-v` | Выводить больше информации на экран в процессе выполнения запросов. | | | `--global-timeout <значение>` | Общий таймаут на выполнение всех запросов. Задаётся в текстовом формате, например: `0.5s`, `1m`, `100us` и т.д. | Отсутствует. Время не ограничено. | | `--request-timeout <значение>` | Таймаут на выполнение каждой итерации каждого запроса. Задаётся в текстовом формате, например: `0.5s`, `1m`, `100us` и т.д. | Отсутствует. Время не ограничено. | | `--threads <значение>` или `-t <значение>` | Количество потоков, генерирующих нагрузку. Ноль означает, что запросы будут выполняться в основном потоке; при ином значении запросы будут перемешаны. | `0` | | `--stats <значение>` | Режим сбора расширенной статистики выполнения. Возможные значения: `full`, `profile`. | `full` | ## Построение модели цепи Маркова {#model} Перед использованием генератора или режимов `run upsert` / `run select` с генерируемыми запросами необходимо построить модель цепи Маркова из текстового датасета. Модель фиксирует вероятности переходов между словами и используется для генерации реалистичного текста. ```bash ydb workload fulltext model --input wikipedia_sample.csv.gz --output markov_dict.tsv.gz --order 3 ``` ### Доступные параметры {#model-options} | Имя | Описание | Значение по умолчанию | |---|---|---| | `--input <путь>` или `-i <путь>` | Путь к файлу или директории с датасетом. Поддерживаемые форматы: `.csv[.gz]`, `.tsv[.gz]`. Файл должен содержать столбец `text`. | Обязательный | | `--output <путь>` или `-o <путь>` | Путь к выходному файлу словаря модели. | `markov_dict.tsv.gz` | | `--order <значение>` или `-n <значение>` | Порядок цепи Маркова (размер контекста n-граммы). Порядок 1 использует контекст из одного слова для предсказания следующего слова, порядок 2 из двух слов и т.д. Допустимые значения: от 1 до 5. | `1` | Параметр `--order` задаёт количество предыдущих слов, на основании которых принимается решение о том, какое слово выбрать следующим. Обычно этот параметр принимает значения от 1 до 5: меньшие значения приводят к более случайным текстам, а большие — к большему сходству с исходным текстом. Размер марковской модели растёт экспоненциально с ростом значения `--order`. ## Очистка данных {#cleanup} Удаление таблиц, созданных для нагрузочного тестирования ```bash ydb workload fulltext clean ``` ## Примеры использования {#examples} ### Пример с генерируемым датасетом 1. Скачать либо обучить Марковскую модель: - Скачать модель из S3: ```bash wget https://storage.yandexcloud.net/ydb-public/markov_dict.tsv.gz ``` - Обучение модели на данных с Wikipedia: ```python from datasets import load_dataset ds = load_dataset( "rumbleFTW/wikipedia-20220301-en-raw", split="train[:1000000]", streaming=False, ) ds.to_csv('wikipedia_sample.csv.gz', compression='gzip', index=False) ``` ```bash ydb workload fulltext model --input wikipedia_sample.csv.gz --output markov_dict.tsv.gz --order 3 ``` 2. Инициализируйте таблицы для нагрузочного тестирования: ```bash ydb workload fulltext init ``` 3. Генерация и загрузка в БД синтетических документов: ```bash ydb workload fulltext import generator --model markov_dict.tsv.gz ``` 4. Запуск нагрузки на поиск: ```bash ydb workload fulltext run select --model markov_dict.tsv.gz ``` Пример вывода: ```text Window Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 1 23 23 0 0 242 407 453 453 2 18 18 0 1 611 807 915 915 3 6 6 0 7 161 991 991 991 4 35 35 0 0 173 803 923 923 5 59 59 0 1 135 647 759 803 6 26 26 0 0 257 335 339 339 7 15 15 0 1 651 963 975 975 8 11 11 0 1 871 943 963 963 9 18 18 0 6 190 967 999 999 10 31 31 0 1 433 755 995 995 Total Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 10 242 24.2 0 18 259 915 991 999 ``` Описание колонок: - Window – Порядковый номер временного окна (например, каждая секунда или фиксированный интервал). - Txs – Количество успешно выполненных транзакций в данном окне (или общее количество по всем окнам в нижней секции). - Txs/Sec – Количество транзакций в секунду для данного окна (или среднее значение для итоговой строки). - Retries – Количество автоматических повторных попыток из-за временных ошибок (например, конфликтов или троттлинга). - Errors – Количество неисправимых ошибок. - p50(ms) – Медианная (50-й перцентиль) задержка выполнения транзакции в миллисекундах. - p95(ms) – Задержка на уровне 95-го перцентиля (миллисекунды). - p99(ms) – Задержка на уровне 99-го перцентиля (миллисекунды). - pMax(ms) – Максимальная наблюдаемая задержка в пределах окна (или глобальный максимум для итоговой строки). 5. Запуск нагрузки на запись: ```bash ydb workload fulltext run upsert --model markov_dict.tsv.gz ``` Пример вывода: ```text Window Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 1 255 255 0 0 31 34 117 123 2 279 279 0 0 32 37 42 45 3 282 282 0 0 31 35 37 40 4 277 277 0 0 32 37 39 42 5 281 281 0 0 32 38 40 42 6 278 278 0 0 32 39 41 43 7 279 279 0 0 32 38 39 43 8 275 275 0 0 33 39 42 46 9 282 282 0 0 32 37 39 40 10 293 293 0 0 31 37 39 41 Total Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) ``` 6. Удаление таблиц, созданных для нагрузочного тестирования: ```bash ydb workload fulltext clean ``` ### Пример с датасетом MS MARCO 1. Скачайте пакет данных (содержит `documents.tsv.gz`, `queries.tsv.gz`, `markov_dict.tsv.gz` и `query_relevances.tsv.gz`): ```bash wget https://storage.yandexcloud.net/ydb-public/quality-bundle.tar tar -xf quality-bundle.tar ``` 2. Инициализируйте таблицы для нагрузочного тестирования: ```bash ydb workload fulltext init ``` 3. Импортируйте документы из датасета: ```bash ydb workload fulltext import files ``` 4. Запуск нагрузки на поиск: ```bash ydb workload fulltext run select --quality ``` Пример вывода: ```text Search quality measurement... Search quality measurement completed for 100 queries in 1 seconds. nDCG@10: 0.270 Errors: 0 Window Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 1 23 23 0 0 242 407 453 453 2 18 18 0 1 611 807 915 915 3 6 6 0 7 161 991 991 991 4 35 35 0 0 173 803 923 923 5 59 59 0 1 135 647 759 803 6 26 26 0 0 257 335 339 339 7 15 15 0 1 651 963 975 975 8 11 11 0 1 871 943 963 963 9 18 18 0 6 190 967 999 999 10 31 31 0 1 433 755 995 995 Total Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 10 242 24.2 0 18 259 915 991 999 ``` 5. Запуск нагрузки на запись: ```bash ydb workload fulltext run upsert ``` Пример вывода: ```text Window Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 1 255 255 0 0 31 34 117 123 2 279 279 0 0 32 37 42 45 3 282 282 0 0 31 35 37 40 4 277 277 0 0 32 37 39 42 5 281 281 0 0 32 38 40 42 6 278 278 0 0 32 39 41 43 7 279 279 0 0 32 38 39 43 8 275 275 0 0 33 39 42 46 9 282 282 0 0 32 37 39 40 10 293 293 0 0 31 37 39 41 Total Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 10 2781 278.1 0 0 32 38 41 123 Window Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 1 255 255 0 0 31 34 117 123 2 279 279 0 0 32 37 42 45 3 282 282 0 0 31 35 37 40 4 277 277 0 0 32 37 39 42 5 281 281 0 0 32 38 40 42 6 278 278 0 0 32 39 41 43 7 279 279 0 0 32 38 39 43 8 275 275 0 0 33 39 42 46 9 282 282 0 0 32 37 39 40 10 293 293 0 0 31 37 39 41 Total Txs Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) 10 2781 278.1 0 0 32 38 41 123 ``` 6. Удаление таблиц, созданных для нагрузочного тестирования: ```bash ydb workload fulltext clean ```