kermt-add-cmim-pretrain

kermt-add-cmim-pretrain

grover_base チェックポイント（従来のオリジナル GROVER の grover.encoders.* または最新の kermt.encoders.*。語彙ヘッドの有無は問いません）を、完全な ハイブリッド（cMIM + 語彙）チェックポイントに変換し、その後、ユーザーの コーパスでハイブリッドとして継続事前学習します。

これは薄いラッパーです。upgrade_to_hybrid.py により、check_checkpoint.py で model_type: hybrid と判定される新しい ckpt が生成され、それ以降の ワークフローは kermt-continue-pretrain と同じです。

ステータス：実験的です。 このワークフローはエンドツーエンドで機能しますが、 原稿のスクラッチからのハイブリッド学習（リリース済みチェックポイントを 生成するもの）とのベンチマークは実施されていません。ランダム初期化から 再開するのではなく、既存の grover_base チェックポイントを拡張したい場合は、 kermt-pretrain-scratch の実験的な代替手段として使用してください。 アップグレード後の ckpt を本番作業に利用する前に、ご自身のベンチマークで 下流タスクの性能を検証してください。

ハードウェア要件

kermt-continue-pretrain と同じです（cMIM デコーダーによりパラメーターは増えますが、 その増加はわずかで、VRAM の余裕は十分なはずです）。アップグレードのステップ自体は 高速（約 5 秒）で、CPU のみを使用します。GPU を使用するのは、その後の継続事前学習だけです。

実行するタイミング

• grover_base チェックポイント（エンコーダーのみ、または語彙ヘッド付き）を持っており、 それをハイブリッド（語彙 + cMIM 対照学習）事前学習に拡張したい場合。
• スクラッチから事前学習をやり直すことなく（kermt-pretrain-scratch では数日規模）、 事前学習済みエンコーダーに SMILES 再構成の対照目的関数を追加する場合に便利です。

既存のハイブリッドまたは cmim ckpt を継続する場合は、直接 kermt-continue-pretrain を使用してください。カスタムコーパスで新しいモデルを学習する場合は、 kermt-pretrain-scratch を使用してください。

入力

必須：

• --ckpt <path> — アップグレードする grover_base ckpt。 check_checkpoint.py --mode upgrade_to_hybrid で検証されます。ckpt に対照ヘッドまたは タスク FFN がすでにある場合は拒否されます。
• --csv <path> — 事前学習コーパスの CSV。kermt-continue-pretrain の --csv 入力と同じ形式です。

任意（kermt-continue-pretrain と同じ）：

• --val-csv <path> — 検証用の CSV。指定しない場合は、prepare_data が --val-frac 0.1 で自動的に分割します。
• 学習ハイパーパラメーターの上書き（--epochs N、--batch-size N、lr の 3 値、 --warmup-epochs F など）。
• --vocab-loss-weight F / --latent-dim N / --contrastive-temperature F。
• --wandb-project NAME / --wandb-run-name NAME — 任意の Weights & Biases ログ記録（run name が反映されるのは、project も指定した場合のみです）。デフォルトでは無効です。
• --gpus 0,2。

ワークフロー

$KERMT_REPO を kermt リポジトリのチェックアウト先のパスとします。

1. 事前チェック：check_system（kermt-continue-pretrain のステップ 1 と同じです）。

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

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

3. 入力 ckpt を check_checkpoint --mode upgrade_to_hybrid で検証します。 ok: false の場合は中止します。バリデーターは、すでに contrast head を持つ ckpt（kermt-continue-pretrain を提案）や、task FFN heads を持つ ckpt（ckpt はファインチューニング済みです。元の事前学習チェックポイントの使用を提案）を拒否します。

4. check_data --mode pretrain でコーパスを検証します。 ok: false の場合は中止します。

5. --mode pretrain を指定してデータを準備します — --vocab-dir は指定しません。 アップグレードでは、コーパスの語彙サイズに合わせた新しい vocab heads が構築されるため、ckpt の古い語彙（encoder-only のレガシー grover_base ckpt には存在しない場合もあります）を引き継ぐのではなく、prepare_data によってコーパスから新しい語彙を生成します：

   $KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> --run-dir $RUN_DIR -- \
       "python agent/scripts/prepare_data.py --mode pretrain \\
            --csv /data/<basename> --out /runs/data \\
            [--val-csv /data/<val-basename>] [--val-frac 0.1] [--seed 0]"
   

   出力マニフェストには vocab_source: "built_fresh" が含まれ、smiles_vocab（コーパスから構築され、新しい decoder に必要）が生成されます。

