Rastreamento de experimentos com o Neptune#

Neptune é um armazenamento de metadados para MLOps, criado para equipes que executam muitos experimentos. Ele oferece um único local para registrar, armazenar, exibir, organizar, comparar e consultar todos os seus metadados de construção de modelos.

O Ultralytics YOLO26 integra-se com o Neptune para otimizar o rastreamento de experimentos. Essa integração permite que você registre automaticamente métricas de treinamento, visualize predições de modelos e armazene artefatos de modelos sem escrever código de registro personalizado.

Principais recursos#

• Registro Automatizado: Registre automaticamente métricas-chave de treinamento, como perda de caixa, perda de classificação e mAP.
• Visualização de Imagens: Visualize mosaicos de treinamento e predições de validação diretamente no painel do Neptune.
• Checkpoint de Modelos: Faça o upload e o controle de versão dos pesos do seu modelo treinado (best.pt) automaticamente ao final do treinamento.
• Rastreamento de Hiperparâmetros: Registre todos os parâmetros de configuração para garantir total reprodutibilidade dos seus experimentos.
• Gráficos Interativos: Visualize matrizes de confusão e curvas de precisão-revocação (precision-recall) para analisar o desempenho do modelo.

Instalação#

Para usar o Neptune com o Ultralytics, você precisará instalar o pacote de cliente neptune junto com ultralytics.

# Install the required packages
pip install ultralytics neptune

# Enable Neptune integration in Ultralytics settings
yolo settings neptune=True

Configuração#

Antes de começar o treinamento, você precisa conectar seu ambiente local ao seu projeto do Neptune. Você precisará do seu Token de API e Nome do Projeto do seu painel do Neptune.

Obtenha suas credenciais#

1. Faça login em Neptune.ai.
2. Crie um novo projeto (ou selecione um existente).
3. Vá ao seu menu de usuário e obtenha seu Token de API.

Defina variáveis de ambiente#

A maneira mais segura de lidar com credenciais é através de variáveis de ambiente. Observe que o callback do Ultralytics para o Neptune lê o argumento project do YOLO e não usa NEPTUNE_PROJECT. Passe o slug completo do Neptune (por exemplo, workspace/name) via project= no seu comando de treinamento; caso contrário, o Neptune tentará usar o padrão literal "Ultralytics" e a execução falhará.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

Uso#

Uma vez configurado, você pode começar a treinar seus modelos YOLO26. A integração com o Neptune funciona automaticamente quando o pacote neptune está instalado e a integração está ativada nas configurações.

Exemplo de Treinamento#

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")

# Train the model
# Pass the Neptune project slug as the 'project' argument (workspace/name)
results = model.train(data="coco8.yaml", epochs=10, project="my-workspace/my-project", name="experiment-1")

Entendendo a Integração#

O diagrama a seguir ilustra como o pipeline de Treinamento do Ultralytics interage com o Neptune para registrar vários artefatos e métricas.

graph LR
    A[YOLO Training Loop]:::start --> B{Neptune Callback}:::decide
    B -->|Log Scalars| C[Loss, mAP, LR]:::proc
    B -->|Log Images| D[Mosaics, Preds]:::proc
    B -->|Log Artifacts| E[Model Weights]:::proc
    B -->|Log Metadata| F[Hyperparameters]:::proc

    C --> G[Neptune Server]:::extern
    D --> G
    E --> G
    F --> G

    G --> H[Neptune Web Dashboard]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef extern fill:#607D8B,color:#fff

O que é registrado?#

Quando você executa o comando de treinamento, a integração com o Neptune captura automaticamente a seguinte estrutura de dados em sua execução:

1. Configuração/Hiperparâmetros: Todos os argumentos de treinamento (épocas, lr0, otimizador, etc.) são registrados na seção de Configuração.
2. Configuração/Modelo: A arquitetura e definição do modelo.
3. Métricas:
   • Train: box_loss, cls_loss, l1_loss (dfl_loss em modelos baseados em DFL), lr (taxa de aprendizado).
   • Métricas: precision, recall, mAP50, mAP50-95.
4. Imagens:
   • Mosaic: Lotes de treinamento mostrando aumento de dados.
   • Validation: Rótulos de verdade fundamental e predições do modelo em dados de validação.
   • Plots: Matrizes de confusão, curvas de Precisão-Revocação.
5. Pesos: O modelo treinado final (best.pt) é enviado para a pasta weights na execução do Neptune.

Uso Avançado#

Organizando execuções#

Você pode usar os argumentos padrão do Ultralytics project e name para organizar suas execuções no Neptune.

• project: Deve ser o slug do projeto no Neptune workspace/name; é isso que o callback passa para neptune.init_run.
• name: Atua como o identificador para a execução específica.

Log Personalizado#

Se você precisar registrar métricas personalizadas adicionais além do log automático, você pode acessar a instância de execução do Neptune. Observe que você precisará modificar a lógica do treinador ou criar um callback personalizado para acessar o objeto de execução específico, pois a integração do Ultralytics gerencia o ciclo de vida da execução internamente.

FAQ#