Hugging Face's logo

Trackio documentation

トラッキング

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

トラッキング

はじめに

Trackioは、project内で実験を整理するのを助けます。 projectはrunsのコレクションであり、各runは特定のパラメータセットと結果を伴うコードの単一の実行を表します。

初期化

Trackioで実験のトラッキングを開始するには、まずinit()関数でプロジェクトを初期化する必要があります:

import trackio

trackio.init(project="my_project")
  • プロジェクトが既に存在する場合、読み込まれます。
  • そうではない場合、Trackioは新しいものを作成します。

どちらの場合も、新しいランが自動的に開始され、データの記録がすぐにできるようになります。

ランの命名

各ランに意味のある名前を付けることで、整理や後日の参照が容易になるため、推奨されます。 name パラメータを使用して名前を設定できます:

trackio.init(project="my_project", name="my_first_run")

名前が指定されていない場合、Trackioはデフォルトの名前を生成します。

ランのグループ化

group パラメータを使用して、関連するランをグループに整理できます。これは、異なる設定で複数の実験を実行しながら、それらをまとめて比較したい場合に特に役立ちます。

# Group runs by experiment type
trackio.init(project="my_project", name="baseline_run_1", group="baseline")
trackio.init(project="my_project", name="augmented_run_1", group="augmented")
trackio.init(project="my_project", name="tuned_run_1", group="tuned")

同じグループ名で実行されたランはサイドバーにグループ化されるため、関連する実験を比較しやすくなります。また、Tracking Configuration（下記参照）に記載されているように、他の設定パラメータでもランをグループ化できます。

リモートログ出力（Hugging Face Spaceまたはセルフホストサーバー）

デフォルトでは、メトリクスはローカルに保存され、ダッシュボードはあなたのマシン上で開かれます。代わりに、メトリクスを以下に送信できます:

  • space_id を渡す（または TRACKIO_SPACE_ID を設定する）ことで、Hugging Face Space を指定できます。Trackio は Space を作成または再利用し、そこにデータを同期します。
  • server_url を渡す（または TRACKIO_SERVER_URL を設定する）ことで、セルフホストされた Trackio サーバー（HTTP または HTTPS）を使用できます。trackio.show() から取得した書き込みアクセス用 URL（クエリに write_token を含めることもできます）を使用するか、ベース URL と TRACKIO_WRITE_TOKEN を使用します。クライアントは、ダッシュボードが使用するのと同じ 書き込みトークン で認証を行います（Hugging Face トークンではありません）。

Space とセルフホスト URL の両方が設定されている場合（space_id / TRACKIO_SPACE_ID と server_url / TRACKIO_SERVER_URL が同時に指定されている場合）、Space が優先されます。セルフホスト URL は無視されます。dataset_id（非推奨。bucket_id を使用してください）や bucket_id などのオプションは、Hugging Face デプロイメントに適用されます。server_url のみが有効な場合、サーバーを実行するホスト上でストレージを設定してください（環境変数を参照）。

セットアップの手順（trackio showの実行、0.0.0.0へのバインド、トークンの書き込み）については、サーバーのセルフホスティングを参照してください。

組み込みダッシュボードは、localhost では 1 秒ごと、Hugging Face Space（*.hf.space）で開いた場合は 2 秒ごとに新しいランとメトリクスをポーリングします。これにより、Space URL に対するレート制限を緩和します。

データのロギング

実行が初期化されると、log()関数を使用してデータのロギングを開始できます。

trackio.log({"loss": 0.05})

Trackioは防御的に設計されており、Trackio側の障害がメインの実験コードを停止させることはありません。通常の使用において、Trackioのログ記録、フラッシュ、または配信パス内の問題が発生した場合、例外がトレーニングループから発生するのではなく、警告とローカルバッファリングに縮退します。

log()を呼び出すたびに、ステップカウンターが自動的にインクリメントされます。 複数のメトリクスを一度に記録する場合は、まとめて渡します:

trackio.log({
    "loss": 0.05,
    "accuracy": 0.95,
})

テーブルのログ記録

Tableクラスを使用して、表形式のデータをログに記録できます。これは、予測結果などの結果や、構造化されたデータの追跡に便利です。Imageクラスを使用して、テーブルに画像カラムを含めることもできます。

import pandas as pd

df = pd.DataFrame(
    {
        "prompt": ["Trackio", "Logging is"],
        "completion": ["is great!", "easy and fun!"],
        "reward": [0.123, 0.456],
    }
)
trackio.log(
    {
        ...
        "texts": trackio.Table(dataframe=df),
    }
)

