antirez/ds4 - Metal向け DeepSeek V4 Flash ローカル推論エンジン
(github.com/antirez)- Apple Metal GPU に最適化された DeepSeek V4 Flash 専用のローカル推論エンジンで、汎用 GGUF ランナーではなく単一モデルに集中したネイティブ C 実装
- DeepSeek V4 Flash はアクティブなパラメータ数が少なく、高速を実現し、thinking モードでは他モデル比で 1/5 程度の短い思考区間を生成
- 100 万トークンのコンテキストウィンドウと極度に圧縮された KV キャッシュにより、ローカル環境でも長文脈推論が可能で、ディスク KV キャッシュ永続化をサポート
- OpenAI および Anthropic 互換の HTTP API サーバーを内蔵し、Claude Code、opencode、Pi など多様なコーディングエージェントと即座に連携可能
- llama.cpp と GGML エコシステムを土台に構築され、GPT 5.5 の強力なコーディング支援を受けて開発されたプロジェクト
プロジェクト概要と設計思想
ds4.cは DeepSeek V4 Flash 専用の小型ネイティブ推論エンジンであり、汎用 GGUF ランナーや他ランタイムのラッパーではない- 中核経路は DeepSeek V4 Flash に特化した Metal グラフ実行器で、DS4 専用のロード、プロンプトレンダリング、KV 状態、サーバー API の接着コードを含む
- ローカル推論分野には優れたプロジェクトが多い一方、新しいモデルが次々に登場することで関心が分散する問題がある
- このプロジェクトは 一度に一つのモデルに意図的に集中し、公式ベクトル検証（logits）、長文脈テスト、エージェント統合まで実施
- ローカル推論のビジョンは、A) HTTP API を含む推論エンジン + B) 特定エンジン向けに最適化された GGUF + C) コーディングエージェント実装によるテストと検証、この 3 つが連動すること
- Metal 専用であり、将来的に CUDA をサポートする可能性はあるが未確定
- CPU 経路は正確性検証用としてのみ存在し、現在の macOS バージョンの 仮想メモリ実装バグにより CPU コード実行時にカーネルクラッシュが発生
- GPT 5.5 の強力な支援を受けて開発され、人間がアイデア、テスト、デバッグを主導
DeepSeek V4 Flash を別エンジンにした理由
- アクティブなパラメータが少なく、より高速な推論速度を実現
- thinking モードでは他モデル比で 1/5 程度の短い思考区間を生成し、思考区間の長さは 問題の複雑さに比例
- 他モデルが thinking モードで実用にならない状況でも DeepSeek V4 Flash は利用可能
- 100 万トークンのコンテキストウィンドウをサポート
- 284B パラメータ規模で、27B、35B モデルと比べて 知識の境界領域でより多くの情報を持つ
- イタリア語のテレビ番組や政治関連の質問などで差を確認できる
- 英語とイタリア語の 文章品質が準フロンティアモデル級
- KV キャッシュが極度に圧縮されており、ローカルコンピュータで長文脈推論が可能で、ディスク KV キャッシュ永続化もサポート
- 特殊な方式で量子化した場合、2 ビット量子化でも良好に動作し、128GB RAM の MacBook で実行可能
- 今後 DeepSeek から V4 Flash の更新版が出る見込み
llama.cpp および GGML への謝辞
- ds4.c は GGML にリンクしていないが、llama.cpp プロジェクトが切り開いた道の上に成り立っている
- llama.cpp のカーネル、量子化フォーマット、GGUF エコシステム、ハードウェア寄りのエンジニアリング知識が不可欠な参考資料
- 一部のソースレベルコードは MIT ライセンスのもとで維持または適用されている: GGUF quant レイアウトとテーブル、CPU quant/dot ロジック、特定の Metal カーネルなど
- LICENSE ファイルに GGML 著作者の著作権表示を維持
モデル重み
- このプロジェクト専用に公開された DeepSeek V4 Flash GGUFのみが動作し、任意の DeepSeek/GGUF ファイルとは互換性がない
- 2 ビット量子化には 非対称量子化方式を適用
- MoE エキスパートのみを量子化: up/gate は
IQ2_XXS、down はQ2_K - 共有エキスパート、プロジェクション、ルーティングなど残りのコンポーネントは 量子化せず品質を確保
- MoE エキスパートのみを量子化: up/gate は
./download_model.sh q2で 128GB RAM マシン向け、./download_model.sh q4で 256GB 以上の RAM マシン向けモデルをダウンロード- Hugging Face（
antirez/deepseek-v4-gguf）からダウンロードし、curl -C -により部分ダウンロードの再開をサポート
- Hugging Face（
./download_model.sh mtpで任意の **投機的デコーディング（speculative decoding）**対応 GGUF をダウンロード可能- MTP/投機的デコーディング経路はまだ実験的で、現時点ではわずかな速度向上のみを提供
速度ベンチマーク
--ctx 32768、--nothink、greedy デコーディング、-n 256設定での単発実行 Metal CLI 数値- MacBook Pro M3 Max, 128GB (q2)
- 短いプロンプト: prefill 58.52 t/s、生成 26.68 t/s
- 11709 トークンのプロンプト: prefill 250.11 t/s、生成 21.47 t/s
- q4 はメモリ不足のため N/A
- Mac Studio M3 Ultra, 512GB (q2)
- 短いプロンプト: prefill 84.43 t/s、生成 36.86 t/s
- 11709 トークンのプロンプト: prefill 468.03 t/s、生成 27.39 t/s
- Mac Studio M3 Ultra, 512GB (q4)
- 短いプロンプト: prefill 78.95 t/s、生成 35.50 t/s
- 12018 トークンのプロンプト: prefill 448.82 t/s、生成 26.62 t/s
CLI の使い方
-pオプションで ワンショットプロンプトを実行し、-pなしで実行すると 対話型マルチターンチャットモードに入る- 対話型 CLI はレンダリング済みチャットのトランスクリプトとライブ Metal KV チェックポイントを保持し、各ターンが前の会話を拡張する
- 便利なコマンド:
/help、/think、/think-max、/nothink、/ctx N、/read FILE、/quit- Ctrl+C で現在の生成を中断し、プロンプトに戻る
- デフォルトは thinking モードで、
/nothinkまたは--nothinkで直接応答モードに切り替え --mtp MTP.gguf --mtp-draft 2で任意の MTP 投機経路を有効化可能- greedy デコーディングでのみ有用で、confidence gate（
--mtp-margin）を使って遅い部分受理を防げる
- greedy デコーディングでのみ有用で、confidence gate（
サーバー
- OpenAI/Anthropic 互換の ローカル HTTP サーバーを実行可能
- Metal 専用で、1 つの変更可能なグラフ/KV チェックポイントをメモリ内に保持
- ステートレスなクライアントが同じプロンプトのより長い版を再送すると、共有プレフィックスの再利用が可能
- リクエスト解析とソケット処理はクライアントスレッドで実行されるが、推論自体は 単一の Metal ワーカーを通じて直列化される
- 現在のサーバーは複数の独立リクエストをバッチ処理せず、同時リクエストは順番待ちになる
-
サポートされるエンドポイント
GET /v1/models、GET /v1/models/deepseek-v4-flashPOST /v1/chat/completions、POST /v1/completions、POST /v1/messages
-
/v1/chat/completions（OpenAI 互換）messages、max_tokens/max_completion_tokens、temperature、top_p、top_k、min_p、seed、stream、stream_options.include_usage、tools、tool_choiceをサポート- ツールスキーマは DeepSeek の DSML ツールフォーマットでレンダリングされ、生成された DSML ツール呼び出しは OpenAI ツール呼び出しへ逆変換される
-
/v1/messages（Anthropic 互換）- Claude Code スタイルのクライアント向けエンドポイント
system、messages、tools、tool_choice、max_tokens、temperature、top_p、top_k、stream、stop_sequences、thinking 制御をサポート- ツール使用は Anthropic
tool_useブロックとして返される
- どちらの API も SSE ストリーミングをサポートし、thinking モードでは推論過程がネイティブ API 形式でストリーミングされる
エージェントクライアント連携
- ds4-server は OpenAI 互換の chat completions を使うローカルコーディングエージェントと連携可能
- 128GB RAM で 2 ビット quant（81GB）を動かす場合、100k〜300k トークンのコンテキストウィンドウが適切
- フル 1M トークンコンテキストでは約 26GB のメモリ（圧縮インデクサのみで約 22GB）を使用
384000の出力制限設定によりトークン上限回避が可能（モデルは最大 384k トークンまで生成可能）-
opencode 連携
~/.config/opencode/opencode.jsonに provider と agent 項目を追加して設定baseURLをhttp://127.0.0.1:8000/v1に指定
-
Pi 連携
~/.pi/agent/models.jsonに provider 設定を追加- DeepSeek の thinking フォーマット、reasoning effort 対応、ストリーミング usage 対応などの互換オプションを含む
~/.pi/agent/settings.jsonでデフォルトモデルに設定可能
-
Claude Code 連携
- Anthropic 互換エンドポイントを使い、
~/bin/claude-ds4ラッパースクリプトで環境変数を設定 ANTHROPIC_BASE_URLをローカルサーバーに向け、すべてのモデル変数をdeepseek-v4-flashに設定- Claude Code は初回に約 25k トークンの大規模プロンプトを送るため、
--kv-disk-dirの有効化が必須- 最初の高コスト prefill 後、ディスク KV キャッシュが保存済みプレフィックスを再利用し、後続セッションでプロンプト全体を再処理する必要がなくなる
- Anthropic 互換エンドポイントを使い、
Thinking モード
- DeepSeek V4 Flash は non-thinking、thinking、Think Max の 3 つのモードをサポート
- サーバーのデフォルトは thinking モード
reasoning_effort=maxで Think Max を要求できるが、コンテキストサイズがモデルカード推奨値に対して十分大きい場合にのみ適用- 小さいコンテキストでは通常の thinking にフォールバック
- OpenAI
reasoning_effort=xhighは通常の thinking にマッピングされ、Think Max ではない - 直接応答が必要な場合は
thinking: {"type":"disabled"}、think:false、またはdeepseek-chatのような non-thinking モデル別名を使用
ディスク KV キャッシュ
- Chat/completion API は ステートレスのため、エージェントクライアントは毎リクエストで会話全体を再送する
- ds4-server はレンダリング済みトークン列をキャッシュ済みトークンプレフィックスと比較して処理する
- ライブなインメモリチェックポイントは現在セッションを担当
- ディスク KV キャッシュは セッション切り替えやサーバー再起動後も有用なプレフィックスを保持する仕組み
- 現在、メモリ上には 1 つのライブ KV キャッシュのみが存在し、新しい無関係セッションがこれを置き換えた場合、以前のチェックポイントはディスク KV キャッシュに書き込まれているときだけ再処理なしで再開できる
--kv-disk-dirと--kv-disk-space-mbで有効化-
キャッシュキーとファイル構造
- キャッシュキーは正確なトークン ID の SHA1 ハッシュであり、生テキストではない
- 各トークン ID はリトルエンディアン 32 ビット整数としてハッシュ化され、ファイル名は
<sha1>.kv - 通常の
read/writeI/O で記録し、mmapは使用しない（既にモデルをマップしているプロセスに追加の VM マッピングを避けるため）
-
ディスクキャッシュファイルのレイアウト
- KVC 固定ヘッダー 48 バイト: magic（"KVC"）、バージョン、routed expert quant ビット、保存理由、キャッシュ済みトークン数、ヒット回数、コンテキストサイズ、生成/最終使用 Unix 時刻、DS4 セッションペイロードのバイト数
- レンダリング済みテキスト: キャッシュ済みトークンプレフィックスのトークナイザーデコード文字列（観察用であり、キーには使われない）
- DS4 セッションペイロード: 13 個のリトルエンディアン u32 フィールドで始まり、magic（"DSV4"）、ペイロードバージョン、コンテキストサイズ、prefill チャンクサイズ、KV リング容量などを含む
- チェックポイントのトークン ID、次トークン用の float32 logits、レイヤーごとの圧縮 attention 行数、ライブ raw スライディングウィンドウ KV 行、圧縮レイヤーの KV 行および compressor frontier テンソルなどを保存
-
チェックポイント保存タイミング
cold: 長い初期プロンプトが安定したプレフィックスに到達した後、生成前continued: prefill または生成が設定間隔だけ進行したときevict: 無関係なリクエストがライブなインメモリセッションを置き換える前shutdown: サーバーが正常終了するとき
- cold 保存時には小さなトークンサフィックスをトリミングし、prefill チャンク境界に整列させることで、将来のリクエストで BPE 境界の再トークン化ミスを防ぐ
- デフォルト値: 最小 512 トークンプレフィックス、cold 保存最大 30000 トークン、末尾 32 トークンをトリミング、2048 トークンチャンク整列
- デフォルトでは、2 ビットと 4 ビットの routed-expert バリアント間でも トークンプレフィックスが一致すればチェックポイント再利用が可能
--kv-cache-reject-different-quantで同一量子化専用の再利用に設定可能
バックエンド
- デフォルトバックエンドは Metal（
--metal） - CPU 参照/デバッグ経路（
--cpu）も存在するが、本番向けではない- サーバーは Metal 専用であり、最適化実装は Metal グラフ経路に存在
- MIT ライセンス、C/Objective-C/Metal 実装
1件のコメント
Hacker Newsのコメント
既存のコードベースで Claude Code と一緒に使ってみたが、2ビット量子化モデルなのにそれなりに役に立つようだ
プロンプト処理には数分かかるが、実際の編集は 20トークン/秒以上でかなり速い
小さな作業ではコード探索、修正適用、テスト作成まで成功したが、ちょっとした指摘ひとつは直せなかった
もっと悪いことに、別の問題を解いている最中に同時進行でしていた「The Duck」に関する会話を幻覚として持ち出してきた。たぶん Claude Code の初期プロンプト例のひとつなのだろう
以前、Qwen3モデル 向けにかなりよく似たものを作ったことがある。Qwen3だけを実行し、一部の量子化のみをサポートし、GGUF からロードし、Claude が反復的に最適化した推論を使うものだった
全体が数ファイル程度と小さくて理解しやすく、学生がデコーディング戦略の追加や abliteration のようなことを実験しながら学べるようにしたプロジェクトだった。有名フレームワークは大きく複雑すぎてハックしにくく、教育用プロジェクトは GPT-2 のような古いものに留まりがちだ
教育用として始めたが、その後ずっと頭から離れないアイデアがある。特定の GPU+モデルの組み合わせ に合わせた超最適化推論エンジンを作ったらどうかというものだ。GPU は高価でますます入手しにくくなっているので、抽象化を十分に剥がして正確なハードウェア/モデルに直接合わせれば、かなり最適化できそうに思える
ただし、モデルが陳腐化すると全部を最初からやり直さなければならないという問題がある
あまり人気のないプラットフォームでは、まだ簡単に得られる性能改善の余地があるが、特定の GPU ファミリー向けに超最適化されたモデル実行器を作って劇的に良い性能を得る余地はあまりない。中核計算はすでに各 GPU 向けの高度に最適化されたカーネルが処理している
CPU アーキテクチャ上でより良く動くよう最適化した llama.cpp のフォークもあるが、保守者間に意見の相違がないなら、特定のモデル+GPU 実行器を別に作るより、こうした改善を upstream にマージするほうが時間の使い方としては良い
https://codegolf.stackexchange.com/questions/215216/high-thr...
計算量の大きい 行列積 をオペアンプで処理できるだろうか？ そしてこうしたアナログ的アプローチは、ビット表現の限界よりはるかに効率的になり得るだろうか？
最新の AI が カーネル最適化 までできるようになったのだから、もっと多くの人が自分のハードウェアに合ったより良い推論を自作してみるべきだと思う
古い W7900(RDNA3) を持っているが、48GB VRAM に加え、123 FP16 TFLOPS/INT8 TOPS、864GB/s のメモリ帯域幅といった指標はかなり悪くない。だが AMD の ROCm サポートも llama.cpp のサポートも悪名高いほどひどかった
最近このカードを専用エージェント/コーディングエンドポイントとして使うために、W8A8-INT8 モデルのチューニングを始めた。数日間で自動反復を約 800 回回し、複数の frontier/SOTA モデルを使ってみたが、Kimi K2.6 が意外なほど良かった。結果として、Qwen3.6 MoE 基準で llama.cpp の最高値より prefill は 20%、decode は 50% 速くなった
今は MTP と DFlash の最適化をさらに掘り下げていて、結果にはかなり満足している。次は Gemma 4 を試すつもりだ
それでも llama.cpp は最高性能ではないかもしれないが、ほとんどのモデルを一貫して動かせる。MTP が不足していて、ハイブリッドモデルのキャッシュ無効化の問題があるようだが、少なくとも何が動くかは分かる
Python ベースの推論器は uv/venv、自分の venv、システム環境、Python、本体ライブラリまで入り乱れていて、実際に何が動いているのか把握するにはエージェントが必要になりそうなくらいだ。スキル不足やユーザーエラーだというのは分かっているが、そこに使う時間が残っていない
完璧でなくても GitHub や Hugging Face に上げれば、別のエージェントが 0 からではなくそこから始められる。Ling-2.6-flash(107B-A7B4 MoE) でもそうしたし、ローカル LLM 用として持っている別のハードウェアである M2 Max で実用的に動かせる最大の LLM だ
MTP がうまく動かなくても、少なくとも今の llama.cpp が Ling-2.6-flash をまったく動かせない状態よりは改善だ。関連議論は https://huggingface.co/inclusionAI/Ling-2.6-flash/discussion... にあり、4ビット量子化は https://huggingface.co/ljupco/Ling-2.6-flash-GGUF、ブランチは https://github.com/ljubomirj/llama.cpp/tree/LJ-Ling-2.6-flas... にある
llama.cpp は PC サポートをもっとずっと良くできたはずだと思う。ベンダー側のサポート不足が一因なのだろうが、これだけユーザーが多いのに、標準的な PC でさらに最適化された推論があまり見られないのは驚きだ
本当にすごい。ひとつの オープンソースモデル を何か月も集中的に最適化したら、どんな結果になるのか気になる
推論サービングだけでなく、ハーネス最適化やカスタムワークフローまで含めて、frontier モデルは推論や導出ができる一方で、オープンソースモデルはサイズや学習上の限界ゆえに本質的に不足している部分の差を、どこまで埋められるのか見てみたい
Kimi 2.6 をそこそこのトークン/秒で運用するのに月 2 万ドルかかるのに、そのトークンを利益を出して売るにはハードウェア費用を月 1000 ドル未満に抑えなければならない
億万長者が原価の 1/10〜1/20 でトークンを売ってくれる寛大さや、有能なオープンソースモデルがコンシューマー向けハードウェアに載るという幻想めいた未来に能力を賭けているなら、もう終わっている
面白くて興味深く、多くを物語るデータポイントがある。私の MacBook M3 Max は、DS4 が最大速度でトークンを生成しているとき、消費電力が 50W まで上がる
DS4 Flash が 50W でピークを打ち、280B パラメータだとすると、1.6T パラメータの DS4 Pro はだいたい 300W くらいだろうか？ 最新の GPT 5 や Opus も同じように 500W 前後という感じがする
Claude Code を使っていて、モデルがひとりで延々と回っているあいだ、どこかのデータセンターで 500W を燃やしていると考えていいのだろうか？
Mac Studio では 96GB RAM より大きいオプションを注文できない。M3 Ultra でも M4 Max でも同じだ。オーストラリア限定なのかは分からない
一方で MacBook Pro は M5 Mac で 128GB を指定できる
https://www.apple.com/au/shop/buy-mac/mac-studio
Apple はぼったくり価格への批判や在庫不足への反発を受けるくらいなら、いっそ価格を付けない方を選んだのかもしれない
96GB を超えるすべての Mac Studio 構成とベースモデルの Mac mini をなくした。Neo のベース構成も市場から下げることを検討中という噂がある
ファブの生産能力と RAM 供給の制約を、こういう形で処理しているのだろう
単純な動機づけのためのベンチマークや目標が欠けているのかもしれない
一般的なツールチェーンを使うより速いとか、より大きく賢いモデルを動かせるのだろうとは推測できるが、そのベースラインに対して既存の改善幅や期待改善幅がどの程度なのか、明確には書かれていないように見える
関連する比較値を知っていれば、提示された数字から計算はできるのだろうけれど
非常に印象的だ。ただ、大きな入力で応答を開始するまで 4分ほど かかるように見えるのは妙だ
Mac ハードウェアで LLM を使ってはいないが、かなり驚きだし、実用上は相当大きな障害になりそうだ
ただ、通常利用ではキャッシュの説明を見るとずっと納得がいく。Claude Code は有用な作業を始める前に普通 25k トークンほどの大きな初期プロンプトを送ることがあり、
--kv-disk-dirを有効にしておけば、最初の高コストな prefill の後でディスク KV キャッシュが保存済みプレフィックスを再利用し、プロンプト全体を再処理しなくて済むしかし M3 Ultra では prefill 速度がほぼ 500 トークン/秒なので、十分に実用的な領域だ。M3 Max は少し忍耐が要るがうまく動くし、pi agent を使えば思考過程を出力するので、待つ代わりに検閲されていない chain of thought を読める
昨日 X に M3 Max で使っている動画を上げたが、かなりまともな速度でトークンを吐き出していた
MacBook で大きな LLM を使う場合、トークン生成速度は許容できるが、問題は コンテキスト読み込み だ
チャットセッションのように KV キャッシュを使う増分読み込みではなく、大きなファイルを貼り付けるときのように大きな入力を読む場合が問題になる。数分かかることがある
クラウドプロバイダーが提供する本来の知能からはかなり離れている可能性が高い
それでもエージェント型ワークフローにおけるローカル LLM の可能性を、よりよく示している
会話履歴全体を毎回入れ直す方式に依存しないアーキテクチャはあるのだろうか？ たとえば再帰型 LLM のようなものだ