carloslfu/slotstream

源码: https://github.com/carloslfu/slotstream

slotstream

在内存不足以加载 Qwen3.8-Flash-Next 的 Mac 上运行该模型。模型在4位量化下大小为104 GB；slotstream通过SSD流式传输模型，并将其运行在你提供的任何内存中，最低计划下限为8.1 GB。这是一个单一的Swift二进制文件，包含常用的Ollama和OpenAI聊天/生成端点。

它能在我的Mac上运行吗

磁盘是第一个遇到的瓶颈。 你需要约110 GB的可用空间，因此无论内存多大，512 GB磁盘的Mac是最低的现实要求。权重是一次性下载的104 GB：快速网络下不到一小时，慢速网络则需数小时（见下表）。

仅48 GB行的数据是在真实硬件上测量的；其余数据来自同一测量曲线，且更小的Mac也配备较慢的SSD。在下载任何内容之前，运行 slotstream doctor 查看你的机器能获得什么表现，以及是否有足够的磁盘空间存放权重。

安装

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

将预编译的二进制文件安装到 `~/.slotstream/bin` 并将其添加到你的PATH中。需要Apple Silicon和macOS 14+。重新运行同一行命令即可升级；使用 `rm -rf ~/.slotstream` 卸载。

发布版本由CI从带标签的提交构建，并带有签名的来源证明，因此你可以自行验证资产而非信任下载：

``bash
gh attestation verify slotstream-arm64.tar.gz --repo carloslfu/slotstream

或者自行构建——只需命令行工具，无需Xcode：

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

### 104 GB 下载

二进制文件很小；权重不然。24个文件总计103.8 GB，一次性下载。`serve` 和 `run` 命令会在首次运行时提供下载，而 `slotstream pull` 命令会独立执行：

``bash
slotstream serve

无论哪种方式，它都会打印文件大小、目标位置和你的可用磁盘空间，并在传输前等待你确认；如果磁盘无法容纳，它会直接拒绝。

瓶颈在于Hugging Face，而非你的网络连接。 超过四个并发连接后，速度会达到平台期：4、8、16和32个连接都落在相同的36至57 MB/s范围内，Hugging Face自家最快的客户端 hf_xet 也是如此，而同一网络连接到普通主机时能达到134 MB/s。因此，超过约400 Mbps后，更大的带宽并无助益：

一次真实安装耗时35分钟；顶行范围较宽是因为Hugging Face自身的吞吐量在会话间有所波动。其下各行是根据你的全速额定速度对103.8 GB进行的算术计算，因此请将其视为最佳情况。

中断是安全的：它会从停止的确切字节恢复，并且所有24个文件都会根据编译进二进制文件的sha256哈希进行校验，因此截断、大小相同或损坏的下载无法到达引擎。pull --verify 可在10秒内重新哈希现有副本——这里并行哈希耗时7.7秒。

使用它

serve 监听端口11434，并实现Ollama客户端和OpenAI SDK使用的聊天/生成子集：

``bash curl localhost:11434/api/chat -d ‘{ “model”: “qwen3.8-flash-next:4bit”, “messages”: [{“role”: “user”, “content”: “hello”}] }’

``bash
OLLAMA_HOST=http://localhost:11434 ollama run qwen3.8-flash-next:4bit

Open WebUI、Ollama CLI和OpenAI SDK均已针对此子集进行测试。流式传输、CORS和常见的采样选项（temperature、top_p、top_k、min_p、presence_penalty、seed、num_predict、stop）均受支持。不支持的语义如工具、图像、JSON模式输出、对数概率和替代模型名称会返回清晰的400错误，而非被静默忽略。

对话中的后续轮次仅预填充新增内容，因此随着聊天增长，首个token的时间保持稳定——在八轮对话中测量为6.0秒，而非攀升至25.8秒。一个值得了解的结果是：重用此状态与重新计算并非逐比特相同，因此在两个token势均力敌时回复可能偶尔出现差异。如果需要精确重现，可使用 --no-prefix-cache 关闭此功能。

提示加补全的长度上限为32,768个token（--max-context）。长提示是耗时的主要方面：在16 GB Mac上预填充速度约为50 tok/s，在48 GB Mac上约为125 tok/s，因此一个8,000 token的提示需要等待大约一到三分钟才能获得首个token。每个用户锁确保一次只运行一个模型进程。

内存管理

不带标志时，slotstream会自动调整以适应你的机器，并告知你其选择。这是一台48 GB Mac——它显示为52 GB，因为此处所有计算均使用十进制GB，而Apple将同一内存标称为48：

