clearml/clearml · 上手攻略

仓库：clearml/clearml
链接：https://github.com/clearml/clearml
分类：ai
作者：Jay
更新：2026-07-15

这是什么

ClearML 是一个开源的 ML/DL/GenAI 全栈开发与生产平台，涵盖实验管理（Experiment Manager）、数据管理与版本控制（Hyper-Datasets）、MLOps/LLMOps 编排（Agent + Orchestration）、模型服务（Model Serving）、报表与可视化（Reports）五大模块。用作者自己的话说：解决的是"训练生产级深度学习模型这个光荣但混乱的过程"的追踪与管控问题。

核心设计哲学是零摩擦集成：只需在代码里加两行（from clearml import Task + Task.init()），就能自动记录完整的实验环境、代码版本、超参数、输出日志、GPU 利用率等所有信息，无需修改现有训练代码结构。

目前 GitHub Stars 超过 6700，被大量 AI 研究团队和企业用于管理从研究到生产的完整工作流。

解决什么问题

机器学习项目在实际推进中会面临一系列基础设施挑战：

实验混乱：跑了上百次实验，不知道哪个超参数对应哪个结果，代码改了也不知道有没有提升
环境不可复现：队友的代码在自己机器上跑不通，缺少完整的环境记录
算力调度原始：GPU 机器空闲时无法自动排队跑任务，需要人工干预
数据版本缺失：训练数据更新后，无法追踪哪个模型用了哪版数据
模型上线复杂：训练完的模型没有统一途径部署为 API 服务

ClearML 用一套平台把这五件事统一解决，且全部开源可自托管。

快速安装

前置：准备 ClearML Server

使用 ClearML 前需要连接到后端服务，有两种方式：

方式一：使用官方免费托管服务（推荐入门） 1. 访问 https://app.clear.ml 注册免费账号 2. 在 Settings → Workspace → Create credentials 获取 API Key 和 Secret 3. 本地执行 clearml-init，按提示填入凭证

方式二：自托管（企业/隐私需求）

# 使用 Docker 部署完整 ClearML Server
# 参考：https://clear.ml/docs/latest/docs/deploying_clearml/clearml_server
docker pull allegroai/clearml

# docker-compose 快速启动
git clone https://github.com/clearml/clearml-server.git
cd clearml-server/docker
docker-compose up -d

安装 Python SDK

pip install clearml

# 可选：完整全家桶（含 Agent、Data 等）
pip install "clearml[full]"

初始化

clearml-init

按提示输入 api.clear.ml（托管服务地址）和从 https://app.clear.ml 获取的凭据。

核心用法

1. 实验追踪（Experiment Manager）——两行接入

from clearml import Task

# 初始化任务（这行代码之后，所有输出自动记录）
task = Task.init(
    project_name='my-research-project',
    task_name='ResNet50-baseline-v3'
)

# 正常写训练代码即可
# ClearML 会自动记录：
# - 代码（git commit + diff）
# - 依赖包及版本
# - 超参数（argparse/Click/Hydra 等）
# - 控制台输出（stdout/stderr）
# - TensorBoard / Matplotlib / 图像等各类 scalar
# - GPU/CPU 利用率
# - 模型快照

import torch
# ... 正常训练代码 ...

task.close()  # 任务结束时调用

2. 超参数记录（手动记录更精细控制）

from clearml import Task

task = Task.init(project_name='hpo', task_name='search')

# 记录字典类型的超参数
task.connect({
    'learning_rate': 0.001,
    'batch_size': 32,
    'optimizer': 'Adam'
})

# connect 还能追踪 argparse
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--lr', type=float, default=0.01)
args = parser.parse_args()
task.connect(parser)  # argparse 自动记录

3. 数据集管理（Hyper-Datasets）

# 创建数据集
clearml-data create --project my-project --name CIFAR10

# 上传本地数据
clearml-data upload --id <dataset_id> --files ./data/cifar10/

# 在代码中引用数据集
from clearml import Dataset

dataset = Dataset.get(dataset_id='<your-dataset-id>', dataset_project='my-project')
local_path = dataset.get_local_copy()  # 下载到本地

Python API 记录数据集版本：

from clearml import Dataset
import shutil

# 创建新版本
dataset = Dataset.create(
    dataset_project='my-project',
    dataset_name='coco2017'
)
dataset.add_files(path='./data/coco/train')
dataset.upload()
dataset.finalize()

4. 超参优化（Hyper-Parameter Optimization）

from clearml import Task
from clearml.automation.optuna import OptunaOptimizer

