Exo 分布式推理集群：从单台 Mac 到多节点加速的完整实操指南

Exo 分布式推理集群：从单台 Mac 到多节点加速的完整实操指南

【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exo

Exo 是一个分布式推理集群工具：把多台设备自动组网成一个推理集群，让单机内存装不下的大模型可以拆到多台设备上加载，并且随设备增加继续提速。适合手上有几台 Apple Silicon 设备、想本地跑数百 B 参数模型、又希望现有客户端不用改协议的人。

三步跑通：最小可用的多节点推理

环境检查

• Python 3.13（用 uv 管理）、Node.js 18+、Rust nightly——macOS 与 Linux 通用
• macOS 另需 Xcode（提供 MLX 编译用的 Metal Toolchain）
• Apple Silicon 硬件监控需要 macmon 工具
• 要启用 RDMA：macOS 26.2+、Thunderbolt 5 设备，节点间全互联，且各设备系统版本完全一致

最小可运行配置

git clone https://gitcode.com/GitHub_Trending/exo8/exo cd exo/dashboard && npm install && npm run build && cd .. uv run exo

macOS 上也可走 GUI 路径：装官方 app（要求 macOS Tahoe 26.2+），启动后授权安装网络配置，应用常驻菜单栏即可。

验证成功的标志

启动后浏览器打开http://localhost:52415，能看到 dashboard 的集群视图和本地节点卡片；执行curl http://localhost:52415/models返回内置模型列表，说明 API 已就绪。单台 MacBook 作为节点运行的界面如下。

架构速览：从发现到张量并行

数据流向：客户端请求 → 协调层放置决策 → 各节点 MLX 引擎 → 流式回传。

核心模块拆解

• placement.py — 调度层：结合实时拓扑与内存约束，计算模型在各设备上的可行分片方案
• runner.py — 节点运行器：承接任务、分发到推理引擎、上报进度、支持取消
• builder.py — MLX 推理引擎：加载模型、构建张量并行分片与 KV 前缀缓存
• networking/src/swarm.rs — Rust 网络层：节点自动发现与发布/订阅消息通道

设计取舍

• 选 MLX 而非 CUDA 后端：原生针对 Apple Silicon 优化，免驱动层；代价是 Linux 目前只能跑 CPU
• 没有中心服务器：任何节点都能当协调层做放置决策，少一个单点故障
• 张量并行/流水线分片由调度层按链路带宽自动选，用户不手动配置

实测数据：RDMA 与 TCP 的吞吐对比

Qwen3 235B A22B（8-bit）解码吞吐，Exo（RDMA）对 llama.cpp（TCP）：

测试环境：4 台 512GB M3 Ultra Mac Studio，Thunderbolt 5 全互联；数据来自 Jeff Geerling 的集群测试，仓库内同图见 docs/benchmarks/。官方同时声明：Tensor Parallel RDMA 把 TB5 链路上节点间延迟降低 99%；张量并行在 2 台/4 台设备上分别最高提速 1.8 倍/3.2 倍。注意 TCP 方案节点越多吞吐反而越低，RDMA 路径则随节点数继续提升。

进阶与扩展：基准、自定义模型与调优

常用集成

• exo-bench — 测 prefill/decode 吞吐，对比不同放置方案 — 走/bench/chat/completions端点
• HuggingFace 自定义模型 — 把 HF 上的模型拉进集群 —POST /models/add接口
• 环境变量配置 — 存储/离线/隔离 —EXO_MODELS_DIRS、EXO_OFFLINE、EXO_LIBP2P_NAMESPACE

exo-bench 输出 prompt_tps、generation_tps 与峰值内存，可直接对比 ring 与 jaccl、pipeline 与 tensor 两类方案。

性能调优清单

• 优先启用 RDMA → 节点间延迟降低 99%；前提是线缆全互联支持 TB5、各设备 macOS 版本完全一致
• 网络好但算力弱的机器用--no-worker只挂协调层 → 避免参与推理拖累整体
• 模型目录指到外挂 SSD（EXO_MODELS_DIRS）→ 系统盘空间紧张时的下载兜底
• 加载前用/instance/previews预览全部可行放置 → 先选 pipeline 还是 tensor，再拉起实例

常见问题与坑

• 节点互相发现不了？基本是不在同网段或命名空间不同。用EXO_LIBP2P_NAMESPACE统一命名空间，并确认同一二层网络。
• RDMA 端口发现失败？官方明确 RDMA 口在不同 macOS 版本间可能互相不可见。检查所有设备版本完全一致（beta 版本号也要相同）。
• 内存不够装不下模型？换 4-bit 量化版本或减少参与节点，用/instance/previews看各放置的memory_delta_by_node再决定。
• Linux 想用 GPU？目前 Linux 仅 CPU 推理，GPU 支持开发中，可装mlx-cuda12/mlx-cuda13extra 试 CUDA 版 MLX。

以上端点细节见 docs/api.md。

适用边界

• 适合：Apple Silicon 多机组网、跑单机内存装不下的大模型；给现有工具提供 OpenAI/Claude/Ollama 兼容 API 的本地推理替代；用闲置 Mac 做推理原型验证
• 不适合：Linux 生产推理（GPU 支持尚在开发）；追求最低首字延迟的线上服务——多机张量并行与单机高带宽方案相比没有延迟优势

官方接口文档见 docs/api.md，完整安装与 RDMA 配置以仓库 README 为准。

【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exo