slotstream memory plan (auto) device: 52 GB RAM (36.0 GB reclaimable now), 40.2 GB Metal working set target: 33.0 GB total for this process (override: --memory-gb N | --max-ram-percent P) cache: ~152 of 512 experts per layer (7280 global slots = 20.1 GB pool) expect: ~32.0 GB peak, ~12 tok/s warm decode (est. from M5 Pro anchors) prefill: 4096 tokens per pass (~125 tok/s here; costs ~5.3 GB of the target) reuse: up to 32768 tokens across 4 conversations (~1.2 GB), so a follow-up turn re-prefills only what is new

它取三个限制值中的最低值：33 GB、RAM的70% 和 Metal 工作集限制，并且当其他应用程序实际占用内存（而非被系统交换出去）时，它会进一步缩小规模。

33 GB是关键数值。这不是礼貌性限制，而是性能拐点：这是专家缓存能清除解码平台期，同时预算仍能负担快速4,096 token预填充通过的最小目标值。以1 GB为步长进行扫描，34到84 GB之间没有任何设置能改进这两个指标。因此，64 GB或128 GB的Mac请求与48 GB Mac相同的33 GB——额外内存无法带来收益，doctor 命令会说明这一点，而非让你猜测。它在运行时也保持弹性：每15秒重新检查一次，并在请求间调整缓存大小，在压力下收缩，平静后重新增长。输出在调整大小时保持字节一致。

--max-ram-percent P 可调整70%的份额，无需你自行计算GB值。另外两个限制仍然适用，因此它可以降低目标值，但无法将其提升超过拐点。

三个标志可以直接完全替代自动设置，第一个生效，并且如果你愿意尝试，它们中的任何一个都可以超过33 GB——完整的专家驻留（每层所有512个，因此无路由专家SSD读取；n-gram行仍然流式传输）需要约88 GB，且从未经过测量：

• --memory-gb G — 进程的总内存。最小值8.1。
• --experts-per-layer N — 直接设置缓存大小，范围为模型的512个专家。每个成本0.133 GB。
• --pool-gb G — 原始池大小。

slotstream doctor 会打印上述任何设置将产生的计划，--sim-ram / --sim-available 可预览另一台机器，而 --json 会以未舍入的估计值输出脚本所需的计划。

工作原理

模型的大部分字节存在于两个位置：68 GB的路由专家（每层512个，每个token激活10个）和32 GB的n-gram表。密集的骨干网络仅3.8 GB且保持常驻。专家通过 pread 读取到所有48层共享的固定缓存槽池中，因此热层可以从冷层借用槽位。

缓存大小改变速度，永不改变输出。 4 GB缓存和24 GB缓存之间的贪婪解码是字节一致的，这种等效性是一项常规测试。

为什么不直接mmap文件？MLX无法物化内存映射张量的一部分：top-10专家收集会评估该层的所有512个专家，16行n-gram查找会评估整个250 MB分片，因此mmap路径会加载约100 GB并崩溃。标准的 mlx_lm.load() 路径使这台48 GB机器进入48 GB交换空间而未产生一个token。

状态与限制

可工作，并在一台机器（配备48 GB内存的M5 Pro）上进行了测量。较小的内存层级数据是从其曲线推导得出的，而非在16 GB真实硬件上运行。

已知不足：

• 长提示启动缓慢。 提示中的所有内容在首个token出现前都已处理。预填充的每个token速度比生成快约10倍（约113 tok/s 对比约11 tok/s），但你需要为每个提示token预先支付此时间：一个15 token的提示在2秒内启动，一个8,000 token的提示则需要约70秒。在对话中你只需支付一次——后续轮次会重用先前的状态。计算现在占据了大部分时间，而缩短它意味着使用分组GEMM内核。
• macOS 14和15 仅测试了安装程序，未测试运行时。

PLAN.md 包含设计和里程碑跟踪器；MEASUREMENTS.md 包含此处所有数字及其方法，包括失败的实验。

测试

Tools/verify.sh 是验收测试套件——81项检查，涵盖权重来源、与版本匹配的Python参考实现的黄金标准、跨模拟机器的规划器行为、跨缓存大小和实时调整的字节一致性、--memory-gb 承诺，以及一组曾导致服务器崩溃的输入的服务器健壮性测试。

Tools/e2e_release.sh 针对通过 curl | sh 安装的二进制文件运行另外31项测试，这是用户实际获得的版本。

无需权重的部分（规划器、采样器与numpy参考实现对比、管控策略、API健壮性）在CI中针对每个发布版本运行。

许可证

MIT。Sources/SlotstreamCore/Vendored/GatedDelta.swift 移植自mlx-swift-lm (https://github.com/ml-explore/ml-explore/mlx-swift-lm) (MIT)，而 Tools/reference/ 包含了用作测试预言的社区脚本 qwen4_exp.py。权重来自 pipenetwork/Qwen3.8-Flash-Next-MLX-4bit (https://huggingface.co/pipenetwork/Qwen3.8-Flash-Next-MLX-4bit) 并遵循Qwen社区许可证。