Integração com ClearML#

Sobre o ClearML#

ClearML é uma plataforma de MLOps open-source criada para otimizar os fluxos de trabalho de machine learning e poupar tempo de engenharia.

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

Usa quantas dessas ferramentas precisares — começa apenas pelo gerenciador de experimentos ou encadeia tudo num pipeline completo.

🦾 Configuração#

O ClearML precisa comunicar-se com um servidor para rastrear teus experimentos e dados. Tens duas opções:

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

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

pip install clearml

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

clearml-init

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

🚀 Treinar o YOLOv5 com ClearML#

Para ativar o rastreamento de experimentos, instala o pacote pip do ClearML se ainda não o tiveres feito:

pip install clearml

Isto ativará a integração com o script de treinamento do YOLOv5. Cada execução de treinamento a partir de agora 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 padrões são YOLOv5 e Training. O ClearML usa / como um delimitador de subprocessos, 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 do modelo (use --save-period n para salvar a cada n épocas)
• Saída da consola
• Escalares (mAP_0.5, mAP_0.5:0.95, precisão, recall, perdas, taxas de aprendizagem)
• 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 em 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.

🔗 Gestão de Versionamento de Conjuntos de Dados (Datasets)#

Versionar dados separadamente do código facilita o acesso à versão mais recente e garante total reprodutibilidade. Este repositório aceita um ID de versão do conjunto de dados, obtém os dados automaticamente se estiverem em falta e regista o ID como parâmetro da tarefa para que saibas sempre quais os dados usados em cada experimento.

Prepara o teu Conjunto de Dados#

O repositório do YOLOv5 suporta muitos datasets por meio de arquivos de configuração YAML. Por padrão, os datasets são baixados para a pasta ../datasets em relação à raiz do repositório. Após baixar coco128, a estrutura da pasta fica assim:

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

Qualquer conjunto de dados funciona, desde que preserves esta estrutura.

Em seguida, copie o arquivo YAML do dataset para a pasta raiz do dataset — o ClearML lê este arquivo para usar o dataset 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

Carrega o teu Conjunto de Dados#

Para registar o conjunto de dados como um dataset versionado do ClearML, entra na sua pasta raiz e executa:

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

clearml-data sync é um atalho 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

Treina num Conjunto de Dados ClearML#

Com o conjunto de dados registado, aponta 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, podes construir sobre eles. Como cada experimento rastreado captura todo o ambiente — código, pacotes instalados e configuração — as execuções são totalmente reprodutíveis. O ClearML permite-te 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 HPO localmente, usa o script fornecido. Primeiro, certifica-te de que existe uma tarefa de treinamento no gerenciador de experimentos — o script clona-a e varia os 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 job para uma fila do ClearML para que um agente remoto o processe.

🤯 Execução Remota (Avançado)#

Executar HPO localmente é prático, mas muitas vezes você vai querer realizar experimentos em hardware mais potente — uma máquina com GPU local ou uma instância em 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 noutra máquina (pacotes instalados, alterações não confirmadas e configuração). Um agente ClearML escuta uma fila, recolhe tarefas recebidas, recria o ambiente, executa o trabalho e envia escalares e gráficos de volta para o gerenciador de experimentos.

Transforma qualquer máquina — uma VM na nuvem, um computador com GPU local ou um portátil — num agente ClearML com:

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

Clonar, Editar e Enfileirar#

Com um agente em execução, podes atribuir-lhe trabalho diretamente a partir da interface:

• 🪄 Clica com o botão direito num experimento e clona-o.
• 🎯 Edita os seus hiperparâmetros.
• ⏳ Clica com o botão direito na tarefa clonada e enfileira-a numa fila de destino.

Executar 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 o registrador do ClearML ter sido instanciado. Adicione a linha destacada em 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 esta alteração, a execução do script de treinamento processa até essa linha, empacota o código e envia-o para a fila.

Trabalhadores com Autoescala#

O ClearML vem com escaladores automáticos que iniciam máquinas remotas na AWS, GCP ou Azure quando uma fila tem experimentos pendentes, convertem-nas em agentes ClearML e as desligam quando o trabalho é concluído — para que você pague apenas pela computação que estiver realmente em execução.

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

Saber 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.