# 让评审一眼看出 PR 有没有拖累模型

> 借助 CML，一个工作流文件加三个 Python 脚本，就能让每个 PR 自动评论指标和图表。

原文: https://fdetimes.net/zh/guides/cml-ci-cd-ml-metrics-pull-requests/

在不少机器学习团队里，代码评审中最难回答的问题与代码本身无关，而是：这次改动让模型变好了还是变差了？评审者在 diff 里看到三行特征代码被改动，但直到模型上了生产环境，才有人发现准确率已经从 0.91 降到了 0.89。

CML 是 Continuous Machine Learning（持续机器学习）的缩写，自称是面向机器学习项目的持续集成/持续交付（CI/CD）工具。它的承诺很具体：每个 pull request 都会生成一份自己的报告，包含指标和图表。本文在 GitHub 上从头到尾搭建这样一条流水线。

对想成为前线部署工程师（FDE）的人来说，这项技能马上就能派上用场。到了客户现场，别一上来就提议建设一个庞大的 MLOps 平台。先在客户自己的仓库里跑起一个小机制，让每个人都能看到每次修改之后模型如何变化。

## 机器学习的 CI 和 Web 应用的 CI 有什么不同？

GitLab 对 CI 的定义是：通过自动构建和测试，尽早、频繁地验证代码变更。CD 则自动准备好通过测试的代码，使其随时可以部署。Google Cloud 的 MLOps 文档把这个范围扩展到了机器学习系统：CI 还必须测试数据、数据 schema 和模型。

Google 还单独提出了持续训练（CT），即自动重新训练并上线模型，并称这是机器学习系统独有的特性。正因如此，本文的流水线分为三个阶段：检查数据、重新训练、对比指标。代码通过了测试，模型照样可能变差。

## 要搭建什么，需要准备什么

先看最终效果。每当有人打开 pull request，GitHub Actions 就会运行一个工作流。GitHub 文档将工作流定义为运行一个或多个 job 的自动化流程。它由事件触发，即仓库中的某个特定活动，比如打开 pull request。

你的 job 要完成这些事：检查数据、训练模型、将结果与基线对比，再由 CML 把结果表发布到 PR。

你需要一个 GitHub 仓库、Python、仓库里一个小型 CSV 数据文件，以及一个几分钟内就能训练完的模型。下面的示例做了简化，便于理解。列名、库和阈值都只是占位，请换成你自己的。

## 第 1 步：在训练前拦下坏数据

训练很花时间，所以要先发现数据错误。下面的脚本检查所有必需列是否齐全、是否存在空值。任一检查失败，脚本都会以非零状态码退出，工作流随之终止。

```python
# check_data.py（简化示例）
import sys
import pandas as pd

EXPECTED = ["tenure", "monthly_spend", "churned"]
df = pd.read_csv("data/train.csv")

missing = [c for c in EXPECTED if c not in df.columns]
if missing:
    sys.exit(f"缺少列：{missing}")
if df[EXPECTED].isnull().any().any():
    sys.exit("必需列中存在空值")
print(f"OK：共 {len(df)} 行")
```

测试方法：先在本地运行 `python check_data.py`，然后从 CSV 中删掉一列再运行一次，脚本应当报错。如果从没见过检查失败，就说明你还没真正测试过它。

## 第 2 步：训练并把指标写入文件

对 `train.py` 的唯一要求是把指标写进一个机器可读的文件。训练代码怎么写由你决定，需要保留的是结尾部分。

```python
# train.py 结尾部分（简化）
import json
metrics = {"accuracy": round(acc, 4), "recall": round(rec, 4)}
with open("metrics.json", "w") as f:
    json.dump(metrics, f)
```

在主分支上运行一次，把输出复制为 `baseline.json` 并提交。之后每个 PR 都与这个参照点对比。这比在 CI 里直接与主分支对比更简单，代价是接受新模型时要记得更新基线。

## 第 3 步：生成 Markdown 对比报告

CML 评论使用 Markdown，所以对比脚本只需打印一张表格。

```python
# compare.py（简化）
import json
base = json.load(open("baseline.json"))
new = json.load(open("metrics.json"))

print("| 指标 | 基线 | PR | 差值 |")
print("|---|---|---|---|")
for k in base:
    d = new[k] - base[k]
    flag = "⚠️" if d < -0.01 else ""
    print(f"| {k} | {base[k]} | {new[k]} | {d:+.4f} {flag} |")
```

