carloslfu/slotstream

slotstream – 在配备 48 GB 内存的 Mac 上运行 1250 亿参数的 LLM

它是什么 – 一个原生 Swift 命令行工具（和库），可在 Apple Silicon Mac 上运行 Qwen‑3.8‑Flash‑Next 4 位模型（磁盘占用约 105 GB，1250 亿参数）。它将模型的大部分权重从 SSD 流式传输到一个小型 RAM 缓存中，因此在缓存预热后，48 GB 内存的 Mac 可实现约 12 个 token/秒的生成速度。该二进制文件不依赖 Python，一次下载后即可离线运行，并提供与 Ollama 和 OpenAI 兼容的 HTTP API。

为何重要 – 大规模 LLM 通常需要数十 GB 的 GPU 内存。slotstream 表明，通过巧妙的专家缓存和 4 位量化技术，一台消费级 Mac 无需将整个模型加载到 RAM 中即可运行一个 1250 亿参数的模型。

---

主要特性（如 README 所述）

• 从 SSD 加载模型 – 权重以紧凑的 4 位格式存储（压缩后约 88 GB）。slotstream 在 RAM 中保持一个固定的 专家 缓存槽池，并按需从 SSD 拉取所需部分。
• 自动内存规划 – 启动时，程序根据 Mac 的 RAM、Metal 工作集限制以及 RAM 的 70% 上限自动选择内存目标。您可通过 --memory‑gb 覆盖该设置。
• 快速推理 – 在 48 GB M5 Pro Mac 上，缓存预热后可达到约 12 tok/s；较小的机器也能运行（8 GB RAM 时约 3 tok/s，但可能触发交换）。
• API 兼容性 – 提供：
  • 一个 Ollama 风格的端点（/api/chat），可与 Open WebUI 和 Ollama CLI 一起使用。
  • 一个 OpenAI 风格的端点（/v1/chat/completions），可被任何 OpenAI SDK 使用。
  • 图像支持（base‑64 或 data‑URL 负载），带有视觉塔，额外增加约 0.9 GB 内存计划。
  • 通过 OpenAI 聊天模式和 Vercel AI SDK 网关（fx 代理框架使用）实现工具调用。
• CLI 命令
  • slotstream pull – 从公共 Hugging Face 镜像下载并验证模型（支持断点续传，哈希校验）。
  • slotstream run --prompt "…" – 从终端一次性生成内容。
  • slotstream serve – 启动 HTTP 服务器以供客户端集成。
  • slotstream doctor – 下载前显示内存计划、估算速度和可用磁盘空间检查。
• Swift 包 – 相同引擎可通过 Package.swift 添加到 Swift 项目中，暴露 Planner 和 WeightStore API 以用于自定义应用。
• 推测性解码 – 可选加载 1.5 GB 的“草稿头”以提出候选 token，由主模型验证，当可用 RAM 足够时可实现最高约 24% 的加速。
• 详尽文档 – 包含安装指南、客户端设置、视觉功能、编码代理（fx）、Hermes 工具调用、故障排除、硬件测量和设计细节等文档。

---

系统要求

要求	详情
CPU / GPU	Apple Silicon（M 系列）且支持 Metal。macOS 14+（已测试 14、15、26）。
RAM	最低 8 GB（将大量交换）。推荐 48 GB 以获得全速性能。
磁盘	用于压缩模型（约 88 GB）和二进制文件的约 110 GB 可用 SSD 空间。
其他	无需 Python；二进制文件为自包含的 Swift 可执行文件。

---

典型工作流程

1. 安装 – curl -fsSL https://raw.githubusercontent.com/carloslfu/slotstream/main/install.sh | sh（将 slotstream 放置在 ~/.slotstream/bin）。
2. 检查你的 Mac – slotstream doctor 查看自动选择的内存目标和可用空间。
3. 下载模型 – slotstream pull（一次性，支持断点续传，哈希校验）。
4. 快速测试 – slotstream run --prompt "Why is the sky blue?"。
5. 为应用提供服务 – slotstream serve，并将 Open WebUI、Ollama 或任何 OpenAI SDK 指向 http://localhost:11434。
6. 可选 – 启用视觉功能（--vision on）、推测性解码（--mtp auto）或调整上下文长度（--max-context 65536）。

---

限制与注意事项

• 仅支持特定模型 – 目前仅实现 qwen3.8‑flash‑next:4bit；其他 LLM 家族不兼容。
• 硬件绑定 – 需要 Apple Silicon 和 Metal；目前无 Linux/Windows 支持（计划未来推出“Sevra”产品）。
• 内存压力 – 在低内存 Mac 上，系统可能大量交换，导致生成变慢并可能加速 SSD 磨损。
• 上下文窗口 – 默认 32k token（可通过标志提升至 65k）。长提示仍会产生数秒的预填充开销。
• 视觉准确性 – 图像处理功能正常，但项目未提供视觉问答的基准测试。
• 并发性 – 每个进程仅支持一次生成；多个用户需使用独立进程。

---

哪些人可能使用它

• 开发者：构建本地优先的 AI 助手（如即将推出的 Sevra 应用）并希望在 Mac 上使用快速、离线的 LLM。
• 研究人员：在消费级硬件上实验混合专家模型。
• 高级用户：偏好自包含二进制文件，希望避免 Python/conda 环境。
• 工具构建爱好者：集成 Ollama、OpenAI SDK 或 fx 代理框架。

---

快速参考链接

• 安装脚本 – install.sh
• API 文档 – docs/API.md
• 客户端指南 – docs/CLIENTS.md
• 视觉指南 – docs/API.md#images
• 编码代理指南 – docs/FX.md
• 设计与内存规划器 – PLAN.md
• 性能测量 – MEASUREMENTS.md
• 发布说明 – CHANGELOG.md

---

总结

slotstream 是一个真实、生产级别的推理引擎，通过从 SSD 流式传输权重并管理动态缓存，使一台 Apple Silicon Mac 即可运行 1250 亿参数的 LLM。它以极小的 Swift 二进制文件形式发布，提供标准的 Ollama/OpenAI 端点，支持图像和工具调用，并提供 Swift 库以将引擎嵌入原生 macOS 应用。该项目持续维护，拥有详尽文档和清晰的硬件导向性能模型。