Exo：分布式本地大模型推理网络部署指南

exo 是由 exo labs 维护的开源项目，口号是「Run frontier AI locally」（在本地运行前沿 AI），GitHub Star 数约 4.8 万，采用 Apache-2.0 协议。exo 把你手头的所有设备连接成一个 AI 集群：不仅能跑下单台设备内存装不下的大模型，还凭借对 RDMA over Thunderbolt 的 day-0 支持，让模型随设备增加而跑得更快。它解决的核心痛点是：前沿大模型动辄需要上百 GB 显存，普通个人用户没有数据中心级显卡，但家里往往有多台 Mac、多台 PC 闲置；exo 让这些设备自动组网、自动分片，把「买不起的大模型」变成「拼起来就能跑」。与传统多机推理方案需要手工配置网络、手工切分模型不同，exo 强调「开箱即集群」：装好启动后设备自动发现、自动选择并行策略、自动暴露兼容主流客户端的 API。本文基于官方 README 完整整理，从核心特性、安装方式、RDMA 配置、API 用法到环境变量进行全面说明，适合手头有多台 Mac 或 Linux 机器、想搭建本地大模型推理集群的读者参考，也适合想把已有 OpenAI/Ollama 客户端无缝迁移到本地集群的用户。

一、项目官方信息

二、官方图片

exo 自带一个用于管理集群和与模型对话的 Dashboard，启动后访问 http://localhost:52415 即可打开，无需额外部署前端。官方截图展示了「4 台 M3 Ultra Mac Studio（每台 512GB 内存）组成的集群，分别加载 DeepSeek v3.1（8-bit）与 Kimi-K2-Thinking（4-bit）」的集群视图；官方还引用了 Jeff Geerling 的实测案例：在 4 台 M3 Ultra Mac Studio 上通过张量并行加 RDMA，跑通 Qwen3-235B（8-bit）、DeepSeek v3.1 671B（8-bit）与 Kimi K2 Thinking（原生 4-bit）等旗舰模型。本文封面采用官方仓库图。

三、核心特性

• 自动设备发现：运行 exo 的设备会自动互相发现，无需任何手动配置。新设备加入网络后即可被集群识别，省去了手工编辑主机列表的麻烦。
• Thunderbolt RDMA：exo 从第一天起就支持 Thunderbolt 5 上的 RDMA，设备间延迟降低 99%。这意味着多台 Mac 直连后，跨设备传张量几乎和本地显存一样快。
• 拓扑感知自动并行：exo 基于实时设备拓扑视图，自动计算把模型拆分到所有可用设备上的最佳方式，综合考虑设备资源与每条链路的网络延迟/带宽，自动选择流水线并行还是张量并行。
• 张量并行：支持模型分片，2 台设备最高提速 1.8 倍，4 台设备最高提速 3.2 倍。
• MLX 后端：使用 MLX 作为推理后端，使用 MLX distributed 做分布式通信，天然适配 Apple Silicon 的统一内存架构。
• 多 API 兼容：同时兼容 OpenAI Chat Completions API、Claude Messages API、OpenAI Responses API 与 Ollama API，现有工具和客户端可直接复用，不需要为 exo 专门改造代码。
• 自定义模型：可从 HuggingFace Hub 加载自定义模型，扩展可用模型范围。

四、环境要求与安装

运行 exo 的设备会自动发现彼此，每台设备都提供 API 与管理台（http://localhost:52415）。Mac 上最简单的方式是使用 macOS App，也可以从源码在 macOS 或 Linux 上运行。官方 README 特别提醒：macOS 26.2 以上版本若要启用 RDMA，务必先看完「在 macOS 上启用 RDMA」一节。

方式 A：macOS App（Mac 上最简单）

exo 提供一个在后台运行的 macOS App，安装后无需碰命令行即可把当前 Mac 接入集群，要求 macOS Tahoe 26.2 或更高版本。可直接下载 EXO-latest.dmg，或用 Homebrew 安装：

brew install --cask exo

App 首次运行会请求修改系统设置与安装新网络配置的权限，官方表示这一体验正在改进。macOS App 还提供自定义命名空间（EXO_ZENOH_NAMESPACE）功能，用于在同一网络上隔离多个 exo 集群、隔离开发/测试集群与生产集群、防止误加入他人集群；该设置在 App 的高级设置中配置，源码运行时则通过同名环境变量设置，命名空间会在启动日志中打印出来便于排查。卸载推荐通过菜单栏图标 → Advanced → Uninstall 完成；若已删除 App，可运行 sudo ./app/EXO/uninstall-exo.sh 清理网络 LaunchDaemon、网络配置脚本、日志与「exo」网络位置，最后还需手动在系统设置的登录项中移除 EXO。

方式 B：从源码运行（macOS）

