Link to this sectionRastreamento de experimentos com o Neptune#

O Neptune é um repositório de metadados para MLOps, criado para equipes que realizam muitos experimentos. Ele oferece um único lugar para registrar, armazenar, exibir, organizar, comparar e consultar todos os seus metadados de criação de modelos.

O Ultralytics YOLO26 integra-se ao Neptune para simplificar o rastreamento de experimentos. Esta 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 log personalizado.

Link to this sectionPrincipais recursos#

• Log Automatizado: Registre automaticamente as principais métricas de treinamento, como perda de caixa (box loss), 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 Modelo: Faça upload e 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.

Link to this sectionInstalação#

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

# Install the required packages
pip install ultralytics neptune

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

Link to this sectionConfiguraçã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.

Link to this sectionObtenha 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.

Link to this sectionDefina variáveis de ambiente#

A maneira mais segura de lidar com credenciais é via variáveis de ambiente. Observe que o callback do Neptune para o Ultralytics lê o argumento project do YOLO e não utiliza 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

Link to this sectionUso#

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á habilitada nas configurações.

Link to this sectionExemplo 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")

Link to this sectionEntendendo 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

Link to this sectionO 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:
   • Treino: box_loss, cls_loss, dfl_loss, 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 (ground truth) 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.

Link to this sectionUso Avançado#

Link to this sectionOrganizando execuções#

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

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

Link to this sectionLog 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.

Link to this sectionFAQ#

Link to this sectionComo desativo o log do Neptune?#

Se você instalou o neptune mas deseja desativar o log para uma sessão específica ou globalmente, você pode modificar as configurações do YOLO.

# Disable Neptune integration
yolo settings neptune=False

Link to this sectionMinhas imagens não estão sendo enviadas. O que há de errado?#

Certifique-se de que sua rede permita conexões com os servidores do Neptune. Além disso, o log de imagens geralmente ocorre em intervalos específicos (por exemplo, final das épocas ou final do treinamento). Se você interromper o treinamento precocemente usando Ctrl+C, alguns artefatos finais como matrizes de confusão ou os melhores pesos do modelo podem não ser enviados.

Link to this sectionPosso registrar em um ID de execução específico do Neptune?#

A integração atual cria automaticamente uma nova execução para cada sessão de treinamento. Para retomar o log em uma execução existente, você precisaria, tipicamente, manipular a inicialização do Neptune manualmente no código Python, o que está fora do escopo da integração automática. No entanto, o Ultralytics suporta a retomada de treinamento localmente, o que criará uma nova execução no Neptune para rastrear as épocas retomadas.

Link to this sectionOnde posso encontrar os pesos do modelo no Neptune?#

No seu painel do Neptune, navegue até a seção Artifacts ou All Metadata. Você encontrará uma pasta weights contendo seu arquivo best.pt, que você pode baixar para implantação.