3分钟跑通 Exo：本地分布式 AI 集群环境配置与安装排错全攻略-编程实验室

3分钟跑通 Exo：本地分布式 AI 集群环境配置与安装排错全攻略

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

exo 把多台本地设备自动组成一个 AI 集群，让单卡装不下的大模型跑起来，设备越多还越快。这篇文章带你从零完成环境配置和依赖安装，3 分钟看到它真的能跑，再附上常见报错的排错方法。

最小安装路径：先看到它跑起来

别急着看原理，先把这两步敲完。装 exo 需要 Node（构建 dashboard）、uv（Python 依赖管理）和 Rust nightly（编译 Rust 绑定），下面默认 macOS 用 brew，Linux 把brew install uv node换成sudo apt install nodejs npm加 uv 官方安装脚本即可：

brew install uv node curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup toolchain install nightly

然后克隆、构建 dashboard、启动：

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

最后一行会启动集群节点，dashboard 和 API 落在http://localhost:52415。验证一下：

curl http://localhost:52415/models

返回 JSON 模型列表，说明环境通了。如果机器上装了 Nix，macOS 用户可以直接nix run .#exo，跳过大部分前置步骤。

开工前体检：硬件与软件要求

安装前先对一遍清单，能省掉一半的报错时间。

硬件：exo 对单机没有硬性门槛，关键是"集群总内存装得下模型"。几个可行组合：

2 × 8GB 内存的 M3 MacBook Air，跑 8B 级模型
4 × 512GB M3 Ultra Mac Studio，能跑 671B 级模型（官方 benchmark 配置）
1 台 16GB 内存的 RTX 4070 Ti 笔记本（Linux 上目前跑 CPU，GPU 支持开发中）
3 × 4~8GB 树莓派 / 小内存设备凑总内存，速度不追求

软件：

组件	版本要求	说明
Python	必须 3.13	pyproject.toml 里写死`requires-python = "==3.13.*"`，这是排错第一大坑
uv	≥ 0.8.6	负责解析锁定好的依赖并自动选 3.13，装它就不用手动折腾 venv
Node.js	≥ 18	只用来构建 dashboard
Rust	nightly	构建 Rust 绑定 exo-rs
Xcode（macOS）	最新稳定版	提供 Metal 工具链，MLX 编译需要
macmon（macOS）	仓库指定的 fork 版本	Apple Silicon 硬件监控，Homebrew 的 0.6.1 在 M5 上会崩

依赖方面，核心依赖版本在 pyproject.toml 里已锁定解析（见 uv.lock），比较关键的一批：

aiohttp>=3.12.14 # 异步 HTTP，dashboard API 底座 pydantic>=2.11.7 # 数据校验 huggingface-hub>=1.8.0 # 模型下载 transformers>=5.6.2 # 模型分词与配置 rustworkx>=0.17.1 # 图算法，算集群拓扑 exo-rs # 工作区内的 Rust 绑定，uv 会现场编译

Apple Silicon 还会拉mlx==0.32.0、mlx-lm、mflux==0.17.5及torch==2.10.0；NVIDIA 路线走mlx-cuda12/mlx-cuda13加nvidia-ml-py>=13.595.45。这些都不用你手动敲，uv sync一次到位。

安装实操：三种场景按需选

推荐路径：uv 一把梭

uv sync --all-packages uv run exo

uv sync --all-packages会在仓库根建好.venv、按 uv.lock 装齐全部依赖，并连同 rust/exo_rs 一起编译出 exo-rs 绑定；uv run exo则永远在这个环境里执行，不污染系统 Python。

手动控制安装：建环境 → 核心依赖 → 平台扩展

想逐层掌控的话，按这个顺序来：

# 第一层：建环境。必须 3.13，装不上就先用 uv 装一个 python3.13 -m venv .venv source .venv/bin/activate

Windows 上激活是.venv\Scripts\activate。

# 第二层：核心依赖 + Rust 绑定 uv sync --all-packages

