Qwen3.8-Flash-Next の Mac 向け実行環境：容量不足でも動作可能化

Qwen3.8-Flash-Next（1250 億パラメータの Mixture-of-Experts モデル）を、ディスク容量が十分でないように見えても動作させることができます。このモデルは通常、4 ビット量化で 104 GB のディスク領域を必要としますが、Slotstream を使うことで SSD からデータをストリーミングして読み込み、与えられたメモリ制限内で実行可能です。

主な特徴

• 単一 Swift バイナリ：Python は不要です。
• 既存ツールの互換性：Ollama および OpenAI チャット API を実装しており、既存のクライアントは変更なしで動作します。
• 自動メモリ調整：マシンの RAM 量に応じて自動的に最適化されます。

パフォーマンスとシステム要件（48 GB M5 Pro の場合）

48 GB のメモリを搭載した Mac（M5 Pro チップ）での实测値です。

• ウォームデコード速度: 約 12 トークン/秒
• エンジン起動時間: 約 2 秒（3.8 GB の主干部分のみ読み込みます）
• ピークメモリ使用量: 32 GB（自動調整、上限を指定も可）
• ディスク上の全量ファイル: 104 GB

Mac での動作条件確認

⚠️ 重要: メモリ容量だけでなく、SSD の空き容量がボトルネックになります。メモリ不足でも 512 GB SSD を持っていれば動作しますが、ディスク領域が不足している場合は起動しません。

各メモリティアでの推定性能

slotstream doctor --sim-ram N

💡 自動サイズ調整: システム全体を使い尽くすことはなく、安全に動作します。小型 Mac は SSD の読み込み速度が遅いため、理論値よりも低速になる可能性があります。インストール前に必ず

slotstream doctor

を実行して推奨プランを確認してください。

インストール方法

1. リリース版のインストール

最新のリリースを

.~/.slotstream/bin/

.~/.slotstream

2. セキュアな検証（重要）

ビルドは CI（継続的インテグレーション）で署名され、元データの出所証明（Provenance）が付けられています。 blindly に信じるのではなく、以下のように検証してダウンロードします：

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

3. ソースコードからのビルド

Xcode は不要で、コマンドラインツールのみで動作します：

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

104 GB のファイルダウンロードについて

バイナリ自体は軽量ですが、モデルの重み（Weights）が 103.8 GB（24 ファイル分）と大きいです。

slotstream pull

serve/run

ダウンロードにかかる時間

Hugging Face の制限速度（約 36–57 MB/s）のため、インターネット回線によって以下のように変化します。

• 100 Mbps: 約 2 時間 20 分
• 25 Mbps: 約 9 時間

中断しても安全です（再開機能）

• 途中からの再開:

  pull

  コマンドは以前から進捗を保存し、読み込まれたチャンクのみ再処理します。
• 完全な整合性保証: 全 24 ファイルについて SHA-256 ハッシュ値との照合が行われ、破損したファイルはエンジンに到達しません。
• フォールバック: 固定コミットのミラーとオリジナルリポジトリの両方がハッシュチェックで検証可能です。
• 再ハッシュ化: 既存コピーを再確認するには

  pull --verify

  を実行します（本稿では 8 秒）。

使用方法

クイックテスト（サーバー起動なし）

コマンドラインからすぐに質問できます：

slotstream run --prompt "why is the sky blue?"

API サーバーとしての起動

ポート 11434 でリスニングし、Ollama クライアントや OpenAI SDK が利用可能なチャットエンドポイントを提供します。

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

互換性と制限事項

• 対応: Open WebUI、OpenAI SDK、Ollama CLI（一部）、ストリーミング、CORS、標準サンプリングオプションは正常に動作します。
• 未対応機能: ツール呼び出し、画像入力、JSON スキーマ出力、ログプロブなどは明確な HTTP 400 エラー を返します（静かに無視するのではなく）。
• 詳細仕様とエラーリストは

  docs/API.md

  を参照してください。

速度に関する特性

• 推論（デコード）: 比較的容易です（約 12 トークン/秒）。
• プロンプト処理がボトルネック: プロンプト全体を最初のトークン生成前に処理するため、待機時間が発生します。
  • 48 GB Mac: 8,000 トークンのプロンプトで約 1 分
  • 16 GB Mac: 同サイズで約 3 分弱
• コンテキスト制限: プログンプトと生成の合計 32,768 トークン に制限されます（

  --max-context

  フラグ）。

コスト削減効果（対話時の速度向上）

会話中に発生する「最初のトークン生成までの待機時間」は、初回のみに限られます。フォローアップターンでは新規部分のみの事前計算を行うため、後続のターンでは待機時間が劇的に短縮されます。

