# Bonsai 2 加速进展速报（截至 2026-09-20）

> 检索范围：官方 PrismML fork（releases / commits / PR / issue）、Bonsai-demo 仓库、HF、社区项目、技术媒体。
> 重点：**加速**。所有数字均标注来源；本机实测与我们自己的部署现状分开写。
> 相关文件归档在 `社区加速资料/`。

---

## 0. 一句话结论

**官方发布后 3 天内，社区已经把官方缺失的两条加速路线都补上了。**

| 路线 | 官方 | 社区（已可用） |
|---|---|---|
| **MTP 投机解码** | ❌ 三值转换时把 MTP 层丢了 | ✅ **把 Qwen3.8-27B 的 MTP 头嫁接回去**（`sudoingX/bonsai2-small-gpu`）|
| **解码内核提速** | 基线 | ✅ **PTQ1_0 mat-vec 内核 1.5×**（同上，PR #218）|
| dspark 草稿模型 | ❌ 未发布 | ⚠️ 仅 Apple/MLX 侧、且对 Bonsai 只有 1.07–1.13× |

**组合效果（RTX 3060 12GB 实测）**：25.0 tok/s（原版）→ **50.1 tok/s**（内核 + MTP），**约 2.0×**。

**你的 5060 Ti 正好在覆盖范围内**：该内核编译支持 **sm_86 ~ sm_120**。

---

## 1. 官方现状：Bonsai 2 目前**没有任何投机解码**

| 项 | 结论 | 依据 |
|---|---|---|
| MTP | ❌ **模型里没有 MTP 层** | 本机实测报错：`context type MTP requested but model doesn't contain MTP layers` |
| dspark drafter | ❌ **未发布** | 官方 `download_models.sh` L144 注释：`Bonsai 2 has no dspark drafter`；HF 仓库无 drafter 文件 |
| ngram（官方文档） | 未提及 | — |

官方 fork 上的相关 PR 仍 **全部 open**（未合并）：

| PR | 标题 | 状态 |
|---|---|---|
| **#217** | qwen35: apply the Hadamard inverse to token embeddings in the MTP draft graph | open |
| **#218** | （PTQ1_0 mat-vec 内核）| open |
| **#221** | cuda: Bonsai 2 27B at the full 262k window with the MTP head on 12 GB Ada | open（2026-09-20 提交，25 commits）|
| **#215** | hybrid PTQ1_0 dispatch | open |
| **#94** | sycl: add Prism Q1_0 and Q2_0 g128 support（Intel Arc 路线）| open |
| **#85** | Docs: `--kv-mean-center` workflow for q4_0 K-cache（**262K 上下文在 16GB 卡上需要**）| open |

---

## 2. 社区方案 A：MTP 头嫁接（最重磅）

