kermt-finetune

kermt-finetune

ユーザー指定のラベル付き CSV を使って、事前学習済み KERMT エンコーダーをファインチューニングします。このスキルはワークフローオーケストレーターとして、チェックポイントの検証、データの検証と準備、ランナーのデタッチ起動を行い、実行ディレクトリとコンテナー名を返します。

ハードウェア要件

• GPU：デフォルトでは 1 基（シングル GPU）です。--gpus 0（または使用する GPU の ID）を渡すと、GPU を 1 基選択できます。マルチ GPU ホストでトレーニングを高速化するには、--num-gpus N（N>1）を渡して、N 基の GPU でデータ並列 DDP を実行します。この場合、--batch-size は GPU ごとの値です（グローバルな実効バッチサイズ = batch_size × N）。
• VRAM：デフォルトの batch_size 32 設定では 8 GB 以上が必要です。VRAM が少なくても、小さなバッチサイズなら動作します。--batch-size N を渡すと上書きできます。
• ディスク：1 回の実行につき数 GB（チェックポイント、特徴量、ログ）。
• ドライバー／CUDA：CUDA 12.6（kermt イメージのベース）をサポートするホストであれば使用できます。kermt-setup が事前に検証します。

入力

必須：

• --csv <path> — ラベル付き CSV。最初の列は smiles で、それ以外の各列がターゲットです。

チェックポイント（省略可能。省略した場合はリリース済みモデルがデフォルトで使用されます）：

• --ckpt <path> — 入力する事前学習済みチェックポイント（grover_base / cmim / hybrid）。バリデーターは、すでにファインチューニング済みのチェックポイントを拒否し、kermt-infer へのリダイレクトを案内します。省略した場合、スキルはリリース済みの事前学習済み hybrid モデル nvidia/NV-KERMT-70M-v2 のダウンロードを提案し、そのモデルからファインチューニングします。手順 3「チェックポイントの解決と検証」を参照してください。
• --pretrained-release — 対話形式の確認なしで、リリース済みモデルを使用することを明示的に指定します（非対話型／エージェントでの実行向け）。--ckpt とは併用できません。
• --model-dir <dir> — ダウンロードしたバンドルの保存先（デフォルトは $KERMT_REPO/models/NV-KERMT-70M-v2/）。ここに完全なバンドルがすでに存在する場合は再利用され、再ダウンロードされません。

省略可能：

• --dataset-type {regression | classification | multiclass} — デフォルトは regression（defaults_finetune.json から取得）。損失、メトリクスのデフォルト値、およびヘッドの初期化を決定します。分類タスクでは --dataset-type classification を指定してください。

• --targets COL [COL ...] — ターゲット列名を明示的に指定します。省略した場合、バリデーターは数値型の smiles 以外の列を自動検出し、続行前にスキルがユーザーに確認します。

• --val-csv <path> と --test-csv <path> — ユーザー指定の検証用およびテスト用分割データです。両方を指定するか、どちらも指定しないでください。指定しない場合、スキルは設定済みの --split-type を使って自動分割します。

• --split-type {random | scaffold_balanced | index_predetermined} — デフォルトは defaults_finetune.json の scaffold_balanced です。

  • random と scaffold_balanced：学習用 CSV から検証用／テスト用データを内部で分割します。--val-csv／--test-csv は不要です。
  • index_predetermined：--val-csv と --test-csv で事前分割済みの CSV を渡す必要があります（さらに、別途フォールドごとのインデックスファイルも必要です。kermt/util/utils.split_data を参照）。データセットに独自の標準分割が含まれる場合に使用します（例：tests/data/Biogen_for_grover/scaffold/ balance/<endpoint>/{train,val,test}.csv）。

• --metric NAME — mae（回帰のデフォルト）、auc（分類のデフォルト）、または kermt.util.metrics.get_metric_func が受け付ける任意の名前です。

• --epochs N／--batch-size N／--init-lr F／--max-lr F／--final-lr F／--warmup-epochs F／--weight-decay F／--dropout F／--bond-drop-rate F／--dist-coff F／--early-stop-epoch N／--seed N — 学習ハイパーパラメーターの上書き指定です。指定されていない項目は agent/config/defaults_finetune.json から補われます。

• --ffn-hidden-size N／--ffn-num-layers N — 共有 FFN トランクの次元です。

