Integração com o ClearML#

Sobre o ClearML#

O ClearML é uma plataforma de código aberto de MLOps criada para simplificar os fluxos de trabalho de machine learning e poupar tempo de engenharia.

• 🔨 Acompanha cada execução de treinamento do YOLOv5 no gerenciador de experimentos.
• 🔧 Crie versões e acesse os seus dados de treinamento personalizados com a ferramenta de versionamento de dados integrada do ClearML.
• 🔦 Treine e monitore remotamente as execuções do YOLOv5 usando o ClearML Agent.
• 🔬 Encontre o melhor mAP com a otimização de hiperparâmetros do ClearML.
• 🔭 Transforme o seu modelo YOLOv5 em uma API com alguns comandos usando o ClearML Serving.

Use quantas ou tão poucas dessas ferramentas quanto precisar — comece apenas com o gerenciador de experimentos ou encadeie tudo em um pipeline completo.

🦾 Configuração#

O ClearML precisa se comunicar com um servidor para acompanhar os seus experimentos e dados. Você tem duas opções:

• Cadastre-se no ClearML Hosted Service gratuito, ou
• Implante o seu próprio servidor ClearML — ele é de código aberto, portanto continua sendo uma opção viável mesmo para dados sensíveis.

Em seguida, instale o pacote clearml Python e conecte o SDK ao seu servidor:

pip install clearml

Gere as credenciais em Settings → Workspace → Create new credentials (no canto superior direito da interface do ClearML) e execute:

clearml-init

Siga as instruções. Pronto — a configuração está concluída.

🚀 Treinando YOLOv5 com o ClearML#

Para ativar o acompanhamento de experimentos, instale o pacote pip do ClearML, caso ainda não o tenha feito:

pip install clearml

Isso ativará a integração com o script de treinamento do YOLOv5. A partir de agora, cada execução de treinamento será capturada e armazenada pelo gerenciador de experimentos do ClearML.

Para personalizar os nomes do projeto e da tarefa, passe --project e --name para train.py. Os valores padrão são YOLOv5 e Training. O ClearML usa / como delimitador de subprojetos; por isso, evite / nos nomes personalizados de projetos.

python train.py --img 640 --batch 16 --epochs 3 --data coco8.yaml --weights yolov5s.pt --cache

Ou com nomes personalizados:

python train.py --project my_project --name my_training --img 640 --batch 16 --epochs 3 --data coco8.yaml --weights yolov5s.pt --cache

Cada execução captura:

• Código-fonte e alterações não confirmadas
• Pacotes instalados
• Hiperparâmetros
• Pontos de verificação do modelo (use --save-period n para salvar a cada n épocas)
• Saída do console
• Escalares (mAP_0.5, mAP_0.5:0.95, precisão, recall, perdas, taxas de aprendizado)
• Detalhes da máquina, tempo de execução e data de criação
• Gráficos gerados, como o correlograma de rótulos e a matriz de confusão
• Imagens com caixas delimitadoras por época
• Visualizações de mosaico por época
• Imagens de validação por época

Tudo aparece na interface do ClearML, para que você possa monitorar o treinamento em um só lugar. Adicione colunas personalizadas (por exemplo, mAP_0.5) para ordenar pelo modelo com melhor desempenho ou selecione vários experimentos para compará-los lado a lado.

Continue lendo para saber mais sobre otimização de hiperparâmetros e execução remota.

🔗 Gerenciamento de versões de conjuntos de dados#

Versionar os dados separadamente do código facilita obter a versão mais recente e garante a reprodutibilidade completa. Este repositório aceita um ID de versão do conjunto de dados, obtém os dados automaticamente se estiverem ausentes e registra o ID como parâmetro da tarefa, para que você saiba sempre quais dados foram usados em cada experimento.

Prepare o seu conjunto de dados#

O repositório YOLOv5 oferece suporte a muitos conjuntos de dados por meio de arquivos de configuração YAML. Por padrão, os conjuntos de dados são baixados para a pasta ../datasets, relativa à raiz do repositório. Depois de baixar coco128, a estrutura de pastas fica assim:

..
|_ yolov5
|_ datasets
    |_ coco128
        |_ images
        |_ labels
        |_ LICENSE
        |_ README.txt

Qualquer conjunto de dados funciona, desde que você preserve esta estrutura.

Em seguida, copie o arquivo YAML do conjunto de dados para a pasta raiz do conjunto de dados — o ClearML lê esse arquivo para usar o conjunto de dados corretamente. Você pode criar o seu próprio YAML seguindo o layout do exemplo e garantindo que ele defina path, train, test, val, nc e names.

