ClickHouse/docs/en/guides/apply-catboost-model.md

243 lines
7.3 KiB
Markdown
Raw Normal View History

2020-04-03 13:23:32 +00:00
---
toc_priority: 41
toc_title: Applying CatBoost Models
---
2020-03-18 18:43:51 +00:00
# Applying a Catboost Model in ClickHouse {#applying-catboost-model-in-clickhouse}
2019-10-10 12:17:39 +00:00
[CatBoost](https://catboost.ai) is a free and open-source gradient boosting library developed at [Yandex](https://yandex.com/company/) for machine learning.
2019-08-22 11:34:56 +00:00
2020-02-03 19:11:18 +00:00
With this instruction, you will learn to apply pre-trained models in ClickHouse by running model inference from SQL.
To apply a CatBoost model in ClickHouse:
2020-03-20 10:10:48 +00:00
1. [Create a Table](#create-table).
2. [Insert the Data to the Table](#insert-data-to-table).
3. [Integrate CatBoost into ClickHouse](#integrate-catboost-into-clickhouse) (Optional step).
4. [Run the Model Inference from SQL](#run-model-inference).
2019-08-22 05:45:45 +00:00
For more information about training CatBoost models, see [Training and applying models](https://catboost.ai/docs/features/training.html#training).
You can reload CatBoost models if the configuration was updated without restarting the server using [RELOAD MODEL](../sql-reference/statements/system.md#query_language-system-reload-model) and [RELOAD MODELS](../sql-reference/statements/system.md#query_language-system-reload-models) system queries.
2020-03-18 18:43:51 +00:00
## Prerequisites {#prerequisites}
2021-05-27 19:44:11 +00:00
If you do not have the [Docker](https://docs.docker.com/install/) yet, install it.
2019-08-22 11:34:56 +00:00
!!! note "Note"
[Docker](https://www.docker.com) is a software platform that allows you to create containers that isolate a CatBoost and ClickHouse installation from the rest of the system.
Before applying a CatBoost model:
**1.** Pull the [Docker image](https://hub.docker.com/r/yandex/tutorial-catboost-clickhouse) from the registry:
2020-03-20 10:10:48 +00:00
``` bash
$ docker pull yandex/tutorial-catboost-clickhouse
```
2019-08-22 11:34:56 +00:00
This Docker image contains everything you need to run CatBoost and ClickHouse: code, runtime, libraries, environment variables, and configuration files.
2019-08-22 15:13:36 +00:00
**2.** Make sure the Docker image has been successfully pulled:
2020-03-20 10:10:48 +00:00
``` bash
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
2019-10-10 12:17:39 +00:00
yandex/tutorial-catboost-clickhouse latest 622e4d17945b 22 hours ago 1.37GB
```
2019-08-22 15:13:36 +00:00
**3.** Start a Docker container based on this image:
2020-03-20 10:10:48 +00:00
``` bash
$ docker run -it -p 8888:8888 yandex/tutorial-catboost-clickhouse
```
2020-03-18 18:43:51 +00:00
## 1. Create a Table {#create-table}
2020-03-19 06:53:47 +00:00
To create a ClickHouse table for the training sample:
2020-03-19 06:53:47 +00:00
**1.** Start ClickHouse console client in the interactive mode:
2020-03-20 10:10:48 +00:00
``` bash
$ clickhouse client
```
2019-08-22 11:34:56 +00:00
!!! note "Note"
The ClickHouse server is already running inside the Docker container.
**2.** Create the table using the command:
2020-03-20 10:10:48 +00:00
``` sql
:) CREATE TABLE amazon_train
(
2020-03-20 10:10:48 +00:00
date Date MATERIALIZED today(),
ACTION UInt8,
RESOURCE UInt32,
MGR_ID UInt32,
ROLE_ROLLUP_1 UInt32,
ROLE_ROLLUP_2 UInt32,
ROLE_DEPTNAME UInt32,
ROLE_TITLE UInt32,
ROLE_FAMILY_DESC UInt32,
ROLE_FAMILY UInt32,
ROLE_CODE UInt32
)
2020-01-09 16:42:20 +00:00
ENGINE = MergeTree ORDER BY date
```
**3.** Exit from ClickHouse console client:
2020-03-20 10:10:48 +00:00
``` sql
:) exit
```
2020-03-18 18:43:51 +00:00
## 2. Insert the Data to the Table {#insert-data-to-table}
To insert the data:
**1.** Run the following command:
2020-03-20 10:10:48 +00:00
``` bash
$ clickhouse client --host 127.0.0.1 --query 'INSERT INTO amazon_train FORMAT CSVWithNames' < ~/amazon/train.csv
```
2020-03-19 06:53:47 +00:00
**2.** Start ClickHouse console client in the interactive mode:
2020-03-20 10:10:48 +00:00
``` bash
$ clickhouse client
```
**3.** Make sure the data has been uploaded:
2020-03-20 10:10:48 +00:00
``` sql
:) SELECT count() FROM amazon_train
2019-10-10 12:17:39 +00:00
SELECT count()
FROM amazon_train
+-count()-+
2019-10-10 12:17:39 +00:00
| 65538 |
2020-04-03 13:23:32 +00:00
+-------+
```
2020-03-18 18:43:51 +00:00
## 3. Integrate CatBoost into ClickHouse {#integrate-catboost-into-clickhouse}
!!! note "Note"
2019-10-14 10:33:39 +00:00
**Optional step.** The Docker image contains everything you need to run CatBoost and ClickHouse.
2019-10-14 10:33:39 +00:00
To integrate CatBoost into ClickHouse:
2019-10-14 12:39:42 +00:00
**1.** Build the evaluation library.
2019-10-14 10:33:39 +00:00
The fastest way to evaluate a CatBoost model is compile `libcatboostmodel.<so|dll|dylib>` library. For more information about how to build the library, see [CatBoost documentation](https://catboost.ai/docs/concepts/c-plus-plus-api_dynamic-c-pluplus-wrapper.html).
2019-10-14 13:08:46 +00:00
**2.** Create a new directory anywhere and with any name, for example, `data` and put the created library in it. The Docker image already contains the library `data/libcatboostmodel.so`.
2019-10-14 10:33:39 +00:00
**3.** Create a new directory for config model anywhere and with any name, for example, `models`.
2020-03-20 10:10:48 +00:00
**4.** Create a model configuration file with any name, for example, `models/amazon_model.xml`.
2019-10-14 10:33:39 +00:00
2020-03-20 10:10:48 +00:00
**5.** Describe the model configuration:
2020-03-20 10:10:48 +00:00
``` xml
<models>
<model>
<!-- Model type. Now catboost only. -->
<type>catboost</type>
<!-- Model name. -->
<name>amazon</name>
<!-- Path to trained model. -->
<path>/home/catboost/tutorial/catboost_model.bin</path>
<!-- Update interval. -->
<lifetime>0</lifetime>
</model>
</models>
```
2019-10-14 13:13:26 +00:00
**6.** Add the path to CatBoost and the model configuration to the ClickHouse configuration:
2020-03-20 10:10:48 +00:00
``` xml
2019-10-14 10:33:39 +00:00
<!-- File etc/clickhouse-server/config.d/models_config.xml. -->
2019-10-14 13:08:46 +00:00
<catboost_dynamic_library_path>/home/catboost/data/libcatboostmodel.so</catboost_dynamic_library_path>
<models_config>/home/catboost/models/*_model.xml</models_config>
```
2021-04-17 23:28:47 +00:00
!!! note "Note"
You can change path to the CatBoost model configuration later without restarting server.
2020-03-18 18:43:51 +00:00
## 4. Run the Model Inference from SQL {#run-model-inference}
2019-10-10 12:17:39 +00:00
For test model run the ClickHouse client `$ clickhouse client`.
2020-03-20 10:10:48 +00:00
Lets make sure that the model is working:
2020-03-20 10:10:48 +00:00
``` sql
:) SELECT
modelEvaluate('amazon',
RESOURCE,
MGR_ID,
ROLE_ROLLUP_1,
ROLE_ROLLUP_2,
ROLE_DEPTNAME,
ROLE_TITLE,
ROLE_FAMILY_DESC,
ROLE_FAMILY,
2020-03-20 10:10:48 +00:00
ROLE_CODE) > 0 AS prediction,
ACTION AS target
FROM amazon_train
LIMIT 10
```
2019-08-22 11:34:56 +00:00
!!! note "Note"
Function [modelEvaluate](../sql-reference/functions/other-functions.md#function-modelevaluate) returns tuple with per-class raw predictions for multiclass models.
2020-03-20 10:10:48 +00:00
Lets predict the probability:
2020-03-20 10:10:48 +00:00
``` sql
:) SELECT
modelEvaluate('amazon',
RESOURCE,
MGR_ID,
ROLE_ROLLUP_1,
ROLE_ROLLUP_2,
ROLE_DEPTNAME,
ROLE_TITLE,
ROLE_FAMILY_DESC,
ROLE_FAMILY,
ROLE_CODE) AS prediction,
2020-03-20 10:10:48 +00:00
1. / (1 + exp(-prediction)) AS probability,
ACTION AS target
FROM amazon_train
LIMIT 10
```
2019-08-22 11:34:56 +00:00
!!! note "Note"
More info about [exp()](../sql-reference/functions/math-functions.md) function.
2019-08-22 11:34:56 +00:00
2020-03-20 10:10:48 +00:00
Lets calculate LogLoss on the sample:
2020-03-20 10:10:48 +00:00
``` sql
:) SELECT -avg(tg * log(prob) + (1 - tg) * log(1 - prob)) AS logloss
2020-03-20 10:10:48 +00:00
FROM
(
2020-03-20 10:10:48 +00:00
SELECT
modelEvaluate('amazon',
RESOURCE,
MGR_ID,
ROLE_ROLLUP_1,
ROLE_ROLLUP_2,
ROLE_DEPTNAME,
ROLE_TITLE,
ROLE_FAMILY_DESC,
ROLE_FAMILY,
ROLE_CODE) AS prediction,
2020-03-20 10:10:48 +00:00
1. / (1. + exp(-prediction)) AS prob,
ACTION AS tg
FROM amazon_train
)
2019-08-22 11:34:56 +00:00
```
!!! note "Note"
More info about [avg()](../sql-reference/aggregate-functions/reference/avg.md#agg_function-avg) and [log()](../sql-reference/functions/math-functions.md) functions.
2020-03-19 06:53:47 +00:00
[Original article](https://clickhouse.com/docs/en/guides/apply_catboost_model/) <!--hide-->