Bonsai-demo

在本地运行 Bonsai 语言模型的完整示例仓库，支持 1-bit 和 Ternary 两种量化格式，涵盖 27B/8B/4B/1.7B 四种尺寸。亮点在于极低比特量化（1-bit 仅需 3.5GB 显存即可运行 27B 模型），使得超大模型能在消费级设备上流畅推理；最新 27B 版还集成了视觉、工具调用和思考能力，并已接入主流 llama.cpp，提供预编译二进制和 Open WebUI 交互界面。

README

Bonsai Demo

Bonsai

官方网站 | GitHub | Discord

HuggingFace 模型集合: Bonsai 27B · Bonsai (1-bit) · Ternary-Bonsai

白皮书: Bonsai 27B · 1-bit Bonsai 8B · Ternary-Bonsai 8B

使用此演示仓库，您可以在 Mac（Metal）、Linux/Windows（CUDA、Vulkan、ROCm）或 CPU 上本地运行 Bonsai（1-bit）和 Ternary-Bonsai 语言模型。

🌱 新成员：Bonsai 27B

该系列最新、最大的模型，也是其首个 视觉-语言 模型（Bonsai 27B 集合）：

视觉能力： 发送照片、截图和 PDF；针对它们提问（参见 VISION.md）。
Agentic 工具调用： 原生 OpenAI 风格的 tool_calls，支持完整往返，并在两个演示 UI 中均提供 MCP 服务器（参见 TOOLS.md）。
思考能力： 推理模型；可在 UI 中按对话选择思考努力程度，也可按请求预算。
长上下文： 256k+ token 的对话。
极小体积： 1-bit Bonsai-27B 压缩至约 1.125 bits 每参数：无需内存卸载即可适配现代 iPhone。Ternary-Bonsai-27B（约 1.7 bits 每参数，压缩为 2-bit 以实现快速加速内核）是更高质量选项，也是本演示的默认模型。

以下快速入门只需两条命令：./setup.sh 默认下载 Ternary-Bonsai-27B，然后 ./scripts/start_llama_server.sh 即可在 http://localhost:8080 提供聊天、视觉和工具功能。

快速入门

使用 AI 编码助手进行设置？请参考 AGENTS.md，这是一份为 Agent 编写的指南（包含硬件特定调整、默认值以及询问用户的内容）。

macOS / Linux

git clone https://github.com/PrismML-Eng/Bonsai-demo.git
cd Bonsai-demo

# （可选）选择模型大小：27B（默认）、8B、4B 或 1.7B
export BONSAI_MODEL=27B

# 设置你的 HuggingFace token（仅在 27B 仓库处于私有状态时需要）
export BONSAI_TOKEN="hf_your_token_here"

# 一条命令完成所有操作：安装依赖、下载模型和二进制文件
./setup.sh

Windows (PowerShell)

git clone https://github.com/PrismML-Eng/Bonsai-demo.git
cd Bonsai-demo

# （可选）选择模型大小：27B（默认）、8B、4B 或 1.7B
$env:BONSAI_MODEL = "27B"

# 设置你的 HuggingFace token（仅在 27B 仓库处于私有状态时需要）
$env:BONSAI_TOKEN = "hf_your_token_here"

# 运行设置
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup.ps1

切换系列和大小

您可以在 Ternary（默认）和 1-bit 系列之间以及不同模型大小之间即时切换：

# 运行 Ternary-Bonsai 4B
BONSAI_FAMILY=ternary BONSAI_MODEL=4B ./scripts/download_models.sh
BONSAI_FAMILY=ternary BONSAI_MODEL=4B ./scripts/run_llama.sh -p "Hello!"

Windows 版本：

$env:BONSAI_FAMILY="ternary"; $env:BONSAI_MODEL="4B"
.\setup.ps1
.\scripts\run_llama.ps1 -p "Hello!"

速度基准测试

社区基准测试结果参见 community-benchmarks/，欢迎提交您自己的测试模板。

模型

