Deltafin：Apple Silicon 上での Kimi K3 モデル実行ガイド

概要

Deltafinは、2.8 トリリオンプARAMエータを持つ Kimi K3 (Mix-of-Experts: MoE) モデルを、単一の Apple Silicon Mac で動作させるための小規模研究プロジェクトです。

• 性能: M1 Max でも約 16 トokens/秒 と高速ではありませんが、正確で再現可能です。
• 互換性: 64 GB のラップトップでも動作し、新しいチップやメモリ増加により自動的に高速化されます。

インストール手順

モデルを実行するには以下の 3 つのコマンドが必要です。ステップ 3 が重要な決断点となります。

前提条件

• Python 3.12 以降
• Xcode コマンドラインツール（

  clang

  のため）

ステップ 1：環境の作成

仮想環境を生成し、必要なライブラリをインストールします。

python3 -m venv venv
./venv/bin/pip install torch numpy safetensors tiktoken ml_dtypes blobfile \
    "transformers==4.56.2" einops tokenizers

ステップ 2：Fused MXFP4 カーネルのビルド

高速化のための固有ライブラリをコンパイルします。

clang -O3 -mcpu=native -shared -DNO_MAIN -o tools/libmxfp4gemv.dylib tools/fused_gemv.c

ステップ 3：モデルのダウンロード

2 つのモードから選択できます。推奨されるのは

--full

モード比較表

--full

--stream

• 技術的備考: モデルは約 25.8 GB のデータ（エキスパート×92 レイヤー）を持ちます。ローカルディスク読み取り（約 4 秒）とネットワーク経由読み取り（数分）では速度が異なります。
• 自動判定:

  setup_k3.py

  にフラグなしで実行すると、ディスク容量があれば

  --full

  を選択し、不足すれば自動的に

  --stream

  モードにフォールバックします。

ストリーミングからのフルインストールへの変更: 初期はストリーミングモードから始め、後で高速化のために完全ダウンロードを完了できます（再インストール不要）。

./venv/bin/python tools/fetch_experts_all.py          # 中断可能
./venv/bin/python tools/fetch_experts_all.py --dry-run   # 推定サイズ確認
./venv/bin/python tools/fetch_experts_all.py --layers 1-40   # 部分的ダウンロード

オプション：Int8 Spine（推奨） エキスパート以外の実装を int8 に量子化し、I/O を半減させます。

./venv/bin/python tools/convert_spine_int8.py

使い方

チャット生成

質問を入力して回答を生成します。

./venv/bin/python tools/kimi_run.py --chat --prompt "What are the three largest moons of Saturn?"

生の完遂 (Raw Completion)

制限回数まで出力されます。

Ctrl-C

./venv/bin/python tools/kimi_run.py --prompt "The capital of France is" --max-new 16

OpenAI API サーバー

標準的な OpenAI API を提供します（ポート変更も可）。

./venv/bin/python tools/serve_openai.py --port 8000

cURL リクエスト例

curl http://127.0.0.1:8000/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model": "deltafin-kimi-k3", "messages": [{"role": "user", "content": "Hello!"}]}'

Python SDK 使用例

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="none")

r = client.chat.completions.create(
    model="deltafin-kimi-k3",
    messages=[{"role": "user", "content": "Hello!"}])

print(r.choices[0].message.content)            # 回答
print(r.choices[0].message.reasoning_content)  # K3 の思考プロセス（存在する場合）

⚠️ 自動化における重要な注意点

1. 時間: 回答生成には時間がかかります。タイムアウト設定は秒単位ではなく時間単位にしてください。

   max_tokens

   を省略するとモデルが終了するまで待ちます（推奨）。
2. ストリーミングインストール: クライアント側では非常に低速です。プリフィル（事前計算）を含む長めのプロンプトは、キャッシュ未充填状態で数時間を要することがあります。フルインストール後には通常速度になります。
3. パラメータ制限:

   temperature

   や

   top_p

   は無視されます。同時リクエストは拒否されます（429 エラー）。
4. エージェント: 長期のシステムプロンプトは高コストになるため推奨されません。

仕組みについて

Kimi K3 の総重量は約 1.56 TB で、M1 Max (64 GB RAM) のディスク容量を超過します。しかし、MoE モデルは各トークンごとに一部のエキスパートのみを使用するため、ローカル推論が可能になります。

メモリ構成

• レジデント・スパイン (~114 GB): 共有エキスパートや埋め込みなど。一度

  int8

  に量子化され、ローカル NVMe から読み出されます。
• ルーティングされたエキスパート (~1.45 TB): K3 ルーターは 92 レイヤーのうち各トークンで 16 つのエキスパートを選択します。

アーキテクチャフロー図

