コンテンツにスキップ

導入・基本操作

このページでは、初めてリポジトリを取得した人が環境を構築し、pcaコマンドでself-play、学習、評価を始めるまでの手順を説明します。長時間運用や実験条件の詳細はサーバー学習手順を参照してください。

前提

  • Python 3.12
  • uv
  • Node.js / npm
  • mise
  • 必要に応じてdirenv

CABTを使った対戦には、コンペで配布された実行環境とカードデータが必要です。確認方法はCABTのローカル実行とCABTのDocker実行環境を参照してください。

セットアップ

repo rootで依存関係を導入します。

uv sync --group dev --group docs
npm install

仮想環境を有効化すると、pyproject.tomlの[project.scripts]で定義されたpcaコマンドを直接使えます。

source .venv/bin/activate
pca commands

仮想環境を有効化しない場合:

uv run pca commands

direnvを使う場合は、初回に許可します。.envrcが仮想環境と.envrc.localを読み込みます。

direnv allow
pca commands

必要な生成物ディレクトリは実行時にも作成されます。手動で準備する場合:

mkdir -p data/selfplay data/eval checkpoints logs dist

設定の優先順位

pcaは次の順に設定を解決します。後ろの指定が前を上書きします。

  1. configs/default.yamlのコマンドprofile
  2. コマンドprofileが参照する専用YAML
  3. CLI option

通常は最新のunified modelや探索方式を意識せず、デフォルトprofileを利用できます。別profileを使う場合は--profile、内部で実行されるコマンドだけを確認する場合は--print-commandを使います。

pca --profile configs/default.yaml train \
  --input data/selfplay/custom.jsonl \
  --device mps

pca --print-command selfplay --games 1 --device cpu

profileのschemaとCLIへの受け渡しはTools and Configを参照してください。

実行デバイス

用途 基本設定
self-play worker cpu。GPU利用時はworker数と推論競合を実測する
Macでのtraining mps
NVIDIA環境でのtraining cuda
smoke test / CI cpu

Linux x86_64ではuvがCUDA対応PyTorch indexを使用します。nvidia-smiが動いてもtorch.cuda.is_available()がfalseの場合は、Server Training RunbookのCUDA確認手順を参照してください。

最初の動作確認

CLIとmodule boundaryを確認します。

pca commands
pca selfplay --help
pca train --help
uv run --group dev pytest tests/test_module_boundaries.py

最小のself-play:

pca selfplay \
  --config configs/v13/selfplay-unified-smoke.yaml \
  --games 1 \
  --output data/selfplay/smoke.jsonl

最小の評価:

pca eval \
  --config configs/v13/evaluate-unified-smoke.yaml

自己対戦

現在のデフォルトprofileで100試合を生成する例:

pca selfplay \
  --checkpoint0 checkpoints/policy_value_latest_best.pt \
  --games 100 \
  --workers 8 \
  --device cpu \
  --output data/selfplay/example.jsonl

主な出力:

  • *.jsonl: decision pointごとの学習record
  • *.agent-summary.csv: agent別集計
  • *.agent-matchup.csv: agent組み合わせ別集計
  • *.deck-summary.csv: deck別集計

record形式と実装はSelf-Play Modulesを参照してください。

Policy/Value学習

self-play JSONLからunified Policy/Value modelを学習します。

pca train \
  --input data/selfplay/example.jsonl \
  --output checkpoints/policy_value_example_final.pt \
  --best-output checkpoints/policy_value_example_best.pt \
  --device mps

大量JSONLでは、設定または--streamingでstreaming datasetを使用できます。

pca train \
  --input data/selfplay/example.jsonl \
  --output checkpoints/policy_value_streaming_final.pt \
  --best-output checkpoints/policy_value_streaming_best.pt \
  --streaming \
  --device mps

model、validation、再開stateの詳細はPolicy/Value Training Modulesを参照してください。

反復学習

1,000試合ごとに学習し、合計10,000試合を生成する例:

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

各cycleでself-play、train、validation、Champion評価を実行します。再開方法、promotion gate、replay、複数GPU、出力manifestはServer Training Runbookにまとめています。

Belief学習

通常のunified checkpointにはintegrated belief headsが含まれます。standalone BeliefNetを個別実験する場合:

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

詳細はBelief Training Modulesを参照してください。

評価

checkpointをISMCTS policyとして評価する例:

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

探索方式や設定のA/B比較:

pca eval-ab \
  --set games=20 \
  --set workers=4 \
  --set device=cpu

評価指標とpromotion benchmarkはEvaluation Modulesを参照してください。

提出用bundle

最新Championを含むKaggle submission bundleを作成します。

pca submission-bundle --output dist/submission.tar.gz

特定checkpointを使う場合だけ--checkpointで上書きします。提出runtimeの境界はSubmission and Serving Modulesを参照してください。

次に読む

目的 ドキュメント
長時間のself-play / train Server Training Runbook
MLflow / DVC MLOps Pipeline
modelと探索の設計 現在の手法
moduleごとの実装 モジュール索引
開発とテスト 開発・品質チェック
artifact形式 Artifacts