Gerencie o código de treinamento com execuções MLflow

Este artigo descreve as execuções do MLflow para gerenciar o treinamento de aprendizado de máquina. Ele também inclui orientações sobre como gerenciar e comparar execuções entre experimentos.

Uma execução MLflow corresponde a uma única execução de código de modelo. Cada execução registra as seguintes informações:

• Origem: nome do bloco de anotações que iniciou a execução ou o nome do projeto e o ponto de entrada para a execução.
  • Versão: Git commit hash se o notebook estiver armazenado em uma pasta Databricks Git ou executado a partir de um projeto MLflow. Caso contrário, revisão do caderno.
  • Hora de início e de fim: Hora de início e de fim da execução.
  • Parâmetros: Parâmetros do modelo salvos como pares chave-valor. Tanto as chaves quanto os valores são cadeias de caracteres.
  • Métricas: Métricas de avaliação de modelo salvas como pares chave-valor. O valor é numérico. Cada métrica pode ser atualizada ao longo da execução (por exemplo, para controlar como a função de perda do seu modelo está convergindo) e o MLflow registra e permite visualizar o histórico da métrica.
  • Tags: Execute metadados salvos como pares chave-valor. Você pode atualizar as tags durante e após a conclusão de uma execução. Tanto as chaves quanto os valores são cadeias de caracteres.
  • Artefatos: arquivos de saída em qualquer formato. Por exemplo, você pode gravar imagens, modelos (por exemplo, um modelo scikit-learn em conserva) e arquivos de dados (por exemplo, um arquivo Parquet) como um artefato.

Todas as execuções do MLflow são registradas no experimento ativo. Se você não tiver definido explicitamente um experimento como o experimento ativo, as execuções serão registradas no experimento do bloco de anotações.

Ver execuções

Você pode acessar uma execução a partir de sua página de experimento pai ou diretamente do bloco de anotações que criou a execução.

Na página do experimento, na tabela de execuções, clique na hora de início de uma execução.

No bloco de anotações, clique ao lado da data e hora da execução na barra lateral Execuções de Experimento.

A tela de execução mostra os parâmetros usados para a execução, as métricas resultantes da execução e quaisquer tags ou anotações. Para exibir Notas, Parâmetros, Métricas ou Tags para esta execução, clique à esquerda do rótulo.

Você também acessa artefatos salvos de uma execução nesta tela.

Trechos de código para previsão

Se você registrar um modelo de uma execução, o modelo aparecerá na seção Artefatos desta página. Para exibir trechos de código ilustrando como carregar e usar o modelo para fazer previsões no Spark e pandas DataFrames, clique no nome do modelo.

Exibir o bloco de anotações ou o projeto Git usado para uma execução

Para exibir a versão do bloco de anotações que criou uma execução:

• Na página do experimento, clique no link na coluna Origem .
• Na página Executar, clique no link ao lado de Origem.
• No bloco de anotações, na barra lateral Execuções de Experimento, clique no ícone Bloco de Anotações na caixa dessa Execução de Experimento.

A versão do bloco de anotações associada à execução aparece na janela principal com uma barra de realce mostrando a data e a hora da execução.

Se a execução foi iniciada remotamente a partir de um projeto Git, clique no link no campo Git Commit para abrir a versão específica do projeto usado na execução. O link no campo Source abre a ramificação principal do projeto Git usado na execução.

Adicionar uma tag a uma execução

As tags são pares chave-valor que você pode criar e usar posteriormente para pesquisar execuções.

1. Na página Executar, clique se ainda não estiver aberta. A tabela de tags é exibida.

   

2. Clique nos campos Nome e Valor e digite a chave e o valor da sua tag.

3. Clique em Adicionar.

   

Editar ou excluir uma tag para uma execução

Para editar ou excluir uma tag existente, use os ícones na coluna Ações .

Reproduzir o ambiente de software de uma execução

Você pode reproduzir o ambiente de software exato para a execução clicando em Reproduzir Executar. A seguinte caixa de diálogo é exibida:

Com as configurações padrão, quando você clica em Confirmar:

• O bloco de anotações é clonado para o local mostrado na caixa de diálogo.
• Se o cluster original ainda existir, o bloco de anotações clonado será anexado ao cluster original e o cluster será iniciado.
• Se o cluster original não existir mais, um novo cluster com a mesma configuração, incluindo quaisquer bibliotecas instaladas, será criado e iniciado. O bloco de notas está ligado ao novo cluster.

Você pode selecionar um local diferente para o bloco de anotações clonado e inspecionar a configuração do cluster e as bibliotecas instaladas:

• Para selecionar uma pasta diferente para salvar o bloco de anotações clonado, clique em Editar pasta.
• Para ver a especificação do cluster, clique em Exibir Especificação. Para clonar apenas o bloco de anotações e não o cluster, desmarque esta opção.
• Para ver as bibliotecas instaladas no cluster original, clique em Exibir Bibliotecas. Se você não se importar em instalar as mesmas bibliotecas do cluster original, desmarque esta opção.

Gerenciar execuções

Renomear execução

Para renomear uma execução, clique no canto superior direito da página de execução e selecione Renomear.

Execuções de filtro

Você pode pesquisar execuções com base em valores de parâmetros ou métricas. Você também pode pesquisar execuções por tag.

• Para procurar execuções que correspondam a uma expressão que contenha valores de parâmetros e métricas, insira uma consulta no campo de pesquisa e clique em Pesquisar. Alguns exemplos de sintaxe de consulta são:

  metrics.r2 > 0.3

  params.elasticNetParam = 0.5

  params.elasticNetParam = 0.5 AND metrics.avg_areaUnderROC > 0.3

  MIN(metrics.rmse) <= 1

  MAX(metrics.memUsage) > 0.9

  LATEST(metrics.memUsage) = 0 AND MIN(metrics.rmse) <= 1

  Por padrão, os valores de métrica são filtrados com base no último valor registrado. Usar MIN ou MAX permitir que você pesquise execuções com base nos valores mínimos ou máximos da métrica, respectivamente. Apenas as execuções registradas após agosto de 2024 têm valores métricos mínimos e máximos.

• Para pesquisar execuções por tag, digite tags no formato: tags.<key>="<value>". Os valores de cadeia de caracteres devem ser colocados entre aspas, conforme mostrado.

  tags.estimator_name="RandomForestRegressor"

  tags.color="blue" AND tags.size=5

  Tanto as chaves como os valores podem conter espaços. Se a chave incluir espaços, você deve colocá-la em backticks, conforme mostrado.

  tags.`my custom tag` = "my value"
  

Você também pode filtrar execuções com base em seu estado (Ativo ou Excluído) e com base em se uma versão do modelo está associada à execução. Para fazer isso, faça suas seleções nos menus suspensos Estado e Tempo criado , respectivamente.

Execuções de download

1. Selecione uma ou mais execuções.

2. Clique em Baixar CSV. Um arquivo CSV contendo os seguintes campos é baixado:

   Run ID,Name,Source Type,Source Name,User,Status,<parameter1>,<parameter2>,...,<metric1>,<metric2>,...
   

Excluir execuções

Você pode excluir execuções usando a interface do usuário do Databricks Mosaic AI com as seguintes etapas:

1. No experimento, selecione uma ou mais execuções clicando na caixa de seleção à esquerda da execução.
2. Clique em Eliminar.
3. Se a execução for pai, decida se você também deseja excluir execuções descendentes. Esta opção está selecionada por predefinição.
4. Clique em Excluir para confirmar. As execuções excluídas são salvas por 30 dias. Para exibir execuções excluídas, selecione Excluído no campo Estado.

A exclusão em massa é executada com base no tempo de criação

Você pode usar Python para excluir em massa execuções de um experimento que foram criadas antes ou em um carimbo de data/hora do UNIX. Usando o Databricks Runtime 14.1 ou posterior, você pode chamar a mlflow.delete_runs API para excluir execuções e retornar o número de execuções excluídas.

A seguir estão os mlflow.delete_runs parâmetros:

• experiment_id: O ID do experimento que contém as execuções a serem excluídas.
• max_timestamp_millis: O carimbo de data/hora máximo de criação em milissegundos desde a época do UNIX para excluir execuções. Somente as execuções criadas antes ou neste carimbo de data/hora são excluídas.
• max_runs: Opcional. Um inteiro positivo que indica o número máximo de execuções a serem excluídas. O valor máximo permitido para max_runs é 10000. Se não for especificado, max_runs o padrão será 10000.

import mlflow

# Replace <experiment_id>, <max_timestamp_ms>, and <max_runs> with your values.
runs_deleted = mlflow.delete_runs(
  experiment_id=<experiment_id>,
  max_timestamp_millis=<max_timestamp_ms>,
  max_runs=<max_runs>
)
# Example:
runs_deleted = mlflow.delete_runs(
  experiment_id="4183847697906956",
  max_timestamp_millis=1711990504000,
  max_runs=10
)

Usando o Databricks Runtime 13.3 LTS ou anterior, você pode executar o seguinte código de cliente em um Bloco de Anotações do Azure Databricks.

from typing import Optional

def delete_runs(experiment_id: str,
                max_timestamp_millis: int,
                max_runs: Optional[int] = None) -> int:
    """
    Bulk delete runs in an experiment that were created prior to or at the specified timestamp.
    Deletes at most max_runs per request.

    :param experiment_id: The ID of the experiment containing the runs to delete.
    :param max_timestamp_millis: The maximum creation timestamp in milliseconds
                                 since the UNIX epoch for deleting runs. Only runs
                                 created prior to or at this timestamp are deleted.
    :param max_runs: Optional. A positive integer indicating the maximum number
                     of runs to delete. The maximum allowed value for max_runs
                     is 10000. If not specified, max_runs defaults to 10000.
    :return: The number of runs deleted.
    """
    from mlflow.utils.databricks_utils import get_databricks_host_creds
    from mlflow.utils.request_utils import augmented_raise_for_status
    from mlflow.utils.rest_utils import http_request

    json_body = {"experiment_id": experiment_id, "max_timestamp_millis": max_timestamp_millis}
    if max_runs is not None:
        json_body["max_runs"] = max_runs
    response = http_request(
        host_creds=get_databricks_host_creds(),
        endpoint="/api/2.0/mlflow/databricks/runs/delete-runs",
        method="POST",
        json=json_body,
    )
    augmented_raise_for_status(response)
    return response.json()["runs_deleted"]

Consulte a documentação da API de Experimentos do Azure Databricks para obter parâmetros e especificações de valor de retorno para excluir execuções com base no tempo de criação.

A restauração é executada

Você pode restaurar execuções excluídas anteriormente usando a interface do usuário do Databricks Mosaic AI.

1. Na página Experimento, selecione Excluído no campo Estado para exibir execuções excluídas.
2. Selecione uma ou mais execuções clicando na caixa de seleção à esquerda da execução.
3. Clique em Restaurar.
4. Clique em Restaurar para confirmar. Para exibir as execuções restauradas, selecione Ativo no campo Estado.

A restauração em massa é executada com base no tempo de exclusão

Você também pode usar Python para restaurar em massa execuções de um experimento que foram excluídas em ou após um carimbo de data/hora do UNIX. Usando o Databricks Runtime 14.1 ou posterior, você pode chamar a mlflow.restore_runs API para restaurar execuções e retornar o número de execuções restauradas.

A seguir estão os mlflow.restore_runs parâmetros:

• experiment_id: A ID do experimento que contém as execuções a serem restauradas.
• min_timestamp_millis: O carimbo de data/hora mínimo de exclusão em milissegundos desde a época do UNIX para restaurar execuções. Somente as execuções excluídas no ou após esse carimbo de data/hora são restauradas.
• max_runs: Opcional. Um inteiro positivo que indica o número máximo de execuções a restaurar. O valor máximo permitido para max_runs é 10000. Se não for especificado, max_runs padrão será 10000.

import mlflow

# Replace <experiment_id>, <min_timestamp_ms>, and <max_runs> with your values.
runs_restored = mlflow.restore_runs(
  experiment_id=<experiment_id>,
  min_timestamp_millis=<min_timestamp_ms>,
  max_runs=<max_runs>
)
# Example:
runs_restored = mlflow.restore_runs(
  experiment_id="4183847697906956",
  min_timestamp_millis=1711990504000,
  max_runs=10
)

