kermt-setup

kermt-setup

引导设置 KERMT Agent 环境。在全新机器上（或 Dockerfile 或 environment.yml 变更后）运行一次，然后再调用任何其他 kermt-* 技能。

硬件要求

• GPU：主机至少有一个可见的、支持 CUDA 的 NVIDIA GPU。镜像基于 nvidia/cuda:12.6.3-cudnn-devel-ubuntu22.04，因此主机驱动必须支持 CUDA 12.6。调用前请在主机上运行 nvidia-smi 验证。
• 主机 Docker：Docker 引擎 + nvidia-container-toolkit。如果没有该工具包，下面工作流的第 2 步中 docker run --gpus all 会失败。
• 磁盘：需要约 50 GB 可用空间来存放构建的 kermt 镜像（docker image inspect --format '{{.Size}}' 报告约 44 GB；docker images 的 Size 列可能显示约 100 GB，因为它会计入可在多个镜像间共享并去重的 buildx 证明层）。请预留约 50 GB 的独占磁盘空间；如果还要保留构建缓存，请额外留出充足空间。
• 内存：构建过程中，conda 环境求解阶段的内存峰值约为 4 GB RAM。
• 此技能本身不会运行训练或推理工作负载；各工作流的硬件要求（VRAM、GPU 数量）在相应的 kermt-<workflow> 技能中说明。

何时调用

• 用户明确提出请求（/kermt-setup、“设置 kermt”、“构建 kermt 镜像”等）。
• 或者，其他 kermt-* 技能检测到镜像不存在并将请求转交至此。（大多数其他技能都会自行调用 kermt_ensure_image，所以通常只有在首次设置、调试或强制重新构建时才需要使用此技能。）

输入

此技能没有必需参数。可选覆盖项（调用前通过环境变量设置，或在用户的 shell 中设置）：

• KERMT_IMAGE — 要构建或验证的镜像标签（默认：kermt:latest）。
• KERMT_REPO — kermt 仓库检出内容在主机上的路径（默认：根据脚本位置自动推导）。

如果用户未指定仓库路径，且当前工作目录不在 kermt 仓库克隆目录中，请先询问仓库路径。

工作流

所有工作都通过 agent/scripts/kermt_container.sh 进行。无需先导入脚本即可直接调用其子命令——这是使用技能时的首选方式。

设 HELPER=$KERMT_REPO/agent/scripts/kermt_container.sh。

1. 确认已安装 docker，且能够连接守护进程。

   $HELPER check_docker
   

   退出码为 0 → 继续。非 0 → 向用户说明错误（通常是“docker 不在 PATH 中”或“无法连接守护进程”）；不要尝试步骤 2。

2. 确认 GPU 直通正常。

   $HELPER check_gpu
   

   此步骤会运行 docker run --rm --gpus all nvidia/cuda:12.6.3-base-ubuntu22.04 nvidia-smi 并检查退出状态。非 0 → 告知用户在主机上安装 nvidia-container-toolkit，并确认主机能够检测到支持 CUDA 的 NVIDIA GPU （在主机上运行 nvidia-smi 也应正常）。到此停止；没有 GPU 直通时，kermt 镜像可以构建，但无法运行任何工作流。

3. 构建或验证 kermt 镜像。

   $HELPER ensure_image
   

   如果镜像已存在，此命令会立即返回。否则会从 $KERMT_REPO/Dockerfile 构建。 调用前先提醒用户：在普通工作站上，首次构建需要约 10–20 分钟，并会将构建日志实时输出到控制台。不要在后台运行——用户需要看到进度，且必须立即显示任何构建失败。

4. **在容器内进行 GPU 烟雾测试。**将整个 python 命令作为单个字符串引用——该辅助脚本会通过 bash -c "$*" 传递参数，因此未加引号的多词命令会被重新解析，嵌入的引号也会被合并。

   $HELPER run -- 'python -c "import torch; print(\"cuda_available:\", torch.cuda.is_available()); print(\"device_count:\", torch.cuda.device_count())"'
   

   预期输出：cuda_available: True，且 device_count 为正数。如果步骤 2 通过，但 cuda_available 为 False，说明容器的 CUDA 配置有问题——向用户报告完整输出并停止；不要宣称环境已就绪。

5. **向用户总结。**报告：

   • 镜像标签和 ID（docker image inspect $KERMT_IMAGE --format '{{.Id}}'）。
   • 镜像大小（docker image inspect $KERMT_IMAGE --format '{{.Size}}'）。
   • 容器内检测到的 GPU 数量。
   • “就绪”——用户现在可以调用其他 kermt-* 技能。

硬性规则

• 不要拉取或推送 docker 镜像。kermt 镜像仅在本地构建。
• 未经用户明确确认，不要自动删除或清理较旧的 kermt:* 标签——用户可能正在另一个容器中运行依赖特定标签的微调或预训练任务。
• 不要修改主机的 docker 守护进程配置、daemon.json 或用户组成员身份。
• 作为此技能的一部分，不要修改 Dockerfile 或 environment.yml。如果构建因 Dockerfile 问题而失败，请报告错误并停止；由用户决定是否编辑。
• 镜像已存在时，不要重建镜像（即不要向 ensure_image 传递 --no-cache 或 --pull 标志），除非用户明确要求强制重建。

强制重建

如果用户明确要求重建（例如修改 Dockerfile 或 environment.yml 后），最简洁的做法是先移除旧镜像，然后重新运行 ensure_image：

docker image rm $KERMT_IMAGE
$HELPER ensure_image

运行 docker image rm 前请先征得用户确认。