用假设的数字试一下：基线准确率为 0.91，PR 得到 0.89。差值为 -0.02，超过了 -0.01 的阈值，因此这一行会被打上警告标记。评审者一眼就能看到，不用再去重跑别人的 notebook。

## 第 4 步：把一切接入工作流

创建文件 `.github/workflows/cml.yaml`。以下细节来自 CML 文档：用 `setup-cml` action 安装 CML，不需要 Docker 容器；通过 `REPO_TOKEN` 变量传入 token，其值取自 `secrets.GITHUB_TOKEN`；最后一步调用 `cml comment create`。其余部分都是最精简的 GitHub Actions 骨架。action 的版本标签请对照 CML 的 Get Started 页面确认。

```yaml
name: model-check
on: pull_request
jobs:
  train-and-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: iterative/setup-cml@v2   # 请对照 CML 文档确认版本标签
      - name: Check data, train, report
        env:
          REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          pip install -r requirements.txt
          python check_data.py
          python train.py
          python compare.py > report.md
          cml comment create report.md
```

`run` 中命令的顺序体现了整篇指南的逻辑：坏数据在第二行就会终止运行，不会在训练上浪费任何时间。

## 第 5 步：打开 PR，查看评论

新建一个分支，改动一个模型参数，push 后打开 pull request。CML 文档用一句话描述了接下来的情况：稍等片刻，PR 中就会出现一条带有 CML 报告的评论。第 3 步生成的指标表会显示在 PR 描述下方。

再测试两种情况。第一，提交一个破坏 CSV 的 PR：工作流应当在数据检查这一步失败。第二，提交一个降低指标的 PR：工作流应当通过，但评论里应带有警告标记。这是两种不同的失败，团队需要能区分它们。

## 最常见的错误

第一个错误是 runner 上没有数据。如果数据由 DVC 管理，要注意 CML 不自带 DVC 及其依赖。文档说明，必须在数据检查步骤之前单独添加 Setup DVC action。

第二个错误是工作流通过了，却没有发出评论。先检查 `REPO_TOKEN` 是否放在调用 `cml comment create` 那一步的 `env` 中，再检查仓库设置里该 token 的权限。

第三个错误更难察觉：基线过时。如果合并了一个更好的模型，却忘了更新 `baseline.json`，之后的每个 PR 都会和一个过时的参照点对比，看起来比实际更好。

## 这项技能在客户现场的用武之地

据 CML 官网介绍，该工具借助 GitLab、GitHub 或 Bitbucket 管理机器学习实验，并追踪谁在什么时候训练了模型或改动了数据。模型出问题时，你要回答的恰恰是这些问题：谁、在什么时候、改了什么。

如果 PR 历史能回答这些问题，就不用去翻每个人的 notebook。

一个实用建议：和客户合作的第一周，先别急着提议新的 MLOps 平台。问清楚他们用哪家 Git 托管服务，然后只为他们最重要的那个模型搭一个这样的工作流。

浏览 FDE 或机器学习工程师的岗位描述时，如果看到“CI/CD for ML”“model validation”或“reproducible training”这类字眼，就要准备好讲清楚这样一条流水线，最好配上一张 PR 中指标评论的截图。

**要点:** 好的机器学习流水线不只是能跑通，而是能在正确的时刻失败：坏数据让运行终止，模型变差会在 pull request 中被标记出来。

最终目标是让客户团队先看指标表，再看 diff。这样，每个 pull request 都会自己回答评审中最难的那个问题：模型是变好了，还是变差了？

**本周动手试试:**

- 找一个旧的训练 notebook，改写成把指标写入 metrics.json 的 train.py，并提交一份 baseline.json。
- 把本文的 CML 工作流加到个人仓库，故意提交一个降低指标的 PR，看评论如何标记它。
- 在简历中加上具体的一行：“使用 CML 为机器学习模型搭建 CI：数据 schema 校验、重新训练，并在每个 pull request 上自动生成指标报告”。

## 信源

- [CML (Continuous Machine Learning)](https://cml.dev/)

- [Get Started | CML](https://cml.dev/doc/start)

- [Get Started with CML on GitHub](https://cml.dev/doc/start/github)

- [What is CI/CD?](https://about.gitlab.com/topics/ci-cd/)

- [GitHub Actions documentation](https://docs.github.com/en/actions)

- [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions)

- [MLOps: Continuous delivery and automation pipelines in machine learning](https://docs.cloud.google.com/architecture/mlops-continuous-delivery-and-automation-pipelines-in-machine-learning)