两个模型系列可用，每个系列包含 27B、8B、4B 和 1.7B 四种大小。27B 模型是视觉-语言模型：可接受图像和文本；所有 27B 仓库都收录在 Bonsai 27B HuggingFace 集合中。

两种格式正在陆续进入主线的 llama.cpp：Q1_0（1-bit）已完全合并到上游，Q2_0（ternary）现在可在主线 CPU 和 Metal 上运行，Vulkan 正在审核中。详情和主线兼容文件：见下文 binary 状态和 ternary 状态。

Bonsai (1-bit)

提供 GGUF (llama.cpp) 和 MLX 1-bit 格式。

模型	格式	HuggingFace 仓库
Bonsai-27B	GGUF	prism-ml/Bonsai-27B-gguf
Bonsai-27B	MLX	prism-ml/Bonsai-27B-mlx-1bit
Bonsai-8B	GGUF	prism-ml/Bonsai-8B-gguf
Bonsai-8B	MLX	prism-ml/Bonsai-8B-mlx-1bit
Bonsai-4B	GGUF	prism-ml/Bonsai-4B-gguf
Bonsai-4B	MLX	prism-ml/Bonsai-4B-mlx-1bit
Bonsai-1.7B	GGUF	prism-ml/Bonsai-1.7B-gguf
Bonsai-1.7B	MLX	prism-ml/Bonsai-1.7B-mlx-1bit

设置 BONSAI_MODEL 以选择要下载和运行的大小（默认：27B）。

Ternary-Bonsai

提供 GGUF (llama.cpp) 和 MLX 2-bit 格式。

模型	格式	HuggingFace 仓库
Ternary-Bonsai-27B	GGUF	prism-ml/Ternary-Bonsai-27B-gguf
Ternary-Bonsai-27B	MLX (2-bit)	prism-ml/Ternary-Bonsai-27B-mlx-2bit
Ternary-Bonsai-8B	GGUF	prism-ml/Ternary-Bonsai-8B-gguf
Ternary-Bonsai-8B	MLX (2-bit)	prism-ml/Ternary-Bonsai-8B-mlx-2bit
Ternary-Bonsai-4B	GGUF	prism-ml/Ternary-Bonsai-4B-gguf
Ternary-Bonsai-4B	MLX (2-bit)	prism-ml/Ternary-Bonsai-4B-mlx-2bit
Ternary-Bonsai-1.7B	GGUF	prism-ml/Ternary-Bonsai-1.7B-gguf
Ternary-Bonsai-1.7B	MLX (2-bit)	prism-ml/Ternary-Bonsai-1.7B-mlx-2bit

这是默认系列。设置 BONSAI_FAMILY=bonsai 以使用 1-bit Bonsai 系列。

环境变量

两个变量都是可选的。如果两者都不设置，默认值为 Ternary-Bonsai-27B： 这就是 ./setup.sh 下载和运行的内容。它们被 setup.sh、setup.ps1、download_models.sh 以及所有 run_* / start_* 脚本（Linux、macOS 和 Windows）读取。

变量	默认值	有效值	用途
`BONSAI_FAMILY`	`ternary`	`ternary`, `bonsai`, `all`	模型系列。`ternary` = Ternary-Bonsai；`bonsai` = 1-bit Bonsai。`all` 表示两个系列（仅设置/下载时）。
`BONSAI_MODEL`	`27B`	`27B`, `8B`, `4B`, `1.7B`, `all`	模型大小。`all` 表示所有四个大小（仅设置/下载时）。
`BONSAI_TOKEN`	—	HuggingFace 只读 token	仅在 27B 模型仓库处于私有状态时需要（发布时移除）。

all 仅对 setup.sh / setup.ps1 / download_models.sh 有效——运行/服务脚本需要具体的系列/大小。

可自由组合：

./setup.sh                                                  # Ternary-Bonsai-27B（默认）
BONSAI_MODEL=1.7B ./setup.sh                                # Ternary-Bonsai-1.7B
BONSAI_FAMILY=bonsai ./setup.sh                             # Bonsai-27B（1-bit）
BONSAI_FAMILY=bonsai BONSAI_MODEL=4B ./setup.sh             # Bonsai-4B
BONSAI_MODEL=all ./setup.sh                                 # 所有 4 种 Ternary-Bonsai 大小
BONSAI_FAMILY=all BONSAI_MODEL=all ./setup.sh               # 完整矩阵（8 个下载）

