SlurmX 使用说明文档¶

Note

该项目和文档由Gemini CLI生成，如需查看更新请访问项目地址

SlurmX 是一套为 Slurm 集群设计的命令行增强工具集，旨在简化繁琐的原生命令（如 sbatch, sinfo, squeue），提供更现代化的终端交互体验。它不仅简化了命令参数，还提供了颜色高亮、智能单位换算和高级批量处理功能。

本文档将详细介绍各模块功能，并对比 Slurm 原生命令，帮助用户在提高效率的同时理解底层原理。

1. 安装 (Installation)¶

依赖环境¶

Python 3.7+
Slurm 客户端环境

安装步骤¶

在项目根目录下执行以下命令进行安装：

# 开发模式安装 (推荐，便于后续更新)
pip install -e .

# 或者直接安装
pip install .

安装完成后，终端即可直接使用 xnodes, xsub 等命令。

2. 模块一：xnodes (节点资源透视)¶

定位：替代 sinfo，提供以“节点”为维度的资源全景视图。自动计算 CPU/内存/GPU 的利用率和负载。

核心功能与原生对比¶

功能	SlurmX 命令	原生 Slurm 命令 (近似)
查看节点概览	`xnodes`	`sinfo -N -l` (信息更杂乱)
只看 GPU 分区	`xnodes -p gpu`	`sinfo -p gpu -N`
找空闲节点	`xnodes --state idle`	`sinfo --state=idle`
按负载排序	`xnodes --sort load`	(原生不支持直接排序输出)

输出列说明¶

Node: 节点名称。
Partitions: 所属分区（队列）。
State: 状态（IDLE=空闲, MIXED=部分占用, ALLOC=占满, DOWN=故障）。
Jobs: 该节点上正在运行的任务数。
CPU: 已分配核数 / 总核数。
Mem: 已分配内存 / 总内存 (自动转换为 GB)。
GPU: 已用卡数 / 总卡数 (显示型号)。
Load: 系统负载 (Load Average)。

3. 模块二：xsub (任务提交助手)¶

定位：替代 sbatch 和 srun，无需手写复杂的 #SBATCH 脚本。

核心参数¶

参数	说明	对应 Slurm 参数
`-p <name>`	指定分区	`--partition=<name>`
`-t <num>`	单任务 CPU 线程数	`--cpus-per-task=<num>`
`-m <size>`	内存大小 (如 16G)	`--mem=<size>`
`-g <res>`	通用资源 (如 gpu:1)	`--gres=<res>`
`-w <time>`	运行时间 (如 1-00:00:00)	`--time=<time>`
`-n <num>`	任务数 (默认1，不常用)	`--ntasks=<num>`
`--save`	保存生成的脚本到本地	(无，原生只会生成临时文件或需手动写)
`--dry-run`	仅打印脚本不提交	(无)

使用场景示例¶

场景 A：交互式调试 (Interactive)¶

申请资源并立即登录节点调试代码。

# 申请 1 个 GPU，4 线程，16G 内存，进入交互式终端
xsub -I -p gpu -g gpu:1 -t 4 -m 16G

原生对应：

srun --pty -p gpu --gres=gpu:1 --cpus-per-task=4 --mem=16G /bin/bash

场景 B：提交单行命令并保存脚本¶

不想写脚本，只想跑个简单的 Python 任务，并保留记录。

xsub -c "python train.py" -J train_v1 -p gpu -t 4 --save

这将生成 train_v1.slurm 文件并自动提交。

场景 C：高级批量处理 (Batch)¶

痛点：有 100 对生信数据（_R1.fq, _R2.fq）需要跑比对，原生需要写复杂的 Shell 循环。方案：使用 -b 通配符配合**高级占位符**。

支持的占位符： * {}：完整文件路径 (例如 data/sample_R1.fq)。 * {%}：仅文件名 (Basename, 例如 sample_R1.fq)。 * {:abs}：绝对路径 (例如 /home/user/data/sample_R1.fq)。 * {.}：去扩展名路径 (例如 data/sample_R1)。 * {^.ext}：去除特定后缀 (例如 {^_R1.fq} 将 sample_R1.fq 变为 sample)。 * {old:new}：字符串替换 (例如 {_R1:_R2} 将 S1_R1.fq 变为 S1_R2.fq)。

示例：批量比对 R1 和 R2

xsub -b "*_R1.fq" -c "bwa mem ref.fa {} {_R1:_R2} > {.}.sam" -t 8 -w 02:00:00

原生对应： 需要编写 Shell for 循环并结合 sed 或 basename 处理文件名，再调用 sbatch。

场景 D：使用自定义模板 (Template)¶

如果你有一个包含复杂环境配置的 base.slurm 模板：

xsub --template base.slurm -p gpu -c "python main.py"

xsub 会将申请的资源参数自动注入到模板顶部并提交。

4. 模块三：xjob (任务管理与监控)¶

定位：替代 squeue、scontrol 和 scancel，提供一站式任务管理。

核心功能与原生对比¶

功能	SlurmX 命令	原生 Slurm 命令
查看我的任务	`xjob` (或 `xjob --me`)	`squeue --me`
查看指定用户	`xjob -u <user>`	`squeue -u <user>`
查看所有任务	`xjob -a`	`squeue`
查看日志 (Peek)	`xjob peek <id>`	(需手动找 Log 路径) `tail -f slurm-xxx.out`
查看详情	`xjob show <id>`	`scontrol show job <id>`
取消任务	`xjob cancel <id>`	`scancel <id>`
清理排队任务	`xjob clean`	`squeue -u $USER --state=PD -h -o %i \| xargs scancel`
用户资源统计	`xjob stats`	(无直接命令，需复杂组合统计)

列表增强说明¶

User: 自动解析用户 ID 为用户名。
Time:
- 运行中：显示 已用时间 / 时间限制。
- 排队中：显示 已等待时间 / 时间限制。
CPUs/Mem: 显示该任务实际申请的资源量。

统计概览 (Stats)¶

查看集群中各用户的资源占用排行：

xjob stats

输出包含： * Running/Pending 任务数 * 占用的总 CPU 核数 * 占用的总内存 (自动换算单位)

5. 模块四：xhist (历史统计)¶

定位：替代 sacct，关注任务效率分析。

核心功能与原生对比¶

功能	SlurmX 命令	原生 Slurm 命令
查看近期概况	`xhist --days 3`	`sacct -S ...` (参数繁琐)
查看所有用户	`xhist --days 7 -a`	`sacct -a -S ...`

效率分析指标¶

xhist 会自动计算并用颜色标记效率指标，帮助优化资源申请：

Core Hours: 总消耗的核时数 (AllocCPUS * ElapsedHours)。
Avg Load (Cores): 平均负载 (Total Core Hours / Total Hours)。代表这段时间内，平均每时每刻有多少个 CPU 核心被占用。
Avg Mem Eff: 平均内存利用率 (MaxRSS / ReqMem)。
Avg CPU Eff: 平均 CPU 利用率 (TotalCPU / (Elapsed * AllocCPUS))。

附录：Mock 模式 (开发与测试)¶

如果你在没有 Slurm 的环境（如本地 Windows/Mac）体验本工具，可以开启 Mock 模式，工具将使用模拟数据：

Windows (PowerShell):

$env:SLURMX_MOCK="1"
xnodes

Linux/Mac:

export SLURMX_MOCK=1
xnodes

本文阅读量次
本站总访问量次

Authors: Wind