> 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 Experiment-Tracking, 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 gesamten ML-Workflow: von Datenverwaltung und Experiment-Tracking bis hin zu Modellregistrierung, automatisierten Pipelines und verteilter Aufgabenausführung auf GPU-Clustern.

| Eigenschaft    | Wert                                                      |
| -------------- | --------------------------------------------------------- |
| **Kategorie**  | MLOps / Experiment-Tracking                               |
| **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-Orchestrator               |
| **Web-UI**         | 8081 | Browserbasiertes Dashboard         |
| **API-Server**     | 8008 | REST-API für SDK und Agents        |
| **Dateiserver**    | 8081 | Speicher für Artefakte und Modelle |
| **ClearML Agent**  | —    | Worker, der ML-Aufgaben ausführt   |

***

## Hauptfunktionen

* **Experiment-Tracking ohne Code** — füge 2 Zeilen Code hinzu, um alles automatisch zu erfassen
* **Automatisches Logging** — Metriken, Parameter, Modelle, Konsolenausgabe, Diagramme, Bilder
* **Git-Integration** — erfasst automatisch den Git-Commit, Diff und nicht gespeicherte Änderungen
* **Datenverwaltung** — versionierte Datensätze mit Herkunftsverfolgung
* **Modellregister** — ML-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 ausführen (ClearML Agent)
* **Hyperparameter-Optimierung** — automatisierte HPO mit populationsbasiertem Training
* **Ressourcenüberwachung** — GPU/CPU/RAM-Überwachung pro Experiment
* **Selbst gehostet oder in der Cloud** — betreiben Sie Ihren eigenen Server oder nutzen Sie die gehostete Plattform von ClearML

***

## Clore.ai-Einrichtung

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

Betreiben Sie den ClearML-Server auf Clore.ai für volle Kontrolle.

### Schritt 1 — Wählen Sie 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 — Mieten Sie 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. Ports öffnen: **22**, **8008**, **8081**
5. Stelle sicher **>= 50 GB Festplattenspeicher** für Experiment-Artefakte

### Schritt 3 — Bereitstellen 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
```

Starten Sie den Stack:

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

# Legen Sie die öffentliche IP Ihres Servers fest
export CLEARML_HOST_IP=<Ihre-Server-IP>

docker-compose up -d
```

{% hint style="warning" %}
Der ClearML-Server benötigt für den gesamten Stack etwa 4 GB RAM (MongoDB + Elasticsearch + Redis + API-Server + WebUI). Stellen Sie sicher, dass Ihre Clore.ai-Instanz über genügend RAM verfügt.
{% endhint %}

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

Für das Experiment-Tracking ohne eigenen Server nutzen Sie den kostenlosen gehosteten Plan:

```bash
# SDK installieren
pip install clearml

# Mit gehostetem Server konfigurieren
clearml-init
# Geben Sie ein: https://api.clear.ml  wenn Sie nach dem API-Host gefragt werden
# Zugangsdaten abrufen von: https://app.clear.ml/settings/workspace-configuration
```

***

## Zugriff auf die Oberfläche

### Web-Dashboard

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

Standardzugangsdaten: Erstellen Sie Ihr 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
```

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

Oder programmatisch 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="YOUR_ACCESS_KEY",
    secret="YOUR_SECRET_KEY"
)
```

***

## Experimente tracken

### Minimale Integration (2 Zeilen)

```python
from clearml import Task

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

# Ihr bestehender Training-Code — keine Änderungen erforderlich
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 und protokolliert den Loss automatisch, wenn Standard-Frameworks verwendet werden
    print(f"Epoch {epoch}, Loss: {loss.item():.4f}")

task.close()
```

### Manuelles Metrik-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)

    # Skalare 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)

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

### Hyperparameter-Tracking

```python
from clearml import Task

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

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

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

***

## Datenverwaltung

```python
from clearml import Dataset

# Einen versionierten Datensatz erstellen
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 den ClearML-Server hochladen
dataset.upload()
dataset.finalize()
print(f"Datensatz-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}")
```

***

## Model 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")

# Ausgabemodell 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 nach 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:
    """Schritt zur Datenvorverarbeitung."""
    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:
    """Schritt zum Trainieren des Modells."""
    from clearml import Task
    task = Task.init(task_name="step-train")
    # ... Trainingslogik
    return "model_id"

def step_evaluate(model_id: str) -> float:
    """Schritt zur Modellauswertung."""
    from clearml import Task
    task = Task.init(task_name="step-evaluate")
    # ... Auswertungslogik
    return 0.95

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

***

## ClearML Agent (Worker)

Führen Sie einen ClearML Agent auf einem GPU-Server aus, um Aufgaben aus der Warteschlange auszuführen:

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

# Konfigurieren (verwendet dieselben Zugangsdaten wie das SDK)
clearml-agent init

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

# Worker mit Docker-Isolation starten (empfohlen)
clearml-agent daemon \
    --queue "gpu-queue" \
    --docker pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime \
    --gpus all
```

