ClearML 实战:用 GitHub Actions 构建 AI 模型 CI/CD 流水线(含完整示例与源码解析)
ClearML 实战:用 GitHub Actions 构建 AI 模型 CI/CD 流水线(含完整示例与源码解析)
本文以 ClearML 开源仓库中的 CI/CD 示例 为主线,系统讲解如何把 ClearML 的实验管理、模型指标、远程执行能力接入 GitHub Actions,实现「PR 自动展示模型指标」「模型性能回归拦截」「远程可运行性校验」三类自动化检查。读完本文,你将掌握三个可直接复用的 CI/CD Job 的完整配置、底层 ClearML SDK 调用原理,以及 clearml-task 命令行在流水线中的正确用法。
一、示例概览:三个 Job 各司其职
仓库中的 run_clearml_checks.yml 定义了一个名为 ClearML Checks 的 GitHub Actions 工作流,它监听 main 分支上的 pull_request 事件(触发类型包括 assigned、opened、edited、reopened、synchronize),并在其中编排了 3 个相互独立的 Job:
| Job | 对应 Python 脚本 | 职责 | 失败后果 |
|---|---|---|---|
task-stats-to-comment |
task_stats_to_comment.py | 在打开的 PR 上自动评论当前提交对应的实验指标 | 阻断合并(找不到对应实验时) |
compare-models |
compare_models.py | 用当前模型指标对比历史最佳,阻止性能回退 | 指标变差即让流水线失败 |
test-remote-runnable |
check_remotely_runnable.py | 校验 PR 代码能被 ClearML Agent 远程拉起并产出迭代 | 超时/失败即拦截合并 |
每个 Job 的逻辑主体都放在对应的 Python 文件中,工作流 YAML 只负责环境准备与调用入口,这种「编排与逻辑分离」的设计便于你把任意一个 Job 单独移植到自己的仓库。
二、前置准备:双通道认证
要让 GitHub runner 能访问 ClearML 服务器并回写 GitHub,需要配置两类凭据。
2.1 ClearML 侧凭据
在 GitHub 仓库的 Settings → Secrets 中依次添加以下三个密钥(键名与工作流文件中的 env 引用保持一致):
CLEARML_API_ACCESS_KEY
CLEARML_API_SECRET_KEY
CLEARML_API_HOST
三个值的获取方式有两种:
- 从本地配置文件读取:如果你已经在本地执行过
clearml-init,配置会写入clearml.conf文件,其中api.api_key、api.secret_key、api.api_server(或api.web_server)字段即对应上述三个密钥; - 在 ClearML WebUI 中新建:登录 WebUI 后,在用户设置中创建新的凭据(Credentials),页面会同时展示 Access Key 与 Secret Key,如下图所示。
注意工作流文件的实际键名:在 run_clearml_checks.yml 中,前两个 Job 的
env引用的是secrets.ACCESS_KEY与secrets.SECRET_KEY(即你需要在 GitHub Secrets 中命名为ACCESS_KEY、SECRET_KEY),第三个 Job 则统一使用CLEARML_API_*命名。移植到自己仓库时,务必让 Secrets 命名与工作流文件中的引用完全一致。
2.2 GitHub 侧令牌
如果希望 Job 1 能把指标以评论的形式发布到 PR 上,还需要一个 GitHub 个人访问令牌(Personal Access Token),并同样存入 Secrets(示例中使用键名 GH_TOKEN)。该令牌需要具备对该仓库的评论(issue comment / PR review)写入权限。此令牌仅在 Job 1 中必需;Job 2、Job 3 不依赖 GitHub 写入能力。
三、部署步骤:把示例搬进自己的仓库
整个工作流的部署分三步走:
- 复制示例目录:将仓库中的
examples/cicd目录整体拷贝到你的新 Git 仓库中(其中包含run_clearml_checks.yml、三个 Python 脚本、example_task.py、requirements.txt等文件)。 - 放置工作流文件:把
run_clearml_checks.yml移动到新仓库的.github/workflows/run_clearml_checks.yml目录位置,GitHub 才会识别并启用该工作流。 - 配置 Secrets 并开 PR:按照上一节要求把 ClearML(以及可选的 GitHub)凭据加入仓库 Secrets,然后针对
main分支新建一个 PR 并提交改动,GitHub Actions 便会自动触发上述三个 Job。
四、Job 1:把实验指标自动贴到 PR 上
4.1 适用场景
假设你的某个训练实验代码已经用 git 做了版本管理,现在在侧分支上开发了新特性并准备合入 main。你希望合入之前确认:这份代码至少在 ClearML 上成功跑过一次实验。为此,可以借助 ClearML SDK 找到该提交对应的实验 Task,取出最新模型指标,并把它们连同实验链接一起自动发布为 PR 评论,让审查者在 PR 页面上直接看到指标快照。
4.2 核心逻辑拆解
task_stats_to_comment.py 的入口执行了三个动作:
task_obj = get_clearml_task_of_current_commit(os.getenv('COMMIT_ID')) # 定位当前提交对应的 Task
task_obj.add_tags(['main_branch']) # 打标签便于 WebUI 识别
stats = get_task_stats(task_obj) # 生成指标表格文本
create_stats_comment(stats) # 发布到 PR
① 定位 Task:get_clearml_task_of_current_commit
这是整条流水线最关键的函数,它利用 Task.query_tasks() 按提交哈希反向查找实验:
tasks = Task.query_tasks(
task_filter={
'order_by': ['-last_update'],
'_all_': dict(fields=['script.version_num'],
pattern=commit_id
),
'status': ['completed']
},
additional_return_fields=['script.diff']
)
其原理是:ClearML 每次记录任务时,会把 git 提交哈希写入 script.version_num 字段,因此可用 _all_ 过滤器做正则匹配;status: ['completed'] 只保留成功完成的实验;order_by: ['-last_update'] 按最近更新排序。随后遍历结果,通过 additional_return_fields 额外取回的 script.diff 字段判断任务是否与当前提交完全一致——script.diff 为空表示该 Task 是用 PR 中这份完全相同的代码跑的(没有额外补丁)。若遍历完仍找不到,则抛出 ValueError("No task based on this code was found in ClearML..."),从而让该 Job 失败、阻断合并。
关于 task_filter 中 _all_、order_by、status 等字段的语义,可参考 SDK 中 Task.query_tasks 的文档注释(clearml/task.py)。
② 生成指标表格:get_task_stats
拿到 Task 对象后,先检查状态:只有 completed 的任务才提取指标,其他状态直接提示"Task is in xxx status, this should not happen!"。对已完成任务调用 task.get_last_scalar_metrics()(实现见 clearml/task.py),该方法返回形如 {"标题": {"序列": {"last": ..., "min": ..., "max": ...}}} 的三层嵌套字典,随后被展平为 (Title, Series, Last, Min, Max) 元组列表,再用 pandas.DataFrame + tabulate(tablefmt="github",即 GitHub 兼容的 Markdown 表格)渲染成 PR 评论内容,并附上 task.get_output_log_web_page() 返回的实验详情页链接(该接口实现在 clearml/backend_interface/task/task.py)。
③ 发布评论:create_stats_comment
脚本读取 GitHub Actions 自动注入的 GITHUB_EVENT_PATH 环境变量指向的 Webhook payload JSON,从中解析出仓库 full_name 与 PR 号 number,随后用 github3.py 库的 login(token=os.getenv("GH_TOKEN")) 完成登录,并调用 pull_request.create_comment(project_stats) 把表格发布为 PR 评论。
五、Job 2:模型性能回归拦截
5.1 适用场景
Job 1 解决"有没有跑过",Job 2 解决"跑得好不好"。很多团队最担心的是合入一个让模型指标明显变差的改动。这个 Job 会找到当前 PR 对应的实验 Task,把它与历史上表现最好的实验做指标对比,只有当当前指标不差于历史最佳时才允许流水线通过,从而在合并前守护 main 分支的模型质量底线。
5.2 核心逻辑拆解
compare_models.py 直接复用了 Job 1 的 get_clearml_task_of_current_commit(因此它顶部有 from task_stats_to_comment import get_clearml_task_of_current_commit——如果你只想移植 Job 2,务必把该函数一并拷贝过去):
current_task = get_clearml_task_of_current_commit(commit_hash)
best_task = Task.get_task(project_name='Github CICD Video', task_name='cicd_test', tags=['Best Performance'])
if best_task:
best_metric = max(best_task.get_reported_scalars().get('Performance Metric').get('Series 1').get('y'))
current_metric = max(current_task.get_reported_scalars().get('Performance Metric').get('Series 1').get('y'))
if current_metric >= best_metric:
current_task.add_tags(['Best Performance']) # 成为新的最佳
# 否则 Job 静默失败(非零退出之外由上层决定)
这里有几个要点值得说明:
Task.get_task(project_name=..., task_name=..., tags=<a href="https://link.gitcode.com/i/c0f81157badaf3335bf6cb137c312502" target="_blank">'Best Performance'])是"按项目 + 名称 + 标签"定位历史最佳实验的便捷 API。标签Best Performance是这套机制自洽的关键:每次有更优指标出现,代码就把该标签转移到新 Task 上(add_tags会保留旧标签并追加新标签,见 [clearml/task.py)。- 指标对比用的是
get_reported_scalars()(实现在 clearml/backend_interface/task/task.py),它返回完整的标量时间序列,示例取Performance Metric标题下Series 1序列的y数组最大值作为代表指标。注意:这里的Performance Metric/Series 1必须与你的训练脚本report_scalar(title=..., series=...)的命名严格对应,否则get()会返回None而抛错。 - 若系统中尚不存在
Best Performance标签的任务,分支逻辑会把当前任务直接标记为最佳(作为首个基线)。
5.3 与训练脚本的约定
示例配套的 example_task.py 是一个可供联调的最小训练脚本:它调用 Task.init(project_name='Github CICD Video', task_name='dummy_task', reuse_last_task_id=False) 初始化实验,然后在 10 个迭代中通过 task.get_logger().report_scalar(title="Performance Metric", series="Series 1", iteration=i, value=random.randint(0, 100)) 上报随机标量——它产出的正是 Job 2 所依赖的 Performance Metric/Series 1 数据。实际使用时,用你自己的训练脚本替换它,并保持 report_scalar 的标题与序列命名与对比逻辑一致。
六、Job 3:校验代码能否被 ClearML Agent 远程执行
6.1 适用场景
本地开发完成、准备交给 ClearML Agent 在远端真实训练之前,最怕遇到"本地能跑、远端起不来"的问题。这个 Job 的思路是:把 PR 上的代码自动交给 ClearML Agent 拉起来跑一小段,只要 Agent 开始上报迭代(iteration),就证明代码具备远程可运行性。这样每条合入 main 的提交都保证"随时可以远程训练"。
6.2 工作流内的两步操作
与另外两个 Job 不同,Job 3 在 YAML 里额外执行了 clearml-task 命令来远程拉起代码:
echo "TASK_ID=$(
clearml-task --project 'Github CICD Video' --name cicd_test --branch ${{ github.head_ref }} --script task.py --requirements requirements.txt --skip-task-init --queue default | rg -o 'Task id=(.*) sent' -r '$1'
)" >> $GITHUB_OUTPUT
分解一下这条命令:
clearml-task是 ClearML 提供的 CLI 工具(入口实现见 clearml/cli/task/main.py),作用是把一个已存在于 git 仓库中的代码作为远程任务提交给 ClearML 服务器,再由 Agent 拉取执行;--project 'Github CICD Video':指定任务所属项目;--name cicd_test:指定远程任务的名称(注意 Job 2 的Task.get_task(..., task_name='cicd_test', ...)也在按此名称查找,两侧必须一致);--branch ${{ github.head_ref }}:指定远端执行的 git 分支,即当前 PR 的源分支;--script task.py:指定入口脚本(示例仓库中实际存放的是 example_task.py,工作流文件里的task.py需要按你的真实入口脚本名替换);--requirements requirements.txt:指定要在远端安装的依赖清单;--skip-task-init:跳过任务初始化阶段,直接执行脚本;--queue default:指定提交到哪个 Agent 队列(只有指定队列任务才会被真正调度执行,这一点在 CLI 参数定义中有明确说明)。
clearml-task 在执行成功后会向控制台输出形如 Task id=xxxx sent 的日志,工作流用 ripgrep(rg -o 'Task id=(.*) sent' -r '$1')从标准输出中抓取 Task-ID,写入 GITHUB_OUTPUT 供下一步使用。
6.3 轮询脚本的行为
随后执行 python check_remotely_runnable.py "${{ steps.launch_task.outputs.TASK_ID }}",把上一步抓到的 Task-ID 作为参数传给 check_remotely_runnable.py。该脚本的 check_task_status 循环逻辑是:
- 默认超时
timeout=600秒,每 5 秒轮询一次task.get_status()与task.get_last_iteration(); - 状态为
queued(排队中):重置超时计时,等待 Agent 拾取; - 状态为
failed或stopped:直接抛出ValueError,说明远程运行失败,需要到 WebUI 查看日志; - 状态为
in_progress且get_last_iteration() > 0:证明脚本已开始产出迭代,此时调用task.mark_stopped()(手动将任务标记为停止)并task.set_archived(True)(归档该任务,避免垃圾任务堆积,接口见 clearml/backend_interface/task/task.py),随后返回True宣告检查通过; - 超过 600 秒仍未产出任何迭代:抛出
ValueError('Triggered Timeout!')让 Job 失败。
这套「拉任务 → 抓 ID → 轮询迭代」的模式,本质上是把 ClearML 的远程执行能力与 GitHub Actions 的失败语义打通:Agent 侧的任何异常都会被转化为流水线红灯。
七、工作流文件全貌解读
run_clearml_checks.yml 的共性配置值得逐条留意:
- 事件触发:
on.pull_request.branches: [main]且types: [assigned, opened, edited, reopened, synchronize],保证 PR 创建、更新(新 push)时都会重新跑一遍检查; - 运行环境:三个 Job 均使用
runs-on: ubuntu-20.04,Python 版本锁定3.10; - 依赖安装:前两个 Job 安装
clearml pandas tabulate github3.py Jinja2(Job 3 只安装clearml,另用apt-get install ripgrep安装抓取 Task-ID 所需的 ripgrep); - 提交 ID 注入:前两个 Job 通过
env.COMMIT_ID: ${{ github.event.pull_request.head.sha }}把当前 PR 头提交哈希传给脚本(脚本再经os.getenv('COMMIT_ID')读取);第三个 Job 则在actions/checkout时用ref: ${{ github.event.pull_request.head.sha }}检出 PR 对应的确切代码; - 环境变量传递:ClearML SDK 会自动读取
CLEARML_API_ACCESS_KEY/CLEARML_API_SECRET_KEY/CLEARML_API_HOST三个环境变量完成服务器认证,这正是第一节在 Secrets 中配置同名键的原因。
八、依赖清单与移植建议
requirements.txt 中的依赖及版本如下(版本号可按需放宽):
tqdm==4.66.3
clearml>=1.14.4
github3.py==3.2.0
tabulate==0.9.0
pandas==1.5.1
移植到自有项目时,有几点实践建议:
- 按需裁剪 Job:若只需"指标回归拦截",则拷贝
compare_models.py时务必连同它依赖的get_clearml_task_of_current_commit函数一起拷贝(它定义在 task_stats_to_comment.py 中); - 统一命名约定:
clearml-task的--project/--name与Task.get_task(project_name=..., task_name=...)、以及report_scalar的标题/序列名,三处必须完全一致,这是整套检查能闭环的前提; - 保证"先跑后合":Job 1 的语义要求 PR 代码至少在 ClearML 上成功运行过一次,因此团队工作流需约定"改动必须先在 ClearML 跑出 completed 实验再提 PR";
- 本地对照验证:三个脚本均可脱离 GitHub 独立运行(只需设置好
CLEARML_API_*环境变量与COMMIT_ID),适合在本地先验证再接入 CI。
九、小结
通过 examples/cicd 这套示例,可以看到 ClearML 在 MLOps 流水线中的三种典型用法:用 Task.query_tasks + script.diff 把 git 提交与实验精确绑定、用 get_last_scalar_metrics / get_reported_scalars 把实验指标结构化提取出来参与门禁判断、以及用 clearml-task 把任意 PR 代码一键交给 Agent 远端试跑。三者组合,就构成了一条"有记录、有对比、可远程"的模型 CI/CD 防线,直接复刻这套模式即可为自己的 AI 项目建立同样的质量闸门。

