carloslfu/slotstream

Run Qwen3.8-Flash-Next (125B MoE, 104 GB at 4-bit) on Macs with a fraction of that RAM by streaming experts from SSD. MLX + Swift, Ollama-compatible API.

slotstream – 在配備 48 GB RAM 的 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 token；較小的機器也能運作（8 GB RAM 時約 3 token/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 可執行檔。

常見工作流程

安裝 – curl -fsSL https://raw.githubusercontent.com/carloslfu/slotstream/main/install.sh | sh（將 slotstream 放置於 ~/.slotstream/bin）。
檢查你的 Mac – slotstream doctor 以查看自動選定的記憶體目標與可用空間。
下載模型 – slotstream pull（一次性、可續傳、雜湊驗證）。
執行快速測試 – slotstream run --prompt "為什麼天空是藍色的？"。
提供給應用程式使用 – slotstream serve，並將 Open WebUI、Ollama 或任何 OpenAI SDK 指向 http://localhost:11434。
可選 – 啟用視覺功能（--vision on）、預測解碼（--mtp auto），或調整上下文長度（--max-context 65536）。

局限與注意事項

僅支援特定模型 – 目前僅實作 qwen3.8‑flash‑next:4bit；其他 LLM 家族不相容。
硬體限制 – 需要 Apple Silicon 與 Metal；目前無 Linux/Windows 支援（未來「Sevra」產品計畫支援）。
記憶體壓力 – 在低 RAM Mac 上，系統可能大量換頁，導致生成變慢，甚至可能損壞 SSD。
上下文視窗 – 預設 32 k token（可透過旗標提升至 65 k）。長提示仍會產生數秒的預填入成本。
視覺準確度 – 圖像處理功能正常，但專案未提供視覺 QA 的基準測試。
併發性 – 每個程序僅支援一次生成；多使用者需使用獨立程序。

哪些人可能使用它

開發者：正在打造本地優先的 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 應用程式。專案持續維護，文件詳盡，並具明確的硬體導向效能模型。