> 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-razvyortyvanie/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 Server), 8081 (Web UI)                |

***

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

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

| Компонент          | Порт | Описание                            |
| ------------------ | ---- | ----------------------------------- |
| **ClearML Server** | —    | Координатор бэкенда                 |
| **Web UI**         | 8081 | Панель управления в браузере        |
| **API Server**     | 8008 | REST API для SDK и агентов          |
| **File Server**    | 8081 | Хранилище артефактов и моделей      |
| **ClearML Agent**  | —    | Воркeр, который выполняет ML-задачи |

***

## Ключевые функции

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

***

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

### Вариант 1 — Полный собственный сервер

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

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

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

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

1. Перейдите на [clore.ai](https://clore.ai) → **Маркетплейс**
2. Для **компонента: CPU-инстансы подходят** компонента: 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=<ip-вашего-сервера>

docker-compose up -d
```

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

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

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

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

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

***

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

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

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

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

### API Server

```
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="ВАШ_ACCESS_KEY",
    secret="ВАШ_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)

    # Логирование скорости обучения
    logger.report_scalar("Learning Rate", "lr", value=0.001 * 0.9**epoch, iteration=epoch)

print("Обучение завершено!")
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"Обучение с 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"ID датасета: {dataset.id}")

# Позже: использовать датасет в экспериментах
dataset = Dataset.get(dataset_name="my-training-data", dataset_version="1.0")
local_path = dataset.get_local_copy()
print(f"Датасет находится по адресу: {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"Модель зарегистрирована: {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()
print("Пайплайн завершён!")
```

***

## ClearML Agent (Воркeр)

Запустите 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.1.0-cuda12.1-cudnn8-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 запущен и подключён к очереди                             |
| Медленный UI                    | Elasticsearchу требуется время для индексирования — подождите 2–3 минуты после запуска |
| API 401 Unauthorized            | Перегенерируйте API-учётные данные в веб-панели ClearML                                |

***

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

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

***

## Сопутствующие инструменты

* [MLflow](/guides/guides_v2-ru/mlops-i-razvyortyvanie/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 (24GB)   | \~$0.12/гпу/час                   |
| Продакшн обучение             | RTX 4090 (24GB)   | \~$0.70/гпу/час                   |
| Крупномасштабные эксперименты | A100 80GB         | \~$1.20/гпу/час                   |

> 💡 Все примеры в этом руководстве можно развернуть на [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-razvyortyvanie/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.