Bonsai-demo：llama.cpp 定制 fork 跑 2-bit 三值 27B 推理的完整解析

Bonsai-demo：llama.cpp 定制 fork 跑 2-bit 三值 27B 推理的完整解析

【免费下载链接】Bonsai-demoBonsai Demo项目地址: https://gitcode.com/GitHub_Trending/bo/Bonsai-demo

Bonsai-demo 是一套让 Bonsai 2 27B 这类 2-bit 级三值量化模型在本地机器上高效推理的工程方案，核心是 PrismML-Eng 维护的 llama.cpp 定制 fork。读完这篇，你会明白它为什么必须 fork 上游、自研格式与内核各自解决什么问题，以及脚本如何替你选对文件和二进制。

项目定位：上游 llama.cpp 覆盖不到的 2-bit 位型

Bonsai-demo 不是一个独立推理引擎，它 fork 的是 PrismML-Eng 团队维护的 llama.cpp 分支（prism分支），demo 本身只负责环境、模型下载、后端自动选择和社区基准的收集。上游主线早就支持了 1-bit 的Q1_0格式，但 Bonsai 2 27B 用的是两种自研打包：PTQ1_0（1.75 bit/权重，5.9 GB）和PQ2_0（2.13 bit/权重，7.2 GB），据仓库文档记载，它们的权重存放在旋转基里，推理时每次矩阵乘前必须做 Hadamard / 快速 Walsh–Hadamard 变换（FWHT）加 sign-flip——这套激活变换只有 fork 的二进制带着。最微妙的一点：主线 llama.cpp 加载 Bonsai 2 的Q2_0文件不会报错，它会正常"读开"然后输出乱码。所以作者非做不可的理由很直接：模型团队把 27B 压到 2 bit 出头，但没有任何现成解码器读得动，内核不跟，压缩就白做了。下图展示了 Bonsai 家族模型在体积—质量权衡中的位置：

格式层：三种打包文件与后端自动选择

Bonsai 2 有三种位宽各异的打包，存的是同一份权重，区别只在解码成本：

选文件这件事 demo 替你做了：scripts/common.sh里的pq2_0_ready_backend()维护一份"哪些后端有 PQ2_0 优化内核"的注册表——Metal、CUDA、ROCm、CPU（x86 VNNI / ARM NEON）有内核就选PQ2_0，Vulkan、SYCL 没有就自动回退到上一代官方 group-64Q2_0文件。你不需要记任何文件名，代价是 PQ2_0 比通用文件只小约 6%，收益全在专用内核上。上一代的格式迁移则是另一回事：旧*-Q2_0.gguf文件把 group-128 布局塞进了 type id 42，而主线后来把 id 42 标准化为 group-64。prism-v7 起的新构建读 id 42 一律按 group-64 解析，遇到旧文件会明确拒绝加载并指向两种新格式——27B 的文件名还有陷阱，官方文件叫Ternary-Bonsai-27B-Q2_g64.gguf而不是Q2_0_g64，按名字搜很容易先撞到已废弃的那个，详见 MODEL-FORMATS.md。

内核层：解码路径、FWHT 变换与上游合并进度

低比特格式能跑得动，靠的是 fork 里逐后端写的解码内核。Bonsai 2 的权重存在旋转基里，每个后端除了量化反变换，还要原生实现 FWHT 与 sign-flip 路径；据仓库文档记载，CPU、Metal、CUDA、ROCm 四个后端均已实现，Vulkan 与 SYCL 为部分支持（Vulkan 上个别 Intel 专有驱动版本会禁用 FWHT 走普通矩阵乘回退）。换个角度看，这部分工作正在逐块回流主线：

1-bit 的Q1_0内核（x86 AVX / NEON / Metal / CUDA / Vulkan）早已全部回馈上游，主线现在也能跑 1-bit 模型。但PQ2_0和PTQ1_0这两个打包类型没有上游支持的承诺，它们会一直住在 fork 里。

长上下文与投机解码：两个实验性开关

27B 支持 262K 上下文，混合注意力结构让 KV 缓存对它的尺寸来说很小：FP16 KV 每 token 64 KiB，100K 上下文约 6.3 GiB。BONSAI_KV4=1把 KV 缓存压到 Q4_0，100K 时降到约 1.8 GiB，代价是解码略慢——官方定位是"省内存的工具，不是提速工具"。配套一步：

./scripts/make_kv_bias.sh BONSAI_KV4=1 ./scripts/start_llama_server.sh

第一条命令跑llama-kv-mean-center生成模型专属偏置文件，写缓存时做一次减法，把 4-bit 量化的质量损失几乎零开销地补回来。投机解码是另一条实验线：fork 在主线自带的 DSpark 之上打了 log-SNR 条件、模型布局自动检测和 drafter 转换工具（gguf-dspark-to-dflash）几个补丁。上一代 27B 配一个约 0.6 GB 的 drafter，在 L40S（CUDA）上实测解码 1.8–2.4 倍提速，代码和数学类任务收益最大；Bonsai 2 目前还没有官方 drafter，开BONSAI_SPECULATIVE=1只会警告并回退普通解码，细节见 SPECULATIVE.md。

从空目录到 8080 端口出词

先 clone 并安装。macOS / Linux 只需两步：

git clone https://gitcode.com/GitHub_Trending/bo/Bonsai-demo cd Bonsai-demo && ./setup.sh

setup.sh只负责装依赖、下模型（Bonsai 2 27B 的PQ2_0权重加视觉投影器，约 7.8 GB）、从固定 release 拉当前平台的 fork 预编译二进制；Open WebUI 和代码解释器会多占几个 GB 和等待时间，用BONSAI_OPENWEBUI=0 BONSAI_CODE_INTERPRETER=0可跳过。它不启动服务，启动交给下一条：

