> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-ru/mlops-i-razvertyvanie/clearml.md).

# ClearML

{% hint style="info" %}
**ClearML** (ранее Trains) — это платформа MLOps с открытым исходным кодом для отслеживания экспериментов, версионирования данных, управления моделями, оркестрации пайплайнов и управления вычислительными ресурсами — всё в одном унифицированном наборе.
{% endhint %}

## Обзор

ClearML — это комплексная платформа для управления жизненным циклом ML от Allegro AI. Она автоматически собирает параметры экспериментов, метрики, артефакты и код с минимальными изменениями в коде. ClearML поддерживает полный ML-процесс: от управления данными и отслеживания экспериментов до реестра моделей, автоматизированных пайплайнов и распределённого выполнения задач на кластерах GPU.

| Параметр        | Значение                                                  |
| --------------- | --------------------------------------------------------- |
| **Категория**   | MLOps / Отслеживание экспериментов                        |
| **Разработчик** | Allegro AI                                                |
| **Лицензия**    | Apache 2.0                                                |
| **GitHub**      | [allegroai/clearml](https://github.com/allegroai/clearml) |
| **Звезды**      | 5.5K+                                                     |
| **Docker Hub**  | `allegroai/clearml`                                       |
| **Порты**       | 22 (SSH), 8008 (API-сервер), 8081 (веб-интерфейс)         |

***

## Архитектура

ClearML состоит из четырёх основных компонентов:

| Компонент           | Порт | Описание                               |
| ------------------- | ---- | -------------------------------------- |
| **Сервер ClearML**  | —    | Координатор бэкенда                    |
| **Веб-интерфейс**   | 8081 | Панель управления в браузере           |
| **API-сервер**      | 8008 | REST API для SDK и агентов             |
| **Файловый сервер** | 8081 | Хранилище артефактов и моделей         |
| **Агент ClearML**   | —    | Рабочий процесс, выполняющий задачи ML |

***

## Ключевые особенности

* **Отслеживание экспериментов без кода** — добавьте 2 строки кода, чтобы автоматически захватывать всё
* **Автоматическое логирование** — метрики, параметры, модели, вывод консоли, графики, изображения
* **Интеграция с Git** — автоматический захват git-коммита, diff и незакоммиченных изменений
* **Управление данными** — версионированные датасеты с отслеживанием происхождения
* **Реестр моделей** — хранение, версионирование и публикация ML-моделей
* **Оркестрация пайплайнов** — создание и запуск многошаговых ML-пайплайнов
* **Удалённое выполнение** — постановка экспериментов в очередь и запуск на удалённых GPU-воркерах (ClearML Agent)
* **Оптимизация гиперпараметров** — автоматическая HPO с обучением на основе популяции
* **Мониторинг ресурсов** — мониторинг GPU/CPU/RAM для каждого эксперимента
* **Самостоятельный хостинг или облако** — запустите свой сервер или используйте хостинговую платформу ClearML

***

## Настройка Clore.ai

### Вариант 1 — Полностью self-hosted сервер

Запустите сервер ClearML на Clore.ai для полного контроля.

### Шаг 1 — Выберите сервер

| Сценарий использования       | Рекомендуется | VRAM  | ОЗУ    |
| ---------------------------- | ------------- | ----- | ------ |
| Только сервер (без обучения) | CPU-инстанс   | —     | 8 ГБ+  |
| Сервер + обучение            | RTX 3080      | 10 ГБ | 16 ГБ  |
| Полный MLOps-кластер         | Несколько GPU | —     | 32 ГБ+ |

### Шаг 2 — Арендуйте сервер на Clore.ai

1. Перейдите на [маркетплейсе clore.ai](https://clore.ai) → **Маркетплейс**
2. Для **сервера** подходят CPU-инстансы
3. Для **воркеров обучения**: GPU-инстансы (RTX 3090, 4090, A100)
4. Откройте порты: **22**, **8008**, **8081**
5. Убедитесь, что **≥ 50 ГБ диска** для артефактов экспериментов

### Шаг 3 — Разверните с Docker Compose

Создайте `docker-compose.yml`:

```yaml
version: "3.6"

services:
  apiserver:
    image: allegroai/clearml:latest
    restart: unless-stopped
    volumes:
      - /opt/clearml/logs:/var/log/clearml
      - /opt/clearml/config:/opt/clearml/config
      - /opt/clearml/data/fileserver:/mnt/fileserver
    environment:
      CLEARML_MONGODB_SERVICE_HOST: mongo
      CLEARML_MONGODB_SERVICE_PORT: 27017
      CLEARML_ELASTICSEARCH_SERVICE_HOST: elasticsearch
      CLEARML_ELASTICSEARCH_SERVICE_PORT: 9200
      CLEARML_REDIS_SERVICE_HOST: redis
      CLEARML_REDIS_SERVICE_PORT: 6379
    ports:
      - "8008:8008"
    depends_on:
      - mongo
      - elasticsearch
      - redis

  webserver:
    image: allegroai/clearml-webserver:latest
    restart: unless-stopped
    ports:
      - "8081:80"
    environment:
      CLEARML_API_HOST: http://localhost:8008

  fileserver:
    image: allegroai/clearml-fileserver:latest
    restart: unless-stopped
    volumes:
      - /opt/clearml/data/fileserver:/mnt/fileserver
    ports:
      - "8081:8081"

  mongo:
    image: mongo:4.4
    restart: unless-stopped
    volumes:
      - /opt/clearml/data/mongo:/data/db
    command: --setParameter internalQueryMaxBlockingSortMemoryUsageBytes=196100200

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.6
    restart: unless-stopped
    environment:
      ES_JAVA_OPTS: "-Xms512m -Xmx2048m"
      bootstrap.memory_lock: "true"
      cluster.name: "clearml"
      discovery.type: "single-node"
      http.publish_host: "$CLEARML_HOST_IP"
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - /opt/clearml/data/elastic:/usr/share/elasticsearch/data

  redis:
    image: redis:6
    restart: unless-stopped
    volumes:
      - /opt/clearml/data/redis:/data

networks:
  default:
    name: clearml_network
```

Запустите стек:

```bash
mkdir -p /opt/clearml/{logs,config,data/{fileserver,mongo,elastic,redis}}

# Укажите публичный IP вашего сервера
export CLEARML_HOST_IP=<your-server-ip>

docker-compose up -d
```

{% hint style="warning" %}
Сервер ClearML требует около 4 ГБ ОЗУ для полного стека (MongoDB + Elasticsearch + Redis + API server + WebUI). Убедитесь, что ваш инстанс на Clore.ai имеет достаточно ОЗУ.
{% endhint %}

### Вариант 2 — Использовать ClearML Hosted (бесплатно)

Для отслеживания экспериментов без запуска собственного сервера используйте бесплатный hosted-план:

```bash
# Установите SDK
pip install clearml

# Настройте с hosted-сервером
clearml-init
# Введите: https://api.clear.ml, когда появится запрос на API host
# Получите учётные данные здесь: https://app.clear.ml/settings/workspace-configuration
```

***

## Доступ к интерфейсу

### Веб-панель

```
http://<server-ip>:8081
```

Учётные данные по умолчанию: создайте аккаунт при первом входе.

### API-сервер

```
http://<server-ip>:8008
```

### Через SSH

```bash
ssh root@<server-ip> -p 22
```

***

## Интеграция SDK

### Установка

```bash
pip install clearml
```

### Первоначальная настройка

```bash
clearml-init
```

Введите URL вашего сервера (`http://<server-ip>:8008`) и API-учётные данные с панели управления.

Или настройте программно:

```python
from clearml import Task

Task.set_credentials(
    api_host="http://<server-ip>:8008",
    web_host="http://<server-ip>:8081",
    files_host="http://<server-ip>:8081",
    key="YOUR_ACCESS_KEY",
    secret="YOUR_SECRET_KEY"
)
```

***

## Отслеживание экспериментов

### Минимальная интеграция (2 строки)

```python
from clearml import Task

# Инициализируйте задачу — это автоматически захватит ВСЁ
task = Task.init(project_name="MyProject", task_name="experiment-001")

# Ваш существующий код обучения — изменений не требуется
import torch
import torch.nn as nn

model = nn.Linear(10, 1)
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)

for epoch in range(10):
    loss = torch.tensor(1.0 / (epoch + 1))
    # ClearML автоматически обнаружит и залогирует loss при использовании стандартных фреймворков
    print(f"Epoch {epoch}, Loss: {loss.item():.4f}")

task.close()
```

### Ручное логирование метрик

```python
from clearml import Task, Logger

task = Task.init(project_name="MyProject", task_name="manual-logging-demo")
logger = task.get_logger()

for epoch in range(50):
    train_loss = 1.0 / (epoch + 1)
    val_accuracy = 0.95 - 0.5 / (epoch + 1)

    # Логируйте скаляры
    logger.report_scalar("Loss", "train", value=train_loss, iteration=epoch)
    logger.report_scalar("Accuracy", "validation", value=val_accuracy, iteration=epoch)

    # Логируйте learning rate
    logger.report_scalar("Learning Rate", "lr", value=0.001 * 0.9**epoch, iteration=epoch)

"Обучение завершено!"
task.close()
```

### Отслеживание гиперпараметров

```python
from clearml import Task

task = Task.init(project_name="HPO-Demo", task_name="run-001")

# Подключите гиперпараметры — они будут автоматически залогированы и доступны для удалённого переопределения
params = {
    "learning_rate": 0.001,
    "batch_size": 32,
    "num_layers": 4,
    "dropout": 0.3,
    "optimizer": "adam",
    "epochs": 100,
}
params = task.connect(params)  # Теперь их можно переопределять через ClearML HPO

print(f"Training with lr={params['learning_rate']}, batch={params['batch_size']}")
```

***

## Управление данными

```python
from clearml import Dataset

# Создайте версионированный датасет
dataset = Dataset.create(
    dataset_name="my-training-data",
    dataset_project="MyProject",
    dataset_version="1.0",
)

# Добавьте файлы
dataset.add_files(path="/data/images/", recursive=True)
dataset.add_files(path="/data/labels.csv")

# Загрузите на сервер ClearML
dataset.upload()
dataset.finalize()
print(f"Dataset ID: {dataset.id}")

# Позже: используйте датасет в экспериментах
dataset = Dataset.get(dataset_name="my-training-data", dataset_version="1.0")
local_path = dataset.get_local_copy()
print(f"Dataset at: {local_path}")
```

***

## Реестр моделей

```python
from clearml import Task, OutputModel, InputModel
import torch

task = Task.init(project_name="ModelRegistry", task_name="training-run")

# После обучения зарегистрируйте модель
model = torch.nn.Linear(100, 10)
torch.save(model.state_dict(), "my_model.pt")

# Зарегистрируйте выходную модель
output_model = OutputModel(task=task, name="MyModel-v1")
output_model.update_weights("my_model.pt")
output_model.publish()  # Пометить как готовую к использованию

print(f"Model registered: {output_model.id}")

# В развертывании: загружайте модель по имени
input_model = InputModel(model_id="<model-id-from-dashboard>")
local_model_path = input_model.get_local_copy()
state_dict = torch.load(local_model_path)
```

***

## Оркестрация пайплайнов

```python
from clearml.automation import PipelineController

def step_preprocess(dataset_id: str) -> str:
    """Шаг предварительной обработки данных."""
    from clearml import Task, Dataset
    task = Task.init(task_name="step-preprocess")
    # ... логика предварительной обработки
    return "processed_data_id"

def step_train(data_id: str, lr: float = 0.001) -> str:
    """Шаг обучения модели."""
    from clearml import Task
    task = Task.init(task_name="step-train")
    # ... логика обучения
    return "model_id"

def step_evaluate(model_id: str) -> float:
    """Шаг оценки модели."""
    from clearml import Task
    task = Task.init(task_name="step-evaluate")
    # ... логика оценки
    return 0.95

# Постройте пайплайн
pipe = PipelineController(
    name="ML-Training-Pipeline",
    project="MyPipelines",
    version="1.0"
)

pipe.add_function_step(
    name="preprocess",
    function=step_preprocess,
    function_kwargs={"dataset_id": "raw-data-id"},
    function_return=["processed_id"],
)

pipe.add_function_step(
    name="train",
    parents=["preprocess"],
    function=step_train,
    function_kwargs={"data_id": "${preprocess.processed_id}"},
    function_return=["model_id"],
    execution_queue="gpu-queue",  # Запуск на GPU-воркере
)

pipe.add_function_step(
    name="evaluate",
    parents=["train"],
    function=step_evaluate,
    function_kwargs={"model_id": "${train.model_id}"},
    function_return=["accuracy"],
)

pipe.start()
pipe.wait()
"Пайплайн завершён!"
```

***

## Агент ClearML (воркер)

Запустите ClearML Agent на GPU-сервере для выполнения заданий из очереди:

```bash
# Установите агент
pip install clearml-agent

# Настройте (используются те же учётные данные, что и для SDK)
clearml-agent init

# Запустите воркер на GPU
clearml-agent daemon --queue "gpu-queue" --gpus 0,1

# Запустите воркер с изоляцией Docker (рекомендуется)
clearml-agent daemon \
    --queue "gpu-queue" \
    --docker pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime \
    --gpus all
```

На Clore.ai поднимите несколько GPU-узлов как ClearML-агенты, чтобы создать распределённый вычислительный кластер.

***

## Оптимизация гиперпараметров

```python
from clearml.automation import (
    HyperParameterOptimizer,
    UniformParameterRange,
    DiscreteParameterValues,
    GridSearch,
)

optimizer = HyperParameterOptimizer(
    base_task_id="<task-id-to-optimize>",
    hyper_parameters=[
        UniformParameterRange("General/learning_rate", min_value=1e-5, max_value=1e-2, step_size=1e-5),
        DiscreteParameterValues("General/batch_size", values=[16, 32, 64, 128]),
        DiscreteParameterValues("General/optimizer", values=["adam", "sgd", "adamw"]),
    ],
    objective_metric_title="Accuracy",
    objective_metric_series="validation",
    objective_metric_sign="max",  # Максимизировать точность на валидации
    max_number_of_concurrent_tasks=4,
    optimizer_class=GridSearch,
    execution_queue="gpu-queue",
    total_max_jobs=50,
)

optimizer.start()
top_exps = optimizer.get_top_experiments(top_k=3)
print("Лучшие эксперименты:", top_exps)
```

***

## Мониторинг и оповещения

```python
from clearml import Task

task = Task.init(project_name="Production", task_name="monitoring")

# Установите теги задачи для удобной фильтрации
task.add_tags(["production", "v2.1", "gpu"])

# Автоматически логируйте системные метрики — достаточно инициализировать задачу
# ClearML автоматически собирает: CPU, RAM, загрузку GPU, VRAM GPU

# Добавьте собственный мониторинг скаляров
logger = task.get_logger()
import time
for i in range(100):
    gpu_util = 85 + (i % 10)
    logger.report_scalar("GPU", "utilization_%", value=gpu_util, iteration=i)
    time.sleep(1)
```

***

## Устранение неполадок

{% hint style="warning" %}
**Elasticsearch не запускается** — Установите `vm.max_map_count=262144` на хосте: `sysctl -w vm.max_map_count=262144`. Добавьте в `/etc/sysctl.conf` для сохранения после перезагрузки.
{% endhint %}

{% hint style="warning" %}
**Не удаётся подключиться к серверу** — Проверьте, что порты 8008 и 8081 открыты в настройках портов Clore.ai. Проверьте `docker ps` чтобы убедиться, что все контейнеры запущены.
{% endhint %}

{% hint style="info" %}
**Эксперименты не отображаются в UI** — Проверьте, что `CLEARML_API_HOST` в вашей конфигурации SDK указывает на `http://<server-ip>:8008`, а не на localhost.
{% endhint %}

{% hint style="info" %}
**Недостаточно места на диске** — ClearML хранит все артефакты локально. Настройте хранилище S3/GCS или увеличьте выделение диска в Clore.ai.
{% endhint %}

| Проблема                        | Исправьте                                                                     |
| ------------------------------- | ----------------------------------------------------------------------------- |
| MongoDB: отказано в подключении | Проверьте контейнер mongo: `docker logs clearml_mongo_1`                      |
| Задача застряла в очереди       | Убедитесь, что ClearML Agent запущен и подключен к очереди                    |
| Медленный интерфейс             | Elasticsearch требуется время на индексацию — подождите 2–3 мин после запуска |
| API 401: Доступ неавторизован   | Сгенерируйте заново API-учётные данные в веб-панели ClearML                   |

***

## Сценарии использования для исследователей, работающих с GPU

* **Отслеживайте запуски обучения** — больше никогда не теряйте гиперпараметры и результаты
* **Сравнивайте эксперименты** — сравнение метрик бок о бок в интерфейсе
* **Воспроизводите результаты** — ClearML автоматически сохраняет git-коммит и diff кода
* **Делитесь результатами** — участники команды видят все эксперименты в общем дашборде
* **Удалённые задачи на GPU** — отправляйте задачи обучения в очередь с ноутбука, запускайте на GPU-узлах Clore.ai
* **Автоматическая оптимизация гиперпараметров** — выполняйте поиск гиперпараметров параллельно на нескольких GPU-узлах

***

## Связанные инструменты

* [MLflow](/guides/guides_v2-ru/mlops-i-razvertyvanie/mlflow.md) — альтернатива трекингу экспериментов
* [Weights & Biases](https://wandb.ai/) — облачный трекинг ML-экспериментов
* [Ray](https://www.ray.io/) — распределённое обучение ML и HPO

***

*ClearML на Clore.ai сочетает отслеживание экспериментов с управлением вычислениями на GPU — предоставляя вашей ML-команде полноценные возможности MLOps без привязки к облачному вендору.*

***

## Рекомендации по GPU для Clore.ai

| Сценарий использования          | Рекомендуемый GPU | Оценочная стоимость на Clore.ai             |
| ------------------------------- | ----------------- | ------------------------------------------- |
| Разработка/тестирование         | RTX 3090 (24 ГБ)  | $0.07–0.21/гпу/ч                            |
| Обучение в продакшене           | RTX 4090 (24 ГБ)  | $0.14–0.42/гпу/ч                            |
| Эксперименты в крупном масштабе | A100 80 ГБ        | [голое железо](https://clore.ai/bare-metal) |

> 💡 Все примеры в этом руководстве можно развернуть на [Clore.ai](https://clore.ai/marketplace) GPU-серверах. Просматривайте доступные GPU и арендуйте по часам — без обязательств, с полным root-доступом.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/mlops-i-razvertyvanie/clearml.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.