跳到主内容
快讯直播
AI智模界
教程

用 Superfluid 把家里几台机器拼成推理集群

很多人在家里攒下不止一台带独立显卡的机器:一台新装的台式机、一台淘汰下来的旧主机、可能还有一台常年开着的迷你主机。单看每台的显存都不算大,加起来却往往能放下一个中等规模的模型。难点不在硬件,而在怎么让它们"看起来像一台机器"——统一调度、统一入口、把请求分到合适的设备上。这篇教程走一遍完整流程:装好环境、让节点互相发现、决定模型怎么放、把请求路由过去,最后实测一次跨设备的吞吐。

适用场景

适合手上有 2 到 4 台带 NVIDIA 显卡的机器、处在同一个家庭局域网内、希望在家跑本地模型的开发者。解决的核心问题是"显存不够但机器不止一台":与其租显卡或者等一张大显存卡,不如把闲置设备组织成一个集群,对外只暴露一个 OpenAI 兼容接口。

同样适合想把实验环境复现出来的小团队——家里这套拓扑和工作里的多机部署逻辑是一致的,先在本地跑通,理解节点发现、模型放置、请求路由这三个环节,迁移到机房时不会手忙脚乱。

环境与前置条件

操作系统与运行时:各节点使用同一发行版家族(推荐 Ubuntu LTS 或同源发行版),内核版本尽量一致,避免 NCCL 通信时的兼容性麻烦。需要 NVIDIA 驱动 + CUDA 运行时,具体版本要求以 Superfluid 官方文档当前版本为准;一条实用原则是所有节点装同一个驱动大版本,用 nvidia-smi 输出的 Driver Version 核对。

网络:所有机器接在同一台交换机或同一个路由器的 LAN 口下,不要跨 NAT、不要走 Wi-Fi 做节点间通信。每台机器配静态 IP 或者路由器上做 DHCP 绑定,因为集群配置里要写死地址。千兆网能跑通,但张量并行这类需要频繁 all-reduce 的模式下会成为瓶颈,2.5G 或万兆更从容。至少留一个网口给集群通信,别和下载、视频流量抢带宽。

显存与内存估算:权重占用大致是「参数量 × 每参数字节数」。FP16 约 2 字节/参数,INT8 约 1 字节,INT4 约 0.5 字节。7B 模型 FP16 约 14GB,加上 KV cache 和框架开销,实际预留要再乘 1.2 到 1.5。多机切分时,各节点显存要按最慢的那台对齐。

磁盘:每个节点准备足够的本地空间放模型权重(一个 7B 的 FP16 权重就是十几 GB),或者用一台机器做 NFS 共享模型目录,省掉重复下载。

其他:各节点时间必须同步,否则节点注册和 token 校验会莫名其妙失败。

分步骤部署

第 1 步:固定地址并打通网络

先给每台机器定好角色和 IP。假设有三台:

角色主机名IP
控制节点node-a192.168.1.10
工作节点node-b192.168.1.11
工作节点node-c192.168.1.12

在每台机器上确认网卡名和链路速率:

```bash

ip -br addr

ethtool eth0 | grep -i speed

```

ip -br addr 应该能看到上面规划的地址,ethtool 输出的 Speed 应该是 1000Mb/s 或更高。低于预期就换网线、换交换机口。

配好静态地址后,从每台机器 ping 另外两台,并确认 MTU 一致(不一致会导致大包被丢弃,表现为"能 ping 通但传大文件卡死"):

```bash

ping -c 3 192.168.1.11

ip link show eth0 | grep mtu

```

再确认时间同步:

```bash

timedatectl status

```

输出里 System clock synchronized: yes 才算过关。不是的话装 chrony 或 systemd-timesyncd 并启用。

第 2 步:装驱动并确认 GPU 可见

每台机器上执行:

```bash

nvidia-smi

```

成功的标志是能看到 GPU 列表、显存总量和驱动版本,并且没有 "Failed to initialize NVML" 之类的报错。把三台机器的输出放在一起对比,驱动版本尽量一致。

如果要用容器方式跑,再确认容器运行时能访问 GPU:

```bash

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

```

镜像 tag 以官方文档当前版本为准。这条命令能打印出和宿主机一样的 GPU 列表,说明容器到驱动的链路是通的。

第 3 步:安装 Superfluid

按照官方仓库 README 的安装章节操作。常见形态有两种:包管理器安装,或者从源码安装。源码安装的通用形态:

```bash

git clone <官方仓库地址>

cd <仓库目录>

python3 -m venv .venv

source .venv/bin/activate

pip install -U pip

pip install -e .

```

安装完成后先别急着配置,跑一遍帮助命令确认 CLI 可用:

```bash

superfluid --help

superfluid --version

```

能打出子命令列表就算装好了。这一步很重要:不同版本的子命令名字和参数名会有差异,后面所有命令请先用 --help 对照一遍再执行,本文给出的命令形态只作流程参考。

三台机器都要装,并且版本保持一致——版本不一致是节点加入失败的常见原因。

