企业官网建设流程全解析

• 人工智能
• 大模型
• 模型量化
• 模型压缩
• 本地部署

导读

本文以本仓库 README.md 为骨架，系统讲解Ternary-Bonsai-2-27B这一 27B 级三元（ternary）推理模型的 GGUF 部署全流程：从{−1, 0, +1}三元权重与 Hadamard 旋转的原理，到 PTQ1_0 / PQ2_0 两种打包格式的选择，再到基于 PrismML llama.cpp fork 的下载、构建、推理命令与采样参数调优。读完本文，你将能在一台消费级 GPU 或 Apple Silicon 笔记本上以约 6～7 GB 显存/内存运行一个保留 98.2% 全精度能力的 27B 推理模型，并能正确规避其已知的运行时坑点。

本仓库为只读镜像，文中所涉文件均为 LFS 指针与文档；实际推理前需按文内命令从模型仓库下载真实权重，并使用 PrismML 的 llama.cpp fork 二进制（详见下文“运行环境”一节）。

一、模型概览：一个 27B 三元推理模型

1.1 基本规格

1.2 与基座模型的关系

从规格表可以看出，Bonsai 2 27B 的架构与 Qwen3.8-27B 完全一致——它没有改动模型拓扑，而是把权重表示从 FP16 换成三元格式，从而在不牺牲推理能力的前提下把体量压缩约 9 倍。这种“架构不变、表示换底”的设计让它可以无缝复用 Qwen3.8-27B 生态中的提示词模板、生成配置与混合注意力主干（约 75% 线性注意力是 262K 长上下文在端侧可行的关键）。

仓库内的 NOTICE.txt 与 LICENSE 也印证了这一派生关系：软件基于 Qwen3.8-27B 构建（Qwen 侧同为 Apache 2.0），整体以 Apache 2.0 发布，公开部署或再分发时建议注明 "Created using Bonsai by Prism ML."。

二、核心原理：Ternary g128 三元权重

2.1 三元化的信息论账本

每个权重只取{−1, 0, +1}三个值之一，一个三元值携带 log₂3 ≈1.585 bits的信息。格式为每 128 个权重共享一个 FP16 缩放因子：

• 三元编码：128 × 1.585 ≈ 202.9 bits
• 分摊的缩放：16 bits / 128 ≈ 0.125 bits/weight
• 合计：约1.71 bits/weight

再计入少量以更高精度保存的张量（线性注意力层的循环状态路径与归一化权重，共 26.2M 参数，约占语言模型的 0.0976%），全模型达到1.72 bits/weight——相对 FP16 的理想压缩比约为9.3x。README 特别强调：这是端到端的三元化，嵌入层、注意力投影、MLP 投影与 LM head 全部覆盖，不存在“低位标签背后藏着高精度逃生通道”的情况；只有视觉塔作为独立的 Q8_0 mmproj 包另行发布。

2.2 Hadamard 旋转：把量化损失摊到每个权重

直接对权重做三元量化会产生集中在个别权重的截断误差。Bonsai 2 27B 采用分块 Hadamard 旋转来缓解：

• 每个矩阵按块 1024 进行正交 Hadamard 旋转后再做三元赋值；
• 旋转在离线阶段折叠进存储权重，因此不消耗额外 bit、也不增加权重搬运流量；
• 打包模型把旋转声明为元数据（prism.hadamard.*），运行时要么施加匹配的激活变换，要么拒绝加载该文件。

这一点直接决定了后文的“必须使用 fork 二进制”要求：旋转激活变换只在 PrismML 的 llama.cpp fork 里实现，主线 llama.cpp 没有这套运行时。

2.3 内存需求对照

两种打包格式的提出，是为了让高效内核能够直接消费三元权重：

• PTQ1_0：把 trits 密集打包（每权重 1.75 bits），几乎贴合理论信息论下限；
• PQ2_0：把每个 trit 放进一个 2-bit 槽位（每权重 2.13 bits），用略大的体积换取更便宜的解包算术。

两者并非严格的优劣排序，吞吐差异见第六节吞吐量表。

三、仓库交付物验证

以本仓库实际文件为准（均为 Git LFS 指针文件，指针内记录了真实大小）：