# 第三层：平台扩展，四选一 uv sync --all-packages --extra mlx # Apple Silicon uv sync --all-packages --extra mlx-cpu # Linux CPU uv sync --all-packages --extra mlx-cuda12 # Linux + NVIDIA CUDA 12 uv sync --all-packages --extra mlx-cuda13 # Linux + NVIDIA CUDA 13

extras 之间互斥，uv 会拦截你同时装两个，不用担心装错。

平台特调：Apple Silicon 的 RDMA 与 NVIDIA 的 CUDA 选择

Apple Silicon 多机要快，靠的是 macOS 26.2 的 Thunderbolt 5 RDMA。启用流程：关机 → 长按电源键 10 秒进恢复模式 → 终端执行rdma_ctl enable→ 重启。注意三件事：每台设备必须直连所有其他成员、线缆要支持 TB5、各设备 macOS 版本必须完全一致（连 beta 号都要一致）。脚本tmp/set_rdma_network_config.sh会自动关掉 Thunderbolt Bridge 并给各 RDMA 端口配 DHCP。

NVIDIA 用户不需要额外调参，差别只在第二层装哪个 extra：驱动是 CUDA 12 选mlx-cuda12，CUDA 13 选mlx-cuda13，对应 torch 的 cu128/cu130 索引 uv 会自动挑。目前 Linux GPU 整体还在 Tier 1 计划中（首个目标是 DGX Spark），遇到性能问题先参考下面踩坑表。

把设备连起来：多端组网与 Dashboard

每台设备各自跑一遍uv run exo就行，节点通过 libp2p 广播自动发现彼此，不需要任何手动配置。

打开http://localhost:52415，dashboard 提供四个核心功能：

集群拓扑视图，实时看设备连接关系与资源
模型选择与 HuggingFace 搜索、分片下载进度
聊天窗口，直接和跑在集群上的模型对话
多 API 兼容：OpenAI Chat Completions、Claude Messages、OpenAI Responses、Ollama 四种格式任选

同网段想隔离多个集群，设EXO_LIBP2P_NAMESPACE=my-dev-cluster再启动即可。

踩坑速查表

症状：uv run exo报 Python 版本不匹配，或requires-python ==3.13.*冲突 →原因：系统只有 3.12/3.11，exo 严格要求 3.13 →修复：

uv python install 3.13 && uv run exo

症状：下载模型或访问 HuggingFace 报 SSL/certificate 错误（macOS） →原因：Python 没挂系统证书 →修复：

/Applications/Python\ 3.13/Install\ Certificates.command

症状：依赖装了一半报版本冲突、exo_rs构建失败 →原因：环境里有残留包与 uv.lock 打架 →修复：

uv sync --all-packages --force-reinstall --no-cache

症状：Linux 上跑起来但速度明显不如预期 →原因：Linux 目前走 CPU 推理，GPU 支持还在开发中，不是配置问题 →修复：暂无命令可解，关注平台支持路线图，或用--no-worker把弱机器降级为纯协调节点。

症状：模型下载慢或超时（国内网络） →原因：直连 huggingface.co 不通畅 →修复：

HF_ENDPOINT=https://hf-mirror.com uv run exo

症状：Apple Silicon 两台机器组成集群后没有加速 →原因：RDMA 没启用，或两台 macOS 版本不一致 →修复：按上文恢复模式执行rdma_ctl enable，并核对sw_vers完全一致后重启两台机器。

跑通验证与下一步

最小验证：启动后浏览器打开http://localhost:52415，在聊天页选一个小模型（比如 4bit 的 Llama 3.2 1B），发一句话，看到流式回复吐字即代表"下载 → 分片 → 加载 → 推理"整条链路全通；嫌模型大，就用终端curl http://localhost:52415/models先确认能列出模型。

下一步可以做的事：再开一台设备跑uv run exo，看 dashboard 里拓扑自动多出一个节点；把你的 OpenAI/Claude/Ollama 客户端指向localhost:52415直接复用现成工具链；用uv run bench/exo_bench.py对比不同分片方式下的 prefill 与解码速度。

参考：