什么是 CML？ 连续机器学习（CML）是一个开源的命令行界面 (CLI) 工具，专注于 MLOps，用于实现持续集成与交付 (CI/CD)。使用它来自动化开发工作流——包括机器配置、模型训练和评估、跨项目历史比较 ML 实验，以及监控变化的数据集。

CML 可以帮助训练和评估模型——并在每次 pull request (拉取请求) 时自动生成包含结果和指标的可视化报告。

一个 神经风格迁移模型 的报告示例。

CML 原则：

• GitFlow 用于数据科学。 使用 GitLab 或 GitHub 管理 ML 实验，跟踪谁训练了 ML 模型或修改了数据及时间。使用 DVC 对数据和模型进行代码化管理，而不是推送到 Git 仓库。
• ML 实验自动报告。 在每个 Git pull request 中自动生成带有指标和图表的报告。严谨的工程实践帮助您的团队做出明智的、数据驱动的决策。
• 无需额外服务。 使用 GitLab、Bitbucket 或 GitHub 构建您自己的 ML 平台。可选地，使用 云存储 以及自托管或云运行器（如 AWS EC2 或 Azure）。无需数据库、服务或复杂设置。

:question: 需要帮助？只是想聊聊 ML 的持续集成吗？访问我们的 Discord 频道！

:play_or_pause_button: 查看我们的 YouTube 视频系列，获取使用 CML 的动手 MLOps 教程！

目录

1. 设置 (GitLab, GitHub, Bitbucket)
2. 用法
3. 入门 (教程)
4. 将 CML 与 DVC 配合使用
5. 高级设置 (自托管，本地包)
6. 示例项目

设置

您需要一个 GitLab、GitHub 或 Bitbucket 账户才能开始。用户可能希望熟悉 Github Actions 或 GitLab CI/CD。这里我们将讨论 GitHub 用例。

GitLab

请参阅我们关于 CML with GitLab CI/CD 的文档，特别是 personal access token (个人访问令牌) 要求。

Bitbucket

请参阅我们关于 CML with Bitbucket Cloud 的文档。

GitHub

任何 CML 项目中的关键文件是 .github/workflows/cml.yaml：

name: your-workflow-name
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    # optionally use a convenient Ubuntu LTS + DVC + CML image
    # container: ghcr.io/iterative/cml:0-dvc2-base1
    steps:
      - uses: actions/checkout@v3
      # may need to setup NodeJS & Python3 on e.g. self-hosted
      # - uses: actions/setup-node@v3
      #   with:
      #     node-version: '16'
      # - uses: actions/setup-python@v4
      #   with:
      #     python-version: '3.x'
      - uses: iterative/setup-cml@v1
      - name: Train model
        run: |
          # Your ML workflow goes here
          pip install -r requirements.txt
          python train.py
      - name: Write CML report
        env:
          REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Post reports as comments in GitHub PRs
          cat results.txt >> report.md
          cml comment create report.md

用法

我们在 自定义 Docker 镜像 上预先安装了 CML 和其他有用的库。在上面的示例中，取消注释字段 container: ghcr.io/iterative/cml:0-dvc2-base1) 将使运行器拉取 CML Docker 镜像。该镜像为了方便起见，已在 Ubuntu LTS 基础之上设置了 Node.js、Python 3、DVC 和 CML。

CML 函数

CML 提供了一系列函数，帮助将 ML 工作流的输出（包括数值数据和关于模型性能的可视化）打包到 CML 报告中。

以下是用于编写 Markdown 报告并将这些报告交付给 CI 系统的 CML 函数表。

CML 报告

cml comment create 命令可用于发布报告。CML 报告是用 Markdown 编写的（GitHub、GitLab 或 Bitbucket 风格）。这意味着它们可以包含图片、表格、格式化文本、HTML 块、代码片段等——实际上，您在 CML 报告中放入什么取决于您。一些示例：

:spiral_notepad: 文本 使用您喜欢的方法写入报告。例如，复制包含 ML 模型训练结果的文本文件的内容：

cat results.txt >> report.md

:framed_picture: 图片 使用 Markdown 或 HTML 显示图片。请注意，如果图片是您的 ML 工作流的输出（即由您的工作流生成），它可以被上传并自动包含到您的 CML 报告中。例如，如果 graph.png 是由 python train.py 输出的，请运行：

echo "![](./graph.png)" >> report.md
cml comment create report.md

开始使用

1. Fork（复制）我们的 示例项目仓库。

:warning: 注意，如果您使用的是 GitLab， 您需要创建一个 Personal Access Token（个人访问令牌） 才能使此示例正常工作。

:warning: 以下步骤都可以在 GitHub 浏览器界面中完成。但是，为了跟随命令操作，我们建议将您的 Fork（复制）克隆到本地工作站：

