Métricas, parâmetros e arquivos de registro com o MLflow
APLICA-SE A: 
SDK do Python azure-ai-ml v2 (atual)
O Azure Machine Learning dá suporte a experimentos de log e rastreamento usando o MLflow Tracking . Você pode registrar modelos, métricas, parâmetros e artefatos com o MLflow, seja localmente no seu computador ou em um ambiente de nuvem.
Importante
Diferentemente do SDK do Azure Machine Learning v1, não há funcionalidade de registro em log no SDK do Azure Machine Learning para Python (v2). Se você usou o SDK v1 do Azure Machine Learning anteriormente, recomendamos que utilize o MLflow para rastrear os experimentos. Consulte Migrar log do SDK v1 para MLflow para obter orientações específicas.
Os logs podem ajudar você a diagnosticar erros e avisos ou acompanhar métricas de desempenho como parâmetros e desempenho do modelo. Este artigo explica como habilitar o registro em log nos seguintes cenários:
- Registre métricas, parâmetros e modelos ao enviar trabalhos.
- Acompanhe as execuções durante o treinamento de forma interativa.
- Exibir informações de diagnóstico sobre o treinamento.
Dica
Este artigo mostra como monitorar o processo de treinamento do modelo. Se você estiver interessado em monitorar o uso de recursos e eventos do Azure Machine Learning, como cotas, trabalhos de treinamento concluídos ou implantações de modelo concluídas, confira Monitoramento do Azure Machine Learning.
Pré-requisitos
Você precisa ter um workspace do Azure Machine Learning. Se você não tiver um, confira Criar recursos do espaço de trabalho.
Você deve ter os pacotes
mlfloweazureml-mlflowinstalados. Se não tiver, use o seguinte comando para instalá-los no ambiente de desenvolvimento:pip install mlflow azureml-mlflowSe estiver fazendo acompanhamento remoto (acompanhamento de experimentos executados fora do Azure Machine Learning), configure o MLflow para rastrear os experimentos. Para obter mais informações, consulte Configurar o MLflow para o Azure Machine Learning.
Para registrar métricas, parâmetros, artefatos e modelos em seus experimentos no Azure Machine Learning usando o MLflow, basta importar o MLflow para o seu script:
import mlflow
Configurar experimentos
O MLflow organiza as informações em experimentos e execuções (no Azure Machine Learning, as execuções são chamadas de trabalhos). Há algumas diferenças em como configurá-las, dependendo de como você executa seu código:
Ao treinar interativamente, como em um Jupyter Notebook, use o seguinte padrão:
- Criar ou definir o experimento ativo.
- Iniciar o trabalho.
- Usar métodos de registro para registrar métricas e outras informações.
- Finalizar o trabalho.
Por exemplo, o trecho de código a seguir configura o experimento e, em seguida, faz o registro durante um trabalho:
import mlflow
# Set the experiment
mlflow.set_experiment("mlflow-experiment")
# Start the run
mlflow_run = mlflow.start_run()
# Log metrics or other information
mlflow.log_metric('mymetric', 1)
# End run
mlflow.end_run()
Dica
Tecnicamente, não é necessário chamar start_run() porque uma nova execução será criada se não houver uma e você chamar uma API de registro. Nesse caso, você pode usar mlflow.active_run() para recuperar a execução que está sendo usada no momento. Para obter mais informações, consulte mlflow.active_run().
Você também pode usar o paradigma do gerenciador de contexto:
import mlflow
mlflow.set_experiment("mlflow-experiment")
# Start the run, log metrics, end the run
with mlflow.start_run() as run:
# Run started when context manager is entered, and ended when context manager exits
mlflow.log_metric('mymetric', 1)
mlflow.log_metric('anothermetric',1)
pass
Quando você inicia uma nova execução com mlflow.start_run, pode ser útil indicar o parâmetro run_name, que se traduz no nome da execução na interface do usuário do Azure Machine Learning e ajuda a identificar a execução mais rapidamente:
with mlflow.start_run(run_name="iris-classifier-random-forest") as run:
mlflow.log_metric('mymetric', 1)
mlflow.log_metric('anothermetric',1)
Para obter mais informações sobre as APIs de registro de MLflow, confira a Referência de MLflow.
Parâmetros de registro
O MLflow é compatível com os parâmetros de log usados por seus experimentos. Os parâmetros podem ser de qualquer tipo e podem ser registrados usando a seguinte sintaxe:
mlflow.log_param("num_epochs", 20)
O MLflow também oferece uma maneira conveniente de registrar vários parâmetros, indicando todos eles usando um dicionário. Várias estruturas também podem passar parâmetros para modelos usando dicionários e, portanto, essa é uma maneira conveniente de registrá-los no experimento.
params = {
"num_epochs": 20,
"dropout_rate": .6,
"objective": "binary_crossentropy"
}
mlflow.log_params(params)
Registrar métricas
As métricas, ao contrário dos parâmetros, são sempre numéricas. A tabela a seguir descreve como registrar tipos numéricos específicos:
| Valor registrado | Código de exemplo | Observações |
|---|---|---|
| Registrar um valor numérico (int ou float) | mlflow.log_metric("my_metric", 1) |
|
| Registrar um valor numérico (int ou float) ao longo do tempo | mlflow.log_metric("my_metric", 1, step=1) |
Use o parâmetro step para indicar a etapa em que o valor da métrica é registrado. Pode ser qualquer número inteiro. O padrão é zero. |
| Registrar um valor booliano | mlflow.log_metric("my_metric", 0) |
0 = True, 1 = False |
Importante
Considerações sobre o desempenho: se for necessário registrar várias métricas (ou vários valores para a mesma métrica), evite fazer chamadas para mlflow.log_metric em loops. É possível obter um melhor desempenho registrando um lote de métricas. Use o método mlflow.log_metrics que aceita um dicionário com todas as métricas que você deseja registrar de uma vez ou use MLflowClient.log_batch o que aceita vários tipos de elementos para registro em log. Consulte Curvas de logs ou lista de valores para obter um exemplo.
Curvas de registro ou lista de valores
As curvas (ou uma lista de valores numéricos) podem ser registradas com o MLflow registrando a mesma métrica várias vezes. O exemplo a seguir mostra como fazer isso:
list_to_log = [1, 2, 3, 2, 1, 2, 3, 2, 1]
from mlflow.entities import Metric
from mlflow.tracking import MlflowClient
import time
client = MlflowClient()
client.log_batch(mlflow.active_run().info.run_id,
metrics=[Metric(key="sample_list", value=val, timestamp=int(time.time() * 1000), step=0) for val in list_to_log])
Imagens de registro
O MLflow dá suporte a duas maneiras de registrar imagens. Ambas as formas mantêm a imagem fornecida como um artefato dentro da execução.
| Valor registrado | Código de exemplo | Observações |
|---|---|---|
| Registrar métricas numpy ou objetos de imagem PIL | mlflow.log_image(img, "figure.png") |
img deve ser uma instância de numpy.ndarray ou PIL.Image.Image. figure.png é o nome do artefato gerado dentro da execução. Ele não precisa ser um arquivo existente. |
| Registrar arquivo de imagem ou gráfico de matlotlib | mlflow.log_figure(fig, "figure.png") |
figure.png é o nome do artefato gerado dentro da execução. Ele não precisa ser um arquivo existente. |
Arquivos de log
Em geral, os arquivos no MLflow são chamados de artefatos. Você pode registrar artefatos de várias maneiras no Mlflow:
| Valor registrado | Código de exemplo | Observações |
|---|---|---|
| Texto de log em um arquivo de texto | mlflow.log_text("text string", "notes.txt") |
O texto é mantido dentro da execução em um arquivo de texto com o nome notes.txt. |
| Dicionários de registros como arquivos JSON e YAML | mlflow.log_dict(dictionary, "file.yaml" |
dictionary é um objeto de dicionário que contém toda a estrutura que você deseja manter como um arquivo JSON ou YAML. |
| Registre um arquivo trivial já existente | mlflow.log_artifact("path/to/file.pkl") |
Os arquivos são sempre registrados na raiz da execução. Se artifact_path for fornecido, o arquivo será registrado em uma pasta conforme indicado nesse parâmetro. |
| Registrar todos os artefatos em uma pasta existente | mlflow.log_artifacts("path/to/folder") |
A estrutura de pastas é copiada para a execução, mas a pasta raiz indicada não é incluída. |
Dica
Ao registrar arquivos grandes com log_artifact ou log_model, é possível que ocorram erros de tempo limite antes que o upload do arquivo seja concluído. Considere aumentar o valor de tempo limite ajustando a variável de ambiente AZUREML_ARTIFACTS_DEFAULT_TIMEOUT. Seu valor padrão é 300 (segundos).
Modelos de registro
O MLflow apresenta o conceito de modelos como uma forma de empacotar todos os artefatos necessários para o funcionamento de um determinado modelo. Os modelos no MLflow são sempre uma pasta com um número arbitrário de arquivos, dependendo do framework usado para gerar o modelo. Os modelos de registro têm a vantagem de rastrear todos os elementos do modelo como uma única entidade que pode ser registrada e implantada. Além disso, os modelos MLflow desfrutam do benefício da implantação sem código e podem ser usados com o painel de IA responsável no estúdio. Para obter mais informações, confira Dos artefatos aos modelos no MLflow.
Para salvar o modelo de uma execução de treinamento, use a API log_model() para a estrutura com a qual está trabalhando. Por exemplo, mlflow.sklearn.log_model(). Para obter mais informações, confira Modelos de registro em log do MLflow. Para migrar modelos existentes para o MLflow, consulte Converter modelos personalizados para o MLflow.
Dica
Ao registrar modelos grandes, você pode encontrar o erro Failed to flush the queue within 300 seconds. Normalmente, isso significa que a operação está atingindo o tempo limite antes da conclusão do upload dos artefatos do modelo. Considere aumentar o valor de tempo limite ajustando a variável de ambiente AZUREML_ARTIFACTS_DEFAULT_TIMEOUT.
Log automático
Com o Azure Machine Learning e o MLflow, os usuários podem registrar métricas, parâmetros de modelo e artefatos de modelo automaticamente ao treinar um modelo. Cada estrutura decide o que acompanhar automaticamente para você. Há suporte para uma variedade de bibliotecas populares de machine learning. Saiba mais sobre o log automático com o MLflow.
Para habilitar o registro em log automático, insira o seguinte código antes do seu código de treinamento:
mlflow.autolog()
Dica
Você pode controlar o que é registrado automaticamente com o log automático. Por exemplo, se você indicar mlflow.autolog(log_models=False), o MLflow registrará tudo, exceto os modelos. Esse controle é útil nos casos em que você deseja registrar modelos manualmente, mas ainda desfruta do registro automático de métricas e parâmetros. Observe também que algumas estruturas podem desabilitar o registro em log automático de modelos se o modelo treinado ultrapassar limites específicos. Esse comportamento depende da variante usada e recomendamos que você consulte a documentação se esse for o seu caso.
Exibir informações de trabalhos/execuções com o MLflow
Você pode exibir as informações registradas usando MLflow por meio do objeto MLflow.entities.Run:
import mlflow
run = mlflow.get_run(run_id="<RUN_ID>")
Você pode exibir as métricas, os parâmetros e as marcas para a execução no campo de dados do objeto de execução.
metrics = run.data.metrics
params = run.data.params
tags = run.data.tags
Observação
O dicionário de métricas retornado por mlflow.get_run ou mlflow.search_runs retorna somente o valor registrado mais recentemente para um determinado nome de métrica. Por exemplo, se você registrar uma métrica chamada iteration várias vezes com valores 1, depois 2, depois 3 e depois 4, somente 4 será retornado ao chamar run.data.metrics['iteration'].
Para que todas as métricas sejam registradas com um nome de métrica específico, você pode usar MlFlowClient.get_metric_history() conforme explicado no exemplo Obter parâmetros e métricas de uma execução.
Dica
O MLflow pode recuperar métricas e parâmetros de várias execuções ao mesmo tempo, permitindo comparações rápidas em várias avaliações. Para saber mais, confira Consultar e comparar experimentos e execuções com o MLflow.
O MLflow pode consultar qualquer artefato registrado por uma execução. Os artefatos não podem ser acessado usando o objeto de execução em si e o cliente MLflow deve ser usado no lugar:
client = mlflow.tracking.MlflowClient()
client.list_artifacts("<RUN_ID>")
Esse método lista todos os artefatos registrados na execução, mas eles permanecem armazenados no repositório de artefatos (armazenamento do Azure Machine Learning). Para baixar qualquer um deles, use o método download_artifact:
file_path = client.download_artifacts("<RUN_ID>", path="feature_importance_weight.png")
Para obter mais informações, consulte Obtenção de métricas, parâmetros, artefatos e modelos.
Exibir informações de trabalhos/execuções no estúdio
Você pode procurar registros de trabalho concluídos, incluindo métricas registradas, no Estúdio do Azure Machine Learning.
Navegue até a guia Trabalhos. Para visualizar todos os trabalhos em seu espaço de trabalho nos experimentos, selecione a guia Todos os trabalhos. Você pode analisar detalhadamente os trabalhos para experimentos específicos aplicando o filtro Experimento na barra de menu superior. Selecione o trabalho de interesse para inserir o modo de exibição de detalhes e, em seguida, selecione a guia Métricas.
Selecione as métricas registradas para renderizar gráficos no lado direito. Você pode personalizar os gráficos com a aplicação de suavização, alteração de cor ou uso de várias métricas em um único grafo. Você também pode redimensionar e reorganizar o layout conforme desejar. Após criar o modo de exibição desejado, é possível salvá-lo para uso futuro e compartilhá-lo com seus colegas de equipe usando um link direto.
Exibir e baixar logs de diagnóstico
Os arquivos de log são um recurso essencial para depurar as cargas de trabalho do Azure Machine Learning. Depois de enviar um trabalho de treinamento, faça uma busca detalhada até uma execução específica para exibir seus logs e saídas:
- Navegue até a guia Trabalhos.
- Selecione o runID para uma execução específica.
- Selecione Saídas e logs na parte superior da página.
- Selecione Baixar tudo para baixar todos os seus logs em uma pasta zip.
- Você também pode baixar arquivos de log individuais escolhendo o arquivo de log e selecionando Baixar
pasta user_logs
Essa pasta contém informações sobre os logs gerados pelo usuário. Essa pasta é aberta por padrão e o std_log.txt log está selecionado. Esse std_log.txt é onde os logs do seu código (por exemplo, as instruções print) aparecem. Esse arquivo contém log stdout e logs stderr do script de controle e do script de treinamento, um por processo. Na maioria dos casos, você monitora os logs aqui.
pasta system_logs
Essa pasta contém os logs gerados pelo Azure Machine Learning e é fechada por padrão. Os logs gerados pelo sistema são agrupados em diferentes pastas com base na fase do trabalho no runtime.
Outras pastas
Para o treinamento de trabalhos em clusters de várias computações, os registros estão presentes para cada nó IP. A estrutura de cada nó é igual a trabalhos de nó único. Há mais uma pasta de logs para os logs de execução geral, stderr e stdout.
O Azure Machine Learning registra informações de outras fontes durante o treinamento, como o AutoML ou o contêiner do Docker que executa o trabalho de treinamento. Muitos desses logs não estão documentados. Se você encontrar problemas e entrar em contato com o suporte da Microsoft, eles poderão usar esses logs durante a solução de problemas.