Usando o Databricks Runtime 13.3 LTS ou anterior, você pode executar o seguinte código de cliente em um Bloco de Anotações do Azure Databricks.

from typing import Optional

def restore_runs(experiment_id: str,
                 min_timestamp_millis: int,
                 max_runs: Optional[int] = None) -> int:
    """
    Bulk restore runs in an experiment that were deleted at or after the specified timestamp.
    Restores at most max_runs per request.

    :param experiment_id: The ID of the experiment containing the runs to restore.
    :param min_timestamp_millis: The minimum deletion timestamp in milliseconds
                                 since the UNIX epoch for restoring runs. Only runs
                                 deleted at or after this timestamp are restored.
    :param max_runs: Optional. A positive integer indicating the maximum number
                     of runs to restore. The maximum allowed value for max_runs
                     is 10000. If not specified, max_runs defaults to 10000.
    :return: The number of runs restored.
    """
    from mlflow.utils.databricks_utils import get_databricks_host_creds
    from mlflow.utils.request_utils import augmented_raise_for_status
    from mlflow.utils.rest_utils import http_request
    json_body = {"experiment_id": experiment_id, "min_timestamp_millis": min_timestamp_millis}
    if max_runs is not None:
        json_body["max_runs"] = max_runs
    response = http_request(
        host_creds=get_databricks_host_creds(),
        endpoint="/api/2.0/mlflow/databricks/runs/restore-runs",
        method="POST",
        json=json_body,
    )
    augmented_raise_for_status(response)
    return response.json()["runs_restored"]

Consulte a documentação da API de Experimentos do Azure Databricks para obter parâmetros e especificações de valor de retorno para restaurar execuções com base no tempo de exclusão.

Comparar execuções

Você pode comparar execuções de um único experimento ou de vários experimentos. A página Comparando execuções apresenta informações sobre as execuções selecionadas em formatos gráficos e tabulares. Você também pode criar visualizações de resultados de execução e tabelas de informações de execução, parâmetros de execução e métricas.

Para criar uma visualização:

1. Selecione o tipo de gráfico (Gráfico de coordenadas paralelas, Gráfico de dispersão ou Gráfico de contorno).

   1. Para um Gráfico de Coordenadas Paralelas, selecione os parâmetros e métricas a serem plotados. A partir daqui, você pode identificar relações entre os parâmetros e métricas selecionados, o que ajuda a definir melhor o espaço de ajuste de hiperparâmetros para seus modelos.

      

   2. Para um Gráfico de Dispersão ou Gráfico de Contorno, selecione o parâmetro ou a métrica a ser exibida em cada eixo.

As tabelas Parâmetros e Métricas exibem os parâmetros de execução e as métricas de todas as execuções selecionadas. As colunas nessas tabelas são identificadas pela tabela Detalhes da execução imediatamente acima. Para simplificar, você pode ocultar parâmetros e métricas que são idênticos em todas as execuções selecionadas alternando .

Comparar execuções a partir de um único experimento

1. Na página do experimento, selecione duas ou mais execuções clicando na caixa de seleção à esquerda da execução ou selecione todas as execuções marcando a caixa na parte superior da coluna.
2. Clique em Comparar. A tela Comparando <N> execuções é exibida.

Comparar execuções de vários experimentos

1. Na página de experimentos, selecione os experimentos que deseja comparar clicando na caixa à esquerda do nome do experimento.
2. Clique em Comparar (n) (n é o número de experimentos selecionados). Uma tela é exibida mostrando todas as execuções dos experimentos selecionados.
3. Selecione duas ou mais execuções clicando na caixa de seleção à esquerda da execução ou selecione todas as execuções marcando a caixa na parte superior da coluna.
4. Clique em Comparar. A tela Comparando <N> execuções é exibida.

A cópia é executada entre espaços de trabalho

Para importar ou exportar execuções MLflow de ou para seu espaço de trabalho Databricks, você pode usar o projeto de código aberto orientado pela comunidade MLflow Export-Import.