> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Словари XGBoost

> Настройка словарей XGBOOST для обучения модели градиентного бустинга и прогнозирования числовой целевой переменной.

[Не поддерживается в ClickHouse Cloud](https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility.md#list-of-unsupported-features)

Словарь `xgboost` (`XGBOOST`) в момент загрузки обучает модель градиентного бустинга [XGBoost](https://xgboost.readthedocs.io/) на обучающих строках из исходной таблицы, а затем предсказывает числовое значение целевой переменной для любого переданного вектора возможностей. Столбцы возможностей образуют ключ словаря, а единственный атрибут — это целевая переменная, которую обучается предсказывать модель.

Он подходит для задач регрессии и бинарной классификации на табличных данных с числовыми возможностями — например, для прогнозирования значения по нескольким измерениям или для оценки строк относительно обученной целевой переменной. Многоклассовые целевые функции не поддерживаются (см. [Параметры структуры](#layout-parameters)).

> [!NOTE]
>
> Интеграция с XGBoost является экспериментальной. Перед созданием словаря `XGBOOST` или вызовом `predictXGBoost` включите её с помощью настройки `enable_xgboost`:
>
> ```sql theme={null}
> SET enable_xgboost = 1;
> ```
>
> Поддерживается только `CREATE DICTIONARY`: словарь `XGBOOST`, определённый в файле конфигурации сервера, загрузить не удастся.

[`predictXGBoost`](https://clickhouse.com/docs/ru/reference/functions/regular-functions/machine-learning-functions) — единственный способ обращаться к словарю: функция принимает возможности в виде отдельных аргументов, возвращает предсказание и поддерживает дополнительные [параметры предсказания](#prediction-parameters). Словарь хранит обученную модель, а не строки, поэтому общий интерфейс словарей — [`dictGet`](https://clickhouse.com/docs/ru/reference/functions/regular-functions/ext-dict-functions#dictGet), `dictHas` и `SELECT * FROM dict` — не поддерживается и возвращает ошибку.

## Быстрый старт

В этом примере мы обучим регрессор на линейной целевой функции `y = 2*x1 + 3*x2`.

**1. Создайте исходную таблицу** с обучающими строками: сначала столбцы возможностей, затем целевой столбец:

```sql theme={null}
CREATE TABLE training_data (x1 Float64, x2 Float64, y Float64)
ENGINE = MergeTree ORDER BY tuple();
```

**2. Вставьте обучающие данные:**

```sql theme={null}
INSERT INTO training_data
SELECT number AS x1, number * 2 AS x2, 2 * x1 + 3 * x2 AS y
FROM numbers(100);
```

**3. Создайте словарь** со структурой `XGBOOST`: столбцы возможностей служат ключом, а `y` — целевым атрибутом:

```sql theme={null}
CREATE DICTIONARY model (x1 Float64, x2 Float64, y Float64)
PRIMARY KEY (x1, x2)
SOURCE(CLICKHOUSE(TABLE 'training_data'))
LAYOUT(XGBOOST(
    objective 'reg:squarederror'
    num_iterations 100
    max_depth 6
))
LIFETIME(0);
```

`PRIMARY KEY (x1, x2)` делает `x1` и `x2` возможностями. Целевая переменная, которую учится предсказывать модель, — `y`: она определяется как единственный столбец, не входящий в ключ. Параметры в `LAYOUT` — это гиперпараметры XGBoost (см. [Параметры структуры](#layout-parameters)).

**4. Предсказание** — `predictXGBoost` принимает возможности по порядку их следования и возвращает предсказание:

```sql theme={null}
SELECT predictXGBoost('model', 1.0, 2.0) AS prediction;
```

Истинное значение равно `2*1 + 3*2 = 8`, поэтому предсказание модели близко к `8`.

## Как это работает

**Обучение (в момент загрузки).** Каждая строка источника представляет собой наблюдение вида `(features..., target)`. При загрузке словаря источник считывается блок за блоком, после чего модель однократно обучается на всём наборе данных. Значения возможностей и целевые значения считываются как числа с плавающей точкой, поэтому столбцы ключа должны быть числовыми, а целевой атрибут — иметь тип с плавающей точкой (см. [Структура словаря](#dictionary-structure)).

> [!WARNING]
>
> **При обучении весь обучающий набор хранится в памяти.** Чтение источника блоками не означает обучения вне оперативной памяти (out-of-core): блоки накапливаются, а не обрабатываются и отбрасываются по одному, поэтому весь обучающий набор оказывается в памяти ещё до первого раунда бустинга и остаётся там до последнего.

**Предсказание (во время выполнения запроса).** Для предсказания модель принимает вектор возможностей — в том же порядке, в котором объявлены столбцы ключа, — пропускает его через обученный бустер и возвращает значение типа `Float64`. Возможность со значением `NULL` передаётся модели как отсутствующее значение, которое XGBoost обрабатывает так, как научился при обучении, поэтому предсказание никогда не равно `NULL`. Если все возможности — константы, модель вычисляется один раз на блок, а не для каждой строки.

**Модель не сохраняется.** Она существует только в памяти, пока загружен словарь, и заново обучается на данных источника при каждой загрузке — в том числе после перезапуска сервера.

**Переобучение модели.** Поскольку при каждой загрузке модель обучается с нуля, команда `SYSTEM RELOAD DICTIONARY` переобучает её на текущем содержимом исходной таблицы:

```sql theme={null}
INSERT INTO training_data VALUES (5, 10, 40);
SYSTEM RELOAD DICTIONARY model;
```

Ненулевое значение `LIFETIME` также приводит к повторному обучению, поскольку перезагрузка по истечении времени жизни — это обычная загрузка. Используйте его для периодического обновления модели по мере роста объёма обучающих данных.

## Структура словаря

Словарь `XGBOOST` имеет фиксированную форму:

* `PRIMARY KEY` — это один или несколько столбцов нативного числового типа (целые числа и числа с плавающей точкой), которые служат возможностями модели. Во время выполнения запроса этот «ключ» представляет собой вектор возможностей, передаваемый для получения предсказания, а не сохранённый ключ для поиска. Порядок возможностей совпадает с порядком объявления столбцов ключа, и `predictXGBoost` сопоставляет свои позиционные аргументы именно с этим порядком.
* Помимо них, объявите **ровно один атрибут типа `Float32` или `Float64`**: целевую переменную, которую учится предсказывать модель. Этот атрибут всегда автоматически определяется как единственный столбец, не входящий в ключ возможностей, — параметра для указания его имени нет, а объявление более одного атрибута приводит к ошибке.

Столбец, не соответствующий этим требованиям, отклоняется при загрузке словаря, а не при его создании.

## Параметры структуры

Допускаются только перечисленные ниже параметры; любое другое имя приводит к ошибке загрузки, поэтому опечатки выявляются при обучении модели, а не игнорируются молча. Параметр `num_iterations` обрабатывается ClickHouse (см. его описание); все остальные параметры передаются в бустер XGBoost без изменений в виде строки, и для них действуют значения по умолчанию и допустимые диапазоны самого XGBoost — см. [справочник параметров XGBoost](https://xgboost.readthedocs.io/en/stable/parameter.html).

| Параметр | Описание |
| - | - |
| `num_iterations` | Количество раундов бустинга (сколько деревьев обучать). Положительное целое число; используется как число итераций цикла обучения и не передаётся в бустер. По умолчанию `100`. |
| `booster` | Тип бустера: `gbtree`, `gblinear` или `dart`. |
| `objective` | Целевая функция обучения, например `reg:squarederror` или `binary:logistic`. Должна предсказывать одно значение на строку; многоклассовые целевые функции (`multi:softmax`, `multi:softprob`) отклоняются. |
| `seed` | Seed генератора случайных чисел. В остальном обучение детерминировано, поэтому этот параметр влияет на модель, только если также задан стохастический параметр (`subsample`, `sampling_method`, любой `colsample_*`). |
| `verbosity` | Уровень детализации журналирования XGBoost: `0` (без вывода), `1` (предупреждения, по умолчанию) или `2` (информационные сообщения). Отладочный уровень `3` отклоняется, поскольку включаемые им мониторы замера времени не являются потокобезопасными. Определяет только то, какие сообщения записывает XGBoost, и никак не влияет на обученную модель. Куда попадают сообщения, см. в разделе [Примечания](#notes). |
| `nthread` | Количество параллельных потоков для обучения. Принимается и передаётся в бустер, но в настоящее время ни на что не влияет: встроенный XGBoost собран без OpenMP, поэтому обучение и предсказание всегда выполняются в одном потоке. |
| `eta` | Коэффициент сжатия шага, применяемый после каждого раунда бустинга. Допускается только это написание; псевдоним XGBoost `learning_rate` не поддерживается. |
| `gamma` | Минимальное уменьшение функции потерь, необходимое для дальнейшего разделения листа. |
| `max_depth` | Максимальная глубина дерева. |
| `min_child_weight` | Минимальная сумма весов экземпляров (гессиана), необходимая в дочернем узле. |
| `max_delta_step` | Максимальный шаг дельты, допустимый для выходного значения каждого листа. |
| `subsample` | Доля строк обучающей выборки, отбираемых для каждого раунда бустинга. |
| `sampling_method` | Метод сэмплирования строк: `uniform` или `gradient_based`. Действует, только если `subsample` меньше `1`. |
| `colsample_bytree` / `colsample_bylevel` / `colsample_bynode` | Доля столбцов (возможностей), отбираемых для каждого дерева / уровня / разделения. |
| `lambda` | Член L2-регуляризации для весов. Допускается только это написание; псевдоним XGBoost `reg_lambda` не поддерживается. |
| `alpha` | Член L1-регуляризации для весов. Допускается только это написание; псевдоним XGBoost `reg_alpha` не поддерживается. |
| `tree_method` | Алгоритм построения деревьев: `auto`, `exact`, `approx` или `hist`. |
| `scale_pos_weight` | Балансирует положительные и отрицательные веса; полезен при несбалансированных классах. |
| `grow_policy` | Способ добавления новых узлов в дерево: `depthwise` или `lossguide`. |
| `max_leaves` | Максимальное количество листовых узлов (используется с `grow_policy` `lossguide`). |
| `max_bin` | Максимальное количество дискретных бинов для группировки непрерывных возможностей (используется с `tree_method` `hist`). |
| `num_parallel_tree` | Количество деревьев, выращиваемых за раунд бустинга (при значении `> 1` обучается бустированный случайный лес). |

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

Например, словарь, в котором также задан размер шага `eta`:

```sql theme={null}
CREATE DICTIONARY model_tuned (x1 Float64, x2 Float64, y Float64)
PRIMARY KEY (x1, x2)
SOURCE(CLICKHOUSE(TABLE 'training_data'))
LAYOUT(XGBOOST(
    objective 'reg:squarederror'
    num_iterations 100
    max_depth 6
    eta 0.3
))
LIFETIME(0);
```

## Параметры предсказания

`predictXGBoost` принимает необязательный концевой константный аргумент типа `Map` с параметрами предсказания XGBoost. Он указывается после возможностей и создаётся с помощью `map`:

```sql theme={null}
SELECT predictXGBoost('model', 1.0, 2.0, map('type', 0, 'iteration_end', 0));
```

Имена параметров соответствуют параметрам предсказания функции XGBoost `XGBoosterPredictFromDMatrix`. Допускаются только перечисленные ниже ключи; любой другой ключ приводит к ошибке запроса. Все параметры являются целыми числами или логическими значениями, поэтому значения `Map` должны иметь целочисленный тип.

| Параметр | Описание | По умолчанию |
| - | - | - |
| `type` | Тип предсказания. Допускаются только `0` (значение) и `1` (margin), поскольку `predictXGBoost` возвращает одно значение `Float64` на строку. Другие типы XGBoost (`2`/`3` — вклады SHAP, `4`/`5` — взаимодействия признаков, `6` — индекс листа) возвращают несколько значений на строку и поэтому отклоняются. | `0` |
| `iteration_begin` | Первый раунд бустинга, учитываемый в предсказании; отсчёт ведётся от `0` (включительно). Не должен превышать число итераций бустинга, на котором обучалась модель (`num_iterations`). | `0` |
| `iteration_end` | Номер раунда, следующего за последним учитываемым раундом бустинга (не включительно): например, при `iteration_end 1` используется только первый раунд, а при `0` — все раунды. Ограничения те же, что и для `iteration_begin`. | `0` |

## Примечания

* **Семантика вычислительного словаря.** Это *вычислительный* словарь: в нём хранится обученная модель, а не строки, и обращаться к нему с запросами можно только через `predictXGBoost`. Общий интерфейс словарей не поддерживается и возвращает ошибку: `dictGet` (сохранённого атрибута для поиска нет — "ключ" представляет собой вектор возможностей, по которому строится предсказание), `dictHas` (ключи не хранятся), `SELECT * FROM dict` и соединение со словарём как с таблицей. Поскольку `predictXGBoost` — единственная точка входа, для каждого предсказания должна быть включена настройка `enable_xgboost`.

* **Только числовые столбцы.** Каждый столбец возможностей (ключа) должен иметь нативный числовой тип, а целевой атрибут — тип `Float32` или `Float64`. При обучении и предсказании значения считываются как числа с плавающей точкой. Аргументы возможностей функции `predictXGBoost` также могут иметь тип `Nullable`, см. раздел [Как это работает](#how-it-works).

* **`system.dictionaries` не показывает сохранённых элементов.** Вместо хранения строк словарь обучает модель, поэтому `element_count` равен `0`, как и у словаря `direct`. `bytes_allocated` тоже равен `0`: обученная модель принадлежит XGBoost, а он не сообщает, сколько памяти она занимает. `query_count` и `found_rate` учитывают строки, переданные в модель функцией `predictXGBoost`; вызов, все возможности которого являются константами, вычисляется один раз на блок, поэтому учитывается одна строка на блок, а не каждая строка.

* **При неудачной перезагрузке сохраняется предыдущая модель.** Если повторное обучение завершается сбоем — исходная таблица удалена, её схема изменилась, гиперпараметр больше не принимается, — словарь не начинает выдавать ошибки при предсказании. Вместо этого он продолжает использовать последнюю успешно обученную модель и записывает ошибку. Чтобы определить, отражает ли модель актуальные исходные данные, сравните `last_successful_update_time` с `last_exception` в `system.dictionaries`:

  ```sql theme={null}
  SELECT name, status, last_successful_update_time, last_exception
  FROM system.dictionaries
  WHERE name = 'model';
  ```

* **Сообщения XGBoost записываются в журнал сервера.** Они пишутся через логгер `XGBoost` с тем уровнем, который назначает им XGBoost, и привязываются к запросу, выполняющему обучение или предсказание, поэтому также появляются в `system.text_log`. Чтобы видеть больше сообщений, увеличьте `verbosity`.

* **Порядок возможностей имеет значение.** `predictXGBoost` сопоставляет позиционные аргументы возможностей со столбцами ключа в порядке их объявления, при этом число аргументов возможностей должно совпадать с числом столбцов ключа.
