Seguimiento

Introducción

Trackio te ayuda a organizar tus experimentos dentro de un project. Un project es una colección de runs, donde cada run representa una única ejecución de tu código con un conjunto específico de parámetros y resultados.

Inicialización

Para comenzar a rastrear un experimento con Trackio, primero debe inicializar un proyecto con la función init():

import trackio

trackio.init(project="my_project")

Si el proyecto ya existe, se cargará.
En caso contrario, Trackio creará uno nuevo.

En ambos casos, se inicia automáticamente una nueva ejecución, lista para que registres datos.

Nombrar tu ejecución

Es una buena idea asignar a cada ejecución un nombre significativo para facilitar la organización y la referencia posterior. Puedes establecer un nombre usando el parámetro name:

trackio.init(project="my_project", name="my_first_run")

Si no se proporciona un nombre, Trackio genera uno predeterminado.

Agrupar ejecuciones

Puedes organizar ejecuciones relacionadas en grupos mediante el parámetro group. Esto resulta especialmente útil cuando se ejecutan varios experimentos con diferentes configuraciones pero se desea compararlos juntos:

# Group runs by experiment type
trackio.init(project="my_project", name="baseline_run_1", group="baseline")
trackio.init(project="my_project", name="augmented_run_1", group="augmented")
trackio.init(project="my_project", name="tuned_run_1", group="tuned")

Las ejecuciones con el mismo nombre de grupo se pueden agrupar en la barra lateral, lo que facilita comparar experimentos relacionados. También puedes agrupar ejecuciones por cualquier otro parámetro de configuración (consulta Tracking Configuration a continuación).

Registro remoto (Hugging Face Space o servidor autoalojado)

Por defecto, las métricas se almacenan localmente y abres el panel de control en tu máquina. En su lugar, puedes enviar las métricas a:

Un Hugging Face Space, pasando space_id (o configurando TRACKIO_SPACE_ID). Trackio puede crear o reutilizar el Space y sincronizar los datos allí.
Un servidor de Trackio autoalojado (HTTP o HTTPS), pasando server_url (o configurando TRACKIO_SERVER_URL). Utilice la URL de acceso de escritura de trackio.show() (opcionalmente con write_token en la consulta) o una URL base más TRACKIO_WRITE_TOKEN. El cliente se autentica con el mismo token de escritura que utiliza el panel (no con su token de Hugging Face).

Si se configura tanto un Space como una URL autoalojada (space_id / TRACKIO_SPACE_ID junto con server_url / TRACKIO_SERVER_URL), el Space tiene prioridad y la URL autoalojada se ignora. Opciones como dataset_id (obsoleta; use bucket_id en su lugar) y bucket_id se aplican a las implementaciones de Hugging Face; cuando solo está en vigor server_url, configure el almacenamiento en el host que ejecuta el servidor (consulte Variables de entorno).

Para los pasos de configuración (ejecutar trackio show, vincular a 0.0.0.0, escribir tokens), consulte Autoalojar el servidor.

El panel de control integrado consulta nuevas ejecuciones y métricas cada 1 segundo en localhost y cada 2 segundos cuando se abre en un Hugging Face Space (*.hf.space), para facilitar los límites de tasa en la URL del Space.

Registro de datos

Una vez que tu ejecución está inicializada, puedes comenzar a registrar datos usando la función log():

trackio.log({"loss": 0.05})

Trackio está escrito de forma defensiva para que los fallos en el lado de Trackio nunca deriven en la caída de tu código principal de experimentación. En un uso normal, los problemas en las rutas de registro, volcado o entrega de Trackio se degradan en advertencias y almacenamiento local en búfer, en lugar de lanzar excepciones desde tu bucle de entrenamiento.

Cada llamada a log() incrementa automáticamente el contador de pasos. Si deseas registrar varias métricas a la vez, pásalas juntas:

trackio.log({
    "loss": 0.05,
    "accuracy": 0.95,
})

Tablas de registro

Puedes registrar datos tabulares usando la clase Table. Esto es útil para hacer seguimiento de resultados como predicciones, o cualquier dato estructurado. Las tablas pueden incluir columnas de imágenes usando la clase Image.

import pandas as pd

df = pd.DataFrame(
    {
        "prompt": ["Trackio", "Logging is"],
        "completion": ["is great!", "easy and fun!"],
        "reward": [0.123, 0.456],
    }
)
trackio.log(
    {
        ...
        "texts": trackio.Table(dataframe=df),
    }
)

