# ClearML

{% hint style="info" %}
**ClearML** （前称 Trains）是一个开源的 MLOps 平台，用于实验跟踪、数据版本管理、模型管理、流水线编排和计算资源管理 —— 所有功能整合在一个统一套件中。
{% endhint %}

## 概览

ClearML 是由 Allegro AI 提供的全面机器学习生命周期管理平台。它通过最少的代码更改自动捕获实验参数、指标、工件和代码。ClearML 支持完整的机器学习工作流：从数据管理与实验跟踪到模型注册、自动化流水线以及在 GPU 集群上的分布式任务执行。

| 属性             | 数值                                                        |
| -------------- | --------------------------------------------------------- |
| **类别**         | MLOps / 实验跟踪                                              |
| **开发者**        | Allegro AI                                                |
| **许可证**        | Apache 2.0                                                |
| **GitHub**     | [allegroai/clearml](https://github.com/allegroai/clearml) |
| **Star 数**     | 5.5K+                                                     |
| **Docker Hub** | `allegroai/clearml`                                       |
| **端口**         | 22（SSH）、8008（API 服务器）、8081（Web UI）                        |

***

## 架构

ClearML 由四个主要组件组成：

| 组件                | 端口   | 说明                   |
| ----------------- | ---- | -------------------- |
| **ClearML 服务器**   | —    | 后端协调器                |
| **Web UI**        | 8081 | 基于浏览器的仪表板            |
| **API 服务器**       | 8008 | 用于 SDK 和代理的 REST API |
| **文件服务器**         | 8081 | 工件和模型存储              |
| **ClearML Agent** | —    | 执行机器学习任务的工作者         |

***

## 主要功能

* **零代码实验跟踪** — 添加 2 行代码即可自动捕获所有内容
* **自动记录** — 指标、参数、模型、控制台输出、图表、图像
* **Git 集成** — 自动捕获 git 提交、diff 和未提交的更改
* **数据管理** — 带血统追踪的版本化数据集
* **模型注册表** — 存储、版本化并部署机器学习模型
* **流水线编排** — 构建并运行多步骤机器学习流水线
* **远程执行** — 将实验排入队列并在远程 GPU 工作节点上运行（ClearML Agent）
* **超参数优化** — 基于种群训练的自动化 HPO
* **资源监控** — 按实验监控 GPU/CPU/RAM
* **自托管或云端** — 运行您自己的服务器或使用 ClearML 的托管平台

***

## Clore.ai 设置

### 选项 1 — 完整自托管服务器

在 Clore.ai 上运行 ClearML 服务器以获得完全控制权。

### 步骤 1 — 选择服务器

| 使用场景        | 推荐       | 显存（VRAM） | 内存（RAM） |
| ----------- | -------- | -------- | ------- |
| 仅服务器（不训练）   | CPU 实例   | —        | 8 GB+   |
| 服务器 + 训练    | RTX 3080 | 10 GB    | 16 GB   |
| 完整 MLOps 集群 | 多 GPU    | —        | 32 GB+  |

### 步骤 2 — 在 Clore.ai 上租用服务器

1. 前往 [clore.ai](https://clore.ai) → **市场（Marketplace）**
2. 对于 **服务器** 组件：CPU 实例即可满足需求
3. 对于 **训练工作节点**：GPU 实例（RTX 3090、4090、A100）
4. 打开端口： **22**, **8008**, **8081**
5. 确保 **≥ 50 GB 磁盘空间** 用于实验工件

### 步骤 3 — 使用 Docker Compose 部署

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

启动堆栈：

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

# 设置服务器的公网 IP
export CLEARML_HOST_IP=<your-server-ip>

docker-compose up -d
```

{% hint style="warning" %}
ClearML 服务器的完整堆栈（MongoDB + Elasticsearch + Redis + API 服务器 + WebUI）大约需要 \~4 GB RAM。请确保您的 Clore.ai 实例有足够内存。
{% endhint %}

### 选项 2 — 使用 ClearML 托管（免费）

若无需运行服务器即可进行实验跟踪，可使用免费的托管计划：

```bash
# 安装 SDK
pip install clearml

# 使用托管服务器进行配置
clearml-init
# 在提示输入 API 主机时输入： https://api.clear.ml
# 从此处获取凭证： https://app.clear.ml/settings/workspace-configuration
```

***

## 访问界面

### Web 仪表板

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

默认凭据：首次登录时创建您的账户。

### API 服务器

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

### 通过 SSH 访问

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

***

## SDK 集成

### 安装

```bash
pip install clearml
```

### 初始配置

```bash
clearml-init
```

输入您的服务器 URL（`http://<server-ip>:8008`）以及来自仪表板的 API 凭证。

或以编程方式配置：

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

***

## 跟踪实验

### 最小集成（2 行）

```python
from clearml import Task

# 初始化任务 —— 这会自动捕获所有内容
task = Task.init(project_name="MyProject", task_name="experiment-001")

# 您现有的训练代码 —— 无需更改
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 会自动检测并记录 loss
    print(f"Epoch {epoch}, Loss: {loss.item():.4f}")

task.close()
```

### 手动指标记录

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

    # 记录标量
    logger.report_scalar("Loss", "train", value=train_loss, iteration=epoch)
    logger.report_scalar("Accuracy", "validation", value=val_accuracy, iteration=epoch)

    # 记录学习率
    logger.report_scalar("Learning Rate", "lr", value=0.001 * 0.9**epoch, iteration=epoch)

print("训练完成！")
task.close()
```

### 超参数跟踪

```python
from clearml import Task

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

# 连接超参数 —— 自动记录并可远程覆盖
params = {
    "learning_rate": 0.001,
    "batch_size": 32,
    "num_layers": 4,
    "dropout": 0.3,
    "optimizer": "adam",
    "epochs": 100,
}
params = task.connect(params)  # 现在可以被 ClearML HPO 覆盖

print(f"Training with lr={params['learning_rate']}, batch={params['batch_size']}")
```

***

## 数据管理

```python
from clearml import Dataset

# 创建版本化数据集
dataset = Dataset.create(
    dataset_name="my-training-data",
    dataset_project="MyProject",
    dataset_version="1.0",
)

# 添加文件
dataset.add_files(path="/data/images/", recursive=True)
dataset.add_files(path="/data/labels.csv")

# 上传到 ClearML 服务器
dataset.upload()
dataset.finalize()
print(f"Dataset ID: {dataset.id}")

# 稍后：在实验中使用该数据集
dataset = Dataset.get(dataset_name="my-training-data", dataset_version="1.0")
local_path = dataset.get_local_copy()
print(f"Dataset at: {local_path}")
```

***

## 模型注册表

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

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

# 训练后，注册模型
model = torch.nn.Linear(100, 10)
torch.save(model.state_dict(), "my_model.pt")

# 注册输出模型
output_model = OutputModel(task=task, name="MyModel-v1")
output_model.update_weights("my_model.pt")
output_model.publish()  # 标记为可用

print(f"Model registered: {output_model.id}")

# 部署时：按名称加载模型
input_model = InputModel(model_id="<model-id-from-dashboard>")
local_model_path = input_model.get_local_copy()
state_dict = torch.load(local_model_path)
```

***

## 流水线编排

```python
from clearml.automation import PipelineController

def step_preprocess(dataset_id: str) -> str:
    """数据预处理步骤。"""
    from clearml import Task, Dataset
    task = Task.init(task_name="step-preprocess")
    # ... 预处理逻辑
    return "processed_data_id"

def step_train(data_id: str, lr: float = 0.001) -> str:
    """模型训练步骤。"""
    from clearml import Task
    task = Task.init(task_name="step-train")
    # ... 训练逻辑
    return "model_id"

def step_evaluate(model_id: str) -> float:
    """模型评估步骤。"""
    from clearml import Task
    task = Task.init(task_name="step-evaluate")
    # ... 评估逻辑
    return 0.95

# 构建流水线
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",  # 在 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("流水线完成！")
```

***

## ClearML Agent（工作者）

在 GPU 服务器上运行 ClearML Agent 来执行已排队的实验：

```bash
# 安装 agent
pip install clearml-agent

# 配置（使用与 SDK 相同的凭证）
clearml-agent init

# 在 GPU 上启动工作者
clearml-agent daemon --queue "gpu-queue" --gpus 0,1

# 使用 Docker 隔离启动工作者（推荐）
clearml-agent daemon \
    --queue "gpu-queue" \
    --docker pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime \
    --gpus all
```

在 Clore.ai 上，启动多个 GPU 节点作为 ClearML agent 以创建分布式计算集群。

***

## 超参数优化

```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",  # 最大化验证准确率
    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("最佳实验：", top_exps)
```

***

## 监控与告警

```python
from clearml import Task

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

# 为便于筛选设置任务标签
task.add_tags(["production", "v2.1", "gpu"])

# 自动记录系统指标 —— 只需初始化任务即可
# ClearML 自动捕获：CPU、内存、GPU 利用率、GPU 显存

# 添加自定义标量监控
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)
```

***

## 故障排除

{% hint style="warning" %}
**Elasticsearch 启动失败** — 设置 `vm.max_map_count=262144` 在主机上： `sysctl -w vm.max_map_count=262144`。添加到 `/etc/sysctl.conf` 以实现持久化。
{% endhint %}

{% hint style="warning" %}
**无法连接到服务器** — 在 Clore.ai 端口设置中验证 8008 和 8081 端口已打开。检查 `docker ps` 以确保所有容器正在运行。
{% endhint %}

{% hint style="info" %}
**实验未出现在 UI 中** — 检查 `CLEARML_API_HOST` 在您的 SDK 配置中是否指向 `http://<server-ip>:8008`，而非 localhost。
{% endhint %}

{% hint style="info" %}
**磁盘空间不足** — ClearML 将所有工件存储在本地。配置 S3/GCS 存储或在 Clore.ai 中增加磁盘配额。
{% endhint %}

| 问题            | 修复                                         |
| ------------- | ------------------------------------------ |
| MongoDB 连接被拒绝 | 检查 mongo 容器： `docker logs clearml_mongo_1` |
| 任务卡在队列中       | 确保 ClearML Agent 正在运行并连接到队列                |
| UI 响应慢        | Elasticsearch 需要时间建立索引 —— 启动后等待 2–3 分钟     |
| API 401 未授权   | 在 ClearML Web 仪表板中重新生成 API 凭证              |

***

## GPU 研究人员的使用场景

* **跟踪训练运行** — 再也不会丢失超参数或结果
* **比较实验** — 在 UI 中并排比较指标
* **复现结果** — ClearML 自动捕获 git 提交与代码差异
* **共享结果** — 协作者在共享仪表板中可查看所有实验
* **远程 GPU 作业** — 从笔记本将训练作业入队，在 Clore.ai GPU 节点上运行
* **自动化 HPO** — 在多个 GPU 节点上并行运行超参数搜索

***

## 相关工具

* [MLflow](https://docs.clore.ai/guides/guides_v2-zh/mlops-yu-bu-shu/mlflow) — 实验跟踪的替代方案
* [Weights & Biases](https://wandb.ai/) — 托管的机器学习实验跟踪
* [Ray](https://www.ray.io/) — 分布式机器学习训练与 HPO

***

*在 Clore.ai 上使用 ClearML 将实验跟踪与 GPU 计算管理结合 —— 为您的机器学习团队提供完整的 MLOps 能力，且不受云厂商锁定。*

***

## Clore.ai GPU 推荐

| 使用场景  | 推荐 GPU         | 在 Clore.ai 的预计成本 |
| ----- | -------------- | ---------------- |
| 开发/测试 | RTX 3090（24GB） | \~$0.12/每 GPU/小时 |
| 生产训练  | RTX 4090（24GB） | \~$0.70/每 GPU/小时 |
| 大规模实验 | A100 80GB      | \~$1.20/每 GPU/小时 |

> 💡 本指南中的所有示例都可以部署在 [Clore.ai](https://clore.ai/marketplace) GPU 服务器上。浏览可用的 GPU 并按小时租用 — 无需承诺，完全 root 访问。