> 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-es/mlops-y-despliegue/clearml.md).

# ClearML

{% hint style="info" %}
**ClearML** (anteriormente Trains) es una plataforma de MLOps de código abierto para el seguimiento de experimentos, el versionado de datos, la gestión de modelos, la orquestación de pipelines y la gestión de recursos de cómputo — todo en una suite unificada.
{% endhint %}

## Descripción general

ClearML es una plataforma integral de gestión del ciclo de vida de ML de Allegro AI. Captura automáticamente los parámetros, métricas, artefactos y código de los experimentos con cambios mínimos en el código. ClearML admite todo el flujo de trabajo de ML: desde la gestión de datos y el seguimiento de experimentos hasta el registro de modelos, los pipelines automatizados y la ejecución distribuida de tareas en clústeres GPU.

| Propiedad         | Valor                                                     |
| ----------------- | --------------------------------------------------------- |
| **Categoría**     | MLOps / Seguimiento de experimentos                       |
| **Desarrollador** | Allegro AI                                                |
| **Licencia**      | Apache 2.0                                                |
| **GitHub**        | [allegroai/clearml](https://github.com/allegroai/clearml) |
| **Estrellas**     | 5.5K+                                                     |
| **Docker Hub**    | `allegroai/clearml`                                       |
| **Puertos**       | 22 (SSH), 8008 (servidor API), 8081 (interfaz web)        |

***

## Arquitectura

ClearML consta de cuatro componentes principales:

| Componente               | Puerto | Descripción                            |
| ------------------------ | ------ | -------------------------------------- |
| **Servidor ClearML**     | —      | Coordinador del backend                |
| **Interfaz web**         | 8081   | Panel de control basado en navegador   |
| **Servidor API**         | 8008   | API REST para el SDK y los agentes     |
| **Servidor de archivos** | 8081   | Almacenamiento de artefactos y modelos |
| **ClearML Agent**        | —      | Trabajador que ejecuta tareas de ML    |

***

## Características clave

* **Seguimiento de experimentos sin código** — agrega 2 líneas de código para capturarlo todo automáticamente
* **Registro automático** — métricas, parámetros, modelos, salida de consola, gráficos, imágenes
* **Integración con Git** — captura automáticamente el commit de Git, el diff y los cambios no confirmados
* **Gestión de datos** — conjuntos de datos versionados con seguimiento de linaje
* **Registro de modelos** — almacena, versiona y sirve modelos de ML
* **Orquestación de pipelines** — crea y ejecuta pipelines de ML de varios pasos
* **Ejecución remota** — encola experimentos y ejecútalos en trabajadores GPU remotos (ClearML Agent)
* **Optimización de hiperparámetros** — HPO automatizada con entrenamiento basado en población
* **Monitorización de recursos** — monitorización de GPU/CPU/RAM por experimento
* **Autoalojado o en la nube** — ejecuta tu propio servidor o usa la plataforma alojada de ClearML

***

## Configuración de Clore.ai

### Opción 1 — Servidor autoalojado completo

Ejecuta el servidor de ClearML en Clore.ai para tener control total.

### Paso 1 — Elige un servidor

| Caso de uso                       | Recomendado      | VRAM  | RAM    |
| --------------------------------- | ---------------- | ----- | ------ |
| Solo servidor (sin entrenamiento) | Instancia de CPU | —     | 8 GB+  |
| Servidor + entrenamiento          | RTX 3080         | 10 GB | 16 GB  |
| Clúster MLOps completo            | Múltiples GPUs   | —     | 32 GB+ |

### Paso 2 — Alquila un servidor en Clore.ai

1. Ve a [clore.ai](https://clore.ai) → **Marketplace**
2. Para el **servidor** componente: las instancias de CPU funcionan bien
3. Para **trabajadores de entrenamiento**: instancias GPU (RTX 3090, 4090, A100)
4. Abrir puertos: **22**, **8008**, **8081**
5. Asegúrate de **≥ 50 GB de disco** para artefactos de experimentos

### Paso 3 — Despliega con Docker Compose

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

Inicia el stack:

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

# Establece la IP pública de tu servidor
export CLEARML_HOST_IP=<your-server-ip>

docker-compose up -d
```

{% hint style="warning" %}
ClearML Server requiere \~4 GB de RAM para el stack completo (MongoDB + Elasticsearch + Redis + servidor API + interfaz web). Asegúrate de que tu instancia de Clore.ai tenga RAM suficiente.
{% endhint %}

### Opción 2 — Usa ClearML alojado (gratis)

Para el seguimiento de experimentos sin ejecutar un servidor, usa el plan alojado gratuito:

```bash
# Instala el SDK
pip install clearml

# Configura con el servidor alojado
clearml-init
# Ingresa: https://api.clear.ml cuando se te solicite el host de la API
# Obtén las credenciales en: https://app.clear.ml/settings/workspace-configuration
```

***

## Acceso a la interfaz

### Panel web

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

Credenciales predeterminadas: crea tu cuenta en el primer inicio de sesión.

### Servidor API

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

### Vía SSH

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

***

## Integración del SDK

### Instalación

```bash
pip install clearml
```

### Configuración inicial

```bash
clearml-init
```

Introduce la URL de tu servidor (`http://<server-ip>:8008`) y las credenciales de API desde el panel.

O configúralo programáticamente:

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

***

## Seguimiento de experimentos

### Integración mínima (2 líneas)

```python
from clearml import Task

# Inicializa la tarea — esto captura TODO automáticamente
task = Task.init(project_name="MyProject", task_name="experiment-001")

# Tu código de entrenamiento existente — no se necesitan cambios
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 detecta automáticamente y registra la pérdida si usas frameworks estándar
    print(f"Época {epoch}, Pérdida: {loss.item():.4f}")

task.close()
```

### Registro manual de métricas

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

    # Registra escalares
    logger.report_scalar("Pérdida", "entrenamiento", value=train_loss, iteration=epoch)
    logger.report_scalar("Precisión", "validación", value=val_accuracy, iteration=epoch)

    # Registra la tasa de aprendizaje
    logger.report_scalar("Tasa de aprendizaje", "lr", value=0.001 * 0.9**epoch, iteration=epoch)

¡Entrenamiento completo!
task.close()
```

### Seguimiento de hiperparámetros

```python
from clearml import Task

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

# Conecta los hiperparámetros — se registran automáticamente y se pueden sobrescribir de forma remota
params = {
    "learning_rate": 0.001,
    "batch_size": 32,
    "num_layers": 4,
    "dropout": 0.3,
    "optimizer": "adam",
    "epochs": 100,
}
params = task.connect(params)  # Ahora puede ser sobrescrito por ClearML HPO

print(f"Entrenando con lr={params['learning_rate']}, lote={params['batch_size']}")
```

***

## Gestión de datos

```python
from clearml import Dataset

# Crea un conjunto de datos versionado
dataset = Dataset.create(
    dataset_name="my-training-data",
    dataset_project="MyProject",
    dataset_version="1.0",
)

# Añade archivos
dataset.add_files(path="/data/images/", recursive=True)
dataset.add_files(path="/data/labels.csv")

# Sube al servidor ClearML
dataset.upload()
dataset.finalize()
print(f"ID del conjunto de datos: {dataset.id}")

# Más tarde: usa el conjunto de datos en experimentos
dataset = Dataset.get(dataset_name="my-training-data", dataset_version="1.0")
local_path = dataset.get_local_copy()
print(f"Conjunto de datos en: {local_path}")
```

***

## Registro de modelos

```python
from clearml import Task, OutputModel, InputModel
import torch

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

# Después del entrenamiento, registra el modelo
model = torch.nn.Linear(100, 10)
torch.save(model.state_dict(), "my_model.pt")

# Registra el modelo de salida
output_model = OutputModel(task=task, name="MyModel-v1")
output_model.update_weights("my_model.pt")
output_model.publish()  # Marcar como listo para usar

print(f"Modelo registrado: {output_model.id}")

# En despliegue: carga el modelo por nombre
input_model = InputModel(model_id="<model-id-from-dashboard>")
local_model_path = input_model.get_local_copy()
state_dict = torch.load(local_model_path)
```

***

## Orquestación de pipelines

```python
from clearml.automation import PipelineController

def step_preprocess(dataset_id: str) -> str:
    """Paso de preprocesamiento de datos."""
    from clearml import Task, Dataset
    task = Task.init(task_name="step-preprocess")
    # ... lógica de preprocesamiento
    return "processed_data_id"

def step_train(data_id: str, lr: float = 0.001) -> str:
    """Paso de entrenamiento del modelo."""
    from clearml import Task
    task = Task.init(task_name="step-train")
    # ... lógica de entrenamiento
    return "model_id"

def step_evaluate(model_id: str) -> float:
    """Paso de evaluación del modelo."""
    from clearml import Task
    task = Task.init(task_name="step-evaluate")
    # ... lógica de evaluación
    return 0.95

# Construye el 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",  # Ejecutar en un trabajador 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()
¡Pipeline completo!
```

***

## ClearML Agent (trabajador)

Ejecuta un ClearML Agent en un servidor GPU para ejecutar los experimentos en cola:

```bash
# Instala el agente
pip install clearml-agent

# Configura (usa las mismas credenciales que el SDK)
clearml-agent init

# Inicia el trabajador en GPU
clearml-agent daemon --queue "gpu-queue" --gpus 0,1

# Inicia el trabajador con aislamiento de Docker (recomendado)
clearml-agent daemon \
    --queue "gpu-queue" \
    --docker pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime \
    --gpus all
```

En Clore.ai, levanta múltiples nodos GPU como agentes ClearML para crear un clúster de cómputo distribuido.

***

## Optimización de hiperparámetros

```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="Precisión",
    objective_metric_series="validación",
    objective_metric_sign="max",  # Maximiza la precisión de validación
    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("Mejores experimentos:", top_exps)
```

***

## Monitoreo y alertas

```python
from clearml import Task

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

# Establece etiquetas de la tarea para filtrar fácilmente
task.add_tags(["production", "v2.1", "gpu"])

# Registra métricas del sistema automáticamente — solo inicializa la tarea
# ClearML captura automáticamente: CPU, RAM, utilización de GPU, VRAM de GPU

# Añade monitorización escalar personalizada
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)
```

***

## Solución de problemas

{% hint style="warning" %}
**Elasticsearch no se inicia** — Establece `vm.max_map_count=262144` en el host: `sysctl -w vm.max_map_count=262144`. Añade a `/etc/sysctl.conf` para que sea persistente.
{% endhint %}

{% hint style="warning" %}
**No se puede conectar al servidor** — Verifica que los puertos 8008 y 8081 estén abiertos en la configuración de puertos de Clore.ai. Comprueba `docker ps` para asegurarte de que todos los contenedores estén en ejecución.
{% endhint %}

{% hint style="info" %}
**Los experimentos no aparecen en la interfaz.** — Verifica que `CLEARML_API_HOST` en la configuración de tu SDK apunta a `http://<server-ip>:8008`, no a localhost.
{% endhint %}

{% hint style="info" %}
**Sin espacio en disco** — ClearML almacena todos los artefactos localmente. Configura almacenamiento S3/GCS o aumenta la asignación de disco en Clore.ai.
{% endhint %}

| Problema                     | Solución                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------ |
| Conexión a MongoDB rechazada | Comprueba el contenedor de mongo: `docker logs clearml_mongo_1`                |
| Tarea atascada en la cola    | Asegúrate de que ClearML Agent esté en ejecución y conectado a la cola         |
| Interfaz de usuario lenta    | Elasticsearch necesita tiempo para indexar — espera 2–3 min después de iniciar |
| API 401 No autorizado        | Regenera las credenciales de la API en el panel web de ClearML                 |

***

## Casos de uso para investigadores de GPU

* **Haz seguimiento de las ejecuciones de entrenamiento** — nunca vuelvas a perder hiperparámetros ni resultados
* **Compara experimentos** — comparación de métricas lado a lado en la interfaz de usuario
* **Reproduce resultados** — ClearML captura automáticamente el commit de git + el diff del código
* **Comparte resultados** — los colaboradores ven todos los experimentos en el panel compartido
* **Trabajos remotos en GPU** — encola trabajos de entrenamiento desde el portátil, ejecútalos en nodos GPU de Clore.ai
* **HPO automatizado** — ejecuta búsqueda de hiperparámetros en paralelo en múltiples nodos GPU

***

## Herramientas relacionadas

* [MLflow](/guides/guides_v2-es/mlops-y-despliegue/mlflow.md) — alternativa de seguimiento de experimentos
* [Weights & Biases](https://wandb.ai/) — seguimiento de experimentos de ML alojado
* [Ray](https://www.ray.io/) — entrenamiento distribuido de ML y HPO

***

*ClearML en Clore.ai combina el seguimiento de experimentos con la gestión de cómputo GPU — brindando a tu equipo de ML capacidades completas de MLOps sin dependencia de un proveedor de nube.*

***

## Recomendaciones de GPU para Clore.ai

| Caso de uso                 | GPU recomendada | Costo estimado en Clore.ai                |
| --------------------------- | --------------- | ----------------------------------------- |
| Desarrollo/Pruebas          | RTX 3090 (24GB) | $0.07–0.21/gpu/hr                         |
| Entrenamiento en producción | RTX 4090 (24GB) | $0.14–0.42/gpu/hr                         |
| Experimentos a gran escala  | A100 80GB       | [bare metal](https://clore.ai/bare-metal) |

> 💡 Todos los ejemplos de esta guía pueden desplegarse en [Clore.ai](https://clore.ai/marketplace) servidores GPU. Explora las GPUs disponibles y alquila por hora: sin compromisos, acceso root completo.


---

# 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-es/mlops-y-despliegue/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.