Binary 的上游状态

Q1_0 在上游 llama.cpp 中开箱即用，支持众多后端：CPU（通用、NEON 和优化 x86）、Metal、CUDA 和 Vulkan。

运行时	状态
llama.cpp (CPU, Metal, CUDA, Vulkan)	✅ 已合并到上游，开箱即用
MLX (1-bit)	⏳ 上游等待中：mlx#3161；合并之前，请使用 PrismML-Eng/mlx（分支 `prism`，由 `setup.sh` 自动构建）

Ternary 的上游状态

Ternary 支持正在迁移到主线 llama.cpp：后端逐个落地，因此目前是主线和我们分支的混合。实际影响是：我们目前提供三个 ternary GGUF 变体，每个都需要在正确的位置运行。

文件	格式	运行环境
`*-Q2_0.gguf`	分组大小 128。本演示使用的格式，兼容我们的分支。一旦 llama.cpp 迁移完成，这些文件将被弃用，并由 `PQ2_0` gguf 替代	本演示 / 分支二进制文件。无法在主线加载（类型 ID 相同但块大小不同）
`*-Q2_0_g64.gguf`	分组大小 64（2.25 bpw）。官方 llama.cpp 格式；这些文件将被重命名为纯 `Q2_0`，替换当前文件	主线 llama.cpp（目前仅 CPU 和 Metal）
`*-PQ2_0.gguf`	暂不支持。计划作为未来的分支格式：与当前分组大小 128 的 `Q2_0` 格式相同，但使用自己的 ggml 类型 ID，以便与上游 `Q2_0` 共存	暂无（分支支持计划中）

各后端迁移状态：

后端	状态	位置
CPU（ARM NEON + 通用标量）	✅ 已合并到主线 llama.cpp	ggml-org/llama.cpp#24448
Metal	✅ 已合并到主线 llama.cpp	ggml-org/llama.cpp#25419
Vulkan	🔄 上游进行中（独立 PR，非我们的）	ggml-org/llama.cpp#25430
CUDA	🔄 上游审查中	ggml-org/llama.cpp#25707
x86 (AVX-512-VNNI)	⏳ 等待中	待定

CPU 和 Metal 现在可以在主线 llama.cpp 上运行 Q2_0，无需分支（使用最新的 ggml-org/llama.cpp 构建，配合 *-Q2_0_g64.gguf 文件）。对于 CUDA 和其他后端，请使用本演示：它附带了分支预编译二进制文件，因此下载的分组大小 128 的 *-Q2_0.gguf 文件可以直接开箱即用。MLX 2-bit 在标准 MLX 中支持，无需分支。

要在标准 ggml-org/llama.cpp（CPU 或 Metal）上直接运行较小的 ternary 模型，请使用分组大小 64 的文件：

模型	仓库	文件（主线兼容）
1.7B	prism-ml/Ternary-Bonsai-1.7B-gguf	`Ternary-Bonsai-1.7B-Q2_0_g64.gguf`
4B	prism-ml/Ternary-Bonsai-4B-gguf	`Ternary-Bonsai-4B-Q2_0_g64.gguf`
8B	prism-ml/Ternary-Bonsai-8B-gguf	`Ternary-Bonsai-8B-Q2_0_g64.gguf`

hf download prism-ml/Ternary-Bonsai-1.7B-gguf Ternary-Bonsai-1.7B-Q2_0_g64.gguf --local-dir models
hf download prism-ml/Ternary-Bonsai-4B-gguf  Ternary-Bonsai-4B-Q2_0_g64.gguf  --local-dir models
hf download prism-ml/Ternary-Bonsai-8B-gguf  Ternary-Bonsai-8B-Q2_0_g64.gguf  --local-dir models

`setup.sh` 的功能

设置脚本会为您处理所有事情，即使是在新机器上：

