誰もが TurboQuant について話していて、多くの人が次のように一言でまとめています：
run bigger models on smaller hardware
この一文はキャッチーですが、混乱が始まるのもここです。そしてはい、これも私の最初の推測でした。「いいね！じゃあ、この 24GB のユニファイドメモリ搭載 MacBook で 70B モデルを動かせる」みたいに。
この記事には 2 つの目的があります：
- TurboQuant が実際に何なのか、そして何ではないのかを説明する
- Apple Silicon 向けのローカル実用スタックを示し、TurboQuant が役に立つ場面では活用しつつ、それ以外のセットアップを地獄にしない
ここで紹介するスタックは意図的に控えめです。これは、私たち多くが実際に持っているであろうタイプのマシン向けです：
- Apple Silicon 搭載の MacBook
- メモリ容量が限られたユニファイドメモリ
- 普通の人の予算
- そしておそらく、非合理なほどの自信
Part 1: what TurboQuant is, and what it is not
TurboQuant は 主にモデルの重み（モデルウェイト）サイズを問題として解決するものではありません。
まず、ここをはっきりさせる必要があります。
人々が「より小さなハードウェアで、より大きなモデルを動かせる」と言うとき、通常はもう少し間接的な意味で捉えています：
- 実行時のメモリ使用による負荷（メモリプレッシャー）を減らす
- それによって コンテキスト をより長く使うための、より余裕のあるメモリ予算を確保したり、ヘッドルームを増やしたり、あるいは（やや）大きめの構成を可能にしたりする
しかし、圧縮されるのはディスク上の主要なモデルのチェックポイントではありません。
推論中に使われる KV キャッシュ です。
The missing half of memory optimization
ローカルでの LLM 議論の多くは 重みの量子化 に焦点が当たりがちです：
- GGUF
- AWQ
- 4-bit および 8-bit のモデルバリアント
- メモリに収まるための小さめのチェックポイント
これは有用ですが、物語の半分にすぎません。
推論時のメモリ請求額は、だいたい次のように見えます：
runtime memory = model weights + KV cache
KV キャッシュはコンテキスト長に応じて増えます。プロンプトが大きくなったり、生成が長くなったりすると、このキャッシュが主要な要因になっていきます。
このため、長いコンテキストのタスクは、しばしば人々が想像するよりずっと厳しく感じられます。技術的にはあなたのマシンに収まるモデルでも、次のようなことを始めると、結局は現実的でなくなることがあります：
- RAG プロンプトに大量の取得チャンクを詰め込む
- 長いドキュメントから OCR テキストを掃除する
- 複数のファイルをまとめて要約する
- 大量のソースを貼り付けた状態でコードベースを推論する
What TurboQuant brings
TurboQuant は問題の「実行時」の側面に切り込みます。
大まかに言うと、標準的な FP16 表現よりもはるかに攻めたやり方で KV キャッシュを圧縮しつつ、品質の維持を試みます。
それにより、次のような実用的な利点が生まれます：
- 長いコンテキストでの推論時のメモリ負荷を低減
- より大きなプロンプトのための余裕（ヘッドルーム）を増やす
- 負荷がかかったときの並行性や安定性が向上する可能性
- データセンター向けカードではないハードウェアで、本格的なドキュメント作業を行うためのより現実的な道筋になる
What TurboQuant does not magically do
それは、次を魔法のように実現するという意味ではありません：
- 巨大な任意のモデルが、今すぐあなたのラップトップに心地よく収まる
- すべてのケースで品質が一切損なわれない
- 今日のすべてのランタイムが、ネイティブにそれをサポートしている
- もう重みの量子化は不要になる
正しいイメージは次の通りです：
- 重みの量子化は 脳（brain） を圧縮する
- TurboQuant はモデルの 作業メモリ（working memory） を圧縮する
どちらか一方だけ最適化しても、まだテーブルに置き去りの（活用できる）節約効果が残ります。
Part 2: the engineering decision
すべてを 1 つのランタイムに無理やり詰め込もうとするのではなく、私は分割アーキテクチャを選びました。
Why not just patch everything into Ollama?
同時に次の 2 つを得たかったからです：
- 安定した日常的なローカルエンドポイント
- 長いコンテキストでメモリを多く使う作業のための、より実験的な道
Ollama は最初の目的にとても優れています。シンプルで使いやすく、すでにツールによる幅広いサポートがあります。
2 つ目の目的に対しては、今日の Apple Silicon では小さな MLX ベースの TurboQuant サイドカーのほうが適しています。
その結果、この設計になりました：
client / UI / code tool
|
v
routing proxy :8000
/ \
v v
Ollama TurboQuant sidecar
:11434 :8001
What each piece does
Ollama
Ollama は簡単な道を担当します：
- 短いチャット
- コーディングの支援
- 日常的なやり取り
- コンテキストが小さいタスク
Flash Attention と KV-cache の量子化で設定されているため、すでにいくらかのメモリ節約を得ています。
TurboQuant MLX sidecar
サイドカーは、KV キャッシュの圧が支配的になるジョブを担当します：
- 長い RAG プロンプト
- 大きなドキュメント向けの OCR クリーンアップ
- 複数ドキュメントの統合（マルチドキュメント合成）
- ファイル中心のアシスタント作業フロー
OpenAI と互換のエンドポイントを公開しているため、この API 形に話しかけることをすでに知っているクライアントから利用できます。
Routing proxy
ルーターがバックエンド切り替えの面倒さを取り除きます。
要求を検査し、プロンプトサイズを推定して、それが Ollama へ行くべきかサイドカーへ行くべきかを判断します。
つまり、多くの場合クライアントは 1 つの URL を指すだけで、スタックが妥当な選択をしてくれます。
Part 3: one-command install
私のリポジトリにあるコードには、単一のインストーラが含まれています：
bash install.sh
このインストーラは実用的な作業を行います：
- 推奨される Ollama の環境変数を設定する
- Python 環境を作成する
- FastAPI、MLX、および必要なライブラリをインストールする
- 必要に応じて TurboQuant MLX の依存関係をクローンする
- 自動起動用の LaunchAgent ファイルを作成する
- ルーティングプロキシとサイドカーのスクリプトをインストールする
- Open WebUI の利用メモを書き込む
Why a one-command installer matters
実験的なスタックは、セットアップが考古学プロジェクトになると死んでしまうからです。
新しいマシンごとに、5 つの README タブを開いて、3 か月前の issue コメントを 1 つ読むような儀式が必要なら、そのスタックは本当に使える状態ではありません。
インストーラによって、これを再現可能なベースラインに変えます。
Part 4: how the package is implemented
The sidecar
サイドカーは小さな FastAPI サービスで、次のことを行います：
- MLX モデルを読み込む
- TurboQuant のパッチを適用する
- Transformer レイヤごとに TurboQuant の KV キャッシュを作成する
/v1/chat/completions を公開します
それによって、下流のツールにとってインターフェースが馴染みやすくなります。
ルータ
ルータは、FastAPI の別のサービスで、こちらも /v1/chat/completions を公開します。
そのデフォルトの動作は、意図的にシンプルです：
- 複数のメッセージ長を合算してプロンプトサイズを見積もる
- トークン閾値の下では Ollama を使用する
- その閾値以上では TurboQuant を使用する
tq:のようなモデルプレフィックスで明示的に上書きできるようにする
これは、今後ずっと必要になる最後のルーティング戦略を意味するものではありません。理解しやすく、デバッグしやすく、改善しやすいことを目的にしています。
macOS の LaunchAgents
このスタックはユーザー用の LaunchAgents を使うため、両方のサービスをログイン時に自動で起動できます。
これにより、セットアップは軽量でローカルのまま保たれ、必要がない限り、余計なサービス管理ツールを導入することも避けられます。
第5部：このスタックが他のツールのどこに位置づくか
OpenAI 互換のエンドポイントを公開する理由はシンプルです。多くのツールがすでにそれらの使い方を知っているからです。
Open WebUI
Open WebUI はルーティングプロキシをデフォルトのエンドポイントとして使えます：
http://127.0.0.1:8000/v1
比較やデバッグのために、直指定のエンドポイントを追加することもできます。
Claude Code
あなたの Claude Code のワークフローが OpenAI 互換のローカルエンドポイントをサポートしているなら、ルータは自動的に大きなコンテキストを TurboQuant バックエンドへ押し出せる、単一のターゲットを提供します。
これは、作業負荷が次のように切り替わるときに役立ちます：
- 短いコードに関する質問
- 幅広いコードベースの推論
- ファイル量が多いプロンプト
Antigravity
長いプロンプト、多数のリトリーブチャンク、またはメモリ負荷の高いコンテキスト作業の恩恵を受けるものは、ルーティングされたエンドポイントに自然に適合します。
ルータを使うことで、プロンプトが重くなるたびにバックエンドを手動で切り替える必要がありません。
カスタムスクリプトとエージェントフレームワーク
それらがすでに chat-completions 形式を話せるなら、最小限のつなぎでこのスタックに組み込めます。
（上記のものすべて――そしてそれ以上も――リポジトリの README.md に例があります）
第6部：実用的な例
例1：長文ドキュメントの OCR クリーンアップ
ローカルの OCR パイプラインが、長くてノイズの多いテキストの塊を生成します。
それをルーティングプロキシに送ります。
小さいページは Ollama のままにし、大きいページは TurboQuant 側のサイドカーへ送ります。
例2：複数の PDF に対する RAG
あなたのリトリーバが、いくつかのドキュメントから多数のチャンクを返します。
最終的なプロンプトは大きく、KV キャッシュへの圧力が問題になります。
ルータはリクエストを TurboQuant に押し出します。
例3：コードベース解析アシスタント
「この関数は何をしているか」のような小さな質問は Ollama のままです。
「この6つのファイルを比較し、共有される状態の流れを説明して」のような大きなタスクはサイドカーへ行きます。
例4：Open WebUI での混合インタラクティブ利用
通常のチャットはキビキビ動きます。
テキストの壁を貼り付けて統合を依頼するとき、ルータがそのリクエストを重いバックエンドへ移してくれるため、考えなくても済みます。
第7部：トレードオフと制限
このスタックは便利ですが、魔法ではありません。
トレードオフとしては次のようなものがあります：
- サイドカーは Ollama よりも実験的です
- ルーティングのヒューリスティックは依然としてヒューリスティックです
- 上流リポジトリが API を変更する可能性があります
- モデルの選択は依然としてとても重要です
- 品質と性能は、特定のワークロードに依存します
しかし良い点も本物です：
この仕組みにより、素朴な単一バックエンド構成よりも、控えめな Apple Silicon マシンでも長いコンテキストのタスクをずっとうまくこなせます。
その価値はあります。
参考文献と技術ドキュメント
- Google Research：TurboQuant のブログ記事
- Flash Attention と KV-cache 量子化のための Ollama ドキュメントおよび FAQ
- MLX フレームワークのドキュメント
- MLX LM のドキュメントとモデルエコシステム
-
sharpner/turboquant-mlxリポジトリ - Open WebUI のドキュメント
- Apple launchd および LaunchAgent のドキュメント
- FastAPI のドキュメント
最後にひとこと
ローカル LLM の世界で私が学んだことがあるとすれば、それはこれです：
人は、無限のハードウェアが必要になることよりも、無駄が少ないことを必要とする場合のほうが、はるかに多いのです。
このリポジトリは、その考えを Mac 上で実運用できるようにするための、小さくて少し悪戯な試みです。
貧乏人向けのスタック？はい。
でも 立派 なものです。
