Trackio - ML トレーニングの実験トラッキング

Trackio は ML トレーニングメトリクスをログして可視化するための実験トラッキングライブラリです。Hugging Face Spaces にシンクして、リアルタイム監視ダッシュボードを実現します。

3 つのインターフェース

タスク	インターフェース	リファレンス
トレーニング中のメトリクスのログ	Python API	references/logging_metrics.md
トレーニング診断のアラート発火	Python API	references/alerts.md
トレーニング後/中のメトリクス・アラートの取得	CLI	references/retrieving_metrics.md

各インターフェースの使い分け

Python API → ロギング

トレーニングスクリプトで import trackio を使ってメトリクスをログします:

• trackio.init() でトラッキングを初期化
• trackio.log() でメトリクスをログするか、TRL の report_to="trackio" を使用
• trackio.finish() で完了

重要概念: リモート/クラウドトレーニングの場合、space_id を渡すことで、メトリクスは Space ダッシュボードにシンクされ、インスタンス終了後も保持されます。

→ セットアップ、TRL 統合、設定オプションについては references/logging_metrics.md を参照してください。

Python API → アラート

トレーニングコードに trackio.alert() 呼び出しを挿入して、重要なイベントをフラグしてください。デバッグ用の print ステートメント挿入に似ていますが、構造化でクエリ可能です:

• trackio.alert(title="...", level=trackio.AlertLevel.WARN) — アラートを発火
• 3 つの深刻度レベル: INFO、WARN、ERROR
• アラートはターミナルに表示され、データベースに保存され、ダッシュボードに表示され、オプションで Webhook (Slack/Discord) に送信されます

LLM エージェント向けの重要概念: アラートは自律的な実験反復の主要メカニズムです。エージェントは損失スパイク、NaN 勾配、低精度、トレーニング停滞などの診断条件についてトレーニングコードにアラートを挿入すべきです。アラートはターミナルに表示されるため、トレーニングスクリプトの出力を監視しているエージェントは自動的にそれを検知します。バックグラウンド実行やデタッチ実行の場合、エージェントは CLI でポーリングできます。

→ 完全なアラート API、Webhook セットアップ、自律エージェントワークフローについては references/alerts.md を参照してください。

CLI → 取得

trackio コマンドを使ってログされたメトリクスとアラートをクエリします:

• trackio list projects/runs/metrics — 利用可能なデータを検出
• trackio get project/run/metric — サマリーと値を取得
• trackio list alerts --project <name> --json — アラートを取得
• trackio show — ダッシュボードを起動
• trackio sync — HF Space にシンク

重要概念: 自動化と LLM エージェント向けのプログラマティック出力には --json を追加します。

→ すべてのコマンド、ワークフロー、JSON 出力形式については references/retrieving_metrics.md を参照してください。

最小ロギングセットアップ

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

最小取得

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

自律 ML 実験ワークフロー

LLM エージェントとして実験を自律的に実行する場合、推奨ワークフローは以下の通りです:

1. アラート付きトレーニングセットアップ — 診断条件用に trackio.alert() 呼び出しを挿入
2. トレーニング起動 — スクリプトをバックグラウンドで実行
3. アラートのポーリング — trackio list alerts --project <name> --json --since <timestamp> で新しいアラートをチェック
4. メトリクス読取 — trackio get metric ... で特定値を検査
5. 反復 — アラートとメトリクスに基づいて実行を停止し、ハイパーパラメータを調整して新しい実行を起動

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

別のターミナル/プロセスからポーリングします:

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