Server Training Runbook

更新日: 2026-07-05

この文書は、サーバーまたは長時間実行環境で self-play 収集、Policy/Value 学習、評価前チェックを回すための現行 runbook である。古い version 固有の script ではなく、pca コマンドと configs/default.yaml を入口にする。

方針

現行の標準パイプラインは Belief-Guided Neural ISMCTS self-play -> unified Policy/Value 学習 である。

• self-play は configs/default.yaml の selfplay-train に定義された最新 config を使う。
• Policy/Value checkpoint は unified model を前提にし、aux prize heads と integrated belief heads も同じ checkpoint に含める。
• standalone BeliefNet は互換用または個別実験用であり、通常の反復学習では必須ではない。
• 長時間 run は chunk に分け、--resume で再開できるようにする。
• 学習完了後は latest alias を更新し、次の self-play / eval / submission から同じ stable path を使う。

前提

repo root で実行する。環境は Python 3.12 と uv を前提にする。

uv sync
source .venv/bin/activate
pca commands

direnv を使っている場合は、direnv allow 後に pca をそのまま実行できる。

direnv allow
pca commands

必要な asset の目安:

pokemon-tcg-ai-battle/EN_Card_Data.csv
decks/own/
decks/opponents/
checkpoints/policy_value_v13_unified_rule_bootstrap_filtered_10k_best.pt

現在のデフォルトは configs/default.yaml にまとまっている。コマンドごとの実体は次の通り。

Command	Default
pca selfplay	configs/v13/selfplay-v13-ismcts-selfplay.yaml
pca train	configs/v13/train-policy-unified-selfplay.yaml
pca eval	configs/v13/evaluate-v13-ismcts-vs-rule.yaml
pca selfplay-train	scripts/run_selfplay_train.sh
初期 checkpoint	checkpoints/policy_value_v13_unified_rule_bootstrap_filtered_10k_best.pt

実行内容だけ確認したい場合は --print-command を使う。

pca --print-command selfplay-train --games 10 --workers 2

推奨する実行単位

長時間 self-play は、1つの巨大ファイルを一気に作るのではなく、chunk に分けて実行する。1000 games を 100 games x 10 chunk で収集してから 1 回学習する例:

pca selfplay-train \
  --run-name ismcts-selfplay-1000g \
  --chunks 10 \
  --games-per-chunk 100 \
  --workers 8 \
  --train-device mps \
  --resume

Linux/CUDA サーバーでは --train-device cuda、CPU 検証では --train-device cpu を使う。self-play は multiprocessing と安定性を優先し、デフォルトで CPU を使う。必要な場合だけ --selfplay-device を上書きする。

pca selfplay-train \
  --run-name cuda-selfplay-1000g \
  --chunks 10 \
  --games-per-chunk 100 \
  --workers 16 \
  --train-device cuda \
  --resume

反復学習

「N 試合 self-play するたびに学習し、その best checkpoint を次の self-play に使う」場合は、--total-games と --games-per-cycle を使う。

合計 10,000 games を 1,000 games ごとに学習する例:

pca selfplay-train \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --run-name ismcts-iterative-10k \
  --total-games 10000 \
  --games-per-cycle 1000 \
  --chunks 10 \
  --workers 8 \
  --train-device mps \
  --resume

この例では、各 cycle が 1,000 games で、--chunks 10 によって 1 cycle が 100 games x 10 chunk に分割される。cycle 1 の学習が終わると、cycle 2 の self-play は cycle 1 の best checkpoint から始まる。

途中で止まった場合は、同じ --run-name、--run-id、--resume で再実行する。run id を固定しておくと再開しやすい。

pca selfplay-train \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --run-name ismcts-iterative-10k \
  --run-id 20260705-120000 \
  --total-games 10000 \
  --games-per-cycle 1000 \
  --chunks 10 \
  --workers 8 \
  --train-device mps \
  --resume

再開時の挙動:

