cml
v0.20.6
Qu'est-ce que CML? L'apprentissage automatique continu (CML) est un outil CLI open-source pour implémenter l'intégration et la livraison continues (CI / CD) avec un accent sur les MLOPS. Utilisez-le pour automatiser les workflows de développement - y compris l'approvisionnement en machines, la formation et l'évaluation du modèle, la comparaison des expériences ML à travers l'historique du projet et la surveillance des ensembles de données changeants.
CML peut aider à former et à évaluer les modèles - puis générer un rapport visuel avec des résultats et des mesures - automatiquement sur chaque demande de traction.
Un exemple de rapport pour un modèle de transfert de style neuronal.
Principes CML:
❓ Besoin d'aide? Vous voulez juste discuter de l'intégration continue pour ML? Visitez notre canal Discord!
⏯️ Consultez notre série de vidéos YouTube pour les tutoriels pratiques Mlops en utilisant CML!
Vous aurez besoin d'un compte Gitlab, Github ou Bitbucket pour commencer. Les utilisateurs peuvent souhaiter se familiariser avec les actions GitHub ou GitLab CI / CD. Ici, discutera du cas d'utilisation GitHub.
Veuillez consulter nos documents sur CML avec GitLab CI / CD et en particulier l'exigence de jeton d'accès personnel.
Veuillez consulter nos documents sur CML avec Bitbucket Cloud.
Le fichier clé dans n'importe quel projet CML est .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 Nous fournissons utilement CML et d'autres bibliothèques utiles préinstallées sur nos images Docker personnalisées. Dans l'exemple ci-dessus, la découverte du container: ghcr.io/iterative/cml:0-dvc2-base1 ) fera en sorte que le coureur tirera l'image cml docker. L'image a déjà NodeJS, Python 3, DVC et CML configurées sur une base Ubuntu LTS pour plus de commodité.
CML fournit un certain nombre de fonctions pour aider à emballer les sorties de workflows ML (y compris des données numériques et des visualisations sur les performances du modèle) dans un rapport CML.
Vous trouverez ci-dessous un tableau des fonctions CML pour rédiger des rapports Markdown et la livraison de ces rapports à votre système CI.
| Fonction | Description | Exemples d'entrées |
|---|---|---|
cml runner launch | Lancez un coureur localement ou hébergé par un fournisseur de cloud | Voir les arguments |
cml comment create | Renvoie le rapport CML en tant que commentaire dans votre flux de travail GitLab / GitHub | <path to report> --head-sha <sha> |
cml check create | Renvoie le rapport CML en tant que chèque GitHub | <path to report> --head-sha <sha> |
cml pr create | Engager les fichiers donnés dans une nouvelle branche et créer une demande de traction | <path>... |
cml tensorboard connect | Renvoyez un lien vers une page tensorboard.dev | --logdir <path to logs> --title <experiment title> --md |
La commande cml comment create peut être utilisée pour publier des rapports. Les rapports CML sont écrits dans Markdown (saveurs GitHub, Gitlab ou Bitbucket). Cela signifie qu'ils peuvent contenir des images, des tables, du texte formaté, des blocs HTML, des extraits de code et plus encore - vraiment, ce que vous mettez dans un rapport CML dépend de vous. Quelques exemples:
? ️ Texte écrivez à votre rapport en utilisant la méthode que vous préférez. Par exemple, copiez le contenu d'un fichier texte contenant les résultats de la formation du modèle ML:
cat results.txt >> report.md ? ️ Les images affichent des images à l'aide de Markdown ou HTML. Notez que si une image est une sortie de votre flux de travail ML (c'est-à-dire qu'elle est produite par votre flux de travail), il peut être téléchargé et inclus automatiquement dans votre rapport CML. Par exemple, si graph.png est sorti par python train.py , exécutez:
echo "  " >> report.md
cml comment create report.md
️ Notez que si vous utilisez GitLab, vous devrez créer un jeton d'accès personnel pour cet exemple.
️ Les étapes suivantes peuvent toutes être effectuées dans l'interface du navigateur GitHub. Cependant, pour suivre les commandes, nous vous recommandons de cloner votre fourchette à votre poste de travail local:
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 Dans votre éditeur de texte de choix, modifiez la ligne 16 de train.py to depth = 5 .
Engager et pousser les changements:
git checkout -b experiment
git add . && git commit -m " modify forest depth "
git push origin experimentexperiment à main . Peu de temps, vous devriez voir un commentaire des github-actions apparaissent dans la demande de traction avec votre rapport CML. Ceci est le résultat de la fonction cml send-comment dans votre flux de travail.
Ceci est le contour du flux de travail CML:
.github/workflows/cml.yaml est exécuté, etLes fonctions CML vous permettent d'afficher les résultats pertinents du flux de travail - tels que les métriques et visualisations de performances du modèle - dans les vérifications et commentaires GitHub. Quel type de workflow que vous souhaitez exécuter et que vous souhaitez mettre dans votre rapport CML, dépend de vous.
Dans de nombreux projets ML, les données ne sont pas stockées dans un référentiel GIT, mais doivent être téléchargées à partir de sources externes. DVC est un moyen courant d'apporter des données à votre coureur CML. DVC vous permet également de visualiser comment les métriques diffèrent entre les engagements pour faire des rapports comme celui-ci:
Le fichier .github/workflows/cml.yaml utilisé pour créer ce rapport est:
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
️ Si vous utilisez DVC avec le stockage cloud, notez les variables d'environnement pour votre format de stockage.
Il existe de nombreux fournisseurs de stockage pris en charge. Voici quelques exemples pour certains des fournisseurs les plus fréquemment utilisés:
# 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_TOKENest facultatif.
AWS_ACCESS_KEY_IDetAWS_SECRET_ACCESS_KEYpeuvent également être utilisés parcml runnerpour lancer des instances EC2. Voir [Variables d'environnement].
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 }}
️ Normalement,GOOGLE_APPLICATION_CREDENTIALSest le chemin d'accès du fichierjsoncontenant les informations d'identification. Cependant, dans l'action, cette variable secrète est le contenu du fichier. Copiez le contenujsonet ajoutez-le comme secret.
env :
GOOGLE_APPLICATION_CREDENTIALS : ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
️ Après avoir configuré vos informations d'identification Google Drive, vous trouverez un fichierjsonsuryour_project_path/.dvc/tmp/gdrive-user-credentials.json. Copiez son contenu et ajoutez-le comme variable secrète.
env :
GDRIVE_CREDENTIALS_DATA : ${{ secrets.GDRIVE_CREDENTIALS_DATA }} Les actions GitHub sont exécutées sur des coureurs hébergés par GitHub par défaut. Cependant, il existe de nombreuses raisons d'utiliser vos propres coureurs: pour profiter des GPU, orchestrer les ressources informatiques partagées de votre équipe ou s'entraîner dans le cloud.
☝️ Astuce! Consultez la documentation officielle de GitHub pour commencer la configuration de votre propre coureur auto-hébergé.
Lorsqu'un workflow nécessite des ressources de calcul (telles que les GPU), CML peut automatiquement allouer des instances cloud à l'aide de cml runner . Vous pouvez faire tourner des instances sur AWS, Azure, GCP ou Kubernetes.
Par exemple, le flux de travail suivant déploie une instance g4dn.xlarge sur AWS EC2 et forme un modèle sur l'instance. Une fois le travail, l'instance s'arrête automatiquement.
Vous remarquerez peut-être que ce flux de travail est assez similaire au cas d'utilisation de base ci-dessus. Le seul ajout est cml runner et quelques variables d'environnement pour passer vos informations d'identification de service cloud au workflow.
Notez que cml runner redémarrera également automatiquement vos travaux (que ce soit à partir d'un délai d'expiration de workflow de 35 jours GitHub ou d'une interruption d'instance spot 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 Dans le workflow ci-dessus, l'étape deploy-runner lance une instance EC2 g4dn.xlarge dans la région us-west . L'étape model-training s'exécute ensuite sur l'instance nouvellement lancée. Voir [Variables d'environnement] ci-dessous pour plus de détails sur les secrets requis.
? Notez que les travaux peuvent utiliser n'importe quel conteneur Docker! Pour utiliser des fonctions telles que
cml send-commentà partir d'un travail, la seule exigence est d'installer CML.
L'image CML Docker ( ghcr.io/iterative/cml ou iterativeai/cml ) est chargée de python, de cuda, de git , node et d'autres éléments essentiels pour la science des données complète. Différentes versions de ces éléments essentiels sont disponibles à partir de différentes balises d'image. La convention de balise est {CML_VER}-dvc{DVC_VER}-base{BASE_VER}{-gpu} :
{BASE_VER} | Logiciel inclus ( -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) |
Par exemple, iterativeai/cml:0-dvc2-base1-gpu , ou ghcr.io/iterative/cml:0-dvc2-base1 .
La fonction cml runner launch accepte les arguments suivants:
--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: ""]
️ Vous devrez créer un jeton d'accès personnel (PAT) avec des privilèges d'accès à lecture / écriture de référentiel et de workflow. Dans l'exemple de workflow, ce jeton est stocké commePERSONAL_ACCESS_TOKEN.
Si vous utilisez l'option --cloud , vous devrez également fournir des informations d'identification d'accès de vos ressources de calcul cloud sous forme de secrets. Dans l'exemple ci-dessus, AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY (avec des privilèges pour créer et détruire les instances EC2) sont nécessaires.
Pour AWS, les mêmes informations d'identification peuvent également être utilisées pour configurer le stockage cloud.
CML Support Proxy via des variables d'environnement connues http_proxy et https_proxy .
Cela signifie utiliser des machines sur site comme coureurs auto-hébergés. La fonction cml runner launch est utilisée pour configurer un coureur auto-hébergé local. Sur une machine locale ou un cluster GPU sur site, installez CML en tant que package, puis exécutez:
cml runner launch
--repo= $your_project_repository_url
--token= $PERSONAL_ACCESS_TOKEN
--labels= " local,runner "
--idle-timeout=180La machine écoutera les workflows de votre référentiel de projet.
Dans les exemples ci-dessus, CML est installé par l'action setup-cml , ou est préinstallé dans une image Docker personnalisée tirée par un coureur CI. Vous pouvez également installer CML en tant que package:
npm install --location=global @dvcorg/cml Vous pouvez utiliser cml sans nœud en téléchargeant le bon binaire autonome pour votre système à partir de la section d'actifs des versions.
Vous devrez peut-être installer des dépendances supplémentaires pour utiliser les tracés DVC et les commandes CLI 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 L'installation du package CML et VEGA-LITE nécessite le NodeJS Package Manager ( npm ) qui est expédié avec NodeJS. Les instructions d'installation sont ci-dessous.
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 nodejsCe sont quelques exemples de projets utilisant CML.
? a besoin d'une pat.
