ClearML 全栈 MLOps/LLMOps 套件实战指南:两行代码接入实验管理、数据管理与自动化编排

原创2026-10-14 09:33:501,680 阅读
文章标签:MLOpsLLMOps人工智能

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,其核心流程是:

  1. 读取本地配置文件(默认路径为 ~/clearml.conf 或 ~/trains.conf,见 clearml/backend_config/defs.py),若文件已存在则直接退出;
  2. 提示粘贴 Web UI 复制的配置(含 access key 与 secret key);
  3. 解析出 API、Web、Files 三个服务地址(对托管服务会自动推导 app.→api./files. 前缀,对自托管端口也会自动推断 8080/8008/8081 的对应关系);
  4. 用 Session 验证凭据有效性;
  5. 将配置写入本地文件。

第 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 的运行时组件归纳为三层:

  1. ClearML Python 包(SDK):将 ClearML 集成进现有脚本(两行代码),并提供 Task、Logger、Dataset、PipelineController 等强大的类与方法集合来扩展实验与工作流;
  2. ClearML Server:存储实验、模型与工作流数据,支撑 Web UI 实验管理与 MLOps 自动化,用于可复现与调优。以托管服务和开源自托管两种形式提供;
  3. 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:

  1. Step 1 – 实验管理:Getting_Started_1_Experiment_Management.ipynb,完成 SDK 接入与首次实验跟踪;
  2. Step 2 – Agent 配置:Getting_Started_2_Setting_Up_Agent.ipynb,搭建远程执行 Agent;
  3. 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)等场景,可与本文各章节配合实战。

登录后查看全文
clearml