launch

Launch：長時間のMLトレーニングジョブの事前チェックリスト

長時間のトレーニングジョブは、失敗すると大きなコストがかかります。データセットのパスが見つからない、あるいはNFSマウントに対してデフォルトの workers=8 が設定されていたために、12時間の実行が3エポック目でクラッシュすれば、丸一日が無駄になります。このスキルでは、GPUを使う前にすばやく確認する6つの項目を説明します。

このプラグインのエージェント型Stopフックは、アシスタントがチェックリストを経ずに実行を開始しようとすると、reason からここへ誘導します。

実行するタイミング

ユーザーが次のことを依頼した場合：

• トレーニング実行の起動／開始
• 失敗した実行の再開
• 実行中のジョブの停止（チェックリストのクリーンアップ部分も実行します）
• 送信前の起動コマンドの確認

または、ユーザーが次のいずれかを実行しようとしている場合：python train.py、accelerate launch、torchrun、deepspeed、sbatch train.sh、tmux new-session ... python ... train、wandb sweep。

チェックリスト

1. 参照実行との設定差分

最もコストのかかる失敗は、誤った設定で起動することです。開始する前に：

find configs/ recipes/ experiments/ -maxdepth 3 \( -name '*.yaml' -o -name '*.yml' -o -name '*.json' -o -name '*.toml' \) -mtime -30 2> /dev/null | head

目的の実行に似た設定（同じモデルファミリー、同じタスク）のうち、最終更新日時が最も新しいものを選び、目的の設定と比較します：

diff -u configs/baseline_v1.yaml configs/intended.yaml

差分のすべての行を確認します。それぞれについて、次のように問いかけてください。この違いには意図や理由があるか、それとも設定し忘れた古いデフォルト値か？ 気づきにくい性能低下のよくある原因：

• num_workers ／データローダーのワーカー数（多くのリポジトリではデフォルトが8ですが、NFSでは不適切です）
• batch_size（DDPではデバイスごとの値とグローバル値の不一致に注意）
• learning_rate（バッチサイズに比例して調整します。バッチサイズを変更した場合は、学習率も変更する必要があります）
• optimizer のベータ値／重み減衰（論文のデフォルト値とフレームワークのデフォルト値）
• mixed_precision（モデルによっては fp16 と bf16 の違いが重要です）
• gradient_accumulation_steps
• seed（再現性が必要なら設定したままにします）

このプロジェクトに参照設定がない場合は、ユーザーに参照先を指定してもらいます。フレームワークのデフォルト値だけで起動してはいけません。

2. 実行名のルール

実行名は、その実行が続く限りwandb／neptune／チェックポイントディレクトリ／ステータスレポートに残ります。内部コードを使わず、実験の内容を平易な英語で説明する名前にします：

• 悪い例：run-1、exp-b、final-v2、phase2-internal
• 良い例：imagenet-resnet50-bs256-lr0.1-cosine、coco-baseline-bs256-lr3e-4、swin-t-imagenet-distill-from-vit-l

形式：<dataset/task>-<model>-<key-config>-<distinctive-recipe-piece>。実行名だけで実験を一文で説明できないなら、その名前は適切ではありません。

3. パスの確認

起動前に、実行に必要なすべてのパスが存在することを確認します：

# Dataset path
ls -la /path/to/dataset | head

# Pretrained checkpoint (if loading)
ls -la /path/to/checkpoint.pt

# Output directory parent (must exist; the run dir will be created)
ls -la /path/to/runs/

# Config file
cat configs/intended.yaml | head

記憶を頼りにしたパスを信用してはいけません。存在しないデータセットパスで実行を開始すると、すぐに失敗する代わりに、30分後にクラッシュします。

4. モニタリングの設定

実験トラッカーを自動検出します：

• WANDB_API_KEY が設定されている、または起動スクリプトで wandb がインポートされている → wandb
• NEPTUNE_API_TOKEN が設定されている → neptune
• MLFLOW_TRACKING_URI が設定されている、または起動スクリプトで mlflow が使われている → mlflow
• runs/ または lightning_logs/ が存在する → tensorboard
• いずれも該当しない → ユーザーに確認します。数時間にわたる実行で「モニタリングなし」が適切な答えになることはほとんどありません

実行が正しいプロジェクト／エンティティ／実験名に表示されることを確認します。コホート比較用のタグ／グループが設定されていることも確認します。

5. 現地タイムゾーンでの終了予定時刻

実際の所要時間を見積もります：epochs × seconds-per-epoch / 3600 = hours。システムのタイムゾーンを使い、現地時間で終了予定時刻を伝えます。会議／睡眠／不在の時間帯にまたがる場合は、延期するか分割するかを決めます。

6. コードがプッシュ済みコミットと一致していること

ジョブを実行するマシン上で、実行元のリポジトリにて：

git status --porcelain            # must print nothing
git fetch -q && git rev-parse HEAD @{u}   # both hashes must match

未コミットまたは未プッシュの変更があると、後から実行に使われたコードを特定できません。どちらかの確認に失敗した場合は、ローカルで編集してコミット、プッシュし、起動前にホスト上で git pull を実行します。実行とともにコミットハッシュを記録します。

再起動と強制終了時のクリーンアップ

以前失敗した実行を再起動する場合、または置き換えを起動する前に強制終了する場合は、古いアーティファクトを次の順序で削除してください。

1. 起動元マシンのローカルチェックポイントディレクトリ：rm -rf /local/runs/<run-name>（先にパスを確認してください）。
2. クラスター／NFS／オブジェクトストア上のリモートアーティファクトディレクトリ：rm -rf /remote/runs/<run-name>（または同等の操作）。
3. 実験トラッカーの実行：トラッカーの API で削除します（wandb api.run(...).delete()、neptune の run.stop() + delete via UI など）。古いトラッカーの実行が残っていると、その後の比較が損なわれます。
4. スケジューラーの予約：SLURM ジョブ（scancel <jobid>）、lambda labs の予約、cron エントリなどをキャンセルします。「強制終了したのに GPU が割り当てられたまま」という実行は、繰り返し発生する無駄です。

これらを一つでも省くと、次回の起動や比較を混乱させるゴースト状態が残ります。

出力

ユーザーがこのスキルを呼び出したら、6 つのチェック（強制終了の場合は 3 つのチェックとクリーンアップ）を順に実施し、どれに合格し、どれに失敗したかを報告してください。ユーザーが明示的にチェックを免除しない限り、失敗があれば起動をブロックしてください。

問題なく起動できる場合は、コピーしてすぐ使えるよう、最後に起動コマンド自体をフェンス付きコードブロックで提示してください。