Bonsai-demo 完整指南：两条命令跑起 27B 级 2-bit 本地推理

Bonsai-demo 完整指南：两条命令跑起 27B 级 2-bit 本地推理

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

如果你想在自家电脑或笔记本上跑 27B 级的推理模型，Bonsai-demo是目前最省心的入口之一：它打包了 llama.cpp 定制 fork 的预编译二进制和一整套脚本，自动下载 Bonsai 2 27B 的 2-bit 量化模型（PQ2_0打包，约7.2 GB），两条命令就能得到带网页聊天界面的本地推理服务。模型保留了98.2%的 FP16 智能水平，支持262K token上下文，还能输入图片、调用工具。

这套方案的钥匙在于：权重采用三值（ternary）格式打包，每个权重平均只用约 2 bit——27B 级模型因此能装进一个 7GB 文件。但也正因如此，原版 llama.cpp 没法直接跑：部分格式是 fork 专属的自研打包，部分官方格式还依赖只有 fork 才带的激活变换。Bonsai-demo 要做的事，就是把"必须用特定二进制"这件麻烦事变成一键体验。

7GB 文件跑 27B：Bonsai-demo 到底解决什么问题

Bonsai-demo 不是一个模型，而是一份"二进制 + 脚本 + 模型下载"的完整安装包。模型来自 Bonsai 家族——默认 Bonsai 2 27B，另有早期 Bonsai 1-bit 与 Ternary-Bonsai 家族（1.7B / 4B / 8B / 27B）；二进制来自 PrismML-Eng 的 llama.cpp fork（demo 当前固定prism-b10772-e8fd209版本）；脚本负责检测硬件、挑对文件、拉起服务的全部琐碎工作。

适合人群：有一张 NVIDIA / AMD 独立显卡或 Apple Silicon 笔记本，想在本地体验 27B 级推理、视觉与工具调用，又不想碰编译和调参的读者。Bonsai 2 27B 提供三种打包，存的是同一套权重：

值得注意的是兼容性陷阱：原版 llama.cpp 能"加载"Q2_0文件且不报错，但因为缺少 Hadamard 与符号翻转变换，输出是乱码——加载成功不等于兼容。所以要跑 Bonsai 2，必须用这套 fork 二进制。

先看数字：真实硬件上的社区实测速度

下面数据来自社区提交的 community-benchmarks/bonsai2/README.md。PP512 是 512 token 提示词的预填充速度，TG128 是生成阶段速度：

即使是一张 8GB 显存的 RTX 3070，27B 级模型也能跑到 43 t/s 的生成速度——这就是低比特内核优化的直接收益。对比同一张卡的两种打包也有意思：RTX 5080 上PQ2_0的预填充是 2,345 t/s，而更小的PTQ1_0只有 1,017 t/s，接近 2.3 倍差距——多花 1.3 GB 体积换来的是明显的提示词处理提速，这也是 demo 默认下载PQ2_0的原因。

这张表还是持续生长的：社区按TEMPLATE-llama-cpp.md模板复制一份、命名为<backend>-<hardware>-<os>.md、填上实测结果提 PR，就能让自己的硬件出现在榜单上。想查"我的机器大概什么水平"，这里是现成的参照系。

技术层：三处引擎端定制

1️⃣ 三值双打包：文件更小，内核全平台

PQ2_0是 fork 自研的 group-128 打包（ggml type id142），比官方 group-64 的Q2_0小约 6%，文件与内存占用都更低，并在 CUDA、Metal、ROCm、CPU（x86 VNNI / ARM NEON）上有专用加速内核，Vulkan 与 SYCL 也已有设备相关的内核路径，完整矩阵见 BACKEND-SUPPORT.md。官方Q2_0文件则保持最宽的后端覆盖，作为无优化后端时的回退——所以你在任何机器上都不需要记该下哪个 GGUF 文件。顺带一提：上一代的 1-bitQ1_0格式已合并进主线 llama.cpp，1-bit 模型用原版构建也能跑。

2️⃣ 16 平台预编译二进制：跳过一切编译

fork 的 Release 频道提供16个平台的现成二进制：macOS（Apple Silicon / Intel / KleidiAI）、Linux（CPU / CUDA 12.4 / 12.8 / Vulkan / ROCm 7.2）、Windows 全系，甚至包括 iOS XCFramework。setup.sh会自动检测操作系统、架构、GPU 和 CUDA 版本，把对应压缩包下载进bin/目录，全程无需编译。

3️⃣ DSpark 投机解码：代码与数学任务最高 2.4 倍

上一代 27B 附带一个约0.6 GB的草稿小模型（drafter）：它先草拟 4 个 token，主模型一次验证，temperature 0 下输出与正常解码完全一致。L40S（CUDA）上实测三值 27B 解码提速1.8–2.4 倍，代码/数学类任务收益最大，Apple Silicon 仅三值代码/数学受益（约 1.2 倍）。开启方式是设置BONSAI_FAMILY=ternary、BONSAI_MODEL=27B、BONSAI_SPECULATIVE=1后照常启动服务，脚本会自动追加 drafter 参数并把上下文提到 16384；验证是否生效看 API 响应timings里的draft_n字段。Bonsai 2 本身暂无官方 drafter，开了只会警告后按普通模式运行。完整说明见 SPECULATIVE.md。

