srt-slurm：用 Slurm 编排多节点 GPU 推理任务的实践指南

在 GPU 推理部署场景里，一个常见问题是：模型本身能在单机上跑通，但进入多节点、多卡、批量化的生产环境后，任务怎么排队、怎么分配 GPU、怎么重试失败、怎么汇总结果，很快变成比推理本身更耗时的工程问题。NVIDIA 开源的 srt-slurm 正是围绕这个痛点出现的方案，它把 Slurm 的资源调度能力和推理部署流程结合起来，让推理任务可以像普通 HPC 作业一样被编排、提交和追踪。

这篇文章会从 srt-slurm 解决的问题出发，先解释它和 NVIDIA NIM、Slurm 之间的关系，再给出环境准备、最小部署案例、关键设计点和常见问题排查路径。内容面向已经能跑通单卡推理、但想把推理任务推向多节点集群的开发者，也适合正在评估推理调度方案的平台工程师。

1. 先理解 srt-slurm 在推理部署链路中的位置

1.1 它不是一个推理引擎，而是一个编排层

很多人在第一次听到 srt-slurm 时，会误以为它是一个新的推理框架。实际上，srt-slurm 的定位更接近编排调度层，它不负责模型推理本身，而是负责管理推理任务如何被提交、调度、监测和回收。

在推理部署完整链路中，各层职责大致如下：

srt-slurm 位于任务调度和业务层之间。它要解决的是：当推理请求变多、GPU 资源需要共享时，谁来决定任务先跑后跑，谁负责记录状态，谁在任务失败后重新拉起。

1.2 srt-slurm 与 Slurm 调度器的边界

Slurm 本身已经提供了作业提交、节点分配、资源限制和队列管理能力。srt-slurm 的价值不是替换这些能力，而是把 Slurm 的通用作业模型映射到"推理部署"这个具体场景。

例如，Slurm 的作业通常由用户通过sbatch手动提交，作业内容是一个批处理脚本。而 srt-slurm 的工作方式是先接收推理部署请求，再根据请求生成合适的 Slurm 作业，跟进作业执行状态，最终将结果返回给上层。

两者的边界可以这样理解：

• Slurm 关心的是"作业能不能在资源充足时被调度起来"。
• srt-slurm 关心的是"一个推理请求是否成功、失败、重试，以及如何被上层感知"。

1.3 与 NVIDIA NIM 的关系

NVIDIA NIM 是 NVIDIA 提供的推理微服务容器方案，它把模型部署成可调用的 API 服务。实际项目中 srt-slurm 常与 NIM 搭配使用：srt-slurm 负责在 Slurm 集群上编排 NIM 服务或 NIM 推理任务的启动、扩缩与回收，NIM 负责对外提供推理能力。

如果暂时没有使用 NIM，也可以用 TensorRT-LLM 或 vLLM 的离线推理脚本来承接任务。srt-slurm 的编排逻辑并不绑定具体推理引擎，只需要推理脚本能接受命令行参数、产生输出文件即可。

1.4 适合使用 srt-slurm 的场景

在真实项目里，不是所有推理场景都需要 srt-slurm。下面这张表可以帮助判断：

一句话概括：当推理任务需要按批处理方式在共享 GPU 集群上运行，并且需要追踪任务状态时，srt-slurm 的价值最明显。

2. 编排推理部署的核心机制：任务如何从一个请求变成一组 Slurm 作业

2.1 推理请求到子任务拆分

srt-slurm 处理一个推理部署请求时，并不是把整个请求直接丢给某一块 GPU。它首先会把请求拆分成更适合 Slurm 调度的子任务。拆分维度通常有两种。

第一种是按输入数据拆分。比如一个批处理请求包含 1000 段文本，需要生成摘要，可以先按shard_size切分为 10 个子任务，每个子任务负责 100 段文本。第二种是按资源并行拆分。比如一个模型太大放不单卡，需要做张量并行，那么一个推理任务可能要申请 2 卡或 4 卡，此时子任务就是"同一模型在特定并行策略下的运行实例"。

拆分的核心目的是提高资源利用率和容错率。如果把 1000 段文本放到一个 Slurm 作业里跑，一旦某个文本导致显存溢出或进程崩溃，整个作业都要重来。拆分成多个子任务后，失败影响被限制在单个分片内。

