PrismML分叉还是上游llama.cpp?Ternary-Bonsai-2-2B构建选型完全解析(含CUDA/Metal编译)

原创2026-11-08 20:00:561,728 阅读

PrismML分叉还是上游llama.cpp?Ternary-Bonsai-2-2B构建选型完全解析(含CUDA/Metal编译)

Ternary-Bonsai-2-2B 是 PrismML 推出的三元(ternary)权重量化 2B 级视觉语言模型,以 GGUF 格式发布,可在 llama.cpp 的 CUDA、Metal、CPU 三大后端上本地运行。语言模型体积仅 约 0.52 GB(FP16 下约 3.8 GB),是目前最轻量的多模态模型之一。本文将完整解析 PrismML 分叉 vs 上游 llama.cpp 两条构建路线的取舍、三种量化格式的选型策略,以及 CUDA / Metal 编译步骤,帮助新手一次跑通。

📦 模型亮点:从 3.8 GB 到 0.52 GB

Ternary-Bonsai-2-2B 的核心思路:把全部语言权重压缩为三元值 {−1, 0, +1},配合 FP16 分组缩放存储,由专用 kernel 直接消费、永不还原回 FP16。关键规格如下(详见 README.md):

项目 规格
基础模型 派生自 Qwen3.5-2B(架构不变)
语言模型 ~1.88B 参数(24 层,hidden 2048,embedding 与 LM head 共享)
视觉塔 ~0.33B,独立 mmproj 包,仅当输入图片时才加载
注意力架构 混合注意力(3 线性 : 1 全注意力)、SwiGLU、RoPE、RMSNorm
上下文长度 262,144 tokens(继承自基础模型)
运行后端 llama.cpp(CUDA / Metal / CPU)
许可证 Apache 2.0

💡 注意:权重中折叠了分块 Hadamard 旋转,运行时需对激活做对应变换——这正是版本选型的根源(后文详述)。

🗂 仓库文件清单:5 个 GGUF 文件怎么选

仓库共 5 个模型文件(3 个语言模型 + 2 个视觉塔),大小与定位如下(来自 README.md 文件表):

文件 内容 大小 定位
Ternary-Bonsai-2-2B-PTQ1_0.gguf 语言模型 · dense trits 0.43 GB 内存最紧张时
Ternary-Bonsai-2-2B-PQ2_0.gguf 语言模型 · 2-bit slots 0.52 GB 官方默认
Ternary-Bonsai-2-2B-Q2_0.gguf 语言模型 · Q2_0 0.55 GB 上游 llama.cpp 兼容
Ternary-Bonsai-2-2B-mmproj-Q8_0.gguf 视觉塔 0.36 GB 推荐
Ternary-Bonsai-2-2B-mmproj-BF16.gguf 视觉塔(参考精度) 0.67 GB 调试对照

三个语言模型包装的是同一套三元权重,区别只在存储布局与 kernel 速度;bits/weight 分别为 ~1.83、~2.20、~2.33。下载后可用 SHA256SUMS 校验文件完整性。

⚖️ 构建选型核心:PrismML 分叉 vs 上游 llama.cpp

这是使用本模型最容易踩坑的地方。两者的差异(依据 README.md 后端说明 与 分叉说明):

对比项 PrismML llama.cpp 分叉(prism 分支) 上游 llama.cpp(官方版)
支持的量化类型 PTQ1_0、PQ2_0、Q2_0 全部三种 仅 Q2_0
最低版本要求 分叉的任一可用构建 b11556 或更新版本
三元权重消费方式 定制 kernel 直接读取,永不展开为 FP16 依赖 b11556 新增的 Hadamard 激活运行时
获取方式 官方 release 预编译包 / 自行编译 官方 release 预编译包 / 自行编译
适用人群 想用到最小体积 PTQ1_0 或默认 PQ2_0 的用户 必须使用官方原版构建的环境

⚠️ 两个关键事实:

  1. 上游 b11556 之前的 llama.cpp 加载 Q2_0 文件时不会报错,但会静默输出错误内容——请务必使用当前版本(见 README.md);
  2. 上游尚不支持 PTQ1_0 和 PQ2_0 类型,遇到会直接以"未知类型"拒载。

三步决策指南

  • 内存优先(0.43 GB)→ 选 PTQ1_0 → 必须用 PrismML 分叉
  • 均衡默认(0.52 GB)→ 选 PQ2_0 → 推荐 PrismML 分叉(官方在 Apple Silicon 上实测的打包方式)
  • 必须用官方原版 → 选 Q2_0 → 上游 b11556+ 即可

🔧 编译指南:CUDA 与 Metal 一步到位

环境依赖

平台 后端 需要安装
Linux + NVIDIA GPU CUDA git、cmake、CUDA Toolkit
macOS(Apple Silicon) Metal git、cmake、Xcode Command Line Tools
无 GPU 机器 CPU git、cmake

编译 PrismML 分叉(跑通全部三个文件)