检查/安装系统依赖： macOS 上的 Xcode CLT，Linux 上的 build-essential
安装 uv： 快速 Python 包管理器（用户本地，非全局）
创建 Python venv 并运行 uv sync——从 pyproject.toml 安装 cmake、ninja、huggingface-cli
从 HuggingFace 下载模型（27B 在仓库私有时需要 BONSAI_TOKEN）
从 GitHub Release 下载预编译二进制文件（或根据需要从源代码构建）
从源代码构建 MLX（仅 macOS）：克隆我们的分支，构建到 venv 中，安装 ML 栈（mlx-lm、torch、transformers）
将 Open WebUI 安装到 venv 中用于 agentic 演示（设置 BONSAI_OPENWEBUI=0 可跳过）
构建代码解释器 venv（.venv-jupyter）：Jupyter + matplotlib / pandas / numpy / scipy / sympy / yfinance，用于 Open WebUI 代码解释器（设置 BONSAI_CODE_INTERPRETER=0 可跳过）

重新运行 setup.sh 是安全的——它会跳过已完成的步骤。

运行模型

所有运行脚本都遵循 BONSAI_MODEL（默认 27B）。设置它以运行不同大小：

llama.cpp (Mac / Linux — 自动检测平台)

./scripts/run_llama.sh -p "What is the capital of France?"

# 运行不同模型大小
BONSAI_MODEL=4B ./scripts/run_llama.sh -p "Write a haiku about bonsai trees"

llama.cpp (Windows PowerShell)

.\scripts\run_llama.ps1 -p "What is the capital of France?"

# 运行不同模型大小
$env:BONSAI_MODEL = "4B"
.\scripts\run_llama.ps1 -p "Write a haiku about bonsai trees"

MLX — Mac (Apple Silicon)

source .venv/bin/activate
./scripts/run_mlx.sh -p "What is the capital of France?"

聊天服务器

启动 llama-server 及其内置聊天 UI：

./scripts/start_llama_server.sh    # http://localhost:8080

# 提供不同模型大小
BONSAI_MODEL=4B ./scripts/start_llama_server.sh

Windows PowerShell：

.\scripts\start_llama_server.ps1

思考

27B 是一个思考模型，默认开启思考。在聊天 UI 中为每个对话进行调整（无需重启）：点击消息框中的灯泡图标，选择 推理努力程度：关闭、低（512 tokens）、中（2,048）、高（8,192）或最大（无限制）。选择会按浏览器持续生效，并随每个请求发送。

在较慢的硬件上，思考通常是等待的主要部分；请在 UI 中选择较低的努力程度。对于未指定推理努力程度的 API 客户端，您可以通过在启动脚本中直接传递 llama-server 标志来设置整个服务器的默认上限：

./scripts/start_llama_server.sh --reasoning-budget 2048

工具调用和 MCP

27B 通过 API 进行原生 OpenAI 风格的工具调用，聊天 UI 包含一个 MCP 客户端，预配置了 Hugging Face + DeepWiki（在消息框的 MCP 选择器中按对话选择加入，未开启之前没有提示成本）。详情、成本和如何添加自己的服务器：TOOLS.md。

视觉

在聊天 UI 中上传图片（消息框中的 +）或通过 API 发送 image_url 部分；脚本会自动加载视觉投影器，并在较慢的后端上降低超大图像的尺寸。成本、图像 token 上限和 OCR 提示：VISION.md。

可选额外功能

llama.cpp 聊天服务器的两个实验性、默认关闭的功能：

推测解码： BONSAI_SPECULATIVE=1 将 27B 与其 dspark 草稿模型配对，在代码和推理上实现约 1.8-2 倍的解码加速（CUDA；Apple Silicon 支持将稍后改进）。权衡和验证：SPECULATIVE.md。
4-bit KV 缓存： BONSAI_KV4=1 在超长上下文中将 KV 缓存内存减少约 3.5 倍，并带有可选校准偏置以提高质量（./scripts/make_kv_bias.sh）。详情：KV-CACHE.md。

上下文大小