部署要点：文本推理只要求语言模型常驻；Q8_0 mmproj 通常被卸载（offload），只有在真正输入图片时才加载，因此纯文本服务永远不会为视觉塔买单。

四、运行环境：这些文件需要 PrismML 的 llama.cpp 构建

4.1 为什么主线 llama.cpp 不行

三元混合注意力内核位于 PrismML 的 llama.cpp fork 中（CUDA + Metal）。主线 llama.cpp 无法运行这些文件：

• 主线将PQ2_0和PTQ1_0当作未知量化类型直接拒绝；
• 主线能加载Q2_0却不给任何警告，随后产生乱码输出——因为它没有 Hadamard 激活运行时。

这一事实同样记录在仓库的 KNOWN_ISSUES.md（“Runtimes other than the PrismML build”一节）：主线 llama.cpp、Ollama、LM Studio（GGUF）均不能加载PQ2_0/PTQ1_0文件；F16文件虽能在主线加载，但同样会因缺少 PrismML 构建才会应用的元数据而产生乱码。务必使用 fork 的二进制。

4.2 获取或构建二进制

# 预编译包：按平台选择归档（PrismML-Eng/llama.cpp 的 releases 页） tar -xzf llama-<tag>-bin-<platform>.tar.gz -C bin --strip-components=1 # 或自行构建（克隆 PrismML-Eng/llama.cpp 后）： git clone <PrismML-Eng/llama.cpp> && cd llama.cpp cmake -B build -DGGML_CUDA=ON && cmake --build build -j # macOS 上省略 -DGGML_CUDA=ON，Metal 为默认

两个版本号提示（来自 KNOWN_ISSUES.md）：

• 首发版本prism-b10687没有附带二进制，请改用prism-b10709或更新的发布；
• 构建 CUDA 时若报CUDA_ARCHITECTURES is empty，需显式传-DCMAKE_CUDA_ARCHITECTURES=<arch>（RTX 40 系列为89）；RTX 5090 可尝试-DCMAKE_CUDA_ARCHITECTURES=120a-real。

4.3 下载模型

hf download prism-ml/Ternary-Bonsai-2-27B-gguf Ternary-Bonsai-2-27B-PQ2_0.gguf --local-dir .

五、Quickstart：一条命令跑起来

./bin/llama-cli -m Ternary-Bonsai-2-27B-PQ2_0.gguf \ -ngl 99 -fa on -c 32768 \ --temp 1.0 --top-p 0.95 --top-k 20 --min-p 0.05 \ -p "Explain quantum computing in simple terms." -n 16384

参数逐项说明：

二进制路径：解压发布的归档是./bin/llama-cli；自行构建则是./build/bin/llama-cli。

两个必须注意的“反直觉”点：

1. 输出上限要留足。这是推理模型，默认先思考再作答，思维链同样计入输出配额。若上限过小（如 256），会在想完之前截断，得到空回答或残缺回答——这是 KNOWN_ISSUES.md 中“最常见报告”。README 建议-n 16384（服务端则设max_tokens）配合-c 65536。
2. --min-p 0.05是默认值，写出来是为了让命令自明。GGUF 文件内携带top_k、top_p、temperature（general.sampling.*），但没有min_p；llama.cpp 自身默认即 0.05，所以用户无需显式设置也能生效。若使用默认min_p=0.0的其他运行时，请手动设 0.05。

reasoning effort：模板默认xhigh（也是 README 推荐的长思考档位）；需要更短回答时用medium换取速度与精度的平衡；low不受支持，选择后模型行为接近xhigh。注意聊天模板只接受low/medium/xhigh，传high会返回 HTTP 500。

服务端场景（llama-server）、工具调用、推理预算（--reasoning-budget N）、图像输入（mmproj）、投机解码等更完整的运行脚本，以官方 Bonsai-demo 仓库为准——README 明确它才是“运行这些模型的唯一事实来源”（source of truth），会随内核迭代持续维护各后端的测试环境与固定版本二进制。

六、生成参数最佳实践

6.1 推荐的采样参数（README 原表）

• Thinking Mode（思考模式）：temperature=1.0，top_p=0.95，top_k=20，min_p=0.05，presence_penalty=0.0，repetition_penalty=1.0
• Instruct（非思考模式）：temperature=0.7，top_p=0.80，top_k=20，min_p=0.0，presence_penalty=1.5，repetition_penalty=1.0

