ClearML 全栈 MLOps/LLMOps 套件实战指南:两行代码接入实验管理、数据管理与自动化编排
ClearML 全栈 MLOps/LLMOps 套件实战指南:两行代码接入实验管理、数据管理与自动化编排
ClearML 是一个面向机器学习/深度学习研发与生产流程的开源 MLOps/LLMOps 套件,本指南基于当前仓库的 README.md 及其源码,系统讲解其五大核心模块、Task.init 两行代码集成的原理、clearml-init 初始化流程、运行时架构,以及配套 CLI、数据集版本化、自动化管线与超参数优化等实战能力。读完本文,你将能够独立完成 ClearML SDK 的安装接入、实验全链路跟踪配置,并理解其底层实现机制。
ClearML 概览:五大核心模块
ClearML 定位为"Auto-Magical"的 AI 工作流加速工具,将实验管理、MLOps 编排与数据管理统一到一个平台中。按 README 的划分,它包含五个主要模块:
| 模块 | 定位 | 说明 |
|---|---|---|
| Experiment Manager | 实验跟踪 | 自动捕获实验设置、环境、超参数、模型快照与各类输出 |
| MLOps / LLMOps | 编排自动化 | ML/DL/GenAI 任务的编排、自动化与管线方案,支持 Kubernetes / 云 / 裸金属 |
| Data-Management | 数据版本化 | 构建在对象存储(S3 / GS / Azure / NAS)之上的全可微数据管理与版本控制 |
| Model-Serving | 模型服务 | 云就绪的可扩展模型服务方案,可快速部署模型端点并内置模型监控 |
| Reports | 报告 | 创建并分享富 Markdown 文档,支持嵌入在线内容 |
此外还有两个延伸能力:Orchestration Dashboard(面向整个计算集群的实时仪表盘,覆盖云 / Kubernetes / 本地)与 Fractional GPUs(基于容器的驱动级 GPU 显存隔离)。
支撑这些组件运转的是 ClearML-server,负责存储实验、模型与工作流数据,既提供免费托管服务,也支持自托管部署。
ClearML Experiment Manager:两行代码的自动集成
Experiment Manager 是 ClearML 的核心入口。按 README 的说法,只需要在代码中增加两行,即可获得完整的实验跟踪能力。当前仓库的 clearml/init.py 中导出了 Task、Logger、Model、Dataset、PipelineController 等核心对象,其中 Task 是接入的入口类。
自动记录的实验设置
接入后,ClearML 会自动捕获并记录:
- 完整源码控制信息:包括未提交的本地改动(diff)。这一行为在 docs/clearml.conf 中有对应配置项
sdk.development.store_uncommitted_code_diff,默认开启。 - 执行环境:具体安装的 Python 包与版本。仓库在
sdk.development下提供detect_with_pip_freeze、detect_with_conda_freeze、detailed_import_report等开关,控制依赖探测策略。 - 超参数(Hyper-parameters),来源覆盖多种常见参数体系:
argparse/ Click / PythonFire 命令行参数及其当前使用值;- 显式的参数字典;
- TensorFlow Defines(absl-py);
- Hydra 配置与覆盖项。
- 初始模型权重文件。
自动捕获的实验输出
- stdout 与 stderr 完整日志;
- 资源监控:CPU/GPU 利用率、温度、IO、网络等指标(由 clearml/utilities/resource_monitor.py 的
ResourceMonitor实现,GPU 监控不可用时会有降级提示); - 模型快照:可配置自动上传到中央存储(共享文件夹、S3、GS、Azure、Http);
- Artifacts 日志与存储:同样支持上述各类存储后端;
- Tensorboard / TensorboardX 的标量、指标、直方图,以及图像、音频、视频样本;
- Matplotlib 与 Seaborn 图形自动序列化上报;
- ClearML Logger 接口,提供完全灵活的显式日志能力(详见 docs/logger.md)。
广泛框架与平台支持
README 列出的受支持框架包括:PyTorch(含 ignite / lightning)、TensorFlow、Keras、AutoKeras、FastAI、XGBoost、LightGBM、MegEngine 与 Scikit-Learn,且支持 Jupyter Notebook 的无缝集成(含版本控制)与 PyCharm 远程调试。仓库中对应示例位于 examples/frameworks 目录,每个框架均有可直接运行的样例脚本。
Task.init:接入的核心入口与参数详解
两行接入代码的本质是调用 Task.init。以 examples/frameworks/pytorch/pytorch_mnist.py 中的真实用法为例:
from clearml import Task
# Connecting ClearML with the current process,
# from here on everything is logged automatically
Task.init(project_name="examples", task_name="PyTorch MNIST train")
从源码 clearml/task.py 可以看到 Task.init 的完整签名与语义。它采用"同项目同名 Task 复用"策略:当同名任务从未运行过、或已发布(Published)/已归档(Archived)、或显式设置 reuse_last_task_id=False 时会创建新 Task;否则返回已初始化的 Task 对象,在 clearml-agent 远程执行时则返回后端中已存在的任务。
主要参数说明如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
project_name |
仓库名 | 项目名,不存在时自动创建;为 None 时使用仓库名 |
task_name |
脚本文件名 | 实验(Task)名称,为 None 时使用 Python 脚本文件名 |
task_type |
training |
任务类型,可选 training/testing/inference/data_processing/application/monitor/controller/optimizer/service/qc/custom |
tags |
无 | 给 Task 添加标签列表,如 ['512x512', 'yolov3'] |
reuse_last_task_id |
True |
True 复用上次 Task ID;False 强制新建;也可传字符串指定要复用的 Task ID |
continue_last_task |
False |
继续上次实验:True 延续上次 Task;False 覆盖;字符串指定 Task ID;整数指定初始迭代偏移 |
output_uri |
无 | 输出模型与 Artifacts 的默认位置:共享文件夹 /mnt/share/folder、S3 s3://bucket/folder、GCS gs://bucket-name/folder、Azure azure://company.blob.core.windows.net/folder/,或 True 使用默认文件服务器 |
auto_connect_arg_parser |
True |
自动连接 argparse/Click/PythonFire/jsonargparse 参数;字典可做细粒度控制,如 {"do_not_include_me": False} |
auto_connect_frameworks |
True |
自动连接框架(Matplotlib、XGBoost、scikit-learn、Keras callbacks、TensorBoard/X 等);字典支持通配符控制模型文件匹配,如 {'pytorch': '*.pt', 'tensorflow': ['*.h5', '*']} |
auto_resource_monitoring |
True |
自动生成机器资源监控曲线,在 Web UI 的 RESULTS → SCALARS 中以 :resource monitor: 标题展示;也接受 dict 传递 report_start_sec 等参数 |
auto_connect_streams |
True |
自动记录 stdout/stderr;字典键为 'stdout'/'stderr'/'logging',如 {'stdout': True, 'stderr': True, 'logging': False} |
源码注释还给出一个重要实践建议:Task.init 应放在脚本执行的最开头(例如 if __name__ == "__main__": 之后),因为 ClearML 会拦截 PyTorch 等库的执行过程,若在初始化前执行代码,可能导致内存泄漏或僵尸子进程。
框架自动集成的底层原理:以 PyTorch 为例
"自动魔法"的实现本质是运行时补丁(monkey-patching)。以 PyTorch 绑定 clearml/binding/frameworks/pytorch_bind.py 为例:
PatchPyTorchModelIO.update_current_task在Task.init时被触发,随即调用_patch_model_io()、_patch_lightning_io()等补丁方法;_patch_model_io()会通过_patched_call包装torch.save、torch.load、torch.jit序列化方法,使模型保存/加载动作被透明地拦截并上报为模型快照;- 同时通过
PostImportHookPatching.add_on_import注册"导入即打补丁"钩子,即使 torch 尚未导入,也会在之后导入时自动生效; - 对 mmcv 的
save_checkpoint也做了适配(_patch_mmcv),扩展了对 OpenMMLab 生态的兼容。
这一机制同样存在于 clearml/binding/frameworks 下的 tensorflow_bind.py、xgboost_bind.py、lightgbm_bind.py、catboost_bind.py、fastai_bind.py、megengine_bind.py 等文件中,只是补丁目标各不相同。理解这一原理有助于排查"为什么框架输出会自动出现在实验里"以及"何时需要手动 Task.connect"。
显式日志:ClearML Logger API
自动捕获之外,ClearML 提供 clearml/logger.py 的 Logger 类做显式上报。从源码可见其覆盖的日志类型:
report_text:文本日志;report_scalar:标量曲线(title、series、value、iteration四个参数);report_histogram:直方图;report_table:表格(支持 pandas DataFrame);report_image/report_media:图像与音视频媒体;report_plotly/report_matplotlib_figure:Plotly 与 Matplotlib 图形。
典型用法见 examples/frameworks/pytorch/pytorch_mnist.py 中对训练 loss 的显式上报:
Logger.current_logger().report_scalar(
"train", "loss",
iteration=(epoch * len(train_loader) + batch_idx),
value=loss.item(),
)
快速上手:5 步完成接入
README 给出了从零到运行的最短路径:
第 1 步:选择后端。 免费注册 ClearML 托管服务,或自托管 ClearML Server(参见官方部署文档中的 Self-Hosting 章节)。
关于 Demo Server:README 特别注明,ClearML 已不再默认使用 demo server。如需启用,需设置环境变量
CLEARML_NO_DEFAULT_SERVER=0。Demo server 无需凭据,但实验是公开的,切勿在上面运行敏感实验。
第 2 步:安装 SDK。
pip install clearml
第 3 步:初始化并连接服务器。 先在服务器 Web UI 的 workspace 设置中创建凭据,然后执行:
clearml-init
该命令的实现在 clearml/cli/config/main.py,其核心流程是:
- 读取本地配置文件(默认路径为
~/clearml.conf或~/trains.conf,见 clearml/backend_config/defs.py),若文件已存在则直接退出; - 提示粘贴 Web UI 复制的配置(含 access key 与 secret key);
- 解析出 API、Web、Files 三个服务地址(对托管服务会自动推导
app.→api./files.前缀,对自托管端口也会自动推断 8080/8008/8081 的对应关系); - 用
Session验证凭据有效性; - 将配置写入本地文件。
第 4 步:为代码增加两行。
from clearml import Task
task = Task.init(project_name='examples', task_name='hello world')
第 5 步:运行。 之后进程产生的所有输出都会被自动记录到 ClearML。
配置文件与环境变量覆盖
clearml-init 生成的配置结构可直接参考仓库内的 docs/clearml.conf 模板:顶层 api 段包含 web_server(8080)、api_server(8008)、files_server(8081)、credentials 与 verify_certificate;sdk 段则包含存储缓存、指标历史、网络重试、AWS/GCS/Azure 存储凭据、日志与开发模式等大量可调项。
对于 CI/CD 等场景,关键配置可通过环境变量覆盖。仓库源码 clearml/backend_config/defs.py 确认了以下变量:CLEARML_CONFIG_FILE(指定配置文件,设置后不再使用其他本地配置文件)、CLEARML_API_ACCESS_KEY / CLEARML_API_SECRET_KEY(凭据覆盖,见 docs/clearml.conf 注释)、CLEARML_CONFIG_PATH(环境配置路径)。另外 CLEARML_NO_DEFAULT_SERVER 用于 demo server 开关,CLEARML_LOG_ENVIRONMENT 可指定要记录的 OS 环境变量列表。
远程执行:从本地调试到云端训练
接入完成后,下一步是自动化。README 指向"two-click automation"能力,即一键把实验转成远程任务。其代码层面核心是 Task.execute_remotely,见 examples/advanced/execute_remotely_example.py 的经典用法:
for epoch in range(1, args.epochs + 1):
if epoch > 1:
# We run training for 1 epoch to make sure nothing crashes then local execution will be terminated.
# Execution will switch to remote execution by the agent listening to specified queue
task.execute_remotely(queue_name="default")
train(...)
test(...)
其行为是:本地运行时,完成当前迭代后把 Task 入队(enqueue)到指定队列并结束本地进程;在 clearml-agent 中运行时则忽略该调用、继续执行。该示例特意先本地跑 1 个 epoch 验证代码无误,再无缝迁移到更强的远程机器完成整个训练。
ClearML 架构:三大运行时组件
README 将 ClearML 的运行时组件归纳为三层:
- ClearML Python 包(SDK):将 ClearML 集成进现有脚本(两行代码),并提供
Task、Logger、Dataset、PipelineController等强大的类与方法集合来扩展实验与工作流; - ClearML Server:存储实验、模型与工作流数据,支撑 Web UI 实验管理与 MLOps 自动化,用于可复现与调优。以托管服务和开源自托管两种形式提供;
- ClearML Agent:负责 MLOps 编排、实验与工作流可复现性以及横向扩展。
三者协作关系是:SDK 在训练进程内采集数据并上报 Server,Server 持久化并提供 Web UI 查看与操作,Agent 从队列拉取任务并在目标机器上复现环境执行。这套分工与 README 对 Experiment Manager、Server、Agent 的职责描述一致。
配套 CLI 与附加模块
SDK 还附带多个命令行工具,入口统一注册在 setup.py 的 console_scripts 中:
| 命令 | 入口 | 用途 |
|---|---|---|
clearml-init |
clearml.cli.config.__main__:main |
SDK 配置向导(上文已述) |
clearml-data |
clearml.cli.data.__main__:main |
数据集创建 / 上传 / 下载与版本管理(详见 docs/datasets.md) |
clearml-task |
clearml.cli.task.__main__:main |
零代码改动地把任意代码库提交到远程机器执行(详见 docs/clearml-task.md) |
clearml-param-search |
clearml.cli.hpo.__main__:main |
超参数优化 |
clearml-debug |
clearml.cli.debug.__main__:main |
调试工具 |
数据管理:clearml-data 与 Dataset
数据管理模块建立在对象存储之上,实现"全可微"的数据版本化——每一次数据集变更都像一次可追踪、可回滚的提交。SDK 侧的核心类是 clearml/datasets/dataset.py 中的 Dataset,从源码可见其关键方法:create(创建数据集版本)、add_files(添加文件)、upload(上传到对象存储)、finalize(封板版本)、get(获取)、list_datasets(列出)等,典型工作流即"创建 → 添加 → 上传 → 封板"四步。CLI 层面则由 clearml-data 命令承载,README 将其描述为"管理并版本化你的数据集,包括从 S3/GS/Azure/NAS 创建、上传、下载数据"。
自动化管线与编排
- Automation Pipeline:基于已有实验/任务构建管线,支持"管线的管线"。核心实现在 clearml/automation/controller.py:
PipelineController提供add_step、start、start_locally、enqueue等方法;PipelineDecorator(同一文件第 3981 行起)提供@PipelineDecorator.component装饰器,用 Python 函数直接定义管线步骤。两者均在 clearml/init.py 中作为顶层 API 导出。仓库内的入门示例位于 examples/pipeline(如pipeline_from_functions.py、pipeline_from_tasks.py、decorated_pipeline_step_decorators.py)。 - AWS Auto-Scaler:按工作负载自动拉起 EC2 实例,支持预算上限配置。
- Hyper-Parameter Optimization:黑盒方式优化任意代码,内置先进的贝叶斯优化算法;仓库还提供 clearml/automation/optuna 与 clearml/automation/hpbandster 两套优化器适配,示例见 examples/optimization/hyper-parameter-optimization。
- Slack 集成:把实验进度/失败直接推送到 Slack,示例见 examples/services/monitoring。
- 另有两个独立配套仓库:
clearml-session(在任何 docker 中启动远程 JupyterLab / VSCode-server)与clearml-task命令行工具。
设计理念与适用场景
ClearML 的诞生源于作者团队与众多研究者共同的痛点:训练生产级深度学习模型是一个"光荣但混乱"的过程。ClearML 通过把代码版本控制、研究项目、性能指标与模型来源(provenance)关联起来,实现跟踪与控制。其设计原则是接入零负担,让团队保留既有方法与习惯:
- 日常使用以提升团队协作与可视化透明度;
- 任何实验一键创建远程任务;
- 自动化流程与管线聚合实验日志、输出与数据;
- 数据统一存放在任意对象存储之上,并通过 ClearML 平台完成编目。
从当前仓库的实际结构看,这一定位体现在三个层面:SDK 两行代码接入(clearml/task.py)、框架绑定自动补丁(clearml/binding)、以及 CLI/自动化控制器(clearml/cli 与 clearml/automation)。
许可证、引用与社区支持
- 许可证:Apache License 2.0(详见仓库根目录 LICENSE)。
- 引用:README 提供 BibTeX 条目,若 ClearML 参与你的开发流程/项目/出版物,建议引用(条目见 README.md)。
- 社区:官方文档、YouTube 频道、Slack 频道与 Stack Overflow 的
clearml标签均可获得支持;功能请求与缺陷报告走 GitHub Issues;贡献方式见 CONTRIBUTING.md。
学习路径:仓库内的官方教程与示例
README 提供了一个三步骤的渐进式入门教程,均以 notebook 形式存放在仓库 docs/tutorials:
- Step 1 – 实验管理:Getting_Started_1_Experiment_Management.ipynb,完成 SDK 接入与首次实验跟踪;
- Step 2 – Agent 配置:Getting_Started_2_Setting_Up_Agent.ipynb,搭建远程执行 Agent;
- Step 3 – 远程执行:Getting_Started_3_Remote_Execution.ipynb,把任务提交到远程执行。
示例代码按主题组织在 examples 目录下,覆盖 PyTorch、TensorFlow、Keras、LightGBM、XGBoost、Matplotlib、scikit-learn 等主流框架(examples/frameworks),以及分布式训练(examples/distributed)、数据集(examples/datasets)、管线(examples/pipeline)、调度触发(examples/scheduler)、报表(examples/reporting)与服务化(examples/services)等场景,可与本文各章节配合实战。