kermt-infer

kermt-infer

SMILES のみの CSV に対して、ファインチューニング済み KERMT チェックポイントで予測を実行します。この スキルはワークフローオーケストレーターです。ckpt の検証、CSV の検証、データの準備、ランナーのブロッキング起動を行い、予測 CSV を返します。

ハードウェア要件

• GPU：1（シングル GPU）。マルチ GPU 推論は現在サポートされていません。
• VRAM：デフォルトの batch_size 32 では 4 GB 以上。
• ディスク：実行ごとに数百 MB（クリーン済み CSV ＋特徴量＋予測）。
• ドライバー／CUDA：CUDA 12.6（kermt イメージのベース）をサポートするホストであれば使用できます。

入力

必須：

• --ckpt <path> — ファインチューニング済みチェックポイント（タスク FFN ヘッドが必要です）。バリデーターは事前学習 ckpt を拒否し、kermt-finetune にリダイレクトします。
• --csv <path> — SMILES のみの CSV。先頭列は smiles である必要があります。その他の列は無視されます。

任意：

• --batch-size N — 設定済みのデフォルト（32）を上書きします。
• --seed N — 推論用の乱数シード（決定論的な特徴量化パス）。
• --gpus 0 — 単一 GPU の ID（デフォルトは 0）。マルチ 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
   

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

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

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

3. チェックポイントを検証します。

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

   JSON を解析します。ok: false の場合は中止します。バリデーターは事前学習 ckpt （has_task_ffn: false）を拒否し、kermt-finetune にリダイレクトします。

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

   $KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> -- \
       "python agent/scripts/check_data.py --mode inference --csv /data/<basename>"
   

   ok: false の場合は中止します。

5. データを準備します。

   $KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> --run-dir $RUN_DIR -- \
       "python agent/scripts/prepare_data.py --mode inference \\
            --csv /data/<basename> --out /runs/data"
   

   出力は $RUN_DIR/data/prepare_data.json に保存され、clean_csv と clean_npz のパスが含まれます（rdkit_2d_normalized 特徴量）。

6. ランナーを起動します（ブロッキング）。

   $KERMT_REPO/agent/scripts/kermt_container.sh run \\
       --ckpt <user-ckpt> --run-dir $RUN_DIR -- \\
       "python agent/scripts/run_inference.py \\
            --ckpt /ckpt \\
            --prepare-manifest /runs/data/prepare_data.json \\
            --out /runs \\
            [--gpus 0 --batch-size N --seed N]"
   

   成功すると予測 CSV のパスが返されます。

7. ユーザーに報告します。 次の短い概要を出力します：

   • 予測：$RUN_DIR/out/predictions.csv（smiles ＋ターゲットごとの列）
   • マニフェスト：$RUN_DIR/run.json（cmd_replay ＋イメージダイジェスト＋適用された引数）
   • ログ：$RUN_DIR/logs/inference.log
   • 行数： 個の分子を 個のターゲットについて予測

厳守事項

• ユーザーの ckpt を変更しないでください。 ランナーは ckpt を一意な <out>/ckpt_link/ サブディレクトリにシンボリックリンクし、main.py predict --checkpoint_dir がその ckpt を取得できるようにします。ソースファイルは変更されません。
• アーキテクチャは必ず ckpt から取得し、CLI／デフォルトから取得しないでください。 ランナーはバリデーターの arch ブロックを run.json に記録しますが、main.py predict に arch フラグを渡しません。predict は読み込んだ ckpt の saved_args からそれらを読み取ります。
• シングル GPU のみです。 マルチ GPU 推論は現在サポートされていません。
• 適用されたデフォルト値を表示してください。 run.json の args_applied フィールドには、すべてのフラグの値とソース（user / default-config）が記録されます。デフォルト値が補完されたフラグの概要を簡潔に示してください。

よくあるエラー

• inference requires a finetuned ckpt with task FFN heads → ckpt は事前学習 ckpt です。先に kermt-finetune を使用してください。
• prepare_data manifest reports ok=False → マニフェストの errors を確認し、失敗したステップを調べてください（通常は clean_smiles または save_features）。
• save_features または main.py predict からの could not convert string to float: '<value>' → 入力 CSV に数値以外のパススルー列（例：split ラベル）があります。推論時、prep ステップで CSV を SMILES のみに絞り込むようになりました。それでもこのエラーが発生する場合は、prepare_data を経由しないランナーが CSV を読み込んでいます。main.py を直接実行せず、スキル経由で再実行してください。
• --gpus '0,1' is single-GPU only → 単一の ID を渡してください。

再実行可能性

run.json の cmd_replay フィールドは、同じ入力で推論を再実行する 1 行のコマンドです。kermt コンテナ内で再実行するには：

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

ok_to_replay: false（起動時に kermt リポジトリの作業ツリーに未コミットの変更がある）の場合は、repo.commit でコミットを固定し、先に git checkout してください。