# 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 访问。


---

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

```
GET https://docs.clore.ai/guides/guides_v2-zh/mlops-yu-bu-shu/clearml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.