> ## 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/zh/reference/functions/regular-functions/machine-learning-functions) 是查询该字典的唯一方式：它以单独参数的形式接收各个特征，返回预测结果，并支持额外的[预测参数](#prediction-parameters)。该字典保存的是训练好的模型而非行数据，因此不支持通用的字典接口 ([`dictGet`](https://clickhouse.com/docs/zh/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]
>
> **训练过程会将整个训练集保存在内存中。** 按块读取数据源并不等同于核外训练：每个块读取后会被累积保留，而不是处理完即丢弃，因此在第一个提升轮开始之前，整个训练集就已全部驻留在内存中，并一直保留到最后一个提升轮结束。

**预测 (在查询时) 。** 进行预测时，模型接收特征向量 (顺序与键列的声明顺序一致) ，将其输入训练好的 booster，并返回一个 `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 booster，并沿用 XGBoost 自身的默认值和取值范围——参见 [XGBoost 参数参考文档](https://xgboost.readthedocs.io/en/stable/parameter.html)。

| 参数 | 描述 |
| - | - |
| `num_iterations` | 提升轮次 (即训练多少棵树) 。正整数，用作训练循环次数，不会转发给 booster。默认值为 `100`。 |
| `booster` | Booster 类型：`gbtree`、`gblinear` 或 `dart`。 |
| `objective` | 学习目标，例如 `reg:squarederror` 或 `binary:logistic`。必须是每行只预测单个值的目标；多分类目标 (`multi:softmax`、`multi:softprob`) 会被拒绝。 |
| `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` | 子节点所需的实例权重 (hessian) 之和的最小值。 |
| `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` 通过 `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 持有，而 XGBoost 不会报告其占用的内存量。`query_count` 和 `found_rate` 统计的是 `predictXGBoost` 传给模型的行数；若某次调用的所有特征均为常量，则每个块只计算一次，因此每个块只计为一行，而非每行各计一次。

* **重新加载失败时会保留之前的模型。** 如果重新训练失败 (例如源表已被删除、其 schema 已更改，或某个超参数不再被接受) ，字典并不会因此开始返回预测失败，而是继续使用最后一次训练成功的模型提供服务，同时记录该错误。比较 `system.dictionaries` 中的 `last_successful_update_time` 与 `last_exception`，即可判断模型是否仍反映当前的源数据：

  ```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` 会按声明顺序将按位置传入的特征参数依次绑定到各键列，且特征参数的数量必须与键列数量一致。
