PrismML分叉还是上游llama.cpp?Ternary-Bonsai-2-2B构建选型完全解析(含CUDA/Metal编译)
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 的用户 | 必须使用官方原版构建的环境 |
⚠️ 两个关键事实:
- 上游 b11556 之前的 llama.cpp 加载 Q2_0 文件时不会报错,但会静默输出错误内容——请务必使用当前版本(见 README.md);
- 上游尚不支持
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 跑起来。