~/yomxxx/posts/2026-11-16-deepseek-v3-190-lines-pure-jax-workshop.mdx
Workshop

$ cat 190 行纯 JAX 跑通 DeepSeek V3:MLA、MoE 均衡与 MTP 本机实测

-- 6 min read ·

11 月 14 日 Hacker News 上一个仓库冲到 272 分:Vaibhaav-Tiwari/deepseek-v3-jax,把 DeepSeek-V3 技术报告里的架构用 190 行纯 JAX 从零实现并完整预训练了一遍——训练语料是 207 本公版侦探小说,就在一台 MacBook Air 上完成,最终验证损失 3.51,还能生成像模像样的福尔摩斯风格文本。

这类仓库我通常持怀疑态度:标题里的行数经常是营销数字,真正的复杂度藏在没写出来的数据管线和训练循环里。但这个仓库不一样——deepseek_v3.py 是 265 行(去掉空行注释后正好 190 行),带 39 项测试、Metal 烟雾脚本、完整消融数据,MIT 协议。于是我把它拉到我自己的 M5 Pro(48GB)上完整跑了一遍,本文是全程实录。

一、环境搭建:三分钟起步,一个坑

git clone https://github.com/Vaibhaav-Tiwari/deepseek-v3-jax && cd deepseek-v3-jax
uv venv -p 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt

依赖全部锁版本,其中最关键的一条是 jax-metal 0.1.1 只兼容 jax 0.4.34,升级 JAX 会让 Apple GPU 后端直接失效。uv 解析完整个环境只花了 15 秒。官方还发布了 v1.0 release,附 138MB 的最终 checkpoint 和预处理好的语料,想跳过 2.6 小时训练直接体验生成也可以。

二、先跑测试,再看模型

作者的工程习惯值得学:测试先行。CPU 上跑全部测试:

JAX_PLATFORMS=cpu .venv/bin/pytest tests.py -q
# 39 passed in 28.74s

39 项全过,28.74 秒,与 README 宣称一致。覆盖面包括因果掩码正确性、缓存解码与全量前向的一致性、路由逻辑、均衡机制、MTP 目标对齐、NaN 处理和 bf16 主权重精度。对于一份「教学代码」来说,这个测试密度超过了多数生产仓库。

接着是 Metal 烟雾测试,用来探明 jax-metal 在你的机器上到底支持哪些算子:

Metal device set to: Apple M5 Pro
PASS  matmul f32  (rel err 0.0e+00)
PASS  matmul bf16  (rel err 3.0e-03)
PASS  lax.top_k  (rel err 0.0e+00)
PASS  softmax + causal mask  (rel err 0.0e+00)
PASS  jit grad 6-layer einsum MLP  (grad norm 45.532)
FAIL  grad through 2-axis contraction: XlaRuntimeError
PASS  throughput f32  (5.09 TFLOP/s)
PASS  throughput bf16  (23.54 TFLOP/s)

我的机器上 12 项 PASS、1 项 FAIL,失败点是「双轴收缩上的梯度」——jax-metal 0.1.1 无法对 mhlo.dot_general 的双批维度版本求导。这不是坏消息而是关键情报:模型代码是照着这个限制写的。所有注意力计算都拆成单收缩维的 einsum,从根上绕开了 Metal 的这个坑。读源码前先跑烟雾测试,你就知道每一处设计选择背后的「为什么」。

三、四个核心机制,逐个用真实张量验证

1. MLA:480 个数压到 144 个

MLA(多头潜在注意力)的思路是把每个头的 K、V 联合压缩成一个低秩隐向量,推理时只缓存这个隐向量。这笔账我写了个脚本用真实张量核对:

standard MHA cache per token per layer: 480 numbers
MLA cache per token per layer:          144 numbers  (480/144 = 3.33x)
actual cache shapes per layer: {'c': [1, 256, 128], 'kr': [1, 256, 16]}

本配置 6 个头,标准 MHA 每 token 每层要存 6 乘(32 维 K_nope 加 16 维 K_rope 加 32 维 V)等于 480 个数;MLA 只存 128 维隐向量 c 加 16 维共享 RoPE 键 kr,144 个数,3.33 倍压缩。代码里的对应物是 init_cache 只建 c 和 kr 两个字段,解码时用 dynamic_update_slice 原位写入。

