thevar1able/ClickHouse
1
0
Fork 0
mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-24 16:42:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(solutions): applying a CatBoost model in ClickHouse

Browse Source
This commit is contained in:
Sergei Bocharov 2019-08-16 09:54:18 +03:00
parent f0409348a1
commit efccf28cfb
6 changed files with 440 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
docs/en/solutions/apply-catboost-model.md Normal file
View File

@ -0,0 +1,212 @@
# Applying a CatBoost model in ClickHouse {#applying-catboost-model-in-clickhouse}
[CatBoost](https://catboost.ai) — is a free and open-source gradient boosting library for machine learning.
To apply a CatBoost model in ClickHouse:
1. [Create a table for the train sample](#create-a-table).
1. [Insert the data to the table](#insert-the-data-to-the-table).
1. [Configure the model](#configure-the-model).
1. [Test the trained model](#test-the-trained-model).
## Before you start {#before-you-start}
If you don't have the [Docker](https://docs.docker.com/install/) yet, install it.
> **Note:** [Docker](https://www.docker.com) uses containers to create virtual environments that isolate a CatBoost and ClickHouse installation from the rest of the system. CatBoost and ClickHouse programs are run within this virtual environment.
Before applying a CatBoost model:
**1.** Pull the [Docker image](https://hub.docker.com/r/yandex/tutorial-catboost-clickhouse) from the registry:
```bash
$ docker pull yandex/tutorial-catboost-clickhouse
```
This Docker image contains everything you need to run an application: code, runtime, libraries, environment variables, and configuration files.
**3.** Make sure the Docker image has been pulled:
```bash
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
yandex/tutorial-catboost-clickhouse latest 3e5ad9fae997 19 months ago 1.58GB
```
**2.** Start the Docker-configured image:
```bash
$ docker run -it -p 8888:8888 yandex/tutorial-catboost-clickhouse
```
> **Note:** Example running a Jupyter Notebook with this manual materials to [http://localhost:8888](http://localhost:8888).
## 1. Create a table {#create-a-table}
To create a ClickHouse table for the train sample:
**1.** Start a ClickHouse client:
```bash
$ clickhouse client
```
> **Note:** The ClickHouse server is already running inside the Docker container.
**2.** Create the table using the command:
```sql
:) CREATE TABLE amazon_train
(
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
)
ENGINE = MergeTree(date, date, 8192)
```
## 2. Insert the data to the table {#insert-the-data-to-the-table}
To insert the data:
**1.** Exit from ClickHouse:
```sql
:) exit
```
**2.** Upload the data:
```bash
$ clickhouse client --host 127.0.0.1 --query 'INSERT INTO amazon_train FORMAT CSVWithNames' < ~/amazon/train.csv
```
**3.** Make sure the data has been uploaded:
```sql
$ clickhouse client
:) SELECT count() FROM amazon_train
SELECT count()
FROM amazon_train
+-count()-+
| 32769 |
+---------+
```
## 3. Configure the model to work with the trained model {#configure-the-model}
This step is optional: the Docker container contains all configuration files.
**1.** Create a config file (for example, `config_model.xml`) with the model configuration:
```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>
```
> **Note:** To show contents of the config file in the Docker container, run `cat models/amazon_model.xml`.
**2.** Add the following lines to the `/etc/clickhouse-server/config.xml` file:
```xml
<catboost_dynamic_library_path>/home/catboost/.data/libcatboostmodel.so</catboost_dynamic_library_path>
<models_config>/home/catboost/models/*_model.xml</models_config>
```
> **Note:** To show contents of the ClickHouse config file in the Docker container, run `cat ../../etc/clickhouse-server/config.xml`.
**3.** Restart ClickHouse server:
```bash
$ sudo service clickhouse-server restart
```
## 4. Test the trained model {#test-the-trained-model}
For test run the ClickHouse client `$ clickhouse client`.
- Let's make sure that the model is working:
```sql
:) SELECT
modelEvaluate('amazon',
RESOURCE,
MGR_ID,
ROLE_ROLLUP_1,
ROLE_ROLLUP_2,
ROLE_DEPTNAME,
ROLE_TITLE,
ROLE_FAMILY_DESC,
ROLE_FAMILY,
ROLE_CODE) > 0 AS prediction,
ACTION AS target
FROM amazon_train
LIMIT 10
```
> **Note:** Function `modelEvaluate` returns tuple with per-class raw predictions for multiclass models.
- Let's predict probability:
```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,
1. / (1 + exp(-prediction)) AS probability,
ACTION AS target
FROM amazon_train
LIMIT 10
```
- Let's calculate LogLoss on the sample:
```sql
:) SELECT -avg(tg * log(prob) + (1 - tg) * log(1 - prob)) AS logloss
FROM
(
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,
1. / (1. + exp(-prediction)) AS prob,
ACTION AS tg
FROM amazon_train
)
```

5
docs/en/solutions/index.md Normal file
View File

@ -0,0 +1,5 @@
# ClickHouse solution tutorials
Detailed step-by-step instructions that will help you solve various tasks using ClickHouse.
- [Applying a CatBoost model in ClickHouse](apply-catboost-model.md)

210
docs/ru/solutions/apply-catboost-model.md Normal file
View File

@ -0,0 +1,210 @@
# Применение модели CatBoost в ClickHouse {#applying-catboost-model-in-clickhouse}
[CatBoost](https://catboost.ai) — открытая программная библиотека для машинного обучения, использующая схему градиентного бустинга.
Чтобы применить модель CatBoost в ClickHouse:
1. [Создайте таблицу для обучающей выборки](#create-a-table).
1. [Вставьте данные в таблицу](#insert-the-data-to-the-table).
1. [Настройте конфигурацию модели](#configure-the-model).
1. [Протестируйте обученную модель](#test-the-trained-model)
## Подготовка к работе {#before-you-start}
Если у вас еще нет [Docker](https://docs.docker.com/install/), установите его.
> **Примечание.** [Docker](https://www.docker.com) использует контейнеры для создания виртуальных сред, которые изолируют установку CatBoost и ClickHouse от остальной части системы. Программы CatBoost и ClickHouse выполняются в этой виртуальной среде.
Перед применением модели CatBoost в ClickHouse:
**1.** Скачайте [Docker-образ](https://hub.docker.com/r/yandex/tutorial-catboost-clickhouse) из реестра:
```bash
$ docker pull yandex/tutorial-catboost-clickhouse
```
Данный Docker-образ содержит все необходимое для запуска приложения: код, среду выполнения, библиотеки, переменные окружения и файлы конфигурации.
**2.** Проверьте, что Docker-образ действительно скачался:
```bash
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
yandex/tutorial-catboost-clickhouse latest 3e5ad9fae997 19 months ago 1.58GB
```
**3.** Запустите Docker-образ:
```bash
$ docker run -it -p 8888:8888 yandex/tutorial-catboost-clickhouse
```
> **Примечание.** После запуска по адресу [http://localhost:8888](http://localhost:8888) будет доступен Jupyter Notebook с материалами данной инструкции.
## 1. Создайте таблицу {#create-a-table}
Чтобы создать таблицу в ClickHouse для обучающей выборки:
**1.** Запустите ClickHouse-клиент:
```bash
$ clickhouse client
```
> **Примечание.** ClickHouse-сервер уже запущен внутри Docker-контейнера.
**2.** Создайте таблицу в ClickHouse с помощью следующей команды:
```sql
:) CREATE TABLE amazon_train
(
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
)
ENGINE = MergeTree(date, date, 8192)
```
## 2. Вставьте данные в таблицу {#insert-the-data-to-the-table}
Чтобы вставить данные:
**1.** Выйдите из клиента ClickHouse:
```sql
:) exit
```
**2.** Загрузите данные:
```bash
$ clickhouse client --host 127.0.0.1 --query 'INSERT INTO amazon_train FORMAT CSVWithNames' < ~/amazon/train.csv
```
**3.** Проверьте, что данные действительно загрузились:
```sql
$ clickhouse client
:) SELECT count() FROM amazon_train
SELECT count()
FROM amazon_train
+-count()-+
| 32769 |
+---------+
```
## 3. Настройте конфигурацию модели {#configure-the-model}
Опциональный шаг: Docker-контейнер содержит все необходимые файлы конфигурации.
**1.** Создайте файл с конфигурацией модели (например, `config_model.xml`):
```xml
<models>
<model>
<!-- Тип модели. В настоящий момент ClickHouse предоставляет только модель catboost. -->
<type>catboost</type>
<!-- Имя модели. -->
<name>amazon</name>
<!-- Путь к обученной модели. -->
<path>/home/catboost/tutorial/catboost_model.bin</path>
<!-- Интервал обновления. -->
<lifetime>0</lifetime>
</model>
</models>
```
> **Примечание.** Чтобы посмотреть конфигурационный файл в Docker-контейнере, выполните команду `cat models/amazon_model.xml`.
**2.** Добавьте следующие строки в файл `/etc/clickhouse-server/config.xml`:
```xml
<catboost_dynamic_library_path>/home/catboost/.data/libcatboostmodel.so</catboost_dynamic_library_path>
<models_config>/home/catboost/models/*_model.xml</models_config>
```
> **Примечание.** Чтобы посмотреть конфигурационный файл ClickHouse в Docker-контейнере, выполните команду `cat ../../etc/clickhouse-server/config.xml`.
**3.** Перезапустите ClickHouse-сервер:
```bash
$ sudo service clickhouse-server restart
```
## 4. Протестируйте обученную модель {#test-the-trained-model}
Для тестирования запустите ClickHouse-клиент `$ clickhouse client`.
- Проверьте, что модель работает:
```sql
:) SELECT
modelEvaluate('amazon',
RESOURCE,
MGR_ID,
ROLE_ROLLUP_1,
ROLE_ROLLUP_2,
ROLE_DEPTNAME,
ROLE_TITLE,
ROLE_FAMILY_DESC,
ROLE_FAMILY,
ROLE_CODE) > 0 AS prediction,
ACTION AS target
FROM amazon_train
LIMIT 10
```
> **Примечание.** Функция `modelEvaluate` возвращает кортежи (tuple) с исходными прогнозами по классам для моделей с несколькими классами.
- Спрогнозируйте вероятность:
```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,
1. / (1 + exp(-prediction)) AS probability,
ACTION AS target
FROM amazon_train
LIMIT 10
```
- Посчитайте логистическую функцию потерь (LogLoss) на всей выборке:
```sql
:) SELECT -avg(tg * log(prob) + (1 - tg) * log(1 - prob)) AS logloss
FROM
(
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,
1. / (1. + exp(-prediction)) AS prob,
ACTION AS tg
FROM amazon_train
)
```

5
docs/ru/solutions/index.md Normal file
View File

@ -0,0 +1,5 @@
# Сценарии использования ClickHouse
Подробные пошаговые инструкции, которые помогут вам решать различные задачи с помощью ClickHouse.
- [Применение модели CatBoost в ClickHouse](apply-catboost-model.md)

4
docs/toc_en.yml
View File

@ -204,6 +204,10 @@ nav:
- 'clickhouse-copier': 'operations/utils/clickhouse-copier.md'
- 'clickhouse-local': 'operations/utils/clickhouse-local.md'
- 'Solution tutorials':
- 'Overview': 'solutions/index.md'
- 'Applying a CatBoost model in ClickHouse': 'solutions/apply-catboost-model.md'
- 'Development':
- 'hidden': 'development/index.md'
- 'Overview of ClickHouse Architecture': 'development/architecture.md'

4
docs/toc_ru.yml
View File

@ -203,6 +203,10 @@ nav:
- 'clickhouse-copier': 'operations/utils/clickhouse-copier.md'
- 'clickhouse-local': 'operations/utils/clickhouse-local.md'
- 'Сценарии использования':
- 'Обзор': 'solutions/index.md'
- 'Применение модели CatBoost в ClickHouse': 'solutions/apply-catboost-model.md'
- 'F.A.Q.':
- 'Общие вопросы': 'faq/general.md'