> ## 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.

# Diccionarios XGBoost

> Configure diccionarios XGBOOST para entrenar un modelo de gradient boosting y predecir un destino numérico.

[No es compatible con ClickHouse Cloud](https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility.md#list-of-unsupported-features)

El diccionario `xgboost` (`XGBOOST`) entrena un modelo de gradient boosting de [XGBoost](https://xgboost.readthedocs.io/) en el momento de carga, a partir de una tabla de origen con filas de entrenamiento, y después predice un destino numérico para cualquier vector de características que se le pase. Las columnas de características forman la clave del diccionario, y el único atributo es el destino que aprende el modelo.

Resulta adecuado para tareas de regresión tabular y de clasificación binaria con características numéricas; por ejemplo, para pronosticar un valor a partir de varias mediciones o para puntuar filas con respecto a un destino aprendido. Los objetivos multiclase no son compatibles (consulte [Parámetros de disposición](#layout-parameters)).

> [!NOTE]
>
> La integración de XGBoost es experimental. Actívela con el parámetro de configuración `enable_xgboost` antes de crear un diccionario `XGBOOST` o de llamar a `predictXGBoost`:
>
> ```sql theme={null}
> SET enable_xgboost = 1;
> ```
>
> Solo se admite `CREATE DICTIONARY`: un diccionario `XGBOOST` definido en un archivo de configuración del servidor no se carga.

[`predictXGBoost`](https://clickhouse.com/docs/es/reference/functions/regular-functions/machine-learning-functions) es la única forma de consultar el diccionario: recibe las características como argumentos individuales, devuelve la predicción y acepta [parámetros de predicción](#prediction-parameters) adicionales. Como el diccionario contiene un modelo entrenado en lugar de filas, la interfaz genérica de diccionarios ([`dictGet`](https://clickhouse.com/docs/es/reference/functions/regular-functions/ext-dict-functions#dictGet), `dictHas` y `SELECT * FROM dict`) no es compatible y devuelve un error.

## Guía de inicio rápido

En este ejemplo entrenamos un regresor con el destino lineal `y = 2*x1 + 3*x2`.

**1. Cree una tabla de origen** con filas de entrenamiento: primero las columnas de características y, a continuación, el destino:

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

**2. Inserte los datos de entrenamiento:**

```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. Cree el diccionario** con la disposición `XGBOOST`: las columnas de características forman la clave e `y` es el atributo destino:

```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)` convierte `x1` y `x2` en las características. El destino que aprende el modelo es `y`, que se infiere como la única columna que no forma parte de la clave; los parámetros de `LAYOUT` son hiperparámetros de XGBoost (consulte [Parámetros de disposición](#layout-parameters)).

**4. Predecir** — `predictXGBoost` recibe las características por posición y devuelve la predicción:

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

El valor real es `2*1 + 3*2 = 8`, por lo que la predicción del modelo se aproxima a `8`.

## Cómo funciona

**Entrenamiento (en el momento de carga).** Cada fila de la fuente es una observación `(features..., target)`. Cuando se carga el diccionario, la fuente se lee bloque a bloque y, después, el modelo se entrena una sola vez sobre el conjunto completo. Los valores de las características y del destino se leen como números de coma flotante, por lo que las columnas de clave deben ser numéricas y el atributo destino debe ser de coma flotante (consulte [Estructura del diccionario](#dictionary-structure)).

> [!WARNING]
>
> **El entrenamiento mantiene todo el conjunto de entrenamiento en memoria.** Leer la fuente en bloques no equivale a un entrenamiento fuera de memoria (out-of-core): cada bloque se acumula en lugar de consumirse, de modo que todo el conjunto de entrenamiento ya reside en memoria antes de la primera ronda de boosting y permanece en ella hasta la última.

**Predicción (en el momento de la consulta).** Para predecir, el modelo toma el vector de características (en el mismo orden en que se declararon las columnas de clave) y lo pasa por el booster entrenado, que devuelve un `Float64`. Una característica `NULL` se pasa al modelo como valor ausente, que XGBoost trata según lo aprendido durante el entrenamiento, por lo que la predicción nunca es `NULL`. Cuando todas las características son constantes, el modelo se evalúa una vez por bloque en lugar de una vez por fila.

**El modelo no se persiste.** Solo existe en memoria mientras el diccionario permanece cargado y se vuelve a entrenar a partir de la fuente en cada carga, incluso tras reiniciar el servidor.

**Reentrenamiento del modelo.** Como cada carga entrena el modelo desde cero, `SYSTEM RELOAD DICTIONARY` lo vuelve a entrenar con el contenido actual de la tabla de origen:

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

Un valor de `LIFETIME` distinto de cero también provoca un reentrenamiento, ya que una recarga activada por la duración es una carga normal. Úselo para actualizar el modelo periódicamente a medida que aumentan los datos de entrenamiento.

## Estructura del diccionario

Un diccionario `XGBOOST` tiene una forma fija:

* La `PRIMARY KEY` está formada por una o más columnas de un tipo numérico nativo (enteros y números de coma flotante): las características. En el momento de la consulta, esta "clave" es el vector de características que se pasa para obtener la predicción, no una clave de búsqueda almacenada. El orden de las características corresponde al orden en que se declaran las columnas clave, y `predictXGBoost` asocia sus argumentos posicionales siguiendo ese orden.
* Además, declare **exactamente un atributo de tipo `Float32` o `Float64`**: el destino que aprende el modelo. Siempre se infiere como la única columna que no forma parte de la clave de características; no existe ningún parámetro para indicarlo, y declarar más de un atributo produce un error.

Una columna que no cumpla estos requisitos se rechaza al cargar el diccionario, no al crearlo.

## Parámetros de disposición

Solo se aceptan los parámetros que se enumeran a continuación; cualquier otro nombre provoca un error en la carga, de modo que los errores tipográficos se detectan al entrenar el modelo en lugar de ignorarse silenciosamente. `num_iterations` lo gestiona ClickHouse (consulte su descripción); todos los demás parámetros se redirigen sin cambios al booster de XGBoost, como cadena, y adoptan el valor predeterminado y el rango de valores propios de XGBoost. Consulte la [referencia de parámetros de XGBoost](https://xgboost.readthedocs.io/en/stable/parameter.html).

| Parámetro | Descripción |
| - | - |
| `num_iterations` | Número de rondas de boosting (cuántos árboles se entrenan). Un entero positivo que se utiliza como número de iteraciones del bucle de entrenamiento en lugar de redirigirse al booster. Valor predeterminado: `100`. |
| `booster` | Tipo de booster: `gbtree`, `gblinear` o `dart`. |
| `objective` | Objetivo de aprendizaje, p. ej., `reg:squarederror` o `binary:logistic`. Debe ser un objetivo que prediga un único valor por fila; los objetivos multiclase (`multi:softmax`, `multi:softprob`) se rechazan. |
| `seed` | Semilla de números aleatorios. Por lo demás, el entrenamiento es determinista, así que solo modifica el modelo si también se establece un parámetro estocástico (`subsample`, `sampling_method` o cualquier `colsample_*`). |
| `verbosity` | Nivel de detalle del registro de XGBoost: `0` (silencioso), `1` (advertencias, valor predeterminado) o `2` (información). El nivel de depuración `3` se rechaza, porque los monitores de tiempo que activa no son seguros para subproceso. Solo determina qué mensajes registra XGBoost, nunca afecta al modelo entrenado. Consulte [Notas](#notes) para saber adónde se envían los mensajes. |
| `nthread` | Número de threads paralelos utilizados para el entrenamiento. Se acepta y se redirige, pero actualmente no tiene ningún efecto: el XGBoost incluido se compila sin OpenMP, por lo que el entrenamiento y la predicción se ejecutan siempre en un único thread. |
| `eta` | Reducción del tamaño del paso aplicada después de cada ronda de boosting. Solo se acepta este nombre; el alias `learning_rate` de XGBoost, no. |
| `gamma` | Reducción mínima de la pérdida necesaria para realizar una nueva división en una hoja. |
| `max_depth` | Profundidad máxima de un árbol. |
| `min_child_weight` | Suma mínima del peso de instancia (hessiana) necesaria en un nodo hijo. |
| `max_delta_step` | Paso delta máximo permitido para la salida de cada hoja. |
| `subsample` | Fracción de las filas de entrenamiento muestreadas en cada ronda de boosting. |
| `sampling_method` | Método de muestreo de filas: `uniform` o `gradient_based`. Solo tiene efecto si `subsample` se establece en un valor inferior a `1`. |
| `colsample_bytree` / `colsample_bylevel` / `colsample_bynode` | Fracción de columnas (características) muestreadas por árbol / por nivel / por división. |
| `lambda` | Término de regularización L2 sobre los pesos. Solo se acepta este nombre; el alias `reg_lambda` de XGBoost, no. |
| `alpha` | Término de regularización L1 sobre los pesos. Solo se acepta este nombre; el alias `reg_alpha` de XGBoost, no. |
| `tree_method` | Algoritmo de construcción de árboles: `auto`, `exact`, `approx` o `hist`. |
| `scale_pos_weight` | Equilibra los pesos positivos y negativos; resulta útil con clases desbalanceadas. |
| `grow_policy` | Cómo se añaden nuevos nodos al árbol: `depthwise` o `lossguide`. |
| `max_leaves` | Número máximo de nodos hoja (se usa con `grow_policy` `lossguide`). |
| `max_bin` | Número máximo de bins discretos utilizados para agrupar características continuas (se usa con `tree_method` `hist`). |
| `num_parallel_tree` | Número de árboles generados por ronda de boosting (un valor `> 1` entrena un bosque aleatorio con boosting). |

Los nombres de los parámetros no distinguen entre mayúsculas y minúsculas, y cada uno solo puede indicarse una vez. Los valores deben ser un entero positivo, un número de coma flotante o una cadena entre comillas: el propio DDL del diccionario rechaza los literales negativos antes de que lleguen a la disposición, por lo que no es posible indicar un `seed` negativo.

Por ejemplo, un diccionario que además establece el tamaño del paso `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);
```

## Parámetros de predicción

`predictXGBoost` acepta, como argumento final opcional después de las características, un `Map` constante con parámetros de predicción de XGBoost, construido con `map`:

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

Los nombres de los parámetros se corresponden con los parámetros de predicción de `XGBoosterPredictFromDMatrix` de XGBoost. Solo se aceptan las claves que se indican a continuación; cualquier otra clave hace que la consulta falle. Todos los parámetros son de tipo integer o boolean, por lo que los valores del `Map` deben ser de un tipo entero.

| Parámetro | Descripción | Valor predeterminado |
| - | - | - |
| `type` | Tipo de predicción. Solo se aceptan `0` (valor) y `1` (margen), ya que `predictXGBoost` devuelve un único `Float64` por fila. Los demás tipos de XGBoost (`2`/`3`: contribuciones SHAP; `4`/`5`: interacciones entre características; `6`: índice de hoja) generan varios valores por fila y se rechazan. | `0` |
| `iteration_begin` | Primera ronda de boosting que se incluye en la predicción, contando desde `0` (inclusivo). No puede superar el número de iteraciones de boosting con las que se entrenó el modelo (`num_iterations`). | `0` |
| `iteration_end` | Posición inmediatamente posterior a la última ronda de boosting que se incluye (exclusivo); así, `iteration_end 1` usa solo la primera ronda, y `0` usa todas las rondas. Tiene los mismos límites que `iteration_begin`. | `0` |

## Notas

* **Semántica de diccionario computacional.** Este es un diccionario *computacional*: contiene un modelo entrenado, no filas, y `predictXGBoost` es la única forma de consultarlo. La interfaz genérica de diccionarios no es compatible y devuelve un error: `dictGet` (no hay ningún atributo almacenado que buscar; la "clave" es un vector de características a partir del cual se predice), `dictHas` (no se almacenan claves), `SELECT * FROM dict` y hacer join con el diccionario como si fuera una tabla. Dado que `predictXGBoost` es el único punto de entrada, el parámetro de configuración `enable_xgboost` debe estar habilitado en cada predicción.

* **Solo columnas numéricas.** Todas las columnas de características (clave) deben ser de un tipo numérico nativo, y el atributo de destino debe ser `Float32` o `Float64`. Los valores se leen como números de coma flotante durante el entrenamiento y la predicción. Los argumentos de características de `predictXGBoost` también pueden ser `Nullable`; consulte [Cómo funciona](#how-it-works).

* **`system.dictionaries` no muestra elementos almacenados.** El diccionario entrena un modelo en lugar de almacenar filas, por lo que `element_count` es `0`, igual que en un diccionario `direct`, y `bytes_allocated` también es `0`: el modelo entrenado pertenece a XGBoost, que no informa de cuánta memoria ocupa. `query_count` y `found_rate` cuentan las filas que `predictXGBoost` pasa al modelo; una llamada cuyas características son todas constantes se evalúa una vez por bloque, por lo que cuenta una fila por bloque y no una por cada fila.

* **Si una recarga falla, se conserva el modelo anterior.** Si el reentrenamiento falla (la tabla de origen ya no existe, su esquema ha cambiado o un hiperparámetro ya no se acepta), las predicciones del diccionario no empiezan a fallar. Sigue sirviendo el último modelo entrenado correctamente y se limita a registrar el error. Compare `last_successful_update_time` con `last_exception` en `system.dictionaries` para saber si el modelo sigue reflejando los datos de origen actuales:

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

* **Los mensajes de XGBoost se envían al registro del servidor.** Se escriben con el logger `XGBoost`, con el nivel que les asigna XGBoost, y se asocian a la consulta que entrena o predice, por lo que también aparecen en `system.text_log`. Aumente `verbosity` para ver más mensajes.

* **El orden de las características es importante.** `predictXGBoost` asocia sus argumentos posicionales de características a las columnas de clave según el orden de declaración, y el número de argumentos de características debe coincidir con el número de columnas de clave.
