ClearML中文文档实战：从安装到第一个实验的保姆级教程
最近在整理团队的机器学习实验流程，发现一个普遍问题：很多同学跑完实验，结果和代码就散落在各自的笔记本或服务器上，过段时间想复现或者对比一下，简直是一场灾难。参数忘了、环境变了、数据版本对不上……这些问题反复出现，促使我开始寻找一个能“管住”整个实验生命周期的工具。ClearML正是在这个背景下进入我的视野，它不像一些平台那样需要彻底改变开发习惯，而是以一种“无侵入”的方式，悄无声息地帮你把实验管起来。
对于刚接触ClearML的Python开发者来说，最迫切的需求不是理解其宏大的架构，而是“怎么快速把它用起来”。这篇文章就是为你准备的。我会抛开复杂的理论，聚焦于最实际的操作：从零开始，安装SDK、配置服务器、创建第一个实验，并穿插那些我踩过坑的常见报错解决方案。我们的目标很明确：让你在30分钟内，跑通第一个被ClearML完整记录和管理的机器学习实验。
1. 环境准备与核心组件理解
在动手安装之前，花几分钟理解ClearML的核心角色是值得的，这能帮你避免后续配置中的迷惑。你可以把ClearML想象成一个由三部分组成的协同系统：记录员（SDK）、档案馆（Server）和执行者（Agent）。
- ClearML SDK (Python库)：这是你将在代码中直接交互的部分。通过几行简单的
import和初始化，它就能自动“粘附”在你的训练脚本上，捕获代码、环境、参数、指标和输出模型。它就像你身边的记录员，默默记下实验发生的一切。 - ClearML Server (服务器)：这是所有记录信息的中央存储和展示平台。它提供了一个Web界面（WebApp），让你可以可视化地对比实验、查看指标曲线、管理模型。你可以把它理解为公司的中央档案馆，所有实验报告都归档于此。
- ClearML Agent (代理)：这是一个可选但强大的组件。它能在远程机器（本地服务器或云上）上自动执行你排队的任务。你提交任务后，Agent会拉取代码、准备环境并运行，实现训练的自动化。它就像一位可靠的执行者，帮你把想法变成实际运行的任务。
对于入门，我们首先需要的是SDK和Server。Agent可以在我们熟悉基础操作后再引入。这里有一个简单的对比，帮助你理清关系：
| 组件 | 作用 | 是否必须入门？ | 部署位置 |
|---|---|---|---|
| ClearML SDK | 集成在代码中，用于记录实验数据。 | 是 | 你的开发环境（笔记本/服务器） |
| ClearML Server | 存储和展示数据，提供Web UI。 | 是 | 独立的服务器（本地或云端） |
| ClearML Agent | 自动执行远程任务。 | 否（进阶需要） | 执行任务的机器（GPU服务器等） |
提示：ClearML官方提供了免费的托管Server服务（
app.clear.ml），对于个人学习和小团队起步非常友好，可以免去自己部署服务器的麻烦。我们教程后续会使用它。
1.1 安装Python SDK
安装SDK非常简单，一条pip命令即可。但为了环境整洁，我强烈建议使用虚拟环境（如venv或conda）。
# 创建并激活一个虚拟环境（以venv为例） python -m venv clearml_env source clearml_env/bin/activate # Linux/macOS # clearml_env\Scripts\activate # Windows # 安装clearml SDK pip install clearml安装完成后，可以通过以下命令验证是否成功，并查看版本。
python -c “import clearml; print(‘ClearML SDK版本:’, clearml.__version__)”如果安装过程遇到网络问题，可以考虑使用国内镜像源，例如：
pip install clearml -i https://pypi.tuna.tsinghua.edu.cn/simple2. 配置ClearML凭证与连接Server
安装好SDK后，它还不知道该把记录的数据发送到哪里。这就需要我们进行配置，建立SDK和Server之间的连接。我们将使用ClearML的免费托管服务来快速开始。
第一步：获取免费的ClearML账户和凭证
- 访问 ClearML Signup 注册一个免费账户。
- 登录后，点击页面右上角的头像，选择“Settings”。
- 在设置页面，选择“Workspace”选项卡。
- 在这里你可以看到你的“API Credentials”，包含：
api_server: 通常是https://api.clear.mlweb_server: 通常是https://app.clear.mlfiles_server: 通常是https://files.clear.mlaccess_key和secret_key
第二步：在本地配置凭证ClearML SDK提供了非常方便的命令行工具来完成一键配置。在你的终端中执行：
clearml-init这时，命令行会交互式地引导你完成配置：
- 它会提示你输入上述的
api_server,web_server,files_server地址，通常直接回车使用默认值即可。 - 然后会要求输入从Web界面获取的
access_key和secret_key。 - 配置完成后，信息会安全地保存在本地的
~/clearml.conf文件中。
注意：
clearml-init是最高效的方式。你也可以手动创建或编辑~/clearml.conf文件，但容易格式出错。一个正确的配置文件片段如下所示：
api { api_server: https://api.clear.ml web_server: https://app.clear.ml files_server: https://files.clear.ml credentials { “access_key” = “你的ACCESS_KEY” “secret_key” = “你的SECRET_KEY” } }验证连接配置完成后，运行一个简单的测试脚本来验证一切是否正常：
# test_connection.py from clearml import Task task = Task.init(project_name=’TestProject’, task_name=’Connection Test’) print(“ClearML任务初始化成功！任务ID:”, task.id) task.close()运行这个脚本后，立刻刷新你的ClearML WebApp页面（app.clear.ml）。你应该能在“TestProject”项目下看到一个名为“Connection Test”的新任务。点击进去，可以看到任务的基本信息、代码执行环境等已经被捕获。这说明你的SDK已经成功连接到ClearML Server了！
3. 创建你的第一个自动化实验
现在我们来点实际的：将一个普通的PyTorch或TensorFlow训练脚本，改造成一个能被ClearML自动跟踪的实验。关键在于Task.init()这行代码。
3.1 改造一个简单的PyTorch训练脚本
假设我们有一个最基础的MNIST分类训练脚本train_mnist.py。下面是改造前后的核心对比。
改造前（普通脚本）：
import argparse import torch import torch.nn as nn import torch.optim as optim from torchvision import datasets, transforms def main(args): # … 数据加载、模型定义等代码 … for epoch in range(args.epochs): train_loss = train_one_epoch(…) val_acc = validate(…) print(f’Epoch {epoch}: loss={train_loss:.4f}, val_acc={val_acc:.4f}’) torch.save(model.state_dict(), ‘mnist_model.pth’) if __name__ == ‘__main__’: parser = argparse.ArgumentParser() parser.add_argument(‘--lr’, type=float, default=0.01) parser.add_argument(‘--batch_size’, type=int, default=64) parser.add_argument(‘--epochs’, type=int, default=5) args = parser.parse_args() main(args)改造后（ClearML集成）：
import argparse import torch import torch.nn as nn import torch.optim as optim from torchvision import datasets, transforms # 1. 导入ClearML from clearml import Task def main(args): # 2. 初始化ClearML任务（必须放在脚本逻辑开始前） task = Task.init( project_name=’GettingStarted/MNIST’, # 项目可以层级化 task_name=’PyTorch MNIST Baseline’, # 实验名称 tags=[‘baseline’, ‘pytorch’] # 方便搜索的标签 ) # 3. 将命令行参数自动记录为实验超参数 task.connect(args) logger = task.get_logger() # 获取logger对象，用于手动记录 # … 数据加载、模型定义等代码 … for epoch in range(args.epochs): train_loss = train_one_epoch(…) val_acc = validate(…) print(f’Epoch {epoch}: loss={train_loss:.4f}, val_acc={val_acc:.4f}’) # 4. 手动记录指标到ClearML（自动记录也已生效） logger.report_scalar(‘loss’, ‘train’, value=train_loss, iteration=epoch) logger.report_scalar(‘accuracy’, ‘val’, value=val_acc, iteration=epoch) torch.save(model.state_dict(), ‘mnist_model.pth’) # 5. 可选：将输出的模型文件注册为任务工件 task.upload_artifact(‘model’, artifact_object=’mnist_model.pth’) print(‘任务完成，请在ClearML WebApp查看详情。’) # 任务会自动关闭，也可以显式调用 task.close() if __name__ == ‘__main__’: parser = argparse.ArgumentParser() parser.add_argument(‘--lr’, type=float, default=0.01) parser.add_argument(‘--batch_size’, type=int, default=64) parser.add_argument(‘--epochs’, type=int, default=5) args = parser.parse_args() main(args)关键改造点解析：
Task.init(): 这是魔法开始的地方。它创建了一个任务实例，并立即开始后台捕获：整个脚本文件、Git信息（如果有）、Python环境包列表。task.connect(args): 这行代码将你的argparse参数对象“连接”到任务。ClearML会自动解析这些参数，并将其作为超参数记录在WebApp中。后续你甚至可以在WebUI上直接修改这些参数值来重新运行实验。- 自动记录: 集成后，所有打印到控制台（
stdout/stderr）的日志、通过torch.utils.tensorboard.SummaryWriter或matplotlib绘制的图表，大部分都会被ClearML自动捕获。你几乎不需要额外代码。 - 手动记录: 使用
task.get_logger()获取的logger对象，可以更灵活地记录标量、图像、表格等。report_scalar方法让你能结构化地记录损失和准确率。 - 工件管理:
upload_artifact将训练好的模型文件注册为该任务的输出工件，方便在WebApp中直接查看和下载。
运行这个改造后的脚本，就像你平时运行Python脚本一样：
python train_mnist.py --lr 0.001 --batch_size 1283.2 在WebApp中查看与分析实验
脚本运行结束后（甚至还在运行时），你就可以打开ClearML WebApp (app.clear.ml) 进行查看了。
- 项目与任务列表: 在主页或“项目”页面，你会看到“GettingStarted”项目，其下有“MNIST”子项目，里面躺着我们刚运行的“PyTorch MNIST Baseline”任务。
- 实验概览: 点击任务名称进入详情页。“概览”选项卡展示了任务状态、创建时间、使用的参数（
lr=0.001,batch_size=128）、Git提交哈希、Python环境等所有被自动捕获的信息。 - 指标对比（核心功能）: 切换到“标量”选项卡。你会看到两条曲线：“loss/train”和“accuracy/val”，这正是我们通过
logger.report_scalar记录的。ClearML会自动为你绘制随时间（迭代次数）变化的曲线图。如果你多次运行不同参数的实验，可以在项目页面勾选多个任务，然后点击“对比”，将它们的所有指标曲线放在同一张图中，差异一目了然。 - 结果复现: 想用不同的学习率再跑一次？不需要改代码。在任务详情页，点击“克隆”按钮。系统会创建一个配置完全相同的副本任务（状态为“草稿”）。在草稿任务的配置中，直接修改
lr参数的值，然后点击“入队执行”。如果配置了ClearML Agent，这个新任务会自动在远程执行；没有Agent的话，你也可以获取到运行命令，在本地执行。
4. 进阶配置与常见问题排查
当你成功运行第一个实验后，可能会遇到一些典型问题或产生进阶需求。这里分享几个我遇到过的场景和解决方案。
4.1 处理常见报错与连接问题
错误:
ClearML was unable to detect git repository- 原因: 你的代码目录不是一个git仓库，或者ClearML无法读取.git信息。
- 解决: 这只是一个警告，不影响核心功能。如果想消除，可以在
Task.init()中添加参数auto_connect_frameworks=False来禁用部分自动连接，或者确保在git仓库中运行。对于快速实验，完全可以忽略。
错误:
Missing credentials或Connection failed- 原因:
clearml.conf配置文件缺失、位置不对或凭证错误。 - 解决:
- 确认是否运行过
clearml-init。 - 检查配置文件路径：
~/.clearml/clearml.conf或%USERPROFILE%\.clearml\clearml.conf(Windows)。 - 重新运行
clearml-init覆盖配置。 - 检查防火墙或网络代理是否阻止了与
api.clear.ml的连接。
- 确认是否运行过
- 原因:
任务信息没有上传到WebApp
- 原因: 脚本可能异常退出，或者任务没有正常关闭。
- 解决: 确保脚本逻辑执行完毕。最好使用
try…finally块来保证task.close()被调用。
task = Task.init(…) try: # 你的训练主逻辑 train_model() finally: task.close()
4.2 配置自定义输出存储
默认情况下，ClearML会将模型、工件等大文件上传到其免费的files.clear.ml存储，但有空间限制。对于生产用途，你需要配置自己的存储后端（如AWS S3、Google Cloud Storage、Azure Blob，甚至是共享的NFS目录）。
配置可以通过代码或配置文件完成。这里展示通过代码为特定任务配置S3存储：
from clearml import Task, StorageManager # 初始化任务 task = Task.init(…) # 设置任务的默认输出URI为S3 bucket task.set_output_destination( storage=’s3://my-ml-bucket/clearml-output’, name=’My S3 Bucket’ # 在WebApp中显示的名称 ) # 或者，通过StorageManager添加全局可用的存储配置 StorageManager.add_cache_module( base_url=’s3://my-ml-bucket’, s3_key=’YOUR_AWS_KEY’, s3_secret=’YOUR_AWS_SECRET’, s3_region=’us-east-1’ )更推荐的方式是在WebApp的“管理”->“凭证”页面添加你的云存储凭证，然后在任务中直接引用凭证名，这样更安全，无需在代码中硬编码密钥。
4.3 与TensorBoard和Matplotlib的无缝集成
ClearML的一个强大之处在于它对主流可视化库的自动捕获。你几乎不需要改变原有的可视化代码。
- TensorBoard: 如果你使用
torch.utils.tensorboard.SummaryWriter或tensorboardX，ClearML会自动捕获所有写入的标量、直方图、图像、文本等，并在WebApp的“标量”和“调试样本”选项卡中展示。 - Matplotlib: 当你调用
plt.figure()和plt.show()或plt.savefig()时，ClearML会自动捕获生成的图形，并将其作为任务的“图表”或“调试样本”保存。
这意味着，你现有的TensorBoard日志代码可以直接工作，并且多了一个集中、可持久化、便于协作的Web界面来查看这些结果。
5. 从实验走向自动化：初探Pipeline与Agent
当你熟悉了单个实验的管理后，ClearML真正的威力开始显现：自动化工作流。这主要涉及两个组件：Pipeline（构建复杂工作流）和Agent（自动执行任务）。
5.1 使用ClearML Agent解放本地机器
你不想让训练任务占满本地开发机的GPU？或者需要在多台机器上排队运行大量超参搜索？ClearML Agent是答案。
部署一个Agent的基本步骤：
- 在一台拥有计算资源（如带GPU的云服务器）的机器上安装ClearML Agent。
pip install clearml-agent - 在该机器上同样运行
clearml-init，配置相同的Server地址和凭证，使其能与你的ClearML Server通信。 - 启动Agent服务，让它开始监听任务队列。
clearml-agent daemon --queue default--queue default表示这个Agent监听名为“default”的任务队列。
提交任务到队列：在你的训练脚本中，初始化任务时指定一个队列，任务就不会立即在本地运行，而是进入“草稿”状态。
task = Task.init(project_name=’…’, task_name=’…’) # … 连接参数等操作 … task.execute_remotely(queue_name=’default’) # 指定远程队列或者，更常见的做法是：在WebApp中，将任何一个“草稿”状态的任务（包括克隆出来的任务），手动“入队”到“default”队列。
一旦任务入队，正在监听“default”队列的Agent就会自动获取任务代码、创建环境、安装依赖并执行。你可以在WebApp上实时看到任务日志和状态更新。
5.2 构建第一个简单的Pipeline
Pipeline允许你将数据预处理、训练、评估等步骤定义为一个个独立的ClearML任务，并指定它们之间的依赖关系。ClearML会自动调度执行。
下面是一个极简的Pipeline示例，定义了两个步骤：
# pipeline_definition.py from clearml import PipelineController def main(): # 创建Pipeline控制器 pipe = PipelineController( project=’DemoPipeline’, name=’Simple Training Pipeline’, version=’1.0’ ) # 添加步骤1：数据预处理 pipe.add_step( name=’data_processing’, base_task_project=’DemoPipeline’, base_task_name=’Data Processing Template’, # 这是一个预先创建好的任务模板 parameter_override={‘General/dataset_url’: ‘s3://my-data/raw.zip’} ) # 添加步骤2：模型训练，依赖步骤1的输出 pipe.add_step( name=’model_training’, parents=[‘data_processing’], # 指定依赖 base_task_project=’DemoPipeline’, base_task_name=’Training Template’, parameter_override={ ‘General/dataset_id’: ‘${data_processing.artifacts.dataset.id}’ # 引用上一步的产出 } ) # 启动Pipeline pipe.start() if __name__ == ‘__main__’: main()运行这个Pipeline定义脚本后，ClearML Server会依次创建并调度执行“data_processing”和“model_training”任务。在WebApp的“流水线”页面，你可以看到一个可视化的DAG图，清晰展示每个步骤的状态和依赖。
通过这个从安装、配置、第一个实验到进阶自动化的完整流程，ClearML展示出了它作为实验管理平台的核心价值：不干扰你的编码，却全方位守护你的实验资产。它解决的正是机器学习开发中那些琐碎但至关重要的问题——可复现性、可比较性和自动化。
