DeepSeek R1 ローカル推論エンジン for Metal

ds4.c は、DeepSeek V4 Flash に特化した小規模なネイティブ推論エンジンです。意図的に範囲を限定しており、汎用的な GGUF 実行環境でも、別のruntime のラッパーでも、フレームワークでもありません。主となるパスは、DS4 固有のローディング、プロンプトレンダリング、KV ステート、そしてサーバー API の接着層が付随した DeepSeek V4 Flash 専用メタルグラフ実行器です。

このプロジェクトが存在する背景には llama.cpp と GGML が不可欠であり、必ず謝辞セクションもご一読ください。Georgi Gerganov および他の貢献者諸氏へ心から感謝します。

さて、再び本プロジェクトに戻りましょう。なぜ私たちは DeepSeek v4 Flash を「独立した専用エンジンに値する特別なお modelli」と考えているのか。それは、強力な小規模なdenseモデルと比較した結果、以下の特性を報告できるからです：

• アクティブパラメータが少ないため、DeepSeek v4 Flash はより高速に動作します。
• 「思考（thinking）」モードにおいては、最大限の思考出力を避ければ、他のモデルに比べてはるかに短い思考セクション（多くの場合他モデルの 1/5 など）を生成し、重要なのは、思考セクションの長さが問題の複雑さに比例することです。これにより、他モデルでは実用的ではない状況でも、DeepSeek v4 Flash は思考機能を有効にしたまま利用可能です。
• コンテキストウィンドウは 100 万トークンに対応します。
• その分大きく、知識の境界線上でサンプリングすると多くの事柄を知っています。例えばイタリアのテレビ番組や政治に関する質問をした場合、すぐに 284B パラメータが 27B や 35B パラメータよりも遥かに優れていることが浮かび上がります。
• 英語とイタリア語の文章作成能力は非常に高く、「準フロンティア（quasi-frontier）」的なモデルを感じさせます。
• KV キャッシュは圧縮性に非常に優れており、ローカルコンピュータでの長時間コンテキスト推論や、ディスク上の KV キャッシュ永続化を可能にします。
• 特異な方法で量子化された場合、2 ビット量子化と良好に動作し、これにより 128GB の RAM を搭載した MacBook でも実行可能です（詳細は後述）。
• DeepSeek から v4 Flash のさらに優れた改良版が今後リリースされることを期待しています。

しかしながら、本プロジェクトにおけるいくつかの重要な点は以下の通りです：

• ローカル推論の分野には多数の優れたプロジェクトが存在しますが、新しいモデルが絶えず公開され、その度に注目が移ってしまいます。このプロジェクトはあえて「狭い賭け」を行っています：一度に一つのモデルのみを対象とし、公式実装によるベクトル検証（logits）、長時間コンテキストテスト、かつ実際に機能するかを可視化するための十分なエージェント統合を実装する、というものです。対象となる正確なモデルは景気が変われば変更される可能性がありますが、制約は変わりません：高品位のパーソナルマシンや Mac Studio における信頼性の高いローカル推論を目指し、最低でも 128GB のメモリから開始します。
• このソフトウェアは GPT 5.5 の強力な支援のもとで開発されましたが、コンセプト、テスト、デバッグは人間が主導しています。我々はオープンにこれを語る理由は、それがプロジェクトの構築方法を形作ったからです。もし AI が生成したコードに満足できないようであれば、本ソフトウェアには向いていません。また、以下の謝辞も同様に重要です：このプロジェクトが存在する根底には llama.cpp と GGML があり、これらは主に人間の手による実装です。
• この実装は、「DeepSeek v4 のような圧縮 KV キャッシュと、現代 MacBook の高速 SSD ディスクの組み合わせが、KV キャッシュは RAM に属するという既存の概念を改めなければならない」という思想に基づいています。すなわち、KV キャッシュは第一級（first-class）のディスク住民なのです。
• 私たちのビジョンは、ローカル推論が「开箱即用」で良好に連携する三要素のセットであるべきだというものです：A) HTTP API を備えた推論エンジン + B) 特定の実行環境と前提条件下で動作するように特別に設計された GGUF ファイル + C) コーディングエージェントによるテストと検証実装です。本推論エンジンは、提供された GGUF ファイルのみを実行します。異なるコンテキストサイズで取得した公式な logits と比較してテストされます。このプロジェクトが存在する理由は、単に実行可能であるだけでなく、一つのローカルモデルを「エンドツーエンドで完成品として」届けたいと考えたからです。しかし、これはアルファ品質のコードであり、おそらくまだ完全に達成できたわけではありません。
• 現在は Metal 専用です。将来的に CUDA サポートを実装するかもしれませんが、それ以上の拡張は予定されていません。CPU パスは正しさ検証用のみであり、警告：現在の macOS バージョンには仮想メモリ実装の不具合があり、CPU コードを実行するとカーネルがクラッシュします。ソフトウェアの複雑さゆえです。毎回コンピューターの再起動を必要とするため、この CPU 推論クラッシュ問題を解決することは至難の業でしたが、もしお力添えいただける方は大歓迎です。

