ClearML 实战:用 GitHub Actions 构建 AI 模型 CI/CD 流水线(含完整示例与源码解析)

原创2026-10-14 10:21:141,161 阅读
文章标签:MLOpsLLMOps人工智能

ClearML 实战:用 GitHub Actions 构建 AI 模型 CI/CD 流水线(含完整示例与源码解析)

本文以 ClearML 开源仓库中的 CI/CD 示例 为主线,系统讲解如何把 ClearML 的实验管理、模型指标、远程执行能力接入 GitHub Actions,实现「PR 自动展示模型指标」「模型性能回归拦截」「远程可运行性校验」三类自动化检查。读完本文,你将掌握三个可直接复用的 CI/CD Job 的完整配置、底层 ClearML SDK 调用原理,以及 clearml-task 命令行在流水线中的正确用法。

ClearML 三个 CI 检查任务全部通过时的 GitHub Actions 运行结果

一、示例概览:三个 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,如下图所示。

ClearML WebUI 中创建 API 凭据的页面

注意工作流文件的实际键名:在 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 写入能力。

三、部署步骤:把示例搬进自己的仓库

整个工作流的部署分三步走:

  1. 复制示例目录:将仓库中的 examples/cicd 目录整体拷贝到你的新 Git 仓库中(其中包含 run_clearml_checks.yml、三个 Python 脚本、example_task.py、requirements.txt 等文件)。
  2. 放置工作流文件:把 run_clearml_checks.yml 移动到新仓库的 .github/workflows/run_clearml_checks.yml 目录位置,GitHub 才会识别并启用该工作流。
  3. 配置 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

移植到自有项目时,有几点实践建议:

  1. 按需裁剪 Job:若只需"指标回归拦截",则拷贝 compare_models.py 时务必连同它依赖的 get_clearml_task_of_current_commit 函数一起拷贝(它定义在 task_stats_to_comment.py 中);
  2. 统一命名约定:clearml-task 的 --project/--name 与 Task.get_task(project_name=..., task_name=...)、以及 report_scalar 的标题/序列名,三处必须完全一致,这是整套检查能闭环的前提;
  3. 保证"先跑后合":Job 1 的语义要求 PR 代码至少在 ClearML 上成功运行过一次,因此团队工作流需约定"改动必须先在 ClearML 跑出 completed 实验再提 PR";
  4. 本地对照验证:三个脚本均可脱离 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 项目建立同样的质量闸门。

登录后查看全文
clearml