実験トラッキング

🎓 レベル：標準　|　重要度：A（必須）

📎 前提：再現性とバージョニング　|　関連：ハイパーパラメータ管理と再現

要点（BLUF）

実験トラッキングは「1回の実験（run）を、後から比較・再現できる形で記録する」仕組みです。記録すべきは4要素：パラメータ・メトリクス・成果物（モデル等）・出自（コード/データのバージョン）。
手作業のスプレッドシート管理は必ず破綻します。記録漏れ・転記ミス・「どのコードとデータで出した数字か」の欠落が積もり、半年後には誰も再現できません。
MLflow・Weights & Biases などの専用ツールが標準ですが（要最新確認）、本質は「run = params + metrics + artifacts + provenance」という単純な構造です。本ノートでは依存ゼロの最小トラッカーで本質を体感します。

1. なぜトラッキングが要るのか

ML 開発は探索です。「C を変えたら？」「特徴量を足したら？」を何十回も試します。各試行の結果を記録しないと、「一番良かったのはどの設定だっけ」「あの数字、どのデータで出した？」が分からなくなります。トラッキングは、この探索の履歴を機械可読な記録として残し、比較・再現・引き継ぎを可能にします。これは再現性（再現性とバージョニング）を日々の実験に落とし込む実務装置です。

2. run に記録する4要素

要素	内容	例
パラメータ	入力の設定	学習率・正則化 C・特徴量セット
メトリクス	出力の評価	精度・F1・損失・学習時間
成果物	生成物	モデルファイル・図・混同行列
出自（provenance）	再現の鍵	コードのGitハッシュ・データの内容ハッシュ

4つ目の出自が抜けがちですが最重要です。params と metrics だけ記録しても、「どのコード・どのデータで出したか」が無ければ再現できません（学習データの管理とデータバージョニング）。

3. 図解：トラッキングの流れ

flowchart LR
  A["実験開始（start_run）"] --> B["パラメータ記録"]
  B --> C["出自記録（コード版とデータ版）"]
  C --> D["学習と評価"]
  D --> E["メトリクスと成果物記録"]
  E --> F["実験終了（end_run）保存"]
  F --> G["複数runを横断比較 -> 最良を選ぶ"]

4. 動く最小例：MLflow風の最小トラッカー

labs/03_tracking/tiny_tracker.py に、依存ゼロ（標準ライブラリ＋scikit-learn）の最小トラッカーを置きました。run を JSON で保存し、4要素を記録、複数 run を比較して最良を選びます。中核はこれだけです：

class TinyTracker:
    def start_run(self, name):
        run_id = time.strftime("%Y%m%d-%H%M%S") + f"-{name}"
        return {"run_id": run_id, "name": name, "params": {},
                "metrics": {}, "provenance": {}, "artifacts": []}

    def log_params(self, run, **params):
        run["params"].update(params)

    def log_metrics(self, run, **metrics):
        run["metrics"].update({k: round(float(v), 4) for k, v in metrics.items()})

    def log_provenance(self, run, code_version, data_array):
        h = hashlib.sha256(np.ascontiguousarray(data_array).tobytes()).hexdigest()[:12]
        run["provenance"] = {"code_version": code_version, "data_hash": h}

正則化 C を 0.01 / 0.1 / 1.0 と変えて3 run 記録し、F1 最大の run を選びます。実行結果：

run=...-logreg_C0.01  C=0.01  acc=0.93   f1=0.9327
run=...-logreg_C0.1   C=0.1   acc=0.95   f1=0.9528
run=...-logreg_C1.0   C=1.0   acc=0.945  f1=0.9479

=== 最良 run（f1最大）===
run_id   : ...-logreg_C0.1
params   : {'model': 'LogisticRegression', 'C': 0.1}
metrics  : {'accuracy': 0.95, 'f1': 0.9528}
出自     : {'code_version': 'git:abc123', 'data_hash': '7a82c1a6b301'}

出力の意味：3つの実験が機械可読に記録され、F1 最大は C=0.1（f1=0.9528）と一意に選べました。各 run には出自（コード版 git:abc123・データ版 7a82c1a6b301）が紐づくので、後から「この数字はこのコードとこのデータで出した」と厳密に再現できます。実運用ではこの構造を MLflow 等が担います（要最新確認）が、骨格は同じです。

5. 運用の勘所

出自を必ず記録する：params/metrics だけでなく、コードハッシュとデータハッシュを毎 run 記録する。これが無いと再現不能。
記録は自動化する：人手で書くと必ず漏れる。学習スクリプトに記録呼び出しを埋め込み、走れば自動で残るようにする。
比較可能な単位で記録する：同じデータ分割・同じ評価指標で記録し、run 間を公平に比較できるようにする。
成果物はストレージに、メタは軽量DBに：モデル本体はオブジェクトストレージ、params/metrics は検索可能な形で（MLflow の Tracking Server の発想）。

なぜそうするのか

実験トラッキングは「あとで困らないため」の保険ではなく、意思決定の基盤です。どのモデルを本番に出すかは、複数 run の公平な比較で決まります。記録が無ければ比較できず、比較できなければ「なんとなく良さそう」で本番を選ぶことになります。出自を含めて記録するのは、選んだモデルを確実に再現してデプロイするためです（次のモデルレジストリとモデルのライフサイクルへ繋がる）。

⚠️ よくある落とし穴

出自を記録しない：params/metrics だけでは「どのコード・データで出したか」が失われ再現不能。
手作業で記録する：スプレッドシート転記は必ず漏れ・ミスが出る。自動記録にする。
指標を後から変えて比較する：run ごとに評価指標が違うと比較できない。指標を固定する。
成果物を run と紐付けず散逸させる：どの run がどのモデルファイルを生んだか分からなくなる。

対応 lab

mlops-study/labs/03_tracking/tiny_tracker.py — MLflow風の最小トラッカー。run の記録・保存・横断比較・最良選択。python tiny_tracker.py で実行。