git clone https://github.com/<your-username>/example_cml

2. 要创建 CML（Continuous Machine Learning）工作流，请将以下内容复制到新文件 .github/workflows/cml.yaml：

name: model-training
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - uses: iterative/setup-cml@v1
      - name: Train model
        env:
          REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          pip install -r requirements.txt
          python train.py

          cat metrics.txt >> report.md
          echo "![](./plot.png)" >> report.md
          cml comment create report.md

3. 在您选择的文本编辑器中，将 train.py 的第 16 行修改为 depth = 5。

4. 提交并推送更改：

git checkout -b experiment
git add . && git commit -m "modify forest depth"
git push origin experiment

5. 在 GitHub 上，打开一个拉取请求（Pull Request）以比较 experiment 分支和 main 分支。

很快，您应该在拉取请求中看到来自 github-actions 的评论，其中包含您的 CML 报告。这是您工作流中 cml send-comment 函数的结果。

这是 CML 工作流的概述：

• 您将更改推送到 GitHub 仓库，
• 运行 .github/workflows/cml.yaml 文件中的工作流，以及
• 生成报告并发布到 GitHub。

CML 功能允许您在 GitHub Checks（检查）和评论中显示工作流的相关结果——例如模型性能指标和可视化图表。您想要运行哪种工作流，以及想要在 CML 报告中放入什么内容，由您决定。

将 CML 与 DVC 结合使用

在许多机器学习（ML）项目中，数据不存储在 Git 仓库中，而是需要从外部来源下载。DVC（Data Version Control）是将数据带入您的 CML 运行器的常见方式。DVC 还允许您可视化不同提交之间的指标差异，从而生成如下报告：

用于创建此报告的 .github/workflows/cml.yaml 文件如下：

name: model-training
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    container: ghcr.io/iterative/cml:0-dvc2-base1
    steps:
      - uses: actions/checkout@v3
      - name: Train model
        env:
          REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          # Install requirements
          pip install -r requirements.txt

          # Pull data & run-cache from S3 and reproduce pipeline
          dvc pull data --run-cache
          dvc repro

          # Report metrics
          echo "## Metrics" >> report.md
          git fetch --prune
          dvc metrics diff main --show-md >> report.md

          # Publish confusion matrix diff
          echo "## Plots" >> report.md
          echo "### Class confusions" >> report.md
          dvc plots diff --target classes.csv --template confusion -x actual -y predicted --show-vega main > vega.json
          vl2png vega.json -s 1.5 > confusion_plot.png
          echo "![](./confusion_plot.png)" >> report.md

          # Publish regularization function diff
          echo "### Effects of regularization" >> report.md
          dvc plots diff --target estimators.csv -x Regularization --show-vega main > vega.json
          vl2png vega.json -s 1.5 > plot.png
          echo "![](./plot.png)" >> report.md

          cml comment create report.md

:warning: 如果您将 DVC 与云存储一起使用，请注意您的存储格式的环境变量。

配置云存储提供商

有许多 支持的云存储提供商。 以下是一些最常用提供商的示例：

# Github
env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  AWS_SESSION_TOKEN: ${{ secrets.AWS_SESSION_TOKEN }}

env:
  AZURE_STORAGE_CONNECTION_STRING:
    ${{ secrets.AZURE_STORAGE_CONNECTION_STRING }}
  AZURE_STORAGE_CONTAINER_NAME: ${{ secrets.AZURE_STORAGE_CONTAINER_NAME }}

env:
  OSS_BUCKET: ${{ secrets.OSS_BUCKET }}
  OSS_ACCESS_KEY_ID: ${{ secrets.OSS_ACCESS_KEY_ID }}
  OSS_ACCESS_KEY_SECRET: ${{ secrets.OSS_ACCESS_KEY_SECRET }}
  OSS_ENDPOINT: ${{ secrets.OSS_ENDPOINT }}

env:
  GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}

env:
  GDRIVE_CREDENTIALS_DATA: ${{ secrets.GDRIVE_CREDENTIALS_DATA }}

高级设置

自托管（本地或云端）运行器

默认情况下，GitHub Actions 在 GitHub 托管的运行器上运行。但是，使用自己的运行器有很多很好的理由：利用 GPU、协调团队共享的计算资源，或在云端进行训练。

:point_up: 提示！ 查看 官方 GitHub 文档 以开始设置您自己的自托管运行器。

使用 CML 分配云计算资源

当工作流需要计算资源（如 GPU）时，CML 可以使用 cml runner（CML Runner）自动分配云实例。你可以在 AWS、Azure、GCP 或 Kubernetes 上启动实例。