ログレポート（Markdown）

You can log markdown reports using the Markdown class. Reports are shown in the Reports page in the dashboard, where the newest report appears first.

trackio.log(
    {
        "training_report": trackio.Markdown(
            """# Training Report

Final validation accuracy: **0.92**

- Best epoch: 18
- Early stopping: enabled
"""
        )
    }
)

ランの実行中に複数回レポートを記録できます（例えば、チェックポイントごとに1回など）。Trackioはステップ全体にわたって完全な履歴を保持します。

完全な実行可能なスクリプトについては、examples/training-with-report.pyを参照してください。

画像のログ記録

Imageクラスを使用して、画像をログに記録できます。

trackio.log({"image": trackio.Image(value="path/to/image.png", caption="Image caption")})

画像は、パス、numpy配列、またはPIL Imageから記録できます。

動画のログ記録

Videoクラスを使用して、動画をログに記録できます。

import trackio
import numpy as np

# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)
trackio.log({"my_video": video})

# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)
trackio.log({"batch_videos": batch_video})

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")
trackio.log({"file_video": video})

動画は、ファイルパスまたはNumPy配列から記録できます。

Numpy配列の要件:

  • np.uint8 型で、RGB 値が [0, 255] の範囲内である必要があります
  • 形状は次のいずれかである必要があります:
    • 単一の動画の(frames, channels, height, width)
    • 複数の動画の場合、(batch, frames, channels, height, width)（グリッドにタイル化されます）

オーディオのログ記録

Audioクラスを使用して、オーディオをログに記録できます。

import trackio
import numpy as np

# Generate a 1-second 440 Hz sine wave (mono)
sr = 16000
t = np.linspace(0, 1, sr, endpoint=False)
wave = 0.2 * np.sin(2 * np.pi * 440 * t)
audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
trackio.log({"tone": audio})

# Stereo from numpy array (shape: samples, 2)
stereo = np.stack([wave, wave], axis=1)
audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
trackio.log({"stereo": audio})

# From an existing file
audio = trackio.Audio("path/to/audio.wav", caption="From file")
trackio.log({"file_audio": audio})

オーディオは、ファイルパスまたはNumPy配列から記録できます。

Numpy配列の要件:

  • Shape はモノラルの場合は (samples,)、ステレオの場合は (samples, 2) である必要があります
  • numpy配列からログを記録する場合は、sample_rateを指定する必要があります。
  • 値は浮動小数点数または整数である必要があります。浮動小数点数はピーク正規化され、16ビットPCMに変換されます。
  • numpy配列からログを記録する場合、formatは"wav"または"mp3"に設定できます（デフォルトは"wav"）

3Dオブジェクトのロギング

他のメディアと同じtrackio.log() API を使用して、Object3D を利用します:

import numpy as np
import trackio

trackio.log({"scene": trackio.Object3D("path/to/scene.glb", caption="Prediction")})

points = np.random.normal(size=(50_000, 3))
trackio.log({"point_cloud": trackio.Object3D.from_numpy(points)})
形式メッシュ点群Gaussian splat
.glb / .gltfはいglTF経由いいえ
.objはいいいえいいえ
.stlはいいいえいいえ
.plyはいはいはい
.splatいいえいいえはい

NumPy配列は、これらの形状のいずれかである必要があります:

  • XYZ座標用の(N, 3)。
  • (N, 4) は XYZ に 1 から 14 までの整数カテゴリを加えたものです。Trackio は決定的なカテゴリパレットを適用します。
  • XYZと0から255までの整数RGB値の(N, 6)。

座標は有限である必要があります。通常の点群は、レンダリングされる点が300,000点に決定的に制限されます。元の点数とレンダリングされた点数は引き続き表示されます。TrackioはメッシュやGaussian splatsを間引くことはありません。

モデルは自己完結型である必要があります。埋め込み glTF データ URI はサポートされていますが、外部 glTF リソース、OBJ マテリアルライブラリ、および PLY テクスチャはサポートされていません。すべてのオブジェクトは、画像、動画、音声と同様に、<project>/<run>/<step>/<uuid>.<ext> というレイアウトを使用します。

3Dオブジェクトもテーブル内で動作します:

table = trackio.Table(
    columns=["sample", "reconstruction"],
    data=[["chair", trackio.Object3D("chair.gltf")]],
)
trackio.log({"reconstructions": table})

HTMLと図のログ記録

