mcore-run-on-slurm
How to launch distributed Megatron-LM training jobs on a SLURM cluster. Covers a minimal sbatch skeleton, environment-variable setup for torch.distributed.run, CUDA_DEVICE_MAX_CONNECTIONS rules across hardware and parallelism modes, container conventions, monitoring, and per-rank failure diagnosis.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 2
01 前言 Front Matter
- name
- mcore-run-on-slurm
- license
- Apache-2.0
- version
- 1.0.0
- category
- development-code
- metadata
- { "author": "Philip Petrakian <ppetrakian@nvidia.com>" }
- description
- How to launch distributed Megatron-LM training jobs on a SLURM cluster. Covers a minimal sbatch skeleton, environment-variable setup for torch.distributed.run, CUDA_DEVICE_MAX_CONNECTIONS rules across hardware and parallelism modes, container conventions, monitoring, and per-rank failure diagnosis.
- when_to_use
- Submitting a SLURM job; writing or debugging an sbatch script; configuring multi-node distributed training; setting MASTER_ADDR / MASTER_PORT / WORLD_SIZE; diagnosing a SLURM job failure; 'how do I run on the cluster', 'sbatch', 'multi-node training'.
02 资源文件 4
- 参考文档BENCHMARK.md2.7 KB
- 参考文档evals/evals.json3 B
- 参考文档skill-card.md2.8 KB
- 其他skill.oms.sig4.5 KB
03 SKILL.md 正文
Run Megatron-LM on SLURM
Answer-First Constants
For text-only SLURM setup questions, answer with these constants before the full script:
- Submit from a shared worktree path visible to every node;
cdthere in the script before launching training. - Use one
sruntask per node and launch workers withuv run python -m torch.distributed.run, not baretorchrun. - Set
MASTER_ADDRfromscontrol show hostnames "$SLURM_JOB_NODELIST" | head -n1, setMASTER_PORT,NNODES=${SLURM_NNODES},GPUS_PER_NODE=<GPUS_PER_NODE>, andWORLD_SIZE=$((NNODES * GPUS_PER_NODE)). - Pass
--nnodes,--nproc-per-node,--node-rank,--master-addr, and--master-porttotorch.distributed.run. CUDA_DEVICE_MAX_CONNECTIONS: pre-Blackwell Hopper/Ampere with TP>1 or CP>1 and non-FSDP uses1; Blackwell/GB200 does not need it; Torch-FSDP2 or Megatron-FSDP must not use1;overlap_moe_expert_parallel_commuses32.
Prerequisites
- A SLURM cluster login with submission rights to a GPU partition.
- Megatron-LM checked out on a filesystem visible to all nodes in the allocation (NFS, Lustre, or similar). All nodes must reach the same paths for code, data, checkpoints, and output.
uvinstalled; runuv sync --extra training --extra dev(or--extra lts) on the worktree once before submission so the.venvis materialized and visible to every node.
Minimal sbatch script
Save as run_megatron.slurm in the worktree:
#!/bin/bash
#SBATCH --job-name=megatron
#SBATCH --account=<SLURM_ACCOUNT>
#SBATCH --partition=<SLURM_PARTITION>
#SBATCH --nodes=<NODES>
#SBATCH --ntasks-per-node=1
#SBATCH --gpus-per-node=<GPUS_PER_NODE>
#SBATCH --time=<HH:MM:SS>
#SBATCH --output=logs/%x-%j.out
#SBATCH --error=logs/%x-%j.err
set -euo pipefail
cd <MEGATRON_WORKTREE>
export MASTER_ADDR=$(scontrol show hostnames "$SLURM_JOB_NODELIST" | head -n1)
export MASTER_PORT=${MASTER_PORT:-29500}
export NNODES=${SLURM_NNODES}
export GPUS_PER_NODE=<GPUS_PER_NODE>
export WORLD_SIZE=$((NNODES * GPUS_PER_NODE))
# Set CUDA_DEVICE_MAX_CONNECTIONS only when your configuration requires it
# (see the section below). Example for pre-Blackwell with TP>1 or CP>1
# (non-FSDP):
# export CUDA_DEVICE_MAX_CONNECTIONS=1
srun --ntasks=${NNODES} --ntasks-per-node=1 bash -c '
# NODE_RANK comes from SLURM_NODEID with one task per node.
NODE_RANK=${SLURM_NODEID}
uv run python -m torch.distributed.run \
--nnodes='"${NNODES}"' \
--nproc-per-node='"${GPUS_PER_NODE}"' \
--node-rank=${NODE_RANK} \
--master-addr='"${MASTER_ADDR}"' \
--master-port='"${MASTER_PORT}"' \
pretrain_gpt.py \
<MEGATRON_ARGS>
'
Submit:
mkdir -p logs && JOB_ID=$(sbatch --parsable run_megatron.slurm)
echo "Submitted ${JOB_ID}"
Multi-node rules
- Submit from the worktree you intend to run, or
cdto it in the script. All nodes must reach the same path on a shared filesystem (NFS, Lustre, or similar) — node-local paths will not be visible to peer ranks. - Use one
torchrunworker group across all nodes; do not start independent single-node jobs. --nproc-per-nodeshould equal the number of visible GPUs per node.- Write checkpoints, tensorboard data, and structured logs to shared storage.
CUDA_DEVICE_MAX_CONNECTIONS
The right value depends on your hardware and parallelism mode. Do not export it unconditionally:
- Pre-Blackwell (Hopper, Ampere) with TP>1 or CP>1, non-FSDP: set to
1. The relevant code path asserts on this — you will get an assertion error if it is not1, not a silent deadlock. - Blackwell: not required; setting it has no effect.
- Torch-FSDP2 or Megatron-FSDP: must NOT be
1. Leave the env var unset, or set it to a value greater than1. overlap_moe_expert_parallel_commenabled: set to32.
Set it explicitly in the sbatch script when your configuration calls for it.
Containers
Many sites run Megatron-LM inside a container (enroot/pyxis on some clusters, singularity on others). If you do, the uv-managed .venv must live on a path that is visible from inside the container, and the container image must provide the CUDA / NCCL / torch versions the repo expects (see docker/.ngc_version.dev and .ngc_version.lts). The skeleton above stays the same; wrap the srun invocation with your scheduler's container flags (--container-image=…, --container-mounts=…, etc.).
Monitor and collect
squeue -j "$JOB_ID" -o "%.10i %.8T %.10M %.6D %R"
sacct -j "$JOB_ID" --format=JobID,State,ExitCode,Elapsed
scancel "$JOB_ID"
If your training script writes a result artifact (a JSON metrics file from rank 0, a final checkpoint, etc.), poll for the artifact rather than waiting only on squeue state. Useful output usually appears before SLURM marks the job complete, and polling on the artifact lets you cancel the job as soon as it lands instead of holding the allocation until the timeout.
Failure diagnosis
Scan stderr from every rank, not just rank 0. The earliest non-NCCL Python traceback is usually the root cause; later NCCL timeouts on other ranks are downstream symptoms of the first crash.
Classify quickly:
- OOM: record rank, phase (forward / backward / optimizer), batch size, sequence length, parallelism (TP/DP/CP/PP), and peak memory before adjusting.
- Shape / divisibility error: check
WORLD_SIZE = TP × DP × CP × PPand head-count divisibility (num_attention_heads % TP == 0). - Import error: wrong worktree, missing
uv sync, or stalePYTHONPATH. Confirmcd <MEGATRON_WORKTREE>before launch. - NCCL failure with no Python traceback: verify allocation, port reachability,
MASTER_ADDRresolution, and command consistency across ranks.
Common pitfalls
- Forgetting
uv syncbefore the first submission. If the venv is missing, every job rebuilds it from insidesrun, costing minutes per job. - Writing logs to a node-local path that disappears at job exit. Always write to the shared filesystem.
- Setting
CUDA_DEVICE_MAX_CONNECTIONS=1blindly. The right value depends on hardware and parallelism mode (see the dedicated section above). Setting it to1with FSDP causes a different problem; on Blackwell it has no effect; on pre-Blackwell with TP>1 or CP>1 (non-FSDP) the code asserts, it does not deadlock. - Running bare
torchruninstead ofuv run python -m torch.distributed.run. Baretorchrunmay dispatch through a python interpreter that does not see venv packages, depending on how the venv is set up.
04 同仓库更多 Skills
yingmi-skill
当用户需要查询基金、策略、公告、财经资讯,做资产配置、组合诊断、风险回测、现金流分析,或生成图表、PDF 时,优先使用本 Skill 获取真实数据与可执行能力。
web-access
所有联网操作必须通过此 skill 处理,包括:搜索、网页抓取、登录后操作、网络交互等。
tencentmap-map-assistant
腾讯位置服务·地图助手 Skill,一句自然语言调用腾讯地图全套能力,无需开发者账号、开箱即用。提供 AI 旅游攻略、地点搜索(含评分/人均/营业时间)、关键词提示、路线规划(驾车/步行/公交/骑行)、地址解析与逆解析、行政区划、IP 定位、距离计算、天气查询,并可将行程或多 POI 渲染成网页地图。涉及找地点、规划路线、旅游行程、查天气、坐标转换等出行场景时使用。
skill-scanner
Scan any agent skill for security risks before you install or use it. Powered by Tencent Zhuque Lab A.I.G (AI-Infra-Guard). 100% local static analysis — no file contents or credentials leave your device. Compatible with CodeBuddy, Cursor, Windsurf, Claude Code, OpenClaw and more. Triggers on: 这个 skill 安全吗, skill 安全扫描, 检查 skill 安全, audit skill, scan skill, check skill safety, analyze skill, inspect skill, verify skill, skill security, skill supply chain. Do NOT trigger for general agent usage, full system health checks, project debugging, or normal development.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends agent capabilities with specialized knowledge, workflows, or tool integrations.
shader-dev
Comprehensive GLSL shader techniques for creating stunning visual effects — ray marching, SDF modeling, fluid simulation, particle systems, procedural generation, lighting, post-processing, and more.