Métricas, parâmetros e arquivos de registro com o MLflow

Artigo
09/03/2024

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.
Registre métricas em log de forma assíncrona.
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 mlflow e azureml-mlflow instalados. Se não tiver, use o seguinte comando para instalá-los no ambiente de desenvolvimento:
```
pip install mlflow azureml-mlflow
```
Observação

Para registrar em log assíncrono de métricas, você precisa ter o MLflow versão 2.8.0 superior e o azureml-mlflow versão 1.55 ou superior.
Se 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:

Treinamento interativo
Treinamento com trabalhos

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.

Ao executar trabalhos de treinamento no Azure Machine Learning, você não precisa chamar mlflow.start_run porque as execuções são iniciadas automaticamente. Portanto, você pode usar os recursos de rastreamento do mlflow diretamente em seus scripts de treinamento:

import mlflow

mlflow.autolog()

mlflow.log_metric('mymetric', 1)
mlflow.log_metric('anothermetric',1)

Dica

Ao enviar trabalhos usando a CLI v2 do Azure Machine Learning, você pode definir o nome do experimento usando a propriedade experiment_name na definição YAML do trabalho. Você não precisa configurá-lo no script de treinamento. Confira YAML: nome de exibição, nome do experimento, descrição e marcas para obter detalhes.

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 e podem ser registradas de forma síncrona ou assíncrona. Quando as métricas são registradas, elas ficam imediatamente disponíveis para consumo após o retorno da chamada. 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. Um melhor desempenho pode ser obtido usando o registro em log assíncrono com mlflow.log_metric("metric1", 9.42, synchronous=False) ou registrando um lote de métricas.

Registrar métricas em log de forma assíncrona

O MLflow também permite o registro em log de métricas de forma assíncrona. O registro assíncrono de métricas é particularmente útil nos casos em que grandes trabalhos de treinamento com dezenas de nós de computação podem estar sendo executados e tentando registrar métricas simultaneamente. Também é útil quando um pequeno número de nós está tentando registrar um alto número de métricas.

O registro em log de métricas assíncrona permite que você registre métricas imediatamente evitando que elas se materializem no serviço de back-end. Essa abordagem é dimensionada para grandes rotinas de treinamento que registram centenas de milhares de valores de métrica e é a abordagem recomendada.

As métricas de logs do MLflow são sincronizadas por padrão; no entanto, você pode alterar esse comportamento a qualquer momento:

import mlflow

mlflow.config.enable_async_logging()

A mesma propriedade pode ser definida usando uma variável de ambiente:

export MLFLOW_ENABLE_ASYNC_LOGGING=True

Para registrar métricas específicas de forma assíncrona, use a API de log do MLflow como normalmente, mas adicione o parâmetro extra synchronous=False.

import mlflow

with mlflow.start_run():
    # (...)
    mlflow.log_metric("metric1", 9.42, synchronous=False)
    # (...)

Quando você usa log_metric(synchronous=False), o controle é retornado automaticamente ao chamador depois que a operação é aceita; contudo, o valor não está disponível para leitura imediata. O registro em log assíncrono de métricas garante a ordem e elas são mantidas com o carimbo de data/hora de quando foram registradas.

Importante

Mesmo com o synchronous=False, o Azure Machine Learning garante a ordenação das métricas.

Se você precisar aguardar que um valor específico seja mantido no back-end, use a operação de métrica retornada para aguardar, conforme mostrado no exemplo a seguir:

import mlflow

with mlflow.start_run():
    # (...)
    run_operation = mlflow.log_metric("metric1", 9.42, synchronous=False)
    # (...)
    run_operation.wait()
    # (...)

Você pode registrar uma métrica de cada vez de forma assíncrona ou registrar um lote de métricas, conforme mostrado no exemplo a seguir:

import mlflow
import time
from mlflow.entities import Metric

with mlflow.start_run() as current_run:
    mlflow_client = mlflow.tracking.MlflowClient()

    metrics = {"metric-0": 3.14, "metric-1": 6.28}
    timestamp = int(time.time() * 1000)
    metrics_arr = [Metric(key, value, timestamp, 0) for key, value in metrics.items()]

    run_operation = mlflow_client.log_batch(
        run_id=current_run.info.run_id,
        metrics=metrics_arr,
        synchronous=False,
    )

A operação wait() também está disponível ao registrar em log um lote de métricas:

run_operation.wait()

Você não precisará chamar wait() em suas rotinas se não precisar obter acesso imediato aos valores de métrica. O Azure Machine Learning espera automaticamente quando o trabalho está prestes a ser concluído para ver se há alguma métrica pendente a ser mantida. Quando um trabalho é concluído no Azure Machine Learning, todas as métricas deverão ser mantidas.

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 sobre trabalhos ou 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 sobre trabalhos ou 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.

Compartilhar via

Métricas, parâmetros e arquivos de registro com o MLflow

Pré-requisitos

Configurar experimentos

Parâmetros de registro

Registrar métricas

Registrar métricas em log de forma assíncrona

Curvas de registro ou lista de valores

Imagens de registro

Arquivos de log

Modelos de registro

Log automático

Exibir informações sobre trabalhos ou execuções com o MLflow

Exibir informações sobre trabalhos ou execuções no estúdio

Exibir e baixar logs de diagnóstico

pasta user_logs

pasta system_logs

Outras pastas

Comentários

Recursos adicionais

Compartilhar via

Métricas, parâmetros e arquivos de registro com o MLflow

Pré-requisitos

Configurar experimentos

Parâmetros de registro

Registrar métricas

Registrar métricas em log de forma assíncrona

Curvas de registro ou lista de valores

Imagens de registro

Arquivos de log

Modelos de registro

Log automático

Exibir informações sobre trabalhos ou execuções com o MLflow

Exibir informações sobre trabalhos ou execuções no estúdio

Exibir e baixar logs de diagnóstico

pasta user_logs

pasta system_logs

Outras pastas

Conteúdo relacionado

Comentários

Recursos adicionais