• --ffn-num-task-specific-layers N／--ffn-task-specific-hidden-size H — ターゲットごとの FFN ヘッドです（デフォルトは 0＝無効。ターゲットごとに特性が異なるマルチターゲットのファインチューニングに便利です）。N > 0 の場合は、両方を指定する必要があります。

• --ensemble-size N／--num-folds N — マルチモデル／k 分割交差検証の設定です。それぞれのデフォルトは 1 です。

• --gpus 0 — 単一プロセスでのファインチューニングに使用する単一 GPU ID（デフォルトは 0）です。--num-gpus > 1 の場合は無視されます。

• --num-gpus N — データ並列 DDP ファインチューニングに使用する GPU の数です。デフォルトは 1（単一プロセス。変更なし）です。N>1 の場合、WORLD_SIZE=N で main.py finetune を実行します（GPU ごとに 1 プロセス）。--batch-size は GPU ごとの値です。

• --from-prepare <dir> — prepare ステップをスキップし、<dir> にある既存の prepare_data.json を再利用します。ハイパーパラメーターを調整しながら反復する場合に便利です。

ワークフロー

$KERMT_REPO を kermt リポジトリのチェックアウト先のパスとし、kermt-setup によって kermt:latest がビルド済みであるとします。以下のすべてのパスはホスト上のものです。ヘルパーがそれらを既知のコンテナーパスにバインドマウントします。

1. 事前確認：コンテナーとシステムプローブを確認します。

   $KERMT_REPO/agent/scripts/kermt_container.sh check_system | python -c "
   import json, sys; d = json.load(sys.stdin)
   if not d['ok']:
       print('System check failed:', d['gaps']); sys.exit(1)
   print(f'OK: {len(d[\"gpus\"])} GPU(s); CUDA via container toolkit')
   "
   

   ok: false の場合は続行しません。

2. 実行ディレクトリを計算します。

   RUN_DIR=$KERMT_REPO/runs/finetune_$(date -u +%Y-%m-%dT%H-%M-%SZ)
   