从 PrismML 的 llama.cpp 分叉获取源码(prism 分支),然后:

# Linux + CUDA:显式开启 CUDA 后端
cmake -B build -DGGML_CUDA=ON && cmake --build build -j
# macOS:Metal 是默认后端,无需额外参数
cmake -B build && cmake --build build -j

💡 不想编译?分叉的 release 页提供了各平台预编译二进制包,下载后解压到 bin 目录即可,省去全部编译步骤。

编译上游 llama.cpp(仅跑 Q2_0)

流程完全相同:克隆上游源码(b11556 或更新版本),Linux 加 -DGGML_CUDA=ON、macOS 保持默认,cmake --build build -j 即可。

🚀 快速上手:从文本对话到看图理解

文本对话

./bin/llama-cli -m Ternary-Bonsai-2-2B-PQ2_0.gguf -ngl 99 -fa on \
  -p "Explain in three sentences why the sky is blue."

图片 + 文本

./bin/llama-mtmd-cli -m Ternary-Bonsai-2-2B-PQ2_0.gguf \
  --mmproj Ternary-Bonsai-2-2B-mmproj-Q8_0.gguf -ngl 99 \
  --image photo.jpg -p "Describe this image."

常用参数速查:

参数 作用
-m 语言模型文件
--mmproj 视觉投影器(mmproj)文件
-ngl 99 把全部层卸载到 GPU
-fa on 开启 Flash Attention
--image-min-tokens 提升图片 token 预算(默认太小,图片里的小字会看不清,可设为 1024)

启动 OpenAI 兼容服务只需把上面换成 llama-server,加上 --port 8080 即可,参数完全一致。

⚙️ 采样参数最佳实践:思考模式 vs 非思考模式

官方推荐的采样设置(对三种量化打包通用,见 README.md 生成参数):

参数 思考模式(默认) 非思考模式
temperature 1.0 0.7
top_p 0.95 0.80
top_k 20 20
min_p 0.0 0.0
presence_penalty 1.0 1.5
repetition_penalty 1.0 1.0

配套要点:

  • 惩罚项作用于最近 64 个 token(--repeat-last-n 64,即 llama.cpp 默认窗口);
  • 思考模式要留足输出空间:简单问题也可能消耗 3,000+ 思考 token,建议允许 8,192 以上输出 token;短答案场景请关闭思考模式(请求中传 "enable_thinking": false);
  • 思考模式下避免贪心解码(temperature=0),部分提示词会卡死在推理中;
  • 简单系统提示即可,例如:You are a helpful assistant。

🧰 常见坑与解决方案

坑 表现 解决
BF16 视觉包并发崩溃 llama-server 同时处理多个图片请求时可能崩溃 换用 Q8_0 mmproj(质量几乎相同,不受影响)
上游版本过旧 加载 Q2_0 不报错但输出乱答 升级到 b11556 或更新版本
图片中小字识别差 密集小文本读不出来 加 --image-min-tokens 1024
思考模式"卡住" 长思考后不收敛 提高 temperature,勿用贪心解码
盲目上投机解码 期望加速反而更慢 2B 模型解码本已便宜,官方实测 draft head 更慢,用普通解码即可

🍎 Apple Silicon 用户另有选择:同一套权重的 MLX 版本(Ternary-Bonsai-2-2B-mlx-2bit)可在 mlx-vlm 0.7.8+ 中直接加载,注意其 Python generate() 默认贪心解码,需手动传入上表参数。

📄 获取模型与许可证说明

推荐用 Hugging Face CLI 只拉取需要的文件:

hf download prism-ml/Ternary-Bonsai-2-2B-gguf Ternary-Bonsai-2-2B-Q2_0.gguf Ternary-Bonsai-2-2B-mmproj-Q8_0.gguf --local-dir .

或直接克隆本仓库(模型文件走 Git LFS,克隆后需执行 git lfs pull 补全):

git clone https://gitcode.com/hf_mirrors/prism-ml/Ternary-Bonsai-2-2B-gguf

许可证方面(LICENSE、NOTICE.txt):

  • 整体遵循 Apache 2.0,与基础模型 Qwen3.5-2B(Alibaba Cloud)保持一致;
  • 若你公开部署或再分发,官方请求附带署名:"Created using Bonsai by Prism ML."

✅ 小结

  • 要最小体积 / 默认体验 → PrismML 分叉 + PTQ1_0(0.43 GB)或 PQ2_0(0.52 GB);
  • 必须用官方原版 → 上游 llama.cpp b11556+ + Q2_0(0.55 GB);
  • 编译只需一条 cmake:Linux 加 -DGGML_CUDA=ON,macOS 默认走 Metal;
  • 视觉任务认准 Q8_0 mmproj,思考模式留够 8192 输出 token。

按这份路线选型,你就能在 Windows、Linux、macOS 上以最少的折腾把 Ternary-Bonsai-2-2B 跑起来。

登录后查看全文
Ternary-Bonsai-2-2B-gguf