prism-ml/Ternary-Bonsai-2-27B-mlx-2bit · Hugging Face

来源：https://huggingface.co/prism-ml/Ternary-Bonsai-2-27B-mlx-2bit Bonsai

Prism ML 网站 (https://prismml.com/)|白皮书 (https://github.com/PrismML-Eng/Bonsai-demo/blob/main/bonsai-2-27b-whitepaper.pdf)|演示与示例 (https://github.com/PrismML-Eng/Bonsai-demo)|Discord (https://discord.gg/prismml)

在日常笔记本电脑上，使用三元 transformer 权重实现完整的 27B 级推理能力

磁盘占用 8.60 GB，包含语言模型 + 视觉塔 | 保留 98.2% 的 FP16 智能水平 | 在 Apple M5 Max 笔记本上可达 ~47 tok/s

亮点

• 8.60 GB 磁盘占用：7.67 GB 语言模型（从约 54 GB FP16 缩减而来）加上 0.92 GB 视觉塔。MLX 的容器为每组存储一个缩放因子和一个偏置，因此语言模型的存储成本为 2.25 bits/权重，而相同的三元权重在 GGUF PTQ1_0 打包格式中仅需 1.75 bits。
• 保留 98.2% 的 FP16 智能水平：在 14 个思考模式基准测试中平均得分 84.78——远高于传统 IQ2_XXS 构建版本（72.59），且其占用空间不到后者的三分之二；与 UD-Q4_K_XL 相比，仅落后 0.4 分，而后者占用空间是其三倍。
• 在极低比特位宽下保持思考、推理和智能体行为：在传统低位表示会崩溃的 sub-4-bit 区间内，数学得分仅比全精度低半分（96.57），编码能力与基线持平（89.42），智能体工具调用得分为 74.92。
• 端到端三元语言权重：覆盖嵌入层、注意力投影层、MLP 投影层和 LM 头，不存在高位精度的“逃生通道”伪装成低位标签——真正实现了 1.72 bits/权重（作为表示），作为 MLX 存储格式为 2.25 bits/权重；视觉塔包含在此包中，未量化。
• 设备端支持 262K token 上下文：得益于 Qwen3.8-27B 混合注意力主干网络（约 75% 线性注意力），使其在设备端保持实用。
• 自定义三元混合注意力内核：适用于 Apple MLX (Python, Swift) 和 CUDA——打包权重可直接使用，无需展开回 FP16。
• GGUF 伴生版本：同时提供 Ternary-Bonsai-2-27B-gguf (https://huggingface.co/prism-ml/Ternary-Bonsai-2-27B-gguf)，用于 llama.cpp (CUDA, Metal, CPU)，提供两种打包格式——PTQ1_0 (5.95 GB) 和 PQ2_0 (7.21 GB)。

资源

• 白皮书 (https://github.com/PrismML-Eng/Bonsai-demo/blob/main/bonsai-2-27b-whitepaper.pdf) —— 完整的方法论、基准测试和测量说明
• 演示与示例 (https://github.com/PrismML-Eng/Bonsai-demo) —— 运行这些模型的权威来源：包含每个后端的测试环境、固定二进制文件、服务、基准测试和集成方案，并随运行时更新而保持最新。
• 低位内核：MLX 分支 (Apple Silicon) · mlx-swift 分支 (iOS/macOS) · llama.cpp 分支 (CUDA)
• Discord (https://discord.gg/prismml) —— 加入社区获取支持、讨论和更新

模型概述

权重表示：三元 g128

每个权重取值为 {−1, 0, +1}，每组 128 个权重共享一个 FP16 缩放因子。一个三元值携带 log2(3) ≈ 1.585 bits 的信息量，因此该格式的有效存储成本为 约 1.71 bits/权重（三元编码 + 16 位缩放因子分摊至 128 个权重）；将三元表示之上持有的少量张量计算在内，整个模型达到 1.72 bits/权重——相比 FP16 实现了约 9.3 倍的理想化压缩。

权重以旋转基存储：在分配三元值之前，每个矩阵都通过分块正交 Hadamard 旋转变换，运行时对激活值应用相应的匹配变换。该旋转离线折入存储的权重中，因此不会产生额外的比特位开销或权重数据流量；打包模型将旋转信息作为元数据声明，运行时要么应用匹配的变换，要么拒绝加载文件。

内存需求

以上是语言模型的数据；包含 0.92 GB 视觉塔后，磁盘上的包大小为 8.60 GB。

实际部署需要高效内核能够消费的打包格式，Bonsai 2 提供了两种：PTQ1_0 密集打包 trits，基本达到信息论目标；而 PQ2_0 将每个 trit 存储在 2 位插槽中，以占用空间换取更低的解包开销。两者并无绝对的优劣——参见下方的吞吐量表。这些大小仅描述语言模型，即文本推理唯一需要常驻的组件；26.2M 参数（占语言模型的 0.0976%——线性注意力层的循环状态路径，加上归一化权重）以更高精度保留，并计入 1.72 的数字中。

与传统低位构建版本——其宣称的标签低估了真实平均位宽（一个广泛使用的 Qwen3.8-27B “2-bit”构建版本实际为 2.8 bits/权重，占用 9.4 GB）——不同，Bonsai 的表示承载的位宽与其名称相符。

MLX 打包

此包包含语言模型和视觉塔。model.safetensors 文件为 8.60 GB：7.67 GB 打包的语言权重和 0.92 GB 视觉塔。视觉塔是官方的 Qwen3.8-27B 视觉塔，以 FP16 格式承载，未旋转、未量化。Hadamard 旋转仅应用于语言模型的投影层，因此视觉塔无需变换，直接透传。

MLX 的分组低位格式每组存储一个缩放因子和一个偏置。三元级别 \{-s, 0, \+s\} 通过设置 scale = s 和 bias = -s 精确重现，因此 2 位编码 \{0, 1, 2\} 解码为 -s、0、+s。偏置不携带新信息，但容器在每组 128 个权重中存储两个 FP16 值，而原生格式只存储一个。因此有效速率为 2.25 bits/权重，高于 PQ2_0 的 2.13。这是容器属性，而非不同的表示方式：打包权重解码后与 GGUF 格式的值完全相同，通过逐位比较组缩放因子已得到验证。

最佳实践

生成参数

我们建议使用以下采样参数集进行生成：

• 思考模式：temperature=1.0, top_p=0.95, top_k=20, min_p=0.0, presence_penalty=0.0, repetition_penalty=1.0
• 指令（或非思考）模式：temperature=0.7, top_p=0.80, top_k=20, min_p=0.0, presence_penalty=1.5, repetition_penalty=1.0

这些参数与基础模型自身的 generation_config.json 一致，并包含在 GGUF 元数据 (general.sampling.*) 中，因此读取模型默认值的客户端无需额外设置即可使用。这些也是报告基准测试结果（思考模式）时使用的设置。

模型默认使用 xhigh 推理强度；使用 medium 可获得更短的回复以及速度和准确性的平衡。不支持 low 推理强度，选择该设置时模型行为将接近 xhigh。

系统提示词

您可以使用简单的系统提示词，例如：

You are a helpful assistant

快速开始

PrismML-Eng/Bonsai-demo (https://github.com/PrismML-Eng/Bonsai-demo) 是运行这些模型的权威来源。 它包含经过测试的设置，构建正确的 MLX 运行时，并保持最新。此处任何内容与之冲突时，以其为准。

hf download prism-ml/Ternary-Bonsai-2-27B-mlx-2bit --local-dir bonsai2-27b-mlx

此包声明了 model_type: prism_hadamard_qwen35，并需要 runtime/ 中捆绑的加载器。普通的 MLX 加载器会跳过激活变换和逆嵌入查找，因此会返回错误输出而非报错。

pip install -r bonsai2-27b-mlx/runtime/requirements.txt

import sys
sys.path.insert(0, "bonsai2-27b-mlx/runtime")
from vision_artifact import load_vl_model, chat_config
from mlx_vlm import generate
from mlx_vlm.prompt_utils import apply_chat_template

model, processor, config = load_vl_model("bonsai2-27b-mlx")
prompt = apply_chat_template(processor, chat_config(config), "What is in this image?", num_images=1)
print(generate(model, processor, prompt, ["photo.jpg"], max_tokens=256, temperature=1.0))

纯文本使用时不传递图像。需要 chat_config，因为 mlx-vlm 的提示工具依赖 model_type。所有操作基于标准包运行，无需分支；PACK-RUNTIME.md 文档说明了相关约定，Bonsai-demo (https://github.com/PrismML-Eng/Bonsai-demo) 提供了经过测试的设置。

对于 CUDA、CPU 和 llama.cpp on Metal，请使用相同权重的 GGUF 打包版本：Ternary-Bonsai-2-27B-gguf (https://huggingface.co/prism-ml/Ternary-Bonsai-2-27B-gguf)。这需要构建我们的 llama.cpp 分支 (https://github.com/PrismML-Eng/llama.cpp)；标准 llama.cpp 无法运行它们。

跨平台吞吐量

tg128 是生成 128 个 token 时的 token 生成吞吐量（受内存带宽限制的交互阶段）；pp512 是处理 512 个输入 token 时的提示处理吞吐量（受计算限制的阶段）。单位均为 tokens/s。各行使用 llama.cpp (Metal/CUDA，自定义低位内核) 在相同权重的 GGUF 打包版本上测量，批大小为 1，深度为 0，不启用视觉塔。NVIDIA 功耗为包含 HBM/GDDR 的板卡功耗。

在笔记本电脑上，FP16 基线版本（~54 GB）完全无法容纳——有意义的结论不是加速比，而是一个 27B 模型能在日常笔记本电脑上交互式运行。在 M5 Pro 上测量的解码流式传输了约 204 GB/s 的权重，证实了低位表示旨在利用的内存带宽主导特性。M5 Pro 的数据是在安静机器上测量的；此笔记本电脑随后台负载波动约 4%。

这两种打包格式是真实的权衡而非严格的排序。PTQ1_0 每步移动的权重数据少 17%，但解包密集 trits 需要计算开销，因此它在 Ada 一代显卡和 L4（内存是瓶颈）上获胜，而在 H100、A100 和 Blackwell 显卡上则落后，因为这些卡上的批大小为 1 的解码受限于指令吞吐量和启动开销。提示处理是计算密集型，在所有平台上都偏向 PQ2_0。

Apple 行没有提供每 token 能耗数据，因为两个平台的监测工具未包含相同的组件：nvidia-smi 包含显卡的 HBM/GDDR，而 Apple 的 powermetrics 报告 CPU、GPU 和 ANE，但不包含 DRAM 供电轨。测量确实支持绝对功耗：M5 Pro 在 GPU 供电轨上解码功耗为 27.5 W，CPU 和 GPU 总计 34.1 W，而上述 NVIDIA 显卡的板卡功耗为 300–455 W。

其他 Apple 平台

在早期未旋转构建版本上测量，待在当前堆栈（llama.cpp Metal 后端）上重新测量后更新：

在更强大的 M5 Max 上，模型可达到约 47 tok/s；在 M4 Pro 上，对于非常长的提示，预填充（~125 tok/s）而非解码是实际限制。

基准测试

使用 EvalScope + vLLM 在 NVIDIA H100 上评估，基础设施、解码和评分条件相同，采用思考模式——该模式下模型的完整推理能力得到发挥，传统方法的 sub-4-bit 崩溃现象最为明显。涵盖六个技能类别的 14 个基准测试。位宽为真实平均值；“vs FP16”是相对于 Qwen3.8-27B FP16 参考版本的比较。

在 5.9 GB 占用空间下，Bonsai 2 27B 以超过十二分的优势超越了 sub-4-bit 传统构建版本（其占用空间还不到后者的三分之二），并且在占用空间仅为 UD-Q4_K_XL 三分之一的情况下，仅落后 0.4 分。

总体差距也掩盖了传统构建版本的失败方式：其性能下降是选择性的，集中在需要持续推理链的基准测试上。IQ2_XXS 在 AIME26 上降至 57.5，在 LiveCodeBench 上降至 56.4，而在 MMLU-Redux 上仍能获得 88.93 分——这就是为什么随意测试会错过崩溃现象。Bonsai 2 在这些关键基准测试上表现稳定，分别获得 95.83 和 90.07 分。之前的 Bonsai 27B 报告在第二个模型系列 Gemma-4-31B 上显示了相同模式，因此崩溃是方法的属性，而非单一基础模型的属性。

按技能类别