Informes de registro (Markdown)

Puedes registrar informes en markdown usando la clase Markdown. Los informes se muestran en la página Reports del panel de control, donde el informe más reciente aparece primero.

trackio.log(
    {
        "training_report": trackio.Markdown(
            """# Training Report

Final validation accuracy: **0.92**

- Best epoch: 18
- Early stopping: enabled
"""
        )
    }
)

Puedes registrar informes varias veces durante una ejecución (por ejemplo, un informe por punto de control) y Trackio mantendrá el historial completo a lo largo de los pasos.

Para un script completo y ejecutable, consulte examples/training-with-report.py.

Registro de imágenes

Puedes registrar imágenes usando la clase Image.

trackio.log({"image": trackio.Image(value="path/to/image.png", caption="Image caption")})

Las imágenes se pueden registrar desde una ruta, un array de numpy o una imagen PIL.

Registros de videos

Puedes registrar videos usando la clase Video.

import trackio
import numpy as np

# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)
trackio.log({"my_video": video})

# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)
trackio.log({"batch_videos": batch_video})

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")
trackio.log({"file_video": video})

Los videos se pueden registrar desde una ruta de archivo o desde un array de numpy.

Requisitos de los arreglos de Numpy:

Debe ser de tipo np.uint8 con valores RGB en el rango [0, 255]
La forma debe ser una de las siguientes:
- (frames, channels, height, width) para un solo video
- (batch, frames, channels, height, width) para varios vídeos (se organizarán en una cuadrícula)

Registro de audio

Puedes registrar audio utilizando la clase Audio.

import trackio
import numpy as np

# Generate a 1-second 440 Hz sine wave (mono)
sr = 16000
t = np.linspace(0, 1, sr, endpoint=False)
wave = 0.2 * np.sin(2 * np.pi * 440 * t)
audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
trackio.log({"tone": audio})

# Stereo from numpy array (shape: samples, 2)
stereo = np.stack([wave, wave], axis=1)
audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
trackio.log({"stereo": audio})

# From an existing file
audio = trackio.Audio("path/to/audio.wav", caption="From file")
trackio.log({"file_audio": audio})

El audio se puede registrar desde una ruta de archivo o desde un array de numpy.

Requisitos de los arreglos de Numpy:

La forma debe ser (samples,) para mono o (samples, 2) para estéreo
sample_rate debe proporcionarse al registrar desde un array de numpy
Los valores pueden ser de tipo float o entero; los floats se normalizan en su pico y se convierten a PCM de 16 bits
format puede ser "wav" o "mp3" al registrar desde un array de numpy (por defecto "wav")

Registro de objetos 3D

Usa Object3D con la misma API trackio.log() que otros medios:

import numpy as np
import trackio

trackio.log({"scene": trackio.Object3D("path/to/scene.glb", caption="Prediction")})

points = np.random.normal(size=(50_000, 3))
trackio.log({"point_cloud": trackio.Object3D.from_numpy(points)})

Formato	Mesh	Nube de puntos	Gaussian splat
`.glb` / `.gltf`	Sí	A través de glTF	No
`.obj`	Sí	No	No
`.stl`	Sí	No	No
`.ply`	Sí	Sí	Sí
`.splat`	No	No	Sí

Los arreglos de NumPy deben tener una de estas formas:

(N, 3) para las coordenadas XYZ.
(N, 4) para XYZ más una categoría entera de 1 a 14. Trackio aplica una paleta de categorías determinista.
(N, 6) para valores XYZ más valores RGB enteros de 0 a 255.

Las coordenadas deben ser finitas. Las nubes de puntos ordinarias están limitadas de forma determinista a 300.000 puntos renderizados; sus recuentos originales y renderizados siguen siendo visibles. Trackio no realiza decimación de mallas ni de splats gaussianos.

Los modelos deben ser autosuficientes. Se admiten URI de datos glTF incrustados, pero no los recursos glTF externos, las bibliotecas de materiales OBJ ni las texturas PLY. Cada objeto utiliza el mismo esquema <project>/<run>/<step>/<uuid>.<ext> que las imágenes, los vídeos y el audio.

Los objetos 3D también funcionan en tablas:

table = trackio.Table(
    columns=["sample", "reconstruction"],
    data=[["chair", trackio.Object3D("chair.gltf")]],
)
trackio.log({"reconstructions": table})

