> 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-zh/mlops-yu-bu-shu/clearml.md).

# 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) |
| **星标**         | 5.5K+                                                     |
| **Docker Hub** | `allegroai/clearml`                                       |
| **端口**         | 22（SSH）、8008（API 服务器）、8081（Web UI）                        |

***

## 架构

ClearML 由四个主要组件组成：

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

***

## 主要特性

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

***

## Clore.ai 设置

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

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

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

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

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

1. 前往 [clore.ai](https://clore.ai) → **市场**
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 Server 运行完整堆栈（MongoDB + Elasticsearch + Redis + API server + WebUI）大约需要 4 GB 内存。请确保你的 Clore.ai 实例有足够的内存。
{% endhint %}

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

如果你想在不运行服务器的情况下进行实验跟踪，可以使用免费的托管方案：

```bash
# 安装 SDK
pip install clearml

# 使用托管服务器进行配置
clearml-init
# 提示时输入：https://api.clear.ml  作为 API host
# 凭据可从此处获取：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)

训练完成！
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】【：】【“】【t_af78516c】【：】【“】【"""模型评估步骤。"""
    """模型评估步骤。"""
    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()
流水线完成！
```

***

## 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.11.0-cuda12.8-cudnn9-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、RAM、GPU 利用率和 GPU VRAM

# 添加自定义标量监控
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 正在运行并已连接到队列               |
| 界面响应缓慢        | Elasticsearch 需要时间进行索引 — 启动后等待 2–3 分钟      |
| API 401 未授权   | 在 ClearML Web 仪表板中重新生成 API 凭据              |

***

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

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

***

## 相关工具

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

***

*ClearML 在 Clore.ai 上将实验跟踪与 GPU 计算管理相结合 — 为你的 ML 团队提供完整的 MLOps 能力，而无需受制于云厂商锁定。*

***

## Clore.ai GPU 推荐

| 使用场景  | 推荐 GPU         | Clore.ai 预计成本                     |
| ----- | -------------- | --------------------------------- |
| 开发/测试 | RTX 3090（24GB） | $0.07–0.21/gpu/hr                 |
| 生产训练  | RTX 4090（24GB） | $0.14–0.42/gpu/hr                 |
| 大规模实验 | A100 80GB      | [裸机](https://clore.ai/bare-metal) |

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


---

# 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-zh/mlops-yu-bu-shu/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.