Starten Sie auf Clore.ai mehrere GPU-Knoten als ClearML Agents, um einen verteilten Rechencluster 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 & Warnungen

```python
from clearml import Task

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

# Task-Tags für einfaches Filtern festlegen
task.add_tags(["production", "v2.1", "gpu"])

# Systemmetriken automatisch protokollieren — einfach die Aufgabe initialisieren
# ClearML erfasst automatisch: CPU-, RAM- und GPU-Auslastung sowie 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** — Setzen Sie `vm.max_map_count=262144` auf dem Host: `sysctl -w vm.max_map_count=262144`. Fügen Sie es hinzu zu `/etc/sysctl.conf` für die Persistenz.
{% endhint %}

{% hint style="warning" %}
**Keine Verbindung zum Server möglich** — Prüfen Sie, ob die Ports 8008 und 8081 in den Port-Einstellungen von Clore.ai offen sind. Überprüfen Sie `docker ps` um sicherzustellen, dass alle Container ausgeführt werden.
{% endhint %}

{% hint style="info" %}
**Experimente werden nicht in der UI angezeigt** — Prüfen Sie, ob `CLEARML_API_HOST` in Ihrer SDK-Konfiguration auf `http://<server-ip>:8008`und nicht auf localhost verweist.
{% endhint %}

{% hint style="info" %}
**Kein Speicherplatz mehr** — ClearML speichert alle Artefakte lokal. Konfigurieren Sie S3/GCS-Speicher oder erhöhen Sie die Festplattenzuweisung in Clore.ai.
{% endhint %}

| Problem                                       | Fix                                                                                      |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| MongoDB-Verbindung verweigert                 | Überprüfen Sie den Mongo-Container: `docker logs clearml_mongo_1`                        |
| Aufgabe in der Warteschlange hängen geblieben | Stellen Sie sicher, dass der ClearML Agent läuft und mit der Warteschlange verbunden ist |
| Langsame Benutzeroberfläche                   | Elasticsearch benötigt Zeit zum Indizieren — warten Sie 2–3 Min. nach dem Start          |
| API 401 Nicht autorisiert                     | Erneuern Sie die API-Zugangsdaten im ClearML-Web-Dashboard                               |

***

## Anwendungsfälle für GPU-Forscher

* **Trainingsläufe nachverfolgen** — verlieren Sie nie wieder Hyperparameter oder Ergebnisse
* **Experimente vergleichen** — Metrikvergleich nebeneinander in der Benutzeroberfläche
* **Ergebnisse reproduzieren** — ClearML erfasst Git-Commit + Code-Diff automatisch
* **Ergebnisse teilen** — Mitarbeitende sehen alle Experimente im gemeinsamen Dashboard
* **Remote-GPU-Jobs** — Trainingsjobs vom Laptop aus in die Warteschlange stellen, auf Clore.ai-GPU-Knoten ausführen
* **Automatisierte HPO** — Hyperparametersuche parallel über mehrere GPU-Knoten ausführen

***

## Verwandte Tools

* [MLflow](/guides/guides_v2-de/mlops-and-bereitstellung/mlflow.md) — Alternative für Experiment-Tracking
* [Weights & Biases](https://wandb.ai/) — gehostetes ML-Experiment-Tracking
* [Ray](https://www.ray.io/) — verteiltes ML-Training und HPO

***

*ClearML auf Clore.ai kombiniert Experiment-Tracking mit GPU-Computing-Management — und bietet Ihrem ML-Team volle MLOps-Funktionen ohne Lock-in bei einem Cloud-Anbieter.*

***

## GPU-Empfehlungen für Clore.ai

| Anwendungsfall                | Empfohlene GPU   | Geschätzte Kosten bei Clore.ai            |
| ----------------------------- | ---------------- | ----------------------------------------- |
| Entwicklung/Testen            | RTX 3090 (24 GB) | 0,07–0,21 $/GPU/Stunde                    |
| Produktionstraining           | RTX 4090 (24 GB) | 0,14–0,42 $/GPU/Stunde                    |
| Experimente im großen Maßstab | A100 80GB        | [Bare Metal](https://clore.ai/bare-metal) |

> 💡 Alle Beispiele in diesem Leitfaden können bereitgestellt werden auf [Clore.ai](https://clore.ai/marketplace) GPU-Servern. 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, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-de/mlops-and-bereitstellung/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.