carloslfu/slotstream · 上手攻略

仓库：carloslfu/slotstream
链接：https://github.com/carloslfu/slotstream
分类：LLM推理·本地运行·Apple Silicon
作者：Tom
更新：2026-09-02

这是什么

slotstream 是一个让 125B 参数的 Qwen3.8-Flash-Next（MoE 架构，4-bit 量化后 105 GB）在内存不足的 Mac 上运行的工具。它通过 SSD 顺序流式读取专家权重，配合固定大小的专家槽位池，实现"内存要多少就给多少"的弹性运行。

核心逻辑：模型权重分段存在 SSD，只把当前需要的专家加载进内存，其余躺在磁盘上按需调度。3.8 GB 的 trunk（主干部分）常驻内存，引擎启动时间仅 ~2 秒，峰值内存由机器实际容量决定。

⚠️ 注意：slotstream 专为 Apple Silicon（MLX）设计，x86 硬件不在支持范围内。

解决什么问题

Mac 上跑不动大模型，通常是因为权重太大、全量塞进内存导致交换（swap）崩溃。传统方案靠更快的 kernel 或更高压缩率，而 slotstream 选择了一个更直接的路：承认内存不够，就用 SSD 换内存，用带宽换容量。

适合场景： - 有大硬盘、内存不够跑完整大模型的 Apple Silicon Mac 用户 - 想在笔记本上跑 100B+ 级模型、但不想换机器的开发者 - 需要 Ollama/OpenAI 兼容 API 以对接现有工具链的人

快速安装

一键安装（二进制）

curl -fsSL https://raw.githubusercontent.com/carloslfu/slotstream/main/install.sh | sh

安装路径：~/.slotstream/bin/slotstream，自动加入 PATH。重复运行可升级。

卸载

rm -rf ~/.slotstream
# 然后删除 PATH 中加入的那行（installer 会告知具体位置）

源码编译

需要 Command Line Tools（Xcode 不必需）：

git clone https://github.com/carloslfu/slotstream && cd slotstream
make build

硬件门槛

你的 Mac 内存	slotstream 占用	预估解码速度
8 GB	8.1 GB（地板值）	~3 tok/s
16 GB	10 GB	~4 tok/s
24 GB	16 GB	~8 tok/s
48 GB+	33 GB（上限）	~12 tok/s

⚠️ 表格中 48 GB 以上为实测值；其余为 slotstream doctor --sim-ram N 估算结果，较小机器 SSD 速度更慢，实际速度可能更低。

⚠️ 磁盘必须 ≥110 GB 可用空间（512 GB Mac 是现实最低门槛）。

安装前必做——诊断自己的机器：

slotstream doctor

会打印你的机器计划、是否满足磁盘要求，以及各档位内存预期。

核心用法

下载模型权重（首次）

slotstream pull

会打印 105 GB 总大小、目标路径和磁盘剩余空间，确认后才开始下载。中断安全——支持断点续传，所有文件下载完会校验 sha256。

验证已有副本：

slotstream pull --verify

直接运行（无服务器）

slotstream run --prompt "为什么天空是蓝色的？"

启动 API 服务器（Ollama 兼容）

slotstream serve

监听 localhost:11434，同时实现 Ollama 风格和 OpenAI 风格的端点。

Ollama 格式（curl 示例）：

curl localhost:11434/api/chat -d '{
  "model": "qwen3.8-flash-next:4bit",
  "messages": [{"role": "user", "content": "hello"}]
}'

OpenAI 格式（Python 示例）：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="unused")
r = client.chat.completions.create(
    model="qwen3.8-flash-next:4bit",
    messages=[{"role": "user", "content": "hello"}],
)
print(r.choices[0].message.content)

api_key 任意填写，不做校验（本地服务，无需认证）。

OpenAI SDK 的其他端点

端点	说明
`POST /v1/chat/completions`	OpenAI 格式聊天
`GET /v1/models`	列出可用模型
`POST /api/chat`	Ollama 格式聊天（默认流式）
`POST /api/generate`	Ollama 格式 prompt补全
`GET /api/tags`	Ollama 格式模型列表
`GET /api/ps`	当前内存占用

思考模式（think）

curl localhost:11434/api/chat -d '{
  "model": "qwen3.8-flash-next:4bit",
  "messages": [{"role": "user", "content": "解释量子隧穿"}],
  "think": true
}'

think: true 时，模型先输出推理过程（在 message.thinking 字段），再输出答案（在 message.content），两者完全分离，不会混入同一段文字。

采样参数默认值

参数	默认值
temperature	0.7
top_p	0.8
top_k	20
min_p	0
presence_penalty	1.5
max_tokens	512（≤0 = 吃满 context）

Speculative Decoding（MTP）

模型自带一个 1.5 GB 的 draft head 做"预测下一个 token 再验证"的投机解码，命中率约 86%。--mtp 默认 auto——有足够专家缓存时自动开启，不够时关闭。开启后在 48 GB Mac 上测得 ×1.24–×1.33 的解码加速。

典型适用场景

本地开发调试：不想把 API key 暴露给第三方，用 Ollama/OpenAI SDK 在本地跑 100B 级模型
内存受限的 Mac 用户：有 48 GB MacBook Pro 但跑不满全量模型
低延迟本地推理：prompt prefill 之后流式解码 ~12 tok/s（48 GB，实测），可接受的中等速度本地推理
模型对比/评测：Ollama 兼容接口，切换后端方便

坑与注意

磁盘空间是硬门槛：至少 110 GB 可用，512 GB Mac 是现实最低配，256 GB 用户基本无法使用
网络速度决定首次下载体验：pull 用 8 并发连接，数据中心 1 Gbit/s 链路测速 112 MB/s（~16 分钟）；100 Mbps 家庭宽带约 2 小时 20 分；25 Mbps 宽带约 9 小时
prompt 阶段慢：8,000 token 的 prompt 在 48 GB Mac 上需约 1 分钟处理完才出第一个 token；对话续聊时只 prefills 新增部分，速度保持稳定
context 上限 32,768 token：serve --max-context 只能降低不能提高；这是 slotstream 实测过的上限，不是模型的原始 262,144 token 能力
不支持 embeddings：/api/embed 和 /api/embeddings 均返回 400
不支持 tools / images / JSON-schema / logprobs：这些请求会返回明确 400 而非静默忽略
Ollama CLI 暂不支持：Ollama 命令行工具暂未适配，只有 WebUI 和 OpenAI SDK 经过测试

与同类对比

项目	适用硬件	内存要求	API 兼容	特殊能力
slotstream	Apple Silicon Mac	弹性（最低 8 GB）	Ollama + OpenAI	SSD 流式，MTP 投机解码
llama.cpp	通用（CPU/GPU）	全量加载	无官方 API	最高通用性
MLX-LM（Apple）	Apple Silicon	全量加载	无官方 API	Apple GPU 优化
Ollama	通用	全量加载	Ollama	生态丰富，模型多

slotstream 的核心差异化是内存弹性：同样跑 Qwen3.8-Flash-Next，8 GB Mac 也能跑，只是慢；llama.cpp/Ollama 在内存不够时直接崩溃或进入巨量 swap。

一句话结论

如果你在用 Apple Silicon Mac、想跑 100B+ 大模型、但内存不够——slotstream 是目前唯一把"SSD 流式专家"做到生产级可用（Ollama 兼容 API + 完整工具链）的方案；唯一代价是需要一块足够大的 SSD。