vllm-metal 分布式推理实战：用 Ray 和雷雳线把大模型拆到多台 Mac

vllm-metal 是面向 Apple Silicon 的 vLLM 硬件插件，基于 MLX 让大模型跑在 Mac 的 GPU 上。这篇文章是一份实战指南：用Ray 分布式执行器加一根雷雳（Thunderbolt）线，把一个模型拆到两台 Mac 上做分布式推理——用流水线并行（PP）承载单机放不下的模型，用数据并行（DP）把吞吐量拉满。

一、什么时候需要"多 Mac 分布式推理"？ 🖥️

单台 Mac 跑 vllm-metal 完全够用，但遇到两种情况时，单机就不够了：

一句话区分：PP 是"一个模型拆着跑"，DP 是"同一模型多副本并行跑"。二者互不兼容，同一批 Mac 只能选其一。

完整官方指南在 docs/distributed.md，建议收藏对照。

二、原理速览：Ray 管控制面，雷雳线管数据面

vllm-metal 的多机推理是一个"双平面"设计，理解这一点就能看懂后面所有命令：

1. 控制面（Ray）：Ray 负责在多 Mac 之间"点名"——每台 Mac 上启动一个 worker 进程，每个 worker 对应一个流水线阶段或一个模型副本。
2. 数据面（MLX ring，走雷雳线）：阶段之间传递的隐藏状态（activation）不经过 Ray，而是走 MLX 自带的点对点send/recv环（ring）后端。雷雳线提供高带宽、低延迟直连——官方文档明确说明 Wi-Fi / 以太网太慢，雷雳是支持的传输方式。

有两处关键适配值得了解（源码都开源在仓库里）：

• Apple GPU 不是 Ray 认识的加速卡（不像 CUDA / TPU），所以MetalPlatform给每台 Mac 注册了一个名为mlx的自定义 Ray 资源，vLLM 的 Ray 执行器按"每个 mlx 资源放一个 worker"的方式排布，见 vllm_metal/platform.py：

  ray_device_key: str = "mlx"

• Ray 默认查不到自定义资源，vllm-metal 通过worker_process_setup_hook在每个 worker 里打了个补丁，让 worker 能读到自己分到的mlx设备，实现见 vllm_metal/compat.py。

流水线切分与跨机传输的核心逻辑（每个阶段只拿一段连续层、阶段 r 从 r-1 收、发给 r+1）实现在 vllm_metal/distributed/pipeline.py。

三、实战：雷雳线 + 流水线并行，两台 Mac 跑一个模型

以官方已验证的Qwen3-0.6B 两 Mac 端到端为例（官方建议先跑小模型验证链路，再换大模型）：Mac A 跑阶段 0（前面的层），Mac B 跑阶段 1（后面的层 + 采样）。

⚠️ 前置条件：两台 Mac 都按 安装文档 装好 vllm-metal，并已安装 Ray（pip install ray）；两台机器都要有模型缓存。

第 1 步：雷雳线直连，配好静态 IP 🔌

用雷雳 / USB4 线直连两台 Mac，macOS 会自动创建 "Thunderbolt Bridge" 接口，各配一个静态 IP：

# Mac A sudo networksetup -setmanual "Thunderbolt Bridge" 10.0.0.1 255.255.255.0 # Mac B sudo networksetup -setmanual "Thunderbolt Bridge" 10.0.0.2 255.255.255.0

在 Mac A 上执行ping -c3 10.0.0.2，通即成功。

还有一个 macOS 特有的坑：.local主机名会解析到本机回环地址（127.0.0.1），另一台 Mac 根本访问不到。需要把主机名映射到雷雳 IP（写进/etc/hosts），详见 docs/distributed.md 中的 "two Macs over Thunderbolt" 一节。

第 2 步：组建 Ray 集群

macOS 上的多节点 Ray 需要两个环境变量，两台机器都要设置：

export RAY_ENABLE_WINDOWS_OR_OSX_CLUSTER=1 # 解锁 macOS 多节点 export RAY_DEFAULT_PYTHON_VERSION_MATCH_LEVEL=minor # 两机 Python 小版本不一致时才需要

