4 台 Mac 组一个集群JACCL Thunderbolt 5 RDMA 搭建低延迟分布式通信实战指南【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx你有没有遇到这种情况几台 Mac 用网线或 Wi-Fi 互联跑张量并行all_reduce 一来一回全卡在 TCP 上小消息延迟吃掉整个推理吞吐梯度同步也一样通信成了最贵的一环。MLX 里的JACCL就是为此而生的它基于 Apple 在 macOS 26.2 提供的 RDMA over Thunderbolt让 Mac 集群在 Thunderbolt 5 链路上直接做低延迟集合通信官方给出的量化收益是延迟比传统 TCP 方案低一个数量级。下面带你从零搭起第一组可用的 Mac 分布式环境。⚡ 30 秒看懂 JACCL 是什么一句话定义JACCL 是 MLX 内置的 macOS 分布式通信库读作 Jackal走 Thunderbolt 5 上的 RDMA提供 all_sum、all_max、all_min、all_gather、send/recv 和 barrier 等原语。用之前先核对三条硬前提macOS SDK 与部署目标均 26.2构建脚本不满足会直接跳过编译节点之间用Thunderbolt 5互连已在恢复模式执行过rdma_ctl enableRDMA over Thunderbolt 处于开启状态。下面这张图是张量并行推理中线性层的通信切分方式你可以直观看到 all_reduce / all_gather 出现在哪 JACCL 适合解决什么问题场景一大模型多机推理的张量并行谁卡住了每层算完都要跨机同步中间结果小消息通信延迟直接决定 token 延迟。 它能做什么all_sum即 all_reduce 求和all_gather把切分的激活拼回完整张量。场景二多机分布式训练的梯度同步谁卡住了每步反传后的 all-reduce 是热点路径TCP 延迟与拷贝开销被放大 N 倍。 它能做什么低延迟all_sum做梯度归约bf16/fp16 类型原生支持可直接对半精度梯度通信。场景三多机协作计算需要点对点交换数据谁卡住了数据重分布如 KV cache 迁移需要按节点定向收发。 它能做什么send/recv点对点原语 barrier同步所有节点到同一步。 为什么 RDMA 快mesh 与 ring 怎么选RDMA 快的本质是快递直送数据由网卡直接从你的进程内存搬到对端进程内存不再进内核 TCP/IP 协议栈省掉了上下文切换、多次内存拷贝和协议处理。TCP 则像走中转站——每个包都要过内核这个中转点小消息尤其吃亏。拓扑选 mesh 还是 ring看消息大小拓扑工作方式擅长场景类比mesh全连接任意两节点直接通信小消息、低延迟每个部门互相直拨电话ring环形流水线reduce-scatter all-gather大消息、高带宽接力跑每人跑一段棒依次传递经验法则小消息走 mesh 保延迟大消息走 ring 拼带宽。ring 在每个 peer 用多条连接时是 JACCL 中大消息带宽最高的组形态。️ 五步搭起第一台 JACCL 集群本节走完你会在 4 台 Mac 上跑通一次真实的 all_sum。第一步前置检查确认 SDK 达标在每台 Mac 上确认 macOS SDK 版本不低于 26.2这是构建 JACCL 的门槛xcrun --sdk macosx --show-sdk-version低于 26.2 就先去升级系统。同时确认 CMake 3.24、工具链支持 C20。第二步恢复模式开启 RDMA用设备列表验证RDMA over Thunderbolt 默认关闭只需做一次将 Mac 启动进入恢复模式打开实用工具 → 终端执行rdma_ctl enable重启。重启后验证设备可见ibv_devices正常输出形如device node GUID ------ ---------------- rdma_en2 8096a9d9edbaac05 rdma_en3 8196a9d9edbaac05 rdma_en5 8396a9d9edbaac05记下每台机器实际看到的设备名如rdma_en5它是后面连接矩阵的原料。第三步构建 JACCL 独立库进入仓库里的独立库目录官方文档见 mlx/distributed/jaccl/lib/README.mdcd mlx/distributed/jaccl/lib mkdir build cd build cmake .. make构建脚本默认 Release注释里特意提醒不设构建类型时 CMake 用空类型-O0会严重拖慢归约和 memcpy 热点路径。第四步编译最小示例官方 examples 目录把上层目录当作 FetchContent 依赖引入并生成四个目标jaccl_minimal_env、jaccl_minimal_cfg、jaccl_minimal_barrier、jaccl_allreduce_benchcd mlx/distributed/jaccl/lib/examples mkdir build cd build cmake .. make jaccl_minimal_env核心逻辑只有几行完整版见 mlx/distributed/jaccl/lib/examples/minimal_env.cppauto group jaccl::init(); float input[10] {1.f, 2.f, 3.f, 4.f, 5.f, 6.f, 7.f, 8.f, 9.f, 10.f}; float output[10]; group-all_sum(input, output, sizeof(input), jaccl::Float32);第五步按 rank 启动四个进程核对输出4 台机器各开一个终端分别设置环境变量后启动同一个二进制export JACCL_RANK0 export JACCL_IBV_DEVICESdevices.json export JACCL_COORDINATOR192.168.1.1:32132 ./jaccl_minimal_env # rank 1/2/3 把 JACCL_RANK 改成 1/2/3预期每个进程打印Rank r of 4且Result:行每个元素都等于4.5 × 原值4 个 rank 求和。只要有一台卡住或数值不对跳到最后一节对照排查。️ 三种方式描述谁连谁环境变量、Config、自动探测环境变量方式临时调试最快jaccl::init()无参调用会走Config::from_env()逐项读取下表变量JACCL_*优先于MLX_*变量别名含义JACCL_RANKMLX_RANK本进程 rank从 0 开始的整数JACCL_IBV_DEVICESMLX_IBV_DEVICES设备连接关系 JSON 文件路径JACCL_COORDINATORMLX_JACCL_COORDINATOR协调者rank 0 监听端的 IP:portJACCL_RINGMLX_JACCL_RING可选设置后优先 ring 拓扑设备文件是个 JSON 矩阵devices[i][j]写连接 rank i 到 rank j 的设备名i j处填null[ [null, rdma_en5, rdma_en4, rdma_en3], [rdma_en5, null, rdma_en3, rdma_en4], [rdma_en4, rdma_en3, null, rdma_en5], [rdma_en3, rdma_en4, rdma_en5, null] ]跑 ring 时只有左右邻居位置能填设备名其余必须留空。Config 代码方式配置写死在程序里需要程序内嵌配置时用Config对象下面是最小的 4 节点 mesh 示例空数组表示不连自己auto cfg jaccl::Config() .set_rank(0) // 每个节点改成不同值 .set_coordinator(192.168.1.1:32132) // rank 0 监听地址 .set_devices({ {{}, {rdma_en5}, {rdma_en4}, {rdma_en3}}, {{rdma_en5}, {}, {rdma_en3}, {rdma_en4}}, {{rdma_en4}, {rdma_en3}, {}, {rdma_en5}}, {{rdma_en3}, {rdma_en4}, {rdma_en5}, {}} }); auto group jaccl::init(cfg);set_devices会推导组大小并强制矩阵是方阵另有set_devices_from_file直接读上面那种 JSON。自动探测方式一条命令生成 hostfile手工画矩阵容易出错mlx.distributed_config可以自动探测 Thunderbolt 物理连接mlx.distributed_config --verbose \ --hosts m3-ultra-1,m3-ultra-2,m3-ultra-3,m3-ultra-4 \ --over thunderbolt --dot | dot -Tpng | open -f -a Preview第一条命令把实际接线画成图先肉眼核对物理拓扑核对无误后加--auto-setup --output m3-ultra-jaccl.json即可生成直接交给mlx.launch使用的 hostfilehost 节点含ssh、ips、rdma三字段rdma就是矩阵的一行。选型建议临时调试用环境变量长期项目用 Config 内嵌真正组网优先用自动探测——接线画错比代码写错难查得多。 Group API 速查表与 init 行为方法参数语义坑点rank()/size()无查自身身份与组大小组创建后不可变all_sum/all_max/all_mininput, output, n_bytes, dtype全组归约输出与输入同大小dtype 决定按什么类型解释数据all_gatherinput, output, n_bytes收集全组数据输出必须是size() * n_bytessum_scatterinput, output, n_bytes, dtype求和 reduce-scatterrank r 拿到的是全组第 r 块之和send/recvbuf, n_bytes, dst/src点对点收发双方大小必须一致barrier无阻塞到全组到达用作全局同步栅栏init的重载与 strict 行为init(bool strict false)从环境变量读配置建组init(const Config, bool strict false)用显式配置建组另有自定义侧信道工厂的重载stricttrue失败时抛异常strictfalse失败时返回nullptr——判空还是 catch由你选。最重要的一条约定JACCL 自身不做任何内存分配所有输出指针必须指向你自己分配好、且足以容纳结果的内存。️ 怎么测 all_reduce 带宽跑 allreduce_bench示例目录里的jaccl_allreduce_bench是 NCCL 风格的基准1K 到 256M 字节逐档扫描all_sum的延迟与带宽支持 float32 / float16 / bfloat16可加-c做正确性校验。启动方式mlx.launch --hostfile m3-ultra-jaccl.json \ ./jaccl_allreduce_bench -n 20 -c参数速查参数含义默认值-w每个消息大小的预热迭代数5-n每个消息大小的计时迭代数20-b/-e最小 / 最大消息字节数1K / 256M-f倍增步长2-d数据类型 float32 / float16 / bfloat16float32-c开启正确性校验每 rank 填 rank1校验结果等于 n(n1)/2关如何读总线带宽输出表里algo BW 消息字节数 / 平均耗时bus BW algo BW × 2(n−1)/nn 为节点数。这个 2(n−1)/n 因子把 ring 全链路实际传输量折算进来——4 节点时即 1.5 倍。对比硬件理论峰值时看 bus BW对比端到端数据吞吐时看 algo BW两者别混用。⚠️ 踩坑与排查四个高频症状症状一构建成功了但根本没有 JACCL 产物。原因CMake 发现非 Darwin 系统、SDK 26.2 或部署目标 26.2 时会打印一条 STATUS 消息后直接跳过不报错。 解法确认输出里没有 Skipping JACCL build用xcrun --sdk macosx --show-sdk-version核对版本MLX 主库不满足条件时只会编译no_jaccl.cpp占位实现。症状二init返回空指针或抛 The configuration should define a valid mesh or a valid ring。原因设备矩阵与物理接线不对应比如ibv_devices里明明只有rdma_en2/en3/en5矩阵里却写了rdma_en4或 mesh 要求对角为空、非对角都有设备没满足。 解法逐台重跑ibv_devices对齐设备名或用mlx.distributed_config --dot生成拓扑图核对后再填矩阵。症状三抛出 invalid_argument The full connectivity matrix should be provided but we have N rows and row r has M columns。原因set_devices强制矩阵是方阵——行数必须等于列数即每行条目数必须等于节点总数。 解法检查 JSON 每行是否漏项文件版还会报 rank r contains only X entries按提示补齐第 r 行。症状四在 MLX 里对组做 split 直接抛 Group split not supported。原因JACCL 集成层mlx/distributed/jaccl/jaccl.cpp没有实现组内再分片这是设计限制而非环境故障。 解法一个脚本只用一个通信组需要多组时拆分进程而非拆分 Group。 收尾如果你的场景是 Mac 集群上跑张量并行推理、多机训练梯度同步且满足 macOS SDK 26.2 与 Thunderbolt 5 互连两条硬门槛JACCL 是目前 MLX 生态里延迟最低的集合通信选择按本文五步搭好环境用自动探测画出连接矩阵再拿 allreduce_bench 的 bus BW 确认链路打满剩下的就是把backendjaccl交给mlx.launch。JACCL 是 MLX 的一部分采用与 MLX 相同的许可证名字读作 Jackal取自 Jack and Angelos Collective Communication Library既是对 NCCL 的致敬也纪念主导 Apple RDMA over Thunderbolt 开发的 Jack Beasley。【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 18:11:25 · 阅读 1.2k 4 台 Mac 组一个集群：JACCL + Thunderbolt 5 RDMA 搭建低延迟分布式通信实战指南
4 台 Mac 组一个集群JACCL Thunderbolt 5 RDMA 搭建低延迟分布式通信实战指南【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx你有没有遇到这种情况几台 Mac 用网线或 Wi-Fi 互联跑张量并行all_reduce 一来一回全卡在 TCP 上小消息延迟吃掉整个推理吞吐梯度同步也一样通信成了最贵的一环。MLX 里的JACCL就是为此而生的它基于 Apple 在 macOS 26.2 提供的 RDMA over Thunderbolt让 Mac 集群在 Thunderbolt 5 链路上直接做低延迟集合通信官方给出的量化收益是延迟比传统 TCP 方案低一个数量级。下面带你从零搭起第一组可用的 Mac 分布式环境。⚡ 30 秒看懂 JACCL 是什么一句话定义JACCL 是 MLX 内置的 macOS 分布式通信库读作 Jackal走 Thunderbolt 5 上的 RDMA提供 all_sum、all_max、all_min、all_gather、send/recv 和 barrier 等原语。用之前先核对三条硬前提macOS SDK 与部署目标均 26.2构建脚本不满足会直接跳过编译节点之间用Thunderbolt 5互连已在恢复模式执行过rdma_ctl enableRDMA over Thunderbolt 处于开启状态。下面这张图是张量并行推理中线性层的通信切分方式你可以直观看到 all_reduce / all_gather 出现在哪 JACCL 适合解决什么问题场景一大模型多机推理的张量并行谁卡住了每层算完都要跨机同步中间结果小消息通信延迟直接决定 token 延迟。 它能做什么all_sum即 all_reduce 求和all_gather把切分的激活拼回完整张量。场景二多机分布式训练的梯度同步谁卡住了每步反传后的 all-reduce 是热点路径TCP 延迟与拷贝开销被放大 N 倍。 它能做什么低延迟all_sum做梯度归约bf16/fp16 类型原生支持可直接对半精度梯度通信。场景三多机协作计算需要点对点交换数据谁卡住了数据重分布如 KV cache 迁移需要按节点定向收发。 它能做什么send/recv点对点原语 barrier同步所有节点到同一步。 为什么 RDMA 快mesh 与 ring 怎么选RDMA 快的本质是快递直送数据由网卡直接从你的进程内存搬到对端进程内存不再进内核 TCP/IP 协议栈省掉了上下文切换、多次内存拷贝和协议处理。TCP 则像走中转站——每个包都要过内核这个中转点小消息尤其吃亏。拓扑选 mesh 还是 ring看消息大小拓扑工作方式擅长场景类比mesh全连接任意两节点直接通信小消息、低延迟每个部门互相直拨电话ring环形流水线reduce-scatter all-gather大消息、高带宽接力跑每人跑一段棒依次传递经验法则小消息走 mesh 保延迟大消息走 ring 拼带宽。ring 在每个 peer 用多条连接时是 JACCL 中大消息带宽最高的组形态。️ 五步搭起第一台 JACCL 集群本节走完你会在 4 台 Mac 上跑通一次真实的 all_sum。第一步前置检查确认 SDK 达标在每台 Mac 上确认 macOS SDK 版本不低于 26.2这是构建 JACCL 的门槛xcrun --sdk macosx --show-sdk-version低于 26.2 就先去升级系统。同时确认 CMake 3.24、工具链支持 C20。第二步恢复模式开启 RDMA用设备列表验证RDMA over Thunderbolt 默认关闭只需做一次将 Mac 启动进入恢复模式打开实用工具 → 终端执行rdma_ctl enable重启。重启后验证设备可见ibv_devices正常输出形如device node GUID ------ ---------------- rdma_en2 8096a9d9edbaac05 rdma_en3 8196a9d9edbaac05 rdma_en5 8396a9d9edbaac05记下每台机器实际看到的设备名如rdma_en5它是后面连接矩阵的原料。第三步构建 JACCL 独立库进入仓库里的独立库目录官方文档见 mlx/distributed/jaccl/lib/README.mdcd mlx/distributed/jaccl/lib mkdir build cd build cmake .. make构建脚本默认 Release注释里特意提醒不设构建类型时 CMake 用空类型-O0会严重拖慢归约和 memcpy 热点路径。第四步编译最小示例官方 examples 目录把上层目录当作 FetchContent 依赖引入并生成四个目标jaccl_minimal_env、jaccl_minimal_cfg、jaccl_minimal_barrier、jaccl_allreduce_benchcd mlx/distributed/jaccl/lib/examples mkdir build cd build cmake .. make jaccl_minimal_env核心逻辑只有几行完整版见 mlx/distributed/jaccl/lib/examples/minimal_env.cppauto group jaccl::init(); float input[10] {1.f, 2.f, 3.f, 4.f, 5.f, 6.f, 7.f, 8.f, 9.f, 10.f}; float output[10]; group-all_sum(input, output, sizeof(input), jaccl::Float32);第五步按 rank 启动四个进程核对输出4 台机器各开一个终端分别设置环境变量后启动同一个二进制export JACCL_RANK0 export JACCL_IBV_DEVICESdevices.json export JACCL_COORDINATOR192.168.1.1:32132 ./jaccl_minimal_env # rank 1/2/3 把 JACCL_RANK 改成 1/2/3预期每个进程打印Rank r of 4且Result:行每个元素都等于4.5 × 原值4 个 rank 求和。只要有一台卡住或数值不对跳到最后一节对照排查。️ 三种方式描述谁连谁环境变量、Config、自动探测环境变量方式临时调试最快jaccl::init()无参调用会走Config::from_env()逐项读取下表变量JACCL_*优先于MLX_*变量别名含义JACCL_RANKMLX_RANK本进程 rank从 0 开始的整数JACCL_IBV_DEVICESMLX_IBV_DEVICES设备连接关系 JSON 文件路径JACCL_COORDINATORMLX_JACCL_COORDINATOR协调者rank 0 监听端的 IP:portJACCL_RINGMLX_JACCL_RING可选设置后优先 ring 拓扑设备文件是个 JSON 矩阵devices[i][j]写连接 rank i 到 rank j 的设备名i j处填null[ [null, rdma_en5, rdma_en4, rdma_en3], [rdma_en5, null, rdma_en3, rdma_en4], [rdma_en4, rdma_en3, null, rdma_en5], [rdma_en3, rdma_en4, rdma_en5, null] ]跑 ring 时只有左右邻居位置能填设备名其余必须留空。Config 代码方式配置写死在程序里需要程序内嵌配置时用Config对象下面是最小的 4 节点 mesh 示例空数组表示不连自己auto cfg jaccl::Config() .set_rank(0) // 每个节点改成不同值 .set_coordinator(192.168.1.1:32132) // rank 0 监听地址 .set_devices({ {{}, {rdma_en5}, {rdma_en4}, {rdma_en3}}, {{rdma_en5}, {}, {rdma_en3}, {rdma_en4}}, {{rdma_en4}, {rdma_en3}, {}, {rdma_en5}}, {{rdma_en3}, {rdma_en4}, {rdma_en5}, {}} }); auto group jaccl::init(cfg);set_devices会推导组大小并强制矩阵是方阵另有set_devices_from_file直接读上面那种 JSON。自动探测方式一条命令生成 hostfile手工画矩阵容易出错mlx.distributed_config可以自动探测 Thunderbolt 物理连接mlx.distributed_config --verbose \ --hosts m3-ultra-1,m3-ultra-2,m3-ultra-3,m3-ultra-4 \ --over thunderbolt --dot | dot -Tpng | open -f -a Preview第一条命令把实际接线画成图先肉眼核对物理拓扑核对无误后加--auto-setup --output m3-ultra-jaccl.json即可生成直接交给mlx.launch使用的 hostfilehost 节点含ssh、ips、rdma三字段rdma就是矩阵的一行。选型建议临时调试用环境变量长期项目用 Config 内嵌真正组网优先用自动探测——接线画错比代码写错难查得多。 Group API 速查表与 init 行为方法参数语义坑点rank()/size()无查自身身份与组大小组创建后不可变all_sum/all_max/all_mininput, output, n_bytes, dtype全组归约输出与输入同大小dtype 决定按什么类型解释数据all_gatherinput, output, n_bytes收集全组数据输出必须是size() * n_bytessum_scatterinput, output, n_bytes, dtype求和 reduce-scatterrank r 拿到的是全组第 r 块之和send/recvbuf, n_bytes, dst/src点对点收发双方大小必须一致barrier无阻塞到全组到达用作全局同步栅栏init的重载与 strict 行为init(bool strict false)从环境变量读配置建组init(const Config, bool strict false)用显式配置建组另有自定义侧信道工厂的重载stricttrue失败时抛异常strictfalse失败时返回nullptr——判空还是 catch由你选。最重要的一条约定JACCL 自身不做任何内存分配所有输出指针必须指向你自己分配好、且足以容纳结果的内存。️ 怎么测 all_reduce 带宽跑 allreduce_bench示例目录里的jaccl_allreduce_bench是 NCCL 风格的基准1K 到 256M 字节逐档扫描all_sum的延迟与带宽支持 float32 / float16 / bfloat16可加-c做正确性校验。启动方式mlx.launch --hostfile m3-ultra-jaccl.json \ ./jaccl_allreduce_bench -n 20 -c参数速查参数含义默认值-w每个消息大小的预热迭代数5-n每个消息大小的计时迭代数20-b/-e最小 / 最大消息字节数1K / 256M-f倍增步长2-d数据类型 float32 / float16 / bfloat16float32-c开启正确性校验每 rank 填 rank1校验结果等于 n(n1)/2关如何读总线带宽输出表里algo BW 消息字节数 / 平均耗时bus BW algo BW × 2(n−1)/nn 为节点数。这个 2(n−1)/n 因子把 ring 全链路实际传输量折算进来——4 节点时即 1.5 倍。对比硬件理论峰值时看 bus BW对比端到端数据吞吐时看 algo BW两者别混用。⚠️ 踩坑与排查四个高频症状症状一构建成功了但根本没有 JACCL 产物。原因CMake 发现非 Darwin 系统、SDK 26.2 或部署目标 26.2 时会打印一条 STATUS 消息后直接跳过不报错。 解法确认输出里没有 Skipping JACCL build用xcrun --sdk macosx --show-sdk-version核对版本MLX 主库不满足条件时只会编译no_jaccl.cpp占位实现。症状二init返回空指针或抛 The configuration should define a valid mesh or a valid ring。原因设备矩阵与物理接线不对应比如ibv_devices里明明只有rdma_en2/en3/en5矩阵里却写了rdma_en4或 mesh 要求对角为空、非对角都有设备没满足。 解法逐台重跑ibv_devices对齐设备名或用mlx.distributed_config --dot生成拓扑图核对后再填矩阵。症状三抛出 invalid_argument The full connectivity matrix should be provided but we have N rows and row r has M columns。原因set_devices强制矩阵是方阵——行数必须等于列数即每行条目数必须等于节点总数。 解法检查 JSON 每行是否漏项文件版还会报 rank r contains only X entries按提示补齐第 r 行。症状四在 MLX 里对组做 split 直接抛 Group split not supported。原因JACCL 集成层mlx/distributed/jaccl/jaccl.cpp没有实现组内再分片这是设计限制而非环境故障。 解法一个脚本只用一个通信组需要多组时拆分进程而非拆分 Group。 收尾如果你的场景是 Mac 集群上跑张量并行推理、多机训练梯度同步且满足 macOS SDK 26.2 与 Thunderbolt 5 互连两条硬门槛JACCL 是目前 MLX 生态里延迟最低的集合通信选择按本文五步搭好环境用自动探测画出连接矩阵再拿 allreduce_bench 的 bus BW 确认链路打满剩下的就是把backendjaccl交给mlx.launch。JACCL 是 MLX 的一部分采用与 MLX 相同的许可证名字读作 Jackal取自 Jack and Angelos Collective Communication Library既是对 NCCL 的致敬也纪念主导 Apple RDMA over Thunderbolt 开发的 Jack Beasley。【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考