cml
v0.20.6
¿Qué es CML? El aprendizaje automático continuo (CML) es una herramienta CLI de código abierto para implementar la integración y entrega continua (CI/CD) con un enfoque en MLOPS. Úselo para automatizar los flujos de trabajo de desarrollo, incluido el aprovisionamiento de la máquina, la capacitación y la evaluación del modelo, comparar experimentos de ML a través del historial de proyectos y monitorear los conjuntos de datos cambiantes.
CML puede ayudar a entrenar y evaluar modelos, y luego generar un informe visual con resultados y métricas, automáticamente en cada solicitud de extracción.
Un informe de ejemplo para un modelo de transferencia de estilo neuronal.
Principios de CML:
❓ ¿Necesitas ayuda? ¿Solo quieres chatear sobre integración continua para ML? ¡Visite nuestro canal Discord!
⏯️ ¡Vea nuestra serie de videos de YouTube para tutoriales de MLOPS prácticos con CML!
Necesitará una cuenta GitLab, GitHub o Bitbucket para comenzar. Los usuarios pueden querer familiarizarse con las acciones de GitHub o Gitlab CI/CD. Aquí, discutirá el caso de uso de GitHub.
Consulte nuestros documentos en CML con GitLab CI/CD y, en particular, el requisito del token de acceso personal.
Consulte nuestros documentos en CML con Bitbucket Cloud.
El archivo clave en cualquier proyecto CML es .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 Proporcionamos útilmente CML y otras bibliotecas útiles preinstaladas en nuestras imágenes de Docker personalizadas. En el ejemplo anterior, incommentar el container: ghcr.io/iterative/cml:0-dvc2-base1 ) hará que el corredor extraiga la imagen CML Docker. La imagen ya tiene NodeJS, Python 3, DVC y CML configuradas en una base de Ubuntu LTS para conveniencia.
CML proporciona una serie de funciones para ayudar a empaquetar las salidas de flujos de trabajo ML (incluidos los datos numéricos y las visualizaciones sobre el rendimiento del modelo) en un informe de CML.
A continuación se muestra una tabla de funciones de CML para escribir informes de Markdown y entregar esos informes a su sistema CI.
| Función | Descripción | Entradas de ejemplo |
|---|---|---|
cml runner launch | Iniciar un corredor localmente o alojado por un proveedor de nube | Ver argumentos |
cml comment create | Return CML Informe como comentario en su flujo de trabajo Gitlab/Github | <path to report> --head-sha <sha> |
cml check create | Return CML Informe como un cheque en GitHub | <path to report> --head-sha <sha> |
cml pr create | Comprometer los archivos dados a una nueva rama y crear una solicitud de extracción | <path>... |
cml tensorboard connect | Devolver un enlace a una placa tensor.dev | --logdir <path to logs> --title <experiment title> --md |
El comando cml comment create se puede usar para publicar informes. Los informes de CML están escritos en Markdown (sabores GitHub, GitLab o Bitbucket). Eso significa que pueden contener imágenes, tablas, texto formateado, bloques HTML, fragmentos de código y más; realmente, lo que pones en un informe CML depende de ti. Algunos ejemplos:
? ️ Texto Escriba a su informe utilizando cualquier método que prefiera. Por ejemplo, copie el contenido de un archivo de texto que contiene los resultados de la capacitación del modelo ML:
cat results.txt >> report.md ? ️ Imágenes de visualización de imágenes usando Markdown o HTML. Tenga en cuenta que si una imagen es una salida de su flujo de trabajo ML (es decir, es producida por su flujo de trabajo), se puede cargar e incluirse automáticamente a su informe CML. Por ejemplo, si python train.py sale de graph.png , ejecute: Ejecutar:
echo "  " >> report.md
cml comment create report.md
️ Tenga en cuenta que si está utilizando GitLab, deberá crear un token de acceso personal para que este ejemplo funcione.
️ Todos los siguientes pasos se pueden hacer en la interfaz del navegador GitHub. Sin embargo, para seguir junto con los comandos, recomendamos clonar su bifurcación a su estación de trabajo 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 En su editor de texto de elección, edite la línea 16 de train.py to depth = 5 .
Commit y presione los cambios:
git checkout -b experiment
git add . && git commit -m " modify forest depth "
git push origin experimentexperiment con main . En breve, debería ver que aparezca un comentario de github-actions en la solicitud de extracción con su informe CML. Este es el resultado de la función cml send-comment en su flujo de trabajo.
Este es el esquema del flujo de trabajo CML:
.github/workflows/cml.yaml se ejecuta, yLas funciones de CML le permiten mostrar resultados relevantes del flujo de trabajo, como las métricas y visualizaciones de rendimiento del modelo, en las verificaciones y comentarios de GitHub. Qué tipo de flujo de trabajo desea ejecutar y quiere poner en su informe CML depende de usted.
En muchos proyectos de ML, los datos no se almacenan en un repositorio Git, pero debe descargarse de fuentes externas. DVC es una forma común de llevar datos a su corredor CML. DVC también le permite visualizar cómo las métricas difieren entre compromisos para hacer informes como este:
El archivo .github/workflows/cml.yaml utilizado para crear este informe es:
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 está utilizando DVC con almacenamiento en la nube, tome nota de las variables de entorno para su formato de almacenamiento.
Hay muchos proveedores de almacenamiento de puNos compatibles. Aquí hay algunos ejemplos para algunos de los proveedores más utilizados:
# 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_TOKENes opcional.
AWS_ACCESS_KEY_IDyAWS_SECRET_ACCESS_KEYtambién puede ser utilizado porcml runnerpara iniciar instancias EC2. Ver [Variables de entorno].
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 }}
️ Normalmente,GOOGLE_APPLICATION_CREDENTIALSes la ruta del archivojsonque contiene las credenciales. Sin embargo, en la acción, esta variable secreta es el contenido del archivo. Copie el contenidojsony agréguelo como un secreto.
env :
GOOGLE_APPLICATION_CREDENTIALS : ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
️ Después de configurar sus credenciales de Google Drive, encontrará un archivojsonenyour_project_path/.dvc/tmp/gdrive-user-credentials.json. Copie su contenido y agréguelo como una variable secreta.
env :
GDRIVE_CREDENTIALS_DATA : ${{ secrets.GDRIVE_CREDENTIALS_DATA }} Las acciones de GitHub se ejecutan en corredores alojados en GitHub de forma predeterminada. Sin embargo, hay muchas razones geniales para usar sus propios corredores: aprovechar las GPU, orquestar los recursos informáticos compartidos de su equipo o entrenar en la nube.
☝️ Tip! Echa un vistazo a la documentación oficial de GitHub para comenzar a configurar tu propio corredor autohostado.
Cuando un flujo de trabajo requiere recursos computacionales (como GPU), CML puede asignar automáticamente instancias en la nube utilizando cml runner . Puede girar instancias en AWS, Azure, GCP o Kubernetes.
Por ejemplo, el siguiente flujo de trabajo implementa una instancia g4dn.xlarge en AWS EC2 y entrena un modelo en la instancia. Después de que se ejecuta el trabajo, la instancia se apaga automáticamente.
Puede notar que este flujo de trabajo es bastante similar al caso de uso básico anterior. La única adición es cml runner y algunas variables de entorno para pasar sus credenciales de servicio en la nube al flujo de trabajo.
Tenga en cuenta que cml runner también reiniciará automáticamente sus trabajos (ya sea desde un tiempo de espera de flujo de trabajo de 35 días de GitHub o una interrupción de instancia de Spot de 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 En el flujo de trabajo anterior, el paso deploy-runner lanza una instancia EC2 g4dn.xlarge en la región us-west . El paso model-training se ejecuta en la instancia recién lanzada. Consulte [Variables de entorno] a continuación para obtener detalles sobre los secrets requeridos.
? ¡Tenga en cuenta que los trabajos pueden usar cualquier contenedor Docker! Para usar funciones como
cml send-commentde un trabajo, el único requisito es tener CML instalado.
La imagen CML Docker ( ghcr.io/iterative/cml o iterativeai/cml ) viene cargada de Python, CUDA, git , node y otros elementos esenciales para la ciencia de datos de pila completa. Hay diferentes versiones de estos elementos esenciales disponibles en diferentes etiquetas de imagen. La convención de la etiqueta es {CML_VER}-dvc{DVC_VER}-base{BASE_VER}{-gpu} :
{BASE_VER} | Software incluido ( -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) |
Por ejemplo, iterativeai/cml:0-dvc2-base1-gpu , o ghcr.io/iterative/cml:0-dvc2-base1 .
La función cml runner launch acepta los siguientes argumentos:
--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: ""]
️ Deberá crear un token de acceso personal (PAT) con acceso de lectura/escritura del repositorio y privilegios de flujo de trabajo. En el flujo de trabajo de ejemplo, este token se almacena comoPERSONAL_ACCESS_TOKEN.
Si usa la opción --cloud , también deberá proporcionar credenciales de acceso de sus recursos de cómputo en la nube como secretos. En el ejemplo anterior, se requiere AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY (con privilegios para crear y destruir instancias EC2).
Para AWS, las mismas credenciales también se pueden usar para configurar el almacenamiento en la nube.
CML Support Proxy a través de variables de entorno conocidas http_proxy y https_proxy .
Esto significa usar máquinas locales como corredores autohospedados. La función cml runner launch se usa para configurar un corredor local autohostado. En una máquina local o un clúster de GPU local, instale CML como un paquete y luego ejecute:
cml runner launch
--repo= $your_project_repository_url
--token= $PERSONAL_ACCESS_TOKEN
--labels= " local,runner "
--idle-timeout=180La máquina escuchará los flujos de trabajo desde el repositorio de su proyecto.
En los ejemplos anteriores, la CML está instalada por la acción setup-cml , o viene preinstalada en una imagen de Docker personalizada extraída por un corredor CI. También puede instalar CML como un paquete:
npm install --location=global @dvcorg/cml Puede usar cml sin nodo descargando el binario independiente correcto para su sistema desde la sección de activos de las versiones.
Es posible que deba instalar dependencias adicionales para usar gráficos DVC y comandos de CLI de 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 La instalación del paquete CML y Vega-Lite requiere el NodeJS Package Manager ( npm ) que se envía con NodeJS. Las instrucciones de instalación están a continuación.
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 nodejsEstos son algunos proyectos de ejemplo usando CML.
? Necesita una palmadita.