然后 Mac A 启动 head（注意把节点 IP 钉在雷雳地址上，并宣告 1 个mlx资源）：

# Mac A VLLM_HOST_IP=10.0.0.1 ray start --head \ --node-ip-address=10.0.0.1 --resources='{"mlx": 1}'

Mac B 通过雷雳 IP 加入：

# Mac B VLLM_HOST_IP=10.0.0.2 ray start --address=10.0.0.1:6379 \ --node-ip-address=10.0.0.2 --resources='{"mlx": 1}'

👉VLLM_HOST_IP是整个流程里最关键的一环：它让 vLLM 的get_ip()返回雷雳地址，跨阶段的传输才会走线缆而不是走别的网络。

第 3 步：一条命令跨机启动服务

# Mac A RAY_ADDRESS=auto VLLM_HOST_IP=10.0.0.1 \ vllm serve Qwen/Qwen3-0.6B \ --distributed-executor-backend ray \ --pipeline-parallel-size 2 \ --tensor-parallel-size 1 \ --no-async-scheduling

看到每个 worker 打印Pipeline stage 0/2与Pipeline stage 1/2、且 MLX ring 引导日志列出两台 Mac 的雷雳 IP，就说明跨机流水线搭好了。

第 4 步：发一条请求验证

curl -s http://10.0.0.1:8000/v1/completions -H 'Content-Type: application/json' \ -d '{"model":"Qwen/Qwen3-0.6B","prompt":"The capital of France is","max_tokens":16,"temperature":0}'

收到正常的补全结果，恭喜——你的第一个多 Mac 大模型服务上线了 🎉 用完在两台 Mac 上都执行ray stop，并把雷雳接口恢复 DHCP 即可。

四、数据并行：模型装得下时，吞吐翻倍的路 ⚡

如果模型本身就装得进一台 Mac，DP 比 PP 更划算：每台 Mac 一份完整副本，单一 API 入口自动负载均衡。Mac A 上这样启动（Ray 集群搭建方式同上）：

RAY_ADDRESS=auto VLLM_HOST_IP=10.0.0.1 \ vllm serve mlx-community/Qwen3-8B-4bit \ --gpu-memory-utilization 0.5 \ --max-model-len 8192 \ --data-parallel-size 2 \ --data-parallel-backend ray \ --data-parallel-size-local 1 \ --data-parallel-address 10.0.0.1

三个容易踩的参数：

• --data-parallel-backend ray必填——默认的mp后端只会在本机拉子进程，无法把副本放到第二台 Mac；
• --data-parallel-size-local 1：每台 Mac 只有 1 块 Apple GPU，所以每节点只能放 1 个副本；
• --data-parallel-address：把 DP 主节点钉到 Ray head 的 IP，避免放置失配。

DP 提升的是并发吞吐而不是单条请求的延迟；head 机器还要额外承担 API server 和负载均衡，所以实测低于 2 倍理想值。可用vllm bench serve量化自己的场景（方法见 docs/benchmarking-macos.md）。

五、常见问题与限制清单 ⚠️

多 Mac 推理还很新，规划时注意以下限制（均摘自 docs/distributed.md）：

另外，Ray 的"资源名 mlx 找不到"类报错（如No available node types can fulfill resource request {'mlx': 1.0}）几乎都是节点没带--resources='{"mlx": 1}'启动；而current platform cpu does not support ray则说明 Metal 插件没激活。排障时先分清是这两类中的哪一种。

六、动手之前，先读懂这些文件 📚

写在最后

vllm-metal 的多 Mac 分布式推理目前处于"已验证、仍崭新"的阶段：单机 Ray 执行器与两 Mac 雷雳流水线都已端到端跑通（Qwen3-0.6B 验证）。建议的路径是——先小模型验证链路，再上大模型；先 PP 突破容量瓶颈，并发上来了再考虑 DP 拉吞吐。把几台闲置的 Mac 用雷雳串起来，你的"本地大模型集群"就能真正跑起来了 🚀