Registro de HTML y figuras

Puedes registrar HTML usando la clase Html.

trackio.log({"report": trackio.Html("<h1>Results</h1>")})

Las figuras de Matplotlib y Plotly se convierten a HTML:

import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[4, 5, 6])
trackio.log({"plot": fig})

Registro de métricas del sistema

Trackio puede registrar automáticamente las métricas del sistema en segundo plano. Admite tanto GPUs de NVIDIA como Macs con Apple Silicon (serie M).

Instalación:

# NVIDIA GPU monitoring
pip install trackio[gpu]

# Apple Silicon system monitoring
pip install trackio[apple-gpu]

Registro automático (predeterminado):

Cuando el paquete adecuado está instalado y se detecta hardware compatible, las métricas del sistema se registran automáticamente en segundo plano (cada 10 segundos por defecto):

import trackio

# Auto-enabled when hardware is detected
trackio.init(project="my_project")

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
# System metrics are logged automatically in the background

trackio.finish()

Puedes personalizar el intervalo o deshabilitar el registro automático:

# Custom interval
trackio.init(project="my_project", gpu_log_interval=5.0)

# Disable auto-logging
trackio.init(project="my_project", auto_log_gpu=False)

Registro manual:

También puede registrar métricas del sistema manualmente en momentos específicos usando log_gpu():

import trackio

trackio.init(project="my_project", auto_log_gpu=False)

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
    trackio.log_gpu()  # Log system metrics at current time

trackio.finish()

Métricas de GPU de NVIDIA:

Métricas por GPU (gpu/{i}/{metric}):

gpu/0/utilization - % de utilización de la GPU
gpu/0/memory_utilization - Utilización del controlador de memoria (%)
gpu/0/allocated_memory - Memoria asignada en GiB
gpu/0/total_memory - Memoria total en GiB
gpu/0/memory_usage - Proporción de uso de memoria (0-1)
gpu/0/temp - Temperatura en grados Celsius
gpu/0/power - Consumo de energía en vatios
gpu/0/power_percent - Potencia como porcentaje del límite
gpu/0/power_limit - Límite de potencia en vatios
gpu/0/sm_clock - Velocidad del reloj SM en MHz
gpu/0/memory_clock - Velocidad del reloj de memoria en MHz
gpu/0/fan_speed - Velocidad del ventilador (%)
gpu/0/performance_state - Estado de rendimiento (P0-P15)
gpu/0/energy_consumed - Energía consumida desde el inicio de la ejecución en julios
gpu/0/pcie_tx - Ancho de banda de transmisión PCIe en MB/s
gpu/0/pcie_rx - Ancho de banda de recepción PCIe en MB/s
gpu/0/throttle_thermal - Ajuste por temperatura (0/1)
gpu/0/throttle_power - Limitación de potencia (0/1)
gpu/0/throttle_hw_slowdown - Reducción de velocidad por hardware (0/1)
gpu/0/throttle_apps - Ajuste de velocidad del reloj de la aplicación (0/1)
gpu/0/corrected_memory_errors - Errores corregidos por ECC
gpu/0/uncorrected_memory_errors - Errores no corregibles de ECC

Métricas agregadas:

gpu/mean_utilization - Utilización media de la GPU en todas las GPUs
gpu/total_allocated_memory - Memoria total utilizada en todas las GPUs en GiB
gpu/total_power - Consumo total de energía en todas las GPU
gpu/max_temp - Temperatura máxima en todas las GPUs

Métricas de Apple Silicon:

cpu/utilization - Utilización general de la CPU en %
cpu/{i}/utilization - Utilización de CPU por núcleo (%)
cpu/frequency - Frecuencia actual de la CPU en MHz
cpu/frequency_max - Frecuencia máxima de la CPU en MHz
memory/used - Memoria utilizada en GiB
memory/total - Memoria total en GiB
memory/available - Memoria disponible en GiB
memory/percent - Uso de memoria (%)
swap/used - Swap usado en GiB
swap/total - Swap total en GiB
swap/percent - Uso de swap en %
temp/{label} - Lecturas del sensor de temperatura en grados Celsius (si está disponible)
gpu/detected - Si se detectó una GPU de Apple (0/1)

Captura de la salida de la consola y el comando de lanzamiento

