cml
v0.20.6
什么是CML？连续机器学习（CML）是用于实施连续集成和交付（CI/CD）的开源CLI工具，重点是MLOP。使用它来自动化开发工作流程 - 包括机器供应，模型培训和评估，比较项目历史记录的ML实验以及监视更改数据集。
CML可以帮助培训和评估模型，然后在每个拉的请求下自动生成带有结果和指标的视觉报告。
神经风格转移模型的示例报告。
CML原则：
❓需要帮助吗？只是想谈论ML的连续集成吗？访问我们的Discord频道！
⏯️使用CML查看我们的YouTube视频系列，以获取动手MLOP教程！
您需要一个GitLab，GitHub或Bitbucket帐户才能开始。用户可能希望熟悉GitHub Action或Gitlab CI/CD。在这里，将讨论GitHub用例。
请使用Gitlab CI/CD，尤其是个人访问令牌要求查看我们在CML上的文档。
请与Bitbucket Cloud一起在CML上查看我们的文档。
任何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基础上设置了Nodejs，Python 3，DVC和CML，以方便起见。
CML提供了许多功能，以帮助将ML工作流的输出（包括数字数据和有关模型性能的可视化）包装到CML报告中。
以下是CML功能表，用于编写Markdown报告并将这些报告交付给您的CI系统。
| 功能 | 描述 | 示例输入 |
|---|---|---|
cml runner launch | 在本地启动跑步者或由云提供商托管 | 请参阅参数 |
cml comment create | 返回CML报告作为您的gitlab/github工作流中的评论 | <path to report> --head-sha <sha> |
cml check create | 返回CML报告作为GITHUB的检查 | <path to report> --head-sha <sha> |
cml pr create | 将给定的文件提交给新分支并创建拉动请求 | <path>... |
cml tensorboard connect | 返回链接到张板。DEV页面 | --logdir <path to logs> --title <experiment title> --md |
cml comment create命令可用于发布报告。 CML报告写在Markdown（GitHub，GitLab或Bitbucket口味）中。这意味着它们可以包含图像，表，格式化的文本，HTML块，代码片段等等 - 实际上，您在CML报告中放置的内容取决于您。一些例子：
？文本使用您喜欢的任何方法写入您的报告。例如，复制包含ML模型培训结果的文本文件的内容：
cat results.txt >> report.md ？图像使用Markdown或HTML显示图像。请注意，如果图像是您的ML工作流程的输出（即，它是由您的工作流产生的），则可以将其上传并自动包含到您的CML报告中。例如，如果python train.py输出graph.png ，则运行：
echo "  " >> report.md
cml comment create report.md
配x 请注意，如果您使用的是gitlab，则需要创建一个个人访问令牌才能使此示例工作。
配x 可以在GitHub浏览器接口中完成以下步骤。但是，要遵循命令，我们建议将您的叉子克隆到本地工作站：
git clone https://github.com/ < your-username > /example_cml.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 "" >> report.md
cml comment create report.md在您选择的文本编辑器中，编辑train.py的第16行至depth = 5 。
提交并推动更改：
git checkout -b experiment
git add . && git commit -m " modify forest depth "
git push origin experimentexperiment分支与main进行比较。不久，您应该看到github-actions的评论出现在带有CML报告的拉动请求中。这是您工作流中cml send-comment函数的结果。
这是CML工作流的概述：
.github/workflows/cml.yaml文件中的工作流程运行，并且CML功能可让您在GitHub检查和评论中显示工作流程中的相关结果（例如模型性能指标和可视化）。您想运行什么样的工作流程，并希望在CML报告中进行哪种工作，这取决于您。
在许多ML项目中，数据并未存储在GIT存储库中，但需要从外部来源下载。 DVC是将数据带入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 "" >> 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 "" >> report.md
cml comment create report.md
配x 如果您将DVC与Cloud Storage一起使用，请注意存储格式的环境变量。
存储提供商可以支持许多支持。以下是一些最常用的提供商的一些示例：
# 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 }}
AWS_SESSION_TOKEN是可选的。
AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY也可以由cml runner使用来启动EC2实例。请参阅[环境变量]。
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 }}
配x 通常，GOOGLE_APPLICATION_CREDENTIALS是包含凭据的json文件的路径。但是，在操作中，此秘密变量是文件的内容。复制json内容并将其添加为秘密。
env :
GOOGLE_APPLICATION_CREDENTIALS : ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
配x 配置Google Drive凭据后，您将在your_project_path/.dvc/tmp/gdrive-user-credentials.json上找到json文件。复制其内容并将其添加为秘密变量。
env :
GDRIVE_CREDENTIALS_DATA : ${{ secrets.GDRIVE_CREDENTIALS_DATA }} 默认情况下，GitHub动作是在GitHub托管的跑步者上运行的。但是，有很多理由使用自己的跑步者：利用GPU，协调团队共享的计算资源或在云中训练。
☝️小费！查看官方的GitHub文档，以开始设置自己的自托管跑步者。
当工作流需要计算资源（例如GPU）时，CML可以使用cml runner自动分配云实例。您可以在AWS，Azure，GCP或Kubernetes上启动实例。
例如，以下工作流在AWS EC2上部署g4dn.xlarge实例，并在实例上训练模型。作业运行后，实例会自动关闭。
您可能会注意到，此工作流与上面的基本用例非常相似。唯一的补充是cml runner和一些环境变量，用于将云服务凭据传递到工作流程。
请注意， cml runner还将自动重新启动您的作业（无论是从GitHub操作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的详细信息，请参见下面的[环境变量]。
？请注意，作业可以使用任何Docker容器！要使用诸如作业中
cml send-comment类的功能，唯一的要求是安装CML。
CML Docker Image（ ghcr.io/iterative/cml或iterativeai/cml ）带有Python，Cuda，Git， git ， node和其他全栈数据科学的必需品。这些必需品的不同版本可从不同的图像标签获得。标签约定为{CML_VER}-dvc{DVC_VER}-base{BASE_VER}{-gpu} ：
{BASE_VER} | 软件包括（ -gpu ） |
|---|---|
| 0 | Ubuntu 18.04，Python 2.7（Cuda 10.1，Cudnn 7） |
| 1 | Ubuntu 20.04，Python 3.8（Cuda 11.2，Cudnn 8） |
例如， iterativeai/cml:0-dvc2-base1-gpu或ghcr.io/iterative/cml:0-dvc2-base1 。
cml runner launch功能接受以下参数：
--labels One or more user-defined labels for
this runner (delimited with commas)
[string] [default: "cml"]
--idle-timeout Time to wait for jobs before
shutting down (e.g. "5min"). Use
"never" to disable
[string] [default: "5 minutes"]
--name Name displayed in the repository
once registered
[string] [default: cml-{ID}]
--no-retry Do not restart workflow terminated
due to instance disposal or GitHub
Actions timeout [boolean]
--single Exit after running a single job
[boolean]
--reuse Don't launch a new runner if an
existing one has the same name or
overlapping labels [boolean]
--reuse-idle Creates a new runner only if the
matching labels don't exist or are
already busy [boolean]
--docker-volumes Docker volumes, only supported in
GitLab [array] [default: []]
--cloud Cloud to deploy the runner
[string] [choices: "aws", "azure", "gcp", "kubernetes"]
--cloud-region Region where the instance is
deployed. Choices: [us-east,
us-west, eu-west, eu-north]. Also
accepts native cloud regions
[string] [default: "us-west"]
--cloud-type Instance type. Choices: [m, l, xl].
Also supports native types like i.e.
t2.micro [string]
--cloud-permission-set Specifies the instance profile in
AWS or instance service account in
GCP [string] [default: ""]
--cloud-metadata Key Value pairs to associate
cml-runner instance on the provider
i.e. tags/labels "key=value"
[array] [default: []]
--cloud-gpu GPU type. Choices: k80, v100, or
native types e.g. nvidia-tesla-t4
[string]
--cloud-hdd-size HDD size in GB [number]
--cloud-ssh-private Custom private RSA SSH key. If not
provided an automatically generated
throwaway key will be used [string]
--cloud-spot Request a spot instance [boolean]
--cloud-spot-price Maximum spot instance bidding price
in USD. Defaults to the current spot
bidding price [number] [default: -1]
--cloud-startup-script Run the provided Base64-encoded
Linux shell script during the
instance initialization [string]
--cloud-aws-security-group Specifies the security group in AWS
[string] [default: ""]
--cloud-aws-subnet, Specifies the subnet to use within
--cloud-aws-subnet-id AWS [string] [default: ""]
配x 您将需要使用存储库读/写访问和工作流特权创建个人访问令牌（PAT）。在示例工作流程中，此令牌存储为PERSONAL_ACCESS_TOKEN。
如果使用--cloud选项，您还需要提供云计算资源的访问凭据作为秘密。在上面的示例中，需要AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY （具有创建和破坏EC2实例的特权）。
对于AWS，相同的凭据也可以用于配置云存储。
CML通过已知环境变量http_proxy和https_proxy支持代理。
这意味着将本地机器用作自主跑步者。 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操作安装，或者在CI Runner提取的自定义Docker映像中预安装。您还可以将CML作为包装安装：
npm install --location=global @dvcorg/cml您可以通过从版本的资产部分下载正确的系统来使用cml无节点。
您可能需要安装其他依赖项来使用DVC图和Vega-Lite CLI命令：
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 ），该软件包管理器（NPM）与nodejs一起运送。安装说明如下。
uses: actions/setup-node@v3
with:
node-version: ' 16 'curl -sL https://deb.nodesource.com/setup_16.x | bash
apt-get update
apt-get install -y nodejs这些是使用CML的一些示例项目。
？需要拍拍。
