Show HN: DeepSeek V3 を純粋な Jax で約200行で実装
Show HN: DeepSeek V3 in ~200 lines of pure Jax (github.com)
要約
この記事は、DeepSeek V3のアーキテクチャを、約200行の純粋なJAXコードで実装したプロジェクトを紹介しています。MacBook Air上で、パブリックドメインの探偵小説を元にスクラッチから事前学習が行われました。FlaxやPyTorchのような外部ライブラリを使用せず、モデルの構造を理解しやすくすることに重点が置かれています。
全文翻訳
DeepSeek V3 を純粋な JAX で190行で実装
DeepSeek-V3技術レポートのアーキテクチャを、190行の純粋なJAXコードで実装しました。MacBook Air上で、パブリックドメインの探偵小説を元にスクラッチから事前学習を行っています。
FlaxもEquinoxもPyTorchも使用していません。パラメータはプレーンな配列の辞書であり、モデルのあらゆる部分は、deepseek_v3.pyで上から下まで読める関数です。
詳細な解説記事を読む: DeepSeek V3 を純粋な JAX で190行で実装(図解、コードのピースごとの説明、結果を含む)
[画像: モデル全体: 36.2Mパラメータ、トークンあたり13.6M使用]
190行に含まれるアイデア
| ペーパーのアイデア | 内容 | 場所 |
|---|---|---|
| Multi-head Latent Attention (MLA) | 各トークンにつき、フルキー・バリューの代わりに小さな潜在変数1つをキャッシュします: ここではレイヤーあたりトークンごとに 480 → 144 の数値 | |
mla, init_cache | ||
| Decoupled RoPE | 全ヘッドで共有される1つのロータリーキーが、圧縮された潜在変数の外側に保持されます | |
rope, apply_rope, mla | ||
| DeepSeekMoE | 常に実行される1つの共有エキスパート + 16個のルーティングされるエキスパート(トークンあたり上位4つ) | |
route, moe | ||
| Auxiliary-loss-free balancing | エキスパートごとのバイアスが、アイドル状態のエキスパートへルーティングを促します。これはエキスパートの重みではなく、どのエキスパートが選択されるかを変更します | |
update_bias, route | ||
| Sequence-wise balance loss | ペーパーの小さな補完的損失(α = 1e-4) | |
seq_balance_loss | ||
| Multi-token prediction (MTP) | 追加モジュールが次のトークンの後も予測し、損失でλ = 0.3で重み付けされます | |
forward, loss_fn | ||
| Training and generation | bf16で計算し、f32のマスターウェイトを使用。MLAキャッシュによるプリフィル + デコード | |
make_train_step, generate |
結果
MacBook Air M5 (24 GB) でのデフォルト設定での1回の実行結果:
| モデル | 36.2Mパラメータ、トークンあたり13.6Mアクティブ |
| データ | 207冊の本、21.7M学習トークン(ハメット作品を3回繰り返し); 検証データは切り離された犯罪小説 |
| 学習 | 12,000ステップ、約98Mトークン(約4.5エポック)、約2.6時間 |
| 速度 | 約10.7kトークン/秒(中央値) |
| 検証損失 | 5.02 (ステップ250) → 3.51 |
| エキスパート負荷、バイアスあり | エキスパートあたり5.7–6.9%(均等なら6.25%)、ステップ2000時 |
| エキスパート負荷、バイアスなし | エキスパートあたり0.09–18.6%、ステップ2000時 |
バイアスあり・なしで、ステップ2000での検証損失は同じでした(3.921 vs 3.923)。バイアスはコストなしでエキスパートを均等化し、ペーパーの主張を裏付けています。
[画像: バランシングバイアスの有無によるエキスパート負荷]
プロンプト「The fog came in off the」に対するモデル自身の生成:
The fog came in off the bay, and the great trees were spreading and the stars were shining.
これはアーキテクチャのデモであり、強力な言語モデルではありません。何がうまくいき、何がうまくいかず、何が欠けているかについては、解説記事を参照してください。
学習済みモデルを試す
v1.0リリースには、公開された実行と同じチェックポイントとデータが含まれています。インストール(ステップ1)の後:
mkdir -p data runs/main
curl -L -o runs/main/ckpt.pkl https://github.com/Vaibhaav-Tiwari/deepseek-v3-jax/releases/download/v1.0/ckpt.pkl # 138 MB
curl -L -o data/tokenizer.json https://github.com/Vaibhaav-Tiwari/deepseek-v3-jax/releases/download/v1.0/tokenizer.json
.venv/bin/python sample.py --prompt "The fog came in off the" --num 3
チェックポイントはPythonのpickleファイルであり、ロード時にコードを実行する可能性があります。信頼できるソースからのチェックポイントのみをロードしてください。
再現する
Apple Silicon Mac、Python 3.12、およびuvが必要です。公開された実行では24 GBのメモリを使用しました。Macをお持ちでない場合は、CPUでの実行を参照してください。
1. インストール
git clone https://github.com/Vaibhaav-Tiwari/deepseek-v3-jax.git && cd deepseek-v3-jax
uv venv -p 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt
requirements.txtのすべてのバージョンはピン留めされています。jax-metal 0.1.1はjax==0.4.34でのみ動作するため、JAXをアップグレードしないでください。
2. セットアップの確認
JAX_PLATFORMS=cpu .venv/bin/pytest tests.py -q # 39 passed
.venv/bin/python smoke_metal.py # オプション: Mac上のjax-metalがサポートするもの
smoke_metal.pyでは、「grad through 2-axis contraction」がjax-metal 0.1.1で失敗します。これは予想されることであり、モデルはこの問題を回避するように書かれています。
3. データセットの構築
.venv/bin/python prepare_data.py
これは、sources.txtにある207冊の本(約120 MB、約7分)をダウンロードし、クリーニングし、8,192トークンのBPEトークナイザーをトレーニングして、data/train.bin、data/val.bin、data/tokenizer.jsonを書き出します。以下のような出力が表示されるはずです:
train: 211 docs, 83.4M chars, 21.69M tokens
val: 4 docs, 1.1M chars, 0.30M tokens
公開された実行のデータには、これらのハッシュがありました:
shasum -a 256 data/train.bin data/val.bin data/tokenizer.json
d37aca97e707bb81b6e4d266cc1adfd1f3e3556457c6eb724e495118a734e0bb data/train.bin
b7ac285b115e6793b5d36aa5b4bc6e81a5fccfc7af0908a306d3828ebca9c31c data/val.bin
c5a142b4006a967c880dda44ad792719d53c16d947da3b6c2332d6132d9967cc data/tokenizer.json
ほとんどの場合、異なるハッシュが得られるでしょう。ハメット作品はStandard Ebooksの正確なコミットにピン留めされており、同一のものが生成されますが、Project Gutenbergのファイルはピン留めできず、Gutenbergはその後203冊中28冊を小さな編集(主にアクセントの削除、「José」→「Jose」など)で再発行しています。トークン数は同じになるため、学習は同様に進行するはずです。
全く同じバイトで学習するには、prepare_data.pyをスキップし、代わりに公開データセットをダウンロードしてください:
mkdir -p data
for f in train.bin val.bin tokenizer.json; do curl -L -o data/$f https://github.com/Vaibhaav-Tiwari/deepseek-v3-jax/releases/download/v1.0/$f; done
shasum -a 256 data/*.bin data/tokenizer.json # 上記のハッシュと一致するはずです
4. 学習
.venv/bin/python train.py # メインの実行: 12kステップ、約2.6時間
.venv/bin/python train.py --steps 2000 --out runs/bias_on # バランシングのアブレーション、バイアスあり
.venv/bin/python train.py --steps 2000 --out runs/bias_off --no-bias # ...バイアスなしの場合
各実行は、metrics.jsonl(損失、検証損失、エキスパートごとの負荷、バイアス、トークン/秒)とckpt.pkl(評価ごとに保存)を--outフォルダ(デフォルトはruns/main)に書き出します。シードは固定されていますが、Metal上のGPU計算はビット単位で決定論的ではないため、数値は上記のものと完全に一致するのではなく、近くなることが予想されます。
5. 生成
.venv/bin/python sample.py --prompt "The fog came in off the" --num 3
デフォルト: 温度0.8、トップk 50、サンプルあたり300新しいトークン(--temp、--top-k、--n)。
6. 図の作成
.venv/bin/python plots.py # runs/main, runs/bias_on, runs/bias_off が必要
JAX_PLATFORMS=cpu .venv/bin/python charts.py # 残りの解説記事のチャート
両方ともpost/figures/に書き出されます。
学習せずに図を再描画するには、リリースからログをダウンロードします: metrics-main.jsonl、metrics-bias_on.jsonl、metrics-bias_off.jsonlをそれぞれruns/main/、runs/bias_on/、runs/bias_off/にmetrics.jsonlとして配置します。charts.pyはチェックポイントとデータセットも必要とします。
CPUでの実行
すべてjax-metalなしで実行できます。非常に遅いため、より小さな設定を使用してください:
JAX_PLATFORMS=cpu .venv/bin/python train.py --config small
--config small(4レイヤー、8エキスパート、トップ2、128トークンコンテキスト)は、8〜16 GBのMac向けです。これは数ステップのみチェックされており、最後まで学習されていません。
ファイル
| ファイル | 内容 |
|---|---|
deepseek_v3.py | モデル: 設定、MLA、MoE、バランシング、MTP、損失、学習ステップ、キャッシュ生成。190行の部分。 |
train.py | 学習ループ: ウォームアップとコサイン減衰付きAdamW、評価、チェックポイント、ロギング |
prepare_data.py, sources.txt | コーパスのダウンロード、クリーニング、トークン化 |
sample.py | チェックポイントからのテキスト生成 |
tests.py | 39のテスト: 因果マスキング、キャッシュ vs フルフォワード、ルーティング、バランシング、MTPターゲット、NaN処理、bf16マスターウェイトなど |
smoke_metal.py | AppleのGPUで動作するJAXオペレーション |
plots.py, charts.py | 図、すべてログ、チェックポイント、コーパスから描画 |
post/ | 解説記事の図、画像、スクリーンショット |
「190行」は、deepseek_v3.pyのドキュメンテーション文字列以降の、空白行およびコメント行を除いた行数をカウントしています:
tail -n +5 deepseek_v3.py | grep -cvE '^\s*(#|$)' # 190
簡略化された点
- Dense MoE計算。 すべてのエキスパートがすべてのトークンで実行され、選択されなかったものはゼロになります。ルーティング計算は正確ですが、スパースディスパッチやエキスパート並列処理はありません。
- MLAでの重み吸収なし。 潜在変数は明示的に展開され、読みやすく、推論時に遅くなります。
- 含まれていないもの: FP8トレーニング、DualPipe、ノード制限ルーティング、YaRNコンテキスト拡張、およびポストトレーニング。
- スケール。 36.2Mパラメータ vs 671B、6レイヤー vs 61、256トークンコンテキスト vs 128K。
データとライセンス
すべての学習テキストは米国でパブリックドメインです: Dashiell HammettのRed Harvest、The Dain Curse、The Maltese Falcon、およびContinental Opの物語(Standard EbooksのCC0版)、加えてProject Gutenbergから約200の探偵・犯罪小説。すべてのソースはsources.txtにリストされています。米国以外のパブリックドメインのステータスは異なる場合があります。
参照
DeepSeek-AI, DeepSeek-V3 Technical Report, 2024.
ライセンス
コード: MIT。学習テキストは米国でパブリックドメインです(上記参照)。