Seguimiento de experimentos con Neptune#

Neptune es un almacén de metadatos para MLOps, diseñado para equipos que ejecutan una gran cantidad de experimentos. Te ofrece un único lugar para registrar, almacenar, mostrar, organizar, comparar y consultar todos los metadatos de construcción de tus modelos.

Ultralytics YOLO26 se integra con Neptune para simplificar el seguimiento de experimentos. Esta integración te permite registrar automáticamente las métricas de entrenamiento, visualizar las predicciones del modelo y almacenar los artefactos del modelo sin escribir código de registro personalizado.

Características clave#

• Registro automatizado: Registra automáticamente las métricas clave de entrenamiento, como la pérdida de caja, la pérdida de clasificación y el mAP.
• Visualización de imágenes: visualiza mosaicos de entrenamiento y predicciones de validación directamente en el panel de control de Neptune.
• Puntos de control del modelo: Sube y controla las versiones de los pesos de tu modelo entrenado (best.pt) automáticamente al finalizar el entrenamiento.
• Seguimiento de hiperparámetros: registra todos los parámetros de configuración para garantizar la reproducibilidad total de tus experimentos.
• Gráficos interactivos: visualiza matrices de confusión y curvas de precisión-exhaustividad (precision-recall) para analizar el rendimiento del modelo.

Instalación#

Para usar Neptune con Ultralytics, necesitarás instalar el paquete de cliente neptune junto con ultralytics.

# Install the required packages
pip install ultralytics neptune

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

Configuración#

Antes de comenzar el entrenamiento, debes conectar tu entorno local a tu proyecto de Neptune. Necesitarás tu API Token y el Project Name de tu panel de control de Neptune.

Obtén tus credenciales#

1. Inicia sesión en Neptune.ai.
2. Crea un proyecto nuevo (o selecciona uno existente).
3. Ve a tu menú de usuario y obtén tu API Token.

Configura las variables de entorno#

La forma más segura de gestionar las credenciales es mediante variables de entorno. Ten en cuenta que el callback de Neptune en Ultralytics lee el argumento project de YOLO y no utiliza NEPTUNE_PROJECT. Pasa el slug completo de Neptune (por ejemplo, workspace/name) mediante project= en tu comando de entrenamiento; de lo contrario, Neptune intentará usar el valor predeterminado literal "Ultralytics" y la ejecución fallará.

export NEPTUNE_API_TOKEN="your_long_api_token_here" # required

Uso#

Una vez configurado, puedes empezar a entrenar tus modelos YOLO26. La integración con Neptune funciona de forma automática cuando el paquete neptune está instalado y la integración está habilitada en la configuración.

Ejemplo de entrenamiento#

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")

Comprendiendo la integración#

El siguiente diagrama ilustra cómo interactúa el pipeline de entrenamiento de Ultralytics con Neptune para registrar varios artefactos y 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

¿Qué se registra?#

Cuando ejecutas el comando de entrenamiento, la integración de Neptune captura automáticamente la siguiente estructura de datos en tu ejecución:

1. Configuración/Hiperparámetros: todos los argumentos de entrenamiento (épocas, lr0, optimizador, etc.) se registran en la sección de Configuración.
2. Configuración/Modelo: la arquitectura y la definición del modelo.
3. Métricas:
   • Entrenamiento: box_loss, cls_loss, dfl_loss, lr (tasa de aprendizaje).
   • Métricas: precision, recall, mAP50, mAP50-95.
4. Imágenes:
   • Mosaic: Lotes de entrenamiento que muestran la aumentación de datos.
   • Validation: Etiquetas de verdad terreno y predicciones del modelo en datos de validación.
   • Plots: Matrices de confusión, curvas de precisión-exhaustividad (Precision-Recall).
5. Pesos: El modelo final entrenado (best.pt) se sube a la carpeta weights en la ejecución de Neptune.

Uso avanzado#

Organización de ejecuciones#

Puedes usar los argumentos estándar de Ultralytics project y name para organizar tus ejecuciones en Neptune.

• project: Debe ser el slug del proyecto de Neptune workspace/name; esto es lo que el callback pasa a neptune.init_run.
• name: Actúa como el identificador de la ejecución específica.

Registro personalizado#

Si necesitas registrar métricas personalizadas adicionales junto con el registro automático, puedes acceder a la instancia de ejecución de Neptune. Ten en cuenta que deberás modificar la lógica del entrenador o crear una callback personalizada para acceder al objeto de ejecución específico, ya que la integración de Ultralytics gestiona el ciclo de vida de la ejecución internamente.

FAQ#