Trackio - ML トレーニング実験追跡

Trackio は ML トレーニングメトリクスをログ記録し可視化するための実験追跡ライブラリです。リアルタイム監視ダッシュボード用に Hugging Face Spaces に同期されます。

3 つのインターフェース

タスク	インターフェース	リファレンス
トレーニング中のメトリクスログ記録	Python API	logging_metrics.md
トレーニング診断用アラート発火	Python API	alerts.md
トレーニング中/後のメトリクス・アラート取得	CLI	retrieving_metrics.md
ストレージスキーマ検査と直接 SQL 実行	CLI	storage_schema.md

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

Python API → ログ記録

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

• trackio.init() で追跡を初期化する
• trackio.log() でメトリクスをログ記録するか、TRL の report_to="trackio" を使用する
• trackio.finish() で終了する

重要な概念: リモート/クラウドトレーニングの場合、space_id を渡してください — メトリクスは Space ダッシュボードに同期され、インスタンス終了後も永続化されます。

→ セットアップ、TRL 統合、設定オプションについては 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 セットアップ、自律エージェントワークフローについては alerts.md を参照してください。

CLI → 取得

trackio コマンドを使用してログされたメトリクスとアラートを問い合わせます:

• trackio list projects/runs/metrics — 利用可能なものを検出する
• trackio get project/run/metric — サマリーと値を取得する
• trackio query project --project <name> --sql "SELECT ..." — キャッチオール読み取り専用 SQL を実行する
• trackio list alerts --project <name> --json — アラートを取得する
• trackio show — ダッシュボードを起動する
• trackio sync — HF Space に同期する

重要な概念: プログラム的な出力を得るには --json を追加してください。自動化と LLM エージェント向けに適しています。

リモート Spaces: list/get/query コマンドに --space <space_id_or_url> を追加してローカルデータの代わりにリモート HF Space を問い合わせます。プライベート Spaces には --hf-token を使用してください。

→ すべてのコマンド、ワークフロー、JSON 出力形式については retrieving_metrics.md を参照してください。 → SQLite テーブル、Parquet レイアウト、直接問い合わせの例については storage_schema.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
trackio query project --project my-project --sql "SELECT name FROM sqlite_master WHERE type = 'table'" --json

# リモート Space を問い合わせる
trackio list projects --space username/my-space --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"