设计依据（README 说明）：

• min_p=0.05会丢弃远低于最高候选概率的 token；测试中它至少不逊于min_p=0.0，且指令遵循更可靠，因此推荐用于思考模式。它同时也是 llama.cpp 的默认值。
• 其余数值与基座模型自身的generation_config.json一致。
• 报告中的基准测试结果即使用上述设置测得（唯一例外：测试时min_p=0.0）。

6.2 关于min_p与惩罚项的元数据缺口

KNOWN_ISSUES.md 补充了两个重要的元数据细节：

• min_p不在 GGUF 中（文件只带top_k=20、top_p=0.95、temperature=1.0）。llama.cpp 用户因默认值 0.05 自动获得；默认 0.0 的运行时需手动设置。模型卡修正元数据的更新已在计划中。
• presence_penalty与repetition_penalty也不在 GGUF 中，因此不带参数的服务器不会自动应用模型卡的数值，需要显式传入。

6.3 System Prompt

一个简单的系统提示即可：

You are a helpful assistant

注意聊天模板要求恰好一条且位于最前的系统消息——多余或位置不当的系统消息会触发 HTTP 500（详见 KNOWN_ISSUES.md 工具调用一节）。

6.4 打包格式怎么选

• PQ2_0：H100、A100 与 Blackwell 系列上 decode 更快；所有平台 prompt 处理（prefill）更快；Apple Silicon 上测的就是它。
• PTQ1_0：Ada 世代显卡与 L4 上 decode 更快；内存最紧张时的首选。

吞吐量对照见第七节。

七、跨平台吞吐量实测

tg128= 生成 128 个 token 的吞吐（内存带宽受限的交互阶段）；pp512= 处理 512 个输入 token 的吞吐（计算受限阶段）。单位为 tokens/s，用llama-bench在 batch size 1、depth 0、无视觉塔的条件下测得；NVIDIA 能耗为板卡功耗（含 HBM/GDDR）。

读表要点（README 的解释）：

1. 两种打包是真实的权衡：PTQ1_0 每步少搬运 17% 的权重数据，但解包密集 trits 需要算术开销——因此在内存是瓶颈的 Ada 世代与 L4 上胜出，在 H100/A100/Blackwell（batch-1 decode 受指令吞吐与启动开销限制）上落败。Prompt 处理是计算受限的，PQ2_0 全平台占优。
2. 笔记本的意义不在速度比：54 GB 的 FP16 基线根本装不进 M5 Pro，关键结论是“27B 模型能在日常笔记本上交互式运行”。M5 Pro 实测 decode 流约 204 GB/s 权重，证实了低比特表示所针对的内存带宽主导画像。
3. 能效对比：M5 Pro 在 GPU 轨上 decode 功耗 27.5 W（CPU+GPU 合计 34.1 W），而上表 NVIDIA 卡为 300–455 W 板卡功耗。Apple 行没有每 token 能耗，因为两平台仪器测量范围不同（nvidia-smi含 HBM/GDDR，Applepowermetrics报告 CPU/GPU/ANE 而无 DRAM 轨）。

7.1 其他 Apple 平台（预旋转构建，当前栈待重测）

M5 Max 可达约 47 tok/s；M4 Pro 上极长提示词的实际瓶颈是 prefill（约 125 tok/s）而非 decode。

八、基准测试：思考模式下的 14 项能力

评估方法：EvalScope + vLLM，统一在 NVIDIA H100 上、相同基础设施、解码与评分流程，思考模式下测得（该模式下模型完整推理被激活，传统方法在 sub-4-bit 下的塌缩最明显）。14 项基准覆盖六个技能类别；“vs FP16”相对 Qwen3.8-27B FP16 参考；比特宽度为真实平均。

• 以 5.95 GB 的体积，Bonsai 2 27B 比 sub-4-bit 的传统构建（IQ2_XXS）高出 12 分以上，而体积只有其约 82%；
• 距 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 家族上也呈现同一模式，说明塌缩是方法属性而非单一基座模型的属性。

8.1 按技能类别

推理主干基本完整保留：数学仅从 97.06 降到 96.57，编码与基线持平，指令遵循甚至略超基线。残余差距集中在最有难度的两类：知识与推理、视觉。