3. チェックポイントを解決して検証します。 解決 — --ckpt が省略された場合のみ。 デフォルトではリリース済みの 事前学習済みハイブリッドモデル nvidia/NV-KERMT-70M-v2 を使用します:

   • 同意ゲート。 --pretrained-release が渡されていない限り、ユーザーに確認します: 「チェックポイントが指定されていません — リリース済みモデル nvidia/NV-KERMT-70M-v2 (NVIDIA Open Model License, https://huggingface.co/nvidia/NV-KERMT-70M-v2) をダウンロードし、それを基にファインチューニングしますか？ [y/N]」。明示的な yes (または --pretrained-release) なしに絶対にダウンロードしないでください。--ckpt と --pretrained-release の両方が指定された場合は中止します — これらは競合します。
   • 保存場所。 デフォルトは $KERMT_REPO/models/NV-KERMT-70M-v2/。指定があれば --model-dir <dir> を優先します。すでに完全なバンドルがある場合は再利用されます。
   • ダウンロード (フォアグラウンド、初回取得時は約 282 MB):

     $KERMT_REPO/agent/scripts/kermt_container.sh run --model-dir <save-dir> -- \
         "python agent/scripts/fetch_released_model.py --out /model"
     

     JSON を解析し、ok: false の場合は中止します (errors を表示)。成功した場合は <user-ckpt> = <save-dir>/kermt_contrastive_v2.0.pt を設定します。

   解決された (またはユーザー提供の) ckpt を検証します:

   $KERMT_REPO/agent/scripts/kermt_container.sh run --ckpt <user-ckpt> -- \
       "python agent/scripts/check_checkpoint.py --mode finetune_init --ckpt /ckpt"
   

   JSON を解析します。ok: false の場合は中止します。バリデータは既に ファインチューニング済みの ckpt (has_task_ffn: true) を拒否し、kermt-infer へ リダイレクトします。

4. データを検証します。

   $KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> -- \
       "python agent/scripts/check_data.py --mode finetune --csv /data/<basename> [--targets COL1 COL2 ...]"
   

   --targets がユーザーによって指定されていない場合は、JSON から auto_detected_targets を表示し、続行する前にユーザーに確認を求めます。ok: false の場合は中止します。

5. データを準備します (--from-prepare が指定されている場合はスキップ)。

   プリフライト: 兄弟の val.csv / test.csv を確認します。 prepare_data を呼び出す前に、 <user-csv> の親ディレクトリを調べます。正規に見える兄弟の val.csv (または val_*.csv — よくあるバリアントには val_T.csv、val_clean.csv があります) と、対応する test.csv / test_*.csv が train CSV の隣に存在する場合、そのデータセットは独自の事前定義された 分割を持っています。その場合は --split-type index_predetermined を設定し、 --val-csv / --test-csv を渡してください — そうしないと、設定された split_type (デフォルト scaffold_balanced) が train CSV を最初から再分割し、 ユーザーの val/test ファイルを黙って破棄します。判断に迷う場合 — または兄弟ファイルが 非正規のサフィックス (_T、_v2 など) を使用している場合 — は、状況をユーザーに 提示し、どちらを望むか確認してください。

   ターゲット名のクォート。 --targets の列名にシェルのメタ文字 (>、&、|、 (、)、$ など) が含まれる場合は、CLI で渡すときにそれぞれをシングルクォートで 囲み、シェルが名前の一部を消費しないようにします。例: --targets 'Log_Caco2_Papp_A>B' 'logD'。CSV ヘッダー自体はダウンストリームのトレーナーによって直接読み取られるため 影響を受けませんが、prepare_data.json マニフェストの targets[] フィールドには シェルが渡した内容がそのまま記録されます — クォートされていないメタ文字はそこで 切り捨てられます。

   マウントに関する注意: kermt_container.sh --data <host-csv> は <host-csv> の 親ディレクトリを /data にマウントします。したがって --val-csv と --test-csv は 同じ親ディレクトリ内のファイルを参照する必要があります。val/test が別のディレクトリ (例えば兄弟の splits/ フォルダ) にある場合は、ファイルではなくディレクトリに対して --data <dir> を使用して 3 つすべての親をマウントしてください。

   $KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> --run-dir $RUN_DIR -- \
       "python agent/scripts/prepare_data.py --mode finetune \\
            --csv /data/<basename> --out /runs/data \\
            --split-type <split_type> \\
            [--val-csv /data/<val-basename> --test-csv /data/<test-basename>] \\
            [--val-frac 0.1 --test-frac 0.1 --seed 0] \\
            --targets <COL1> [COL2 ...]"
   

   出力は $RUN_DIR/data/prepare_data.json に配置されます。scaffold_balanced と index_predetermined の場合、prep は単一の clean_full_csv + .npz を出力します。 ランナーはそれらを main.py finetune にそのまま渡し、main.py finetune が ユーザー指定のシードで内部的に split_data を呼び出します。

6. 実行時間を見積もり、適用されたデフォルトを表示します。

   • ファインチューニングの実時間は通常、1 GPU で数分から数時間です。
   • デフォルトから補われたフラグとユーザー指定のフラグをすべて要約して表示し、 ユーザーが何が仮定されたかを把握できるようにします。ランナーはこれを args_applied に記録します。
   • サンプルメッセージ: "Filling from defaults_finetune.json: epochs=30, batch_size=32, split_type=scaffold_balanced. Override any of these with --<flag>."

7. ターゲット確認ゲート（必須要件）。 ターゲットリストがどのように決定されたか（CLI の --targets、ステップ 4 での自動検出、または「Caco2 と HLM でファインチューニング」のようなユーザーの自然言語でのリクエスト）にかかわらず、runner を起動する前に、明示的な件数を添えて最終的なターゲットリストをユーザーに表示します。 "Will finetune on N target(s): COL1, COL2, ...". ユーザーのリクエストで指定されたサブセットがこのリストと一致しない場合（たとえば、自然言語で 2 つのタスクを指定したのにリストには 4 つ残っている場合）、差異があるものとして扱い、差分を示して再度確認を求めます。誤ったターゲットセットで黙って続行してはいけません。--yes が指定されていない限り、起動前に明示的な確認を待ちます。

8. runner をデタッチして起動します。 （pretrain スキルと同じ動作です。）

   $KERMT_REPO/agent/scripts/kermt_container.sh run_detached \\
       --name kermt-finetune-<ts> \\
       --ckpt <user-ckpt> --run-dir $RUN_DIR -- \\
       "python agent/scripts/run_finetune_local.py \\
            --ckpt /ckpt \\
            --prepare-manifest /runs/data/prepare_data.json \\
            --dataset-type <type> \\
            --out /runs \\
            [--gpus 0] \\
            [--num-gpus N] \\
            [--epochs N --batch-size N --init-lr F ...] \\
            [--ffn-num-task-specific-layers N --ffn-task-specific-hidden-size H]"
   

   コンテナ名、ID、ログファイルのパスが返されます。

9. ユーザーに報告します。 次の内容を短くまとめて出力します。

   • コンテナ名と ID
   • $RUN_DIR/run.json（cmd_replay とイメージダイジェストを含むマニフェスト）
   • ログファイル：$RUN_DIR/logs/finetune.log
   • TensorBoard：$RUN_DIR/logs/tb（tensorboard --logdir $RUN_DIR/logs/tb で開きます）
   • 最終チェックポイントは $RUN_DIR/ckpt/fold_0/model_0/model.pt （best-val）と last_checkpoint.pt（同じディレクトリにあり、自動再開の対象）に保存されます。 保留したテストデータの予測と指標は $RUN_DIR/ckpt/fold_0/test_result.csv に保存されます。パスは --num-folds ／--ensemble-size によって異なります。
   • 進捗を確認するには、kermt-monitor <RUN_DIR>（1 回のみ実行）または docker logs -f <container-name>（ストリーミング）を使用します。
   • 実行の完了まで待つには（短いテスト実行で便利です）： docker wait <container-name> — 完了時に終了コードが出力されます。

必須ルール

• 同意なしにリリース済みモデルをダウンロードしてはいけません。 --ckpt が省略された場合、ユーザーから明示的な「はい」を得るか、明示的な --pretrained-release フラグが指定された後にのみ、nvidia/NV-KERMT-70M-v2 をダウンロードします。--ckpt と --pretrained-release は同時に指定できません。
• ユーザーの入力 ckpt を変更してはいけません。 runner は --checkpoint_path でそのパスを渡します。task/train.py はモデルに読み取り専用で読み込み、新しい FFN ヘッドを追加します。元のファイルは変更されません。
• アーキテクチャは ckpt から取得し、CLI／デフォルト値からは取得しません。 runner は ckpt の saved_args から hidden_size、depth、num_attn_head、activation、embedding_output_type、self_attention（該当する場合は attn_hidden ／ attn_out も）を抽出します。この runner に --hidden-size フラグはありません。
• 実行時間の長いファインチューニングの完了を待ってはいけません。 このスキルは run_detached を使って起動し、ステップ 9 の後すぐに戻ります。kermt-monitor を使用してください。
• 適用したデフォルト値をユーザーに伝えます。 run.json の args_applied フィールドには、各フラグの値とその設定元（user ／ default-config）が記録されます。デフォルト値で設定されたすべてのフラグについて、ユーザーが何を前提とされたのか把握できるよう、1 行で要約して伝えます。

よくあるエラー

• finetune_init requires a pretrain ckpt (grover_base / cmim / hybrid) → 渡した ckpt はすでにファインチューニング済みです（タスク FFN ヘッドがあります）。代わりに pretrain ckpt を選ぶか、既存のファインチューニング済みモデルで予測を実行する場合は kermt-infer を使用してください。同じデータセットでファインチューニングを再開するには、スキルを介さず、直接 python main.py finetune --checkpoint_path <ckpt> ... を呼び出します。保存されたタスクの識別情報を新しいトレーニングデータと照合して機械的に検証できないため、エージェントスキルでは再開をサポートしていません。
• prepare_data manifest reports ok=False → 失敗したステップを errors で確認します（通常は clean_smiles または save_features）。修正して再実行してください。
• ffn_num_task_specific_layers=N>0 but ffn_task_specific_hidden_size is unset → MTL ヘッドには明示的な隠れ層サイズが必要です。--ffn-task-specific-hidden-size H を渡してください。
• finetune is single-GPU（--gpus 0,1 による）→ --gpus は、単一プロセスのファインチューニングで使用するデバイスを 1 つ選択します。複数 GPU を使うには、代わりに --num-gpus N（DDP）を使用してください。

再現性

run.json の cmd_replay フィールドには、同じ入力、ハイパーパラメーター、アーキテクチャでファインチューニングを再実行する単一行のコマンドが記載されています。kermt コンテナ内で再実行するには：

$(jq -r .cmd_replay $RUN_DIR/run.json)

マニフェストで ok_to_replay: false となっている場合（起動時に kermt リポジトリの作業ツリーに未コミットの変更があったため）、完全に同じ結果を再現できない可能性があります。まず repo.commit フィールドで正確なコミットを指定し、git checkout してください。