openTPU移植新模型实战:从Qwen3到线性注意力Qwen3.5、Gemma 4的完整经验
openTPU移植新模型实战:从Qwen3到线性注意力Qwen3.5、Gemma 4的完整经验
openTPU 是一个开源 AI 加速器,一个仓库里同时包含 RTL、ISA、位精确模拟器、内核编译器和性能分析器,可在 Kintex-7 PCIe 卡上运行 Qwen3、LFM2.5、Qwen3.5 与 Gemma 4 等真实模型。这篇文章总结在 openTPU 上移植新模型家族的完整经验:如何读懂模型结构、如何补齐缺失的硬件算子、如何调度内存、如何做到与模拟器逐位一致,以及最后如何量出真实的加速收益。
为什么移植新模型不是一件"小事" 🤔
openTPU 的设计哲学是"一切数据移动都是指令":没有缓存、没有隐藏调度,序列器每周期向 DMA、矩阵单元(MXU)、向量单元(VPU)、量化器下发指令。这种透明性的反面是——每一个新算子、新内存模式都要显式地在 ISA 和 RTL 里落地。
好消息是,移植的套路是可复用的。仓库里已经沉淀了四个模型家族的经验文档,本身就是一份现成的"移植手册":
- docs/lfm2.md:LFM2(混合线性注意力)
- docs/qwen35.md:Qwen3.5(线性注意力 DeltaNet)
- docs/gemma4.md:Gemma 4(逐层嵌入 PLE + KV 共享)
- docs/llama.md:SmolLM3 / Phi-4-mini(Llama 风格,几乎零改动)
下面按移植的实际步骤拆解。
第一步:用 Spec 抽象出模型结构
每个模型家族在 opentpu/llm/ 下都有一个模块(opentpu/llm/qwen35.py、opentpu/llm/gemma4.py 等),里面最核心的是一个 Spec 数据类:层数、隐藏维度、头数、词表、量化格式、特殊结构标志位。
移植新模型时,Spec 是你和编译器之间的"合同"。opentpu/llm/qwen3.py 的 Spec 用开关字段兼容了一整族模型——qk_norm、nope、rotary 部分旋转维度、embed 从 int8 LM head 取行……SmolLM3 和 Phi-4-mini 正是靠这些开关,一行新硬件都不加就跑起来了(见 docs/llama.md)。
💡 经验 1:先数"差异字段",再写代码。如果新模型只是 Qwen3/LFM2 的变体,优先在 Spec 里加开关,程序词保持逐位不变,回归成本最低。
第二步:补齐缺失的硬件算子(Qwen3.5 的关键一役)⚡
Qwen3.5 的主层是 Gated DeltaNet 线性注意力,每个头维护一个 128×128 的状态矩阵,逐 token 递推:
S = exp(g) S
delta = beta (v - S^T k)
S = S + k delta^T
o = S^T q
原版移植时 ISA 里没有现成算子,开发者先用 7 趟 VPU 操作模拟递推,结果只跑到 DRAM 屋顶线的 69%。后来新增 3 条 VPU 指令,把递推压到 3 趟:
- RDOT:行点积(
St k、St q两次读取都变成行点积) - OUTER:带衰减的秩 1 更新,原地完成
- LOG2:用
log2高效实现 softplus
效果立竿见影:单 token 从 11.5M 周期降到 8.4M,屋顶线占比 69% → 95%(实测数据见 docs/qwen35.md 的 Performance 一节)。
💡 经验 2:先用现有算子"拼"出功能版本跑通,再用 profiling 找出瓶颈算子,最后才动 ISA。openTPU 的模拟器与 RTL 逐位对齐,改一条指令立刻能验证正确性。
第三步:把大状态流进小内存
DeltaNet 状态每层 1 MiB(fp32),是片上 TMEM 的 16 倍。openTPU 的解法是状态常驻 DRAM、按头流经 TMEM:
- 双缓冲流水:VPU 更新当前头时,DMA 同时存上一头、载下一头;
- 头成对执行:卷积、SiLU、L2 norm 等小算子一次做两个头,
out_proj按 4 头一组累加,比逐头执行再省 7.9% 周期; - 状态转置存储,让两次读取都变成行点积。
这些调度细节(哪个写操作排在哪个读操作旁边、硬件循环怎么展开)是移植中最"脏"也最值钱的部分,docs/qwen35.md 的 "How it maps" 一节值得逐行阅读。
第四步:处理模型"个性"结构(Gemma 4 的案例)
Gemma 4 是第四个模型家族,它带来的挑战几乎都不是新算子,而是新结构:
| 结构 | openTPU 的解法 |
|---|---|
| 逐层嵌入表 PLE(26 万行 × 8960 维,4.7 GB) | 留在卡上,用 MXU 的"one-hot 矩阵乘"完成逐行 gather 与反量化,每 token 只多读 0.41 MB(占权重 0.03%) |
| 28 层滑动窗口 + 2 种 KV 缓存 | 环形缓存 768 槽位,运行时掩码在卡上用查找表计算 |
| 后 20 层不计算 K/V(KV 共享) | 硬件循环里 4 层一个单元,共享层只读源层缓存 |
logits soft cap(30 tanh(z/30)) |
单调变换不改变 argmax,贪心解码直接在主机/采样器上施加 |
| 词表 262144,fp32 嵌入放不下 | 复用 Qwen3.5 的方案:从 int8 绑定的 LM head 里 gather 行 |
结果:Gemma 4 E2B 在卡上 decode 10.57 tok/s,prefill 32.1 tok/s,DRAM 带宽用到峰值的 92%。完整映射见 docs/gemma4.md。
💡 经验 3:大表(嵌入、RoPE、PLE)统一"建表 + 卡上 gather"。只要表行间隔规整,运行时位置可以只用 1-2 个参数寄存器寻址,程序体积和主机开销都最小。
第五步:逐位一致的验证体系 ✅
移植最怕"看起来能跑"。openTPU 的验证分三层:
- 模拟器 vs HF fp32:
tools/compare_hf.py/ tools/validate.py 对比贪心 token 与 logits,报告 top-1 一致率、KL 散度,并区分"量化本身损失"与"设备 bug"; - RTL vs 模拟器逐位一致:
--backend rtl --against isa,要求 logit 0 ulp 差异; - 真卡 vs 模拟器:
otpu-selftest --sim --model qwen35等,卡上每个 decode 路径(常驻程序、逐位置、卡上 generate 循环)都要与模拟器 bit-for-bit。
Qwen3.5 的完整测试矩阵在 tests/test_qwen35.py,覆盖随机小模型、真实 0.8B 的 8 个贪心 token、group-major 布局位精确等场景。
第六步:量化与调优,把速度榨出来 📈
跑通只是起点。openTPU 的 decode 受 DRAM 带宽约束,速度基本等于"每 token 权重字节数"的倒数,于是:
- 4-bit 权重(fp4 + 两级 block scale):decode 提速 40%~45%,LM head 保留 int8 保精度,细节见 docs/quant.md;
- 按层混合格式(
wformat="mix"):用 dKL 指标按"精度损失 ≤ 0.1 × 提速收益"的规则为每个模型选混合方案,机制在 docs/formats.md; - DSTEP 指令(Qwen3.5):状态由 DMA 数据通路直接流过,VPU 不再做 3 趟状态扫描,投影 decode 从 19.0 提升到 24.6 tok/s。
最终实测成绩(生产镜像,2026-10-01,详见 README.md):
| 模型 | 权重 | Decode | Prefill | DRAM 效率 |
|---|---|---|---|---|
| Qwen3-0.6B | int8 / 4-bit | 21.6 / 31.3 tok/s | 92~103 tok/s | 82~84% |
| Qwen3.5-0.8B | int8 / 4-bit | 17.6 / 24.5 tok/s | 61~67 tok/s | 83~85% |
| Qwen3.5-2B | int8 / 4-bit | 8.0 / 12.1 tok/s | 38~42 tok/s | 92~94% |
| Qwen3.5-4B | 4-bit + int8 head | 5.88 tok/s | 12.9 tok/s | 92% |
| Gemma 4 E2B | 4-bit + int8 head | 10.57 tok/s | 32.1 tok/s | 92% |
移植检查清单 📋
把四次移植的经验浓缩成一张清单:
- 写 Spec:数清与已有家族的结构差异,能开关就不新写模块;
- 先拼算子跑通:用现有 ISA 拼出功能版本,接受慢;
- profiling 找瓶颈:用 Lens(docs/lens.md)看周期去哪了,缺算子才动 ISA;
- 大表建表 + 卡上 gather,运行时参数尽量用 1~2 个寄存器表达;
- 三层验证:模拟器 vs HF → RTL 逐位 vs 模拟器 → 真卡逐位 vs 模拟器;
- 量化与调度收尾:4-bit / mix 格式 + 流水/循环调度,最后量出 tok/s 和 DRAM 利用率。
值得一提的是,同一套设计还能通过 targets/*.toml 构建到 ASIC:NanGate45 工艺上 33 个 SRAM macro + 约 56 万标准单元,从 SystemVerilog 到布线版图全程开源工具链完成(docs/asic.md)——移植模型时写的每一行内核,最终也会跑进芯片里。
想上手的话,从 docs/isa.md 和 opentpu/kernels/ 读起,再对照上面四份模型文档,你就能完整复现"一个模型家族从 0 到上卡"的全过程。