llama.cpp と GGML への謝辞

ds4.c は GGML にリンクしていませんが、llama.cpp プロジェクトが開いた道筋、それらのカーネル、量子化フォーマット、GGUF エコシステム、そしてそこで培われた難易度の高い工学知識に感謝しています。我々は llama.cpp とその貢献者諸氏に深く感銘を受け、恩義を感じています。彼らの実装、カーネル、テスト、および設計選好は、この DeepSeek V4 Flash 専用推論パスの構築において不可欠な参考文献となりました。一部のソースレベルの部品については MIT ライセンスの下でそのまままたは適応させて保留しており、その理由と真摯な感謝から、LICENSE ファイル内に GGML の著者名も記載し続けています。

モデルウェイト

この実装は、本プロジェクトのために公開された DeepSeek V4 Flash GGUF ファイルのみに対応しています。汎用的な GGUF ローダーではなく、任意の DeepSeek/GGUF ファイルはこのエンジンが期待するテンソル配置、量子化ミックス、メタデータ、またはオプションの MTP ステートを持っていたとは限りません。ここで提供されている 2 ビット量子化は冗談ではありません：它们は良好に動作し、コーディングエージェント下で機能し、ツール呼び出しを信頼性の高い方法で行います。

2 ビット量子化は非常に非対称な量子化手法を採用しており、ルーティングされた MoE エクスペルトのみが量子化されています（上方向/ゲート部は IQ2_XXS、下方向は Q2_K）。これらはモデル全体空間の大部分を占めており、他のコンポーネント（共有エクスペルト、プロジェクション、ルーティング）は品質を保証するため未 touch として扱われます。

メインモデルのダウンロード

./download_model.sh q2   # 128 GB RAM マシン向け
./download_model.sh q4   # 256 GB RAM 以上のマシン向け

スクリプトは https://huggingface.co/antirez/deepseek-v4-gguf からファイルをダウンロードし、

./gguf/

curl -C -

./ds4flash.gguf

--token TOKEN

HF_TOKEN

./download_model.sh mtp fetches 選択された MTP のオプション的推測デコーディングサポート GGUF ファイルを取得します。これは q2 および q4 両方とも使用可能ですが、明示的に --mtp で有効化する必要があります。現在の MTP/推測デコーディングパスはまだ実験的です：正しさをゲートされており、現状では生成速度の有意な向上ではなく、わずかな速度向上のみを提供します。

次にビルド：

./ds4flash.gguf

-m

./gguf/

./ds4 --help

./ds4-server --help

速度

ここには、q2 GGUF、

--ctx 32768

--nothink

-n 256

CLI

ワンショットプロンプト：

./ds4 -p "Redis ストリームを一言で説明してください。"

-p

/help

/think

/think-max

/nothink

/ctx N

/read FILE

/quit

ds4>

CLI はデフォルトで思考モードになります。直接回答を得たい場合は

/nothink

--nothink

--mtp MTP.gguf --mtp-draft 2

--mtp-margin

サーバー

ローカルの OpenAI/Anthropic 互換サーバーを開始します：

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

サーバーは Metal 専用です。状態のないクライアントが同じプロンプトのより長いバージョンを再送信した場合でも、共有プレフィックスを再利用してゼロトークンからプリフィルするのではなく、既存のステートをリサイクルできます（メモリ上の可変グラフ/KV チェックポイントを一つ保持するため）。リクエスト解析とソケットはクライアントスレッドで処理されますが、推論自体は単一のメタルワーカーを通じてシリアライズされます。現在のサーバーは複数の独立したリクエストをバッチ化して同時実行することはなく、並行リクエストは単一のライブグラフ/セッション上で順番待ちします。

サポートされているエンドポイント：

• GET /v1/models

• GET /v1/models/deepseek-v4-flash

• POST /v1/chat/completions

• POST /v1/completions

• POST /v1/messages

/v1/chat/completions

max_tokens

max_completion_tokens

top_p