..
|_ yolov5
|_ datasets
    |_ coco128
        |_ images
        |_ labels
        |_ coco128.yaml  # <---- HERE
        |_ LICENSE
        |_ README.txt

Carregue o seu conjunto de dados#

Para registrar o conjunto de dados como um conjunto de dados versionado do ClearML, mude para a pasta raiz dele e execute:

cd ../datasets/coco128
clearml-data sync --project YOLOv5 --name coco128 --folder .

clearml-data sync é uma forma abreviada da sequência a seguir, que você também pode executar explicitamente:

# Add --parent <parent_dataset_id> to base this version on a previous one.
# Duplicate files are not re-uploaded.
clearml-data create --name coco128 --project YOLOv5
clearml-data add --files .
clearml-data close

Treine em um conjunto de dados do ClearML#

Com o conjunto de dados registrado, aponte o treinamento para ele pelo ID:

python train.py --img 640 --batch 16 --epochs 3 --data clearml://YOUR_DATASET_ID --weights yolov5s.pt --cache

👀 Otimização de hiperparâmetros#

Com os experimentos e dados versionados, você pode criar novas etapas com base neles. Como cada experimento acompanhado captura todo o ambiente — código, pacotes instalados e configuração — as execuções são totalmente reproduzíveis. O ClearML permite clonar um experimento, alterar os seus parâmetros e executá-lo novamente de forma automática, o que é a base da otimização de hiperparâmetros (HPO).

Para executar a HPO localmente, use o script incluído. Primeiro, verifique se existe uma tarefa de treinamento no gerenciador de experimentos — o script irá cloná-la e variar os seus hiperparâmetros.

Preencha o ID da tarefa do modelo em utils/loggers/clearml/hpo.py e execute:

# Install Optuna or change the optimizer to RandomSearch.
pip install optuna
python utils/loggers/clearml/hpo.py

Altere task.execute_locally() para task.execute() para enviar o trabalho para uma fila do ClearML, onde um agente remoto poderá obtê-lo.

🤯 Execução remota (avançada)#

Executar a HPO localmente é conveniente, mas muitas vezes você vai querer executar experimentos em hardware mais potente — uma máquina GPU local ou uma instância na nuvem. Essa é a função do ClearML Agent:

• Visão geral no YouTube
• Documentação

Cada experimento acompanhado contém tudo o que é necessário para reproduzi-lo em outra máquina (pacotes instalados, alterações não confirmadas e configuração). Um agente do ClearML monitora uma fila, obtém as tarefas recebidas, recria o ambiente, executa o trabalho e transmite escalares e gráficos de volta para o gerenciador de experimentos.

Transforme qualquer máquina — uma VM na nuvem, uma máquina local com GPU ou um laptop — em um agente do ClearML com:

clearml-agent daemon --queue QUEUES_TO_LISTEN_TO [--docker]

Clonagem, edição e enfileiramento#

Com um agente em execução, você pode atribuir trabalho diretamente a ele pela interface:

• 🪄 Clique com o botão direito em um experimento e clone-o.
• 🎯 Edite os seus hiperparâmetros.
• ⏳ Clique com o botão direito na tarefa clonada e enfileire-a em uma fila de destino.

Executando uma tarefa remotamente#

Você também pode marcar programaticamente um script em execução para execução remota adicionando task.execute_remotely() depois que o logger do ClearML tiver sido instanciado. Adicione a linha destacada a train.py:

# ...
# Loggers
data_dict = None
if RANK in {-1, 0}:
    loggers = Loggers(save_dir, weights, opt, hyp, LOGGER)  # loggers instance
    if loggers.clearml:
        loggers.clearml.task.execute_remotely(queue="my_queue")  # <------ ADD THIS LINE
        # data_dict is None unless the user selected a ClearML dataset, in which case ClearML fills it in.
        data_dict = loggers.clearml.data_dict
# ...

Depois dessa alteração, executar o script de treinamento fará com que ele execute até essa linha, empacote o código e o envie para a fila.

Workers com escalonamento automático#

O ClearML inclui autoscalers que iniciam máquinas remotas na AWS, GCP ou Azure quando uma fila tem experimentos pendentes, transformam-nas em agentes do ClearML e desligam-nas quando o trabalho termina — assim, você paga apenas pela computação que está realmente em execução.

Assista ao vídeo de introdução abaixo:

Saiba mais#

Para obter mais informações sobre a integração do ClearML com modelos Ultralytics, consulte o nosso guia de integração do ClearML e veja como você pode aprimorar o seu fluxo de trabalho de MLOps com outras ferramentas de acompanhamento de experimentos.