RoPE 的处理也值得注意:位置编码部分(kr)被故意留在压缩路径外面,由所有头共享一份。这就是「解耦 RoPE」——如果把它塞进隐向量再解压,旋转位置编码的非线性会破坏低秩压缩的数学性质。

2. DeepSeekMoE:1 个共享专家加 16 个路由专家,每 token 选 4 个

参数账我也实际盘了一遍:

total 36.2M | embed+head 6.3M | attn 1.8M | moe 25.1M | mtp 1.8M
active per token: 13.5M  (attn 1.85 + head 3.15 + dense ffn 1.18 + active moe 1.47 x 5 层)

总参数 36.2M,但每个 token 真正走过的权重只有 13.5M——MoE 的 25.1M 参数里每层只激活共享专家加 top-4 路由专家。这就是稀疏激活的直观体现:参数膨胀 2.7 倍,单 token 算力几乎不变。

3. 辅助损失-free 均衡:bias 只改「选谁」,不改「门控值」

这是全文最精妙的 10 行。传统 MoE 用辅助损失逼着路由均匀,但辅助损失会干扰主损失;DeepSeek V3 的方案是给每个专家维护一个 bias,路由时把它加到亲和度分数上参与排序,但门控数值仍然用原始分数:

scores = jax.nn.sigmoid(x @ w_router)                       # 原始亲和度
_, idx = jax.lax.top_k(scores + stop_gradient(bias), top_k) # bias 决定选谁
gated = where(picked, scores, 0.0)                          # 门控值仍是原始分数

我用随机输入做了个最小实验:给从未被选中的 3 号专家人为加 0.5 的 bias:

picked with zero bias:    [0, 1, 5, 14]
picked with +0.5 on e3:   [1, 3, 5, 14]
scores identical: True  | expert 3 newly picked: True

专家集合变了,分数一个没变。 stop_gradient 保证 bias 的调整不产生梯度——它靠训练循环里每步一次的符号更新(负载过重的专家 bias 下调,闲置的上调)独立运作,与损失函数完全解耦。

4. MTP:一个额外模块预测 t+2

多 token 预测的实现异常朴素:主模型预测下一个 token,一个独立的轻量模块拿主模型的隐状态拼上 t+1 token 的 embedding,再过一层 block 预测 t+2,损失权重 0.3。推理加速要靠 speculative decoding 才能兑现,这里只保留了训练时的表示学习收益。

四、我的复现实验:500 步均衡消融

作者跑过 2000 步的 bias 开关消融。我在 M5 Pro 上用 Metal 后端各跑了 500 步完整对照(36.2M 参数全配置,每步 8192 个 token):

指标bias 开启bias 关闭
step 250 验证损失5.0175.017
step 500 验证损失4.5594.565
专家负载范围5.74% – 6.95%0.45% – 18.54%
负载标准差0.22pp4.05pp
稳态吞吐约 26.8k tok/s约 29.0k tok/s

两个关键结论:

第一,均衡是免费的。 500 步时两者的验证损失差 0.006,开启 bias 的那一组反而略好——在噪声范围内。论文「均衡不伤模型质量」的主张在小规模下完全复现。

第二,负载坍缩真实且剧烈。 两组在 step 25 时的负载极差都是约 24 个百分点(8192 个 token 涌向少数专家),关掉 bias 的那一组到 step 500 仍然有专家只分到 0.45% 的流量、另有专家吃掉 18.54%——那个专家的显存和算力配额在真实分布式训练里就是瓶颈。bias 开启后 475 步内把极差压到 1.2 个百分点,每个专家稳稳落在 6.25% 均匀线附近。

顺带一提吞吐:我这里的稳态约 29k tok/s,比作者 M5 Air 的 10.7k 中位数快近 3 倍,主要差在内存带宽。 Metal 不是确定性后端,数字会有小幅度波动。

五、生成实测:侦探小说味的 36M 小模型

加载官方 checkpoint 生成两段续写,提示词与作者相同:

The fog came in off the rain from the great, cloudy sun. The darkness was
bright and dark. Holmes led the way into the garden and up to the window.
On the mantel-piece was the old leather chair which was in the centre of
the room, and held the candle on the mantelpiece...