top_k

min_p

seed

stream

stream_options.include_usage

/v1/messages

tool_use

両方の API は SSE ストリーミングをサポートしています。思考モードでは、推論は最終テキストに混ざられることなく、ネイティブ API 形式でストリームされます。

最小限の OpenAI 例：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"deepseek-v4-flash",
    "messages":[{"role":"user","content":"Redis デザイン原理を三つ列挙してください。"}],
    "stream":true
  }'

エージェントクライアントの使用例

ds4-server は、OpenAI 互チャットコンプリションを発信するローカルコーディングエージェントで使用できます。まずサーバーを開始し、クライアントのコンテキスト制限値をサーバー起動時の

--ctx

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

必要であればより大きなコンテキストとキャッシュを使用できます。フルコンテキスト（1M トークン）は約 26GB のメモリを使用します（圧縮インデッカー単体でも 22GB に相当），したがってシステムに合わせて適切なコンテキストを構成してください。128GB の RAM の場合、81GB を既に使用する 2 ビット量子化を実行することになりますが、26GB はおそらく多いため、100~300k トークンのコンテキストウィンドウの方が賢明です。

以下の出力制限（384,000 トークン）は、モデルが元々非常に長い返信を生成できるため（最大 384k トークン）、トークン上限を回避するために設けられています。ただし、サーバーは構成されたコンテキストウィンドウが満杯になると停止します。

Opencode の場合：

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ds4": {
      "name": "ds4.c (local)",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:8000/v1",
        "apiKey": "dsv4-local"
      },
      "models": {
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash (ds4.c local)",
          "limit": {
            "context": 100000,
            "output": 384000
          }
        }
      }
    }
  },
  "agent": {
    "ds4": {
      "description": "Local ds4-server で提供する DeepSeek V4 Flash",
      "model": "ds4/deepseek-v4-flash",
      "temperature": 0
    }
  }
}

Pi の場合：

~/.pi/agent/models.json

