kermt-infer

kermt-infer

在仅包含 SMILES 的 CSV 上，使用微调后的 KERMT 检查点运行预测。该技能是工作流编排器：验证 ckpt、验证 CSV、准备数据、阻塞式启动运行器，并返回预测 CSV。

硬件要求

• GPU：1 个（单 GPU）。目前不支持多 GPU 推理。
• 显存：默认 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，绝不取自 CLI/默认值。 运行器会在 run.json 中记录验证器的 arch 区块，但不会向 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' 标签）。现在预处理步骤会在推理时将 CSV 精简为仅包含 SMILES；如果仍出现此错误，说明 CSV 是由绕过 prepare_data 的运行器读取的。请通过此技能重新运行，而不要直接运行 main.py。
• --gpus '0,1' is single-GPU only → 仅传入单个 ID。

可重放性

run.json 的 cmd_replay 字段是一条单行命令，可使用相同输入重新运行推理。在 kermt 容器内重放：

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

如果 ok_to_replay: false（启动时 kermt 仓库工作树有未提交更改），请先通过 repo.commit 固定提交，并执行 git checkout 切换到该提交。