# 启动 Optuna 超参搜索
optimizer = OptunaOptimizer(
    task=Task.init(project_name='hpo', task_name='lr-search'),
    # 定义目标函数
    parameter_names=['config.lr', 'config.batch_size'],
    # 搜索空间
    search_space={
        'config.lr': {'type': 'uniform', 'min': 1e-5, 'max': 1e-1},
        'config.batch_size': {'type': 'choice', 'values': [16, 32, 64]},
    },
    # 优化目标：最小化 val_loss
    objectives=[{'type': 'minimize', 'metric': 'validation/loss'}],
)
optimizer.start()
optimizer.wait()  # 阻塞直到完成
best = optimizer.get_best_parameters()

5. Pipeline 编排

from clearml import PipelineController

pipeline = PipelineController(
    project='my-pipeline',
    name='training-pipeline',
)

# 添加步骤
pipeline.add_step(name='data_prep',  # 预处理步骤
    base_task_project='templates',
    base_task_name='preprocess-script',
)

pipeline.add_step(name='training',    # 训练步骤
    base_task_project='templates',
    base_task_name='train-script',
    parameter_override={'Args/lr': 0.001}  # 注入参数
)

pipeline.start()

6. 模型服务

# 启动模型服务（基于 Triton 或自带服务）
clearml-serving create --name my-service
clearml-serving add model --model_id <model_id> --endpoint /predict
clearml-serving start

典型适用场景

场景	适用模块
研究团队记录每次实验结果	Experiment Manager
团队共享训练环境和代码	Experiment Manager + Agent
大规模超参搜索（Bayesian / Optuna）	Hyper-Parameter Optimization
大型数据集版本管理与共享	Hyper-Datasets
训练任务自动化调度（定时/Cron）	Orchestration / Pipeline
训练完一键部署为 REST API	Model Serving
监控模型推理性能与漂移	Model Monitoring（Serving 内置）
构建 RAG Pipeline（v3.25+ 向量库）	Hyper-Datasets（向量字段）

坑与注意

1. 默认使用 demo server 的变更

ClearML 已不再默认连接公开 demo server（新用户若不加 CLEARML_NO_DEFAULT_SERVER=0 环境变量则不会连）。注意：发送到 demo server 的实验是公开的，请勿上传敏感实验。正式使用务必初始化自己的服务或使用托管版。

2. 初始化后配置存在本地

clearml-init 会把凭据写入 ~/clearml.conf（Linux/Mac）或 %USERPROFILE%\.clearml.conf（Windows），这台机器上所有项目共享同一身份。切换账号需要重新 clearml-init。

3. Git 集成需注意未提交代码

ClearML 会自动记录 git diff（包括未 commit 的本地修改），这对追踪实验有帮助，但如果代码含敏感信息要注意。

4. 大文件上传需配置存储后端

直接用托管服务时，模型快照和数据集默认存在 ClearML 的存储中（免费额度有限）。生产环境建议配置 S3 / GCS / Azure Blob Storage 作为存储后端：

from clearml import OutputModel
model = OutputModel(task=task)
model.upload_storage = 's3://my-bucket/models/'

5. v3.25 新增向量数据库

v3.25（2025 年中）引入了 Hyper-Datasets 内置向量字段，可直接存储 embeddings 并在 UI 内做向量相似度搜索。这是构建 RAG pipeline 的新方式，但尚属新功能，相关 SDK API 可能仍在演进中，使用前核对当前最新版本文档。

6. 多 GPU / 分布式训练

ClearML Agent 支持 Docker 容器化的任务分发，但分布式 PyTorch（DDP）训练需要在代码层面正确配置 local_rank，ClearML 本身不自动处理多卡通信。

与同类对比

仓库/工具	定位	优点	缺点
ClearML	全栈 MLOps 平台	五件套合一、开源自托管、零摩擦集成	功能多导致学习曲线陡峭
MLflow	实验追踪为主	生态大、简单直观	数据管理/编排/服务偏弱
Weights & Biases (wandb)	实验追踪+可视化	界面好、免费个人版	非开源、服务器在国外
DVC	数据版本控制	数据管理强、轻量	不覆盖实验追踪和服务
Kubeflow	企业级 MLOps	适合大规模 K8s 部署	部署复杂，入门门槛高
Neptune.ai	实验管理即服务	托管简单、集成丰富	非开源、价格较贵

一句话推荐结论

如果你受够了每次复现实验都要翻聊天记录、手动记超参数、找队友要代码版本，ClearML 的"加两行代码自动记一切"是你目前在开源界能找到的最低摩擦、最高收益的 ML 实验管理方案，尤其适合研究团队或 AI 初创公司的全流程管理。