hpc-runtime-doctor

HPC 运行时诊断工具

目标

将集群症状转化为资源布局诊断、环境检查清单和安全重试方案。

要求

• Python 3.10+
• 无外部依赖
• 支持 Linux、macOS 和 Windows

收集的输入

输入	描述	示例
调度器	SLURM、PBS、LSF、本地	slurm
节点/任务/线程	运行时布局	2 nodes, 128 tasks, 2 threads
GPU	通过 --gpus 指定的总 GPU 数（整个作业），或通过 --gpus-per-node 指定的每节点 GPU 数	--gpus 4 或 --gpus-per-node 1
症状	观察到的故障	oom,killed,slow-gpu
MPI/OpenMP/GPU 使用情况	并行模式	mpi+openmp+gpu
墙钟时间	请求的运行时间	12:00:00
临时存储	是否使用临时存储	true

决策指引

• 更改物理设置前，先检查资源布局。
• 调试求解器行为前，确认模块/编译器/MPI/CUDA 一致。
• 将重启文件缺失和临时存储清理视为工作流故障，而非物理问题。
• 对于 GPU 作业，确认可执行文件是使用请求的加速器后端构建的。

脚本输出

scripts/hpc_runtime_doctor.py 会生成：

• resource_layout（包含 tasks_per_node、total_cpus、总 gpus 数和 gpus_per_node）
• diagnoses
• environment_checks
• retry_plan
• scheduler_notes
• warnings（布局标记，例如每个 GPU 的 rank 过量、OpenMP/线程不匹配，以及任务分配不均）

在默认的非 JSON 模式下，脚本还会打印资源布局摘要、所有 warnings、环境检查和重试方案，因此最具可操作性的事项绝不会被隐藏。

工作流

--gpus 表示 总 GPU 数（整个作业）。已知每节点的分配量时，请使用 --gpus-per-node（对应 SLURM --gres=gpu:N 语义）；此时总 GPU 数为 gpus_per_node * nodes，且该值会覆盖 --gpus。

python3 skills/hpc-deployment/hpc-runtime-doctor/scripts/hpc_runtime_doctor.py \
  --scheduler slurm \
  --nodes 2 \
  --tasks 128 \
  --cpus-per-task 2 \
  --gpus 4 \
  --symptoms oom,slow-gpu \
  --uses-mpi \
  --uses-openmp \
  --uses-gpu \
  --json

上述示例将 128 个 rank 分配到 4 个 GPU（每个 GPU 32 个 rank），因此 warnings 列表会显示 Many MPI ranks per GPU (32.0 ranks/GPU) may reduce GPU efficiency.。每 GPU rank 数检查使用总 rank 数除以总 GPU 数，因此在多节点作业中也能正确触发（阈值为每 GPU 16 个 rank）。

错误处理

无效的资源计数会以退出代码 2 终止。未知症状会作为自定义条目保留，供人工审核。

限制

此工具不会查询正在运行的调度器。它根据提交的布局和症状进行诊断。

验证清单

• 记录脚本的 resource_layout 块，并确认 tasks_per_node 是整数（不是小数），且 total_cpus 等于 tasks * cpus_per_task；如果 tasks_per_node 是小数，应在重试前处理任务分配不均警告。
• 对于 GPU 作业，记录解析后的总 gpus 数（以及设置时的 gpus_per_node），并计算每 GPU rank 数 = tasks / gpus，确认其不超过每 GPU 16 个 rank 的阈值，或已审慎接受由此产生的 Many MPI ranks per GPU 警告。
• 检查 warnings 列表中的每一项（使用 cpus_per_task=1 的 OpenMP、已请求 GPU 但 GPU 数为零、tasks < nodes、任务分配不均、重 I/O 作业使用临时存储），逐项解决或说明理由，不要忽略。
• 将 environment_checks 项落实为实际产物：收集模块列表、可执行文件路径/版本、MPI 启动器与库的匹配情况、加速器构建标志（CUDA/Kokkos/OpenMP）以及调度器 stdout/stderr。
• 将每个观察到的症状对应到一条 diagnoses 条目，并确认没有症状在 custom 类别中被搁置（每个 custom 项都已收集 stderr/stdout/模块列表/命令行，供人工审核）。
• 按照 retry_plan 操作：重新运行最小复现用例，只更改一个资源变量，启用重启/检查点，并将调度器脚本及环境快照与结果一并保存。

常见陷阱与自我开脱