{
  "providers": {
    "ds4": {
      "name": "ds4.c local",
      "baseUrl": "http://127.0.0.1:8000/v1",
      "api": "openai-completions",
      "apiKey": "dsv4-local",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": true,
        "supportsUsageInStreaming": true,
        "maxTokensField": "max_tokens",
        "supportsStrictMode": false,
        "thinkingFormat": "deepseek",
        "requiresReasoningContentOnAssistantMessages": true
      },
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash (ds4.c local)",
          "reasoning": true,
          "thinkingLevelMap": {
            "off": null,
            "minimal": "low",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "xhigh": "xhigh"
          },
          "input": ["text"],
          "contextWindow": 100000,
          "maxTokens": 384000,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

オプションとして、

~/.pi/agent/settings.json

{
  "defaultProvider": "ds4",
  "defaultModel": "deepseek-v4-flash"
}

Claude Code の場合：

Anthropic 互換エンドポイントを使用します。以下のラッパーは

~/bin/claude-ds4

#!/bin/sh
unset ANTHROPIC_API_KEY

export ANTHROPIC_BASE_URL="${DS4_ANTHROPIC_BASE_URL:-http://127.0.0.1:8000}"
export ANTHROPIC_AUTH_TOKEN="${DS4_API_KEY:-dsv4-local}"
export ANTHROPIC_MODEL="deepseek-v4-flash"

export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek-v4-flash"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek V4 Flash local ds4"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="ds4.c local GGUF"

export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000

exec "$HOME/.local/bin/claude" "$@"

Claude Code は有用な作業を開始する前に、約 25k トークンの大きな初期プロンプトを送出することがあります。

--kv-disk-dir

思考モード

DeepSeek V4 Flash は、非思考、思考、および Think Max という明確に区別されたモードを持っています。サーバーはデフォルトで思考モードになります。

reasoning_effort=max

reasoning_effort=xhigh

直接返信については、

thinking: {"type":"disabled"}

think:false

deepseek-chat

ディスク KV キャッシュ

チャット/コンプリメント API は状態なしです：エージェントクライアントは通常、各リクエストで全会話を再送信します。ds4-server はレンダリングされたトークンストリームとキャッシュされたトークンプレフィックスを比較することでこれを処理します。ライブのインメモリーチェックポイントは現在のセッションをカバーし、ディスク KV キャッシュにより有用なプレフィックスがセッション切り替えやサーバー再起動後も存続します。

メモリ効率のため、現在は一時的に一つのライブ KV キャッシュのみがあります。新しい関連性のないセッションがそれを置換する際、古いチェックポイントがディスク KV キャッシュに書き出されている場合のみ、再処理なしで再開可能です。つまり、メモリーキャッシュはアクティブなセッションを管理し、ディスクキャッシュは異なるセッション間での再起動機構です。

有効化には：

./ds4-server --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

キャッシュキーは生のテキストではなく正確なトークン ID の SHA1 です。各トークン ID はリトルエンディアン 32 ビット整数としてハッシュされ、ファイル名は

<sha1>.kv

ファイルは意図的に通常の read/write I/O で書き出されており、

mmap

ディスク上のキャッシュファイルは：

• KVC 固定ヘッダー、48 バイト

• u32 rendered_text_bytes

• UTF-8 ish トークンテキスト

  rendered_text_bytes

• DS4 セッションペイロード、KVC ヘッダーからの

  payload_bytes

固定ヘッダーはリトルエンディアンです：

u8[3]

u8

u8

u8

u8[2]

u32

u32

u32

u8[4]

u64

u64

u64

レンダリングされたテキストはキャッシュされたトークンプレフィックスのトークナイザーデコード済みテキストです。人間のキャッシュディレクトリを解凍せずに検査できるように可視化のためにのみ保存されており、キーとして使用されず、読み込み時に信頼されていません。読み込み後、保存されたチェックポイントトークンはまだ入ってくる要求プレフィックスと一致する必要があります。

DS4 セッションペイロードは 13 つのリトルエンディアン

u32

次に以下のものを保存します：

• u32[token_count]

  チェックポイントトークン ID。
• そのチェックポイント後の次トークンの logits:

  float32[vocab_size]

  。

• u32[layer_count]

  圧縮済み注意力行数。

• u32[layer_count]

  ratio-4 インデックス行数。 各レイヤーについて：ライブローリング滑り窓 KV 行は、物理環順序ではなく論理的な位置順序で書き込まれています。 圧縮層については：ライブ圧縮済み KV 行およびコンプレッサーフロンティアテンソル。 ratio-4 圧縮層については：ライブインデックス圧縮行およびインデックスフロンティアテンソル。

Logits はホスト

ds4_session

テンソルペイロードは汎用的な推論グラフダンプではなく DS4 固有の KV/セッションステートです。このモデルレイアウトに対して互換性のある ds4.c ビルド間でのみ移植性が期待されます。

キャッシュは以下の 4 つの瞬間にチェックポイントを保存します：

• cold（寒冷）: 長い最初のプロンプトが安定したプレフィックスに達した後、生成前。
• continued（継続）: プリフィルまたは生成が構成された間隔でライブ会話を進めた際。
• evict（追放）: 関連性のないリクエストがライブインメモリーセッションを置換する直前。
• shutdown（シャットダウン）: サーバーがクリーンに終了した際。

Cold セーブは意図的に少量のトークンサフィックスをトリムし、プリフィルチャンク境界へアライメントします。これにより、将来のリクエストが同じプロンプトにテキストを追加した場合に、一般的な BPE 境界再トークナイゼーションミスを回避できます。デフォルトは保守的であり、少なくとも 512 トークンのプレフィックスを保存し、最大 30,000 トークンのプロンプトを cold セーブし、尾部から 32 トークンをトリムし、2048 トークンチャンクへアライメントします。重要なスライダーは：

• --kv-cache-min-tokens

• --kv-cache-cold-max-tokens

• --kv-cache-continued-interval-tokens

• --kv-cache-boundary-trim-tokens

• --kv-cache-boundary-align-tokens

デフォルトでは、トークンプレフィックスが一致する場合、2 ビットおよび 4 ビットのルーティングエクスパートバリアントの間にチェックポイントを再利用できます。厳密な同じ量子化での再利用のみを望む場合は

--kv-cache-reject-different-quant

キャッシュディレクトリは使い捨てです。挙動が不審に思われる場合は、サーバーを停止して削除してください。

hexdump

バックエンド

デフォルトのバックエンドは Metal です：

CPU リファレンス/デバッグパスもあります：

# (CPU 実装詳細)

CPU パスをプロダクションターゲットとして扱わないでください。サーバーは Metal 専用であり、最適化された実装はメタルグラフパスにあります。これらは将来変更される可能性があります。

テストベクトル

tests/test-vectors

deepseek-v4-flash

top_logprobs

./ds4 --dump-logprobs

プロジェクト全体のテストは C ランナーによって駆動されます：

• make test                  # ./ds4_test --all

• ./ds4_test --logprob-vectors

• ./ds4_test --server