exo:把多块设备组成本地AI集群的完整指南,4台Mac跑通671B参数分布式推理

exo:把多块设备组成本地AI集群的完整指南,4台Mac跑通671B参数分布式推理

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

exo 是一个开源的本地 AI 集群项目：它能把多台 Mac、Linux 服务器组建成一个分布式推理集群，让单台设备装不下的大模型被自动切分到多台机器上运行。基于 MLX 推理后端与拓扑感知的自动并行策略，exo 在 4 台 M3 Ultra Mac Studio 上跑通了 Qwen3-235B、DeepSeek 671B 等前沿大模型的本地推理，并提供了 OpenAI / Claude / Ollama 多套兼容 API，让你用现有工具即可直接调用。

一、项目定位：它解决什么问题

大模型本地推理长期面临一个死结：模型越大，单机内存越不够。买一台顶配机器是"暴力解"，成本高且扩展性差。exo 给出的思路是把家里、实验室里闲置的算力"拧"成一股绳：

• 自动发现：任何运行 exo 的设备会自动发现彼此，无需手动配置网络拓扑；
• 越加越快：得益于 Thunderbolt 5 上的 RDMA 支持（延迟降低 99%），增加设备不只是扩大容量，而是真正提升推理速度；
• 零迁移成本：兼容 OpenAI Chat Completions、Claude Messages、OpenAI Responses 和 Ollama 四套 API，现有客户端和工具链可以直接指向 exo 使用。

适合人群：拥有多台 Apple Silicon 设备（或 Linux 服务器）的个人开发者、AI 爱好者，以及想在私有环境里免费运行超大参数模型的团队。

二、核心机制拆解：大模型如何被切到多台机器

理解 exo 不需要懂分布式系统，抓住四个概念即可。

1. 每个节点 = 四合一的角色

每台设备运行同一个 exo 进程，内部并行四个组件（见 src/exo/main.py 与 AGENTS.md）：

组件之间不直接互调，而是通过类型化的 pub/sub 主题通信（src/exo/routing/topics.py），底层网络由 Rust 实现提供（rust/networking/），Python 侧通过 PyO3 绑定（rust/exo_rs/）调用。

2. 拓扑感知的自动放置

这是 exo 区别于"简单把模型分块"的关键。Master 会实时掌握整个集群的设备拓扑图——每台机器的内存、每两条链路之间的带宽与延迟，然后计算最优的切分方案：

• 放置算法在 src/exo/master/placement.py 中实现，支持Pipeline 并行与Tensor 并行两种切分方式；
• 拓扑建模见 src/exo/shared/topology.py；
• MLX 引擎的自动并行策略在 src/exo/worker/engines/mlx/auto_parallel.py。

3. 事件溯源管理集群状态

集群状态采用事件溯源（event sourcing）模式：状态本身是不可变对象（src/exo/shared/types/state.py），所有变化都以事件形式广播，Master 负责索引并下发，各节点用纯函数apply()把事件回放成一致状态（src/exo/shared/apply.py）。这带来一个实用收益：任何节点重启后都能快速恢复出完整的集群视图，而不是各存各的。

三、性能与效果证明：4 台 Mac Studio 的实测数据

官方在 4 × 512GB M3 Ultra Mac Studio 集群上做了多模型实测（RDMA over Thunderbolt 5 全互联），基准截图收录在 docs/benchmarks/ 目录。

Qwen3-235B（8-bit）在 4 台 M3 Ultra Mac Studio 上的 Tensor Parallel + RDMA 实测（数据来源：Jeff Geerling）

DeepSeek v3.1 671B（8-bit）同集群实测——单台设备完全无法承载的模型规模

几个关键数字：

也就是说：在这套集群上，加设备不仅扩容，还在加速——这是 RDMA 低延迟互联带来的直接红利。

四、从 0 到 1 上手：两种部署路径

路径 A：macOS 桌面应用（最省心）

面向普通用户，要求 macOS Tahoe 26.2 或更高版本：

brew install --cask exo

安装后应用常驻菜单栏，首次启动需授权安装一个网络配置 profile（用于节点间组网）。应用内置集群状态监控、节点健康检查（app/EXO/EXO/Services/）与 Thunderbolt Bridge 检测。

路径 B：源码运行（macOS / Linux）

前置工具：uv（Python 依赖管理）、node（构建仪表盘）、rustnightly（构建 Rust 绑定）。macOS 上还需要 Xcode 提供 Metal 工具链。