• chunk JSONL と summary CSV がそろっている chunk は skip する。
• --resume 付きで best checkpoint が既にある train stage は skip する。
• cycle 実行では、次 cycle の checkpoint が直前 cycle の best checkpoint に自動で切り替わる。

出力

主な生成物:

Artifact	Path
chunk JSONL	data/selfplay/<run-name>-<run-id>/<run-name>-partNNN.jsonl
merged JSONL	data/selfplay/<run-name>-<run-id>.jsonl
agent summary	*.agent-summary.csv
agent matchup summary	*.agent-matchup.csv
deck summary	*.deck-summary.csv
final checkpoint	checkpoints/policy_value_<run_name>_<run_id>_final.pt
best checkpoint	checkpoints/policy_value_<run_name>_<run_id>_best.pt
logs	logs/selfplay-train/<run-id>-*.log

学習が完了すると latest alias も更新される。

Alias	Meaning
checkpoints/policy_value_latest_best.pt	最後に完了した学習 run の best checkpoint。
checkpoints/policy_value_latest_final.pt	最後に完了した学習 run の final checkpoint。
checkpoints/policy_value_<run_name>_latest_best.pt	同じ run name 内の latest best checkpoint。
checkpoints/policy_value_<run_name>_latest_final.pt	同じ run name 内の latest final checkpoint。
checkpoints/policy_value_latest.yaml	latest alias が指す実体、run name、run id、config。

次の self-play、eval、submission bundle では、基本的に checkpoints/policy_value_latest_best.pt を使う。

pca selfplay \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --output data/selfplay/latest-smoke.jsonl \
  --games 4 \
  --workers 2

小さな疎通確認

大量実行の前に、同じ入口で小さく動かす。

pca selfplay-train \
  --run-name smoke-selfplay-train \
  --games 4 \
  --workers 2 \
  --train-device cpu \
  --resume

コマンド展開だけ見る場合:

pca --print-command selfplay-train \
  --run-name smoke-selfplay-train \
  --games 4 \
  --workers 2 \
  --train-device cpu

self-play だけ確認したい場合:

pca selfplay \
  --output data/selfplay/smoke.jsonl \
  --games 2 \
  --workers 2 \
  --device cpu

確認するログ:

fallback=0
search begin > 0
ismcts dec > 0
nn calls > 0
depth avg が 2 以上
reach attack_reached / prize_reached が出る

fallback が連続して出る場合、その JSONL は teacher search として弱い。大量学習に進む前に例外、checkpoint load、card metadata、belief source を確認する。

Policy/Value 学習だけ再実行する

self-play JSONL が既にある場合は train stage だけ実行できる。

pca selfplay-train \
  --skip-selfplay \
  --selfplay-output data/selfplay/ismcts-selfplay-1000g-20260705-120000.jsonl \
  --run-name ismcts-selfplay-1000g \
  --run-id 20260705-120000-retrain \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --train-device mps

より直接的に学習する場合:

pca train \
  --input data/selfplay/ismcts-selfplay-1000g-20260705-120000.jsonl \
  --init-checkpoint checkpoints/policy_value_latest_best.pt \
  --output checkpoints/policy_value_retrain_final.pt \
  --best-output checkpoints/policy_value_retrain_best.pt \
  --device mps

大きな JSONL では config 側の streaming を使う。CLI で明示する場合:

pca train \
  --input data/selfplay/large-selfplay.jsonl \
  --output checkpoints/policy_value_large_final.pt \
  --best-output checkpoints/policy_value_large_best.pt \
  --streaming \
  --device cuda

Belief 学習

通常の unified self-play / train では integrated belief heads を使うため、別 checkpoint の BeliefNet 学習は必須ではない。standalone belief checkpoint を別実験で使う場合だけ実行する。

pca belief-train \
  --input data/selfplay/example.jsonl \
  --output checkpoints/belief_final.pt \
  --best-output checkpoints/belief_best.pt \
  --device mps

No usable belief records found が出る場合は、self-play 収集時に full-observation targets が入っているか、JSONL が壊れていないかを確認する。

