launch

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

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

このプラグインのエージェント型 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 のベータ値／weight decay（論文のデフォルトとフレームワークのデフォルト）
• mixed_precision（モデルによっては fp16 と bf16 の違いが重要です）
• gradient_accumulation_steps
• seed（再現性が必要なら設定したままにします）

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

2. 実行名の規則

実行名は、実行が存続する限り wandb／neptune／チェックポイントディレクトリ／ステータスレポートで使われます。内部コードではなく、平易な英語で実験の内容を表す必要があります：

• 悪い例：run-1、wave-2、cs-ad、phase2-internal
• 良い例：7src-fastvit-s-featmap-mlp-dinov3、coco-baseline-bs256-lr3e-4、swin-t-imagenet-distill-from-vit-l

命名パターン：<dataset/task>-<model>-<key-config>-<distinctive-recipe-piece>。名前だけで実験内容を一文で説明できないなら、その名前は適切ではありません。Stop フックは、セッション内だけで使われるラベルを含む実行参照に警告します。

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

記憶を頼りにしたパスを信用してはいけません。destructive_path_guard.sh フックは rm／mv の明らかなケースをすでにブロックしますが、起動時のパスも同じように慎重に確認する必要があります。データセットのパスが存在しないまま実行を始めると、すぐにではなく 30 分後にクラッシュします。

4. モニタリングの設定

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

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

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

5. ローカルタイムゾーンでの ETA

経過時間を見積もります：epochs × seconds-per-epoch / 3600 = hours。ローカルの TZ（システムの TZ。timezone_scrub.sh フックで検証されます）で ETA を伝えます。会議／睡眠／不在の時間帯に実行がまたがる場合は、延期するか分割するかを決めます。

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

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

1. 起動マシン上のローカルチェックポイントディレクトリ：rm -rf /local/runs/<run-name>（先にパスを確認してください。destructive_path_guard.sh が警告を表示します）。
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 が割り当てられたまま」という実行は、繰り返し発生する無駄です。

これらのいずれかを省略すると、次の起動や比較で混乱を招くゴースト状態が残ります。

出力

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

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