2.2 任务生命周期：提交到 Slurm 后如何被追踪

一个典型的 srt-slurm 任务流程如下：

1. 编排服务接收到推理请求。
2. 服务生成一次推理任务的唯一标识，例如infer_20250101_153000。
3. 根据请求内容和集群资源情况，拆分子任务。
4. 每个子任务生成一个 Slurm 提交脚本或直接调用sbatch命令。
5. 记录每个子任务的 Slurm Job ID 和输入输出路径。
6. 通过squeue、sacct或回调机制检查任务状态。
7. 任务完成后读取结果，供上层合并或返回给用户。

这个流程里的关键点是任务日志和结果回收。Slurm 作业执行在不同节点上，如果节点之间没有共享存储，编排服务无法在控制节点上读取结果文件。这在实际部署中是最容易忽略的问题。

2.3 学习环境与生产环境的差异

学习环境可以用一个控制节点加一个计算节点来模拟，甚至在单机上直接测试脚本逻辑。真正进入生产环境后，需要注意组件会明显增多。

学习环境的最小组合：

• 一台或多台安装 NVIDIA GPU 的服务器。
• Slurm 控制节点与计算节点配置完成。
• Python 虚拟环境。
• 一套简单的输入输出目录。

这种环境下，srt-slurm 的编排逻辑可以简化到"提交任务、等待结果、输出日志"三个步骤。只要理解闭环即可。

生产环境的组合要复杂得多。除了 Slurm 集群，还需要日志采集、监控告警、结果存储、模型仓库、权限管理和重试机制。这些组件不会自动随 srt-slurm 安装，需要平台侧自行补齐。

2.4 Slurm 关键参数与 srt-slurm 的对应关系

srt-slurm 的配置最终要落到 Slurm 作业参数上。理解下面这张表，可以帮助快速定位配置错误。

实际使用时，不一定要把所有参数都暴露给用户。更稳妥的做法是把 srt-slurm 封装成一套服务或 CLI，让用户只提交"推理请求"，服务层负责生成 Slurm 参数。

3. 环境准备：先确认 GPU、驱动、容器运行时和 Slurm 四层状态

srt-slurm 对运行环境有一定要求。开始部署前，先把四层环境检查清楚，否则后面出现的错误很容易被误判为编排问题。

3.1 第一层：GPU 和驱动

先确认节点上有哪些 GPU，以及驱动是否正常：

nvidia-smi

输出中应包含 GPU 型号、显存、驱动版本、CUDA 版本。常见的异常输出有：

• NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver：驱动未正确安装或内核模块未加载。
• 没有输出任何 GPU：节点上可能没有 GPU，或者驱动安装后没有重启。

如果系统中曾经安装过 NVIDIA 驱动，但升级内核后驱动失效，需要重新安装或使用dkms管理驱动模块。这里不要只依赖nvidia-smi，还要检查驱动模块：

lsmod | grep nvidia

没有nvidia、nvidia_uvm等模块时，驱动基本没有加载。

3.2 第二层：NVIDIA Container Toolkit

容器中的推理任务需要访问 GPU，因此每个计算节点都要安装 NVIDIA Container Toolkit。检查方式：

nvidia-container-cli --version

如果没有安装，容器内调用nvidia-smi时会报could not select device driver，或者运行时找不到 GPU。安装后，需要确认容器运行时配置生效：

docker info | grep -i runtime

输出中应包含nvidia运行时。如果是 Kubernetes 或 Slurm + Singularity 环境，还要确认对应容器引擎能识别 NVIDIA 运行时。

3.3 第三层：Slurm 集群

srt-slurm 依赖 Slurm 提供任务调度。至少需要一个控制节点和一个计算节点。检查集群状态：

sinfo

正常输出会显示分区、节点状态、可用资源。如果输出为空或节点状态为down、drain，需要先处理节点健康问题，再进行编排测试。

计算节点是否使用容器由集群决定。常见组合是：

• Slurm + Singularity/Apptainer：适合 HPC 场景。
• Slurm + Docker：适合已有 Docker 镜像和镜像仓库的团队。
• Slurm + Pyxis：适合在 Slurm 任务中直接使用 Docker 镜像。

