ClearML

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.

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

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:

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

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.

Option 2 — ClearML Hosted verwenden (kostenlos)

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

# 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

ssh root@<server-ip> -p 22

---

SDK-Integration

Installation

pip install clearml

Erstkonfiguration

clearml-init

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

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

---

Experimente tracken

Minimale Integration (2 Zeilen)

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

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

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

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

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

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:

# 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

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

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

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.

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.

Experimente werden nicht in der UI angezeigt — Prüfen Sie, ob CLEARML_API_HOST in Ihrer SDK-Konfiguration auf http://<server-ip>:8008und nicht auf localhost verweist.

Kein Speicherplatz mehr — ClearML speichert alle Artefakte lokal. Konfigurieren Sie S3/GCS-Speicher oder erhöhen Sie die Festplattenzuweisung in Clore.ai.

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 — Alternative für Experiment-Tracking

• Weights & Biases — gehostetes ML-Experiment-Tracking

• Ray — 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

💡 Alle Beispiele in diesem Leitfaden können bereitgestellt werden auf Clore.ai GPU-Servern. Durchsuchen Sie verfügbare GPUs und mieten Sie stundenweise — keine Verpflichtungen, voller Root-Zugriff.