ClearML

ClearML (anciennement Trains) est une plateforme MLOps open source pour le suivi des expériences, la gestion des versions des données, la gestion des modèles, l'orchestration des pipelines et la gestion des ressources de calcul — le tout dans une suite unifiée.

Aperçu

ClearML est une plateforme complète de gestion du cycle de vie ML d'Allegro AI. Elle capture automatiquement les paramètres d'expérience, les métriques, les artefacts et le code avec des modifications de code minimes. ClearML prend en charge l'ensemble du flux de travail ML : de la gestion des données et du suivi des expériences au registre de modèles, aux pipelines automatisés et à l'exécution distribuée des tâches sur des clusters GPU.

Propriété	Valeur
Catégorie	MLOps / Suivi des expériences
Développeur	Allegro AI
Licence	Apache 2.0
GitHub	allegroai/clearml
Étoiles	5,5 k+
Docker Hub	allegroai/clearml
Ports	22 (SSH), 8008 (serveur API), 8081 (interface web)

---

Architecture

ClearML se compose de quatre composants principaux :

Composant	Port	Description
Serveur ClearML	—	Coordinateur du backend
Interface web	8081	Tableau de bord basé sur le navigateur
Serveur API	8008	API REST pour le SDK et les agents
Serveur de fichiers	8081	Stockage des artefacts et des modèles
Agent ClearML	—	Worker qui exécute les tâches ML

---

Caractéristiques clés

• Suivi des expériences sans code — ajoutez 2 lignes de code pour tout capturer automatiquement

• Journalisation automatique — métriques, paramètres, modèles, sortie console, graphiques, images

• Intégration Git — capture automatiquement le commit Git, le diff et les modifications non validées

• Gestion des données — jeux de données versionnés avec suivi de l'origine

• Registre de modèles — stockez, versionnez et servez des modèles ML

• Orchestration des pipelines — créez et exécutez des pipelines ML en plusieurs étapes

• Exécution à distance — mettez les expériences en file d'attente et exécutez-les sur des workers GPU distants (ClearML Agent)

• Optimisation des hyperparamètres — HPO automatisée avec entraînement basé sur la population

• Surveillance des ressources — surveillance GPU/CPU/RAM par expérience

• Auto-hébergé ou cloud — exécutez votre propre serveur ou utilisez la plateforme hébergée de ClearML

---

Configuration de Clore.ai

Option 1 — Serveur entièrement auto-hébergé

Exécutez le serveur ClearML sur Clore.ai pour un contrôle total.

Étape 1 — Choisir un serveur

Cas d’utilisation	Recommandé	VRAM	RAM
Serveur uniquement (pas d'entraînement)	Instance CPU	—	8 Go+
Serveur + entraînement	RTX 3080	10 Go	16 Go
Cluster MLOps complet	Plusieurs GPU	—	32 Go+

Étape 2 — Louer un serveur sur Clore.ai

1. Accédez à clore.ai → Place de marché

2. Pour le serveur composant : les instances CPU conviennent parfaitement

3. Pour workers d'entraînement: instances GPU (RTX 3090, 4090, A100)

4. Ouvrir les ports : 22, 8008, 8081

5. Assurez-vous que ≥ 50 Go de disque pour les artefacts d'expérience

Étape 3 — Déployer avec Docker Compose

Créez un fichier 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

Démarrez la pile :

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

# Définissez l'adresse IP publique de votre serveur
export CLEARML_HOST_IP=<your-server-ip>

docker-compose up -d

Le serveur ClearML nécessite environ 4 Go de RAM pour la pile complète (MongoDB + Elasticsearch + Redis + serveur API + WebUI). Assurez-vous que votre instance Clore.ai dispose de suffisamment de RAM.

Option 2 — Utiliser ClearML hébergé (gratuit)

Pour le suivi des expériences sans faire tourner de serveur, utilisez l'offre hébergée gratuite :

# Installer le SDK
pip install clearml

# Configurer avec le serveur hébergé
clearml-init
# Saisissez : https://api.clear.ml lorsque l'hôte API vous est demandé
# Obtenez les identifiants sur : https://app.clear.ml/settings/workspace-configuration

---

Accéder à l'interface

Tableau de bord Web

http://<server-ip>:8081

Identifiants par défaut : créez votre compte lors de la première connexion.

Serveur API

http://<server-ip>:8008

Via SSH

ssh root@<server-ip> -p 22

---

Intégration du SDK

Installation

pip install clearml

Configuration initiale

clearml-init

Entrez l'URL de votre serveur (http://<server-ip>:8008) et les identifiants API depuis le tableau de bord.

Ou configurez par programme :

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

---

Suivi des expériences

Intégration minimale (2 lignes)

from clearml import Task

# Initialiser la tâche — cela capture TOUT automatiquement
task = Task.init(project_name="MyProject", task_name="experiment-001")

# Votre code d'entraînement existant — aucune modification nécessaire
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 détecte automatiquement et journalise la perte si vous utilisez des frameworks standards
    print(f"Époque {epoch}, perte : {loss.item():.4f}")

task.close()

Journalisation manuelle des métriques

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)

    # Journaliser les scalaires
    logger.report_scalar("Loss", "train", value=train_loss, iteration=epoch)
    logger.report_scalar("Accuracy", "validation", value=val_accuracy, iteration=epoch)

    # Journaliser le taux d'apprentissage
    logger.report_scalar("Learning Rate", "lr", value=0.001 * 0.9**epoch, iteration=epoch)

