Bonsai Demo 本地运行指南

项目概述

Bonsai Demo 是一个开源仓库，用于在本地运行 Bonsai（1-bit） 与 Ternary-Bonsai 系列语言模型，支持 macOS（Metal）、Linux/Windows（CUDA、Vulkan、ROCm）及纯 CPU 后端。最新发布的 Bonsai 27B 是该系列首个视觉-语言模型，支持图像输入、原生 OpenAI 风格的工具调用（Tool Calling）以及 MCP 协议服务器，并具备推理（Thinking）与 256K 长上下文能力。其中 1-bit 版本每权重仅约 1.125 bit，可直接装入现代 iPhone；Ternary 版本（每权重约 1.7 bit，打包为 2-bit 以适配加速内核）为默认选项。

模型家族与规格

仓库提供两大家族，每种均包含 27B、8B、4B、1.7B 四档规模，并分别提供 GGUF（llama.cpp）与 MLX 格式。环境变量 BONSAI_FAMILY 控制家族（ternary 为默认，bonsai 为 1-bit），BONSAI_MODEL 控制尺寸（默认 27B）。

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

快速开始

macOS / Linux

git clone https://github.com/PrismML-Eng/Bonsai-demo.git
cd Bonsai-demo
export BONSAI_MODEL=27B                  # 可选：27B（默认）/8B/4B/1.7B
export BONSAI_TOKEN="hf_your_token_here" # 27B 仓库私有期间必需
./setup.sh                               # 安装依赖、下载模型与二进制
./scripts/start_llama_server.sh          # 启动对话服务器：http://localhost:8080

Windows（PowerShell）

git clone https://github.com/PrismML-Eng/Bonsai-demo.git
cd Bonsai-demo
$env:BONSAI_MODEL = "27B"
$env:BONSAI_TOKEN = "hf_your_token_here"
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup.ps1

切换家族与尺寸示例：

# 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!"

关键环境变量

变量	默认	用途
BONSAI_MODEL	27B	选择模型尺寸：27B/8B/4B/1.7B
BONSAI_FAMILY	ternary	选择家族：ternary 或 bonsai（1-bit）
BONSAI_NGL	自动检测	GPU 层卸载数；0 表示纯 CPU
BONSAI_CTX	按 RAM 分级	上下文长度；最大 262144；0 表示自动
BONSAI_HOST	127.0.0.1	服务器绑定地址
BONSAI_SPECULATIVE	0	启用 dspark 草稿模型的推测解码
BONSAI_KV4	0	启用 4-bit KV 缓存以支持超长上下文

完整变量列表（24 项）见 environment_variables.md。

上游后端状态

1-bit（Q1_0） 已合并入主流 llama.cpp，覆盖 CPU、Metal、CUDA、Vulkan。1-bit MLX 仍依赖 PrismML 仓库的 prism 分支（PR mlx#3161 合并前）。

Ternary（Q2_0） 正在向 mainstream 迁移：

后端	状态
CPU（ARM NEON + 通用）	已合并入 llama.cpp
Metal	已合并
Vulkan	已合并
CUDA	已合并
x86 AVX-512-VNNI 优化	待合并

仓库当前提供三种 ternary GGUF 变体：*-Q2_0.gguf（group size 128，本 demo 使用）、*-Q2_0_g64.gguf（group size 64，主线 llama.cpp 兼容）、*-PQ2_0.gguf（实验性，未来迁移用）。在主线 llama.cpp 上运行 1.7B/4B/8B ternary 模型时，应下载 *_Q2_0_g64.gguf 文件。

setup.sh 执行流程

1. 检查并安装系统依赖（macOS 的 Xcode CLT、Linux 的 build-essential）。
2. 安装 uv（用户级 Python 包管理器）。
3. 创建虚拟环境并运行 uv sync，安装 cmake、ninja、huggingface-cli。
4. 从 HuggingFace 下载模型（27B 需 BONSAI_TOKEN）。
5. 下载预编译二进制（GitHub Release）。
6. macOS 下从源码编译 MLX 分支 prism，并安装 mlx-lm/torch/transformers。
7. 安装 Open WebUI（BONSAI_OPENWEBUI=0 跳过）。
8. 构建代码解释器虚拟环境 .venv-jupyter（BONSAI_CODE_INTERPRETER=0 跳过）。

重跑 setup.sh 是安全的，会跳过已完成步骤。

运行模型

./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"

# Apple Silicon 上的 MLX 后端
source .venv/bin/activate
./scripts/run_mlx.sh -p "What is the capital of France?"

启动带 UI 的对话服务器：

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

该脚本自动检测 GPU（Metal/CUDA/ROCm/Vulkan）并卸载全部层。若检测错误，可通过 BONSAI_NGL=0 强制 CPU 推理。

推理（Thinking）控制

27B 是推理模型，默认启用思考模式。可在 UI 的灯泡图标中选择 Off / Low(512) / Medium(2048) / High(8192) / Max 五个等级；该选择会持久化于浏览器。命令行可通过 --reasoning-budget 参数限制服务端默认预算：

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

可选实验特性

• 推测解码：BONSAI_SPECULATIVE=1，配合 dspark 草稿模型可在代码与推理任务上获得约 1.8–2 倍加速（CUDA 后端），仅限本仓库的 fork 二进制。
• 4-bit KV 缓存：BONSAI_KV4=1，长上下文下 KV 缓存内存降低约 3.5 倍。
• 视觉编码器驻留内存：BONSAI_MMPROJ_CPU=1，将 27B 的视觉投影器保留在系统内存，节省约 0.9 GiB 显存。

上下文长度