若已安装 Nix，可直接 nix run .#exo 运行，跳过大部分步骤。常规方式需要先准备：Xcode（提供 MLX 编译所需的 Metal ToolChain）、Homebrew、uv、Node.js（构建 Dashboard）、Rust 稳定版（构建 Rust 绑定），以及可选的 macmon（用于 Apple Silicon 上的 GPU 使用率、功耗与温度监控，未安装时回退到 psutil 只监控内存；注意需按 README 指定的 fork 版本安装，Homebrew 版 macmon 0.6.1 在 M5 上会崩溃）。然后：

git clone https://github.com/exo-explore/exo
cd exo/dashboard && npm install && npm run build && cd ..
uv sync --extra mlx
uv run exo

方式 C：从源码运行（Linux）

前置依赖为 uv、Node.js 18+、Rust 稳定版，可通过 apt 或 Linux 版 Homebrew 安装。注意：目前 exo 在 Linux 上只跑 CPU，GPU 支持仍在开发中；Linux 安装时使用 uv sync --extra mlx-cpu（NVIDIA 用户可选 --extra mlx-cuda13 或 --extra mlx-cuda12）。Linux 下文件位置遵循 XDG 规范：配置在 ~/.config/exo/、数据在 ~/.local/share/exo/、缓存与日志在 ~/.cache/exo/（带自动日志轮转）、自定义模型卡在 ~/.local/share/exo/custom_model_cards/，这些路径都可以用对应的 XDG 环境变量覆盖。常用运行参数：--no-worker 让节点只做网络与编排、不执行推理（适合网络好但 GPU 弱的机器）；--legacy-daemon 以 SysV 风格后台守护进程运行，systemd 和 launchd 应直接前台运行而不加此参数。

五、在 macOS 上启用 RDMA

RDMA（远程直接内存访问）是 macOS 26.2 新增的能力，在任何带 Thunderbolt 5 的 Mac 上可用（M4 Pro Mac Mini、M4 Max Mac Studio、M4 Max MacBook Pro、M3 Ultra Mac Studio）。启用后，多台 Mac 之间可以像访问本地内存一样直接读写彼此内存，省去了网络协议栈的拷贝，这也是 exo 敢承诺「延迟降低 99%」的技术基础。启用步骤：

1. 关机；
2. 长按电源键 10 秒直到启动菜单出现；
3. 选择「Options」进入恢复模式；
4. 在恢复界面的实用工具菜单中打开终端；
5. 输入 rdma_ctl enable 并回车；
6. 重启 Mac。

注意事项：想加入 RDMA 集群的设备必须与集群中其他所有设备直连；线缆必须支持 TB5；Mac Studio 上不能使用紧挨以太网口的那个 Thunderbolt 5 口；源码运行时需使用 tmp/set_rdma_network_config.sh 脚本禁用 Thunderbolt Bridge 并在每个 RDMA 口上设置 dhcp；不同 macOS 版本之间 RDMA 口可能互相发现不了，所有设备的系统版本必须完全一致（包括 beta 版本号）。

启用 RDMA 的意义在于：普通网络下多机传张量是主要瓶颈，而 RDMA 让设备间延迟降低 99%，这也是官方宣称「4 台 M3 Ultra Mac Studio 跑 DeepSeek v3.1 671B（8-bit）」这类基准案例的前提——没有 RDMA，张量并行的加速比会大打折扣。

六、使用方法：API 调用

exo 同时提供四种兼容 API。以小模型 mlx-community/Llama-3.2-1B-Instruct-4bit 为例，完整流程为：

1. 预览实例部署位置：访问 /instance/previews?model_id=...，获得该模型所有合法的分片方案（Pipeline 分片或张量并行）及每个节点的内存增量；可以用 jq 直接筛出第一个无错误的部署方案。
2. 创建实例：向 /instance POST 选中的部署方案，接口异步返回 command_id，再通过 /instance/await?model_id=... 用 SSE 流等待实例就绪；就绪时收到 "type": "ready" 消息，超时则收到 "type": "timeout"，默认无限等待，可通过 timeout_seconds 限定。
3. 发送对话：向 /v1/chat/completions POST 请求，格式与 OpenAI 完全一致，支持流式返回；换模型只需修改请求体中的 model 字段。
4. 删除实例：通过 /state 或 /instance 查到实例 ID 后，向 /instance/{id} 发送 DELETE，释放集群资源。

除 OpenAI 格式外，Claude Messages 格式走 /v1/messages，OpenAI Responses 格式走 /v1/responses，Ollama 格式走 /ollama/api/chat 与 /ollama/api/tags，可直接对接 OpenWebUI 等工具。这意味着你现有的 OpenAI API 客户端代码、Claude 客户端、Ollama 客户端几乎不用改一行，把 base URL 指向 http://localhost:52415 即可。从 HuggingFace 添加自定义模型用 POST /models/add；需要 trust_remote_code 的模型默认禁用，仅在信任其远程代码时显式开启，这是出于安全考虑——因为远程代码会在本地执行。其他常用端点：/models 列出所有模型、/models?status=downloaded 只看已下载、/models/search?query=llama&limit=10 搜索 HuggingFace、/state 查看实例与部署状态。更完整的端点列表与请求/响应类型见仓库中的 docs/api.md 与 src/exo/api/main.py。

