> 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-de/mlops-and-bereitstellung/clearml.md).

# ClearML

{% hint style="info" %}
**ClearML** (früher Trains) ist eine Open-Source-MLOps-Plattform für Experimentverfolgung, Datenversionierung, Modellverwaltung, Pipeline-Orchestrierung und Verwaltung von Rechenressourcen – alles in einer einheitlichen Suite.
{% endhint %}

## Überblick

ClearML ist eine umfassende Plattform zur Verwaltung des ML-Lebenszyklus von Allegro AI. Sie erfasst automatisch Experimentparameter, Metriken, Artefakte und Code mit minimalen Codeänderungen. ClearML unterstützt den vollständigen ML-Workflow: von Datenmanagement und Experimentverfolgung bis hin zu Modell-Registry, automatisierten Pipelines und verteilter Ausführung von Aufgaben auf GPU-Clustern.

| Eigenschaft    | Wert                                                      |
| -------------- | --------------------------------------------------------- |
| **Kategorie**  | MLOps / Experimentverfolgung                              |
| **Entwickler** | Allegro AI                                                |
| **Lizenz**     | Apache 2.0                                                |
| **GitHub**     | [allegroai/clearml](https://github.com/allegroai/clearml) |
| **Sterne**     | 5,5K+                                                     |
| **Docker Hub** | `allegroai/clearml`                                       |
| **Ports**      | 22 (SSH), 8008 (API-Server), 8081 (Web-UI)                |

***

## Architektur

ClearML besteht aus vier Hauptkomponenten:

| Komponente         | Port | Beschreibung                       |
| ------------------ | ---- | ---------------------------------- |
| **ClearML Server** | —    | Backend-Koordinator                |
| **Web-UI**         | 8081 | Browser-basiertes Dashboard        |
| **API-Server**     | 8008 | REST-API für SDK und Agents        |
| **File Server**    | 8081 | Speicher für Artefakte und Modelle |
| **ClearML Agent**  | —    | Worker, der ML-Aufgaben ausführt   |

***

## Wesentliche Merkmale

* **Zero-Code-Experimentverfolgung** — füge 2 Codezeilen hinzu, um alles automatisch zu erfassen
* **Automatisches Logging** — Metriken, Parameter, Modelle, Konsolenausgabe, Plots, Bilder
* **Git-Integration** — automatisches Erfassen des Git-Commits, Diffs und unkommittierter Änderungen
* **Datenmanagement** — versionierte Datensätze mit Lineage-Tracking
* **Modell-Registry** — Modelle speichern, versionieren und bereitstellen
* **Pipeline-Orchestrierung** — mehrstufige ML-Pipelines erstellen und ausführen
* **Remote-Ausführung** — Experimente in die Warteschlange stellen und auf entfernten GPU-Workern (ClearML Agent) ausführen
* **Hyperparameter-Optimierung** — automatisierte HPO mit populationsbasierendem Training
* **Ressourcenüberwachung** — GPU/CPU/RAM-Überwachung pro Experiment
* **Selbst gehostet oder Cloud** — betreibe deinen eigenen Server oder nutze ClearMLs gehostete Plattform

***

## Clore.ai Einrichtung

### Option 1 — Vollständig selbst gehosteter Server

Führe den ClearML-Server auf Clore.ai aus, um volle Kontrolle zu haben.

### Schritt 1 — Wähle einen Server

| Anwendungsfall              | Empfohlen    | VRAM  | RAM    |
| --------------------------- | ------------ | ----- | ------ |
| Nur Server (kein Training)  | CPU-Instanz  | —     | 8 GB+  |
| Server + Training           | RTX 3080     | 10 GB | 16 GB  |
| Vollständiger MLOps-Cluster | Mehrere GPUs | —     | 32 GB+ |

### Schritt 2 — Miete einen Server auf Clore.ai

1. Gehe zu [clore.ai](https://clore.ai) → **Marktplatz**
2. Für die **Server-** Komponente: CPU-Instanzen funktionieren gut
3. Für **Training-Worker**: GPU-Instanzen (RTX 3090, 4090, A100)
4. Offene Ports: **22**, **8008**, **8081**
5. Stelle sicher **≥ 50 GB Festplatte** für Experiment-Artefakte

### Schritt 3 — Deployment mit Docker Compose

Erstelle `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
```

Starte den Stack:

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

# Setze die öffentliche IP deines Servers
export CLEARML_HOST_IP=<deine-server-ip>

docker-compose up -d
```

{% hint style="warning" %}
Der ClearML-Server benötigt \~4 GB RAM für den vollständigen Stack (MongoDB + Elasticsearch + Redis + API-Server + WebUI). Stelle sicher, dass deine Clore.ai-Instanz ausreichend RAM hat.
{% endhint %}

### Option 2 — Nutze ClearML Hosted (kostenlos)

Für Experimentverfolgung ohne eigenen Server nutze den kostenlosen gehosteten Plan:

```bash
# SDK installieren
pip install clearml

# Mit gehostetem Server konfigurieren
clearml-init
# Gib bei der Abfrage für den API-Host ein: https://api.clear.ml
# Hol dir Anmeldedaten von: https://app.clear.ml/settings/workspace-configuration
```

***

## Zugriff auf die Oberfläche

### Web-Dashboard

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

Standard-Anmeldedaten: Erstelle dein Konto beim ersten Login.

### API-Server

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

### Per SSH

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

***

## SDK-Integration

### Installation

```bash
pip install clearml
```

### Erstkonfiguration

```bash
clearml-init
```

Gib deine Server-URL ein (`http://<server-ip>:8008`) und die API-Zugangsdaten aus dem Dashboard.

Oder programmgesteuert konfigurieren:

```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="DEIN_ACCESS_KEY",
    secret="DEIN_SECRET_KEY"
)
```

***

## Experimente verfolgen

### Minimale Integration (2 Zeilen)

```python
from clearml import Task

# Task initialisieren — dies erfasst ALLES automatisch
task = Task.init(project_name="MyProject", task_name="experiment-001")

# Dein vorhandener Trainingscode — keine Änderungen nötig
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 erkennt automatisch Verlust (loss) und protokolliert ihn bei Verwendung gängiger Frameworks
    print(f"Epoch {epoch}, Loss: {loss.item():.4f}")

task.close()
```

### Manuelles Metriken-Logging

```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)

    # Skalars protokollieren
    logger.report_scalar("Loss", "train", value=train_loss, iteration=epoch)
    logger.report_scalar("Accuracy", "validation", value=val_accuracy, iteration=epoch)

    # Lernrate protokollieren
    logger.report_scalar("Learning Rate", "lr", value=0.001 * 0.9**epoch, iteration=epoch)

print("Training abgeschlossen!")
task.close()
```

### Hyperparameter-Tracking

```python
from clearml import Task

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

# Verbinde Hyperparameter — automatisch protokolliert und remote überschreibbar
params = {
    "learning_rate": 0.001,
    "batch_size": 32,
    "num_layers": 4,
    "dropout": 0.3,
    "optimizer": "adam",
    "epochs": 100,
}
params = task.connect(params)  # Jetzt vom ClearML HPO überschreibbar

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

***

## Datenmanagement

```python
from clearml import Dataset

# Erstelle einen versionierten Datensatz
dataset = Dataset.create(
    dataset_name="my-training-data",
    dataset_project="MyProject",
    dataset_version="1.0",
)

# Dateien hinzufügen
dataset.add_files(path="/data/images/", recursive=True)
dataset.add_files(path="/data/labels.csv")

# Auf ClearML-Server hochladen
dataset.upload()
dataset.finalize()
print(f"Dataset ID: {dataset.id}")

# Später: den Datensatz in Experimenten verwenden
dataset = Dataset.get(dataset_name="my-training-data", dataset_version="1.0")
local_path = dataset.get_local_copy()
print(f"Datensatz unter: {local_path}")
```

***

## Modell-Registry

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

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

# Nach dem Training das Modell registrieren
model = torch.nn.Linear(100, 10)
torch.save(model.state_dict(), "my_model.pt")

# Output-Modell registrieren
output_model = OutputModel(task=task, name="MyModel-v1")
output_model.update_weights("my_model.pt")
output_model.publish()  # Als einsatzbereit markieren

print(f"Modell registriert: {output_model.id}")

# In der Bereitstellung: Modell per Namen laden
input_model = InputModel(model_id="<model-id-from-dashboard>")
local_model_path = input_model.get_local_copy()
state_dict = torch.load(local_model_path)
```

***

## Pipeline-Orchestrierung

```python
from clearml.automation import PipelineController

def step_preprocess(dataset_id: str) -> str:
    """Datenvorverarbeitungsschritt."""
    from clearml import Task, Dataset
    task = Task.init(task_name="step-preprocess")
    # ... Vorverarbeitungslogik
    return "processed_data_id"

def step_train(data_id: str, lr: float = 0.001) -> str:
    """Modell-Trainingsschritt."""
    from clearml import Task
    task = Task.init(task_name="step-train")
    # ... Trainingslogik
    return "model_id"

def step_evaluate(model_id: str) -> float:
    """Modell-Evaluationsschritt."""
    from clearml import Task
    task = Task.init(task_name="step-evaluate")
    # ... Evaluationslogik
    return 0.95

# Pipeline bauen
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",  # Auf GPU-Worker ausführen
)

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("Pipeline abgeschlossen!")
```

***

## ClearML Agent (Worker)

Führe einen ClearML Agent auf einem GPU-Server aus, um wartende Experimente zu bearbeiten:

```bash
# Agent installieren
pip install clearml-agent

# Konfigurieren (verwendet die gleichen Anmeldedaten wie das SDK)
clearml-agent init

# Worker auf GPU starten
clearml-agent daemon --queue "gpu-queue" --gpus 0,1

# Worker mit Docker-Isolierung starten (empfohlen)
clearml-agent daemon \
    --queue "gpu-queue" \
    --docker pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime \
    --gpus all
```

Auf Clore.ai kannst du mehrere GPU-Knoten als ClearML-Agents starten, um ein verteiltes Compute-Cluster zu erstellen.

***

## Hyperparameter-Optimierung

```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",  # Validierungsgenauigkeit maximieren
    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("Beste Experimente:", top_exps)
```

***

## Überwachung & Alerts

```python
from clearml import Task

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

# Setze Task-Tags zur einfachen Filterung
task.add_tags(["production", "v2.1", "gpu"])

# Systemmetriken automatisch protokollieren — einfach die Task initialisieren
# ClearML erfasst automatisch: CPU-, RAM-, GPU-Auslastung, GPU-VRAM

# Benutzerdefiniertes Scalar-Monitoring hinzufügen
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)
```

***

## Fehlerbehebung

{% hint style="warning" %}
**Elasticsearch startet nicht** — Setze `vm.max_map_count=262144` auf dem Host: `sysctl -w vm.max_map_count=262144`. Füge hinzu zu `/etc/sysctl.conf` für Persistenz.
{% endhint %}

{% hint style="warning" %}
**Kann keine Verbindung zum Server herstellen** — Überprüfe, ob die Ports 8008 und 8081 in den Clore.ai-Port-Einstellungen offen sind. Prüfe `docker ps` um sicherzustellen, dass alle Container laufen.
{% endhint %}

{% hint style="info" %}
**Experimente erscheinen nicht in der UI** — Prüfe, dass `CLEARML_API_HOST` in deiner SDK-Konfiguration auf `http://<server-ip>:8008`, nicht auf localhost zeigt.
{% endhint %}

{% hint style="info" %}
**Festplattenspeicher erschöpft** — ClearML speichert alle Artefakte lokal. Konfiguriere S3/GCS-Speicher oder erhöhe die Festplattenzuweisung in Clore.ai.
{% endhint %}

| Problem                         | Behebung                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| MongoDB-Verbindung abgelehnt    | Prüfe den mongo-Container: `docker logs clearml_mongo_1`                            |
| Task hängt in der Warteschlange | Stelle sicher, dass der ClearML Agent läuft und mit der Warteschlange verbunden ist |
| Langsame UI                     | Elasticsearch braucht Zeit zum Indexieren — warte 2–3 Minuten nach dem Start        |
| API 401 Unauthorized            | Erzeuge API-Zugangsdaten neu im ClearML-Web-Dashboard                               |

***

## Anwendungsfälle für GPU-Forschende

* **Trainingsläufe verfolgen** — verliere niemals wieder Hyperparameter oder Ergebnisse
* **Experimente vergleichen** — nebeneinander Metrikvergleiche in der UI
* **Ergebnisse reproduzieren** — ClearML erfasst automatisch Git-Commit + Code-Diff
* **Ergebnisse teilen** — Mitarbeitende sehen alle Experimente im gemeinsamen Dashboard
* **Remotegpu-Jobs** — Trainingsjobs vom Laptop in die Warteschlange stellen und auf Clore.ai GPU-Knoten ausführen
* **Automatisierte HPO** — Hyperparameter-Suche parallel über mehrere GPU-Knoten ausführen

***

## Verwandte Tools

* [MLflow](/guides/guides_v2-de/mlops-and-bereitstellung/mlflow.md) — Alternative zur Experimentverfolgung
* [Weights & Biases](https://wandb.ai/) — gehostete ML-Experimentverfolgung
* [Ray](https://www.ray.io/) — verteiltes ML-Training und HPO

***

*ClearML auf Clore.ai kombiniert Experimentverfolgung mit GPU-Compute-Management — und bietet deinem ML-Team vollständige MLOps-Fähigkeiten ohne Bindung an einen Cloud-Anbieter.*

***

## Clore.ai GPU-Empfehlungen

| Anwendungsfall             | Empfohlene GPU  | Geschätzte Kosten auf Clore.ai |
| -------------------------- | --------------- | ------------------------------ |
| Entwicklung/Test           | RTX 3090 (24GB) | \~$0.12/GPU/Stunde             |
| Produktions-Training       | RTX 4090 (24GB) | \~$0.70/GPU/Stunde             |
| Groß angelegte Experimente | A100 80GB       | \~$1.20/GPU/Stunde             |

> 💡 Alle Beispiele in diesem Leitfaden können bereitgestellt werden auf [Clore.ai](https://clore.ai/marketplace) GPU-Server. Durchsuchen Sie verfügbare GPUs und mieten Sie stundenweise — keine Verpflichtungen, voller Root-Zugriff.


---

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

```
GET https://docs.clore.ai/guides/guides_v2-de/mlops-and-bereitstellung/clearml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.