ds4.c

DeepSeek V4 Flash 専用のネイティブ推論エンジン（Metal 本番パス）

1 — 概要

位置づけ

ds4.c は汎用 GGUF ランナーではなく、DeepSeek V4 Flash 向けにロード形式・量子化・Metal グラフ・KV 状態・HTTP API を一貫させた小さな推論エンジンである。本番は Metal グラフ実行で、llama.cpp / GGML 由来の知見とカーネル・量子レイアウトを参照しつつ、当該モデル専用の読み込みと検証に絞っている。

1Mコンテキスト上限（トークン）

Metal本番実行パス

KV圧縮キャッシュ＋ディスク永続化

HTTPOpenAI / Anthropic 互換

設計上の狙いは、公式実装と整合した logits の検証、長文・エージェント用途での KV 再利用、およびローカル環境（高メモリ Mac など）での実用性である。公開 GGUF はプロジェクト配布のものに限定され、任意ファイルはレイアウト不一致で動かない。

2 — モジュール構成

データの流れ

GGUF mmap → トークナイザ → Metal グラフ → CLI / ds4-server

ファイル	役割
`ds4.c`	モデルロード、トークナイザ、CPU 参照、Metal スケジュール、セッション、ディスクキャッシュ直列化
`ds4_cli.c`	コマンドライン、linenoise REPL、対話トランスクリプト
`ds4_server.c`	OpenAI / Anthropic 互換 HTTP、ワーカーキュー、ストリーミング、ツール呼び出しマッピング、ディスク KV 方針
`ds4_metal.m`	Objective-C による Metal ランタイムとカーネルラッパ
`metal/*.metal`	演算カーネル（Attention、MoE、規約など）
`tests/`	単体・統合テスト、公式ベクトル

3 — モデル取得とビルド

入手と既定パス

配布スクリプトは Hugging Face: antirez/deepseek-v4-gguf から q2 / q4 を取得し、./gguf/ に保存して ./ds4flash.gguf を選択モデルへ向ける。./download_model.sh mtp で投機的デコード用 GGUF を追加できる（--mtp で有効化。現状は実験扱い）。

./download_model.sh q2   # 128 GB クラス向け
./download_model.sh q4   # 256 GB 以上向け
make

既定のモデルパスは ./ds4flash.gguf。別ファイルは -m で指定。./ds4 --help と ./ds4-server --help に全フラグが載る。

2-bit 量子化の要点

ルーティング MoE 専家のみ非対称量子化（up/gate を IQ2_XXS、down を Q2_K）。共有エキスパートや投影・ルーティングは高ビットのままにし、品質とツール利用の安定性を優先している。

4 — CLI と HTTP サーバー

CLI

ワンショットは -p。対話は ./ds4 のみ起動。対話モードはマルチターンで Metal KV を保持し、/think、/nothink、/ctx N、/read FILE などが使える。既定は thinking モード。

./ds4 -p "Explain Redis streams in one paragraph."
./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

サーバー API

推論は単一 Metal ワーカーに直列化され、同時リクエストはキュー待ちになる。主なエンドポイント:

GET /v1/models、GET /v1/models/deepseek-v4-flash
POST /v1/chat/completions（OpenAI 形式、ツール・ストリーミング対応）
POST /v1/completions
POST /v1/messages（Anthropic 形式、thinking 制御）

参考スループット（README 掲載値）

条件: Metal CLI、--ctx 32768、--nothink、貪欲、-n 256。

機種	量子化	プロンプト	Prefill	生成
MacBook Pro M3 Max, 128 GB	q2	short	58.52 t/s	26.68 t/s
MacBook Pro M3 Max, 128 GB	q2	11709 tokens	250.11 t/s	21.47 t/s
Mac Studio M3 Ultra, 512 GB	q2	short	84.43 t/s	36.86 t/s
Mac Studio M3 Ultra, 512 GB	q4	short	78.95 t/s	35.50 t/s

5 — ディスク KV キャッシュ

ステートレスクライアントとの相性

チャット API はステートレスが前提のため、クライアントは毎回長い会話全文を送りがちである。ds4-server はレンダ済みトークン列とキャッシュされたプレフィックスを照合し、共有プレフィックスを再計算から省く。メモリ上のチェックポイントが現在セッション、ディスク KV がセッション切替や再起動後の再開に効く。

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

キーは生テキストではなく、トークン ID 列の SHA1（各 ID を little-endian 32-bit としてハッシュ連鎖）。キャッシュファイル名は <sha1>.kv。本文は人間向け観測用で、ロード時の整合判定には使われない。

6 — エージェント連携の要点

ローカル HTTP を前提にした設定

OpenAI 互換クライアントでは baseURL を http://127.0.0.1:8000/v1 に向け、サーバー起動時の --ctx 以下にクライアント側のコンテキスト上限を合わせる。Claude Code 利用時は Anthropic 互換エンドポイントへ ANTHROPIC_BASE_URL 等を向ける運用が README に例示されている。

Thinking モード: サーバー既定は thinking。thinking: {"type":"disabled"} や think:false、非 thinking エイリアスで直接回答に切り替えられる。reasoning_effort=max は Think Max だが、コンテキストが十分大きい場合に限るなどモデルカード推奨に従うフォールバックがある。

7 — 制約と注意

運用上の境界

Metal のみ本番: CPU パスは参照・デバッグ用。大きな CPU 推論を macOS で走らせると、README が指摘するようにカーネル VM まわりの不具合でクラッシュする報告がある。
単一ライブ KV: メモリ上は同時に一系統。別セッションへ切り替えると、旧チェックポイントをディスクに書いていないと再開で全プレフィックス再計算になる。
巨大プロセスの並列: 複数の巨大モデルプロセスを同時に動かさない（インスタンスロック意図）。
128 GB での ctx: q2 でもモデル占有が大きいため、100k〜300k トークン帯のコンテキスト設計が現実的、という README のガイダンスがある。

8 — 出典・リンク

一次情報

GitHub: antirez/ds4 — ソースと README
Hugging Face: antirez/deepseek-v4-gguf — 配布ウェイト
llama.cpp — 謝辞で明示される参照実装・エコシステム