> 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-fr/mlops-et-deploiement/clearml.md).

# ClearML

{% hint style="info" %}
**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.
{% endhint %}

## 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](https://github.com/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](https://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`:

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

Démarrez la pile :

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

{% hint style="warning" %}
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.
{% endhint %}

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

```bash
# 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

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

***

## Intégration du SDK

### Installation

```bash
pip install clearml
```

### Configuration initiale

```bash
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 :

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

***

## Suivi des expériences

### Intégration minimale (2 lignes)

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

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

    # 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

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

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

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

```python
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 :

```bash
# 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

```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",  # 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

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

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="info" %}
**Espace disque insuffisant** — ClearML stocke tous les artefacts localement. Configurez un stockage S3/GCS ou augmentez l'allocation de disque dans Clore.ai.
{% endhint %}

| 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](/guides/guides_v2-fr/mlops-et-deploiement/mlflow.md) — alternative de suivi d'expériences
* [Weights & Biases](https://wandb.ai/) — suivi d'expériences ML hébergé
* [Ray](https://www.ray.io/) — 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](https://clore.ai/bare-metal) |

> 💡 Tous les exemples de ce guide peuvent être déployés sur [Clore.ai](https://clore.ai/marketplace) des serveurs GPU. Parcourez les GPU disponibles et louez à l'heure — sans engagement, accès root complet.


---

# 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-fr/mlops-et-deploiement/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.