./scripts/start_llama_server.sh

成功标志：llama-server 监听 8080 端口，浏览器打开http://localhost:8080的内置聊天页能正常出词。不想开服务的话，./scripts/run_llama.sh -p "..."可以一次性提问，终端直接回答案。Windows 用户改用setup.ps1和scripts/start_llama_server.ps1，可能要先Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass；PowerShell 侧注意脚本可能因驱动版本误判后端（后文会讲）。Apple Silicon 额外有一条 MLX 原生路径：setup.sh会装好.venv-vlm环境，./scripts/run_mlx.sh或./scripts/start_mlx_server.sh（8081 端口）即可，文本、图像和工具调用都支持。

进阶路径：源码编译、环境变量与二次运行

想自己编译（打补丁、调构建参数）的话，构建脚本会自动 clone fork 的prism分支做全量构建：

./scripts/build_mac.sh ./scripts/build_cuda_linux.sh

macOS 上自动区分 Apple Silicon（开 Metal）与 Intel（纯 CPU），Linux 侧自动探测 CUDA 版本，产物进bin/mac/、bin/cuda/。Vulkan 和 ROCm 没有一键脚本，按 README.md 的 "Building from Source" 一节手动 cmake 即可。

日常调参全部走环境变量，最有代表性的几个：BONSAI_CTX覆盖上下文（不传则按机器内存分层，8K 到 131K）；BONSAI_NGL=0强制纯 CPU，弱核显机器上通常比自动探测更好；BONSAI_KV4=1开 4-bit KV 缓存。完整 24 个变量见 environment_variables.md。还有两条进阶线值得看一眼：上一代 27B 的投机解码需要先把公开 drafter 转一遍（gguf-dspark-to-dflash加量化，两条命令），转换输出文件名必须保留dspark-dflash字样，启动脚本靠它发现 drafter；BONSAI_MMPROJ_CPU=1把视觉投影器留在内存里，释放约 0.9 GiB 显存给 KV 和上下文，代价是图像 prefill 变慢。想跑完整 agent 体验（工具调用、代码解释器、内置 demo 数据库），./scripts/start_openwebui.sh起 9090 端口，Bonsai 2 驱动 Hermes 从零写出并自测一个 3D 滑板游戏的完整记录在 AGENT-DEMO.md。

社区实测：Bonsai 2 27B 在不同硬件上的生成速度

以下数据全部来自仓库内 community-benchmarks/bonsai2/README.md 的社区提交（PQ2_0打包，TG128 为 128-token 生成速度，PP512 为 512-token 提示处理速度）：

说人话：8 GB 的 RTX 3070 上 27B 解码仍有 43.7 t/s，日常对话完全够用；Apple Silicon 上 MLX 路径普遍比 llama.cpp Metal 略快（27.1 对 24.3 t/s），M 系用户值得两条都试。上一代的 27B（ternary）成绩在 community-benchmarks/ternary-bonsai/README.md，其中 L40S 上开 DSpark 投机解码从 74.3 t/s 提到约 133–175 t/s。

你可能踩到的坑

• 主线 llama.cpp 加载 Bonsai 2 的Q2_0文件"成功"了——它识别了格式和架构，但跳过了必须的 Hadamard 与 sign-flip 变换，输出是乱码而不是报错。PQ2_0、PTQ1_0至少会因未知 type id 被明确拒绝。所以别把"加载成功"当成兼容，Bonsai 2 的 GGUF 一律用 fork 二进制。
• 旧*-Q2_0.gguf文件在新构建上直接打不开。那是迁移前 group-128 塞进 type id 42 的废弃布局，prism-v7 起会明确报错并指向替代格式，换PQ2_0或_g64文件；27B 搜文件名时认准Q2_g64这个不常规写法。
• Windows 上setup.ps1选中了 Vulkan 或 CPU 而不是 CUDA。新版 NVIDIA 驱动把nvidia-smi输出里的CUDA Version:改成了CUDA UMD Version:，旧版检测逻辑认不出来。症状是提示卡住不出 token，去bin/目录看实际下了哪个后端即可确认。
• M5 Mac 上 Metal 初始化失败、shader 运行时编译报错。macOS 26.2–26.4 部分版本的 MPP 头文件变更导致生态级的运行时编译问题（Ollama、whisper.cpp 同样中招），设GGML_METAL_TENSOR_DISABLE=1跳过 tensor API 即可，保留完整 Metal 速度，只损失 Neural Accelerator 的 prefill 加成。
• 上下文别手动拉满。旧版脚本曾默认-c 0（模型完整训练上下文 262K），小内存机器直接卡死；现在脚本已改为按内存分层，但仍爆内存时用BONSAI_CTX=8192 ./scripts/start_llama_server.sh这类方式显式压小。

写在最后

适合谁很清楚：想在笔记本或单张消费卡上跑 27B 级三值推理、接受绑定 fork 二进制的人，以及想研究低比特格式如何工程化落地（自研打包、逐后端内核、格式迁移、校准偏置）的人。不适合的是必须用上游主线 llama.cpp 或想零绑定集成的场景——Bonsai 2 目前只有 fork 能跑对。成熟度上，据仓库文档记载，上游合并已完成 CPU 与 Metal 的 FWHT 工作，CUDA 与 Vulkan 还在 review，PQ2_0/PTQ1_0没有上游支持承诺，但走官方Q2_0的路线正在推进，Hadamard 相关 PR 全部合并后 Q2_0 文件就能迁回主线运行，届时 fork 的必要性会自然下降。仓库地址：git clone https://gitcode.com/GitHub_Trending/bo/Bonsai-demo。

【免费下载链接】Bonsai-demoBonsai Demo项目地址: https://gitcode.com/GitHub_Trending/bo/Bonsai-demo