評価

学習後は小さな評価で動作確認してから、games / workers を増やす。

pca eval \
  --checkpoint0 checkpoints/policy_value_latest_best.pt \
  --games 20 \
  --workers 4 \
  --device cpu \
  --output data/eval/latest-smoke.json \
  --csv-output data/eval/latest-smoke.csv

rule agent pool 相手のデフォルト評価:

pca eval \
  --checkpoint0 checkpoints/policy_value_latest_best.pt \
  --games 100 \
  --workers 8 \
  --device cpu \
  --output data/eval/latest-vs-rule.json \
  --csv-output data/eval/latest-vs-rule.csv

評価で見る指標:

• normal_wins
• avg_prizes_taken
• avg_attacks
• avg_first_attack_step
• avg_first_prize_step
• deck_out_losses
• unfinished
• attack_ready_count

deck-out 勝ちだけ増える場合は、teacher search または value target がサイド取得に十分寄っていない可能性がある。

ログの読み方

self-play ログの重要部分:

search begin=... step=... end=... full_obs=... fallback=...
nn calls=... cache=hit/miss total=... fwd=...
[local-policy-batcher] requests=... batches=... avg_batch=... req/s=...
ismcts dec=... sim=... hidden=... time=...
depth avg=... max=... hist=...
reach turn_advance=... attack_reached=... prize_reached=...
root-actions sel play=... attach=... attack=... choice=...
prize-delta events=... taken=... value=...
perf elapsed=... speed=... progress=... remaining=... eta=...

見る順番:

1. fallback
2. 0 が望ましい。増える場合は search が落ちて NN-only fallback になっている。
3. depth avg
4. 2 以上を目安に見る。1 台だとほぼ root 付近しか見ていない。
5. reach
6. attack_reached / prize_reached が極端に低いと、探索が攻撃・サイド取得に届いていない。
7. nn fwd
8. 最大ボトルネックになりやすい。local-policy-batching を使う場合は [local-policy-batcher] avg_batch も見る。
9. perf progress / remaining / eta
10. 並列 self-play では一番遅い worker の eta が全体完了の目安になる。
11. taken / remain
12. サイド取得が増えているかを見る。deck-out や pokemon-out だけで終わるデータは品質が低い。

training ログで見る項目:

loss policy value aux belief policy_w aux_cov belief_cov lr grad
[memory] rss mps_alloc mps_driver mps_limit
Wrote best checkpoint ...
Wrote checkpoint ...

MPS で mps_driver が大きく見える場合でも、学習が継続していて mps_limit 付近で落ちていなければ即問題とは限らない。OOM が出る場合は batch size、streaming、device、worker 数を下げる。

JSONL の保全

長時間実行後は、生成された JSONL と summary CSV を消さないようにする。最低限、行数と先頭 record を確認する。

wc -l data/selfplay/ismcts-selfplay-1000g-20260705-120000.jsonl
head -n 1 data/selfplay/ismcts-selfplay-1000g-20260705-120000.jsonl

別環境へ移す場合は、JSONL と対応する checkpoint manifest を一緒に残す。

data/selfplay/<run>.jsonl
data/selfplay/<run>/*.csv
checkpoints/policy_value_<run>_best.pt
checkpoints/policy_value_latest.yaml

推奨サイクル

1. pca selfplay-train --games 4 で smoke。
2. pca selfplay-train --chunks 10 --games-per-chunk 100 で 1,000 games 収集と学習。
3. pca eval --checkpoint0 checkpoints/policy_value_latest_best.pt で rule agent pool と評価。
4. 問題なければ --total-games / --games-per-cycle で反復学習に進む。
5. 良い checkpoint は run-name scoped alias と manifest を残す。

1 回で大きく強くするより、teacher search と value head を少しずつ改善しながら反復する。

関連ドキュメント

• Self-Play Modules
• Policy/Value Training Modules
• Belief Training Modules
• Evaluation Modules
• Artifacts Catalog