3.4 第四层：Python 环境和依赖

srt-slurm 是 Python 项目。建议使用 Python 3.10 或更高版本，并使用虚拟环境隔离依赖。

python3 -m venv venv source venv/bin/activate pip install --upgrade pip

安装 srt-slurm 时，先确认项目要求的版本依赖。如果原始项目文档没有明确版本，落地前要先确认依赖版本，避免直接安装最新版导致兼容问题。

4. 最小可运行案例：用 srt-slurm 编排一个两节点推理任务

下面用一个最小案例展示 srt-slurm 的工作方式。案例目标：把一个大模型输入拆分到多个 GPU 节点并行推理，再汇总结果。这个案例能体现"编排"的核心价值，也能在真实集群上快速验证。

4.1 准备推理应用

先准备一个可被 Slurm 调用的推理脚本。这里用一个模拟模型加载的脚本，实际项目中替换为真实的模型推理代码。

import argparse import json import os import time def init_model(): # 实际项目在这里加载模型，例如从模型仓库拉取并加载权重 print("model loaded", flush=True) def infer(text): # 实际项目执行真正的推理计算 time.sleep(2) return {"result": f"processed: {text}", "gpu": os.environ.get("CUDA_VISIBLE_DEVICES", "unknown")} if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--input", required=True) parser.add_argument("--output", required=True) args = parser.parse_args() init_model() with open(args.input, "r", encoding="utf-8") as f: items = json.load(f) outputs = [] for item in items["texts"]: outputs.append(infer(item)) with open(args.output, "w", encoding="utf-8") as f: json.dump(outputs, f, ensure_ascii=False, indent=2) print("job finished", flush=True)

脚本要支持命令行参数，这是 Slurm 调用程序时最直接的数据传递方式。flush=True用来保证日志能被及时采集。

4.2 准备输入数据

创建一个输入文件，模拟一批待推理文本：

{ "texts": [ "text-a", "text-b", "text-c", "text-d" ] }

实际项目中，这个文件可以是数据分片、用户请求队列或上游任务产出的中间结果。为了演示数据拆分，再把输入拆成两个分片：

mkdir -p data python3 -c " import json data = {'texts': ['text-a', 'text-b', 'text-c', 'text-d']} half = len(data['texts']) // 2 for i, part in enumerate([data['texts'][:half], data['texts'][half:]]): with open(f'data/input_{i}.json', 'w') as f: json.dump({'texts': part}, f) "

4.3 编写 Slurm 提交脚本

编写一个能够被sbatch提交的脚本：

#!/bin/bash #SBATCH --job-name=srt-infer-demo #SBATCH --output=logs/slurm-%j.out #SBATCH --error=logs/slurm-%j.err #SBATCH --nodes=1 #SBATCH --ntasks-per-node=1 #SBATCH --gpus-per-node=1 #SBATCH --time=00:10:00 source venv/bin/activate INPUT_FILE=$1 OUTPUT_FILE=$2 echo "start task: $INPUT_FILE" srun python infer.py --input "$INPUT_FILE" --output "$OUTPUT_FILE" echo "finish task: $INPUT_FILE"

这里把输入文件和输出文件作为命令行参数传给脚本。在真实编排中，这两个路径由 srt-slurm 的服务端生成，并写入任务元数据。

4.4 模拟 srt-slurm 的编排逻辑

srt-slurm 的编排逻辑可以简化成三个步骤：

1. 接收一个大的推理请求。
2. 将输入拆分为多个子任务。
3. 为每个子任务申请 Slurm 资源，并收集结果。

下面用 Python 代码模拟这个流程：

