MLOpsパイプライン¶
この runbook は、DVC と MLflow で self-play / training / evaluation artifact を体系的に追跡するための入口である。
目的¶
selfplay -> train -> eval -> promote -> submissionの依存関係を DVC で表現する。pca selfplay-trainが出す run manifest を MLflow に記録する。- 大きい JSONL / checkpoint は Git に直接入れず、DVC artifact として扱う。
- 既存の
pcaCLI、latest checkpoint alias、run manifest はそのまま使う。
セットアップ¶
uv sync --group mlops
DVC / MLflow / system metrics用のpsutilとNVIDIA
GPU監視用のnvidia-ml-pyは、通常の実行依存ではなく mlops dependency group に分けている。NVIDIA
GPUがない環境ではGPU metricだけが省略される。
DVC¶
pipeline 定義は dvc.yaml、既定値は params.yaml にある。
現在の stage:
| Stage | 役割 |
|---|---|
selfplay_train |
pca selfplay-train を実行し、JSONL / checkpoint / manifest を作る。 |
log_mlflow |
過去runやDVC runのmanifestをMLflowへ明示的に取り込む互換stage。 |
pipeline の状態を見る:
mise run mlops:dvc:status
mise run mlops:dvc:dag
実行する:
uv run --group mlops dvc repro selfplay_train
uv run --group mlops dvc repro log_mlflow
params.yaml の selfplay_train.run_id、total_games、games_per_cycle、chunks、checkpoint
を変えると別 run として実行できる。NVIDIA 複数 GPU で self-play worker を分散する場合は
selfplay_train.selfplay_devices_flag に --selfplay-devices auto または
--selfplay-devices cuda:0,cuda:1 を設定する。self-play 推論だけ fp16 checkpoint を使う場合は
selfplay_train.selfplay_precision: fp16 にする。
DVC が管理する checkpoint は dvc.yaml の outs にある train_output と train_best_output
である。通常の pca selfplay-train
を直接実行して作った run 固有 checkpoint は、自動では DVC 管理に入らない。DVC に載せたい run は
params.yaml の出力 path をその run に合わせて dvc repro selfplay_train
するか、個別 artifact として dvc add する。
MLflow¶
pca selfplay-trainは既定で同じpipeline run
IDの親runと、cycleごとの子runを作成する。追加optionは不要で、MLflow
UIを起動していない間もsqlite:///mlflow.dbへ直接記録される。
pca selfplay-train \
--checkpoint checkpoints/policy_value_latest_best.pt \
--run-name iterative-10k \
--total-games 10000 \
--games-per-cycle 1000 \
--chunks 10 \
--workers 8 \
--train-device mps \
--resume
別のexperiment/backendを使う場合は--mlflow-experimentと--mlflow-tracking-uriを指定する。MLflowだけを無効化する場合は--no-mlflowを使う。この場合も復旧可能なmetrics
JSONLは残る。
過去のrun manifestを手動登録する場合は:
uv run --group mlops python -m pca.tools.mlflow_log_manifest \
--manifest logs/selfplay-train/dvc-selfplay-train-local.manifest.yaml \
--experiment pokemon-card-ai \
--tracking-uri sqlite:///mlflow.db
UI を見る:
mise run mlflow:ui
ブラウザで http://127.0.0.1:5050 を開く。macOSではControl
Centerがポート5000を使用することがあるため、MLflow UIには5050を割り当てている。
表示される指標¶
| Prefix | 内容 |
|---|---|
selfplay/progress |
完了games/records、finished/unfinished率。 |
selfplay/result |
勝率とWilson 95%信頼区間、deck-out/pokemon-out率。 |
selfplay/game/* |
1試合ごとの結果、盤面、行動品質、探索、速度と直近20/100試合の移動値。 |
selfplay/behavior |
ベンチ準備、エネルギー、進化、setup trainer、攻撃見送り、攻撃可能時END、初回攻撃。 |
selfplay/search |
simulations、depth、prior/visit/Q entropy、一致率、Gumbel候補・round・fallback。 |
selfplay/performance |
games/hour、records/sec、NN encode/tensor/forward、tree encode、ISMCTS時間。 |
train/window |
直近progress intervalのloss、policy KL/entropy/top-1一致率、LR、grad。 |
train/running |
epoch開始からの累積平均。 |
train/epoch |
epoch全体、validation loss、validation_*_gap。 |
train/system |
process RSS、CUDA/MPS memory。 |
system |
15秒間隔のhost CPU/RAM/disk/network、stage全processのRSS、NVIDIA GPU使用率・memory。 |
training/best |
親runに集約されたcycleごとのbest train/validation metrics。 |
training/selected_attempt |
promotion対象として選ばれたtrain attempt番号。 |
training/attempts_requested |
同じself-playデータで許可したtrain attempt上限。 |
data |
train/validation record数、recent/history replay game数とhistory比率。 |
promotion/head_to_head |
Candidate対Champion勝率、Wilson 95%信頼区間、未完了率。 |
promotion/rule_pool |
candidate/championのmacro/micro勝率、信頼区間、終了理由、デッキ別勝率と信頼区間。 |
promotion/promoted |
promotion合否。 |
promotion/training_promoted |
次cycleのTraining Championとして採用されたか。正式昇格も1になる。 |
train/windowを短期変化、train/runningを全体傾向として見る。MLflowの親runを開くと、各cycleの最終self-play、train/validation、promotion指標がstep=cycle番号として1本のグラフにまとまる。親runの子run一覧を展開すると、各cycleのbatch推移や探索統計を個別に確認できる。異なるpipeline
run同士はCompareで比較する。
validation_*_gapはvalidation - trainで、正の値が大きくなるほど未見gameへの汎化差が広がっている。self-playのp0/p1勝率は同一model対戦では強さの指標にせず、固定benchmarkのpromotion/head_to_headとpromotion/rule_poolを主指標にする。デッキ別metricはpromotion/rule_pool/<role>/by_deck/<deck>/...から確認する。
試合ごとのSelf-Play Metrics¶
各試合はgame_idをMLflowのstepとして、子cycle
runのselfplay/game/*へ記録する。主な系列は次のとおり。
outcome/*: 完了、p0/p1勝敗、deck-out、pokemon-out。board/*: サイド、攻撃回数、攻撃可能decision、終了時の山札・手札、進行不能pass。behavior/*: 基本ポケモン・エネルギー・進化・trainerの見送り、攻撃可能時END、攻撃せずturn終了。search/*: simulation/decision、深度、到達率、prior/visit/Q一致、entropy、Gumbel候補・round・fallback、leaf batch。performance/*: NN、encode、tensor、forward、tree encode、ISMCTSの試合別時間。rolling/20/*、rolling/100/*: 完了率、p0勝率、step、サイド、行動見送り、探索深度、試合時間の移動値。
全試合のMLflow metricに文字列dimensionを展開するとmetric数が増えすぎるため、deck/agent名とraw diagnosticsは次の専用JSONLへ保存する。
data/selfplay/<run-name>-<run-id>.game-metrics.jsonl
1行が1試合で、dimensions、比較用のmetrics、元のsetup_diagnosticsとdiagnosticsを持つ。--game-metrics-output PATHで変更できる。--resume時は既存のgame_idを重複記録せず、移動値も既存行から復元する。workerからMLflow/SQLiteへ同時書き込みせず、chunk完了時に親processがgame
ID順でまとめて反映するため、UIへの表示は試合終了直後ではなくchunk完了単位になる。
System MetricsとTraces¶
通常のpca selfplay-trainでは、各self-play/train/evaluation stageをtelemetry
wrapperから起動する。wrapperは自分自身と再帰的なchild
processを監視するため、--workers 8のself-playでもworkerを含めた
system/process_tree_rss_megabytesを記録できる。既定の間隔は15秒で、変更・無効化は次を使う。
pca selfplay-train --system-metrics-interval 30 ...
pca selfplay-train --no-system-metrics ...
MLflow UIでは子cycle runを開き、Metricsのsystem/*を選ぶ。NVIDIA環境では集約値に加えて
system/gpu_0_*のようなdevice別metricが出る。MPSはNVML対象外なので、既存のtrain/system/mps_*を確認する。
Tracesには全simulationや全batchを保存せず、次だけを記録する。
pipeline.<stage>: self-play、merge、train、promotionなど各commandの所要時間、終了status、exit code。train.validation: epochごとのvalidation入力数とvalidation metrics。selfplay.game: cycle先頭の代表3試合と、未完了・Gumbel fallback・攻撃可能turn終了などの異常試合。
MLflow
UIのexperimentまたはrun画面からTracesを開き、trace名、status、duration、inputs/outputsで絞り込む。代表試合数とchunkごとの追加異常上限は変更できる。
pca selfplay-train \
--trace-sample-games 5 \
--trace-max-anomalies 10 \
...
traceを停止してmetricsだけ残す場合は--no-mlflow-tracingを使う。System
Metrics、Traces、MLflowへの書き込み失敗はwarningとして扱い、学習本体やappend-only metrics
JSONLを止めない。
指標の説明¶
各runには、日本語のmetricガイドを次の場所へ自動保存する。
| MLflow UI | 内容 |
|---|---|
Overview > Notes |
指標の読み方、主指標、注意点を短くまとめた入口。 |
Artifacts > metadata > metrics-reference.md |
実装が認識している全metric patternの説明。run開始時から参照できる。 |
Artifacts > metadata > metrics-catalog.md |
そのrunで実際に記録されたmetricだけの説明。run終了時に作成する。 |
Artifacts > metadata > *.json |
Markdownと同じ定義の機械可読版。分析toolから再利用できる。 |
説明にはmetric名、意味、単位、望ましい変化方向、解釈上の注意を含める。デッキ別metricのように名前が動的に増えるものも、共通patternから対象デッキ名を含む説明を生成する。MLflowの通常metricには説明専用fieldがないため、グラフ上のmetric名とこのcatalogを対応させて読む。
各cycleは次も保存する。
logs/selfplay-train/<run-name>-<run-id>.metrics.jsonl
data/selfplay/<run-name>-<run-id>.game-metrics.jsonl
logs/selfplay-train/<run-name>-<run-id>.mlflow-run-id
logs/selfplay-train/<run-name>-<run-id>-cycleNNN.mlflow-run-id
cycleなしのrun ID fileは親run、cycleNNN付きは子runとの対応を保持する。--resumeは両方のrun ID
fileを読み、同じ親子runへ続きを記録する。MLflowへの書き込み失敗はwarningに留め、self-play/trainは継続する。
運用メモ¶
- DVC は pipeline と artifact の再現性を担当する。
- MLflow は実験比較、metrics、run manifest の検索を担当する。
- checkpoint 本体を MLflow に保存したい場合だけ
--log-checkpointsを使う。通常は DVC 側で artifact として扱う。 - Cloud や共有 storage へ artifact を置く場合は、DVC remote を別途設定する。