cml
v0.20.6
O que é CML? O aprendizado de máquina contínuo (CML) é uma ferramenta CLI de código aberto para implementar a integração e entrega contínuas (CI/CD) com foco no MLOPS. Use -o para automatizar fluxos de trabalho de desenvolvimento - incluindo provisionamento de máquinas, treinamento e avaliação de modelos, comparação de experimentos de ML no histórico do projeto e monitorando os conjuntos de dados em mudança.
A CML pode ajudar a treinar e avaliar modelos - e, em seguida, gerar um relatório visual com resultados e métricas - automaticamente em todas as solicitações de tração.
Um relatório de exemplo para um modelo de transferência de estilo neural.
Princípios da CML:
❓ Precisa de ajuda? Só quer conversar sobre integração contínua para ML? Visite nosso canal Discord!
⏯️ Confira nossa série de vídeos do YouTube para tutoriais práticos do MLOPS usando CML!
Você precisará de uma conta GitLab, Github ou Bitbucket para começar. Os usuários podem querer se familiarizar com as ações do GitHub ou o GitLab CI/CD. Aqui, discutirá o caso de uso do Github.
Consulte nossos documentos na CML com o GitLab CI/CD e, em particular, o requisito de token de acesso pessoal.
Consulte nossos documentos na CML com o Bitbucket Cloud.
O arquivo chave em qualquer projeto da 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 Fornecemos a CML e outras bibliotecas úteis pré-instaladas em nossas imagens personalizadas do Docker. No exemplo acima, descomportar o container: ghcr.io/iterative/cml:0-dvc2-base1 ) fará com que o corredor puxe a imagem do Docker CML. A imagem já possui NodeJs, Python 3, DVC e CML configurados em uma base do Ubuntu LTS por conveniência.
A CML fornece várias funções para ajudar a empacotar as saídas dos fluxos de trabalho da ML (incluindo dados numéricos e visualizações sobre o desempenho do modelo) em um relatório da CML.
Abaixo está uma tabela de funções da CML para escrever relatórios de remarca e entregar esses relatórios ao seu sistema de IC.
| Função | Descrição | Exemplo de entrada |
|---|---|---|
cml runner launch | Inicie um corredor localmente ou hospedado por um provedor de nuvem | Veja argumentos |
cml comment create | Retorne o relatório da CML como um comentário no seu fluxo de trabalho GitLab/Github | <path to report> --head-sha <sha> |
cml check create | Retorne o relatório da CML como um check -in no github | <path to report> --head-sha <sha> |
cml pr create | Compromete os arquivos fornecidos a uma nova filial e crie uma solicitação de tração | <path>... |
cml tensorboard connect | Retorne um link para uma página Tensorboard.dev | --logdir <path to logs> --title <experiment title> --md |
O comando cml comment create pode ser usado para publicar relatórios. Os relatórios da CML são escritos em sabores Markdown (Github, Gitlab ou Bitbucket). Isso significa que eles podem conter imagens, tabelas, texto formatado, blocos HTML, trechos de código e muito mais - realmente, o que você coloca em um relatório da CML depende de você. Alguns exemplos:
? Aste Escreva no seu relatório usando o método que você preferir. Por exemplo, copie o conteúdo de um arquivo de texto que contém os resultados do ML Model Training:
cat results.txt >> report.md ? ️ Imagens exibem imagens usando o Markdown ou HTML. Observe que, se uma imagem for uma saída do seu fluxo de trabalho ML (ou seja, é produzida pelo seu fluxo de trabalho), ela poderá ser carregada e incluída automática ao seu relatório CML. Por exemplo, se graph.png for emitido pelo python train.py , execute:
echo "  " >> report.md
cml comment create report.md
️ Observe que, se você estiver usando o GitLab, precisará criar um token de acesso pessoal para que este exemplo funcione.
️ As etapas a seguir podem ser feitas na interface do navegador Github. No entanto, para acompanhar os comandos, recomendamos clonar o garfo à sua estação de trabalho 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 Em seu editor de texto de escolha, edite a linha 16 do train.py to depth = 5 .
Compromete e empurre as mudanças:
git checkout -b experiment
git add . && git commit -m " modify forest depth "
git push origin experimentexperiment com o main . Logo, você deve ver um comentário das github-actions na solicitação de tração com o seu relatório da CML. Isso é resultado da função de cml send-comment no seu fluxo de trabalho.
Este é o esboço do fluxo de trabalho da CML:
.github/workflows/cml.yaml é executado eAs funções da CML permitem exibir resultados relevantes do fluxo de trabalho - como métricas e visualizações de desempenho do modelo - nas verificações e comentários do GitHub. Que tipo de fluxo de trabalho você deseja executar e deseja colocar seu relatório da CML, depende de você.
Em muitos projetos de ML, os dados não são armazenados em um repositório Git, mas precisam ser baixados de fontes externas. O DVC é uma maneira comum de trazer dados para o seu Runner da CML. O DVC também permite visualizar como as métricas diferem entre as confirmações para fazer relatórios como este:
O arquivo .github/workflows/cml.yaml usado para criar este relatório é:
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
️ Se você estiver usando o DVC com armazenamento em nuvem, observe as variáveis de ambiente para o seu formato de armazenamento.
Existem muitos provedores de armazenamento suportados. Aqui estão alguns exemplos para alguns dos fornecedores mais usados:
# 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é opcional.
AWS_ACCESS_KEY_IDeAWS_SECRET_ACCESS_KEYtambém podem ser usados pelocml runnerpara iniciar instâncias do EC2. Veja [variáveis de ambiente].
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_CREDENTIALSé o caminho do arquivojsonque contém as credenciais. No entanto, na ação, essa variável secreta é o conteúdo do arquivo. Copie o conteúdojsone adicione -o como um segredo.
env :
GOOGLE_APPLICATION_CREDENTIALS : ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
️ Depois de configurar suas credenciais do Google Drive, você encontrará um arquivojsonemyour_project_path/.dvc/tmp/gdrive-user-credentials.json. Copie seu conteúdo e adicione -o como uma variável secreta.
env :
GDRIVE_CREDENTIALS_DATA : ${{ secrets.GDRIVE_CREDENTIALS_DATA }} As ações do GitHub são executadas em corredores movidos pelo Github por padrão. No entanto, existem muitas ótimas razões para usar seus próprios corredores: aproveitar as GPUs, orquestrar os recursos de computação compartilhada da sua equipe ou treinar na nuvem.
☝️ Dica! Confira a documentação oficial do GitHub para começar a configurar seu próprio corredor auto-hospedado.
Quando um fluxo de trabalho requer recursos computacionais (como GPUs), a CML pode alocar automaticamente instâncias em nuvem usando cml runner . Você pode aumentar as instâncias na AWS, Azure, GCP ou Kubernetes.
Por exemplo, o seguinte fluxo de trabalho implanta uma instância g4dn.xlarge no AWS EC2 e treina um modelo na instância. Depois que o trabalho é executado, a instância é desligada automaticamente.
Você pode notar que esse fluxo de trabalho é bastante semelhante ao caso de uso básico acima. A única adição é cml runner e algumas variáveis de ambiente para passar suas credenciais de serviço em nuvem para o fluxo de trabalho.
Observe que cml runner também reiniciará automaticamente seus trabalhos (seja de um tempo limite de fluxo de trabalho de ações de 35 dias do GitHub ou uma interrupção da instância do Spot do 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 No fluxo de trabalho acima, a etapa deploy-runner lança uma instância do EC2 g4dn.xlarge na região us-west . A etapa model-training é executada na instância recém-lançada. Veja [variáveis de ambiente] abaixo para obter detalhes sobre os secrets necessários.
? Observe que os trabalhos podem usar qualquer contêiner do Docker! Para usar funções como
cml send-commentde um trabalho, o único requisito é instalar a CML.
A imagem CML Docker ( ghcr.io/iterative/cml ou iterativeai/cml ) vem carregada com python, cuda, git , node e outros itens essenciais para a ciência de dados de pilha completa. Versões diferentes desses itens essenciais estão disponíveis em diferentes tags de imagem. A convenção de tag é {CML_VER}-dvc{DVC_VER}-base{BASE_VER}{-gpu} :
{BASE_VER} | Software incluído ( -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 exemplo, iterativeai/cml:0-dvc2-base1-gpu , ou ghcr.io/iterative/cml:0-dvc2-base1 .
A função cml runner launch aceita os seguintes 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: ""]
️ Você precisará criar um token de acesso pessoal (PAT) com os privilégios de acesso e fluxo de trabalho do repositório. No exemplo de fluxo de trabalho, este token é armazenado comoPERSONAL_ACCESS_TOKEN.
Se estiver usando a opção --cloud , você também precisará fornecer credenciais de acesso aos seus recursos de computação em nuvem como segredos. No exemplo acima, são necessários AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY (com privilégios para criar e destruir instâncias EC2) são necessárias.
Para a AWS, as mesmas credenciais também podem ser usadas para configurar o armazenamento em nuvem.
CML Suporte proxy via variáveis de ambiente conhecidas http_proxy e https_proxy .
Isso significa usar máquinas no local como corredores auto-hospedados. A função cml runner launch é usada para configurar um corredor local auto-hospedado. Em uma máquina local ou cluster de GPU no local, instale a CML como um pacote e, em seguida, execute:
cml runner launch
--repo= $your_project_repository_url
--token= $PERSONAL_ACCESS_TOKEN
--labels= " local,runner "
--idle-timeout=180A máquina ouvirá fluxos de trabalho do seu repositório do projeto.
Nos exemplos acima, a CML é instalada pela ação setup-cml , ou é pré-instalada em uma imagem personalizada puxada por um corredor de CI. Você também pode instalar o CML como um pacote:
npm install --location=global @dvcorg/cml Você pode usar cml sem nó baixando o binário independente correto do seu sistema na seção de ativos dos lançamentos.
Pode ser necessário instalar dependências adicionais para usar plotagens de DVC e comandos da 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 A instalação do pacote CML e Vega-Lite requer o NodeJS Package Manager ( npm ), que é enviado com o NodeJS. As instruções de instalação estão abaixo.
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 nodejsEstes são alguns projetos de exemplo usando CML.
? precisa de um tapinha.
