Integração com ClearML

Sobre o ClearML

ClearML é uma plataforma de MLOps open-source criada para otimizar fluxos de trabalho de aprendizado de máquina e economizar tempo de engenharia.

• 🔨 Acompanhe cada execução de treinamento do YOLOv5 no gerenciador de experimentos.
• 🔧 Crie versões e acesse 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 seu modelo YOLOv5 treinado em uma API com alguns comandos usando o ClearML Serving.

Use quantas dessas ferramentas precisar — comece apenas com o gerenciador de experimentos ou conecte tudo em um pipeline completo.

🦾 Configuração

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

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

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

pip install clearml

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

clearml-init

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

🚀 Treinando o YOLOv5 com o ClearML

Para ativar o rastreamento 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 o train.py. Os padrões são YOLOv5 e Training. O ClearML usa / como delimitador de subprojeto, portanto, evite / em nomes de projetos personalizados.

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
• Checkpoints de 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 classificar pelo modelo de 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ão de conjunto de dados

O versionamento de dados separado do código facilita a obtenção da versão mais recente e garante total reprodutibilidade. Este repositório aceita um ID de versão de conjunto de dados, busca os dados automaticamente se estiverem faltando e registra o ID como um parâmetro de tarefa para que você sempre saiba quais dados foram usados em cada experimento.

Prepare seu conjunto de dados

O repositório YOLOv5 suporta 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 em relação à raiz do repositório. Após baixar o coco128, a estrutura da pasta fica assim:

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

Qualquer conjunto de dados funciona, desde que você mantenha essa estrutura.

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

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

Carregue seu conjunto de dados

Para registrar o conjunto de dados como um conjunto de dados ClearML versionado, entre na pasta raiz dele e execute:

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

clearml-data sync é uma abreviação para a seguinte sequência, 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 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 experimentos e dados versionados, você pode criar coisas sobre eles. Como cada experimento rastreado captura o ambiente completo — código, pacotes instalados e configuração — as execuções são totalmente reproduzíveis. O ClearML permite clonar um experimento, alterar seus parâmetros e executá-lo novamente de forma automática, o que é a base da otimização de hiperparâmetros (HPO).

Para executar HPO localmente, use o script fornecido. Primeiro, certifique-se de que uma tarefa de treinamento exista no gerenciador de experimentos — o script a clona e varia seus hiperparâmetros.

Preencha o ID da tarefa de 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

Alterne task.execute_locally() para task.execute() para enviar o trabalho para uma fila do ClearML para que um agente remoto o processe.

🤯 Execução remota (Avançado)

Executar HPO localmente é conveniente, mas muitas vezes você desejará experimentos em hardware mais potente — uma máquina com GPU local ou uma instância na nuvem. Esse é o papel do ClearML Agent:

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

Cada experimento rastreado 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 ClearML escuta uma fila, pega 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 com GPU local ou um laptop — em um agente 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 a ele diretamente da interface:

• 🪄 Clique com o botão direito em um experimento e clone-o.
• 🎯 Edite 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 sinalizar um script em execução para execução remota de forma programática, adicionando task.execute_remotely() após a instaciação do logger do ClearML. Adicione a linha destacada ao 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
# ...

Após essa alteração, a execução do script de treinamento ocorre até essa linha, empacota o código e envia-o para a fila.

Workers de dimensionamento automático

O ClearML vem com autoscalers que iniciam máquinas remotas na AWS, GCP ou Azure quando uma fila tem experimentos pendentes, convertem-nos em agentes ClearML e desligam-nos quando o trabalho termina — assim, você paga apenas pela computação que está realmente sendo utilizada.

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

Saiba mais

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