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的一些示例項目。
？需要拍拍。
