huggingface-trackio

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 ダッシュボードに同期されるため、インスタンスの終了後も保持されます。自動作成された Space はデフォルトで公開されます。メトリクスを公開しない場合は、private=True を指定してください。

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

Python API → アラート

トレーニングコードに trackio.alert() の呼び出しを挿入して、重要なイベントを通知します。デバッグ用に print 文を挿入するようなものですが、構造化されていて、クエリで取得できます。

• trackio.alert(title="...", level=trackio.AlertLevel.WARN) — アラートを発報します
• 重大度は INFO、WARN、ERROR の 3 段階です
• アラートはターミナルに出力され、データベースに保存され、ダッシュボードに表示されます。また、オプションで 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

# Spaces are PUBLIC by default (good for shareable dashboards);
# pass private=True if the metrics should not be public
trackio.init(project="my-project", space_id="username/trackio", private=True)
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"