**项目**：[sudoingX/bonsai2-small-gpu](https://github.com/sudoingX/bonsai2-small-gpu) —— 副标题直接写着 *"the Qwen 3.8 MTP head grafted back onto the ternary file for lossless speculative decoding"*。

### 原理

从任意**带 `blk.64.nextn.*` 张量的 Qwen3.8-27B GGUF**（捐赠者，如 `unsloth/Qwen3.8-27B-GGUF` 的 UD-Q4_K_M，16.5 GB）里：
1. **抽头**：复制 `blk.64` 的 15 个张量（MTP 解码块 + `nextn.eh_proj / enorm / hnorm / shared_head_norm`），再补第 16 个 `blk.64.nextn.embed_tokens.weight`（捐赠者的 `token_embd` 副本）→ 1,066,172,160 字节，**有官方公布的 sha256 可校验**
2. **合并**：字节级写进 Bonsai 2 GGUF → 867 张量 / 7,012,820,512 字节，**同样有 sha256**
   - 头部新增 `qwen35.nextn_predict_layers = 1`，`block_count` 64 → 65
   - **可自证无副作用**：`merge.py --strip` 反向剥离后 sha256 = 原文件 `53107f53...`（逐字节还原）
3. **为什么需要单独的 embedding 表**：Bonsai 2 的 embedding 在 Hadamard 旋转基下，fork 的 MTP 图不做逆变换，所以头必须自带一份普通 embedding 表

### 用法

```bash
llama-server -m Ternary-Bonsai-2-27B-PTQ1_0-mtp.gguf -ngl 99 -fa on \
  -c 131072 -np 1 -ctk q4_0 -ctv q4_0 --jinja \
  --temp 1.0 --top-p 0.95 --top-k 20 \
  --spec-type draft-mtp --spec-draft-n-max 1
```

⚠️ **必须 `--spec-draft-n-max 1`，不是 3**。原因：PTQ1_0 内核下 3-token 验证批次成本 = 2.4 个单步，n-max 2/3 反而**比不开更慢**。

### 实测数字（RTX 3060 12GB，131072 上下文，关思考）

| 配置 | 解码 tok/s |
|---|---:|
| 原版 fork + 原文件 | 25.0 |
| 原版 fork + MTP 头 | 27.1 |
| **内核分支 + MTP 头** | **50.1**（代码 53.2）|

接受率 0.5（散文）～ 0.95（代码）。显存：131072 用 10,638 MiB；163840（q4_0 草稿 KV）用 11,726 MiB；196608 在原版 fork 上 OOM。

### ⚠️ 最重要的警告：原版 fork 上**不是无损的**

作者自己写得很清楚：

> On this fork and card the greedy texts differ after 14 to 52 tokens, at near ties, because the CUDA kernels are **not batch-size invariant on PTQ1_0**. **Treat the numbers above as throughput, not as a lossless speedup.**

只有**用它自己的内核分支 + `GGML_CUDA_BATCH_INVARIANT=1`**，贪心输出才与不开投机**逐字节一致**。所以：
- 只想快：原版 fork + MTP 头即可，但输出会有细微差异
- 要无损：必须同时上内核分支（见方案 B）

### 附赠：他们也踩了和我们一模一样的思考坑

> the GGUF chat template defaults `reasoning_effort` to `xhigh` … on the 3060 at a 4,096-token client cap that returned nothing on an SVG, an HTML page and a 100-line Python script (**6 of 6 greedy runs spent the whole cap inside `<think>`**), and the SVG never finished thinking even at 16,384.

他们的解法：**`--reasoning-effort medium`**（思考开、不额外加那句 "think carefully"）→ 同批任务 45–124 秒完成，思考 22–2381 token。
→ **这独立印证了我们昨晚的诊断与修复方向**（我们的默认档用 `--reasoning off`，更激进；两者都对）。

---

## 3. 社区方案 B：PTQ1_0 解码内核（1.5×）

**分支**：`sudoingX/llama.cpp` 的 `pr-ptq1-mmv`（上游 PR **#218**）。

| | prebuilt fork | 打补丁后 | 倍数 |
|---|---:|---:|---:|
| tg128（新鲜上下文） | 26.43 | **40.54** | **1.53×** |
| tg128 @ 16384 | 21.73 | 30.85 | 1.42× |
| tg128 @ 65536 | 14.3 | 17.9 | 1.25× |
| tg128 @ 131072 | 9.8 | 11.4 | 1.16× |
| pp512 | 269.6 | 267.8 | 不变 |
| 显存 | 7.3 GB @64K / 11.7 GB @262K | 同 | 不变 |

- **预处理（prefill）不变，显存不变** —— 纯解码加速
- 小批次也大幅改善：pp2 34.1→61.1、pp3 33.3→72.0、pp4 35.3→81.0（对投机解码的验证批次尤其关键）
- **架构覆盖 sm_86 ~ sm_120**（作者注：`sm_90` / `sm_120` 的 host-stub 失败已在 `2578fdf` 修好）→ **你的 5060 Ti（sm_120）在内**
- ⚠️ **只针对 `PTQ1_0` packing**。我们当前部署的是 `PQ2_0`（选它的理由是 Blackwell 上 pp 快 2.16×）—— 所以这条要连模型文件一起换

---

## 4. 社区方案 C：12GB Ada 上跑满 262K + MTP（PR #221）

`professorpalmer`，2026-09-20 提交，25 commits，目标合并进官方 `prism` 分支。组合了 **#218（内核）+ #215（hybrid PTQ1_0 dispatch）+ 原地 q4_0/q8_0 K/V flash attention**，标题即目标：*"Bonsai 2 27B at the full 262k window with the MTP head on 12 GB Ada"*。

→ 这条如果合并，就是"小显存 + 满上下文 + MTP"的完整方案。**值得盯**。

---

## 5. Apple 侧：mlx-dspark（对 Bonsai 收益很小）

[ARahim3/mlx-dspark](https://github.com/ARahim3/mlx-dspark)：DeepSeek DSpark 与 z-lab DFlash 的 **MLX 原生移植**，声称 Apple Silicon 上最高 4× 无损加速，覆盖 Gemma-4 / Qwen3.8 / Nemotron / **Bonsai** 等。

但对 Bonsai 效果有限：

| 目标 | 加速比 | 说明 |
|---|---:|---|
| Ternary-Bonsai-27B（上一代，2-bit） | **1.07–1.13×**（代码 1.13×） | 官方文档把 Bonsai 列为**反例**：混合注意力的 2-bit 验证是 compute-bound，投机常常不划算，工具的 `--max-draft auto` 会自动"停到不亏的位置" |
| Bonsai 2 的 MLX 版 | **not measured yet** | — |

→ **Apple 路线对 Bonsai 不香**，别指望。这也侧面说明：**NVIDIA/CUDA 上的 MTP 嫁接路线（方案 A）才是正解**。

---

## 6. 其他后端与生态

| 方向 | 状态 |
|---|---|
| **SYCL**（Intel Arc）| PR **#94**：为 Prism Q1_0 / Q2_0 g128 加 SYCL 支持，open |
| **q4_0 K-cache + `--kv-mean-center`** | PR **#85** 文档：**262K 上下文在 16GB 卡上需要这个流程** ← 和你的机器直接相关 |
| MLX Serve | `ddalcu/mlx-serve` v26.9.5 已含 Bonsai，并带 iOS app |
| 浏览器内推理 | 已有媒体报道 Bonsai 2「可在浏览器里跑」（WebGPU 方向）|
| MoE / 多序列 | PR #107（MoE prefill 融合）、#207（GDN 原地 recurrent state 更新，多序列解码）|

---

## 7. ⚠️ 一条与**我们实测冲突**的官方 issue（重要）

官方 fork **issue #203**（2026-09-19，`lyb618888-bojian`）：

> `--spec-type ngram-* silently no-ops on Ternary-Bonsai-2 (hybrid GDN): flag accepted, never activates, zero logging`
> 环境：**Apple M4 Max / macOS 15 / Metal backend**，模型 `Ternary-Bonsai-2-27B-PQ2_0.gguf`
> 现象：`timings.draft_n == null`，解码 31.7 tok/s 与无投机完全相同，日志里 grep 不到任何 spec/ngram 字样。
> 对照实验：同 build 同模型下 `--spec-type draft-simple -md Qwen3.5-4B-Q4_K_M.gguf` **是生效的**（draft_n=274 / accepted=25），说明投机管线本身对 hybrid 目标是通的，只有 n-gram 实现静默失效。

**但我们在你的 CUDA 机器上实测 ngram-map-k4v 是生效的**：

| 任务 | 基线 | ngram-map-k4v | 接受率 |
|---|---:|---:|---:|
| 逐句抄录 | 47.7 | **126.2 tok/s（2.65×）** | 85%（draft_n=452）|
| 提取数字 | 47.9 | 76.4 tok/s | 72% |

→ **该 issue 至少是 Metal 特异的**；**CUDA 上 n-gram 投机可用**（我们已部署并验证）。
→ 但如果以后要在 Mac 上跑 Bonsai 2，**别指望 n-gram**，那里要用 draft-simple + 小模型。

---

## 8. 对你这台 5060 Ti 的建议（按性价比排序）

### ① 现状（已做，零风险）
`PQ2_0` + `ngram-map-k4v` + Q4 KV。已拿到：pp512 **1001 t/s**、高重复任务 **2.65×**（127 tok/s）。

### ② 收益最大：嫁接 MTP 头 + 上内核分支 ⭐ 推荐
需要：下载 `unsloth/Qwen3.8-27B-GGUF` 的 UD-Q4_K_M（**16.5 GB**）、约 **25 GB** 磁盘、编译 `pr-ptq1-mmv`（sm_120）、把 `PTQ1_0` 换成嫁接后的文件。

预期收益（按 3060 数据外推，**属推算非实测**）：

| 项 | 3060（实测） | 你的 5060 Ti（推算） |
|---|---:|---:|
| 基线（原版 fork, PTQ1_0） | 26.3 | 45.1（我们实测）|
| + 内核分支 | 40.5（1.53×） | **~69** |
| + MTP 头 | 50.1 | **~85–95** |

⚠️ 前提与风险：
- 3060 是 360 GB/s、5060 Ti 是 448 GB/s，比值不完全线性，**必须实测**
- **原版 fork 上非无损**（贪心输出 14–52 token 后分叉）；要无损必须同时上内核分支 + `GGML_CUDA_BATCH_INVARIANT=1`
- 我们当前用 PQ2_0，换 PTQ1_0 会牺牲它的 2.16× prefill 优势 —— 但内核补丁也大幅改善了小批次 prefill（pp4 35→81 t/s），可能抵消

### ③ 观望：等 #218 / #221 合并进官方 fork
合并后**直接换预编译二进制 + 用嫁接文件**即可，不用自己编译。这是最省事的路径。

---

## 附：来源

| 来源 | 链接 |
|---|---|
| 社区 MTP 嫁接 + 内核项目 | [sudoingX/bonsai2-small-gpu](https://github.com/sudoingX/bonsai2-small-gpu) |
| ↑ 嫁接配方（含全部 sha256）| `社区加速资料/sg_recipe.txt` |
| ↑ 内核实测报告 | `社区加速资料/sg_KERNEL_REPORT.md` |
| ↑ 他们的思考坑记录 | `社区加速资料/sg_reasoning_effort.md` |
| Apple MLX dspark | [ARahim3/mlx-dspark](https://github.com/ARahim3/mlx-dspark)（`社区加速资料/mlx-dspark.md`）|
| 官方 fork PR/issue | [#217](https://github.com/PrismML-Eng/llama.cpp/pull/217) · [#218](https://github.com/PrismML-Eng/llama.cpp/pull/218) · [#221](https://github.com/PrismML-Eng/llama.cpp/pull/221) · [#203](https://github.com/PrismML-Eng/llama.cpp/issues/203) · [#85](https://github.com/PrismML-Eng/llama.cpp/pull/85) · [#94](https://github.com/PrismML-Eng/llama.cpp/pull/94) |
| 官方发布 | [prismml.com/news/bonsai-2-27b](https://prismml.com/news/bonsai-2-27b) |

*本速报 2026-09-20 编制；项目处于高速迭代期，建议数日内复查官方 fork 的 PR 合并状态。*