import os import subprocess import time import json def submit_slurm_job(input_path, output_path, job_index): cmd = ["sbatch", "submit_infer.sh", input_path, output_path] result = subprocess.run(cmd, capture_output=True, text=True) print(result.stdout.strip()) if result.returncode != 0: print(result.stderr) raise RuntimeError(f"submit job {job_index} failed") def wait_and_check(expected_outputs, timeout=300): deadline = time.time() + timeout while time.time() < deadline: done = 0 for out_path in expected_outputs: if os.path.exists(out_path): done += 1 if done == len(expected_outputs): print("all jobs done") return time.sleep(5) raise TimeoutError("jobs not finished in timeout") def main(): os.makedirs("logs", exist_ok=True) os.makedirs("outputs", exist_ok=True) job_scripts = [ ("data/input_0.json", "outputs/result_0.json"), ("data/input_1.json", "outputs/result_1.json"), ] expected_outputs = [] for idx, (input_path, output_path) in enumerate(job_scripts): submit_slurm_job(input_path, output_path, idx) expected_outputs.append(output_path) wait_and_check(expected_outputs) all_results = [] for expected in expected_outputs: with open(expected, "r", encoding="utf-8") as f: all_results.extend(json.load(f)) with open("outputs/final_result.json", "w", encoding="utf-8") as f: json.dump(all_results, f, ensure_ascii=False, indent=2) print("final result saved") if __name__ == "__main__": main()

这段代码展示了编排的最小闭环：提交任务、等待完成、汇总结果。实际 srt-slurm 会在这里加入错误重试、超时处理、资源限制和任务状态管理，但核心结构一致。

4.5 运行验证与预期结果

在集群上执行：

python run_workflow.py

预期现象：

• 控制台输出两条Submitted batch job 101、Submitted batch job 102类似的信息。
• 等待约 10 秒后输出all jobs done。
• outputs/final_result.json中合并了全部推理结果。

检查最终结果：

cat outputs/final_result.json

输出应包含每个分片的处理结果，并带有各自的CUDA_VISIBLE_DEVICES信息，说明任务确实被调度到了对应 GPU。这个结果证明编排链路已经打通。

5. 关键设计点：把 srt-slurm 接入真实推理服务时要注意什么

通过最小案例后，需要把编排逻辑从 demo 形式往真实服务迁移。下面几个设计点直接决定迁移成本。

5.1 任务元数据要保存完整

每个子任务至少需要保存以下信息：

状态变化是编排系统最容易出错的地方。不要只把状态存在内存里，落库或落文件后，控制节点重启时才能恢复任务。

5.2 超时和重试要有明确策略

推理任务可能因为排队、加载模型、长文本生成等原因运行很久。设置超时时要区分两层：

• Slurm 超时：通过--time限制任务运行上限，超时后 Slurm 会终止作业。
• 编排层超时：任务已经提交但长时间没有产出结果时，编排层要能检测并重试或告警。

重试策略推荐：

• 同一个输入最多重试 3 次。
• 重试间隔按指数退避，例如 10 秒、30 秒、90 秒。
• 每次重试要记录原因，否则排查时看不到任务为什么失败。

5.3 结果收集要兼容部分失败

多节点推理最麻烦的场景不是全部失败，而是部分成功、部分失败。此时编排系统应该：

• 保留成功的分片结果。
• 对失败分片单独标记。
• 允许用户只重跑失败分片，而不是整个大任务重新提交。

实现时可以在结果目录中增加_SUCCESS标记文件，汇总阶段只读取带有该标记的分片。

5.4 模型加载和显存占用需要单独规划

大模型推理时，模型权重加载和显存占用经常变化。srt-slurm 在编排任务时通常不会自动判断显存是否够用，需要在使用前明确以下参数：

如果模型权重一张卡放不下，需要先确定并行策略，再设置 srt-slurm 的 GPU 申请参数。

6. 常见问题排查：从现象定位到根因

srt-slurm 排错和普通推理系统排错略有不同。很多问题表面上出现在编排层，实际根因在 Slurm、驱动、容器或数据路径里。建议按下面的链路排查。

6.1 任务提交失败

现象：

sbatch: error: Batch job submission failed: Invalid account or account/partition combination specified

可能原因和检查方式：

• 用户没有指定正确的 Slurm Account 或分区。
• 检查方式：执行sacctmgr -p show assoc user=$USER查看用户关联的 Account。
• 处理方式：在提交脚本中显式写入#SBATCH --account=xxx或#SBATCH --partition=xxx。

另一种常见原因是分区被关闭或满负荷。检查sinfo中分区状态是否为down、drain。资源不够时 Slurm 会保留作业而不是拒绝提交，这与"提交失败"现象不同，需要区分。