Trackio registra el comando utilizado para iniciar cada ejecución (por ejemplo, python train.py --lr 1e-3) y lo muestra en la parte superior de la página de la ejecución en el panel de control, con un botón para copiarlo. Los valores de los argumentos cuyos nombres parecen secretos (como --hub_token, --api-key o password=...) se reemplazan por REDACTED. El comando se almacena en la configuración de la ejecución bajo la clave reservada _Command.

Trackio también puede capturar todo lo que tu script escribe en stdout y stderr, incluidas las llamadas a print(), la salida de logging y los tracebacks, para que puedas seguir los registros de una ejecución desde el panel de control cuando no estés frente a la terminal. La captura de consola está desactivada de forma predeterminada. Actívala con capture_console=True:

import logging

import trackio

logging.basicConfig(level=logging.INFO)

trackio.init(project="my_project", capture_console=True)

for step in range(100):
    loss = ...
    logging.info("step %d loss=%.4f", step, loss)
    trackio.log({"loss": loss})

trackio.finish()

O actívalo sin cambiar tu código estableciendo la variable de entorno TRACKIO_CAPTURE_CONSOLE:

TRACKIO_CAPTURE_CONSOLE=1 python train.py

La salida capturada aparece en la sección Salida de la consola de la página de la ejecución (abre una ejecución desde la página Ejecuciones). Se actualiza cada 10 segundos mientras la ejecución está en curso, y el botón Descargar guarda el registro completo como un archivo de texto. Cada línea se almacena con la hora UTC en la que se escribió; el panel de control la muestra en tu hora local. La salida se guarda cada 10 segundos y al finalizar la ejecución, funciona tanto para ejecuciones locales como para ejecuciones registradas en un Space o en un servidor autoalojado, y tiene un límite de 20 MB por ejecución.

Si el proceso se detiene con SIGTERM (un límite de tiempo de Slurm, docker stop o una expulsión de Kubernetes), se pierde la salida escrita desde el último guardado. Establezca TRACKIO_HANDLE_SIGTERM=1 para guardarla antes de que el proceso finalice.

La captura de consola funciona envolviendo el método write de sys.stdout y sys.stderr, por lo que también recopila los manejadores de logging configurados antes de que se llamara a trackio.init(). La salida escrita directamente en los descriptores de archivo subyacentes, como los mensajes de extensiones de C o subprocesos, no se captura.

Nota: Si registras en un Space público, la salida de consola capturada es visible para cualquier persona que pueda ver el panel de control. Asegúrate de que tu script no imprima secretos antes de habilitar la captura de consola.

Finalizar una ejecución

Cuando tu ejecución esté completa, finalízala con finish(). Esto marca la ejecución como completada y guarda todos los datos registrados:

trackio.finish()

Reanudar una ejecución

Trackio identifica las ejecuciones internamente mediante un run_id estable. El name legible por humanos ya no tiene que ser único, por lo que puedes crear varias ejecuciones con el mismo nombre de visualización.

Si necesitas continuar la última ejecución con un nombre determinado (por ejemplo, después de una interrupción), vuelve a llamar a init() con el mismo proyecto y nombre de ejecución, y establece resume="must":

trackio.init(project="my_project", name="my_first_run", resume="must")

Esto cargará la ejecución creada más recientemente con ese nombre para que puedas seguir registrando datos usando el mismo run_id. Pero si configuras resume="must" y no existe una ejecución previa con el mismo nombre, Trackio generará un error.

Para mayor flexibilidad, use resume="allow". Esto reanudará la última ejecución con ese nombre si existe, o creará una nueva ejecución en caso contrario.

El valor predeterminado es resume="never", que siempre crea una ejecución nueva con un run_id nuevo, incluso si ya existe otra ejecución con el mismo name.

Seguimiento de la configuración

You can also track configuration parameters for your runs. This is useful for keeping track of hyperparameters or other settings used in your experiments. You can log configuration data using the config parameter in the init() function:

for batch_size in [16, 32, 64]:
    for lr in [0.001, 0.01, 0.1]:
        trackio.init(
            project="hyperparameter_tuning",
            name=f"lr_{lr}_batch_{batch_size}_run",
            config={
                "learning_rate": lr,
                "batch_size": batch_size,
            }
        )
        # ... your training code ...
        trackio.finish()

En el panel de control, luego puede agrupar por “learning_rate” o “batch_size” para comparar más fácilmente las ejecuciones con diferentes hiperparámetros.

Update on GitHub