27B 模型支持最多 262,144 tokens 的上下文。FP16 KV 缓存每个 token 消耗 64 KiB（100K 时约 6.3 GiB），因此 100K 上下文即使在许多消费级设备上也能容纳，无需 KV 缓存量化。模型的混合注意力使其缓存相对于其尺寸保持较小。

使用可选的 4-bit KV 缓存（BONSAI_KV4=1），缓存降至每个 token 约 18 KiB，100K 时约 1.8 GiB，比下面的 100K 数据节省约 4.5 GiB（例如，Ternary-Bonsai-27B 在 llama.cpp 上从约 13.7 GiB 降至约 9.2 GiB）。

27B 峰值内存（权重 + 激活 + FP16 KV 缓存 + 约 1.2 GiB 开销；仅文本，添加约 0.9 GiB 用于视觉投影器）：

模型	格式	权重	4K 上下文	10K 上下文	100K 上下文
Bonsai-27B (1-bit)	llama.cpp `Q1_0`	3.53 GiB	4.8 GiB	5.2 GiB	10.8 GiB
Bonsai-27B (1-bit)	MLX 1-bit	3.92 GiB	5.5 GiB	5.9 GiB	11.4 GiB
Ternary-Bonsai-27B	llama.cpp `Q2_0`	6.66 GiB	7.8 GiB	8.1 GiB	13.7 GiB
Ternary-Bonsai-27B	MLX 2-bit	7.05 GiB	8.6 GiB	8.9 GiB	14.4 GiB
参考：27B 16-bit	GGUF BF16	47.73 GiB	49 GiB	49.6 GiB	55.2 GiB
参考：27B "4-bit"	llama.cpp `UD Q4_K_M`	15.73 GiB	17.2 GiB	17.6 GiB	23.2 GiB
参考：27B "4-bit"	MLX 4-bit	13.3 GiB	17.0 GiB	17.3 GiB	22 GiB

（MLX 打包文件比 GGUF 大约 400 MiB，因为 MLX 存储 scale 和 bias，GGUF 仅存储 scale。）

默认情况下，脚本传递 -c 0，这允许 llama.cpp 的 --fit 自动根据可用内存调整 KV 缓存大小（无预分配浪费）。如果您的构建不支持 -c 0，脚本将根据系统 RAM 回退到安全值。使用以下命令覆盖：./scripts/run_llama.sh -c 8192 -p "Your prompt"

较旧的纯文本模型大小整体更小；8B 支持最多 65,536 tokens 的上下文：

Bonsai-8B 估算值（权重 + KV 缓存 + 激活）：

上下文大小	估算内存使用
8,192 tokens	~2.5 GB
32,768 tokens	~5.9 GB
65,536 tokens	~10.5 GB

Open WebUI（可选）：完整的 agentic 演示

Open WebUI 为您提供了一个类似 ChatGPT 的界面，运行在本地 27B 之上：支持图片聊天、针对实时工具的工具调用、服务器端代码解释器（绘图 + 市场数据）以及一个包含隐藏故事的销售数据库供您探索。所有内容自动配置，无需手动点击设置：

./scripts/start_openwebui.sh

setup.sh 会为您安装它；该脚本启动后端，播种演示（工具、模型设置、演示数据库），然后打开 http://localhost:9090。后端、可尝试的内容和自定义：OPENWEBUI.md。

从源代码构建

如果您更愿意从源代码构建 llama.cpp 而不是使用预编译二进制文件：

Mac (Apple Silicon — Metal)

./scripts/build_mac.sh

克隆 PrismML-Eng/llama.cpp，使用 Metal 构建，输出到 bin/mac/。

Mac (Intel — 仅 CPU)

./scripts/build_mac.sh

脚本自动检测 Intel 与 Apple Silicon。在 Intel Mac 上，使用 -DGGML_METAL=OFF（仅 CPU）构建。MLX 也会自动跳过，因为它需要 Apple Silicon。

Linux (仅 CPU)

./scripts/build_cpu_linux.sh

构建仅 CPU 的二进制文件，无 GPU 依赖。适用于 x64 和 arm64。输出到 bin/cpu/。

Linux (CUDA)

