mlx.launch MLX 多节点分布式启动完整实战本地调试一次跑通【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx当你第一次想把任务跑上多台 Mac 时最纠结的往往不是代码而是启动环境。MLX 是苹果芯片的数组框架配套的 mlx.launch 能一条命令把同一个脚本铺到多台机器上。这篇文章带你一步步走通 MLX 多机分布式启动的全流程从 SSH 预检到失败后的排障。启动前预检先确认这三件事做完这一步你能得到对每台机器直接ssh 主机名就能免密登录三个启动前提全部就位启动即失败的大概率原因提前消灭。跑任务之前先对照这个清单查一遍。任何一条不满足后面都要花时间反复调试ssh hostname能不输密码、不弹主机确认直接登录python 二进制在所有机器上的路径一致——用mlx.launch --print-python查看期望路径你要跑的脚本在所有机器上路径一致。MLX 多机 SSH 免密三步配好如果ssh还在要密码现在就把免密登录做掉生成密钥把公钥拷到每台机器再验证一遍ssh-keygen -t ed25519 -C mlx-distributed ssh-copy-id -i ~/.ssh/id_ed25519.pub node1.local ssh-copy-id -i ~/.ssh/id_ed25519.pub node2.local配完可以用ssh node1.local echo ok验证。机器多的话顺手把主机别名写进~/.ssh/config后面 hostfile 里用短名会清爽很多。主机文件一条命令生成并验证做完这一步你能得到一份格式标准的 hosts.json直接交给 mlx.launch 就能用不会再手滑写错 JSON 或弄混 IP 归属。hostfile 主机文件配置其实很简单一个 JSON 列表每项包含ssh要登录的主机名和ips用于通信的 IP。网络走网卡时用官方工具提取每台机器的 en0 地址并写好文件mlx.distributed_config --hosts node1.local,node2.local \ --over ethernet --output hosts.json生成后打开看一眼结构就是下面这样[ {ssh: node1.local, ips: [192.168.1.101]}, {ssh: node2.local, ips: [192.168.1.102]} ]如果是雷雳线缆互联把参数换成--over thunderbolt --backend ring脚本会帮你探测出环形拓扑再加--dot可以导出 GraphViz 连线图哪根线插错了位置一眼就能看出来。 第一次多机启动从命令到跑通做完这一步你能得到一个终端里同时看到每个 rank 的打印任务真的在多台机器上并行了。上多机之前先在本机验证代码没问题mlx.launch -n 2 my_script.py会在 localhost 拉起 2 个进程能看到各 rank 输出就说明脚本本身是好的。验证通过后上多机指定主机有两种写法mlx.launch --hosts ip1,ip2 my_script.py mlx.launch --hostfile hosts.json my_script.pymlx.launch 会 ssh 到每台机器、按 rank 起进程并全程监控任何一个进程挂了其余进程会被自动终止。它还会把每个进程的 stdout、stderr 转发回你的终端并把你的键盘输入广播给所有进程——所以交互式调试器在分布式下也能用。脚本里只需调用mx.distributed.init()单机跑时这些操作自动变成 no-op不用自己写if size 1的判断。 排障指南用日志分层定位问题节点做完这一步你能得到任务卡住时知道该看哪台机器、该拉哪一层日志而不是对着连接超时干着急。MLX 分布式排障可以拆成三层由浅到深第一层连通性。启动时加上--verbose日志里能看到每台主机的处理进度。某个节点迟迟没起来就回到预检清单里手动ssh一遍十次有九次还是免密登录或路径没对齐。第二层环通信。ring 后端走 TCP 套接字--starting-port指定 rank 0 的监听端口之后的每个 rank 依次加 1。如果日志里只有一个节点连上重点检查另一台机器对应端口是否被防火墙拦了。第三层GPU 任务流。通信通了但算子行为不对时用 Metal 调试器看任务依赖。先编译 MLX 时带上CMAKE_ARGS-DMLX_METAL_DEBUGON会记录编译产物并给 Metal 对象加标签再带着MTL_CAPTURE_ENABLED1运行程序生成.gputrace文件用 Xcode 打开。Dependencies 视图里所有 GPU 任务的依赖关系一目了然阻塞点一眼可见如果习惯直接在 Xcode 里调试可以用 CMake 生成 Xcode 工程选中 metal_capture 示例的 schema 运行捕获流程与上面一致进阶按硬件选通信后端做完这一步你能得到面对任意一套机器都能脱口而出该用哪个--backend不再照抄别人教程里的参数。ring 是默认后端不依赖第三方库、永远可用通常比 MPI 更快。注意它的--hosts只收 IP 不收主机名ssh 主机名和通信 IP 不一致时就用 hostfile--connections-per-ip可以调大相邻节点之间的连接数。CUDA 环境默认走 NCCL 后端。从 Mac 拉起远端 Linux GPU 集群时mlx.launch --backend nccl --hosts linux-1,linux-2 -n 8 -- ./my-job.sh这会在每台节点起 8 个进程共 16 个。跨平台场景用 MPI 后端它是 mpirun 的薄封装hostfile 里的 IP 会被忽略要求每台机器之间两两可 ssh且 mpirun 在所有节点上路径一致。给 mpirun 传参直接用--mpi-argmlx.launch --backend mpi --mpi-arg --mca btl_tcp_if_include en0 \ --hostfile hosts.json my_script.py如果你的机器是雷雳 5 且开启了 RDMAJACCL 是低延迟之选但它要求全互联拓扑hostfile 里还要列全每对节点间的 RDMA 设备配置门槛最高。✅ 收尾要点浓缩为 4 条启动前查三件事SSH 免密、python 同路径mlx.launch --print-python、脚本同路径主机文件交给mlx.distributed_config --over ethernet生成不手写 JSON先用mlx.launch -n 2本机小规模验证再上多机失败就加--verbose分层定位后端按硬件选ring 默认零依赖NCCL 配 CUDA 集群MPI 走跨平台JACCL 上雷雳 RDMA更多参数细节见官方文档分布式通信、启动分布式程序、Metal 调试器。【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mlx.launch MLX 多节点分布式启动完整实战：本地调试一次跑通
mlx.launch MLX 多节点分布式启动完整实战本地调试一次跑通【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx当你第一次想把任务跑上多台 Mac 时最纠结的往往不是代码而是启动环境。MLX 是苹果芯片的数组框架配套的 mlx.launch 能一条命令把同一个脚本铺到多台机器上。这篇文章带你一步步走通 MLX 多机分布式启动的全流程从 SSH 预检到失败后的排障。启动前预检先确认这三件事做完这一步你能得到对每台机器直接ssh 主机名就能免密登录三个启动前提全部就位启动即失败的大概率原因提前消灭。跑任务之前先对照这个清单查一遍。任何一条不满足后面都要花时间反复调试ssh hostname能不输密码、不弹主机确认直接登录python 二进制在所有机器上的路径一致——用mlx.launch --print-python查看期望路径你要跑的脚本在所有机器上路径一致。MLX 多机 SSH 免密三步配好如果ssh还在要密码现在就把免密登录做掉生成密钥把公钥拷到每台机器再验证一遍ssh-keygen -t ed25519 -C mlx-distributed ssh-copy-id -i ~/.ssh/id_ed25519.pub node1.local ssh-copy-id -i ~/.ssh/id_ed25519.pub node2.local配完可以用ssh node1.local echo ok验证。机器多的话顺手把主机别名写进~/.ssh/config后面 hostfile 里用短名会清爽很多。主机文件一条命令生成并验证做完这一步你能得到一份格式标准的 hosts.json直接交给 mlx.launch 就能用不会再手滑写错 JSON 或弄混 IP 归属。hostfile 主机文件配置其实很简单一个 JSON 列表每项包含ssh要登录的主机名和ips用于通信的 IP。网络走网卡时用官方工具提取每台机器的 en0 地址并写好文件mlx.distributed_config --hosts node1.local,node2.local \ --over ethernet --output hosts.json生成后打开看一眼结构就是下面这样[ {ssh: node1.local, ips: [192.168.1.101]}, {ssh: node2.local, ips: [192.168.1.102]} ]如果是雷雳线缆互联把参数换成--over thunderbolt --backend ring脚本会帮你探测出环形拓扑再加--dot可以导出 GraphViz 连线图哪根线插错了位置一眼就能看出来。 第一次多机启动从命令到跑通做完这一步你能得到一个终端里同时看到每个 rank 的打印任务真的在多台机器上并行了。上多机之前先在本机验证代码没问题mlx.launch -n 2 my_script.py会在 localhost 拉起 2 个进程能看到各 rank 输出就说明脚本本身是好的。验证通过后上多机指定主机有两种写法mlx.launch --hosts ip1,ip2 my_script.py mlx.launch --hostfile hosts.json my_script.pymlx.launch 会 ssh 到每台机器、按 rank 起进程并全程监控任何一个进程挂了其余进程会被自动终止。它还会把每个进程的 stdout、stderr 转发回你的终端并把你的键盘输入广播给所有进程——所以交互式调试器在分布式下也能用。脚本里只需调用mx.distributed.init()单机跑时这些操作自动变成 no-op不用自己写if size 1的判断。 排障指南用日志分层定位问题节点做完这一步你能得到任务卡住时知道该看哪台机器、该拉哪一层日志而不是对着连接超时干着急。MLX 分布式排障可以拆成三层由浅到深第一层连通性。启动时加上--verbose日志里能看到每台主机的处理进度。某个节点迟迟没起来就回到预检清单里手动ssh一遍十次有九次还是免密登录或路径没对齐。第二层环通信。ring 后端走 TCP 套接字--starting-port指定 rank 0 的监听端口之后的每个 rank 依次加 1。如果日志里只有一个节点连上重点检查另一台机器对应端口是否被防火墙拦了。第三层GPU 任务流。通信通了但算子行为不对时用 Metal 调试器看任务依赖。先编译 MLX 时带上CMAKE_ARGS-DMLX_METAL_DEBUGON会记录编译产物并给 Metal 对象加标签再带着MTL_CAPTURE_ENABLED1运行程序生成.gputrace文件用 Xcode 打开。Dependencies 视图里所有 GPU 任务的依赖关系一目了然阻塞点一眼可见如果习惯直接在 Xcode 里调试可以用 CMake 生成 Xcode 工程选中 metal_capture 示例的 schema 运行捕获流程与上面一致进阶按硬件选通信后端做完这一步你能得到面对任意一套机器都能脱口而出该用哪个--backend不再照抄别人教程里的参数。ring 是默认后端不依赖第三方库、永远可用通常比 MPI 更快。注意它的--hosts只收 IP 不收主机名ssh 主机名和通信 IP 不一致时就用 hostfile--connections-per-ip可以调大相邻节点之间的连接数。CUDA 环境默认走 NCCL 后端。从 Mac 拉起远端 Linux GPU 集群时mlx.launch --backend nccl --hosts linux-1,linux-2 -n 8 -- ./my-job.sh这会在每台节点起 8 个进程共 16 个。跨平台场景用 MPI 后端它是 mpirun 的薄封装hostfile 里的 IP 会被忽略要求每台机器之间两两可 ssh且 mpirun 在所有节点上路径一致。给 mpirun 传参直接用--mpi-argmlx.launch --backend mpi --mpi-arg --mca btl_tcp_if_include en0 \ --hostfile hosts.json my_script.py如果你的机器是雷雳 5 且开启了 RDMAJACCL 是低延迟之选但它要求全互联拓扑hostfile 里还要列全每对节点间的 RDMA 设备配置门槛最高。✅ 收尾要点浓缩为 4 条启动前查三件事SSH 免密、python 同路径mlx.launch --print-python、脚本同路径主机文件交给mlx.distributed_config --over ethernet生成不手写 JSON先用mlx.launch -n 2本机小规模验证再上多机失败就加--verbose分层定位后端按硬件选ring 默认零依赖NCCL 配 CUDA 集群MPI 走跨平台JACCL 上雷雳 RDMA更多参数细节见官方文档分布式通信、启动分布式程序、Metal 调试器。【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考