print("Entraînement terminé !")
task.close()

Suivi des hyperparamètres

from clearml import Task

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

# Connecter les hyperparamètres — journalisés automatiquement et modifiables à distance
params = {
    "learning_rate": 0.001,
    "batch_size": 32,
    "num_layers": 4,
    "dropout": 0.3,
    "optimizer": "adam",
    "epochs": 100,
}
params = task.connect(params)  # Désormais modifiable par ClearML HPO

print(f"Entraînement avec lr={params['learning_rate']}, lot={params['batch_size']}")

---

Gestion des données

from clearml import Dataset

# Créer un jeu de données versionné
dataset = Dataset.create(
    dataset_name="my-training-data",
    dataset_project="MyProject",
    dataset_version="1.0",
)

# Ajouter des fichiers
dataset.add_files(path="/data/images/", recursive=True)
dataset.add_files(path="/data/labels.csv")

# Téléverser vers le serveur ClearML
dataset.upload()
dataset.finalize()
print(f"ID du jeu de données : {dataset.id}")

# Plus tard : utiliser le jeu de données dans des expériences
dataset = Dataset.get(dataset_name="my-training-data", dataset_version="1.0")
local_path = dataset.get_local_copy()
print(f"Jeu de données à : {local_path}")

---

Registre des modèles

from clearml import Task, OutputModel, InputModel
import torch

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

# Après l'entraînement, enregistrez le modèle
model = torch.nn.Linear(100, 10)
torch.save(model.state_dict(), "my_model.pt")

# Enregistrer le modèle de sortie
output_model = OutputModel(task=task, name="MyModel-v1")
output_model.update_weights("my_model.pt")
output_model.publish()  # Marquer comme prêt à l'emploi

print(f"Modèle enregistré : {output_model.id}")

# En déploiement : charger le modèle par nom
input_model = InputModel(model_id="<model-id-from-dashboard>")
local_model_path = input_model.get_local_copy()
state_dict = torch.load(local_model_path)

---

Orchestration des pipelines

from clearml.automation import PipelineController

def step_preprocess(dataset_id: str) -> str:
    """Étape de prétraitement des données."""
    from clearml import Task, Dataset
    task = Task.init(task_name="step-preprocess")
    # ... logique de prétraitement
    return "processed_data_id"

def step_train(data_id: str, lr: float = 0.001) -> str:
    """Étape d'entraînement du modèle."""
    from clearml import Task
    task = Task.init(task_name="step-train")
    # ... logique d'entraînement
    return "model_id"

def step_evaluate(model_id: str) -> float:
    """Étape d'évaluation du modèle."""
    from clearml import Task
    task = Task.init(task_name="step-evaluate")
    # ... logique d'évaluation
    return 0.95

# Construire le pipeline
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",  # Exécuter sur un worker 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("Pipeline terminé !")