flowchart LR
    subgraph HF["Hugging Face CDN"]
        W[("96 safetensors shards<br/>1.56 TB · MXFP4")]
    end
    subgraph MAC["MacBook (M1 Max, 64 GB)"]
        subgraph DISK["NVMe"]
            SP[("resident spine<br/>114 GB bf16 → 60 GB int8")]
            EC[("expert cache<br/>raw shard spans")]
        end
        subgraph TOK["per token processing"]
            R{"router<br/>top-16 of 896<br/>× 92 layers"}
            L["93 decoder layers<br/>2 shared GPU templates"]
            K["fused MXFP4 GEMV<br/>NEON"]
        end
    end

    W -- "one range request<br/>per missing expert" --> EC
    SP -- "double-buffered<br/>layer loader" --> L
    EC -- "mmap" --> K
    R -- "selected experts" --> K
    K --> L
    L -- "logits" --> R

推論シーケンス図

sequenceDiagram
    participant D as n-gram draft
    participant M as model (one T=2 pass)
    participant S as state snapshot
    
    D->>M: [last_token, draft]
    M->>M: 93 layers, shared cost
    alt draft verified
        M-->>D: 2 tokens accepted
    else draft wrong
        S-->>M: state restored (bit-exact)
        M-->>D: 1 token, nothing lost
    end

パフォーマンス比較 (期待されること)

測定環境：M1 Max (CPU 10 コア / GPU 32 コア / RAM 64 GB)、フルインストール、貪欲デコード。

トークンあたり内訳 (デコード時)

このハードウェアでは約 3.75 tokens/分 の処理速度です。

• レジデント・スパイン読み取り (53 GB): ~5 秒
• エキスパート読み取り (25.8 GB): ~4.3 秒
• スパインの適用 (転送 + デ量子化): ~3 秒
• アテンションとノーマライゼーション: ~2 秒
• MoE 行列乗算: ~1 秒

新しい Mac が速くなる理由

• メモリ帯域幅: M3/M4 Max は高帯域幅を持ち、Ultra で倍増します。スパイン読み込みと計算に直結。
• GPU: より多くのコアが Metal カーネル（デ量子化・アテンション）を高速実行。
• SSD: 後期モデルはより高速な NVMe を搭載。
• RAM (最重要): 53 GB のスパインデータを RAM 上に保持できるかが鍵。128 GB マシンではページミスによるコストがほぼ消失し、性能が劇的に向上します。

設定環境変数

GPU と int8 スパインはデフォルトで自動的に選択されます。以下の変数でオーバーライド可能です。

K3_DEV

auto

K3_SPINE

auto

K3_SPEC

1

K3_TEMPLATES

1

K3_PRELOAD

K3_PREFETCH

1

K3_APPROX

0

K3_RAM_GB

K3_PIN_LAYERS

auto

DELTAFIN_ROOT

repo root

要件

1. ハードウェア: Apple Silicon Mac (M1 Max, 64 GB RAM でテスト済み)。
2. ツール: Xcode Command Line Tools (

   xcode-select --install

   )。
3. Python: バージョン 3.12 以降。
4. ディスク容量: フルインストールで ~1.7 TB、ストリーミングで ~215 GB。
5. ネットワーク: Hugging Face にアクセス可能（初期フェッチ時）。

技術的特徴と最適化

• 結合されたエキスパートフェッチ: 単一の範囲リクエストで全エキスパートを取得し、通信回数を削減。
• Raw-Span ディスクキャッシュ: コンテナ形式の解析なしでシャードバイトを直接使用。
• 並列エキスパート読み込み:

  pread

  と

  F_NOCACHE

  を使い、ページフォールトを回避（コールドリード速度向上）。
• ダブルバッファされたレイヤー読み込み: 計算中同時に次のスパインデータを読み込み。
• Fused MXFP4 デ量子化 + GEMV: NEON カーネルによるビット正確な高速処理。
• カスタム Metal デ量子化カーネル: 標準 MPS の 43 GB/s から 297 GB/s へ大幅改善。
• n-Gram 推測: サフィックスマッチングでドラフトを作成し、2 トークン単位で検証（ロスレス）。

機能しなかったこと (失敗エントリ)

これからの可能性

• Metal エキスパートカーネル: プロトタイプ化済み（非 CUDA/PyTorch 依存）。
• 高品質な評価ベンチマーク: 公式 API に対する平均 NLL を測定するハネスの作成。
• ネイティブエンジン:

  ds4

  の精神に基づく独自エンジンの実装。

お礼とクレジット

Deltafin は以下のオープンソースプロジェクトに大いに依存しています：

1. colibri (JustVugg, Apache-2.0): 大規模 MoE を RAM で動作させる技術、シャード変換ノウハウ。
2. ds4 / DwarfStar: エキスパートストリーミング設計、品質メソッドロジ。
3. Moonshot AI: Kimi K3 の重み公開、長文脈対応のキミ・デルタ・アテンション設計。
4. flash-linear-attention: 移植された計算最適化セマンティクス。
5. llama.cpp / ggml: カーネル内デ量子化および MXFP4 ハンドリングの技術基盤。

ライセンス情報:

• Deltafin の独自コードは MIT ライセンス。
• Kimi K3 の重みとコードは Moonshot AI のライセンス条項に従ってください（Deltafin は Moonshot と無関係です）。