Htmlクラスを使用してHTMLをログに記録できます。

trackio.log({"report": trackio.Html("<h1>Results</h1>")})

Matplotlib と Plotly の図は HTML に変換されます:

import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[4, 5, 6])
trackio.log({"plot": fig})

システムメトリクスのロギング

Trackioはバックグラウンドでシステムメトリクスを自動的に記録できます。NVIDIA GPUとApple Silicon（Mシリーズ）Macの両方をサポートしています。

インストール:

# NVIDIA GPU monitoring
pip install trackio[gpu]

# Apple Silicon system monitoring
pip install trackio[apple-gpu]

自動ログ記録（デフォルト）:

適切なパッケージがインストールされ、互換性のあるハードウェアが検出されると、システムメトリクスはバックグラウンドで自動的に記録されます（デフォルトでは10秒ごと）：

import trackio

# Auto-enabled when hardware is detected
trackio.init(project="my_project")

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
# System metrics are logged automatically in the background

trackio.finish()

間隔をカスタマイズするか、自動ログ出力を無効化できます:

# Custom interval
trackio.init(project="my_project", gpu_log_interval=5.0)

# Disable auto-logging
trackio.init(project="my_project", auto_log_gpu=False)

手動ログ記録:

log_gpu() を使用して、特定のタイミングでシステムメトリクスを手動で記録することもできます:

import trackio

trackio.init(project="my_project", auto_log_gpu=False)

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
    trackio.log_gpu()  # Log system metrics at current time

trackio.finish()

NVIDIA GPU メトリクス:

GPUごとのメトリクス(gpu/{i}/{metric}):

  • gpu/0/utilization - GPU使用率(%)
  • gpu/0/memory_utilization - メモリコントローラー使用率(%)
  • gpu/0/allocated_memory - GiB単位で割り当てられたメモリ
  • gpu/0/total_memory - GiB 単位の総メモリ
  • gpu/0/memory_usage - メモリ使用率 (0-1)
  • gpu/0/temp - セルシウス温度
  • gpu/0/power - ワット単位の電力消費
  • gpu/0/power_percent - 上限に対する電力の割合
  • gpu/0/power_limit - ワット単位の電力制限
  • gpu/0/sm_clock - MHz 単位の SM クロック速度
  • gpu/0/memory_clock - MHz 単位のメモリクロック速度
  • gpu/0/fan_speed - ファン速度 %
  • gpu/0/performance_state - パフォーマンス状態 (P0-P15)
  • gpu/0/energy_consumed - 実行開始以降に消費されたエネルギー（ジュール）
  • gpu/0/pcie_tx - MB/s 単位の PCIe 送信帯域幅
  • gpu/0/pcie_rx - MB/s 単位の PCIe 受信帯域幅
  • gpu/0/throttle_thermal - 熱によるスロットリング（0/1）
  • gpu/0/throttle_power - パワースロットリング（0/1）
  • gpu/0/throttle_hw_slowdown - ハードウェアのスローダウン（0/1）
  • gpu/0/throttle_apps - アプリケーションのクロックスロットリング（0/1）
  • gpu/0/corrected_memory_errors - ECC 修正済みエラー
  • gpu/0/uncorrected_memory_errors - ECC 正誤不能エラー

集計メトリクス:

  • gpu/mean_utilization - 全GPUにわたる平均GPU使用率
  • gpu/total_allocated_memory - 全GPUで消費された合計メモリ量（GiB）
  • gpu/total_power - 全GPUの合計消費電力
  • gpu/max_temp - 全GPUの最高温度

Apple Siliconのメトリクス:

  • cpu/utilization - 全体のCPU使用率(%)
  • cpu/{i}/utilization - コアごとのCPU使用率(%)
  • cpu/frequency - 現在の CPU 周波数（MHz）
  • cpu/frequency_max - CPUの最大周波数（MHz）
  • memory/used - GiB 単位の使用メモリ
  • memory/total - GiB 単位の総メモリ
  • memory/available - GiB 単位の空きメモリ
  • memory/percent - メモリ使用率(%)
  • swap/used - GiB 単位の使用済み Swap
  • swap/total - GiB 単位の合計スワップ量
  • swap/percent - スワップ使用率(%)
  • temp/{label} - セルシウス温度の温度センサーの読み取り値（利用可能な場合）
  • gpu/detected - Apple GPUが検出されたかどうか（0/1）

コンソール出力と起動コマンドのキャプチャ

