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

Bonsai-demollama.cpp 定制 fork 跑 2-bit 三值 27B 推理的完整解析【免费下载链接】Bonsai-demoBonsai Demo项目地址: https://gitcode.com/GitHub_Trending/bo/Bonsai-demoBonsai-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_01.75 bit/权重5.9 GB和PQ2_02.13 bit/权重7.2 GB据仓库文档记载它们的权重存放在旋转基里推理时每次矩阵乘前必须做 Hadamard / 快速 Walsh–Hadamard 变换FWHT加 sign-flip——这套激活变换只有 fork 的二进制带着。最微妙的一点主线 llama.cpp 加载 Bonsai 2 的Q2_0文件不会报错它会正常读开然后输出乱码。所以作者非做不可的理由很直接模型团队把 27B 压到 2 bit 出头但没有任何现成解码器读得动内核不跟压缩就白做了。下图展示了 Bonsai 家族模型在体积—质量权衡中的位置格式层三种打包文件与后端自动选择Bonsai 2 有三种位宽各异的打包存的是同一份权重区别只在解码成本打包位宽 (bit/权重)27B 体积可运行位置PTQ1_01.755.9 GB仅 fork 二进制PQ2_0demo 默认下载2.137.2 GB仅 fork 二进制Q2_0开发版2.257.6 GBfork 二进制主线支持待 PR 合并选文件这件事 demo 替你做了scripts/common.sh里的pq2_0_ready_backend()维护一份哪些后端有 PQ2_0 优化内核的注册表——Metal、CUDA、ROCm、CPUx86 VNNI / ARM NEON有内核就选PQ2_0Vulkan、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 走普通矩阵乘回退。换个角度看这部分工作正在逐块回流主线上游 PR状态仓库文档记载2026-09CPUF16 输入进 FWHT已合并MetalF16 输入进 FWHT、块宽 512已合并CUDAF16 输入进 FWHT待合并VulkanF16 输入进 FWHTdraft1-bit 的Q1_0内核x86 AVX / NEON / Metal / CUDA / Vulkan早已全部回馈上游主线现在也能跑 1-bit 模型。但PQ2_0和PTQ1_0这两个打包类型没有上游支持的承诺它们会一直住在 fork 里。长上下文与投机解码两个实验性开关27B 支持 262K 上下文混合注意力结构让 KV 缓存对它的尺寸来说很小FP16 KV 每 token 64 KiB100K 上下文约 6.3 GiB。BONSAI_KV41把 KV 缓存压到 Q4_0100K 时降到约 1.8 GiB代价是解码略慢——官方定位是省内存的工具不是提速工具。配套一步./scripts/make_kv_bias.sh BONSAI_KV41 ./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在 L40SCUDA上实测解码 1.8–2.4 倍提速代码和数学类任务收益最大Bonsai 2 目前还没有官方 drafter开BONSAI_SPECULATIVE1只会警告并回退普通解码细节见 SPECULATIVE.md。从空目录到 8080 端口出词先 clone 并安装。macOS / Linux 只需两步git clone https://gitcode.com/GitHub_Trending/bo/Bonsai-demo cd Bonsai-demo ./setup.shsetup.sh只负责装依赖、下模型Bonsai 2 27B 的PQ2_0权重加视觉投影器约 7.8 GB、从固定 release 拉当前平台的 fork 预编译二进制Open WebUI 和代码解释器会多占几个 GB 和等待时间用BONSAI_OPENWEBUI0 BONSAI_CODE_INTERPRETER0可跳过。它不启动服务启动交给下一条./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 BypassPowerShell 侧注意脚本可能因驱动版本误判后端后文会讲。Apple Silicon 额外有一条 MLX 原生路径setup.sh会装好.venv-vlm环境./scripts/run_mlx.sh或./scripts/start_mlx_server.sh8081 端口即可文本、图像和工具调用都支持。进阶路径源码编译、环境变量与二次运行想自己编译打补丁、调构建参数的话构建脚本会自动 clone fork 的prism分支做全量构建./scripts/build_mac.sh ./scripts/build_cuda_linux.shmacOS 上自动区分 Apple Silicon开 Metal与 Intel纯 CPULinux 侧自动探测 CUDA 版本产物进bin/mac/、bin/cuda/。Vulkan 和 ROCm 没有一键脚本按 README.md 的 Building from Source 一节手动 cmake 即可。日常调参全部走环境变量最有代表性的几个BONSAI_CTX覆盖上下文不传则按机器内存分层8K 到 131KBONSAI_NGL0强制纯 CPU弱核显机器上通常比自动探测更好BONSAI_KV41开 4-bit KV 缓存。完整 24 个变量见 environment_variables.md。还有两条进阶线值得看一眼上一代 27B 的投机解码需要先把公开 drafter 转一遍gguf-dspark-to-dflash加量化两条命令转换输出文件名必须保留dspark-dflash字样启动脚本靠它发现 drafterBONSAI_MMPROJ_CPU1把视觉投影器留在内存里释放约 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 提示处理速度硬件后端PP512 (t/s)TG128 (t/s)RTX 5090 32 GBCUDA 12.8Linux4,075143.0RTX 4090 24 GBCUDAWindows3,28584.9RTX 3090 Ti 24 GBCUDALinux1,55281.6RTX 3070 8 GBCUDAWindows838.943.7M3 Max 36 GBMetalllama.cpp162.224.3M3 Max 48 GBMLX 2-bit165.927.1说人话8 GB 的 RTX 3070 上 27B 解码仍有 43.7 t/s日常对话完全够用Apple Silicon 上 MLX 路径普遍比 llama.cpp Metal 略快27.1 对 24.3 t/sM 系用户值得两条都试。上一代的 27Bternary成绩在 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_DISABLE1跳过 tensor API 即可保留完整 Metal 速度只损失 Neural Accelerator 的 prefill 加成。上下文别手动拉满。旧版脚本曾默认-c 0模型完整训练上下文 262K小内存机器直接卡死现在脚本已改为按内存分层但仍爆内存时用BONSAI_CTX8192 ./scripts/start_llama_server.sh这类方式显式压小。写在最后适合谁很清楚想在笔记本或单张消费卡上跑 27B 级三值推理、接受绑定 fork 二进制的人以及想研究低比特格式如何工程化落地自研打包、逐后端内核、格式迁移、校准偏置的人。不适合的是必须用上游主线 llama.cpp 或想零绑定集成的场景——Bonsai 2 目前只有 fork 能跑对。成熟度上据仓库文档记载上游合并已完成 CPU 与 Metal 的 FWHT 工作CUDA 与 Vulkan 还在 reviewPQ2_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考