compare

比較：トラッカー間で同じエポックの実行を比較する

最もよくある比較の誤りは、実行 A がエポック 100 中のエポック 11 にあるのに、エポック 100 のベースライン値と比べて「実行 A はベースラインより 4 パーセントポイント遅れている」と報告することです。学生側は まだ学習中 なので、この比較には意味がありません。このスキルでは、同じエポックで揃えて比較することを徹底します。

アシスタントが実行間の差分を揃えずに報告した場合、エージェント型の Stop フックが reason からここへ誘導します。

実行するタイミング

ユーザーが次のいずれかを言った直後です。

• 「実行 A をベースライン／実行 B と比較して」
• 「自分の実行は改善しているか／追いついているか／遅れているか」
• 「これらの実験を順位付けして」
• 「X と Y の wandb／neptune」
• 「ベースラインに対する遅れを追跡して」

トラッカーを自動検出する

次の順に確認します。

1. WANDB_API_KEY 環境変数が設定されている、またはプロジェクトで wandb をインポートしている → wandb
2. NEPTUNE_API_TOKEN 環境変数が設定されている → neptune
3. MLFLOW_TRACKING_URI 環境変数が設定されている、または mlruns/ ディレクトリがある → mlflow
4. runs/ または lightning_logs/ ディレクトリがある → tensorboard
5. 実行ディレクトリに *results*.json／*meta*.json ファイルがある → ローカルファイル形式

どれにも該当しない場合は、推測する前にメトリクスの保存場所をユーザーに尋ねます。

プロトコル

1. 実行を特定する

省略名ではなく、完全な名前を取得します。ユーザーが「fvs-fm とベースライン」と言った場合は、次の点を確認します。

• どの fvs-fm 実行か（プロジェクト + エンティティ + 実行 ID）
• どのベースラインか（完全な実行名。ベースラインには複数のバリエーションがあることがよくあります）

2. メトリクスの履歴を取得する（最終値だけではなく）

最終報告値ではなく、曲線全体が必要です。最終値だけの比較では、収束の動きが分かりません。

wandb の場合：

import wandb
api = wandb.Api()
run = api.run("entity/project/run-id")
history = run.history(samples=10000)  # full history, not just summary

tensorboard の場合は、イベントファイルを解析します（tensorboard.backend.event_processing.event_accumulator.EventAccumulator）。

neptune／mlflow の場合は、それぞれの API を使用します。

3. 学生側の現在のステップを確認する

学生側とは、まだ進行中の実行（または評価対象の実行）です。最新の履歴行から現在のエポック／ステップを取得します。

4. ベースラインを同じステップで切り出す

ここが重要なステップです。ベースラインは（たとえば）エポック 100 まで実行されています。学生側はエポック 11 です。エポック 100 ではなく、エポック 11 における ベースラインのメトリクスを取得します。

student_step = student_history['epoch'].max()
baseline_at_same_step = baseline_history[baseline_history['epoch'] == student_step]

ベースラインに完全に一致するステップがない場合は、補間するか最も近いステップを選びます。どちらを使ったか明記します。

5. 代理メトリクスと下流メトリクスを分ける

多くの ML パイプラインには、代理メトリクス（低コストで、学習中に計算されるもの。特徴量に対する kNN 精度、損失、パープレキシティなど）と、下流の目標メトリクス（計算コストが高く、定期的または最後にのみ計算されるもの。ファインチューニング済みの線形プローブ精度、下流タスクの F1 など）があります。

代理メトリクスは収束の追跡に使います。目標メトリクスは、プロジェクトが実際に最適化しているものです。代理メトリクスだけを報告すると誤解を招く可能性があります。kNN で遅れている実行が、下流のファインチューニングでは差を縮めることもあります。両方を分けて報告します。

                        | student (ep 11) | baseline (ep 11) | delta |
| proxy (kNN top-1)     | 36.4%           | 38.9%            | -2.5  |
| downstream (linear)   | not yet         | 42.1%            | n/a   |

ユーザーが代理メトリクスのデータしか持っていない場合は、そのことを明示します。代理メトリクスだけで勝者を決めてはいけません。

6. 出力に記載する実行名

レポートの各行では、完全な実行名を使用します。cs-ad vs fvs-fm ではなく、必ず phase1-7src-conv-s-adaptor-mlp vs phase1-7src-fastvit-s-featmap-mlp とします。これを後で読む自分が、省略名を覚えているとは限りません。

アンチパターン

• 「X はベースラインより 4pp 遅れている」：どのステップ時点か を示していません。ほとんどの場合、誤りです。
• 「X は収束した」：曲線の最後の 5 エポックを示していません。
• 「最良の実行は Y」：実行ごとに異なる方法で記録されたメトリクス（異なる集約方法、異なる評価セット）に基づいています。
• 単一シードの比較を決定的な結果として扱うこと。分散が分かっている場合はその点に触れ、分からない場合は単一シードであることを明記します。

出力

メトリクスのペア（代理 + 下流）ごとに、簡潔な比較表を作成します。各行は学生側の現在のステップに揃えます。各セルは、特定のトラッカーの実行 ID とステップまで追跡できるようにします。最後に、比較結果を解釈する文を 1〜2 文添えます。「現在の傾きから推定すると、ステップ N で学生側は追いつく見込みです」は有用な表現です。「学生側が勝っている／負けている」と判断できるのは、収束前ではほとんどありません。