例如，以下工作流在 AWS EC2 上部署一个 g4dn.xlarge 实例并在该实例上训练模型。作业运行后，实例会自动关闭。

你可能会注意到这个工作流与上面的 基本用例 非常相似。唯一的区别是增加了 cml runner 和一些环境变量，用于将云服务凭证传递给工作流。

请注意，cml runner 也会自动重启你的任务（无论是由于 GitHub Actions 35 天工作流超时 还是 AWS EC2 竞价实例中断）。

name: Train-in-the-cloud
on: [push]
jobs:
  deploy-runner:
    runs-on: ubuntu-latest
    steps:
      - uses: iterative/setup-cml@v1
      - uses: actions/checkout@v3
      - name: Deploy runner on EC2
        env:
          REPO_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          cml runner launch \
            --cloud=aws \
            --cloud-region=us-west \
            --cloud-type=g4dn.xlarge \
            --labels=cml-gpu
  train-model:
    needs: deploy-runner
    runs-on: [self-hosted, cml-gpu]
    timeout-minutes: 50400 # 35 days
    container:
      image: ghcr.io/iterative/cml:0-dvc2-base1-gpu
      options: --gpus all
    steps:
      - uses: actions/checkout@v3
      - name: Train model
        env:
          REPO_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
        run: |
          pip install -r requirements.txt
          python train.py

          cat metrics.txt > report.md
          cml comment create report.md

在上述工作流中，deploy-runner 步骤在 us-west 区域启动了一个 EC2 g4dn.xlarge 实例。然后 model-training 步骤在新启动的实例上运行。有关所需 secrets（机密）的详细信息，请参见下方的 [环境变量]。

:tada: 注意：作业可以使用任何 Docker 容器！ 要从作业中使用 cml send-comment 等功能，唯一的要求是 安装 CML。

Docker 镜像

CML Docker 镜像（ghcr.io/iterative/cml 或 iterativeai/cml）预装了 Python、CUDA、git、node 以及全栈数据科学所需的其他基础组件。这些基础组件的不同版本可通过不同的镜像标签获取。标签约定为 {CML_VER}-dvc{DVC_VER}-base{BASE_VER}{-gpu}：

例如，iterativeai/cml:0-dvc2-base1-gpu，或 ghcr.io/iterative/cml:0-dvc2-base1。

参数

cml runner launch 函数接受以下参数：

--labels 一个或多个用户定义的标签，用于此运行器 (Runner)（以逗号分隔） [string] [default: "cml"] --idle-timeout 关闭前等待作业的时间（例如 "5min"）。使用 "never" 可禁用 [string] [default: "5 minutes"] --name 注册后在仓库中显示的名称 [string] [default: cml-{ID}] --no-retry 不重启因实例销毁或 GitHub Actions 超时而终止的工作流 [boolean] --single 运行单个作业后退出 [boolean] --reuse 如果已存在的运行器具有相同名称或 重叠的标签，则不启动新的运行器 [boolean] --reuse-idle 仅当匹配的标签不存在或已占用时，才 创建新的运行器 [boolean] --docker-volumes Docker 卷，仅在 GitLab 中支持 [array] [default: []] --cloud 部署运行器的云服务 [string] [choices: "aws", "azure", "gcp", "kubernetes"] --cloud-region 实例部署的区域。选项：[us-east, us-west, eu-west, eu-north]。也 接受原生云区域 [string] [default: "us-west"] --cloud-type 实例类型。选项：[m, l, xl]。 也支持原生类型，如 t2.micro [string] --cloud-permission-set 指定 AWS 中的实例配置文件或 GCP 中的实例服务账户 [string] [default: ""] --cloud-metadata 与提供商上的 cml-runner 实例关联 的键值对，即标签/标签 "key=value" [array] [default: []] --cloud-gpu GPU 类型。选项：k80, v100，或 原生类型，例如 nvidia-tesla-t4 [string] --cloud-hdd-size HDD 大小（GB） [number] --cloud-ssh-private 自定义私有 RSA SSH 密钥。如果未 提供，将使用自动生成的临时密钥 [string] --cloud-spot 请求抢占式实例 [boolean] --cloud-spot-price 抢占式实例的最高竞价价格 （美元）。默认为当前竞价价格 [number] [default: -1] --cloud-startup-script 在实例初始化期间运行提供的 Base64 编码 的 Linux shell 脚本 [string] --cloud-aws-security-group 指定 AWS 中的安全组 [string] [default: ""] --cloud-aws-subnet, 指定要在 AWS 内使用的子网 --cloud-aws-subnet-id AWS [string] [default: ""]

环境变量

:warning: 你需要 创建一个个人访问令牌 (PAT) 并拥有仓库读写权限及工作流权限。在示例工作流中，此令牌存储为 PERSONAL_ACCESS_TOKEN。