使用层：三个不用记参数的便利设计

4️⃣ 上下文自动分档：按内存定大小，不炸机

27B 支持262,144 token上下文，FP16 KV 缓存每 token 64 KiB（100K 时约6.3 GiB）。启动脚本默认不用满训练上下文，而是按你的 RAM 自动选安全档位：小机器从 8K 起步，71GB 以上的机器可到 131K。需要强制指定就传BONSAI_CTX=8192之类的值，0等价于不设置、走自动档。

5️⃣ 4-bit KV 缓存：内存再砍 3.5 倍，偏置补质量

BONSAI_KV4=1把 KV 缓存从 FP16 换成 Q4_0，每 token 成本从 64 KiB 降到约18 KiB——100K 上下文从约 6.3 GiB 降到约1.8 GiB。4-bit 量化在激活均值非零的通道上会损失一点精度，配套的llama-kv-mean-center校准工具能补回大部分：

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

跑一次生成模型专属的<Model>-kv-bias.gguf，服务端自动加载，解码期几乎零开销。代价是解码略慢于 FP16 缓存——它是"内存工具"而非"提速工具"，超长上下文或显存紧张时才值得开。细节见 KV-CACHE.md。

6️⃣ 思考模型开箱即用：推理预算按会话调

Bonsai 2 27B 是思考型模型，默认xhigh推理强度。聊天界面里点灯泡图标可按会话选 Off / Low（512 token）/ Medium（2,048）/ High（8,192）/ Max，无需重启；API 客户端建议按请求发reasoning_effort: "medium"，思考明显更少且精度接近。采样参数脚本已按模型卡推荐值配好：temperature 1.0、top_p 0.95、top_k 20、min_p 0.05。

从零到聊天：安装、启动与进阶配置

一键安装（macOS / Linux）

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

它只做安装与下载：检查系统依赖、装 uv 和 Python venv、下载 7.8GB 的PQ2_0权重与视觉投影器、下载 fork 二进制，外加 Open WebUI 与代码解释器（用BONSAI_OPENWEBUI=0、BONSAI_CODE_INTERPRETER=0可跳过这两项，省几个 GB 和大部分等待）。脚本可重复执行，已完成步骤会自动跳过。Windows 对应setup.ps1。

启动推理服务

./scripts/start_llama_server.sh

打开 http://localhost:8080 即可聊天，界面自带图片上传和 MCP 工具选择器。想不开服务问一句，也可以./scripts/run_llama.sh -p "你的问题"直接在终端完成。全部 24 个环境变量（上下文、GPU 卸载BONSAI_NGL、投机解码等）的完整清单在 environment_variables.md。

想自己编译？

构建脚本会 clone fork 的prism分支做全量构建，产物放进bin/：

./scripts/build_mac.sh # macOS，Apple Silicon 自动开 Metal ./scripts/build_cuda_linux.sh # Linux CUDA，自动探测版本

构建脚本会先探测 GPU 显存，低于 16 GB 时自动把编译并行度限制到-j 2，避免 CUDA 内核编译时 OOM 把机器卡死。

三个常见坑

Bonsai 2 能用原版 llama.cpp 跑吗？不能。PQ2_0/PTQ1_0的 type id 超出原版类型表，会被直接拒绝——这是安全的失败方式；危险的是Q2_0文件能无警告加载、输出乱码。上一代的 1-bitQ1_0和官方 group-64 三值文件则可以用原版构建跑。

⚠️ 旧版*-Q2_0.gguf打不开？那是迁移前的废弃布局（group-128 存在旧 type id 下），新版二进制会报错并指向正确格式，换下PQ2_0或_g64文件即可。留意 27B 的命名陷阱：官方 group-64 文件叫Ternary-Bonsai-27B-Q2_g64.gguf而不是Q2_0_g64，按错误名字搜索会一无所获。

Windows 装完没检测出 CUDA，选了 Vulkan 或 CPU？新版 NVIDIA 驱动的nvidia-smi输出改成了CUDA UMD Version:，旧版 setup 脚本只认CUDA Version:，于是漏检。用新版setup.ps1重跑即可，否则二进制会落在bin\vulkan或bin\cpu下，症状是提示词挂着不出 token 也不报错。

如何定位 Bonsai-demo

Bonsai-demo 不是一个"魔改玩具"，而是一套把三值量化推理做到工程化、全平台、可复现的完整方案：fork 内核负责跑模型，脚本负责管环境，社区 benchmark 集负责验证——本文每个数字都能在仓库里找到出处。如果你想在低内存设备上体验 27B 级的推理、视觉与工具调用，它是当前最省心的入口：两条命令，一个网页。

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