8.2 逐基准完整结果（思考模式）

九、智能密度（Intelligence Density）

智能密度刻画“单位部署体积能换回多少能力”，定义：

D = -log2(1 - score/100) / size_GB

Bonsai 2 27B 的密度约为表中“最密”传统构建（IQ2_XXS，0.257）的1.8x、FP16 的9x；相对上一代 Bonsai 27B（0.416）提升 9.9%。注：上一代行是在同一 14 项基准上重算的，保证同口径可比。

十、典型使用场景

• 笔记本本地 27B Agent：标准笔记本上约 28 tok/s 运行完整 27B 推理与工具调用；262K 上下文支撑长文档分析、整库代码任务等依赖大工作集驻留内存的场景。
• 隐私敏感与离线环境：端侧执行从构造上保证提示词与数据不离开设备，可在间歇性或无网络环境下工作。
• 单 GPU / 消费级 GPU 服务：单张消费级或入门级数据中心 GPU 即可获得 27B 级质量——RTX 5090 约 130 tok/s，72 W 的 L4 约 30 tok/s——并为更大 batch、更长上下文或模型共存留出余量。
• 质量优先的低比特部署：以约九分之一的体积保留全精度模型基准均分的 98.2%。

十一、已知问题与排查速查

本仓库附带 KNOWN_ISSUES.md（最近核验 2026-09-23），覆盖PQ2_0/PTQ1_0/F16与 MLX 构建。以下为高频问题的速查：

其他值得提前知道的运行时坑：

• 采样元数据：min_p、presence_penalty、repetition_penalty均不在 GGUF 中，需显式传入（见第六节）。
• 工具调用：工具arguments为空或非 JSON 时可能 HTTP 500/400，无参调用请发"{}"；系统消息必须唯一且置顶；工具循环中不要向会话回写思维链（会导致每轮重处理大部分对话、提示缓存失效）。
• 加载与平台：CUDA 13.3 构建在某些系统崩溃（Linux 用 CUDA 12.8、Windows 用 12.4 构建）；ROCm/HIP 在消费级 RDNA2 上中止（可试 Vulkan 构建）；--split-mode tensor/row暂不能跨双 GPU 加载；自己用llama-quantize量化普通模型到PQ2_0/PTQ1_0会产生乱码（两类型仅对带prism.hadamard.*旋转元数据的导出检查点有效）。
• 性能：KV cache 避免用q5_0（改用f16/q8_0/q4_0）；单用户服务建议-np 1 --cache-ram 24576避免长对话反复重算 prompt；--spec-type ngram-*对此模型无效果。
• 视觉：小图“指物/接地（grounding）”类任务效果差时，以--image-min-tokens 1024启动服务器。

十二、限制声明

• 质量与体积的权衡：三元模型保留全精度均分的 98.2%，差距适中且可预测——推理核心（数学、编码）与基线相差仅数分，差异集中在最具难度的类别。
• 原生低比特内核仍在演进：密集 PTQ1_0 打包（1.75 bits/weight，5.95 GB）已可用，但解包 trits 消耗算术——它在 Ada 级及更小加速器上更快，在 Ampere/Hopper/Blackwell 上更慢（这些平台上 batch-1 decode 并不受带宽饥饿）；“在每个目标上都把体积优势兑现为延迟优势”是正在进行的工程目标。

十三、许可与引用

本仓库以 Apache 2.0 发布（LICENSE），派生自 Qwen3.8-27B（同样 Apache 2.0，见 NOTICE.txt）。公开部署或再分发时建议注明 "Created using Bonsai by Prism ML."。

若在研究中引用 Bonsai 2 27B，推荐：

@techreport{bonsai2_27b, title = {Bonsai 2 27B: A 27B Ternary Reasoning Model}, author = {Prism ML}, year = {2026}, month = {September}, url = {https://prismml.com} }

进一步阅读：本仓库内的 README.md（本文主体文档）、KNOWN_ISSUES.md（问题与 workaround 全集）、LICENSE 与 NOTICE.txt（许可信息）；模型运行脚本与多后端方案见官方 Bonsai-demo 仓库（README 明确其为运行这些模型的唯一事实来源）。

• 人工智能
• 大模型
• 模型量化
• 模型压缩
• 本地部署