第 4 步:在控制节点初始化集群

在 node-a 上初始化,指定监听地址和集群通信端口:

```bash

superfluid cluster init \

--listen 0.0.0.0 \

--advertise 192.168.1.10 \

--port 8000

```

参数名以 superfluid cluster init --help 为准。初始化成功后会输出一个加入令牌(join token)或者生成一个配置文件,把它记下来,工作节点要用。

记下之后立刻验证控制节点自身的状态:

```bash

superfluid cluster status

```

预期能看到集群 ID、控制节点地址、当前成员数为 1。

第 5 步:工作节点加入集群

在 node-b 和 node-c 上分别执行加入命令,指向控制节点地址和刚才拿到的令牌:

```bash

superfluid node join \

--server http://192.168.1.10:8000 \

--token <上一步的令牌>

```

成功的输出会包含"joined"或"registered"字样,并显示本节点的 ID。回到控制节点查看成员列表:

```bash

superfluid node list

```

三台机器都在列表里、状态为 Ready,说明节点发现这一环通了。这时如果哪台显示 Pending 或 Offline,先看它的日志:

```bash

journalctl -u superfluid -n 100 --no-pager

或者前台运行时直接看终端输出

```

第 6 步:决定模型放置策略

这是整个方案里最需要动脑的一步,有两条路:

路线 A:分片并行。 如果官方文档支持把模型按层切到多台机器上(张量并行或流水并行),就把一个模型跨节点铺开。好处是能跑单机放不下的模型;代价是节点间通信量大,千兆网下会明显拖慢,需要 2.5G 以上。配置里通常要写每个节点的层分配或并行度:

```yaml

model:

name: <模型名>

path: /data/models/<模型目录>

parallel:

tensor: 3 # 参数名以官方文档为准

placement:

  • node: node-a
  • node: node-b
  • node: node-c

```

路线 B:多副本 + 路由。 每台机器各自加载一份完整模型,控制节点按负载把请求分给空闲节点。好处是对网络几乎没要求,千兆也够,坏处是每台都要放得下完整权重。如果三台都能放下 7B 模型,这条路最省心。

无论走哪条,先把模型权重放到每台机器的约定路径下,并且确认目录可读:

```bash

mkdir -p /data/models

du -sh /data/models/<模型目录>

ls /data/models/<模型目录> | head

```

第 7 步:启动服务与请求路由

在控制节点启动推理服务,并指定对外端口。对外暴露一个 OpenAI 兼容端点,其他程序就能直接用标准 SDK 调:

```bash

superfluid serve --config ./cluster.yaml --host 0.0.0.0 --port 8080

```

启动成功的标志是日志里出现监听地址、模型加载完成、所有工作节点就绪。然后把请求路由配置成"按节点负载分发"或"按模型分片路由",具体字段名以官方文档为准。

如果你希望开机自启,用 systemd 托管:

```ini

/etc/systemd/system/superfluid.service

[Unit]

Description=Superfluid inference cluster

After=network-online.target

Wants=network-online.target

[Service]

Type=simple

ExecStart=/opt/superfluid/.venv/bin/superfluid serve --config /etc/superfluid/cluster.yaml --host 0.0.0.0 --port 8080

Restart=on-failure

RestartSec=5

User=superfluid

[Install]

WantedBy=multi-user.target

```

```bash

sudo systemctl daemon-reload

sudo systemctl enable --now superfluid

sudo systemctl status superfluid --no-pager

```

验证部署是否成功

第一层:进程与成员。 控制节点上 superfluid node list 三台都是 Ready,superfluid cluster status 显示健康。

第二层:接口可达。 列出模型:

```bash

curl -s http://192.168.1.10:8080/v1/models | python3 -m json.tool

```

预期返回一个 JSON,data 数组里有你配置的模型名。

第三层:能出 token。 在另一台机器上发起一次推理,确认请求确实穿过了网络:

```bash

curl -s http://192.168.1.10:8080/v1/completions \

-H "Content-Type: application/json" \

-d '{"model":"<模型名>","prompt":"用一句话解释什么是张量并行。","max_tokens":64}' \

| python3 -m json.tool

```

预期返回包含 choices[0].text 和 usage 字段的 JSON。如果用的是 chat 模型,把路径换成 /v1/chat/completions、把 prompt 换成 messages 数组。

第四层:确认跨设备。 请求发出时在另一台机器上观察显存:

```bash

在 node-b 上

watch -n 1 nvidia-smi

```

如果走的是分片模式,应该能看到多台机器的显存同时被占用;如果走多副本,发多次请求应该看到负载在节点间轮转。

第五层:实测吞吐。 用下面的脚本打并发,这是判断这套集群到底值不值的关键数据:

```python

import json, time, threading, urllib.request

URL = "http://192.168.1.10:8080/v1/completions"

MODEL = "<模型名>"

PROMPT = "用三句话说明为什么家庭局域网带宽会影响多机推理速度。"

N = 8

MAX_TOKENS = 128

results = []

def one(_):

body = json.dumps({

"model": MODEL, "prompt": PROMPT, "max_tokens": MAX_TOKENS

}).encode()

req = urllib.request.Request(

URL, data=body, headers={"Content-Type": "application/json"})

t0 = time.time()

with urllib.request.urlopen(req, timeout=600) as r:

data = json.loads(r.read())

results.append((time.time() - t0, data["usage"]["completion_tokens"]))

threads = [threading.Thread(target=one, args=(i,)) for i in range(N)]

t0 = time.time()

for t in threads: t.start()

for t in threads: t.join()

wall = time.time() - t0

tokens = sum(tok for _, tok in results)

lat = sum(dt for dt, _ in results) / len(results)

print(f"并发 {N}:总耗时 {wall:.1f}s")

print(f"输出 {tokens} tokens,吞吐约 {tokens/wall:.1f} tok/s")

print(f"单请求平均延迟 {lat:.1f}s")

```

跑三组对比记下来:单机跑同一模型时的 tok/s、集群多副本模式的 tok/s、集群分片模式的 tok/s。多副本模式下集群吞吐应该接近单机之和(受网络和路由开销略微折损);分片模式下吞吐提升有限甚至下降是正常的,它换来的是"能跑下更大的模型"。把这个对比数据存下来,以后调参有基线。

常见报错与解决

报错:Driver/library version mismatch 或 Failed to initialize NVML: Driver/library version mismatch

原因:内核模块里的驱动版本和用户态库不一致,通常是系统自动升级了驱动包但没重启。

解决:

```bash

cat /proc/driver/nvidia/version

nvidia-smi

sudo reboot

```

重启后版本对不上就重装驱动包,并让所有节点保持一致。

报错:节点加入后一直显示 Pending / Offline,控制节点日志里看不到该节点心跳

原因:防火墙拦了集群通信端口,或者节点时间不同步导致令牌校验失败。

解决:

```bash

控制节点上放行同网段

sudo ufw allow from 192.168.1.0/24

时间同步

sudo timedatectl set-ntp true

timedatectl status

```

放行后再重新 join 一次。

报错:Address already in use

原因:端口被之前的进程占着,多半是上次没正常退出。

解决:

```bash

sudo ss -lntp | grep 8080

sudo kill -9 <PID>

```

或者改 --port 换一个端口。

报错:多机通信时报 NCCL 相关错误,或训练/推理卡在 "init_process_group"

原因:机器有多块网卡(比如一个有线一个无线),NCCL 选错了网卡。

解决:显式指定网卡名:

```bash

export NCCL_SOCKET_IFNAME=eth0

export GLOO_SOCKET_IFNAME=eth0

```

用 ip -br addr 确认哪块是集群网卡,再重启服务。

报错:CUDA out of memory,加载模型时崩

原因:权重加 KV cache 超过了单节点可用显存,尤其多副本模式每台都要放完整模型。

解决:降低精度(INT8/INT4)、减小 max_model_len 或 batch size,或者改成分片模式把模型摊到多台机器上。

报错:小请求正常,长 prompt 会卡住或超时

原因:链路 MTU 不一致,大包被丢。

解决:

```bash

ip link show eth0 | grep mtu

sudo ip link set eth0 mtu 1500

```

让所有节点 MTU 一致后重试。

后续维护

备份:集群配置文件、加入令牌、/etc/superfluid/ 下的所有内容单独存一份,最好纳入版本管理(令牌除外)。模型权重不必备份,重新下载或从共享目录拷即可,但要把模型目录结构和配置里写的路径记录下来。

升级:先把控制节点停掉,再逐个升级工作节点,最后升级并启动控制节点。升级前用一个固定 prompt 跑一遍基线测试,升级后重跑对比 tok/s 和输出质量,确认没有退化。版本号以官方文档当前版本为准,不要让各节点长期跑不同版本。

日志:用 journalctl -u superfluid -f 跟实时日志,或者 journalctl -u superfluid --since "1 hour ago" 回看。日志体积会涨,给 journald 设个上限:编辑 /etc/systemd/journald.conf,把 SystemMaxUse 设成几百 MB,然后 sudo systemctl restart systemd-journald。

监控:把 nvidia-smi 的采样做成定时任务,观察显存和利用率趋势:

```bash

nvidia-smi --query-gpu=timestamp,utilization.gpu,memory.used,memory.total,temperature.gpu \

--format=csv -l 5 >> /var/log/gpu.csv

```

配合 df -h /data 看磁盘、sar -n DEV 5 看网卡流量。跨节点推理最怕的不是慢,是某一台悄悄掉线后请求全压到剩下机器上——所以把 superfluid node list 的健康状态做成定时巡检,掉线就告警。

散热与功耗:多台机器同时满载,房间温度和插座负载都要留意。给机器设个功耗上限(nvidia-smi -pl <瓦数>),比事后跳闸省事。

扩展:加新机器时,先确认驱动版本、Superfluid 版本、模型路径三者和现有节点一致,再执行 join,避免新节点拖垮整组。删节点前先把流量摘掉再停进程,不要直接拔电源。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。