Trackio は、各ランの起動に使用されたコマンド（例: python train.py --lr 1e-3）を記録し、ダッシュボードのランページの上部に表示します。コピー用のボタンも用意されています。シークレットのように見える名前の引数の値（--hub_token、--api-key、password=... など）は、REDACTED に置き換えられます。コマンドは、ランの設定内の予約済みキー _Command として保存されます。

Trackioは、print()呼び出し、loggingの出力、トレースバックを含む、スクリプトがstdoutとstderrに書き込むすべての内容をキャプチャできます。これにより、ターミナルから離れている間でも、ダッシュボードから実行のログを追跡できます。コンソールのキャプチャはデフォルトで無効です。capture_console=Trueを指定して有効にします。

import logging

import trackio

logging.basicConfig(level=logging.INFO)

trackio.init(project="my_project", capture_console=True)

for step in range(100):
    loss = ...
    logging.info("step %d loss=%.4f", step, loss)
    trackio.log({"loss": loss})

trackio.finish()

コードを変更せずに、TRACKIO_CAPTURE_CONSOLE 環境変数を設定することで有効化することもできます:

TRACKIO_CAPTURE_CONSOLE=1 python train.py

キャプチャされた出力は、ランのページ（Runsページからランを開く）のConsole outputセクションに表示されます。ランが進行中の間、10秒ごとに更新され、Downloadボタンを押すと、完全なログがテキストファイルとして保存されます。各行は書き込まれた時点のUTC時刻とともに保存され、ダッシュボードではローカル時刻で表示されます。出力は10秒ごとおよびランが終了したときに保存され、ローカルでの実行、Spaceまたはセルフホストされたサーバーにログが記録された実行のいずれにも対応し、1ランあたり20 MBが上限です。

プロセスがSIGTERM（Slurm の時間制限、docker stop、または Kubernetes のエビクション）で停止された場合、最後の保存以降に書き込まれた出力は失われます。プロセス終了前に保存するには、TRACKIO_HANDLE_SIGTERM=1を設定してください。

コンソールキャプチャは、sys.stdoutとsys.stderrのwriteメソッドをラップすることで動作するため、trackio.init()の呼び出し前に設定されたloggingハンドラーもキャプチャされます。C拡張やサブプロセスからのメッセージなど、基盤となるファイルディスクリプターに直接書き込まれる出力はキャプチャされません。

注:パブリックなSpaceにログを出力する場合、キャプチャされたコンソール出力はダッシュボードを表示できるすべての人に表示されます。コンソールキャプチャを有効にする前に、スクリプトがシークレットを出力していないことを確認してください。

ランの終了

実行が完了したら、finish()で最終処理を行います。 これにより、実行が完了したことがマークされ、記録されたすべてのデータが保存されます:

trackio.finish()

ランの再開

Trackio は、安定した run_id によって実行を内部的に識別します。人間が読みやすい name は、もはや一意である必要がないため、同じ表示名を持つ複数の実行を作成できます。

特定の名称で最新のランを継続する必要がある場合（中断後の再開など）、同じプロジェクト名とラン名を指定してinit()を再度呼び出し、resume="must"を設定します。

trackio.init(project="my_project", name="my_first_run", resume="must")

これにより、その名前で最も最近に作成されたランが読み込まれ、同じrun_idを使用してデータのロギングを継続できます。ただし、resume="must"を設定し、同じ名前を持つ以前のランが存在しない場合、Trackioはエラーを発生させます。

より柔軟な動作を実現するには、resume="allow"を使用します。これにより、同名の実行が存在する場合は最新の実行を再開し、存在しない場合は新しい実行を作成します。

デフォルトはresume="never"で、同じnameを持つ別のランが既に存在していても、常に新しいrun_idを持つ新しいランを作成します。

トラッキング設定

実行の設定パラメータも追跡できます。これは、実験で使用したハイパーパラメータやその他の設定を管理するのに便利です。init()関数のconfigパラメータを使用して、設定データをログに記録できます。

for batch_size in [16, 32, 64]:
    for lr in [0.001, 0.01, 0.1]:
        trackio.init(
            project="hyperparameter_tuning",
            name=f"lr_{lr}_batch_{batch_size}_run",
            config={
                "learning_rate": lr,
                "batch_size": batch_size,
            }
        )
        # ... your training code ...
        trackio.finish()

ダッシュボードでは、“learning_rate”または“batch_size”でグループ化することで、異なるハイパーパラメータを持つランをより簡単に比較できます。

Update on GitHub

←Trackioへの移行 ハイパーパラメータスイープ→