PyTorch Lightning 在本地On-Prem集群上使用 TorchRun 启动多节点分布式训练【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000 GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning本篇指南以 PyTorch Lightning 官方文档 cluster_intermediate_2.rst 为核心讲解如何在不依赖 SLURM、Kubernetes 等调度器的通用本地on-prem计算集群上使用torchrun即 TorchElastic一键拉起跨节点的 DDP 训练任务。读完本文你将掌握MASTER_ADDR/MASTER_PORT/NODE_RANK等分布式环境变量的含义与取值规则能够根据节点数量与每节点 GPU 数量写出可复制的torchrun启动命令并理解这些命令与Trainer(devices..., num_nodes..., strategyddp)参数之间的严格对应关系。一、为什么用 TorchRun 启动本地集群训练对于学术或企业内部搭建的通用计算集群PyTorch Lightning 推荐初学者优先采用 TorchRunTorchElastic方式启动多节点训练因为它所需的配置最少、对训练代码的改动为零。与直接手动设置环境变量相比TorchRun 会自动完成以下工作在每台机器上按--nproc_per_node指定的数量拉起进程自动为你设置 PyTorch 分布式通信包所需的环境变量MASTER_ADDR、MASTER_PORT、RANK、LOCAL_RANK、WORLD_SIZE、GROUP_RANK等简化跨节点网络参数的传递你只需在启动命令中明确三个关键决策主节点地址MASTER_ADDR、通信端口MASTER_PORT以及每个节点的编号NODE_RANK。本指南对应文档索引 cluster.rst 中的 Run with Torch Distributed 章节是其上一级指南 cluster_intermediate_1.rst手动设置环境变量的通用集群方案的进阶替代前者要求你手工在每个节点 export 全部环境变量而 TorchRun 把这一步骤自动化了。二、搭建集群前置条件在运行任何torchrun命令之前需要确认集群满足以下三个条件继承自 cluster_intermediate_1.rst 的集群搭建要求多台安装了 PyTorch Lightning 的计算机每个参与训练的节点都必须安装相同版本及依赖通常做法是把requirements.txt分发到每个节点并执行安装。节点间网络连通防火墙规则必须允许在指定的MASTER_PORT上传输流量TCP。确定主节点与节点编号选定一个节点作为主节点其NODE_RANK为 0其余节点依次编号为 1、2、3……PyTorch Lightning 遵循 PyTorch 分布式通信包的环境变量初始化设计手动方案下要求在每个节点定义MASTER_PORT、MASTER_ADDR、WORLD_SIZE、NODE_RANK这四个环境变量使用 TorchRun 时这些变量由启动器替你完成初始化你只需要在命令行中给出对应的参数。注意TorchRun 之前被称为 TorchElastic在旧文档与旧教程中看到 TorchElastic 即指同一工具。三、理解 TorchRun 需要的三个核心决策官方文档用以下示例解释了每个节点上需要确定的参数取值MASTER_ADDR10.10.10.16—— 主节点rank 0 所在机器的 IP 地址MASTER_PORT29500—— 节点间通信端口NODE_RANK第一个节点为0第二个节点为1依此类推。从源码看PyTorch Lightning 的 TorchElastic 集群环境插件 torchelastic.py 正是从环境变量中读取这些值来初始化分布式环境的MASTER_ADDR读取os.environ[MASTER_ADDR]若缺失则回退为127.0.0.1并给出警告MASTER_PORT读取os.environ[MASTER_PORT]若缺失则回退为12910并给出警告WORLD_SIZE、RANK、LOCAL_RANK分别从同名环境变量读取GROUP_RANK通过os.environ.get(GROUP_RANK, 0)读取默认 0。这解释了为什么torchrun是推荐的启动方式——它把这些环境变量的生成完全自动化你只需在命令行上声明上述三个决策即可。四、TorchRun 启动命令与参数详解在训练脚本按 cluster_intermediate_1.rst 中的“训练脚本设置”一节准备好之后即训练脚本中使用 DDP 策略见第五节在每个节点上运行以下命令即可开始多节点训练torchrun \ --nproc_per_nodeGPUS_PER_NODE \ --nnodesNUM_NODES \ --node_rank NODE_RANK \ --master_addr MASTER_ADDR \ --master_port MASTER_PORT \ train.py --arg1 --arg2各参数含义如下表参数含义默认值注意事项--nproc_per_node每个节点启动的进程数即每节点 GPU 数1必须与Trainer(devices...)中设置的设备数一致--nnodes参与训练的节点/机器总数1必须与Trainer(num_nodes...)中设置的节点数一致--node_rank当前节点在集群中的索引编号—主节点为 0其余节点依次递增--master_addr主节点rank 0的 IP 地址—所有节点必须填写相同的值--master_port节点间通信端口—必须为每个节点的防火墙放行以允许 TCP 流量通过端口选择建议MASTER_PORT应当是主节点上一个空闲的端口。顺带一提在不使用 TorchRun、由 Lightning 自己拉起子进程的场景下_MultiprocessingLauncherLightning 会从集群环境中挑选一个随机的空闲端口并写入MASTER_PORT环境变量见 multiprocessing.py而使用 TorchRun 时端口由你显式指定因此务必在每台机器的防火墙中放行该端口。对于 TorchRun 更高级的配置如 elastic 弹性伸缩、容错训练等可查阅 PyTorch 官方 TorchRun 文档。五、训练脚本与 Trainer 的配置对应关系使用 TorchRun 启动的前提是训练脚本本身已按多节点 DDP 方式配置好 Trainer。参考 cluster_intermediate_1.rst 中的写法在 4 个节点、每节点 8 张 GPU共 32 张 GPU的场景下# train on 32 GPUs across 4 nodes trainer Trainer(acceleratorgpu, devices8, num_nodes4, strategyddp)这里的关键是一致性约束--nproc_per_node必须等于Trainer(devices...)此处为 8--nnodes必须等于Trainer(num_nodes...)此处为 4--master_addr、--master_port、--node_rank则是集群网络的定位信息Lightning 训练脚本内部无需感知。从源码看accelerator_connector.py 会对num_nodes做严格校验它必须为正整数否则抛出ValueErrornum_nodesmust be a positive integer。这也意味着Trainer(num_nodes...)与启动命令中的--nnodes必须保持数值一致否则进程组的初始化将失败。六、完整实战示例2 个节点 × 8 张 GPU假设主节点的 IP 地址为10.10.10.16通信端口使用50000两个节点各 8 张 GPU。第一个节点主节点node rank 0执行torchrun \ --nproc_per_node8 --nnodes2 --node_rank 0 \ --master_addr 10.10.10.16 --master_port 50000 \ train.py第二个节点node rank 1执行torchrun \ --nproc_per_node8 --nnodes2 --node_rank 1 \ --master_addr 10.10.10.16 --master_port 50000 \ train.py注意观察两条命令之间唯一的区别就是--node_rank--nproc_per_node、--nnodes、--master_addr、--master_port在所有节点上必须完全相同这既是正确的用法也是排查问题时的第一检查点。七、TorchRun 与 Lightning 启动器的一致性原理从源码结构看PyTorch Lightning 内部同样提供了与 TorchRun 行为非常相似的进程启动器_SubprocessScriptLauncher见 pytorch 实现 与 fabric 实现。该启动器在每个节点的主进程内通过subprocess.Popen额外拉起num_processes - 1个子进程并为所有进程设置 DDP 环境变量MASTER_ADDR主节点 IP来自集群环境MASTER_PORT主节点通信端口NODE_RANK当前节点索引取值范围 0 到num_nodes - 1LOCAL_RANK当前进程在节点内的编号WORLD_SIZE全部进程总数即num_processes * num_nodes。理解这一点有助于你明白 TorchRun 到底做了什么本质上TorchRun 就是一个“在每台机器上替你把进程拉起来、把环境变量设置好”的外部启动器而 Lightning 的 DDP 策略含 Fabric 与 Trainer 两条路径会通过 TorchElastic 集群环境插件读取这些环境变量完成进程组初始化。因此无论你使用torchrun还是 Lightning 自带启动器最终的分布式初始化语义是完全一致的。八、常见故障排查NCCL 与防火墙当使用 DDP 模式多节点训练遇到问题时很多错误会以 NCCL 通信异常的形式出现掩盖真正的代码错误。此时可以设置NCCL_DEBUGINFO环境变量来查看真实的错误信息NCCL_DEBUGINFO python train.py ...此外结合本文内容多节点启动失败时按以下顺序排查节点间端口不通确认MASTER_PORT在每台机器的防火墙中已放行 TCP 流量rank 编号错误确认每个节点的--node_rank唯一且从 0 开始递增其余参数全节点一致参数不匹配核对--nproc_per_node与Trainer(devices...)、--nnodes与Trainer(num_nodes...)是否一致代码错误被 NCCL 掩盖在任意节点上以NCCL_DEBUGINFO重跑观察完整日志定位真实异常。九、进阶弹性与容错训练TorchRunTorchElastic的价值不仅在于替代手动环境变量设置它还支持弹性elastic训练与容错训练等更高级的用法——例如在训练过程中动态调整参与节点数、或在某个节点故障时自动重启失败的 worker。这些能力属于 TorchRun 自身的特性PyTorch Lightning 的 TorchElastic 集群环境插件已为其预留了支持如GROUP_RANK的读取可在需要时进一步查阅 PyTorch 官方 TorchRun 文档并搭配 Lightning 的 DDP 策略使用。对于由 SLURM 管理的集群可参考同目录下的 SLURM 专属文档cluster.rst 导航中的 Run on a SLURM cluster 章节如需对接自研调度器可阅读 Integrate your own cluster 专家章节。【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000 GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyTorch Lightning 在本地（On-Prem）集群上使用 TorchRun 启动多节点分布式训练
PyTorch Lightning 在本地On-Prem集群上使用 TorchRun 启动多节点分布式训练【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000 GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning本篇指南以 PyTorch Lightning 官方文档 cluster_intermediate_2.rst 为核心讲解如何在不依赖 SLURM、Kubernetes 等调度器的通用本地on-prem计算集群上使用torchrun即 TorchElastic一键拉起跨节点的 DDP 训练任务。读完本文你将掌握MASTER_ADDR/MASTER_PORT/NODE_RANK等分布式环境变量的含义与取值规则能够根据节点数量与每节点 GPU 数量写出可复制的torchrun启动命令并理解这些命令与Trainer(devices..., num_nodes..., strategyddp)参数之间的严格对应关系。一、为什么用 TorchRun 启动本地集群训练对于学术或企业内部搭建的通用计算集群PyTorch Lightning 推荐初学者优先采用 TorchRunTorchElastic方式启动多节点训练因为它所需的配置最少、对训练代码的改动为零。与直接手动设置环境变量相比TorchRun 会自动完成以下工作在每台机器上按--nproc_per_node指定的数量拉起进程自动为你设置 PyTorch 分布式通信包所需的环境变量MASTER_ADDR、MASTER_PORT、RANK、LOCAL_RANK、WORLD_SIZE、GROUP_RANK等简化跨节点网络参数的传递你只需在启动命令中明确三个关键决策主节点地址MASTER_ADDR、通信端口MASTER_PORT以及每个节点的编号NODE_RANK。本指南对应文档索引 cluster.rst 中的 Run with Torch Distributed 章节是其上一级指南 cluster_intermediate_1.rst手动设置环境变量的通用集群方案的进阶替代前者要求你手工在每个节点 export 全部环境变量而 TorchRun 把这一步骤自动化了。二、搭建集群前置条件在运行任何torchrun命令之前需要确认集群满足以下三个条件继承自 cluster_intermediate_1.rst 的集群搭建要求多台安装了 PyTorch Lightning 的计算机每个参与训练的节点都必须安装相同版本及依赖通常做法是把requirements.txt分发到每个节点并执行安装。节点间网络连通防火墙规则必须允许在指定的MASTER_PORT上传输流量TCP。确定主节点与节点编号选定一个节点作为主节点其NODE_RANK为 0其余节点依次编号为 1、2、3……PyTorch Lightning 遵循 PyTorch 分布式通信包的环境变量初始化设计手动方案下要求在每个节点定义MASTER_PORT、MASTER_ADDR、WORLD_SIZE、NODE_RANK这四个环境变量使用 TorchRun 时这些变量由启动器替你完成初始化你只需要在命令行中给出对应的参数。注意TorchRun 之前被称为 TorchElastic在旧文档与旧教程中看到 TorchElastic 即指同一工具。三、理解 TorchRun 需要的三个核心决策官方文档用以下示例解释了每个节点上需要确定的参数取值MASTER_ADDR10.10.10.16—— 主节点rank 0 所在机器的 IP 地址MASTER_PORT29500—— 节点间通信端口NODE_RANK第一个节点为0第二个节点为1依此类推。从源码看PyTorch Lightning 的 TorchElastic 集群环境插件 torchelastic.py 正是从环境变量中读取这些值来初始化分布式环境的MASTER_ADDR读取os.environ[MASTER_ADDR]若缺失则回退为127.0.0.1并给出警告MASTER_PORT读取os.environ[MASTER_PORT]若缺失则回退为12910并给出警告WORLD_SIZE、RANK、LOCAL_RANK分别从同名环境变量读取GROUP_RANK通过os.environ.get(GROUP_RANK, 0)读取默认 0。这解释了为什么torchrun是推荐的启动方式——它把这些环境变量的生成完全自动化你只需在命令行上声明上述三个决策即可。四、TorchRun 启动命令与参数详解在训练脚本按 cluster_intermediate_1.rst 中的“训练脚本设置”一节准备好之后即训练脚本中使用 DDP 策略见第五节在每个节点上运行以下命令即可开始多节点训练torchrun \ --nproc_per_nodeGPUS_PER_NODE \ --nnodesNUM_NODES \ --node_rank NODE_RANK \ --master_addr MASTER_ADDR \ --master_port MASTER_PORT \ train.py --arg1 --arg2各参数含义如下表参数含义默认值注意事项--nproc_per_node每个节点启动的进程数即每节点 GPU 数1必须与Trainer(devices...)中设置的设备数一致--nnodes参与训练的节点/机器总数1必须与Trainer(num_nodes...)中设置的节点数一致--node_rank当前节点在集群中的索引编号—主节点为 0其余节点依次递增--master_addr主节点rank 0的 IP 地址—所有节点必须填写相同的值--master_port节点间通信端口—必须为每个节点的防火墙放行以允许 TCP 流量通过端口选择建议MASTER_PORT应当是主节点上一个空闲的端口。顺带一提在不使用 TorchRun、由 Lightning 自己拉起子进程的场景下_MultiprocessingLauncherLightning 会从集群环境中挑选一个随机的空闲端口并写入MASTER_PORT环境变量见 multiprocessing.py而使用 TorchRun 时端口由你显式指定因此务必在每台机器的防火墙中放行该端口。对于 TorchRun 更高级的配置如 elastic 弹性伸缩、容错训练等可查阅 PyTorch 官方 TorchRun 文档。五、训练脚本与 Trainer 的配置对应关系使用 TorchRun 启动的前提是训练脚本本身已按多节点 DDP 方式配置好 Trainer。参考 cluster_intermediate_1.rst 中的写法在 4 个节点、每节点 8 张 GPU共 32 张 GPU的场景下# train on 32 GPUs across 4 nodes trainer Trainer(acceleratorgpu, devices8, num_nodes4, strategyddp)这里的关键是一致性约束--nproc_per_node必须等于Trainer(devices...)此处为 8--nnodes必须等于Trainer(num_nodes...)此处为 4--master_addr、--master_port、--node_rank则是集群网络的定位信息Lightning 训练脚本内部无需感知。从源码看accelerator_connector.py 会对num_nodes做严格校验它必须为正整数否则抛出ValueErrornum_nodesmust be a positive integer。这也意味着Trainer(num_nodes...)与启动命令中的--nnodes必须保持数值一致否则进程组的初始化将失败。六、完整实战示例2 个节点 × 8 张 GPU假设主节点的 IP 地址为10.10.10.16通信端口使用50000两个节点各 8 张 GPU。第一个节点主节点node rank 0执行torchrun \ --nproc_per_node8 --nnodes2 --node_rank 0 \ --master_addr 10.10.10.16 --master_port 50000 \ train.py第二个节点node rank 1执行torchrun \ --nproc_per_node8 --nnodes2 --node_rank 1 \ --master_addr 10.10.10.16 --master_port 50000 \ train.py注意观察两条命令之间唯一的区别就是--node_rank--nproc_per_node、--nnodes、--master_addr、--master_port在所有节点上必须完全相同这既是正确的用法也是排查问题时的第一检查点。七、TorchRun 与 Lightning 启动器的一致性原理从源码结构看PyTorch Lightning 内部同样提供了与 TorchRun 行为非常相似的进程启动器_SubprocessScriptLauncher见 pytorch 实现 与 fabric 实现。该启动器在每个节点的主进程内通过subprocess.Popen额外拉起num_processes - 1个子进程并为所有进程设置 DDP 环境变量MASTER_ADDR主节点 IP来自集群环境MASTER_PORT主节点通信端口NODE_RANK当前节点索引取值范围 0 到num_nodes - 1LOCAL_RANK当前进程在节点内的编号WORLD_SIZE全部进程总数即num_processes * num_nodes。理解这一点有助于你明白 TorchRun 到底做了什么本质上TorchRun 就是一个“在每台机器上替你把进程拉起来、把环境变量设置好”的外部启动器而 Lightning 的 DDP 策略含 Fabric 与 Trainer 两条路径会通过 TorchElastic 集群环境插件读取这些环境变量完成进程组初始化。因此无论你使用torchrun还是 Lightning 自带启动器最终的分布式初始化语义是完全一致的。八、常见故障排查NCCL 与防火墙当使用 DDP 模式多节点训练遇到问题时很多错误会以 NCCL 通信异常的形式出现掩盖真正的代码错误。此时可以设置NCCL_DEBUGINFO环境变量来查看真实的错误信息NCCL_DEBUGINFO python train.py ...此外结合本文内容多节点启动失败时按以下顺序排查节点间端口不通确认MASTER_PORT在每台机器的防火墙中已放行 TCP 流量rank 编号错误确认每个节点的--node_rank唯一且从 0 开始递增其余参数全节点一致参数不匹配核对--nproc_per_node与Trainer(devices...)、--nnodes与Trainer(num_nodes...)是否一致代码错误被 NCCL 掩盖在任意节点上以NCCL_DEBUGINFO重跑观察完整日志定位真实异常。九、进阶弹性与容错训练TorchRunTorchElastic的价值不仅在于替代手动环境变量设置它还支持弹性elastic训练与容错训练等更高级的用法——例如在训练过程中动态调整参与节点数、或在某个节点故障时自动重启失败的 worker。这些能力属于 TorchRun 自身的特性PyTorch Lightning 的 TorchElastic 集群环境插件已为其预留了支持如GROUP_RANK的读取可在需要时进一步查阅 PyTorch 官方 TorchRun 文档并搭配 Lightning 的 DDP 策略使用。对于由 SLURM 管理的集群可参考同目录下的 SLURM 专属文档cluster.rst 导航中的 Run on a SLURM cluster 章节如需对接自研调度器可阅读 Integrate your own cluster 专家章节。【免费下载链接】pytorch-lightningPretrain, finetune ANY AI model of ANY size on 1 or 10,000 GPUs with zero code changes.项目地址: https://gitcode.com/gh_mirrors/py/pytorch-lightning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考