:information_source: 如果使用 --cloud 选项，你还需要提供云计算资源的访问凭据作为机密。在 上述示例中，需要提供 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY（具有创建和销毁 EC2 实例的权限）。

对于 AWS，相同的凭据也可用于 配置云存储。

代理支持

CML 通过已知环境变量 http_proxy 和 https_proxy 支持代理。

本地部署 (On-premise) 运行器

这意味着使用本地部署的机器作为自托管运行器。cml runner launch 函数用于设置本地自托管运行器。在本地机器或本地 GPU 集群上， 安装 CML 包，然后运行：

cml runner launch \
  --repo=$your_project_repository_url \
  --token=$PERSONAL_ACCESS_TOKEN \
  --labels="local,runner" \
  --idle-timeout=180

该机器将监听来自项目仓库的工作流。

本地包

在上述示例中，CML 是通过 setup-cml action 安装的，或者随持续集成 (CI) 运行器拉取的自定义 Docker 镜像预装。您也可以将 CML 作为包进行安装：

npm install --location=global @dvcorg/cml

您可以通过从 releases 的资源部分下载适用于您系统的正确独立二进制文件，从而在不使用 Node 的情况下使用 cml。

您可能需要安装额外的依赖项才能使用 DVC 图表和 Vega-Lite 命令行命令：

sudo apt-get install -y libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev \
                        librsvg2-dev libfontconfig-dev
npm install -g vega-cli vega-lite

CML 和 Vega-Lite 包的安装需要 NodeJS 包管理器（npm），该管理器随 NodeJS 一同提供。安装说明如下。

安装 NodeJS

• GitHub：在使用 GitHub 默认容器或 CML 的 Docker 容器之一时，这可能不是必需的。自托管运行器可能需要使用设置 action 来安装 NodeJS：

uses: actions/setup-node@v3
  with:
    node-version: '16'

• GitLab：需要直接安装。

curl -sL https://deb.nodesource.com/setup_16.x | bash
apt-get update
apt-get install -y nodejs

参见

以下是一些使用 CML 的示例项目。

• 基础 CML 项目
• 使用 DVC 拉取数据的 CML
• 使用 Tensorboard 的 CML
• 使用小型 EC2 实例的 CML :key:
• 使用 EC2 GPU 的 CML :key:

:key: 需要 个人访问令牌 (PAT)。

:warning: 维护 :warning:

• ~2023-07 Nvidia 已停止提供带有 10.x/cudnn7 和 11.2.1 的容器 CUDA 镜像，CML 镜像将相应更新

CML 快速上手指南

CML (Continuous Machine Learning) 是一个开源的 CLI 工具，专注于 MLOps 领域的持续集成与交付（CI/CD）。它可自动在每次 Pull Request 时训练和评估模型，并生成包含指标和图表的可视化报告。

1. 环境准备

• 账号要求：需要 GitHub、GitLab 或 Bitbucket 账户（本指南以 GitHub 为例）。
• 系统环境：推荐使用 Ubuntu LTS 系统，或直接使用 CML 提供的预配置 Docker 镜像。
• 前置知识：熟悉 Git 操作及 GitHub Actions / GitLab CI/CD 基础概念。
• 网络环境：由于依赖 GitHub 和 Docker Hub，请确保开发环境能正常访问相关服务。

2. 安装步骤

CML 主要通过两种方式使用：在 CI 流水线中集成，或在本地运行 CLI。

方式一：在 GitHub Actions 中使用（推荐）

无需手动安装软件，直接在 Workflow 文件中引入 Action 即可。在 .github/workflows/ 目录下创建文件，添加以下步骤：

- uses: iterative/setup-cml@v1

方式二：本地安装 CLI

若需在本地测试命令，可通过 npm 全局安装：

npm install -g @dvcorg/cml

注意：也可使用官方提供的 Docker 镜像，其中已预装 NodeJS、Python3、DVC 和 CML。

container: ghcr.io/iterative/cml:0-dvc2-base1

3. 基本使用

创建一个简单的模型训练工作流，将结果自动发布为 PR 评论。

第一步：创建工作流文件

在项目根目录创建 .github/workflows/cml.yaml，内容如下：

name: model-training
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - uses: iterative/setup-cml@v1
      - name: Train model
        env:
          REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          pip install -r requirements.txt
          python train.py

          cat metrics.txt >> report.md
          echo "![](./plot.png)" >> report.md
          cml comment create report.md

第二步：执行与查看

1. 提交并推送代码到远程仓库。
2. 在 GitHub 上打开对应的 Pull Request。
3. 等待工作流运行完成，你将看到由 github-actions 机器人发布的评论，其中包含你的训练报告和图表。

常用命令参考