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 を実行する

何であるか – Apple-silicon Mac で Qwen‑3.8‑Flash‑Next 4‑bit モデル（ディスク上では約105 GB、パラメータ数は1250 億）を実行できるネイティブな Swift コマンドラインツール（およびライブラリ）。モデルの大部分の重みを SSD からストリーミングし、小さな RAM キャッシュに保持することで、48 GB の Mac でもキャッシュがウォームアップした後は約 12 トークン/秒の生成が可能になります。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 互換性 – 以下のエンドポイントを提供します：
- Open WebUI や Ollama CLI と連携可能な Ollama 風エンドポイント（/api/chat）。
- 任意の OpenAI SDK で利用可能な OpenAI 風エンドポイント（/v1/chat/completions）。
- 画像対応（base-64 または data-URL ペイロード）で、視覚タワーを追加するとメモリ計画に約 0.9 GB 追加されます。
- OpenAI チャットスキーマおよび fx エージェントフレームワークで使用される Vercel AI SDK ゲートウェイを介したツールコール。
CLI コマンド
- slotstream pull – パブリックな Hugging Face ミラーからモデルをダウンロード・検証（再開可能、ハッシュ検証付き）。
- slotstream run --prompt "…" – ターミナルからワンショット生成。
- slotstream serve – クライアント統合用の HTTP サーバーを起動。
- slotstream doctor – ダウンロード前にメモリ計画、推定速度、空きディスク容量を表示。
Swift パッケージ – 同じエンジンは Package.swift を通じて Swift プロジェクトに追加でき、カスタムアプリ用に Planner と WeightStore API を公開します。
予測デコード – オプションで 1.5 GB の「ドラフトヘッド」をロードし、メインモデルが検証するトークンを提案することで、十分な 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/bin に slotstream を配置）。
Mac の確認 – slotstream doctor で自動選択されたメモリ目標と空き容量を確認。
モデルのダウンロード – slotstream pull（一度限り、再開可能、ハッシュ検証付き）。
簡単なテスト実行 – slotstream run --prompt "Why is the sky blue?"。
アプリ用サーバー起動 – slotstream serve で http://localhost:11434 に Open WebUI、Ollama、または任意の OpenAI SDK を接続。
オプション – 視覚機能を有効化（--vision on）、予測デコードを有効化（--mtp auto）、コンテキスト長を調整（--max-context 65536）。

制限事項と注意点

モデルのみ対応 – 今後は qwen3.8‑flash‑next:4bit のみが実装済み。他の LLM ファミリーは互換性なし。
ハードウェア制限 – Apple-silicon と Metal が必要。Linux/Windows は現時点では対応せず（将来の「Sevra」製品で計画中）。
メモリ圧力 – 低メモリ Mac ではシステムが大量にスワップし、生成速度が低下し、SSD の劣化を引き起こす可能性あり。
コンテキストウィンドウ – デフォルトは 32k トークン（フラグで 65k まで拡張可能）。長いプロンプトは依然として数秒のプリフィルコストを伴う。
ビジョンの精度 – 画像処理は動作するが、視覚的 QA のベンチマークは提供されていない。
並列処理 – 1プロセスあたり1回の生成のみ。複数ユーザーの場合は別々のプロセスが必要。

どのような人に向いているか

開発者 – 今後の Sevra アプリなど、ローカルファーストの AI アシスタントを開発し、Mac 上で高速かつオフラインの LLM を求めている人。
研究者 – コンシューマー向けハードウェアで Mixture-of-Experts モデルを実験したい人。
パワーユーザー – 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 から重みをストリーミングし、動的キャッシュを管理することで、1台の Apple-silicon Mac 上で 1250 億パラメータの LLM を実行可能な本格的なプロダクション用推論エンジンです。非常に小さな Swift バイナリとして配布され、標準的な Ollama/OpenAI エンドポイントを提供し、画像対応やツールコールもサポート。また、ネイティブ macOS アプリにエンジンを埋め込むための Swift ライブラリも提供しています。プロジェクトは積極的にメンテナンスされており、詳細なドキュメントと明確なハードウェア中心のパフォーマンスモデルを持っています。