七、环境变量

exo 支持以下环境变量做运行时配置，典型用法包括：用只读目录加载 NFS 上预下载的模型、把模型下载到外置 SSD、离线模式运行、启用图像模型支持、用自定义命名空间隔离集群、开启分布式追踪做性能分析等。这些变量既可以在启动命令前临时设置，也可以写进 shell 配置长期生效。

八、基准测试与硬件支持

官方提供 exo-bench 工具，在不同部署配置下测量模型预填充（prefill）与 token 生成速度，帮助优化模型性能、验证改进效果。前提是各节点已经用 uv run exo 跑起来，工具内部走 /bench/chat/completions 端点：

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

关键参数包括 --model（模型短 ID 或 HuggingFace ID）、--pp（提示词长度，逗号分隔）、--tg（生成长度，逗号分隔）、--max-nodes（限制节点数，默认 4）、--instance-meta（按 ring/jaccl 过滤，默认 both）、--sharding（按 pipeline/tensor 过滤，默认 both）、--repeat（每种配置重复次数，默认 1）、--warmup（每种部署预热次数，默认 0）与 --json-out（结果输出文件，默认 bench/results.json）。工具输出每种配置的 prompt_tps、generation_tps 与峰值内存占用。硬件方面，macOS 上 exo 使用 GPU；Linux 上目前仅 CPU，新硬件平台支持欢迎在 Issue 中提需求并点赞，让社区知道哪些硬件最受关注。

九、常见问题（FAQ）

Q：exo 和 Ollama 是什么关系？ A：exo 不取代 Ollama，而是直接兼容 Ollama API，你现有的 OpenWebUI 等客户端可以无感切换到 exo 集群；区别在于 exo 把多台设备自动组成集群跑更大的模型，而 Ollama 主要跑单台设备。

Q：我只有一台 Mac，exo 有意义吗？ A：有。单台 Mac 上 exo 就是一个带 Web 管理台、兼容 OpenAI/Claude/Ollama 多种 API 的本地推理服务；再加入第二台设备时，它会自动把模型分片获得加速。

Q：Linux 上为什么 GPU 用不上？ A：官方明确说明 Linux 平台目前只跑 CPU，GPU 支持在开发中；想要特定硬件支持可到 Issue 区提需求。

Q：如何在同一网络上避免误连别人的 exo 集群？ A：通过 EXO_ZENOH_NAMESPACE 环境变量或 App 的高级设置设置自定义命名空间，只有命名空间相同的设备才会组到一起；这也适合把开发集群和生产集群隔离开。

Q：模型文件存在哪里？可以用外置硬盘吗？ A：默认目录在 ~/.local/share/exo/models（Linux）或 ~/.exo/models（macOS）。通过 EXO_MODELS_DIRS 可以把模型下载目录指到外置 SSD，空间不足时会自动回退到默认目录；通过 EXO_MODELS_READ_ONLY_DIRS 可以让 exo 直接读取 NFS 等共享存储上预下载好的模型，且这些模型不会被删除。

Q：没有网络的环境能跑吗？ A：可以。设置 EXO_OFFLINE=true 后 exo 只使用本地已下载的模型，不访问 HuggingFace；配合只读模型目录，适合在内网或隔离环境中部署。

Q：加入集群的设备必须是 Mac 吗？ A：推理后端目前基于 MLX，因此设备侧的 GPU 加速主要在 macOS（Apple Silicon）上生效；Linux 节点目前以 CPU 方式参与，适合作为协调或编排节点（配合 --no-worker 只做网络调度，不承担推理任务）。

十、跳转链接

• 官方仓库：github.com/exo-explore/exo
• macOS 下载：EXO-latest.dmg
• API 文档：docs/api.md
• 基准测试案例：Jeff Geerling 博客
• Discord：discord.gg/TJ4P57arEm
• 贡献指南：CONTRIBUTING.md

参与贡献请先阅读 CONTRIBUTING.md；想支持新硬件平台，可到 Issue 区 搜索或提交需求，并通过点赞让维护者了解社区最关心的硬件。

总体来看，exo 把「多台个人设备拼成大模型推理集群」这件事的门槛降到了最低：Mac 用户装个 App 即可，开发者从源码一行命令启动，API 层兼容主流客户端，配合 Thunderbolt RDMA 还能逼近多机高带宽互联的效果。对于手头有多台 Mac、又想本地跑旗舰大模型的用户，exo 是目前最值得尝试的方案；想跟进最新进展可以关注官方 X 账号 或加入 Discord。