6.2 任务一直 PENDING

现象：任务提交成功，但始终处于PENDING状态，状态为Resources。

可能原因：

• 节点资源不足。
• 节点处于drain或down。
• 作业请求超过节点实际资源，例如节点只有 4 卡，但请求了 8 卡。
• 账户或分区的 QoS 限制。

检查方式：

squeue -u $USER -o "%.18i %.20P %.8j %.8u %.12M %.12L %.20R"

重点看NODELIST(REASON)列。Resources表示资源不足，Priority表示排队优先级不够。再执行sinfo确认节点真实可用资源。

6.3 容器内找不到 GPU

现象：Slurm 任务能启动，但 Python 脚本中nvidia-smi报错或 CUDA 报no kernel image is available。

排查顺序：

1. 先确认节点宿主机nvidia-smi正常。
2. 再确认容器引擎配置了 NVIDIA runtime。
3. 再在容器内执行nvidia-smi验证设备映射。
4. 最后确认容器镜像中的 CUDA 版本和宿主机驱动版本兼容。

如果任务中设置了CUDA_VISIBLE_DEVICES，还要检查这个环境变量是否被错误覆盖。

6.4 输出文件缺失或内容为空

现象：任务显示COMPLETED，但输出目录没有结果文件。

常见原因：

• 脚本中输出路径写死为当前工作目录，而 Slurm 的工作目录和编排服务预期目录不一致。
• 任务被调度到其他节点，而该节点与编排服务没有共享存储。
• 脚本在写出结果前异常退出，但退出码被误判为成功。

检查方式：

sacct -j 101 --format=JobID,JobName,State,ExitCode,Elapsed,End

重点看State是否为COMPLETED，End时间是否合理。同时检查两个节点是否有共享文件系统。没有共享存储时，结果文件只会存在计算节点本地，其他节点无法读取。

6.5 阶段间依赖顺序错乱

如果编排中包含"前序任务完成后才能执行后续任务"，但后续任务提前启动，通常是--dependency使用错误。

常见错误是写了--dependency=afterok:101,102，但 Slurm 要求作业号必须已经存在。正确顺序是：先提交前序任务，拿到作业号后，再提交后续任务。

JOB_ID=$(sbatch --parsable first.sh) sbatch --dependency=afterok:$JOB_ID second.sh

这里的关键是sbatch --parsable会直接输出作业号，便于在脚本中串联依赖。

6.6 排查优先级总结

遇到问题先按顺序检查，避免跳跃定位：

1. 输入数据路径是否存在、是否有读取权限。
2. 计算节点与编排节点是否有共享存储。
3. Slurm 集群状态和任务状态是否正常。
4. GPU 驱动、容器运行时是否正常。
5. Python 依赖是否在任务执行环境中可用。
6. 日志中是否出现明确异常关键字。

按这个顺序，大多数问题可以在几分钟内缩小到具体环节。

7. 最佳实践：让 srt-slurm 编排从"能跑"到"可运维"

srt-slurm 最大的价值是降低多节点推理部署的调度成本，但如果只停留在"提交 Slurm 作业"层面，后续维护会很吃力。下面几条实践建议，都来自真实部署中比较容易踩坑的位置。

7.1 所有路径全部使用绝对路径

推理任务在不同节点间移动时，相对路径经常出问题。推荐的目录结构：

/data/models/ # 模型权重 /data/inputs/ # 任务输入 /data/outputs/ # 结果输出 /data/workflows/ # 编排服务代码 /data/logs/ # 日志

如果集群只有控制节点有编排服务，计算节点只有模型和输入输出目录，那么路径规划会更简单。不要依赖"当前用户主目录"存放任务数据，多用户场景下主目录权限和磁盘空间都不容易控制。

7.2 模型和镜像要提前预置到节点

大模型权重动辄几十 GB，每次任务都从共享存储加载会严重拖慢启动速度。生产环境建议：

• 将常用模型预置到计算节点本地磁盘或高速缓存目录。
• 镜像版本和模型版本一起管理，每个推理版本使用固定 Tag。
• 新模型上线前先在测试分区跑一遍，避免生产任务首次加载时才发现模型损坏或不兼容。

