Trackio - Rastreamento de Experimentos para Treinamento de ML

Trackio é uma biblioteca de rastreamento de experimentos para registrar e visualizar métricas de treinamento de ML. Ela sincroniza com Hugging Face Spaces para painéis de monitoramento em tempo real.

Três Interfaces

Quando Usar Cada Uma

API Python → Registro

Use import trackio em seus scripts de treinamento para registrar métricas:

• Inicialize o rastreamento com trackio.init()
• Registre métricas com trackio.log() ou use o report_to="trackio" do TRL
• Finalize com trackio.finish()

Conceito chave: Para treinamento remoto/na nuvem, passe space_id — as métricas sincronizam com um painel do Space para que persistam após o término da instância.

→ Veja references/logging_metrics.md para configuração, integração TRL e opções de configuração.

API Python → Alertas

Insira chamadas trackio.alert() no código de treinamento para sinalizar eventos importantes — como inserir instruções print para depuração, mas de forma estruturada e consultável:

• trackio.alert(title="...", level=trackio.AlertLevel.WARN) — dispara um alerta
• Três níveis de severidade: INFO, WARN, ERROR
• Alertas são impressos no terminal, armazenados no banco de dados, exibidos no painel e opcionalmente enviados para webhooks (Slack/Discord)

Conceito chave para agentes LLM: Alertas são o principal mecanismo para iteração autônoma de experimentos. Um agente deve inserir alertas no código de treinamento para condições de diagnóstico (picos de perda, gradientes NaN, baixa precisão, estagnação do treinamento). Como os alertas são impressos no terminal, um agente que está observando a saída do script de treinamento os verá automaticamente. Para execuções em segundo plano ou desanexadas, o agente pode consultar via CLI em vez disso.

→ Veja references/alerts.md para a API completa de alertas, configuração de webhook e fluxos de trabalho de agentes autônomos.

CLI → Recuperação

Use o comando trackio para consultar métricas e alertas registrados:

• trackio list projects/runs/metrics — descubra o que está disponível
• trackio get project/run/metric — recupere resumos e valores
• trackio list alerts --project <name> --json — recupere alertas
• trackio show — inicie o painel
• trackio sync — sincronize com o HF Space

Conceito chave: Adicione --json para saída programática adequada para automação e agentes LLM.

→ Veja references/retrieving_metrics.md para todos os comandos, fluxos de trabalho e formatos de saída JSON.

Configuração Mínima de Registro

import trackio

trackio.init(project="my-project", space_id="username/trackio")
trackio.log({"loss": 0.1, "accuracy": 0.9})
trackio.log({"loss": 0.09, "accuracy": 0.91})
trackio.finish()

Recuperação Mínima

trackio list projects --json
trackio get metric --project my-project --run my-run --metric loss --json

Fluxo de Trabalho Autônomo de Experimentos de ML

Ao executar experimentos autonomamente como um agente LLM, o fluxo de trabalho recomendado é:

1. Configure o treinamento com alertas — insira chamadas trackio.alert() para condições de diagnóstico
2. Inicie o treinamento — execute o script em segundo plano
3. Consulte alertas — use trackio list alerts --project <name> --json --since <timestamp> para verificar novos alertas
4. Leia métricas — use trackio get metric ... para inspecionar valores específicos
5. Itere — com base em alertas e métricas, pare a execução, ajuste hiperparâmetros e inicie uma nova execução

import trackio

trackio.init(project="my-project", config={"lr": 1e-4})

for step in range(num_steps):
    loss = train_step()
    trackio.log({"loss": loss, "step": step})

    if step > 100 and loss > 5.0:
        trackio.alert(
            title="Loss divergence",
            text=f"Loss {loss:.4f} still high after {step} steps",
            level=trackio.AlertLevel.ERROR,
        )
    if step > 0 and abs(loss) < 1e-8:
        trackio.alert(
            title="Vanishing loss",
            text="Loss near zero — possible gradient collapse",
            level=trackio.AlertLevel.WARN,
        )

trackio.finish()

Em seguida, consulte de um terminal/processo separado:

trackio list alerts --project my-project --json --since "2025-01-01T00:00:00"

Limitações

…