---

Agent ClearML (worker)

Exécutez un ClearML Agent sur un serveur GPU pour exécuter les expériences en file d'attente :

# Installer l'agent
pip install clearml-agent

# Configurer (utilise les mêmes identifiants que le SDK)
clearml-agent init

# Démarrer le worker sur GPU
clearml-agent daemon --queue "gpu-queue" --gpus 0,1

# Démarrer le worker avec isolation Docker (recommandé)
clearml-agent daemon \
    --queue "gpu-queue" \
    --docker pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime \
    --gpus all

Sur Clore.ai, lancez plusieurs nœuds GPU en tant qu'agents ClearML pour créer un cluster de calcul distribué.

---

Optimisation des hyperparamètres

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",  # Maximiser la précision de validation
    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("Meilleures expériences :", top_exps)

---

Surveillance et alertes

from clearml import Task

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

# Définir des tags de tâche pour faciliter le filtrage
task.add_tags(["production", "v2.1", "gpu"])

# Journaliser automatiquement les métriques système — il suffit d'initialiser la tâche
# ClearML capture automatiquement : utilisation CPU, RAM, GPU, VRAM GPU

# Ajouter une surveillance scalaire personnalisée
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)

---

Dépannage

Elasticsearch ne parvient pas à démarrer — Définissez vm.max_map_count=262144 sur l'hôte : sysctl -w vm.max_map_count=262144. Ajoutez à /etc/sysctl.conf pour la persistance.

Impossible de se connecter au serveur — Vérifiez que les ports 8008 et 8081 sont ouverts dans les paramètres de ports de Clore.ai. Vérifiez docker ps pour vous assurer que tous les conteneurs sont en cours d'exécution.

Les expériences n'apparaissent pas dans l'interface — Vérifiez que CLEARML_API_HOST dans votre configuration SDK pointe vers http://<server-ip>:8008, et non localhost.

Espace disque insuffisant — ClearML stocke tous les artefacts localement. Configurez un stockage S3/GCS ou augmentez l'allocation de disque dans Clore.ai.

Problème	Correctif
Connexion MongoDB refusée	Vérifiez le conteneur mongo : docker logs clearml_mongo_1
Tâche bloquée dans la file d’attente	Assurez-vous que ClearML Agent est en cours d’exécution et connecté à la file d’attente
Interface utilisateur lente	Elasticsearch a besoin de temps pour indexer — attendez 2–3 min après le démarrage
API 401 Non autorisé	Régénérez les identifiants API dans le tableau de bord web ClearML

---

Cas d'utilisation pour les chercheurs GPU

• Suivre les exécutions d'entraînement — ne perdez plus jamais les hyperparamètres ni les résultats

• Comparer les expériences — comparaison des métriques côte à côte dans l'interface

• Reproduire les résultats — ClearML capture automatiquement le commit git + le diff du code

• Partager les résultats — les collaborateurs voient toutes les expériences dans le tableau de bord partagé

• Tâches GPU à distance — mettez les tâches d'entraînement en file d'attente depuis votre ordinateur portable, exécutez-les sur des nœuds GPU Clore.ai

• HPO automatisé — lancez une recherche d'hyperparamètres en parallèle sur plusieurs nœuds GPU

---

Outils associés

• MLflow — alternative de suivi d'expériences

• Weights & Biases — suivi d'expériences ML hébergé

• Ray — entraînement ML distribué et HPO

---

ClearML sur Clore.ai combine le suivi d'expériences avec la gestion du calcul GPU — offrant à votre équipe ML des capacités MLOps complètes sans dépendance à un fournisseur cloud.

---

Recommandations GPU Clore.ai

Cas d’utilisation	GPU recommandé	Coût estimé sur Clore.ai
Développement/Test	RTX 3090 (24 Go)	0,07–0,21 $/gpu/h
Entraînement en production	RTX 4090 (24 Go)	0,14–0,42 $/gpu/h
Expériences à grande échelle	A100 80 Go	bare metal

💡 Tous les exemples de ce guide peuvent être déployés sur Clore.ai des serveurs GPU. Parcourez les GPU disponibles et louez à l'heure — sans engagement, accès root complet.