hugging-face-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 ダッシュボードに同期されるため、インスタンスの終了後も保持されます。

→ セットアップ、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

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"