ClearML

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.

Ü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
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 → 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:

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:

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

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.

Option 2 — Nutze ClearML Hosted (kostenlos)

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

# 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

ssh root@<server-ip> -p 22

---

SDK-Integration

Installation

pip install clearml

Erstkonfiguration

clearml-init

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

Oder programmgesteuert konfigurieren:

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)

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

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

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

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

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

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:

# 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

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

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

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.

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.

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.

Festplattenspeicher erschöpft — ClearML speichert alle Artefakte lokal. Konfiguriere S3/GCS-Speicher oder erhöhe die Festplattenzuweisung in Clore.ai.

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 — Alternative zur Experimentverfolgung

• Weights & Biases — gehostete ML-Experimentverfolgung

• Ray — 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 GPU-Server. Durchsuchen Sie verfügbare GPUs und mieten Sie stundenweise — keine Verpflichtungen, voller Root-Zugriff.