./scripts/build_cuda_linux.sh

自动检测 CUDA 版本。传递 --cuda-path /usr/local/cuda-12.8 以使用特定工具包。

Linux (Vulkan)

# 先安装 Vulkan SDK（例如 sudo apt install libvulkan-dev glslc）
git clone -b prism https://github.com/PrismML-Eng/llama.cpp.git
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_VULKAN=ON
cmake --build build -j$(nproc)
# 二进制文件在 build/bin/

Linux (ROCm / AMD GPU)

# 需要 ROCm 工具包 (hipcc)
git clone -b prism https://github.com/PrismML-Eng/llama.cpp.git
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_HIP=ON
cmake --build build -j$(nproc)
# 二进制文件在 build/bin/

Windows (CUDA)

.\scripts\build_cuda_windows.ps1

自动检测 CUDA 工具包。传递 -CudaPath "C:\path\to\cuda" 以使用特定版本。需要 Visual Studio Build Tools（或完整 Visual Studio）和 CUDA 工具包。

Windows (仅 CPU)

git clone -b prism https://github.com/PrismML-Eng/llama.cpp.git
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
# 二进制文件在 build\bin\Release\

需要 Visual Studio Build Tools 或完整 Visual Studio（包含 C++ 工作负载）。

llama.cpp 预编译二进制文件下载

所有二进制文件均可在 GitHub Release 中找到：

平台
macOS Apple Silicon (arm64)
macOS Apple Silicon (KleidiAI)
macOS Intel (x64)
Linux x64 (CPU)
Linux arm64 (CPU)
Linux x64 (CUDA 12.4)
Linux x64 (CUDA 12.8)
Linux x64 (Vulkan)
Linux arm64 (Vulkan)
Linux x64 (ROCm 7.2)
Windows x64 (CPU)
Windows arm64 (CPU)
Windows x64 (CUDA 12.4)
Windows x64 (Vulkan)
Windows x64 (HIP/ROCm)
iOS (XCFramework)

文件夹结构

设置完成后，目录结构如下：

Bonsai-demo/
├── README.md
├── TOOLS.md                        # 工具调用和 MCP 指南
├── OPENWEBUI.md                    # Open WebUI agentic 演示指南
├── VISION.md                       # 图像输入：成本、上限、OCR 提示
├── SPECULATIVE.md                  # 推测解码（实验性）
├── KV-CACHE.md                     # 4-bit KV 缓存（实验性）
├── AGENTS.md                       # Agent 指南（硬件调优旋钮）
├── setup.sh                        # macOS/Linux 设置
├── setup.ps1                       # Windows 设置
├── pyproject.toml                  # Python 依赖
├── scripts/
│   ├── common.sh                   # 共享助手 + BONSAI_MODEL
│   ├── download_models.sh          # HuggingFace 下载
│   ├── download_binaries.sh        # GitHub Release 下载
│   ├── run_llama.sh                # llama.cpp（自动检测 Mac/Linux）
│   ├── run_llama.ps1               # llama.cpp（Windows PowerShell）
│   ├── run_mlx.sh                  # MLX 推理
│   ├── mlx_generate.py             # MLX Python 脚本
│   ├── start_llama_server.sh       # llama.cpp 服务器（端口 8080）
│   ├── start_llama_server.ps1      # llama.cpp 服务器（Windows PowerShell）
│   ├── start_mlx_server.sh         # MLX 服务器（端口 8081）
│   ├── start_openwebui.sh          # Open WebUI + 自动启动后端
│   ├── openwebui/                  # Open WebUI 演示工具 + 播种
│   ├── build_mac.sh                # 为 Mac 构建 llama.cpp
│   ├── build_cpu_linux.sh          # 为 Linux 构建 llama.cpp（仅 CPU）
│   ├── build_cuda_linux.sh         # 为 Linux CUDA 构建 llama.cpp
│   └── build_cuda_windows.ps1      # 为 Windows CUDA 构建 llama.cpp
├── models/                         # ← 由 setup 下载
│   ├

开源项目PrismML-Eng2026-07-16原文

打开互动版