srt-slurm 编排层最好能把"模型版本"写入任务元数据，方便回滚。

7.3 日志必须带上任务上下文

Slurm 任务日志默认只有作业号和节点信息。实际排查时需要知道这个作业对应哪个推理请求、哪个模型版本、哪个输入文件。建议在推理脚本启动时打印：

print(json.dumps({ "event": "task_start", "input_path": input_path, "output_path": output_path, "gpu": os.environ.get("CUDA_VISIBLE_DEVICES"), "model": os.environ.get("MODEL_NAME"), }), flush=True)

统一使用 JSON 格式输出到stdout，日志采集端可以按event字段做结构化检索。不要只在日志中打印零散字符串。

7.4 小任务不要都走提交-轮询

srt-slurm 的适用场景是长时、GPU 密集的推理任务。如果单个任务只有几百毫秒，频繁提交 Slurm 作业反而会因为排队和调度造成延迟。这类场景更适合：

• 常驻推理服务，例如 vLLM、Triton 或 TensorRT-LLM 的在线服务。
• 服务内部用批处理机制吸收请求。
• 只有在服务扩缩容或离线批处理时，才使用 Slurm 编排。

编排系统、在线推理服务和任务队列各自解决不同问题，不要用一个方案覆盖全部场景。

7.5 发布前检查清单

每次上线新的模型或推理工作流，建议按下面的清单检查：

这份清单可以直接作为发布检查的文本模板。

8. 扩展方向：从单集群推理编排到更完整的推理平台

srt-slurm 成熟之后，通常会沿着几个方向扩展。

8.1 接入在线推理服务网关

可以给 srt-slurm 加一层 API 网关，让外部系统通过 HTTP 提交推理请求。网关负责：

• 把请求转换为标准 Job 描述。
• 提交 Slurm 作业。
• 轮询或回调通知结果。
• 将失败任务纳入重试队列。

这样调用方不需要感知 Slurm 的存在。网关层还可以加鉴权、限流和配额控制。

8.2 与模型版本管理结合

模型文件不是启动时临时下载，而是在模型仓库中打版本号。编排服务通过model_name + model_version确定使用哪个权重文件。发布新版本时只需要切换版本号，必要时可以立即回滚。

8.3 与 CI/CD 流程结合

推理部署通常也需要经过开发、测试、预发、生产四个阶段。可以为每个阶段使用独立 Slurm 分区或独立队列，CI 触发时自动跑通：

1. 编译或打包推理镜像。
2. 在小规模测试分区验证模型加载和推理结果。
3. 通过后推送镜像到生产镜像仓库。
4. 更新编排服务中的模型版本配置。
5. 执行一次金丝雀推理任务，确认输出正常后放量。

8.4 引入工作流 DAG

当推理任务包含多个阶段时，例如数据清洗、分布式推理、结果后处理、评测打分，单层任务编排不够用。可以引入工作流引擎维护 DAG，srt-slurm 只负责其中一个"GPU 推理"节点。这样职责边界更清晰：工作流引擎管理流程，Slurm 管理 GPU 资源。

这里的取舍是引入额外组件会带来学习成本和运维成本，项目初期不建议过度设计。先让单个推理任务稳定运行，再逐步扩展流程编排。

9. 学习路径与落地建议

srt-slurm 是一种把 Slurm 调度能力引入推理部署的技术方案。它的核心价值在于把"模型加载、GPU 申请、任务调度、结果收集"从人工操作变成可编排流程。理解它的关键链路是：推理请求被拆分为子任务，每个子任务被封装为 Slurm 作业，作业运行在 GPU 节点上，结果再由服务层汇总。

实际项目中，建议从最小可运行案例开始，先在只有一到两个 GPU 节点的小集群上跑通完整流程，再逐步加入超时、重试、监控和模型版本管理。不要一开始就在所有功能上铺开。对于新手，最有价值的练习是把自己已有的单机推理脚本改写成两个节点上的并行推理，记录提交作业、轮询状态、收集结果的整个过程。这个练习做完以后，再去看分布式推理平台的编排文档，会发现很多设计都不是凭空出现，而是对这套基础流程的工程化封装。