例: 16 GB 環境で 8 ターン以上重ねた場合、最後ターンの待機時間は 25.8 秒 → 6.0 秒 に短縮されます。 ※完全な再現性を求める場合は

--no-prefix-cache

フラグを使用してください。

メモリ管理について

デフォルト設定（フラグなし）では、マシン環境に合わせ自動調整します（例：48 GB Mac での出力）。

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

自動調整の仕組み

• 戦略: 設定可能な 3 つの制限の中で最も小さい値を採用し、他のアプリがメモリを使っている間も縮小します。
• 上限: 33 GB（測定曲線の膝部分。128 GB マシンでもこのプランを使用します）。
• 動的調整: 実行中は 15 秒ごと に再チェックを行い、リクエスト間のキャッシュ容量を調整（圧力が高いときは縮小、低ければ拡張）します。

上限を自分で設定する方法

以下のフラグを使用してください：

• --memory-gb G

  : プロセス全体の総メモリ容量指定（最低 8.1 GB）。実験目的なら 33 GB 以上も可能です。

• --max-ram-percent P

  : メモリ使用率の上限変更（例：70%）。

• --experts-per-layer / --pool-gb

  : キャッシュ容量の直接指定。

slotstream doctor

動作原理

モデルデータは主に以下の場所から読み込まれます（SSD ストリーミング方式）：

1. 経路化された専門家（Routed Experts）：68 GB（各レイヤーに 512 個、アクティブはトークンあたり 10 個）。
2. N-gram テーブル：32 GB。

これらは

pread

なぜ mmap のみではダメなのか？

Apple の ML フレームワークである MLX は、メモリマップされたテンソルの一部を現実化（Materialize）できません。Top-10 専門家の集計演算にはそのレイヤー全体の専門家が必要となるため、単純な

mmap

mlx_lm.load()

注意点: キャッシュサイズは速度に影響しますが、出力内容（バイト単位）には影響しません。4 GB と 24 GB のキャッシュ間で結果は同一です。

ステータスと制限事項

現状の動作環境は M5 Pro (48 GB) を中心に測定されており、小型マシンについては推定値となります。

• モデル制限: v0 版は

  qwen3.8-flash-next:4bit

  のみを動作させます（ロック付き、1 つのプロセスのみ）。
• OS 対応: macOS 14, 15 インストーラーで動作確認済みですが、ランタイム検証は未完了です。
• Ollama CLI の接続: 現状非対応です。厳格なバリデーターにより

  /api/show

  が拒否され、最初のメッセージに到達する前に停止します（修正版の提供待ち）。

v0.2.0 新機能：推論（Speculative Decode）

詳細は

CHANGELOG.md

--mtp auto|on|off

• 精度: 最初の草案が 86% の確率で正しいことが確認されています。
• 速度向上: キャッシュ容量が大きい場合（目標メモリ > 26 GB）、1.5–1.9 倍の速度向上が期待されます。逆に小さい場合は低下します。
• 有効化条件: 「auto」モードでは、公式リリースから 4.9 GB をダウンロードし、

  mtp.safetensors

  (1.5 GB) を生成する必要があります（

  Tools/mtp_convert.py

  で作成）。ファイルがない場合は機能しません。

ドキュメント一覧

• docs/API.md: エンドポイント、フィールド、サンプリングデフォルト、エラーリスト。
• docs/TROUBLESHOOTING.md: ポート競合、ページング、重量ファイルの移動/検証方法。
• docs/CLI.md: コマンド・フラグ一覧、メモリパラメータ優先順位、環境変数、保存場所。

  slotstream <command> --help

  で詳細確認可能。
• CHANGELOG.md: リリースごとの変更履歴。
• PLAN.md: アーキテクチャ設計とマイルストーン。
• MEASUREMENTS.md: 測定値の詳細な説明（失敗した実験含む）。
• llms.txt: AI エージェント向けの全体マップ。

テスト・検証スイート

Tools/verify.sh

• 重量ファイルのプロヴェネンスとバージョン照合。
• キャッシュサイズおよびライブリサイズ間の一貫性チェック。
• サーバークラッシュを招く入力に対する堅牢性テスト。

また、

Tools/e2e_release.sh

ライセンス

全体は MIT です。

• Sources/SlotstreamCore/Vendored/GatedDelta.swift

  :

  mlx-swift-lm

  (MIT) からの移植。

• Tools/reference/qwen4_exp.py

  : コミュニティのテストオラクルとしてベンダー提供。
• 重量ファイル (

  pipenetwork/Qwen3.8-Flash-Next-MLX-4bit

  ) は Qwen Community License で配布されています。