很多人在家里攒下不止一台带独立显卡的机器:一台新装的台式机、一台淘汰下来的旧主机、可能还有一台常年开着的迷你主机。单看每台的显存都不算大,加起来却往往能放下一个中等规模的模型。难点不在硬件,而在怎么让它们"看起来像一台机器"——统一调度、统一入口、把请求分到合适的设备上。这篇教程走一遍完整流程:装好环境、让节点互相发现、决定模型怎么放、把请求路由过去,最后实测一次跨设备的吞吐。
适用场景
适合手上有 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-a | 192.168.1.10 |
| 工作节点 | node-b | 192.168.1.11 |
| 工作节点 | node-c | 192.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,避免新节点拖垮整组。删节点前先把流量摘掉再停进程,不要直接拔电源。