语感、场景切换、对话格式都对,事实一致性为零(Holmes 出现在本不属于他的语料里)。120 个 token 两次采样全程 11.6 秒。这符合预期:36M 参数加上 21.7M token 的训练量,目标是验证架构机制,不是逼近基础模型。

六、工程判断:教学价值满分,生产价值有限

能不能用? 作为架构教材,这是目前我能找到的 DeepSeek V3 机制最完整的可运行实现——MLA、解耦 RoPE、共享加路由 MoE、无辅助损失均衡、序列级均衡损失、MTP、bf16 混合精度、隐向量缓存解码,一应俱全且每行都能读懂。想给团队讲清楚 DeepSeek V3 为什么快,直接带人读这 190 行,比啃 60 页技术报告高效得多。

坑在哪? 三处教学性简化必须在迁移前补齐:MoE 是稠密计算(每个专家对每个 token 都跑一遍再置零),生产必须换稀疏分发加专家并行;MLA 没有权重吸收,隐向量显式解压好读但推理慢;FP8、DualPipe、YaRN 长上下文全部缺席。另外 checkpoint 是 pickle 格式,README 自己都标注了反序列化可执行任意代码,别随手加载来路不明的权重。

硬件现实。 jax-metal 的算子覆盖仍是短板(双轴收缩梯度不支持),模型代码是绕着限制写的,照抄这套写法到 CUDA 上没有收益。真要在 Apple Silicon 上做训练,这份代码是目前少见的、把 Metal 兼容性当一等公民对待的参考实现。

仓库地址:github.com/Vaibhaav-Tiwari/deepseek-v3-jax(MIT 协议),作者的逐段讲解见其博客 write-up。

Frequently asked questions

为什么用纯 JAX 复现 DeepSeek V3 而不是 PyTorch?
作者的核心选择是零框架:不用 Flax、不用 Equinox,参数就是普通字典套数组,模型每个部件都是一个能从头读到尾的函数。这让 MLA 的压缩路径、MoE 的路由逻辑完全暴露在读者眼前,是学架构最快的方式。PyTorch 生态更全,但 nn.Module 的封装层会把这 190 行膨胀到上千行,教学价值反而被稀释。
MLA 到底省了多少 KV 缓存,这笔账怎么算?
标准多头注意力每 token 每层要缓存每个头的 K_nope、K_rope、V,本配置是 6 头乘 80 个数等于 480 个数。MLA 只缓存低秩压缩后的隐向量 c(128 维)加上全头共享的 RoPE 键(16 维),共 144 个数,压缩 3.33 倍。我在本机用真实张量核对过形状,与 README 宣称一致。注意这是教学配置的倍数,DeepSeek V3 正式版的比例还要更高。
辅助损失-free 负载均衡效果到底怎么样?
我跑了 500 步对照实验:关掉均衡 bias 时专家负载从 0.45% 到 18.54%,极差 18.1 个百分点;开启后压到 5.74% 到 6.95%,极差仅 1.2 个百分点,而验证损失 4.559 对 4.565 基本持平甚至略优。bias 的妙处在于它只参与「选谁」,不参与门控数值,我用随机输入验证过:加入 bias 后选中的专家集合变了,但亲和度分数一个都没变。
这套代码能直接拿去做生产推理吗?
不能。作者明确做了三处教学性简化:MoE 是稠密计算,每个专家都对每个 token 跑一遍再置零,生产系统必须做稀疏分发;MLA 没有权重吸收,隐向量解码时显式展开,省显存但不省算力;FP8 训练、DualPipe 流水线、节点限制路由和后训练全部缺失。把它当架构教学材料很好,当生产基座需要自己补齐这些。
在 Mac 上跑这套代码需要什么配置?
README 要求 Apple Silicon 加 Python 3.12 和 uv,发布跑用了 24GB 内存的 M5 Air。我的 M5 Pro 48GB 更宽裕。有两个坑:jax-metal 0.1.1 锁死 jax 0.4.34,不要升级;jax-metal 不支持双轴收缩的梯度,但模型代码用 einsum 分解绕开了。机器内存小可以加 --config small 换 4 层 8 专家的小配置,纯 CPU 也能跑通全部 39 项测试。
// next.txt ›

Some outbound links in this post are affiliate links — see disclosure.