看似省事的做法	为什么不对／应该怎么做
“运行时没有崩溃，所以布局没问题。”	运行完成不代表结果正确。请检查 warnings 列表和 resource_layout——资源超额分配、放置不均或 GPU 空闲，都可能在没有崩溃的情况下悄悄拖慢运行或导致结果错误。
“每个节点上的进程数都不超过 GPU 数量，所以没有资源超额分配。”	资源超额分配看的是总进程数与总 GPU 数量，而不是每个节点上的进程数。脚本会计算 tasks / gpus；多节点作业可能掩盖较高的进程数/GPU 比值，只有单位一致的检查才能发现这一点。
“我传入了 --gpus，所以每个节点的 GPU 数量无关紧要。”	--gpus 是整个作业的 GPU 总数。如果集群按节点分配 GPU，请使用 --gpus-per-node（SLURM --gres=gpu:N）；它会覆盖 --gpus，总数变为 gpus_per_node * nodes。混淆两者会导致进程数/GPU 比值报告错误。
“作业被杀掉了，所以这是物理模型／求解器的 bug。”	killed／oom／timeout 属于调度器和资源类别，不是物理模型问题。在调整模拟参数之前，请先根据 stdout/stderr 检查运行时限、内存限制和抢占情况。
“规则里没有提到这种未知症状，所以可以忽略。”	未知症状会被诊断为 custom，不会被直接忽略。请收集调度器的 stderr/stdout、模块列表和命令行，供人工审核——没有报错不等于万事无忧。
“同时调整进程数、线程数和构建配置，能更快修好问题。”	一次更改多个变量会让故障无法诊断。retry_plan 要求在能复现问题的最小用例上一次只更改一个变量。

安全性

输入验证

• 输入仅包含标量 CLI 值和布尔值；没有自由格式代码路径。
• 资源数量（--nodes、--tasks、--cpus-per-task、--gpus、--gpus-per-node） 会验证为整数（拒绝布尔值），必须为非负有限值， 且上限为 1,000,000。--nodes、--tasks 和 --cpus-per-task 还必须 至少为 1。超出范围、非整数或为零的值会以代码 2 退出。
• --symptoms 字符串最多包含 64 个以逗号分隔的条目，每个条目最多 64 个字符； --walltime 最多 32 个字符。输入超长时会以代码 2 退出。
• 症状会被拆分、去除首尾空格并转换为小写。未知症状不会被拒绝，而会保留为 custom 诊断，供人工审核。
• --scheduler 接受任意字符串，不会根据允许列表进行检查； 该字符串只会在资源布局中原样返回。

文件访问

• 脚本不会读取或写入任何文件。所有输入均来自 CLI 参数，输出写入 stdout （使用 --json 时输出缩进的 JSON，否则输出人类可读的摘要）；错误写入 stderr。
• 由于不接受或打开任何路径，因此不存在文件系统遍历风险，也无需考虑路径沙箱问题。

工具限制

• allowed-tools 为 Read, Bash, Write, Grep, Glob。
• Bash 仅用于运行捆绑的 scripts/hpc_runtime_doctor.py。
• Read、Grep 和 Glob 用于检查该技能自身的文件，以及用户指定的任何日志或 作业提交脚本；用户提出要求时，使用 Write 记录诊断说明或重试计划。

安全措施

• 不使用 eval、exec、os.system 或 subprocess；脚本不会启动调度器 或任何外部进程，也不会检查环境变量。
• 参数解析由 argparse 处理，并以 JSON 输出机器可读结果。
• 通过资源数量上限（1,000,000）、症状上限 （64 个条目 × 64 个字符）和运行时限上限（32 个字符）来限制 DoS 风险。

参考资料

• 调度器和运行时诊断模式请参阅 references/hpc_runtime_patterns.md。

版本历史

• 1.1.3：新增验证清单（基于证据的项目，与 resource_layout、warnings、rank/GPU、environment_checks、diagnoses 和 retry_plan 相关）以及常见陷阱与合理化说辞表。
• 1.1.1：区分性评估——现在每个案例都会通过确定性的 script_checks 固定脚本的特定输出 （精确的每 GPU rank 警告、诊断类别、资源布局字段）。
• 1.1.0：统一的每 GPU rank 警告（总 rank 数 / 总 GPU 数）、新增 --gpus-per-node 参数、整数型 tasks_per_node 并带有不均匀放置警告、 完整的易读（非 JSON）输出，以及对资源计数、症状和墙钟时间的输入上限。
• 1.0.0：初始版 HPC 运行时诊断技能。