6. ckpt をアップグレードします。

   $KERMT_REPO/agent/scripts/kermt_container.sh run --ckpt <user-ckpt> --run-dir $RUN_DIR -- \
       "python agent/scripts/upgrade_to_hybrid.py \\
            --ckpt /ckpt \\
            --prepare-manifest /runs/data/prepare_data.json \\
            --out /runs/upgraded.pt"
   

   JSON サマリーをユーザーに提示します。特に warnings[] には、エンコーダーアーキテクチャの差異に関する注記（例：レガシー GROVER には、最新の KERMTEmbedding にはない act_func_* キーが 2 つ余分に含まれていました）と、アップグレード後の ckpt のバックボーンが gtrans 以外の場合に関する pretrain_ddp.py の --backbone argparse 制限の注記が含まれます。

7. 実行時間を見積もり、ユーザーに確認します。 kermt-continue-pretrain と同じヒューリスティックを使います（コーパスサイズ × エポック数 × GPU 数 → 所要時間）。

8. ランナーをデタッチして起動します。

   $KERMT_REPO/agent/scripts/kermt_container.sh run_detached \\
       --name kermt-add-cmim-pretrain-<ts> \\
       --run-dir $RUN_DIR -- \\
       "python agent/scripts/run_pretrain_local.py \\
            --ckpt /runs/upgraded.pt \\
            --prepare-manifest /runs/data/prepare_data.json \\
            --out /runs \\
            [--epochs N --batch-size N ...]"
   

   ランナーはアップグレード後の ckpt を model_type: hybrid として認識するため、--pretrain_mode hybrid --vocab_loss_weight 1.0 を自動的に選択し、smiles_vocab も引き渡します。

9. アップグレード後の ckpt のパスと、kermt-continue-pretrain と同じ run.json の参照先／ログパス／TensorBoard URL の形式をユーザーに報告します。

厳守事項

• ユーザーの入力 ckpt は絶対に変更しないでください。 アップグレードでは <run_dir>/upgraded.pt に新しいファイルが書き込まれ、元の ckpt はそのまま保持されます。
• vocab heads は必ず新しく作成します。 入力 grover_base に vocab heads が含まれていても破棄し、新しいコーパスの語彙サイズに合わせて再構築します。アップグレード後の ckpt で継続事前学習を行うと、これらの新しい heads は decoder とともに学習されます。
• --backbone の選択肢を自動的に緩和しないでください。 入力 ckpt のバックボーンが gtrans ではない（例：レガシー dualtrans）ためにアップグレードの警告が出た場合は、警告を提示してユーザーに確認してください。レガシーのバックボーンを選択肢に追加するために parsing.py を黙って変更してはいけません。

よくあるエラー

• check_checkpoint rejected the ckpt と表示され、model_type=hybrid または cmim の場合 → ユーザーの ckpt にはすでに contrast head があります。 kermt-continue-pretrain に案内してください。
• check_checkpoint rejected the ckpt と表示され、task_ffn=true の場合 → ckpt はファインチューニング済みです。アップグレードのワークフローが対応するのは事前学習チェックポイントのみです。
• prepare manifest missing smiles_vocab → prepare_data が --skip-vocab または smiles vocab を省略する同等の指定で実行されました。これらのフラグを付けずに再実行してください。
• unexpected key(s) in encoder load の警告 → レガシー GROVER アーキテクチャでは、最新の KERMTEmbedding では使用されない act_func_* の重みがいくつか保存されていました。問題はなく、エンコーダーの残りの部分は正しく読み込まれています。

実行成功後の run.json の内容

kermt-continue-pretrain と同じ再現性フィールドに加えて、アップグレード後の ckpt の来歴を監査できるよう、アップグレード手順の summary.json が inputs.upgrade_summary のパスに記録されます。

再実行可能性

kermt-continue-pretrain と同じです。cmd_replay は run_pretrain_local.py --ckpt <upgraded.pt> ... の呼び出しを再構築します。add-cmim のフロー全体を最初から最後までやり直すには、入力の grover_base ckpt とコーパスも必要です。どちらも prepare_data と upgrade のマニフェストに絶対パスで記録されています。