# 1. 克隆仓库 git clone https://gitcode.com/GitHub_Trending/exo8/exo cd exo # 2. 构建仪表盘（必须先做，否则界面无页面） cd dashboard && npm install && npm run build && cd .. # 3. 启动 uv run exo

启动后仪表盘与 API 同时运行在http://localhost:52415。Linux 用户额外注意：当前 Linux 仅跑 CPU 后端，GPU 支持在开发中（详见 PLATFORMS.md）。

最小可用配置

• 单台设备也能跑：uv run exo后在仪表盘选一个小模型（如mlx-community/Llama-3.2-1B-Instruct-4bit）即可对话，集群能力是渐进叠加的；
• 两台设备：分别启动 exo，自动发现组网后即可把大模型切成 Pipeline 两段；
• RDMA 加速（可选，需 TB5 设备 + macOS 26.2+）：关机 → 长按电源键 10 秒进恢复模式 → Terminal 执行rdma_ctl enable→ 重启。之后 exo 自动接管。

五、周边生态与扩展

1. 四套 API 即插即用

API 适配层位于 src/exo/api/adapters/，完整端点文档见 docs/api.md：

• OpenAI Chat Completions（/v1/chat/completions）：任何 OpenAI SDK 改个 base_url 即可；
• Claude Messages（/v1/messages）：兼容 Anthropic 工具调用格式；
• OpenAI Responses（/v1/responses）；
• Ollama API（/ollama/api/chat、/ollama/api/tags）：OpenWebUI 等现成前端直接接入。

2. 模型下载与 HuggingFace 集成

模型下载由专用协调器管理（src/exo/download/coordinator.py），支持分片下载、断点续传与校验。自定义模型通过一个端点即可注册：

curl -X POST http://localhost:52415/models/add \ -H 'Content-Type: application/json' \ -d '{"model_id": "mlx-community/my-custom-model"}'

3. 自带基准测试工具

仓库内置exo-bench（bench/exo_bench.py），可测量不同放置方案下 prefill 与 token 生成的速度：

uv run bench/exo_bench.py --model Llama-3.2-1B-Instruct-4bit --pp 128,512 --tg 128

4. 能力矩阵

六、避坑与调优：常见问题清单

这些坑官方文档都踩过，提前知道能省大量时间：

1. RDMA 必须全互联：集群内每台设备都要用TB5 线缆直连其他所有设备，星形/链式接法不行；
2. Mac Studio 端口限制：以太网口旁边的 TB5 口不能用于 RDMA；
3. 系统版本必须逐字一致：所有设备的 macOS 版本（含 beta 编号）必须完全相同，否则 RDMA 端口互相发现失败；
4. Linux 目前只有 CPU：想跑 GPU 请等 Linux CUDA 支持（Nvidia DGX Spark 在 Tier 1 路线图中）；
5. 仪表盘必须先构建：跳过npm run build直接启动，页面会空白；
6. 模型放外置硬盘：默认目录可能装不下超大模型，用环境变量指定多个目录，按剩余空间自动选择：

   EXO_MODELS_DIRS=/Volumes/ExternalSSD/exo-models uv run exo

7. 同网段多集群互相串扰：设置EXO_LIBP2P_NAMESPACE=my-dev-cluster隔离集群；
8. 性能调优技巧：改完放置方案后用exo-bench --sharding tensor --repeat 3 --warmup 1对比 pipeline 与 tensor 两种切分，取generation_tps高者；内存吃紧时优先选 4-bit 量化版本；需要深度分析时打开EXO_TRACING_ENABLED=true查看分布式 trace。

七、实战场景与未来方向

适合的场景：

• 私有化大模型推理：数据不出内网，4 台 Mac Studio 即可承载 671B 级模型；
• 开发调试：用 OpenAI/Claude 兼容 API 无缝替换云端端点，本地免费刷 token；
• 多模态实验：开启图像模型后在同一集群里做文生图任务；
• 集群科研：预填充/解码分离（disaggregation）让研究者可以对比不同通信方案的效率。

演进方向（来自 PLATFORMS.md 路线图）：

• Linux + CUDA（Nvidia DGX Spark 等）被列为 Tier 1 目标——Apple Silicon 之外生态的最大增量；
• Windows（CUDA / CPU）与 Linux Vulkan 在更远期规划中；
• 推理侧的图像模型、预填充/解码分离等高级特性仍在快速迭代。

如果你手里正躺着几台吃灰的 Mac，现在把它们插上线、uv run exo一下，可能就是距离"免费跑前沿大模型"最近的一次。

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